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

<?xml version='1.0' encoding='UTF-8'?>
<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="composition">
  <!--WARNING: This file is automatically generated. Do not edit it.-->
  <title>Template composition</title>
  <para>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.</para>
  <para>Template resources provide a feature similar to the
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/AWS__CloudFormation__Stack.html">AWS::CloudFormation::Stack</link></literal> resource, but also provide a way to:</para>
  <itemizedlist>
    <listitem>
      <para>Define new resource types and build your own resource library.</para>
    </listitem>
    <listitem>
      <para>Override the default behaviour of existing resource types.</para>
    </listitem>
  </itemizedlist>
  <para>To achieve this:</para>
  <itemizedlist>
    <listitem>
      <para>The Orchestration client gets the associated template files and passes them
along in the <literal>files</literal> section of the <literal>POST stacks/</literal> API request.</para>
    </listitem>
    <listitem>
      <para>The environment in the Orchestration engine manages the mapping of resource
type to template creation.</para>
    </listitem>
    <listitem>
      <para>The Orchestration engine translates template parameters into resource
properties.</para>
    </listitem>
  </itemizedlist>
  <para>The following examples illustrate how you can use a custom template to define
new types of resources. These examples use a custom template stored in a
<literal>my_nova.yml</literal> file:</para>
  <programlisting language="yaml">heat_template_version: 2014-10-16

parameters:
  key_name:
    type: string
    description: Name of a KeyPair

resources:
  server:
    type: OS::Nova::Server
    properties:
      key_name: {get_param: key_name}
      flavor: m1.small
      image: ubuntu-trusty-x86_64</programlisting>
  <section xml:id="use-the-template-filename-as-type">
    <?dbhtml stop-chunking?>
    <title>Use the template filename as type</title>
    <para>The following template defines the <literal>my_nova.yaml</literal> file as value for the
<literal>type</literal> property of a resource:</para>
    <programlisting language="yaml">heat_template_version: 2014-10-16

resources:
  my_server:
    type: my_nova.yaml
    properties:
      key_name: my_key</programlisting>
    <para>The <literal>key_name</literal> argument of the <literal>my_nova.yaml</literal> template gets its value from
the <literal>key_name</literal> property of the new template.</para>
    <note>
      <para>The above reference to <literal>my_nova.yaml</literal> assumes it is in the same directory.
You can use any of the following forms:</para>
      <itemizedlist>
        <listitem>
          <para>Relative path (<literal>my_nova.yaml</literal>)</para>
        </listitem>
        <listitem>
          <para>Absolute path (<literal>file:///home/user/templates/my_nova.yaml</literal>)</para>
        </listitem>
        <listitem>
          <para>Http URL (<literal>http://example.com/templates/my_nova.yaml</literal>)</para>
        </listitem>
        <listitem>
          <para>Https URL (<literal>https://example.com/templates/my_nova.yaml</literal>)</para>
        </listitem>
      </itemizedlist>
    </note>
    <para>To create the stack run:</para>
    <programlisting language="console">$ heat stack-create -f main.yaml stack1</programlisting>
  </section>
  <section xml:id="define-a-new-resource-type">
    <?dbhtml stop-chunking?>
    <title>Define a new resource type</title>
    <para>You can associate a name to the <literal>my_nova.yaml</literal> template in an environment
file. If the name is already known by the Orchestration module then your new
resource will override the default one.</para>
    <para>In the following example a new <literal>OS::Nova::Server</literal> resource overrides the
default resource of the same name.</para>
    <para>An <literal>env.yaml</literal> environment file holds the definition of the new resource:</para>
    <programlisting language="yaml">resource_registry:
  "OS::Nova::Server": my_nova.yaml</programlisting>
    <note>
      <para>See <xref linkend="environments"/> for more detail about environment files.</para>
    </note>
    <para>You can now use the new <literal>OS::Nova::Server</literal> in your new template:</para>
    <programlisting language="yaml">heat_template_version: 2014-10-16

resources:
  my_server:
    type: OS::Nova::Server
    properties:
      key_name: my_key</programlisting>
    <para>To create the stack run:</para>
    <programlisting language="console">$ heat stack-create -f main.yaml -e env.yaml example-two</programlisting>
  </section>
  <section xml:id="get-access-to-nested-attributes">
    <?dbhtml stop-chunking?>
    <title>Get access to nested attributes</title>
    <para>There are implicit attributes of a template resource. These are
accessible as follows:</para>
    <programlisting language="yaml">heat_template_version: 2014-10-16

resources:
  my_server:
    type: my_nova.yaml

outputs:
  test_out:
    value: {get_attr: my_server, resource.server, first_address}</programlisting>
  </section>
  <section xml:id="making-your-template-resource-more-transparent">
    <?dbhtml stop-chunking?>
    <title>Making your template resource more "transparent"</title>
    <para>If you wish to be able to return the ID of one of the inner resources
instead of the nested stack's identifier, you can add the special reserved
output "OS::stack_id" to your template resource.</para>
    <programlisting language="yaml">heat_template_version: 2014-10-16

resources:
  server:
    type: OS::Nova::Server

outputs:
  OS::stack_id:
    value: {get_resource: server}</programlisting>
    <para>Now when you use "get_resource" from the outer template heat
will use the nova server id and not the template resource identifier.</para>
  </section>
</section>