← Back to branch summary

~ubuntu-branches/ubuntu/vivid/heat/vivid

« back to all changes in this revision

Viewing changes to doc/source/template_guide/composition.rst

  • Committer: Package Import Robot
  • Author(s): Chuck Short, Chuck Short, Corey Bryant
  • Date: 2015-01-06 08:55:22 UTC
  • mfrom: (1.1.21)
  • Revision ID: package-import@ubuntu.com-20150106085522-4o3hnaff5lacvtrf
Tags: 2015.1~b1-0ubuntu1
[ Chuck Short ]
* Open up for vivid.
* debian/control: Update bzr branch. 
* debian/control: Add python-saharaclient,
  python-osprofiler, python-oslo.middleware, python-oslo.serialization.
* debian/patches/fix-reqirements.patch: Refreshed.
* debian/patches/skip-tests.patch: Updated to skip more tests.
* debian/rules: Skip integration tests.

[ Corey Bryant ]
* New upstream release.
  - d/control: Align requirements with upstream.
  - d/watch: Update uversionmangle for kilo beta naming.
  - d/rules: Generate heat.conf.sample and apply patch before copy.
  - d/rules: Run base tests instead of integration tests.
  - d/p/fix-requirements.patch: Refreshed.
  - d/p/remove-gettextutils-import.patch: Cherry picked from master.
* d/control: Bumped Standards-Version to 3.9.6.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/source/template_guide/composition.rst
 
1
..
 
2
      Licensed under the Apache License, Version 2.0 (the "License"); you may
 
3
      not use this file except in compliance with the License. You may obtain
 
4
      a copy of the License at
 
5
 
 
6
          http://www.apache.org/licenses/LICENSE-2.0
 
7
 
 
8
      Unless required by applicable law or agreed to in writing, software
 
9
      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 
10
      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 
11
      License for the specific language governing permissions and limitations
 
12
      under the License.
 
13
 
 
14
.. _composition:
 
15
 
 
16
====================
 
17
Template composition
 
18
====================
 
19
 
 
20
When writing complex templates you are encouraged to break up your
 
21
template into separate smaller templates. These can then be brought
 
22
together using template resources. This is a mechanism to define a resource
 
23
using a template, thus composing one logical stack with multiple templates.
 
24
 
 
25
 
 
26
How to use template resources for composition
 
27
---------------------------------------------
 
28
 
 
29
Template resources do a very similar job to
 
30
AWS::CloudFormation::Stack, but they are more powerful as they allow a
 
31
template to "stand in for" any resource type.
 
32
 
 
33
Template resources can be used to do the following:
 
34
 
 
35
 * Define new resource types (make you own resource library).
 
36
 * Override the default behaviour of existing resource types.
 
37
 
 
38
The way this is achieved is:
 
39
 
 
40
 * The heat client gets the associated template files and passes them
 
41
   along in the "files" section of the "POST stacks/".
 
42
 * The environment in Orchestration engine manages the mapping of resource type
 
43
   to template creation.
 
44
 * Translation of the template parameters into resource properties.
 
45
 
 
46
Let's go through some examples. In all examples assume the
 
47
same resource template. This is a simple wrapper around a nova server
 
48
(my_nova.yaml).
 
49
 
 
50
.. code-block:: yaml
 
51
 
 
52
  heat_template_version: 2013-05-23
 
53
  parameters:
 
54
    key_name:
 
55
      type: string
 
56
      description: Name of a KeyPair
 
57
  resources:
 
58
    server:
 
59
      type: OS::Nova::Server
 
60
      properties:
 
61
        key_name: {get_param: key_name}
 
62
        flavor: my.best
 
63
        image: the_one_i_always_use
 
64
 
 
65
 
 
66
Example 1
 
67
~~~~~~~~~
 
68
 
 
69
In this example you will not map a resource type name at all, but
 
70
directly specify the template URL as the resource type.
 
71
 
 
72
Your main template (main.yaml) would look like this.
 
73
 
 
74
.. code-block:: yaml
 
75
 
 
76
  heat_template_version: 2013-05-23
 
77
  resources:
 
78
    my_server:
 
79
      type: my_nova.yaml
 
80
      properties:
 
81
        key_name: my_key
 
82
 
 
83
Some notes about URLs:
 
84
 
 
85
The above reference to my_nova.yaml assumes it is in the same directory.
 
86
You could use any of the following forms:
 
87
 
 
88
 * Relative path (type: my_nova.yaml)
 
89
 * Absolute path (type: file:///home/user/templates/my_nova.yaml)
 
90
 * Http URL (type: http://example.com/templates/my_nova.yaml)
 
91
 * Https URL (type: https://example.com/templates/my_nova.yaml)
 
92
 
 
93
 
 
94
To create the stack, run::
 
95
 
 
96
  $ heat stack-create -f main.yaml example-one
 
97
 
 
98
Example 2
 
99
~~~~~~~~~
 
100
 
 
101
In this example you will use the environment (env.yaml) to override the
 
102
OS::Nova::Server with my_nova to get the defaults you want.
 
103
 
 
104
.. code-block:: yaml
 
105
 
 
106
  resource_registry:
 
107
    "OS::Nova::Server": my_nova.yaml
 
108
 
 
109
A more detailed discussion on this can be found here :ref:`environments`
 
110
 
 
111
Now you can use "OS::Nova::Server" in our top level template (main.yaml).
 
112
 
 
113
.. code-block:: yaml
 
114
 
 
115
  resources:
 
116
    my_server:
 
117
      type: OS::Nova::Server
 
118
      properties:
 
119
        key_name: my_key
 
120
 
 
121
To create the stack, run::
 
122
 
 
123
  $ heat stack-create -f main.yaml -e env.yaml example-two
 
124
 
 
125
 
 
126
Getting access to nested attributes
 
127
-----------------------------------
 
128
There are implicit attributes of a template resource. These are
 
129
accessable as follows:
 
130
 
 
131
.. code-block:: yaml
 
132
 
 
133
  heat_template_version: 2013-05-23
 
134
  resources:
 
135
    my_server:
 
136
      type: my_nova.yaml
 
137
 
 
138
  outputs:
 
139
    test_out:
 
140
      value: {get_attr: my_server, resource.server, first_address}
 
141
 
 
142
 
 
143
Making your template resource more "transparent"
 
144
------------------------------------------------
 
145
If you wish to be able to return the ID of one of the inner resources
 
146
instead of the nested stack's ARN, you can add the following special
 
147
output to your template resource.
 
148
 
 
149
.. code-block:: yaml
 
150
 
 
151
  resources:
 
152
    server:
 
153
      type: OS::Nova::Server
 
154
 
 
155
  outputs:
 
156
    OS::stack_id:
 
157
      value: {get_resource: server}
 
158
 
 
159
Now when you use "get_resource" or "get_attr" from the outer template heat
 
160
will use nova server and not the template resource.