heat/doc/source/template_guide/multi-clouds.rst

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 <plugin-options.html> and authentication plugins <authentication-plugins.html#loading-plugins-by-name> 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 <plugin-options.html#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 <plugin-options.html#available-plugins> or get to all class path from plugin names <authentication-plugins.html#loading-plugins-by-name> 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 <plugin-options.html#using-plugins-via-config-file>, via CLI <plugin-options.html#using-plugins-via-cli>, or via keystoneauth sessions <using-sessions.html>.

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 the standard Barbican CLI <cli/cli_usage.html#secret-create> 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.

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 an OS::Heat::Stack resource in your template.

In resource properties, provide credential_secret_id (Barbican secret ID from the secret we just built for credential) under context property.

Here is an template example for you:

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:

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.