openstack/heat
Code Issues Proposed changes

Merge "Add doc for multi-clouds support"

Browse Source
This commit is contained in:
Zuul 2019-06-28 15:16:02 +00:00 committed by Gerrit Code Review
commit 8aea1ca7b2
5 changed files with 207 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/source/template_guide/feature_guide.rst Normal file
View File

@ -0,0 +1,15 @@
.. highlight: yaml
:linenothreshold: 5
.. _feature_guide:
======================
Guideline for features
======================
Here are guideline for features:
.. toctree::
:maxdepth: 2
multi-clouds

1
doc/source/template_guide/index.rst
View File

@ -21,6 +21,7 @@ Template Guide
hot_guide
hello_world
feature_guide
hot_spec
basic_resources
software_deployment

186
doc/source/template_guide/multi-clouds.rst Normal file
View File

@ -0,0 +1,186 @@
.. highlight: yaml
:linenothreshold: 5
.. _multi-clouds:
====================
Multi-Clouds support
====================
Start from Stein release (version 12.0.0), Heat support multi-clouds
orchestration. This document means to provide guideline for how to use
multi-clouds features, and what's the environment requirement.
.. note:: If you like to create a stack in multi-region environment,
you don't need this feature at all. all you need to do is provide
`region_name` under `context` property for `OS::Heat::Stack`_.
If you like to see information on how to provide SSL support for
your multi-region environment, you can jump to `Use CA
cert(Optional)`_ .
Requirements
~~~~~~~~~~~~
* **Barbican service** - For better security concerns, multi-cloud
orchestration feature depends on Barbican service. So you have to make sure
Barbican service is ready in your environment before you use this feature.
* **Access to remote Orchestration service** - Before you run your multi-cloud
template. Make sure you're able to access to remote Orchestration service
with correct endpoint information, legal access right, and ability to access
to the remote site KeyStone, and Orchestration service API endpoint from
local site. You need to make sure local Orchestration service is able to
trigger and complete necessary API calls from local site to remote site. So we
can complete stack actions without facing any access error.
* **Template complete resources/functions compatibility** - In your
Orchestration template, you might want to use all kind of template functions
or resource types as your template version and your Orchestration service
allows. But please aware that once you plan to use Orchestration services
across multiple OpenStack clouds, you have to also consider the
compatibility. Make sure the template version and resource types are ready to
use before you ask remote site to run it. If you accidentally provide wrong
template version (which not provided in remote site), you will get error
message from remote site which prevent you from actually create remote
resources. But it's even better if we can just find such an error earlier.
Prepare
~~~~~~~
First of all, you need to put your remote cloud credential in a Barbican
secret. To build your own multi-clouds stack, you need to build a Barbican
secret first with most information for remote endpoint information.
Gathering credential information
--------------------------------
Before we start generating secret, let's talk about what credential format we
need. credential is a JSON format string contains two keys ``auth_type``, and
``auth``. ``auth_type``, and ``auth`` following auth plugin loader rules from
Keystone. You can find `plugin options`_ and `authentication plugins`_ in
keystoneauth documents.
* **auth_type** - ``auth_type`` is a string for plugin name. Allows value like
`v3applicationcredential`, `password`, `v3oidcclientcredentials`, etc. You
need to provide `available plugins`_.
* **auth** - auth is a dictionary contains all parameters for plugins to
perform authentication. You can find all valid parameter references from
`available plugins`_ or get to all class path from `plugin names`_ for more
detail allowed value or trace plugin class from there.
As you can tell, all allowed authentication plugins for credentials follows
plugins keystoneauth rules. So once new change in keystoneauth, it will also
directly reflect credentials too.
Actually we just call keystoneauth to get plugin loader for remote
authentication plugins. So keep an eye on keystoneauth if you're using this
feature.
Validate your credential
------------------------
Now you have all your credential information ready, try to validate first if
you can. You can either directly test them `via config`_, `via CLI`_, or
`via keystoneauth sessions`_.
build credential secret
-----------------------
Once you're sure it's valid, we can start building the secret out.
To build a secret you just have to follow standard Barbican CLI_ or API to
store your secret.
The local site will read this secret to perform stack actions in remote site.
Let's give a quick example here:
Said you have two OpenStack cloud site A and site B.
If you need to control site B from site A, make sure you have a secret with
site B's access information in site A. If you also like to control site A from
site B, make sure you have a secret with site A's access information in site B.
.. code-block:: sh
openstack secret store -n appcred --payload '{"auth_type": "v3applicationcredential", "auth": {"auth_url": "{Keystone_URL}", "application_credential_id": "{ID}", "application_credential_secret": "{SECRET}"}}'
.. note:: One common error for JSON format is to use single quote(`'`)
instead of double quote (`"`) inner your JSON schema.
Create remote stacks
--------------------
Now, you have a secret id generated for your Barbican secret. Use that id as
input for template.
To create a remote stack, you can simply use `OS::Heat::Stack`_ resource, as
child stack in your template (we also referring this structure as
`nested stack`).
In resource properties, provide `credential_secret_id` (Barbican secret ID
from the secret we just builded for credential) under `context` property.
Here is an template example for you:
.. code-block:: yaml
heat_template_version: rocky
resources:
stack_in_remote_cloud:
type: OS::Heat::Stack
properties:
context:
credential_secret_id: {$Your_Secret_ID}
template: { get_file: "remote-app.yaml" }
And that's all you need to do. The rest looks the same as usual.
Local Heat will read that secret, parse the credential information out,
replace current authentication plugin in context, and make remote calls.
Heat will not store your credential information anywhere. so your secret
security will remains within Barbican. That means if you wish to change your
credential or make sure other people can't access to it. All you need to do is
to update your Barbican secret or strong the security for it.
But aware of this. If you plan to switch the credential content, make sure that
won't affect resources/stacks in remote site. So do such actions with super
care.
Use CA cert(Optional)
---------------------
For production clouds, it's very important to have SSL support. Here we
provide CA cert method for your SSL access. If you wish to use that, use
`ca_cert` under `context` property. Which `ca_cert` is the contents of a CA
Certificate file that can be used to verify a remote cloud or region's server
certificate.
Or you can use `insecure` (a boolean option) under `context` property if you
like to use insecure mode (For security concerns, don't do it!) and you don't
want to use CA cert.
Here is an example for you:
.. code-block:: yaml
heat_template_version: rocky
resources:
stack_in_remote_cloud:
type: OS::Heat::Stack
properties:
context:
credential_secret_id: {$Your_Secret_ID}
ca_cert: {$Contents of a CA cert}
template: { get_file: "remote-app.yaml" }
.. note:: If insecure flag is on, ca_cert will be ignored.
.. _`plugin options`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html
.. _`authentication plugins`: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html#loading-plugins-by-name
.. _`plugin names`: https://docs.openstack.org/keystoneauth/latest/authentication-plugins.html#loading-plugins-by-name
.. _`available plugins`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#available-plugins
.. _`via keystoneauth sessions`: https://docs.openstack.org/keystoneauth/latest/using-sessions.html
.. _`via config`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#using-plugins-via-config-file
.. _`via CLI`: https://docs.openstack.org/keystoneauth/latest/plugin-options.html#using-plugins-via-cli
.. _CLI: https://docs.openstack.org/python-barbicanclient/latest/cli/cli_usage.html#secret-create
.. _`OS::Heat::Stack`: https://docs.openstack.org/heat/rocky/template_guide/openstack.html#OS::Heat::Stack

2
heat_integrationtests/prepare_test_env.sh
View File

@ -83,7 +83,7 @@ function _config_tempest_plugin
# support test multi-cloud
app_cred_id=$((openstack application credential show heat_multicloud || openstack application credential create heat_multicloud \
--secret secret --unrestricted) | grep ' id '|awk '{print $4}')
export OS_CREDENTIAL_SECRET_ID=$(openstack secret store -n heat-multi-cloud-test-cred --payload '{"auth_type": "v3applicationcredential", "auth": {"auth_url": $OS_AUTH_URL, "application_credential_id": $app_cred_id, "application_credential_secret": "secret"}, "roles": ["admin"], "project_id": $app_cred_project_id}')
export OS_CREDENTIAL_SECRET_ID=$(openstack secret store -n heat-multi-cloud-test-cred --payload '{"auth_type": "v3applicationcredential", "auth": {"auth_url": $OS_AUTH_URL, "application_credential_id": $app_cred_id, "application_credential_secret": "secret"}}')
iniset $conf_file heat_features_enabled multi_cloud True
iniset $conf_file heat_plugin heat_plugin credential_secret_id $OS_CREDENTIAL_SECRET_ID

4
releasenotes/notes/add_doc_for_multi_cloud_support-9f6e74ccc2639b4e.yaml Normal file
View File

@ -0,0 +1,4 @@
---
other:
- |
New document is out for ``multi-clouds support``, check out https://docs.openstack.org/heat/latest/template_guide/multi-clouds.html for more information.