5
Licensed under the Apache License, Version 2.0 (the "License"); you may
6
not use this file except in compliance with the License. You may obtain
7
a copy of the License at
9
http://www.apache.org/licenses/LICENSE-2.0
11
Unless required by applicable law or agreed to in writing, software
12
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
13
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
14
License for the specific language governing permissions and limitations
19
==================================
20
Writing a hello world HOT template
21
==================================
23
HOT is a new template format meant to replace the CloudFormation-compatible
24
format (CFN) as the native format supported by the Orchestration module over
26
This guide is targeted towards template authors and explains how to write
27
HOT templates based on examples. A detailed specification of HOT can be found
31
This section gives an introduction on how to write HOT templates, starting from
32
very basic steps and then going into more and more detail by means of examples.
36
The most basic template you can think of contains only a single resource
37
definition using only predefined properties. For example, the template below
38
could be used to deploy a single compute instance:
43
heat_template_version: 2013-05-23
45
description: Simple template to deploy a single compute instance
49
type: OS::Nova::Server
52
image: ubuntu-trusty-x86_64
55
Each HOT template must include the ``heat_template_version`` key with
56
the HOT version value, for example, ``2013-05-23``. A list of HOT template
57
versions can be found at `Heat Template Version
58
file <http://docs.openstack.org/developer/heat/template_guide/hot_spec.html#heat-template-version>`__
60
The ``description`` key is optional, however it is good practice to include
61
some useful text that describes what users can do with the template.
62
In case you want to provide a longer description that does not fit on
63
a single line, you can provide multi-line text in YAML, for example:
68
This is how you can provide a longer description
69
of your template that goes over several lines.
71
The ``resources`` section is required and must contain at least one resource
72
definition. In the above example, a compute instance is defined with fixed
73
values for the ``key_name``, ``image`` and ``flavor`` properties.
76
All the defined elements (key pair, image, flavor) have to exist in the
77
OpenStack environment where the template is used.
81
Input parameters defined in the ``parameters`` section of a template
82
allow users to customize a template during deployment. For example, this allows
83
for providing custom key pair names or image IDs to be used for a deployment.
84
From a template author's perspective, this helps to make a template more easily
85
reusable by avoiding hardcoded assumptions.
87
The following example extends the previous template to provide parameters for
88
the key pair, image and flavor properties of the resource:
93
heat_template_version: 2013-05-23
95
description: Simple template to deploy a single compute instance
101
description: Name of key-pair to be used for compute instance
105
description: Image to be used for compute instance
109
description: Type of instance (flavor) to be used
113
type: OS::Nova::Server
115
key_name: { get_param: key_name }
116
image: { get_param: image_id }
117
flavor: { get_param: flavor }
120
Values for the three parameters must be defined by the template user during the
121
deployment of a stack. The ``get_param`` intrinsic function retrieves a
122
user-specified value for a given parameter and uses this value for the
123
associated resource property.
125
For more information about intrinsic functions, see
126
:ref:`hot_spec_intrinsic_functions`.
128
Providing default values
129
------------------------
130
You can provide default values for parameters. If a user doesn't define a value
131
for a parameter, the default value is used during the stack deployment. The
132
following example defines a default value ``m1.small`` for the
142
description: Flavor to be used
146
If a template doesn't define a default value for a parameter, then the user
147
must define the value, otherwise the stack creation will fail.
149
Hiding parameters values
150
------------------------
151
The values that a user provides when deploying a stack are available in the
152
stack details and can be accessed by any user in the same tenant. To hide the
153
value of a parameter, use the ``hidden`` boolean attribute of the parameter:
161
label: Database Password
162
description: Password to be used for database
165
Restricting user input
166
----------------------
167
You can restrict the values of an input parameter to make sure that the user
168
defines valid data for this parameter. The ``constraints`` property of an input
169
parameter defines a list of constraints to apply for the parameter.
170
The following example restricts the ``flavor`` parameter to a list of three
180
description: Type of instance (flavor) to be used
182
- allowed_values: [ m1.medium, m1.large, m1.xlarge ]
183
description: Value must be one of m1.medium, m1.large or m1.xlarge.
185
The following example defines multiple constraints for a password definition:
193
label: Database Password
194
description: Password to be used for database
197
- length: { min: 6, max: 8 }
198
description: Password length must be between 6 and 8 characters.
199
- allowed_pattern: "[a-zA-Z0-9]+"
200
description: Password must consist of characters and numbers only.
201
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
202
description: Password must start with an uppercase character.
204
The list of supported constraints is available in the
205
:ref:`hot_spec_parameters_constraints` section.
208
You can define multiple constraints of the same type. Especially in the
209
case of allowed patterns this not only allows for keeping regular
210
expressions simple and maintainable, but also for keeping error messages to
211
be presented to users precise.
216
In addition to template customization through input parameters, you can
217
provide information about the resources created during the stack deployment to
218
the users in the ``outputs`` section of a template. In the following example
219
the output section provides the IP address of the ``my_instance`` resource:
225
description: The IP address of the deployed instance
226
value: { get_attr: [my_instance, first_address] }
229
Output values are typically resolved using intrinsic function such as
230
the ``get_attr``. See :ref:`hot_spec_intrinsic_functions` for more information
231
about intrinsic functions..
233
See :ref:`hot_spec_outputs` for more information about the ``outputs`` section.
added
removed
doc/source/template_guide/hello_world.rst
