Move in-tree admin guide from openstack-manuals
Change-Id: I3abb96744039200327c33c7565d7571d74541d6b Closes-Bug: #1706174
This commit is contained in:
rabi
parent
4e4bc0171c
commit
27d297346e
|
|
@ -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.
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
=================
|
||||
Adminstering Heat
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
introduction.rst
|
||||
auth-model.rst
|
||||
stack-domain.rst
|
||||
|
|
@ -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>`_.
|
||||
|
|
@ -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.
|
||||
|
|
@ -60,6 +60,14 @@ Configuring Heat
|
|||
|
||||
configuration/index
|
||||
|
||||
Administering Heat
|
||||
==================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
admin/index
|
||||
|
||||
Using Heat
|
||||
==========
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue