Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to SUSE OpenStack Cloud 8

13 Orchestration

Orchestration is an orchestration engine that provides the possibility to launch multiple composite cloud applications based on templates in the form of text files that can be treated like code. A native Heat Orchestration Template (HOT) format is evolving, but it also endeavors to provide compatibility with the AWS CloudFormation template format, so that many existing CloudFormation templates can be launched on OpenStack.

13.1 Introduction

The OpenStack Orchestration service, a tool for orchestrating clouds, automatically configures and deploys resources in stacks. The deployments can be simple, such as deploying WordPress on Ubuntu with an SQL back end, or complex, such as starting a server group that auto scales by starting and stopping using real-time CPU loading information from the Telemetry service.

Orchestration stacks are defined with templates, which are non-procedural documents. Templates describe tasks in terms of resources, parameters, inputs, constraints, and dependencies. When the Orchestration service was originally introduced, it worked with AWS CloudFormation templates, which are in the JSON format.

The Orchestration service also runs Heat Orchestration Template (HOT) templates that are written in YAML. YAML is a terse notation that loosely follows structural conventions (colons, returns, indentation) that are similar to Python or Ruby. Therefore, it is easier to write, parse, grep, generate with tools, and maintain source-code management systems.

Orchestration can be accessed through a CLI and RESTful queries. The Orchestration service provides both an OpenStack-native REST API and a CloudFormation-compatible Query API. The Orchestration service is also integrated with the OpenStack dashboard to perform stack functions through a web interface.

For more information about using the Orchestration service through the command line, see the OpenStack Command-Line Interface Reference.

13.2 Orchestration authorization model

The Orchestration authorization model defines the authorization process for requests during deferred operations. A common example is an auto-scaling group update. During the auto-scaling update operation, the Orchestration service requests resources of other components (such as servers from Compute or networks from Networking) to extend or reduce the capacity of an auto-scaling group.

The Orchestration service provides the following authorization models:

  • Password authorization

  • OpenStack Identity trusts authorization

13.2.1 Password authorization

The Orchestration service supports password authorization. Password authorization requires that a user pass a username and password to the Orchestration service. Encrypted password are stored in the database, and used for deferred operations.

Password authorization involves the following steps:

  1. A user requests stack creation, by providing a token and username and password. The Dashboard or python-heatclient requests the token on the user's behalf.

  2. If the stack contains any resources that require deferred operations, then the orchestration engine fails its validation checks if the user did not provide a valid username/password.

  3. The username/password are encrypted and stored in the Orchestration database.

  4. Orchestration creates a stack.

  5. Later, the Orchestration service retrieves the credentials and requests another token on behalf of the user. The token is not limited in scope and provides access to all the roles of the stack owner.

13.2.2 OpenStack Identity trusts authorization

A trust is an OpenStack Identity extension that enables delegation, and optionally impersonation through the OpenStack Identity service. The key terminology is trustor (the user delegating) and trustee (the user being delegated to).

To create a trust, the trustor (in this case, the user creating the stack in the Orchestration service) provides the OpenStack Identity service with the following information:

  • The ID of the trustee (who you want to delegate to, in this case, the Orchestration service user).

  • The roles to be delegated. Configure roles through the heat.conf file. Ensure the configuration contains whatever roles are required to perform the deferred operations on the user's behalf. For example, launching an OpenStack Compute instance in response to an auto-scaling event.

  • Whether to enable impersonation.

The OpenStack Identity service provides a trust id, which is consumed by only the trustee to obtain a trust scoped token. This token is limited in scope, such that the trustee has limited access to those roles delegated. In addition, the trustee has effective impersonation of the trustor user if it was selected when creating the trust. For more information, see Chapter 3, Identity management.

Trusts authorization involves the following steps:

  1. A user creates a stack through an API request (only the token is required).

  2. The Orchestration service uses the token to create a trust between the stack owner (trustor) and the Orchestration service user (trustee). The service delegates a special role (or roles) as defined in the trusts_delegated_roles list in the Orchestration configuration file. By default, the Orchestration service sets all the roles from trustor available for trustee. Deployers might modify this list to reflect a local RBAC policy. For example, to ensure that the heat process can access only those services that are expected while impersonating a stack owner.

  3. Orchestration stores the encrypted trust id in the Orchestration database.

  4. When a deferred operation is required, the Orchestration service retrieves the trust id and requests a trust scoped token which enables the service user to impersonate the stack owner during the deferred operation. Impersonation is helpful, for example, so the service user can launch Compute instances on behalf of the stack owner in response to an auto-scaling event.

13.2.3 Authorization model configuration

Initially, the password authorization model was the default authorization model. Since the Kilo release, the Identity trusts authorization model is enabled for the Orchestration service by default.

To enable the password authorization model, change the following parameter in the heat.conf file:


To enable the trusts authorization model, change the following parameter in the heat.conf file:


To specify the trustor roles that it delegates to trustee during authorization, specify the trusts_delegated_roles parameter in the heat.conf file. If trusts_delegated_roles is not defined, then all the trustor roles are delegated to trustee.


The trustor delegated roles must be pre-configured in the OpenStack Identity service before using them in the Orchestration service.

13.3 Stack domain users

Stack domain users allow the Orchestration service to authorize and start the following operations within booted virtual machines:

  • Provide metadata to agents inside instances. Agents poll for changes and apply the configuration that is expressed in the metadata to the instance.

  • Detect when an action is complete. Typically, software configuration on a virtual machine after it is booted. Compute moves the VM state to "Active" as soon as it creates it, not when the Orchestration service has fully configured it.

  • Provide application level status or meters from inside the instance. For example, allow auto-scaling actions to be performed in response to some measure of performance or quality of service.

The Orchestration service provides APIs that enable all of these operations, but all of those APIs require authentication. For example, credentials to access the instance that the agent is running upon. The heat-cfntools agents use signed requests, which require an ec2 key pair created through Identity. The key pair is then used to sign requests to the Orchestration CloudFormation and CloudWatch compatible APIs, which are authenticated through signature validation. Signature validation uses the Identity ec2tokens extension.

Stack domain users encapsulate all stack-defined users (users who are created as a result of data that is contained in an Orchestration template) in a separate domain. The separate domain is created specifically to contain data related to the Orchestration stacks only. A user is created, which is the domain admin, and Orchestration uses the domain admin to manage the lifecycle of the users in the stack user domain.

13.3.1 Stack domain users configuration

To configure stack domain user, the Orchestration service completes the following tasks:

  1. A special OpenStack Identity service domain is created. For example, a domain that is called heat and the ID is set with the stack_user_domain option in the heat.conf file.

  2. A user with sufficient permissions to create and delete projects and users in the heat domain is created.

  3. The username and password for the domain admin user is set in the heat.conf file (stack_domain_admin and stack_domain_admin_password). This user administers stack domain users on behalf of stack owners, so they no longer need to be administrators themselves. The risk of this escalation path is limited because the heat_domain_admin is only given administrative permission for the heat domain.

To set up stack domain users, complete the following steps:

  1. Create the domain:

    $OS_TOKEN refers to a token. For example, the service admin token or some other valid token for a user with sufficient roles to create users and domains. $KS_ENDPOINT_V3 refers to the v3 OpenStack Identity endpoint (for example, http://keystone_address:5000/v3 where keystone_address is the IP address or resolvable name for the Identity service).

    $ openstack --os-token $OS_TOKEN --os-url=$KS_ENDPOINT_V3 --os-\
      identity-api-version=3 domain create heat --description "Owns \
      users and projects created by heat"

    The domain ID is returned by this command, and is referred to as $HEAT_DOMAIN_ID below.

  2. Create the user:

    $ openstack --os-token $OS_TOKEN --os-url=$KS_ENDPOINT_V3 --os-\
      identity-api-version=3 user create --password $PASSWORD --domain \
      $HEAT_DOMAIN_ID heat_domain_admin --description "Manages users \
      and projects created by heat"

    The user ID is returned by this command and is referred to as $DOMAIN_ADMIN_ID below.

  3. Make the user a domain admin:

    $ openstack --os-token $OS_TOKEN --os-url=$KS_ENDPOINT_V3 --os-\
      identity-api-version=3 role add --user $DOMAIN_ADMIN_ID --domain \
      $HEAT_DOMAIN_ID admin

    Then you must add the domain ID, username and password from these steps to the heat.conf file:

    stack_domain_admin_password = password
    stack_domain_admin = heat_domain_admin
    stack_user_domain = domain id returned from domain create above

13.3.2 Usage workflow

The following steps are run during stack creation:

  1. Orchestration creates a new stack domain project in the heat domain if the stack contains any resources that require creation of a stack domain user.

  2. For any resources that require a user, the Orchestration service creates the user in the stack domain project. The stack domain project is associated with the Orchestration stack in the Orchestration database, but is separate and unrelated (from an authentication perspective) to the stack owners project. The users who are created in the stack domain are still assigned the heat_stack_user role, so the API surface they can access is limited through the policy.json file. For more information, see Chapter 3, Identity management.

  3. When API requests are processed, the Orchestration service performs an internal lookup, and allows stack details for a given stack to be retrieved. Details are retrieved from the database for both the stack owner's project (the default API path to the stack) and the stack domain project, subject to the policy.json restrictions.

This means there are now two paths that can result in the same data being retrieved through the Orchestration API. The following example is for resource-metadata:

GET v1/​{stack_owner_project_id}​/stacks/​{stack_name}​/\


GET v1/​{stack_domain_project_id}​/stacks/​{stack_name}​/​\

The stack owner uses the former (via openstack stack resource metadata STACK RESOURCE), and any agents in the instance use the latter.

Print this page