openstack/openstack-manuals
Code Issues Proposed changes

Include the HOT guide in the user-guide

Browse Source 
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
This commit is contained in:
Gauvain Pocentek 2014-10-31 11:59:59 +01:00
parent d640c97427
commit 22f1952bfe
12 changed files with 2122 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
doc/hot-guide/source/environment.rst
View File

@ -85,7 +85,7 @@ environment file. The resource you provide in this manner must have an
identifier, and references either other resources IDs or the URL of an existing
template file.
The following example maps the new :hotref:`OS::Networking::FloatingIP`
The following example maps the new ``OS::Networking::FloatingIP``
resource to the existing :hotref:`OS::Nova::FloatingIP` resource:
.. code-block:: yaml

1
doc/user-guide/bk-user-guide.xml
View File

@ -145,5 +145,6 @@
<xi:include href="ch_cli.xml"/>
<xi:include href="ch_sdk.xml"/>
<xi:include href="app_cheat_sheet.xml"/>
<xi:include href="hot/index.xml"/>
<xi:include href="../common/app_support.xml"/>
</book>

8
doc/user-guide/hot/README.rst Normal file
View File

@ -0,0 +1,8 @@
**The contents of this directory are autogenerated - do NOT modify these files,
your changes will be lost on the next update.**
To generate the files::
cd doc/hot-guide
make xml
openstack-dn2osdbk --toplevel chapter build/xml ../user-guide/hot

17
doc/user-guide/hot/index.xml Normal file
View File

@ -0,0 +1,17 @@
<?xml version="1.0" encoding="UTF-8"?>
<chapter 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-guide">
<!-- WARNING: This file is automatically generated. Do not edit it. -->
<title>HOT guide</title>
<xi:include href="section_hello_world.xml"/>
<xi:include href="section_hot_spec.xml"/>
<xi:include href="section_basic_resources.xml"/>
<xi:include href="section_software_deployment.xml"/>
<xi:include href="section_environment.xml"/>
<xi:include href="section_composition.xml"/>
</chapter>

33
doc/user-guide/hot/section_advanced_topics.xml Normal file
View File

@ -0,0 +1,33 @@
<?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="hot-advanced-topics">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Advanced topics</title>
<section xml:id="networking">
<?dbhtml stop-chunking?>
<title>Networking</title>
<section xml:id="load-balancer">
<title>Load balancer</title>
<para>TODO</para>
</section>
<section xml:id="firewall">
<title>Firewall</title>
<para>TODO</para>
</section>
<section xml:id="vpn">
<title>VPN</title>
<para>TODO</para>
</section>
</section>
<section xml:id="auto-scaling">
<?dbhtml stop-chunking?>
<title>Auto scaling</title>
<section xml:id="alarming">
<title>Alarming</title>
<para>TODO</para>
</section>
<section xml:id="up-scaling-and-down-scaling">
<title>Up scaling and down scaling</title>
<para>TODO</para>
</section>
</section>
</section>

401
doc/user-guide/hot/section_basic_resources.xml Normal file
View File

@ -0,0 +1,401 @@
<?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="hot-basic-resources">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Instances</title>
<!--For consistency let's define a few values to use in the samples:
* image name: ubuntu-trusty-x86_64
* shared/provider network name: "public"
* tenant network and subnet names: "private" and "private-subnet"-->
<section xml:id="manage-instances">
<?dbhtml stop-chunking?>
<title>Manage instances</title>
<section xml:id="create-an-instance">
<title>Create an instance</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> resource to create a Compute instance. The
<literal>flavor</literal> property is the only mandatory one, but you need to define a boot
source using one of the <literal>image</literal> or <literal>block_device_mapping</literal> properties.</para>
<para>You also need to define the <literal>networks</literal> property to indicate to which networks
your instance must connect if multiple networks are available in your tenant.</para>
<para>The following example creates a simple instance, booted from an image, and
connecting to the <literal>private</literal> network:</para>
<programlisting language="yaml">resources:
instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: private</programlisting>
</section>
<section xml:id="connect-an-instance-to-a-network">
<title>Connect an instance to a network</title>
<para>Use the <literal>networks</literal> property of an <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> resource to
define which networks an instance should connect to. Define each network as a
YAML map, containing one of the following keys:</para>
<variablelist role="definition_list">
<varlistentry>
<term>
<literal>port</literal>
</term>
<listitem>
<para>The ID of an existing Networking port. You usually create this port in the
same template using an <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Port.html">OS::Neutron::Port</link></literal> resource. You will be
able to associate a floating IP to this port, and the port to your Compute
instance.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>network</literal>
</term>
<listitem>
<para>The name or ID of an existing network. You don't need to create an
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Port.html">OS::Neutron::Port</link></literal> resource if you use this property, but you will
not be able to associate a floating IP with the instance interface in the
template.</para>
</listitem>
</varlistentry>
</variablelist>
<para>The following example demonstrates the use of the <literal>port</literal> and <literal>network</literal>
properties:</para>
<programlisting language="yaml">resources:
instance_port:
type: OS::Neutron::Port
properties:
network: private
fixed_ips:
- subnet_id: "private-subnet"
instance1:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- port: { get_resource: instance_port }
instance2:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: private</programlisting>
</section>
<section xml:id="create-and-associate-security-groups-to-an-instance">
<title>Create and associate security groups to an instance</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__SecurityGroup.html">OS::Neutron::SecurityGroup</link></literal> resource to create security
groups.</para>
<para>Define the <literal>security_groups</literal> property of the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Port.html">OS::Neutron::Port</link></literal>
resource to associate security groups to a port, then associate the port to an
instance.</para>
<para>The following example creates a security group allowing inbound connections on
ports 80 and 443 (web server) and associates this security group to an instance
port:</para>
<programlisting language="yaml">resources:
web_secgroup:
type: OS::Neutron::SecurityGroup
properties:
rules:
- protocol: tcp
remote_ip_prefix: 0.0.0.0/0
port_range_min: 80
port_range_max: 80
- protocol: tcp
remote_ip_prefix: 0.0.0.0/0
port_range_min: 443
port_range_max: 443
instance_port:
type: OS::Neutron::Port
properties:
network: private
security_groups:
- default
- { get_resource: web_secgroup }
fixed_ips:
- subnet_id: private-subnet
instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- port: { get_resource: instance_port }</programlisting>
</section>
<section xml:id="create-and-associate-a-floating-ip-to-an-instance">
<title>Create and associate a floating IP to an instance</title>
<para>You can use two sets of resources to create and associate floating IPs to
instances.</para>
<section xml:id="os-nova-resources">
<title>OS::Nova resources</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__FloatingIP.html">OS::Nova::FloatingIP</link></literal> resource to create a floating IP, and
the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__FloatingIPAssociation.html">OS::Nova::FloatingIPAssociation</link></literal> resource to associate the
floating IP to an instance.</para>
<para>The following example creates an instance and a floating IP, and associate the
floating IP to the instance:</para>
<programlisting language="yaml">resources:
floating_ip:
type: OS::Nova::FloatingIP
properties:
pool: public
inst1:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
networks:
- network: private
association:
type: OS::Nova::FloatingIPAssociation
properties:
- floating_ip: { get_resource: floating_ip }
- server_id: { get_resource: instance }</programlisting>
</section>
<section xml:id="os-neutron-resources">
<title>OS::Neutron resources</title>
<note>
<para>The Networking service (neutron) must be enabled on your OpenStack
deployment to use these resources.</para>
</note>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__FloatingIP.html">OS::Neutron::FloatingIP</link></literal> resource to create a floating IP, and
the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__FloatingIPAssociation.html">OS::Neutron::FloatingIPAssociation</link></literal> resource to associate the
floating IP to a port:</para>
<programlisting language="yaml">resources:
instance_port:
type: OS::Neutron::Port
properties:
network: private
fixed_ips:
- subnet_id: "private-subnet"
floating_ip:
type: OS::Neutron::FloatingIP
properties:
floating_network: public
port_id: { get_resource: instance_port }
association:
type: OS::Neutron::FloatingIPAssociation
properties:
floatingip_id: { get_resource: floating_ip }
port_id: { get_resource: instance_port }</programlisting>
</section>
</section>
<section xml:id="enable-remote-access-to-an-instance">
<title>Enable remote access to an instance</title>
<para>The <literal>key_name</literal> attribute of the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> resource defines
the key pair to use to enable SSH remote access:</para>
<programlisting language="yaml">resources:
my_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
key_name: my_key</programlisting>
<note>
<para>For more information about key pairs, see the <link xlink:href="http://docs.openstack.org/user-guide/content/cli_configure_instances.html">Configure access and
security for instances</link> section of the OpenStack user guide.</para>
</note>
</section>
<section xml:id="create-a-key-pair">
<title>Create a key pair</title>
<para>You can create new key pairs with the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__KeyPair.html">OS::Nova::KeyPair</link></literal> resource. Key
pairs can be imported or created during the stack creation.</para>
<para>If the <literal>public_key</literal> property is not specified, the Orchestration module
creates a new key pair. If the <literal>save_private_key</literal> property is set to
<literal>true</literal>, the <literal>private_key</literal> attribute of the resource holds the private key.</para>
<para>The following example creates a new key pair and uses it as authentication key
for an instance:</para>
<programlisting language="yaml">resources:
my_key:
type: OS::Nova::KeyPair
properties:
save_private_key: true
my_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
key_name: { get_resource: my_key }
outputs:
private_key:
description: Private key
value: { get_attr: [ my_key, private_key ] }</programlisting>
</section>
</section>
<section xml:id="manage-networks">
<?dbhtml stop-chunking?>
<title>Manage networks</title>
<section xml:id="create-a-network-and-a-subnet">
<title>Create a network and a subnet</title>
<note>
<para>The Networking service (neutron) must be enabled on your OpenStack
deployment to create and manage networks and subnets. Networks and subnets
cannot be created if your deployment uses legacy networking (nova-network).</para>
</note>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Net.html">OS::Neutron::Net</link></literal> resource to create a network, and the
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Subnet.html">OS::Neutron::Subnet</link></literal> resource to provide a subnet for this network:</para>
<programlisting language="yaml">resources:
new_net:
type: OS::Neutron::Net
new_subnet:
type: OS::Neutron::Subnet
properties:
network_id: { get_resource: new_net }
cidr: "10.8.1.0/24"
dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
ip_version: 4</programlisting>
</section>
<section xml:id="create-and-manage-a-router">
<title>Create and manage a router</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__Router.html">OS::Neutron::Router</link></literal> resource to create a router. You can
define its gateway with the <literal>external_gateway_info</literal> property:</para>
<programlisting language="yaml">resources:
router1:
type: OS::Neutron::Router
properties:
external_gateway_info: { network: public }</programlisting>
<para>You can connect subnets to routers with the
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Neutron__RouterInterface.html">OS::Neutron::RouterInterface</link></literal> resource:</para>
<programlisting language="yaml">resources:
subnet1_interface:
type: OS::Neutron::RouterInterface
properties:
router_id: { get_resource: router1 }
subnet: private-subnet</programlisting>
</section>
<section xml:id="complete-network-example">
<title>Complete network example</title>
<para>The following example creates a network stack:</para>
<itemizedlist>
<listitem>
<para>A network and an associated subnet.</para>
</listitem>
<listitem>
<para>A router with an external gateway.</para>
</listitem>
<listitem>
<para>An interface to the new subnet for the new router.</para>
</listitem>
</itemizedlist>
<para>In this example, the <literal>public</literal> network is an existing shared network:</para>
<programlisting language="yaml">resources:
internal_net:
type: OS::Neutron::Net
internal_subnet:
type: OS::Neutron::Subnet
properties:
network_id: { get_resource: internal_net }
cidr: "10.8.1.0/24"
dns_nameservers: [ "8.8.8.8", "8.8.4.4" ]
ip_version: 4
internal_router:
type: OS::Neutron::Router
properties:
external_gateway_info: { network: public }
internal_interface:
type: OS::Neutron::RouterInterface
properties:
router_id: { get_resource: internal_router }
subnet: { get_resource: internal_subnet }</programlisting>
</section>
</section>
<section xml:id="manage-volumes">
<?dbhtml stop-chunking?>
<title>Manage volumes</title>
<section xml:id="create-a-volume">
<title>Create a volume</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Cinder__Volume.html">OS::Cinder::Volume</link></literal> resource to create a new Block Storage
volume.</para>
<para>For example:</para>
<programlisting language="yaml">resources:
my_new_volume:
type: OS::Cinder::Volume
properties:
size: 10</programlisting>
<para>The volumes that you create are empty by default. Use the <literal>image</literal> property to
create a bootable volume from an existing image:</para>
<programlisting language="yaml">resources:
my_new_bootable_volume:
type: OS::Cinder::Volume
properties:
size: 10
image: ubuntu-trusty-x86_64</programlisting>
<para>You can also create new volumes from another volume, a volume snapshot, or a
volume backup. Use the <literal>source_volid</literal>, <literal>snapshot_id</literal> or <literal>backup_id</literal>
properties to create a new volume from an existing source.</para>
<para>For example, to create a new volume from a backup:</para>
<programlisting language="yaml">resources:
another_volume:
type: OS::Cinder::Volume
properties:
backup_id: 2fff50ab-1a9c-4d45-ae60-1d054d6bc868</programlisting>
<para>In this example the <literal>size</literal> property is not defined because the Block Storage
service uses the size of the backup to define the size of the new volume.</para>
</section>
<section xml:id="attach-a-volume-to-an-instance">
<title>Attach a volume to an instance</title>
<para>Use the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Cinder__VolumeAttachment.html">OS::Cinder::VolumeAttachment</link></literal> resource to attach a volume to
an instance.</para>
<para>The following example creates a volume and an instance, and attaches the volume
to the instance:</para>
<programlisting language="yaml">resources:
new_volume:
type: OS::Cinder::Volume
properties:
size: 1
new_instance:
type: OS::Nova::Server
properties:
flavor: m1.small
image: ubuntu-trusty-x86_64
volume_attachment:
type: OS::Cinder::VolumeAttachment
properties:
volume_id: { get_resource: new_volume }
instance_uuid: { get_resource: new_instance }</programlisting>
</section>
<section xml:id="boot-an-instance-from-a-volume">
<title>Boot an instance from a volume</title>
<para>Use the <literal>block_device_mapping</literal> property of the <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal>
resource to define a volume used to boot the instance. This property is a list
of volumes to attach to the instance before its boot.</para>
<para>The following example creates a bootable volume from an image, and uses it to
boot an instance:</para>
<programlisting language="yaml">resources:
bootable_volume:
type: OS::Cinder::Volume
properties:
size: 10
image: ubuntu-trusty-x86_64
instance:
type: OS::Nova::Server
properties:
flavor: m1.small
networks:
- network: private
block_device_mapping:
- device_name: vda
volume_id: { get_resource: bootable_volume }
delete_on_termination: false</programlisting>
<!--TODO
A few elements that probably belong here:
- OS::Swift::Container
- OS::Trove::Instance-->
</section>
</section>
</section>

108
doc/user-guide/hot/section_composition.xml Normal file
View File

@ -0,0 +1,108 @@
<?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>

108
doc/user-guide/hot/section_environment.xml Normal file
View File

@ -0,0 +1,108 @@
<?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="environments">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Environments</title>
<para>The environment affects the runtime behaviour of a template. It provides a way
to override the resource implementations and a mechanism to place parameters
that the service needs.</para>
<para>To fully understand the runtime behavior you have to consider what plug-ins are
installed on the cloud you're using.</para>
<section xml:id="environment-file-format">
<?dbhtml stop-chunking?>
<title>Environment file format</title>
<para>The environment is a yaml text file that contains two main sections:</para>
<variablelist role="definition_list">
<varlistentry>
<term>
<literal>parameters</literal>
</term>
<listitem>
<para>A map of key/pair values.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>
<literal>resource_registry</literal>
</term>
<listitem>
<para>Definition of custom resources.</para>
</listitem>
</varlistentry>
</variablelist>
<para>Use the -e option of the <command>heat stack-create</command> command to
create a stack using with the environment defined in such a file.</para>
<para>You can also provide environment parameters as a list of key/value pairs using
the -P option of the <command>heat stack-create</command> command.</para>
<para>In the following example the environment is read from the <literal>my_env.yaml</literal>
file and an extra parameter is provided using the -P option:</para>
<programlisting language="console">$ heat stack-create my_stack -e my_env.yaml -P "param1=val1;param2=val2" -f my_tmpl.yaml</programlisting>
</section>
<section xml:id="global-and-effective-environments">
<?dbhtml stop-chunking?>
<title>Global and effective environments</title>
<para>The environment used for a stack is the combination of the environment you
use with the template for the stack, and a global environment that is
determined by your cloud operator. An entry in the user environment takes
precedence over the global environment. OpenStack includes a default global
environment, but you cloud operator can add additional environment entries.</para>
<!--TODO:
move this to a heat section in the admin-guide-cloud
The cloud operator can add to the global environment
by putting environment files in a configurable directory wherever
the Orchestration engine runs. The configuration variable is named
"environment_dir" is found in the "[DEFAULT]" section
of "/etc/heat/heat.conf". The default for that directory is
"/etc/heat/environment.d". Its contents are combined in whatever
order the shell delivers them when the service starts up,
which is the time when these files are read.
If the "my_env.yaml" file from the example above had been put in the
"environment_dir" then the user's command line could be this:
::
heat stack-create my_stack -P "some_parm=bla" -f my_tmpl.yaml-->
</section>
<section xml:id="define-values-for-a-template-arguments">
<?dbhtml stop-chunking?>
<title>Define values for a template arguments</title>
<para>You can define values for the template arguments in the <literal>parameters</literal> section
of an environment file:</para>
<programlisting language="yaml">parameters:
KeyName: my_keypair
InstanceType: m1.tiny
ImageId: F18-x86_64-cfntools</programlisting>
</section>
<section xml:id="create-and-override-resources">
<?dbhtml stop-chunking?>
<title>Create and override resources</title>
<para>You can create or override resources in the <literal>resource_registry</literal> section of an
environment file. The resource you provide in this manner must have an
identifier, and references either other resources IDs or the URL of an existing
template file.</para>
<para>The following example maps the new <literal>OS::Networking::FloatingIP</literal>
resource to the existing <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__FloatingIP.html">OS::Nova::FloatingIP</link></literal> resource:</para>
<programlisting language="yaml">resource_registry:
"OS::Networking::FloatingIP": "OS::Nova::FloatingIP"</programlisting>
<para>You can use wilcards to map multiple resources:</para>
<programlisting language="yaml">resource_registry:
"OS::Network*": "OS::Neutron*"</programlisting>
<para>To create or override a resource with a custom resource, create a template file
to define this resource, and provide the URL to the template file in the
environment file:</para>
<programlisting language="yaml">resource_registry:
"AWS::EC2::Instance": file:///path/to/my_instance.yaml</programlisting>
<para>The supported URL scheme are <literal>file</literal>, <literal>http</literal> and <literal>https</literal>.</para>
<note>
<para>The template file extension must be <literal>.yaml</literal> or <literal>.template</literal>, or it will
not be treated as a custom template resource.</para>
</note>
<para>You can limit the usage of a custom resource to a specific resource of the
template:</para>
<programlisting language="yaml">resource_registry:
resources:
my_db_server:
"OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml</programlisting>
</section>
</section>

77
doc/user-guide/hot/section_functions.xml Normal file
View File

@ -0,0 +1,77 @@
<?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="hot-functions">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>HOT functions</title>
<section xml:id="link-between-resources">
<?dbhtml stop-chunking?>
<title>Link between resources</title>
<itemizedlist>
<listitem>
<para>get_param</para>
</listitem>
<listitem>
<para>get_resource</para>
</listitem>
<listitem>
<para>Ref</para>
</listitem>
<listitem>
<para>Fn::GetAtt / get_attr</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="string-manipulations">
<?dbhtml stop-chunking?>
<title>String manipulations</title>
<itemizedlist>
<listitem>
<para>get_file</para>
</listitem>
<listitem>
<para>list_join</para>
</listitem>
<listitem>
<para>str_replace</para>
</listitem>
<listitem>
<para>Fn::Base64</para>
</listitem>
<listitem>
<para>Fn::Join</para>
</listitem>
<listitem>
<para>Fn::Split</para>
</listitem>
<listitem>
<para>Fn::Replace</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="lookup-structured-data">
<?dbhtml stop-chunking?>
<title>Lookup structured data</title>
<itemizedlist>
<listitem>
<para>Fn::FindInMap</para>
</listitem>
<listitem>
<para>Fn::MemberListToMap</para>
</listitem>
<listitem>
<para>Fn::Select</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="misc">
<?dbhtml stop-chunking?>
<title>Misc</title>
<itemizedlist>
<listitem>
<para>Fn::ResourceFacade / resource_facade</para>
</listitem>
<listitem>
<para>Fn::GetAZs</para>
</listitem>
</itemizedlist>
</section>
</section>

185
doc/user-guide/hot/section_hello_world.xml Normal file
View File

@ -0,0 +1,185 @@
<?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="hello-world">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Writing a hello world HOT template</title>
<para>HOT is a new template format meant to replace the CloudFormation-compatible
format (CFN) as the native format supported by the Orchestration module over
time.
This guide is targeted towards template authors and explains how to write
HOT templates based on examples. A detailed specification of HOT can be found
at <xref linkend="hot-spec"/>.</para>
<para>This section gives an introduction on how to write HOT templates, starting from
very basic steps and then going into more and more detail by means of examples.</para>
<section xml:id="a-most-basic-template">
<?dbhtml stop-chunking?>
<title>A most basic template</title>
<para>The most basic template you can think of contains only a single resource
definition using only predefined properties. For example, the template below
could be used to deploy a single compute instance:</para>
<programlisting language="yaml">heat_template_version: 2013-05-23
description: Simple template to deploy a single compute instance
resources:
my_instance:
type: OS::Nova::Server
properties:
key_name: my_key
image: ubuntu-trusty-x86_64
flavor: m1.small</programlisting>
<para>Each HOT template has to include the <literal>heat_template_version</literal> key with value
<literal>2013-05-23</literal>, the current HOT version. While the <literal>description</literal> key is
optional, it is good practice to include some useful text that describes what
users can do with the template. In case you want to provide a longer
description that does not fit on a single line, you can provide multi-line text
in YAML, for example:</para>
<programlisting language="yaml">description: &gt;
This is how you can provide a longer description
of your template that goes over several lines.</programlisting>
<para>The <literal>resources</literal> section is required and must contain at least one resource
definition. In the above example, a compute instance is defined with fixed
values for the <literal>key_name</literal>, <literal>image</literal> and <literal>flavor</literal> properties.</para>
<note>
<para>All the defined elements (key pair, image, flavor) have to exist in the
OpenStack environment where the template is used.</para>
</note>
</section>
<section xml:id="input-parameters">
<?dbhtml stop-chunking?>
<title>Input parameters</title>
<para>Input parameters defined in the <literal>parameters</literal> section of a template
allow users to customize a template during deployment. For example, this allows
for providing custom key pair names or image IDs to be used for a deployment.
From a template author's perspective, this helps to make a template more easily
reusable by avoiding hardcoded assumptions.</para>
<para>The following example extends the previous template to provide parameters for
the key pair, image and flavor properties of the resource:</para>
<programlisting language="yaml">heat_template_version: 2013-05-23
description: Simple template to deploy a single compute instance
parameters:
key_name:
type: string
label: Key Name
description: Name of key-pair to be used for compute instance
image_id:
type: string
label: Image ID
description: Image to be used for compute instance
flavor:
type: string
label: Instance Type
description: Type of instance (flavor) to be used
resources:
my_instance:
type: OS::Nova::Server
properties:
key_name: { get_param: key_name }
image: { get_param: image_id }
flavor: { get_param: flavor }</programlisting>
<para>Values for the three parameters must be defined by the template user during the
deployment of a stack. The <literal>get_param</literal> intrinsic function retrieves a
user-specified value for a given parameter and uses this value for the
associated resource property.</para>
<para>For more information about intrinsic functions, see
<xref linkend="hot-spec-intrinsic-functions"/>.</para>
<section xml:id="providing-default-values">
<title>Providing default values</title>
<para>You can provide default values for parameters. If a user doesn't define a value
for a parameter, the default value is used during the stack deployment. The
following example defines a default value <literal>m1.small</literal> for the
<literal>flavor</literal> property:</para>
<programlisting language="yaml">parameters:
flavor:
type: string
label: Instance Type
description: Flavor to be used
default: m1.small</programlisting>
<note>
<para>If a template doesn't define a default value for a parameter, then the user
must define the value, otherwise the stack creation will fail.</para>
</note>
</section>
<section xml:id="hidding-parameters-values">
<title>Hidding parameters values</title>
<para>The values that a user provides when deploying a stack are available in the
stack details and can be accessed by any user in the same tenant. To hide the
value of a parameter, use the <literal>hidden</literal> boolean attribute of the parameter:</para>
<programlisting language="yaml">parameters:
database_password:
type: string
label: Database Password
description: Password to be used for database
hidden: true</programlisting>
</section>
<section xml:id="restricting-user-input">
<title>Restricting user input</title>
<para>You can restrict the values of an input parameter to make sure that the user
defines valid data for this parameter. The <literal>constraints</literal> property of an input
parameter defines a list of constraints to apply for the parameter.
The following example restricts the <literal>flavor</literal> parameter to a list of three
possible values:</para>
<programlisting language="yaml">parameters:
flavor:
type: string
label: Instance Type
description: Type of instance (flavor) to be used
constraints:
- allowed_values: [ m1.medium, m1.large, m1.xlarge ]
description: Value must be one of m1.medium, m1.large or m1.xlarge.</programlisting>
<para>The following example defines multiple contraints for a password definition:</para>
<programlisting language="yaml">parameters:
database_password:
type: string
label: Database Password
description: Password to be used for database
hidden: true
constraints:
- length: { min: 6, max: 8 }
description: Password length must be between 6 and 8 characters.
- allowed_pattern: "[a-zA-Z0-9]+"
description: Password must consist of characters and numbers only.
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
description: Password must start with an uppercase character.</programlisting>
<para>The list of supported constraints is available in the
<xref linkend="hot-spec-parameters-constraints"/> section.</para>
<note>
<para>You can define multiple constraints of the same type. Especially in the
case of allowed patterns this not only allows for keeping regular
expressions simple and maintainable, but also for keeping error messages to
be presented to users precise.</para>
</note>
</section>
</section>
<section xml:id="template-outputs">
<?dbhtml stop-chunking?>
<title>Template outputs</title>
<para>In addition to template customization through input parameters, you can
provide information about the resources created during the stack deployment to
the users in the <literal>outputs</literal> section of a template. In the following example
the output section provides the IP address of the <literal>my_instance</literal> resource:</para>
<programlisting language="yaml">outputs:
instance_ip:
description: The IP address of the deployed instance
value: { get_attr: [my_instance, first_address] }</programlisting>
<note>
<para>Output values are typically resolved using intrinsic function such as
the <literal>get_attr</literal>. See <xref linkend="hot-spec-intrinsic-functions"/> for more information
about intrinsic functions..</para>
</note>
<para>See <xref linkend="hot-spec-outputs"/> for more information about the <literal>outputs</literal> section.</para>
</section>
</section>

784
doc/user-guide/hot/section_hot_spec.xml Normal file
View File

@ -0,0 +1,784 @@
<?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
contrainsts at instantiation time. The contrainsts 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 ommitted, 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>
dictionnary 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 Orcestration 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 exemple:</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 provdes 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>

399
doc/user-guide/hot/section_software_deployment.xml Normal file
View File

@ -0,0 +1,399 @@
<?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="hot-software-deployment">
<!--WARNING: This file is automatically generated. Do not edit it.-->
<title>Software configuration</title>
<para>There are a variety of options to configure the software which runs on the
servers in your stack. These can be broadly divided into the following:</para>
<itemizedlist>
<listitem>
<para>Custom image building</para>
</listitem>
<listitem>
<para>User-data boot scripts and cloud-init</para>
</listitem>
<listitem>
<para>Software deployment resources</para>
</listitem>
</itemizedlist>
<para>This section will describe each of these options and provide examples for
using them together in your stacks.</para>
<section xml:id="image-building">
<?dbhtml stop-chunking?>
<title>Image building</title>
<para>The first opportunity to influence what software is configured on your servers
is by booting them with a custom-built image. There are a number of reasons
you might want to do this, including:</para>
<itemizedlist>
<listitem>
<para><emphasis role="Boot speed"/> - since the required software is already on the image there
is no need to download and install anything at boot time.</para>
</listitem>
<listitem>
<para><emphasis role="Boot reliability"/> - software downloads can fail for a number of reasons
including transient network failures and inconsistent software repositories.</para>
</listitem>
<listitem>
<para><emphasis role="Test verification"/> - custom built images can be verified in test
environments before being promoted to production.</para>
</listitem>
<listitem>
<para><emphasis role="Configuration dependencies"/> - post-boot configuration may depend on
agents already being installed and enabled</para>
</listitem>
</itemizedlist>
<para>A number of tools are available for building custom images, including:</para>
<itemizedlist>
<listitem>
<para><link xlink:href="https://github.com/openstack/diskimage-builder">diskimage-builder</link> image building tools for OpenStack</para>
</listitem>
<listitem>
<para><link xlink:href="http://imgfac.org/">imagefactory</link> builds images for a variety of operating system/cloud
combinations</para>
</listitem>
</itemizedlist>
<para>Examples in this guide which require custom images will use
<link xlink:href="https://github.com/openstack/diskimage-builder">diskimage-builder</link>.</para>
</section>
<section xml:id="user-data-boot-scripts-and-cloud-init">
<?dbhtml stop-chunking?>
<title>User-data boot scripts and cloud-init</title>
<para>When booting a server it is possible to specify the contents of the user-data
to be passed to that server. This user-data is made available either from
configured config-drive or from the <link xlink:href="http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html">Metadata service</link>.</para>
<para>How this user-data is consumed depends on the image being booted, but the most
commonly used tool for default cloud images is <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link>.</para>
<para>Whether the image is using <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link> or not, it should be possible to
specify a shell script in the user_data property and have it be executed by
the server during boot:</para>
<programlisting language="yaml">resources:
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data: |
#!/bin/bash
echo "Running boot script"
# ...</programlisting>
<!---->
<blockquote>
<para><emphasis role="Tip"/>: debugging these scripts it is often useful to view the boot
log using <literal>nova console-log &lt;server-id&gt;</literal> to view the progress of boot
script execution.</para>
</blockquote>
<para>Often there is a need to set variable values based on parameters or resources
in the stack. This can be done with the <literal>str_replace</literal> intrinsic function:</para>
<programlisting language="yaml">parameters:
foo:
default: bar
resources:
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data:
str_replace:
template: |
#!/bin/bash
echo "Running boot script with $FOO"
# ...
params:
$FOO: {get_param: foo}</programlisting>
<!---->
<blockquote>
<para><emphasis role="Warning"/>: If a stack-update is performed and there are any changes
at all to the content of user_data then the server will be replaced
(deleted and recreated) so that the modified boot configuration can be
run on a new server.</para>
</blockquote>
<para>When these scripts grow it can become difficult to maintain them inside the
template, so the <literal>get_file</literal> intrinsic function can be used to maintain the
script in a separate file:</para>
<programlisting language="yaml">parameters:
foo:
default: bar
resources:
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data:
str_replace:
template: {get_file: the_server_boot.sh}
params:
$FOO: {get_param: foo}</programlisting>
<!---->
<blockquote>
<para><emphasis role="Tip"/>: <literal>str_replace</literal> can replace any strings, not just strings
starting with <literal>$</literal>. However doing this for the above example is useful
because the script file can be executed for testing by passing in
environment variables.</para>
</blockquote>
<section xml:id="choosing-the-user-data-format">
<title>Choosing the user_data_format</title>
<para>The <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Nova__Server.html">OS::Nova::Server</link></literal> user_data_format property determines how the
user_data should be formatted for the server. For the default value
<literal>HEAT_CFNTOOLS</literal>, the user_data is bundled as part of the heat-cfntools
cloud-init boot configuration data. While <literal>HEAT_CFNTOOLS</literal> is the default
for <literal>user_data_format</literal>, it is considered legacy and <literal>RAW</literal> or
<literal>SOFTWARE_CONFIG</literal> will generally be more appropriate.</para>
<para>For <literal>RAW</literal> the user_data is passed to Nova unmodified. For a <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link>
enabled image, the following are both valid <literal>RAW</literal> user-data:</para>
<programlisting language="yaml">resources:
server_with_boot_script:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: |
#!/bin/bash
echo "Running boot script"
# ...
server_with_cloud_config:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: |
#cloud-config
final_message: "The system is finally up, after $UPTIME seconds"</programlisting>
<para>For <literal>SOFTWARE_CONFIG</literal> user_data is bundled as part of the software config
data, and metadata is derived from any associated software deployment
resources.</para>
</section>
<section xml:id="signals-and-wait-conditions">
<title>Signals and wait conditions</title>
<para>Often it is necessary to pause further creation of stack resources until the
boot configuration script has notified that it has reached a certain state.
This is usually either to notify that a service is now active, or to pass out
some generated data which is needed by another resource. The resources
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__WaitCondition.html">OS::Heat::WaitCondition</link></literal> and <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SwiftSignal.html">OS::Heat::SwiftSignal</link></literal> both perform
this function using different techniques and tradeoffs.</para>
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__WaitCondition.html">OS::Heat::WaitCondition</link></literal> is implemented as a call to the
<link xlink:href="http://developer.openstack.org/api-ref-orchestration-v1.html">Orchestration API</link> resource signal. The token is created using credentials
for a user account which is scoped only to the wait condition handle
resource. This user is created when the handle is created, and is associated
to a project which belongs to the stack, in an identity domain which is
dedicated to the orchestration service.</para>
<para>Sending the signal is a simple HTTP request, as with this example using <link xlink:href="http://curl.haxx.se/">curl</link>:</para>
<programlisting language="sh">curl -i -X POST -H 'X-Auth-Token: &lt;token&gt;' \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
'&lt;wait condition URL&gt;' --data-binary '&lt;json containing signal data&gt;'</programlisting>
<para>The JSON containing the signal data is expected to be of the following format:</para>
<programlisting language="json">{
"status": "SUCCESS",
"reason": "The reason which will appear in the 'heat event-list' output",
"data": "Data to be used elsewhere in the template via get_attr",
"id": "Optional unique ID of signal"
}</programlisting>
<para>All of these values are optional, and if not specified will be set to the
following defaults:</para>
<programlisting language="json">{
"status": "SUCCESS",
"reason": "Signal &lt;id&gt; received",
"data": null,
"id": "&lt;sequential number starting from 1 for each signal received&gt;"
}</programlisting>
<para>If <literal>status</literal> is set to <literal>FAILURE</literal> then the resource (and the stack) will go
into a <literal>FAILED</literal> state using the <literal>reason</literal> as failure reason.</para>
<para>The following template example uses the convenience attribute <literal>curl_cli</literal>
which builds a curl command with a valid token:</para>
<programlisting language="yaml">resources:
wait_condition:
type: OS::Heat::WaitCondition
properties:
handle: {get_resource: wait_handle}
# Note, count of 5 vs 6 is due to duplicate signal ID 5 sent below
count: 5
timeout: 300
wait_handle:
type: OS::Heat::WaitConditionHandle
the_server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data:
str_replace:
template: |
#!/bin/sh
# Below are some examples of the various ways signals
# can be sent to the Handle resource
# Simple success signal
wc_notify --data-binary '{"status": "SUCCESS"}'
# Or you optionally can specify any of the additional fields
wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal2"}'
wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal3", "data": "data3"}'
wc_notify --data-binary '{"status": "SUCCESS", "reason": "signal4", "data": "data4"}'
# If you require control of the ID, you can pass it.
# The ID should be unique, unless you intend for duplicate
# signals to overrite each other. The following two calls
# do the exact same thing, and will be treated as one signal
# (You can prove this by changing count above to 7)
wc_notify --data-binary '{"status": "SUCCESS", "id": "5"}'
wc_notify --data-binary '{"status": "SUCCESS", "id": "5"}'
# Example of sending a failure signal, optionally
# reason, id, and data can be specified as above
# wc_notify --data-binary '{"status": "FAILURE"}'
params:
wc_notify: { get_attr: [wait_handle, curl_cli] }
outputs:
wc_data:
value: { get_attr: [wait_condition, data] }
# this would return the following json
# {"1": null, "2": null, "3": "data3", "4": "data4", "5": null}
wc_data_4:
value: { get_attr: [wait_condition, data, '4'] }
# this would return "data4"</programlisting>
<!---->
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SwiftSignal.html">OS::Heat::SwiftSignal</link></literal> is implemented by creating an Object Storage
API temporary URL which is populated with signal data with an HTTP PUT. The
orchestration service will poll this object until the signal data is available.
Object versioning is used to store multiple signals.</para>
<para>Sending the signal is a simple HTTP request, as with this example using <link xlink:href="http://curl.haxx.se/">curl</link>:</para>
<programlisting language="sh">curl -i -X PUT '&lt;object URL&gt;' --data-binary '&lt;json containing signal data&gt;'</programlisting>
<para>The above template example only needs to have the <literal>type</literal> changed to the
swift signal resources:</para>
<programlisting language="yaml">resources:
signal:
type: OS::Heat::SwiftSignal
properties:
handle: {get_resource: wait_handle}
timeout: 300
signal_handle:
type: OS::Heat::SwiftSignalHandle
# ...</programlisting>
<para>The decision to use <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__WaitCondition.html">OS::Heat::WaitCondition</link></literal> or
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SwiftSignal.html">OS::Heat::SwiftSignal</link></literal> will depend on a few factors:</para>
<itemizedlist>
<listitem>
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SwiftSignal.html">OS::Heat::SwiftSignal</link></literal> depends on the availability of an Object
Storage API</para>
</listitem>
<listitem>
<para><literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__WaitCondition.html">OS::Heat::WaitCondition</link></literal> depends on whether the orchestration
service has been configured with a dedicated stack domain (which may depend
on the availability of an Identity V3 API).</para>
</listitem>
<listitem>
<para>The preference to protect signal URLs with token authentication or a
secret webhook URL.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="software-config-resources">
<title>Software config resources</title>
<para>Boot configuration scripts can also be managed as their own resources. This
allows configuration to be defined once and run on multiple server resources.
These software-config resources are stored and retrieved via dedicated calls
to the <link xlink:href="http://developer.openstack.org/api-ref-orchestration-v1.html">Orchestration API</link>. It is not possible to modify the contents of an
existing software-config resource, so a stack-update which changes any
existing software-config resource will result in API calls to create a new
config and delete the old one.</para>
<para>The resource <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareConfig.html">OS::Heat::SoftwareConfig</link></literal> is used for storing configs
represented by text scripts, for example:</para>
<programlisting language="yaml">resources:
boot_script:
type: OS::Heat::SoftwareConfig
properties:
group: ungrouped
config: |
#!/bin/bash
echo "Running boot script"
# ...
server_with_boot_script:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: {get_resource: boot_script}</programlisting>
<para>The resource <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__CloudConfig.html">OS::Heat::CloudConfig</link></literal> allows <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link> cloud-config to
be represented as template YAML rather than a block string. This allows
intrinsic functions to be included when building the cloud-config. This also
ensures that the cloud-config is valid YAML, although no further checks for
valid cloud-config are done.</para>
<programlisting language="yaml">parameters:
file_content:
type: string
description: The contents of the file /tmp/file
resources:
boot_config:
type: OS::Heat::CloudConfig
properties:
cloud_config:
write_files:
- path: /tmp/file
content: {get_param: file_content}
server_with_cloud_config:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: {get_resource: boot_config}</programlisting>
<!---->
<para>The resource <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__MultipartMime.html">OS::Heat::MultipartMime</link></literal> allows multiple
<literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__SoftwareConfig.html">OS::Heat::SoftwareConfig</link></literal> and <literal><link xlink:href="http://docs.openstack.org/hot-reference/content/OS__Heat__CloudConfig.html">OS::Heat::CloudConfig</link></literal>
resources to be combined into a single <link xlink:href="http://cloudinit.readthedocs.org/en/latest/">Cloud-init</link> multi-part message:</para>
<programlisting language="yaml">parameters:
file_content:
type: string
description: The contents of the file /tmp/file
other_config:
type: string
description: The ID of a software-config resource created elsewhere
resources:
boot_config:
type: OS::Heat::CloudConfig
properties:
cloud_config:
write_files:
- path: /tmp/file
content: {get_param: file_content}
boot_script:
type: OS::Heat::SoftwareConfig
properties:
group: ungrouped
config: |
#!/bin/bash
echo "Running boot script"
# ...
server_init:
type: OS::Heat::MultipartMime
properties:
parts:
- config: {get_resource: boot_config}
- config: {get_resource: boot_script}
- config: {get_resource: other_config}
server:
type: OS::Nova::Server
properties:
# flavor, image etc
user_data_format: RAW
user_data: {get_resource: server_init}</programlisting>
<!---->
</section>
</section>
</section>