Sync environment and composition docs from openstack-manuals
Change-Id: Ib9ca5ffa4df5fd9ed6245d359fe1a8a54a477433 Closes-bug: #1366845
This commit is contained in:
Angus Salkeld
parent
b4013fd7f6
commit
bebeb5df44
123
doc/source/template_guide/composition.rst
Normal file
123
doc/source/template_guide/composition.rst
Normal file
@ -0,0 +1,123 @@
|
||||
..
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
.. _composition:
|
||||
|
||||
====================
|
||||
Template composition
|
||||
====================
|
||||
|
||||
When writing complex templates you are encouraged to break up your
|
||||
template into separate smaller templates. These can then be brought
|
||||
together using template resources. This is a mechanism to define a resource
|
||||
using a template, thus composing one logical stack with multiple templates.
|
||||
|
||||
|
||||
How to use template resources for composition
|
||||
---------------------------------------------
|
||||
|
||||
Template resources do a very similar job to
|
||||
AWS::CloudFormation::Stack, but they are more powerful as they allow a
|
||||
template to "stand in for" any resource type.
|
||||
|
||||
Template resources can be used to do the following:
|
||||
|
||||
* Define new resource types (make you own resource library).
|
||||
* Override the default behaviour of existing resource types.
|
||||
|
||||
The way this is achieved is:
|
||||
|
||||
* The heat client gets the associated template files and passes them
|
||||
along in the "files" section of the "POST stacks/".
|
||||
* The environment in Orchestration engine manages the mapping of resource type
|
||||
to template creation.
|
||||
* Translation of the template parameters into resource properties.
|
||||
|
||||
Let's go through some examples. In all examples assume the
|
||||
same resource template. This is a simple wrapper around a nova server
|
||||
(my_nova.yaml).
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
heat_template_version: 2013-05-23
|
||||
parameters:
|
||||
key_name:
|
||||
type: string
|
||||
description: Name of a KeyPair
|
||||
resources:
|
||||
server:
|
||||
type: OS::Nova::Server
|
||||
properties:
|
||||
key_name: {get_param: key_name}
|
||||
flavor: my.best
|
||||
image: the_one_i_always_use
|
||||
|
||||
|
||||
Example 1
|
||||
~~~~~~~~~
|
||||
|
||||
In this example you will not map a resource type name at all, but
|
||||
directly specify the template URL as the resource type.
|
||||
|
||||
Your main template (main.yaml) would look like this.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
heat_template_version: 2013-05-23
|
||||
resources:
|
||||
my_server:
|
||||
type: my_nova.yaml
|
||||
properties:
|
||||
key_name: my_key
|
||||
|
||||
Some notes about URLs:
|
||||
|
||||
The above reference to my_nova.yaml assumes it is in the same directory.
|
||||
You could use any of the following forms:
|
||||
|
||||
* Relative path (type: my_nova.yaml)
|
||||
* Absolute path (type: file:///home/user/templates/my_nova.yaml)
|
||||
* Http URL (type: http://example.com/templates/my_nova.yaml)
|
||||
* Https URL (type: https://example.com/templates/my_nova.yaml)
|
||||
|
||||
|
||||
To create the stack, run::
|
||||
|
||||
$ heat stack-create -f main.yaml example-one
|
||||
|
||||
Example 2
|
||||
~~~~~~~~~
|
||||
|
||||
In this example you will use the environment (env.yaml) to override the
|
||||
OS::Nova::Server with my_nova to get the defaults you want.
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
resource_registry:
|
||||
"OS::Nova::Server": my_nova.yaml
|
||||
|
||||
A more detailed discussion on this can be found here :ref:`environments`
|
||||
|
||||
Now you can use "OS::Nova::Server" in our top level template (main.yaml).
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
resources:
|
||||
my_server:
|
||||
type: OS::Nova::Server
|
||||
properties:
|
||||
key_name: my_key
|
||||
|
||||
To create the stack, run::
|
||||
|
||||
$ heat stack-create -f main.yaml -e env.yaml example-two
|
||||
@ -18,11 +18,12 @@ Environments
|
||||
============
|
||||
|
||||
The environment is used to affect the runtime behaviour of the
|
||||
template. It provides a way to override the default resource
|
||||
implementation and the parameters passed to Heat.
|
||||
template. It provides a way to override the resource
|
||||
implementations and provide a mechanism to place parameters
|
||||
that the service needs.
|
||||
|
||||
To fully understand the runtime behavior you also have to consider
|
||||
what plug-ins the cloud provider has installed.
|
||||
what plug-ins the cloud operator has installed.
|
||||
|
||||
------
|
||||
Format
|
||||
@ -44,21 +45,21 @@ Global and effective environments
|
||||
|
||||
The environment used for a stack is the combination of (1) the
|
||||
environment given by the user with the template for the stack and (2)
|
||||
a global environment that is determined by the cloud provider.
|
||||
Combination is asymmetric: an entry in the first environment takes
|
||||
precedence over an entry in the second. The OpenStack software
|
||||
a global environment that is determined by the cloud operator.
|
||||
Combination is asymmetric: an entry in the user environment takes
|
||||
precedence over the global environment. The OpenStack software
|
||||
includes a default global environment, which supplies some resource
|
||||
types that are included in the standard documentation. The cloud
|
||||
provider can add additional environment entries.
|
||||
operator can add additional environment entries.
|
||||
|
||||
The cloud provider can add to the global environment
|
||||
The cloud operator can add to the global environment
|
||||
by putting environment files in a configurable directory wherever
|
||||
the heat engine runs. The configuration variable is named
|
||||
"environment_dir" and is found in the "heat.common.config" module (AKA
|
||||
the "[DEFAULT]" section) of "/etc/heat/heat.conf". The default for
|
||||
that directory is "/etc/heat/environment.d". Its contents are
|
||||
combined in whatever order the shell delivers them when the heat
|
||||
engine starts up, which is the time when these files are read.
|
||||
"environment_dir" is found in the "[DEFAULT]" section
|
||||
of "/etc/heat/heat.conf". The default for that directory is
|
||||
"/etc/heat/environment.d". Its contents are combined in whatever
|
||||
order the shell delivers them when the service starts up,
|
||||
which is the time when these files are read.
|
||||
|
||||
If the "my_env.yaml" file from the example above had been put in the
|
||||
"environment_dir" then the user's command line could be this:
|
||||
@ -100,7 +101,7 @@ will be mapped to "OS::Quantum*" accordingly.
|
||||
|
||||
Please note that the template resource URL here must end with ".yaml"
|
||||
or ".template", or it will not be treated as a custom template
|
||||
resource.
|
||||
resource. The supported URL types are "http, https and file".
|
||||
|
||||
4) Always map resource type X to Y
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@ -19,8 +19,9 @@ Template Guide
|
||||
|
||||
hot_guide
|
||||
hot_spec
|
||||
environment
|
||||
composition
|
||||
openstack
|
||||
cfn
|
||||
contrib
|
||||
environment
|
||||
functions
|
||||
|
||||
Loading…
Reference in New Issue
Block a user