diff --git a/doc/source/template_guide/composition.rst b/doc/source/template_guide/composition.rst new file mode 100644 index 000000000..6bbbeafa4 --- /dev/null +++ b/doc/source/template_guide/composition.rst @@ -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 diff --git a/doc/source/template_guide/environment.rst b/doc/source/template_guide/environment.rst index 45cd16ebf..877b19f2b 100644 --- a/doc/source/template_guide/environment.rst +++ b/doc/source/template_guide/environment.rst @@ -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/template_guide/index.rst b/doc/source/template_guide/index.rst index e2f8fea0c..80f706206 100644 --- a/doc/source/template_guide/index.rst +++ b/doc/source/template_guide/index.rst @@ -19,8 +19,9 @@ Template Guide hot_guide hot_spec + environment + composition openstack cfn contrib - environment functions