Sync environment and composition docs from openstack-manuals

Change-Id: Ib9ca5ffa4df5fd9ed6245d359fe1a8a54a477433
Closes-bug: #1366845
This commit is contained in:
Angus Salkeld 2014-09-16 12:01:37 +10:00
parent b4013fd7f6
commit bebeb5df44
3 changed files with 140 additions and 15 deletions

View 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

View File

@ -18,11 +18,12 @@ Environments
============ ============
The environment is used to affect the runtime behaviour of the The environment is used to affect the runtime behaviour of the
template. It provides a way to override the default resource template. It provides a way to override the resource
implementation and the parameters passed to Heat. implementations and provide a mechanism to place parameters
that the service needs.
To fully understand the runtime behavior you also have to consider 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 Format
@ -44,21 +45,21 @@ Global and effective environments
The environment used for a stack is the combination of (1) the 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) environment given by the user with the template for the stack and (2)
a global environment that is determined by the cloud provider. a global environment that is determined by the cloud operator.
Combination is asymmetric: an entry in the first environment takes Combination is asymmetric: an entry in the user environment takes
precedence over an entry in the second. The OpenStack software precedence over the global environment. The OpenStack software
includes a default global environment, which supplies some resource includes a default global environment, which supplies some resource
types that are included in the standard documentation. The cloud 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 by putting environment files in a configurable directory wherever
the heat engine runs. The configuration variable is named the heat engine runs. The configuration variable is named
"environment_dir" and is found in the "heat.common.config" module (AKA "environment_dir" is found in the "[DEFAULT]" section
the "[DEFAULT]" section) of "/etc/heat/heat.conf". The default for of "/etc/heat/heat.conf". The default for that directory is
that directory is "/etc/heat/environment.d". Its contents are "/etc/heat/environment.d". Its contents are combined in whatever
combined in whatever order the shell delivers them when the heat order the shell delivers them when the service starts up,
engine starts up, which is the time when these files are read. which is the time when these files are read.
If the "my_env.yaml" file from the example above had been put in the 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: "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" Please note that the template resource URL here must end with ".yaml"
or ".template", or it will not be treated as a custom template 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 4) Always map resource type X to Y
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

View File

@ -19,8 +19,9 @@ Template Guide
hot_guide hot_guide
hot_spec hot_spec
environment
composition
openstack openstack
cfn cfn
contrib contrib
environment
functions functions