HOT is a new template format meant to replace the Heat CloudFormation-compatible format (CFN) as the native format supported by the Heat over time. This specification explains in detail all elements of the HOT template format. An example driven guide to writing HOT templates can be found at Heat Orchestration Template (HOT) Guide.
HOT is considered reliable, supported, and standardized as of our Icehouse (April 2014) release. The Heat core team may make improvements to the standard, which very likely would be backward compatible. The template format is also versioned. In our Juno release, Heat will support multiple different versions of the HOT specification if there is a need driven by the introduction of new features.
HOT templates are defined in YAML and follow the structure outlined below.
heat_template_version: 2013-05-23
description:
# a description of the template
parameter_groups:
# a declaration of input parameter groups and order
parameters:
# declaration of input parameters
resources:
# declaration of template resources
outputs:
# declaration of output parameters
The parameter_groups section allows for specifying how the input parameters should be grouped and the order to provide the parameters in. These groups are typically used to describe expected behavior for downstream user interfaces.
These groups are specified in a list with each group containing a list of associated parameters. The lists are used to denote the expected order of the parameters. Each parameter should be associated to a specific group only once using the parameter name to bind it to a defined parameter in the parameters section.
parameter_groups:
- label: <human-readable label of parameter group>
description: <description of the parameter group>
parameters:
- <param name>
- <param name>
The parameters section allows for specifying input parameters that have to be provided when instantiating the template. Such parameters are typically used to customize each deployment (e.g. by setting custom user names or passwords) or for binding to environment-specifics like certain images.
Each parameter is specified in a separated nested block with the name of the parameters defined in the first line and additional attributes such as type or default value defined as nested elements.
parameters:
<param name>:
type: <string | number | json | comma_delimited_list>
label: <human-readable name of the parameter>
description: <description of the parameter>
default: <default value for parameter>
hidden: <true | false>
constraints:
<parameter constraints>
The following example shows a minimalistic definition of two parameters. Note that the description and label are actually optional, but is good practice to provide a useful description and label for each parameter.
parameters:
user_name:
type: string
label: User Name
description: User name to be configured for the application
port_number:
type: number
label: Port Number
description: Port number to be configured for the web server
The constraints block of a parameter definition allows for defining additional validation constraints that apply to the value of the parameter. At instantiation time of the template, user provided parameter values are validated against those constraints to make sure the provided values match expectations of the template author. Constraints are defined in the form of a bulleted list according to the following syntax:
constraints:
- <constraint type>: <constraint definition>
description: <constraint description>
The following example show the definition of a string parameter with two constraints. Note that while the descriptions for each constraint are optional, it is good practice to provide concrete descriptions so useful messages can be presented to the user at deployment time.
parameters:
user_name:
type: string
label: User Name
description: User name to be configured for the application
constraints:
- length: { min: 6, max: 8 }
description: User name must be between 6 and 8 characters
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
description: User name must start with an uppercase character
The following sections list the supported types of parameter constraints, along with the concrete syntax for each type.
The length constraint applies to parameters of type string and allows for defining a lower and upper limit for the length of the string value. The syntax for the length constraint is:
length: { min: <lower limit>, max: <upper limit> }
It is possible to define a length constraint with only a lower limit or an upper limit. However, at least one of min or max must be specified.
The range constraint applies to parameters of type number and allows for defining a lower and upper limit for the numeric value of the parameter. The syntax of the range constraint is:
range: { min: <lower limit>, max: <upper limit> }
It is possible to define a range constraint with only a lower limit or an upper limit. However, at least one of min or max must be specified. The minimum or maximum boundaries are included in the range. For example, the following range constraint would allow for all numeric values between 0 and 10.
range: { min: 0, max: 10 }
The allowed_values constraint applies to parameters of type string or number and allows for specifying a set of possible values for a parameter. At deployment time, the user provided value for the respective parameter must match one of the elements of the specified list. The syntax of the allowed_values constraint is:
allowed_values: [ <value>, <value>, ... ]
Alternatively, the YAML bulleted list notation can be used:
allowed_values:
- <value>
- <value>
- ...
For example:
parameters:
instance_type:
type: string
label: Instance Type
description: Instance type for compute instances
constraints:
- allowed_values:
- m1.small
- m1.medium
- m1.large
The allowed_pattern constraint applies to parameters of type string and allows for specifying a regular expression against which a user provided parameter value must evaluate at deployment. The syntax of the allowed_pattern constraint is:
allowed_pattern: <regular expression>
For example:
parameters:
user_name:
type: string
label: User Name
description: User name to be configured for the application
constraints:
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
description: User name must start with an uppercase character
The custom_constraint constraint adds an extra step of validation, generally to check that the specified resource exists in the backend. Custom constraints get implemented by plug-ins and can provide any kind of advanced constraint validation logic.
The syntax of the custom_constraint constraint is:
custom_constraint: <name>
The name specifies the concrete type of custom constraint. It corresponds to the name under which the respective validation plugin has been registered with the Heat engine.
For example:
parameters:
key_name
type: string
description: SSH key pair
constraints:
- custom_constraint: nova.keypair
In the resources section, the templates for actual resources that will make up a stack deployed from the HOT template (e.g. compute instances, networks, storage volumes) are defined. Each resource is defined as a separate block in the resources section according to the syntax below.
resources:
<resource ID>:
type: <resource type>
properties:
<property name>: <property value>
metadata:
<resource specific metadata>
depends_on: <resource ID or list of ID>
update_policy: <update policy>
deletion_policy: <deletion policy>
Depending on the type of resource, the resource block might include more resource specific data. Basically all resource types that can be used in CFN templates can also be used in HOT templates, adapted to the YAML structure as outlined above. Below is an example of a simple compute resource definition with some fixed property values.
resources:
my_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: F18-x86_64-cfntools
By means of the depends_on attribute within a resource section it is possible to define a dependency between a resource and one or more other resources. If a resource depends on just one other resource, the ID of the other resource is specified as value of the depends_on attribute as shown in the following example.
resources:
server1:
type: OS::Nova::Server
depends_on: server2
server2:
type: OS::Nova::Server
If a resource depends on more than one other resource, the value of the depends_on attribute is specified as a list of resource IDs as shown in the following example:
resources:
server1:
type: OS::Nova::Server
depends_on: [ server2, server3 ]
server2:
type: OS::Nova::Server
server3:
type: OS::Nova::Server
In the outputs section, any output parameters that should be available to the user can be defined. Typically, this would be, for example, parameters such as IP addresses of deployed instances, or URLs of web applications deployed as part of a stack.
Each output parameter is defined as a separate block within the outputs section according to the following syntax:
outputs:
<parameter name>:
description: <description>
value: <parameter value>
The example below shows, how the IP address of a compute resource can be defined as an output parameter.
outputs:
instance_ip:
description: IP address of the deployed compute instance
value: { get_attr: [my_instance, first_address] }
HOT provides a set of intrinsic functions that can be used inside HOT templates to perform specific tasks, such as getting the value of a resource attribute at runtime. A definition of all intrinsic functions available in HOT is given below.
The get_param function allows for referencing an input parameter of a template from anywhere within a template. At runtime, it will be resolved to the value provided for this input parameter. The syntax of the get_param function is as follows:
get_param:
- <parameter name>
- <key/index 1> (optional)
- <key/index 2> (optional)
- ...
A sample use of this function in context of a resource definition is shown below.
parameters:
instance_type:
type: string
label: Instance Type
description: Instance type to be used.
server_data:
type: json
resources:
my_instance:
type: OS::Nova::Server
properties:
flavor: { get_param: instance_type}
metadata: { get_param: [ server_data, metadata ] }
key_name: { get_param: [ server_data, keys, 0 ] }
In this example, if the instance_type/server_data parameters contained the following data:
{"instance_type": "m1.tiny",
{"server_data": {"metadata": {"foo": "bar"},
"keys": ["a_key","other_key"]}}}
then the value of the property ‘flavor’ would resolve to “m1.tiny”, ‘metadata’ would resolve to {“foo”: “bar”} and ‘key_name’ would resolve to “a_key”.
The get_attr function allows referencing an attribute of a resource. At runtime, it will be resolved to the value of an attribute of a resource instance created from the respective resource definition of the template. The syntax of the get_attr function is as follows:
get_attr:
- <resource ID>
- <attribute name>
- <key/index 1> (optional)
- <key/index 2> (optional)
- ...
Some examples of how to use the get_attr function are shown below:
resources:
my_instance:
type: OS::Nova::Server
# ...
outputs:
instance_ip:
description: IP address of the deployed compute instance
value: { get_attr: [my_instance, first_address] }
instance_private_ip:
description: Private IP address of the deployed compute instance
value: { get_attr: [my_instance, networks, private, 0] }
In this example, if the networks attribute contained the following data:
{"public": ["2001:0db8:0000:0000:0000:ff00:0042:8329", "1.2.3.4"],
"private": ["10.0.0.1"]}
then the value of the get_attr function would resolve to “10.0.0.1”.
The get_resource function allows for referencing another resource within the same template. At runtime, it will be resolved to reference ID of the resource, which is resource type specific. For example, a reference to a floating IP resource will return the respective IP address at runtime. The syntax of the get_resource function is as follows:
get_resource: <resource ID>
The resource ID of the referenced resources as used in the current template is given as single parameter to the get_resource function.
The str_replace function allows for dynamically constructing strings by providing a template string with placeholders and a list of mappings to assign values to those placeholders at runtime. The placeholders are replaced with mapping values wherever a mapping key exactly matches a placeholder. The syntax of the str_replace function is as follows:
str_replace:
template: <template string>
params: <parameter mappings>
The example below shows a simple use of the str_replace function in the outputs section of a template to build a URL for logging into a deployed application.
resources:
my_instance:
type: OS::Nova::Server
# general metadata and properties ...
outputs:
Login_URL:
description: The URL to log into the deployed application
value:
str_replace:
template: http://host/MyApplication
params:
host: { get_attr: [ my_instance, first_address ] }
The str_replace function can also be used for constructing bigger chunks of text like scripts for initializing compute instances as shown in the example below:
parameters:
DBRootPassword:
type: string
label: Database Password
description: Root password for MySQL
hidden: true
resources:
my_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
str_replace:
template: |
#!/bin/bash
echo "Hello world"
echo "Setting MySQL root password"
mysqladmin -u root password $db_rootpassword
# do more things ...
params:
$db_rootpassword: { get_param: DBRootPassword }
In the example above, one can imagine that MySQL is being configured on a compute instance and the root password is going to be set based on a user provided parameter. The script for doing this is provided as userdata to the compute instance, leveraging the str_replace function.
The get_file function allows string content to be substituted into the template. It is generally used as a file inclusion mechanism for files containing non-heat scripts or configuration files. The syntax of the get_file function is as follows:
get_file: <content key>
The content key will be used to look up the files dictionary that is provided in the REST API call. The heat client command from python-heatclient is get_file aware and will populate the files with the actual content of fetched paths and URLs. The heat client command supports relative paths and will transform these to absolute URLs which will be used as the content key in the files dictionary.
The example below demonstrates get_file usage with both relative and absolute URLs.
resources:
my_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
get_file: my_instance_user_data.sh
my_other_instance:
type: OS::Nova::Server
properties:
# general properties ...
user_data:
get_file: http://example.com/my_other_instance_user_data.sh
If this template was launched from a local file this would result in a files dictionary containing entries with keys file:///path/to/my_instance_user_data.sh and http://example.com/my_other_instance_user_data.sh.
The resource_facade function allows a provider template to retrieve data about its resource facade in the parent template. (A provider template is used to provide a custom definition of a resource - the facade - in the form of a Heat template. The resource’s properties are passed to the provider template as its parameters, but other resource data can be included using this function.) The syntax of the resource_facade function is as follows:
resource_facade: <data type>
The data type can be metadata, deletion_policy or update_policy.