From d185092b21c3dfa1a59ee40ef2fe50519a4bee3e Mon Sep 17 00:00:00 2001 From: kairat_kushaev Date: Tue, 17 Mar 2015 19:18:05 +0300 Subject: [PATCH] Add orchestration section into admin guide Add articles about heat orchestration engine to the guide. The articles contain information about common goal of the heat and authorization model used in Heat. Change-Id: I8bf80a7b6b7425525cedf4cfad769f1ac8ee4cde Co-Authored-By: Steven Hardy --- .../bk-admin-guide-cloud.xml | 7 +- doc/admin-guide-cloud/ch_orchestration.xml | 44 +++++ .../section_orchestration-auth-model.xml | 153 ++++++++++++++++++ 3 files changed, 203 insertions(+), 1 deletion(-) create mode 100644 doc/admin-guide-cloud/ch_orchestration.xml create mode 100644 doc/admin-guide-cloud/orchestration/section_orchestration-auth-model.xml diff --git a/doc/admin-guide-cloud/bk-admin-guide-cloud.xml b/doc/admin-guide-cloud/bk-admin-guide-cloud.xml index 195e20fda7..26c1a2bc04 100644 --- a/doc/admin-guide-cloud/bk-admin-guide-cloud.xml +++ b/doc/admin-guide-cloud/bk-admin-guide-cloud.xml @@ -54,7 +54,11 @@ in the Telemetry chapter. The tables contain the release information for all collected meters regarding to when they - were introduced in the module. + were introduced in the module. In addition, + the Orchestration chapter has been added to + the guide. It describes in details + Orchestration module available in OpenStack + since Havana release. @@ -170,5 +174,6 @@ + diff --git a/doc/admin-guide-cloud/ch_orchestration.xml b/doc/admin-guide-cloud/ch_orchestration.xml new file mode 100644 index 0000000000..112139c889 --- /dev/null +++ b/doc/admin-guide-cloud/ch_orchestration.xml @@ -0,0 +1,44 @@ + + + Orchestration + Orchestration is an orchestration engine that provides 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 + endeavours to provide compatibility with the AWS CloudFormation template + format, so that many existing CloudFormation templates can be launched + on OpenStack. +
+ Introduction + Orchestration is a tool for orchestrating clouds that + automatically configures and deploys resources in stacks. + Such deployments can be simple — like deploying WordPress on Ubuntu + with an SQL back-end. And they can be quite complex, like launching + a group of servers that autoscale: starting and stopping based on + realtime CPU loading information from Telemetry module. + Orchestration stacks are defined with templates, which are + non-procedural documents describing tasks in terms of resources, + parameters, inputs, constraints and dependencies. When + Orchestration module was originally introduced, it worked with + AWS CloudFormation templates, which are in JSON format. + Now, Orchestration also executes HOT (Heat Orchestration + Template) templates, written in YAML: a terse notation that loosely + follows Python/Ruby-type structural conventions (colons, returns, + indentation) so it’s more easily to write, parse, grep, generate with + tools, and maintain with source-code management systems. + Orchestration can be accessed via the CLI, and using RESTful queries. + Orchestration module provides both an OpenStack-native ReST API + and a CloudFormation-compatible Query API. Orchestration is also + integrated with OpenStack dashboard in order to launching stacks from + templates through web-interface. + For more details how to use Orchestration module command-line see + + OpenStack Command line interface reference + +
+ + diff --git a/doc/admin-guide-cloud/orchestration/section_orchestration-auth-model.xml b/doc/admin-guide-cloud/orchestration/section_orchestration-auth-model.xml new file mode 100644 index 0000000000..85958a79af --- /dev/null +++ b/doc/admin-guide-cloud/orchestration/section_orchestration-auth-model.xml @@ -0,0 +1,153 @@ + +
+ Orchestration authorization model + Orchestration authorization model defines the process of + authorization that orchestration module uses to authorize requests during + so called deferred operations. The typical example of such operation is + autoscaling group update when heat requests another components + (nova, neutron or others) to extend (reduce) capacity of autoscaling + group. + At the current moment, Orchestration provides two kinds of + authorization models: + + + + Password authorization. + + + Authorization with OpenStack Identity trusts. + + + +
+ Password authorization + Password authorization is the initial authorization model that was + supported by Orchestration module. This kind of authorization requires + from a user to pass a password to Orchestration. Orchestration + stores the encrypted password in database and uses it for deferred + operations. + The following steps are executed for password authorization: + + + + User requests stack creation, providing a token and + username/password (python-heatclient or OpenStack dashboard + normally requests the token for you). + + + If the stack contains any resources marked as requiring + deferred operations orchestration engine will fail validation + checks if no username/password is provided. + + + The username/password are encrypted and stored in the + orchestration DB. + + + Stack creation is completed. + + + At some later stage Orchestration retrieves the + credentials and requests another token on behalf of the user, + the token is not limited in scope and provides access to all + roles of the stack owner. + + + +
+
+ Keystone trusts authorization + OpenStack Identity trusts is the new authorization method available + since IceHouse release. + Trusts are an OpenStack Identity extension, which provide a method to + enable delegation, and optionally impersonation via OpenStack + Identity. 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 Orchestration module) provides + OpenStack Identity 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(configurable via the + heat.conf, but it needs to contain whatever + roles are required to perform the deferred operations on the + users behalf, e.g launching a OpenStack Compute instance in + response to an AutoScaling event). + + + Whether to enable impersonation. + + + + OpenStack Identity then provides a trust_id, which can be consumed by + the trustee (and 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, along with effective impersonation of the trustor user, if + it was selected when creating the trust. More information is available + in Identity management section. + The following steps are executed for trusts authorization: + + + + User creates a stack via an API request (only the token is + required). + + + Orchestration uses the token to create a trust between + the stack owner (trustor) and the heat service user (trustee), + delegating a special role (or roles) as defined in the + trusts_delegated_roles list in the + heat configuration file. By default heat sets all roles from + trustor available for trustee. Deployers may modify this list to + reflect local RBAC policy, e.g to ensure the heat process can + only access those services expected while impersonating + a stack owner. + + + Orchestration stores the encrypted + trust id in the Orchestration DB. + + + When a deferred operation is required, Orchestration + retrieves the trust id, and requests a + trust scoped token which enables the service user to impersonate + the stack owner for the duration of the deferred operation, e.g + to launch some OpenStack Compute instances on behalf of + the stack owner in response to an AutoScaling event. + + + +
+
+ Authorization model configuration + Password authorization model had been the default authorization + model enabled for Orchestration module before Kilo release. Since Kilo + release trusts authorization model has been enabled by default. + To enable password authorization model the following change should + be made in heat.conf: + deferred_auth_method=password + To enable trusts authorization model the following change should be + made in heat.conf: + deferred_auth_method=trusts + To specify trustor roles that will be delegated to trustee during + authorization trusts_delegated_roles parameter + should be specified in heat.conf. If + trusts_delegated_roles is not defined then all + trustor roles will be delegated to trustee. Please pay attention that + trust delegated roles should be pre-configured in OpenStack Identity + before using it in Orchestration module. +
+
+