22f1952bfe
The XML is generated from the hot-guide RST source and imported manually (see doc/user-guide/hot/README.rst to know how). Fix a broken link in the HOT guide to pass the checklinks gate. Change-Id: I839dd7219189c94930f7166ef921bceba0b9b27b
109 lines
4.9 KiB
XML
109 lines
4.9 KiB
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: 2013-05-23
|
|
|
|
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: 2013-05-23
|
|
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_noya.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">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>
|