openstack-manuals/doc/user-guide/hot/section_hot_spec.xml

<?xml version='1.0' encoding='UTF-8'?>
<!--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.-->
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="hot-spec">
  <!--WARNING: This file is automatically generated. Do not edit it.-->
  <title>Heat Orchestration Template (HOT) specification</title>
  <section xml:id="template-structure">
    <?dbhtml stop-chunking?>
    <title>Template structure</title>
    <para>HOT templates are defined in YAML and use the following structure:</para>
    <programlisting language="yaml">heat_template_version: 2013-05-23

description:
  # description of the template

parameter_groups:
  # declaration of input parameter groups and order

parameters:
  # declaration of input parameters

resources:
  # declaration of template resources

outputs:
  # declaration of output parameters</programlisting>
    <variablelist role="definition_list">
      <varlistentry>
        <term>heat_template_version</term>
        <listitem>
          <para>This key with value <literal>2013-05-23</literal> (or a later date) indicates that the
YAML document is a HOT template of the specified version.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>description</term>
        <listitem>
          <para>This optional key gives a description of the template, or
the workload that can be deployed using the template.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>parameter_groups</term>
        <listitem>
          <para>This section specifies how the input parameters should be
grouped and the order to provide the parameters in.</para>
          <para>This section is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>parameters</term>
        <listitem>
          <para>This section specifies input parameters that have to
be provided when instantiating the template.</para>
          <para>This section is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>resources</term>
        <listitem>
          <para>This section contains the declaration of the resources of the template.
This section with at least one resource must be defined in any HOT
template, or the template would not really do anything when being
instantiated.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>outputs</term>
        <listitem>
          <para>This section specifies output parameters available to users once the
template has been instantiated.</para>
          <para>This section is optional.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>
  <section xml:id="hot-spec-parameter-groups">
    <?dbhtml stop-chunking?>
    <title>Parameter groups section</title>
    <para>The <literal>parameter_groups</literal> section specifies 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.</para>
    <para>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. A parameter can only be included in one group. Use the name of the
parameter to add it to a group. The parameters details are defined in
the <literal>parameters</literal> section.</para>
    <programlisting language="yaml">parameter_groups:
- label: &lt;human-readable label of parameter group&gt;
  description: &lt;description of the parameter group&gt;
  parameters:
  - &lt;param name&gt;
  - &lt;param name&gt;</programlisting>
    <variablelist role="definition_list">
      <varlistentry>
        <term>label</term>
        <listitem>
          <para>A human-readable label that defines the associated group of parameters.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>description</term>
        <listitem>
          <para>A human-readable description of the parameter group.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>parameters</term>
        <listitem>
          <para>A list of parameters that belong with this parameter group.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>param name</term>
        <listitem>
          <para>The name of a parameter defined in the <literal>parameters</literal> section.</para>
        </listitem>
      </varlistentry>
    </variablelist>
  </section>
  <section xml:id="hot-spec-parameters">
    <?dbhtml stop-chunking?>
    <title>Parameters section</title>
    <para>The <literal>parameters</literal> section defines input parameters that have to be
provided when instantiating the template. Such parameters are typically used to
customize each deployment, or for binding to environment specifics like certain
images.</para>
    <para>Each parameter is specified in a separated nested block with the name of the
parameter defined in the first line and additional attributes such as a type or
a default value defined as nested elements:</para>
    <programlisting language="yaml">parameters:
  &lt;param name&gt;:
    type: &lt;string | number | json | comma_delimited_list | boolean&gt;
    label: &lt;human-readable name of the parameter&gt;
    description: &lt;description of the parameter&gt;
    default: &lt;default value for parameter&gt;
    hidden: &lt;true | false&gt;
    constraints:
      &lt;parameter constraints&gt;</programlisting>
    <variablelist role="definition_list">
      <varlistentry>
        <term>param name</term>
        <listitem>
          <para>The name of the parameter.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>type</term>
        <listitem>
          <para>The type of the parameter. Supported types
are <literal>string</literal>, <literal>number</literal>, <literal>comma_delimited_list</literal>, <literal>json</literal> and
<literal>boolean</literal>.</para>
          <para>This attribute is required.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>label</term>
        <listitem>
          <para>A human readable name for the parameter.</para>
          <para>This attribute is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>description</term>
        <listitem>
          <para>A human readable description for the parameter.</para>
          <para>This attribute is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>default</term>
        <listitem>
          <para>A default value for the parameter. This value is used if the user doesn't
specify his own value during deployment.</para>
          <para>This attribute is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>hidden</term>
        <listitem>
          <para>Defines whether the parameters should be hidden when a user requests
information about a stack created from the template. This attribute can be
used to hide passwords specified as parameters.</para>
          <para>This attribute is optional and defaults to <literal>false</literal>.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>constraints</term>
        <listitem>
          <para>A list of constraints to apply. The constraints are validated by the
Orchestration engine when a user deploys a stack. The stack creation fails
if the parameter value doesn't comply to the constraints.</para>
          <para>This attribute is optional.</para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>The following example shows a minimalistic definition of two parameters:</para>
    <programlisting language="yaml">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</programlisting>
    <note>
      <para>The description and the label are optional, but defining these attributes
is good practice to provide useful information about the role of the
parameter to the user.</para>
    </note>
    <section xml:id="hot-spec-parameters-constraints">
      <title>Parameter constraints</title>
      <para>The <literal>constraints</literal> block of a parameter definition defines
additional validation constraints that apply to the value of the
parameter. The parameter values provided by a user are validated against the
constraints at instantiation time. The constraints are defined as a list with
the following syntax:</para>
      <programlisting language="yaml">constraints:
  - &lt;constraint type&gt;: &lt;constraint definition&gt;
    description: &lt;constraint description&gt;</programlisting>
      <variablelist role="definition_list">
        <varlistentry>
          <term>constraint type</term>
          <listitem>
            <para>Type of constraint to apply. The set of currently supported constraints is
given below.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>constraint definition</term>
          <listitem>
            <para>The actual constraint, depending on the constraint type.  The
concrete syntax for each constraint type is given below.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>description</term>
          <listitem>
            <para>A description of the constraint. The text
is presented to the user when the value he defines violates the constraint.
If omitted, a default validation message is presented to the user.</para>
            <para>This attribute is optional.</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The following example shows 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 to present useful messages
to the user at deployment time.</para>
      <programlisting language="yaml">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</programlisting>
      <note>
        <para>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.</para>
      </note>
      <para>The following sections list the supported types of parameter constraints, along
with the syntax for each type.</para>
      <section xml:id="length">
        <title>length</title>
        <para>The <literal>length</literal> constraint applies to parameters of type <literal>string</literal>. It defines
a lower and upper limit for the length of the string value.</para>
        <para>The syntax of the <literal>length</literal> constraint is:</para>
        <programlisting language="yaml">length: { min: &lt;lower limit&gt;, max: &lt;upper limit&gt; }</programlisting>
        <para>It is possible to define a length constraint with only a lower limit or an
upper limit. However, at least one of <literal>min</literal> or <literal>max</literal> must be specified.</para>
      </section>
      <section xml:id="range">
        <title>range</title>
        <para>The <literal>range</literal> constraint applies to parameters of type <literal>number</literal>. It defines a
lower and upper limit for the numeric value of the parameter.</para>
        <para>The syntax of the <literal>range</literal> constraint is:</para>
        <programlisting language="yaml">range: { min: &lt;lower limit&gt;, max: &lt;upper limit&gt; }</programlisting>
        <para>It is possible to define a range constraint with only a lower limit or an
upper limit. However, at least one of <literal>min</literal> or <literal>max</literal> must be specified.</para>
        <para>The minimum and maximum boundaries are included in the range. For example, the
following range constraint would allow for all numeric values between 0 and 10:</para>
        <programlisting language="yaml">range: { min: 0, max: 10 }</programlisting>
      </section>
      <section xml:id="allowed-values">
        <title>allowed_values</title>
        <para>The <literal>allowed_values</literal> constraint applies to parameters of type <literal>string</literal> or
<literal>number</literal>. It specifies 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 list.</para>
        <para>The syntax of the <literal>allowed_values</literal> constraint is:</para>
        <programlisting language="yaml">allowed_values: [ &lt;value&gt;, &lt;value&gt;, ... ]</programlisting>
        <para>Alternatively, the following YAML list notation can be used:</para>
        <programlisting language="yaml">allowed_values:
  - &lt;value&gt;
  - &lt;value&gt;
  - ...</programlisting>
        <para>For example:</para>
        <programlisting language="yaml">parameters:
  instance_type:
    type: string
    label: Instance Type
    description: Instance type for compute instances
    constraints:
      - allowed_values:
        - m1.small
        - m1.medium
        - m1.large</programlisting>
      </section>
      <section xml:id="allowed-pattern">
        <title>allowed_pattern</title>
        <para>The <literal>allowed_pattern</literal> constraint applies to parameters of type <literal>string</literal>.
It specifies a regular expression against which a user-provided parameter value
must evaluate at deployment.</para>
        <para>The syntax of the <literal>allowed_pattern</literal> constraint is:</para>
        <programlisting language="yaml">allowed_pattern: &lt;regular expression&gt;</programlisting>
        <para>For example:</para>
        <programlisting language="yaml">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</programlisting>
      </section>
      <section xml:id="custom-constraint">
        <title>custom_constraint</title>
        <para>The <literal>custom_constraint</literal> 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.</para>
        <para>The syntax of the <literal>custom_constraint</literal> constraint is:</para>
        <programlisting language="yaml">custom_constraint: &lt;name&gt;</programlisting>
        <para>The <literal>name</literal> attribute specifies the concrete type of custom constraint. It
corresponds to the name under which the respective validation plugin has been
registered in the Orchestration engine.</para>
        <para>For example:</para>
        <programlisting language="yaml">parameters:
  key_name
    type: string
    description: SSH key pair
    constraints:
      - custom_constraint: nova.keypair</programlisting>
      </section>
    </section>
    <section xml:id="hot-spec-pseudo-parameters">
      <title>Pseudo Parameters</title>
      <para>In addition to parameters defined by a template author, the Orchestration
module also creates two parameters for every stack that allow referential
access to the stack's name and identifier. These parameters are named
<literal>OS::stack_name</literal> for the stack name and <literal>OS::stack_id</literal> for the stack
identifier. These values are accessible via the <literal>get_param</literal> intrinsic
function, just like user-defined parameters.</para>
    </section>
  </section>
  <section xml:id="hot-spec-resources">
    <?dbhtml stop-chunking?>
    <title>Resources section</title>
    <para>The <literal>resources</literal> section defines actual resources that make up a stack
deployed from the HOT template (for instance compute instances, networks,
storage volumes).</para>
    <para>Each resource is defined as a separate block in the <literal>resources</literal> section with
the following syntax:</para>
    <programlisting language="yaml">resources:
  &lt;resource ID&gt;:
    type: &lt;resource type&gt;
    properties:
      &lt;property name&gt;: &lt;property value&gt;
    metadata:
      &lt;resource specific metadata&gt;
    depends_on: &lt;resource ID or list of ID&gt;
    update_policy: &lt;update policy&gt;
    deletion_policy: &lt;deletion policy&gt;</programlisting>
    <variablelist role="definition_list">
      <varlistentry>
        <term>resource ID</term>
        <listitem>
          <para>A resource ID which must be unique within the <literal>resources</literal> section of the
template.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>type</term>
        <listitem>
          <para>The resource type, such as <literal>OS::Nova::Server</literal> or <literal>OS::Neutron::Port</literal>.</para>
          <para>This attribute is required.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>properties</term>
        <listitem>
          <para>A list of resource-specific properties. The property value can be provided
in place, or via a function (see <link linkend="hot-spec-intrinsic-functions"><emphasis>Intrinsic functions</emphasis></link>).</para>
          <para>This section is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>metadata</term>
        <listitem>
          <para>Resource-specific metadata.</para>
          <para>This section is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>depends_on</term>
        <listitem>
          <para>Dependencies of the resource on one or more resources of the template.</para>
          <para>See <link linkend="hot-spec-resources-dependencies"><emphasis>Resource dependencies</emphasis></link> for details.</para>
          <para>This attribute is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>update_policy</term>
        <listitem>
          <para>Update policy for the resource, in the form of a nested dictionary. Whether
update policies are supported and what the exact semantics are depends on
the type of the current resource.</para>
          <para>This attribute is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>deletion_policy</term>
        <listitem>
          <para>Deletion policy for the resource. Which type of deletion policy is
supported depends on the type of the current resource.</para>
          <para>This attribute is optional.</para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>Depending on the type of resource, the resource block might include more
resource specific data.</para>
    <para>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.</para>
    <para>The following example demonstrates the definition of a simple compute resource
with some fixed property values:</para>
    <programlisting language="yaml">resources:
  my_instance:
    type: OS::Nova::Server
    properties:
      flavor: m1.small
      image: F18-x86_64-cfntools</programlisting>
    <section xml:id="hot-spec-resources-dependencies">
      <title>Resource dependencies</title>
      <para>The <literal>depends_on</literal> attribute of a resource defines a dependency between this
resource and one or more other resources.</para>
      <para>If a resource depends on just one other resource, the ID of the other resource
is specified as string of the <literal>depends_on</literal> attribute, as shown in the
following example:</para>
      <programlisting language="yaml">resources:
  server1:
    type: OS::Nova::Server
    depends_on: server2

  server2:
    type: OS::Nova::Server</programlisting>
      <para>If a resource depends on more than one other resources, the value of the
<literal>depends_on</literal> attribute is specified as a list of resource IDs, as shown in
the following example:</para>
      <programlisting language="yaml">resources:
  server1:
    type: OS::Nova::Server
    depends_on: [ server2, server3 ]

  server2:
    type: OS::Nova::Server

  server3:
    type: OS::Nova::Server</programlisting>
    </section>
  </section>
  <section xml:id="hot-spec-outputs">
    <?dbhtml stop-chunking?>
    <title>Outputs section</title>
    <para>The <literal>outputs</literal> section defines output parameters that should be available to
the user once a stack has been created. This would be, for example, parameters
such as IP addresses of deployed instances, or URLs of web applications
deployed as part of a stack.</para>
    <para>Each output parameter is defined as a separate block within the outputs section
according to the following syntax:</para>
    <programlisting language="yaml">outputs:
  &lt;parameter name&gt;:
    description: &lt;description&gt;
    value: &lt;parameter value&gt;</programlisting>
    <variablelist role="definition_list">
      <varlistentry>
        <term>parameter name</term>
        <listitem>
          <para>The output parameter name, which must be unique within the <literal>outputs</literal>
section of a template.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>description</term>
        <listitem>
          <para>A short description of the output parameter.</para>
          <para>This attribute is optional.</para>
        </listitem>
      </varlistentry>
      <varlistentry>
        <term>parameter value</term>
        <listitem>
          <para>The value of the output parameter. This value is usually resolved by means
of a function. See <link linkend="hot-spec-intrinsic-functions"><emphasis>Intrinsic functions</emphasis></link> for details about
the functions.</para>
          <para>This attribute is required.</para>
        </listitem>
      </varlistentry>
    </variablelist>
    <para>The example below shows how the IP address of a compute resource can
be defined as an output parameter:</para>
    <programlisting language="yaml">outputs:
  instance_ip:
    description: IP address of the deployed compute instance
    value: { get_attr: [my_instance, first_address] }</programlisting>
  </section>
  <section xml:id="hot-spec-intrinsic-functions">
    <?dbhtml stop-chunking?>
    <title>Intrinsic functions</title>
    <para>HOT provides a set of intrinsic functions that can be used inside templates
to perform specific tasks, such as getting the value of a resource attribute at
runtime. The following section describes the role and syntax of the intrinsic
functions.</para>
    <section xml:id="get-attr">
      <title>get_attr</title>
      <para>The <literal>get_attr</literal> function references an attribute of a
resource. The attribute value is resolved at runtime using the resource
instance created from the respective resource definition.</para>
      <para>The syntax of the <literal>get_attr</literal> function is:</para>
      <programlisting language="yaml">get_attr:
  - &lt;resource ID&gt;
  - &lt;attribute name&gt;
  - &lt;key/index 1&gt; (optional)
  - &lt;key/index 2&gt; (optional)
  - ...</programlisting>
      <variablelist role="definition_list">
        <varlistentry>
          <term>resource ID</term>
          <listitem>
            <para>The resource ID for which the attribute needs to be resolved.</para>
            <para>The resource ID must exist in the <literal>resources</literal> section of the template.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>attribute name</term>
          <listitem>
            <para>The attribute name to be resolved. If the attribute returns a complex data
structure such as a list or a map, then subsequent keys or indexes can be
specified. These additional parameters are used to navigate the data
structure to return the desired value.</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The following example demonstrates how to use the <literal>get_param</literal> function:</para>
      <programlisting language="yaml">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] }</programlisting>
      <para>In this example, if the networks attribute contained the following data:</para>
      <programlisting language="yaml">{"public": ["2001:0db8:0000:0000:0000:ff00:0042:8329", "1.2.3.4"],
 "private": ["10.0.0.1"]}</programlisting>
      <para>then the value of <literal>the get_attr</literal> function would resolve to <literal>10.0.0.1</literal>
(first item of the <literal>private</literal> entry in the <literal>networks</literal> map).</para>
    </section>
    <section xml:id="get-file">
      <title>get_file</title>
      <para>The <literal>get_file</literal> function returns the content of a file into the template.
It is generally used as a file inclusion mechanism for files
containing scripts or configuration files.</para>
      <para>The syntax of <literal>the get_file</literal> function is:</para>
      <programlisting language="yaml">get_file: &lt;content key&gt;</programlisting>
      <para>The <literal>content key</literal> is used to look up the <literal>files</literal> dictionary that is
provided in the REST API call. The Orchestration client command
(<command>heat</command>) is <literal>get_file</literal> aware and will populate the <literal>files</literal>
dictionary with the actual content of fetched paths and URLs. The
Orchestration client command supports relative paths and will transform these
to the absolute URLs required by the Orchestration API.</para>
      <note>
        <para>The <literal>get_file</literal> argument must be a static path or URL and not rely on
intrinsic functions like <literal>get_param</literal>. the Orchestration client does not
process intrinsic functions (they are only processed by the Orchestration
engine).</para>
      </note>
      <para>The example below demonstrates the <literal>get_file</literal> function usage with both
relative and absolute URLs:</para>
      <programlisting language="yaml">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</programlisting>
      <para>The <literal>files</literal> dictionary generated by the Orchestration client during
instantiation of the stack would contain the following keys:
* <literal>file:///path/to/my_instance_user_data.sh</literal>
* <literal>http://example.com/my_other_instance_user_data.sh*</literal></para>
    </section>
    <section xml:id="get-param">
      <title>get_param</title>
      <para>The <literal>get_param</literal> function references an input parameter of a template. It
resolves to the value provided for this input parameter at runtime.</para>
      <para>The syntax of the <literal>get_param</literal> function is:</para>
      <programlisting language="yaml">get_param:
  - &lt;parameter name&gt;
  - &lt;key/index 1&gt; (optional)
  - &lt;key/index 2&gt; (optional)
  - ...</programlisting>
      <variablelist role="definition_list">
        <varlistentry>
          <term>parameter name</term>
          <listitem>
            <para>The parameter name to be resolved. If the parameters returns a complex data
structure such as a list or a map, then subsequent keys or indexes can be
specified. These additional parameters are used to navigate the data
structure to return the desired value.</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The following example demonstrates the use of the <literal>get_param</literal> function:</para>
      <programlisting language="yaml">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 ] }</programlisting>
      <para>In this example, if the <literal>instance_type</literal> and <literal>server_data</literal> parameters
contained the following data:</para>
      <programlisting language="yaml">{"instance_type": "m1.tiny",
{"server_data": {"metadata": {"foo": "bar"},
                 "keys": ["a_key","other_key"]}}}</programlisting>
      <para>then the value of the property <literal>flavor</literal> would resolve to <literal>m1.tiny</literal>,
<literal>metadata</literal> would resolve to <literal>{"foo": "bar"}</literal> and <literal>key_name</literal> would resolve
to <literal>a_key</literal>.</para>
    </section>
    <section xml:id="get-resource">
      <title>get_resource</title>
      <para>The <literal>get_resource</literal> function references another resource within the
same template. At runtime, it is resolved to reference the ID of the referenced
resource, which is resource type specific. For example, a reference to a
floating IP resource returns the respective IP address at runtime.  The syntax
of the <literal>get_resource</literal> function is:</para>
      <programlisting language="yaml">get_resource: &lt;resource ID&gt;</programlisting>
      <para>The resource ID of the referenced resource is given as single parameter to the
get_resource function.</para>
      <para>For example:</para>
      <programlisting language="yaml">resources:
  instance_port:
    type: OS::Neutron::Port
    properties: ...

  instance:
    type: OS::Nova::Server
    properties:
      ...
      networks:
        port: { get_resource: instance_port }</programlisting>
    </section>
    <section xml:id="list-join">
      <title>list_join</title>
      <para>The <literal>list_join</literal> function joins a list of strings with the given delimiter.</para>
      <para>The syntax of the <literal>list_join</literal> function is:</para>
      <programlisting language="yaml">list_join:
- &lt;delimiter&gt;
- &lt;list to join&gt;</programlisting>
      <para>For example:</para>
      <programlisting language="yaml">list_join: [', ', ['one', 'two', 'and three']]</programlisting>
      <para>This resolve to the string <literal>one, two, and three</literal>.</para>
    </section>
    <section xml:id="resource-facade">
      <title>resource_facade</title>
      <para>The <literal>resource_facade</literal> function retrieves data in a parent provider template.</para>
      <para>A provider template provides a custom definition of a resource, called its
facade. For more information about custom templates, see <xref linkend="composition"/>.
The syntax of the <literal>resource_facade</literal> function is:</para>
      <programlisting language="yaml">resource_facade: &lt;data type&gt;</programlisting>
      <para><literal>data type</literal> can be one of <literal>metadata</literal>, <literal>deletion_policy</literal> or
<literal>update_policy</literal>.</para>
    </section>
    <section xml:id="str-replace">
      <title>str_replace</title>
      <para>The <literal>str_replace</literal> function dynamically constructs 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.</para>
      <para>The syntax of the <literal>str_replace</literal> function is:</para>
      <programlisting language="yaml">str_replace:
  template: &lt;template string&gt;
  params: &lt;parameter mappings&gt;</programlisting>
      <variablelist role="definition_list">
        <varlistentry>
          <term>template</term>
          <listitem>
            <para>Defines the template string that contains placeholders which will be
substituted at runtime.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>params</term>
          <listitem>
            <para>Provides parameter mappings in the form of dictionary. Each key refers to a
placeholder used in the <literal>template</literal> attribute.</para>
          </listitem>
        </varlistentry>
      </variablelist>
      <para>The following example shows a simple use of the <literal>str_replace</literal> function in the
outputs section of a template to build a URL for logging into a deployed
application:</para>
      <programlisting language="yaml">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 ] }</programlisting>
      <para>The following examples show the use of the <literal>str_replace</literal> function to build an
instance initialization script:</para>
      <programlisting language="yaml">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 }</programlisting>
    </section>
  </section>
</section>