openstack/heat
Code Issues Proposed changes

Move in-tree admin guide from openstack-manuals

Browse Source 
Change-Id: I3abb96744039200327c33c7565d7571d74541d6b
Closes-Bug: #1706174
This commit is contained in:
rabi 2017-07-25 11:33:18 +05:30
parent 4e4bc0171c
commit 27d297346e
5 changed files with 350 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

148
doc/source/admin/auth-model.rst Normal file
View File

@ -0,0 +1,148 @@
.. _orchestration-auth-model:
=================================
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
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:
#. 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.
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 :doc:`Identity management <identity-management>`.
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.
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:
.. code-block:: ini
deferred_auth_method=password
To enable the trusts authorization model, change the following
two parameters in the ``heat.conf`` file.
Specify the authentication method for the deferred Orchestration actions.
This parameter triggers creating *trust ID* and stores it
in the Orchestration database:
.. code-block:: ini
deferred_auth_method=trusts
Allow reauthentication with the trust scoped token issued
by using the stored *trust ID* for long running tasks:
.. code-block:: ini
reauthentication_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.
.. note::
The trustor delegated roles must be pre-configured in the
OpenStack Identity service before using them in the Orchestration service.

10
doc/source/admin/index.rst Normal file
View File

@ -0,0 +1,10 @@
=================
Adminstering Heat
=================
.. toctree::
:maxdepth: 2
introduction.rst
auth-model.rst
stack-domain.rst

32
doc/source/admin/introduction.rst Normal file
View File

@ -0,0 +1,32 @@
============
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
<https://docs.openstack.org/cli-reference/heat.html>`_.

152
doc/source/admin/stack-domain-users.rst Normal file
View File

@ -0,0 +1,152 @@
.. _orchestration-stack-domain-users:
==================
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*.
Stack domain users configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
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 :file:`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
:file:`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).
.. code-block:: console
$ 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:
.. code-block:: console
$ 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:
.. code-block:: console
$ 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 :file:`heat.conf` file:
.. code-block:: ini
stack_domain_admin_password = password
stack_domain_admin = heat_domain_admin
stack_user_domain = domain id returned from domain create above
Usage workflow
~~~~~~~~~~~~~~
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 :file:`policy.json` file.
For more information, see :doc:`OpenStack Identity
documentation <identity-management>`.
#. 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
:file:`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.

8
doc/source/index.rst
View File

@ -60,6 +60,14 @@ Configuring Heat
configuration/index
Administering Heat
==================
.. toctree::
:maxdepth: 1
admin/index
Using Heat
==========