diff --git a/doc/admin-guide-cloud/source/orchestration-auth-model.rst b/doc/admin-guide-cloud/source/orchestration-auth-model.rst index fcaea26982..b24ee8bd51 100644 --- a/doc/admin-guide-cloud/source/orchestration-auth-model.rst +++ b/doc/admin-guide-cloud/source/orchestration-auth-model.rst @@ -8,10 +8,10 @@ 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 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 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: @@ -24,14 +24,14 @@ Password authorization The Orchestration service supports password authorization. Password authorization requires that a user pass a -username/password to the service. The Orchestration service -stores the encrypted password in the database and uses it -for deferred operations. +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/password. The Dashboard or + 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 @@ -41,7 +41,7 @@ Password authorization involves the following steps: #. The username/password are encrypted and stored in the Orchestration database. -#. The stack is created. +#. Orchestration creates a stack. #. Later, the Orchestration service retrieves the credentials and requests another token on behalf of the user. The token is not @@ -63,15 +63,15 @@ 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. The roles are configurable through - the ``heat.conf`` file, but it must contain 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. +* 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. -Then, the OpenStack Identity service provides a *trust id*, +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 diff --git a/doc/admin-guide-cloud/source/orchestration-introduction.rst b/doc/admin-guide-cloud/source/orchestration-introduction.rst index 539cd742ef..4aea46ecaf 100644 --- a/doc/admin-guide-cloud/source/orchestration-introduction.rst +++ b/doc/admin-guide-cloud/source/orchestration-introduction.rst @@ -4,13 +4,13 @@ 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. They can -also be complex, such as starting a group of servers that auto scale by -starting and stopping based on real-time CPU loading information from the +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 that describe tasks in terms of resources, parameters, inputs, +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. diff --git a/doc/admin-guide-cloud/source/orchestration-stack-domain-users.rst b/doc/admin-guide-cloud/source/orchestration-stack-domain-users.rst index c18211f099..d53ff352d9 100644 --- a/doc/admin-guide-cloud/source/orchestration-stack-domain-users.rst +++ b/doc/admin-guide-cloud/source/orchestration-stack-domain-users.rst @@ -8,11 +8,11 @@ Stack domain users allow the Orchestration service to authorize and start the following operations within booted virtual machines: -* Provide metadata to agents inside instances, which poll for changes +* 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 +* 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. @@ -25,22 +25,25 @@ 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 that is created through Identity. -Then, the key pair is used to sign requests to the Orchestration +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 that is -related to the Orchestration stacks only. A user is created which is -the *domain admin*, and Orchestration uses that user to manage the -lifecycle of the users in the stack *user domain*. +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*. Stack domain users configuration ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -To configure stack domain users, the following steps occur: +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 @@ -122,7 +125,7 @@ The following steps are run during stack creation: documentation `. #. When API requests are processed, the Orchestration service performs - an internal lookup and allows stack details for a given stack to be + 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