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

<?xml version='1.0' encoding='UTF-8'?>
<!--Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.-->
<section xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="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="hiding-parameters-values">
      <title>Hiding 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 constraints 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>