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.
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.
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
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:
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.
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.
The username/password are encrypted and stored in the Orchestration database.
Orchestration creates a stack.
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.
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 .
Trusts authorization involves the following steps:
A user creates a stack through an API request (only the token is required).
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.
Orchestration stores the encrypted trust id in the Orchestration database.
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.
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:
deferred_auth_method=password
To enable the trusts authorization model, change the following
parameter in the heat.conf
file:
deferred_auth_method=trusts
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.
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.
To configure stack domain user, the Orchestration service completes the following tasks:
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.
A user with sufficient permissions to create and delete projects
and users in the heat
domain is created.
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:
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.
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.
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
The following steps are run during stack creation:
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.
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 .
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}/\ {stack_id}/resources/{resource_name}/metadata
or:
GET v1/{stack_domain_project_id}/stacks/{stack_name}/\ {stack_id}/resources/{resource_name}/metadata
The stack owner uses the former (via openstack stack resource metadata
STACK RESOURCE
), and any agents in the instance
use the latter.