From fdb5e892bf1004dcee28537fe429ea90b9152807 Mon Sep 17 00:00:00 2001 From: ricolin Date: Tue, 2 Apr 2019 12:42:27 +0800 Subject: [PATCH] Add doc for multi-clouds support Add doc for multi-clouds support in template guide. Also remove redundant credential information in multi-clouds integration test. Change-Id: I76c6427b7bbdac2af3b7f01aff1b0541e56b3653 Story: #2002126 Task: #19808 --- doc/source/template_guide/feature_guide.rst | 15 ++ doc/source/template_guide/index.rst | 1 + doc/source/template_guide/multi-clouds.rst | 186 ++++++++++++++++++ heat_integrationtests/prepare_test_env.sh | 2 +- ..._multi_cloud_support-9f6e74ccc2639b4e.yaml | 4 + 5 files changed, 207 insertions(+), 1 deletion(-) create mode 100644 doc/source/template_guide/feature_guide.rst create mode 100644 doc/source/template_guide/multi-clouds.rst create mode 100644 releasenotes/notes/add_doc_for_multi_cloud_support-9f6e74ccc2639b4e.yaml diff --git a/doc/source/template_guide/feature_guide.rst b/doc/source/template_guide/feature_guide.rst new file mode 100644 index 0000000000..512bd00226 --- /dev/null +++ b/doc/source/template_guide/feature_guide.rst @@ -0,0 +1,15 @@ +.. highlight: yaml + :linenothreshold: 5 + +.. _feature_guide: + +====================== +Guideline for features +====================== + +Here are guideline for features: + +.. toctree:: + :maxdepth: 2 + + multi-clouds diff --git a/doc/source/template_guide/index.rst b/doc/source/template_guide/index.rst index 76996f03a7..93cfcc2642 100644 --- a/doc/source/template_guide/index.rst +++ b/doc/source/template_guide/index.rst @@ -21,6 +21,7 @@ Template Guide hot_guide hello_world + feature_guide hot_spec basic_resources software_deployment diff --git a/doc/source/template_guide/multi-clouds.rst b/doc/source/template_guide/multi-clouds.rst new file mode 100644 index 0000000000..6509d1a084 --- /dev/null +++ b/doc/source/template_guide/multi-clouds.rst @@ -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 diff --git a/heat_integrationtests/prepare_test_env.sh b/heat_integrationtests/prepare_test_env.sh index 625f37a139..65c40851bf 100755 --- a/heat_integrationtests/prepare_test_env.sh +++ b/heat_integrationtests/prepare_test_env.sh @@ -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 diff --git a/releasenotes/notes/add_doc_for_multi_cloud_support-9f6e74ccc2639b4e.yaml b/releasenotes/notes/add_doc_for_multi_cloud_support-9f6e74ccc2639b4e.yaml new file mode 100644 index 0000000000..a155747d3b --- /dev/null +++ b/releasenotes/notes/add_doc_for_multi_cloud_support-9f6e74ccc2639b4e.yaml @@ -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.