228 lines
7.7 KiB
ReStructuredText
228 lines
7.7 KiB
ReStructuredText
.. highlight: yaml
|
|
:linenothreshold: 5
|
|
|
|
..
|
|
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.
|
|
|
|
.. _hello_world:
|
|
|
|
==================================
|
|
Writing a hello world HOT template
|
|
==================================
|
|
|
|
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 :ref:`hot_spec`.
|
|
|
|
|
|
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.
|
|
|
|
A most basic template
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
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:
|
|
|
|
.. code-block:: yaml
|
|
|
|
heat_template_version: 2015-04-30
|
|
|
|
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
|
|
|
|
Each HOT template must include the ``heat_template_version`` key with the HOT
|
|
version value, for example, ``2013-05-23``. Consult the :ref:`Heat template
|
|
version list <hot_spec_template_version>` for allowed values and their
|
|
features.
|
|
|
|
The ``description`` key is optional, however 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:
|
|
|
|
.. code-block:: yaml
|
|
|
|
description: >
|
|
This is how you can provide a longer description
|
|
of your template that goes over several lines.
|
|
|
|
The ``resources`` 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 ``key_name``, ``image`` and ``flavor`` properties.
|
|
|
|
.. note::
|
|
All the defined elements (key pair, image, flavor) have to exist in the
|
|
OpenStack environment where the template is used.
|
|
|
|
Input parameters
|
|
~~~~~~~~~~~~~~~~
|
|
Input parameters defined in the ``parameters`` 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.
|
|
|
|
The following example extends the previous template to provide parameters for
|
|
the key pair, image and flavor properties of the resource:
|
|
|
|
.. code-block:: yaml
|
|
|
|
heat_template_version: 2015-04-30
|
|
|
|
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 }
|
|
|
|
|
|
Values for the three parameters must be defined by the template user during the
|
|
deployment of a stack. The ``get_param`` intrinsic function retrieves a
|
|
user-specified value for a given parameter and uses this value for the
|
|
associated resource property.
|
|
|
|
For more information about intrinsic functions, see
|
|
:ref:`hot_spec_intrinsic_functions`.
|
|
|
|
Providing default values
|
|
------------------------
|
|
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 ``m1.small`` for the
|
|
``flavor`` property:
|
|
|
|
.. code-block:: yaml
|
|
|
|
parameters:
|
|
flavor:
|
|
type: string
|
|
label: Instance Type
|
|
description: Flavor to be used
|
|
default: m1.small
|
|
|
|
.. note::
|
|
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.
|
|
|
|
Hiding parameters values
|
|
------------------------
|
|
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 ``hidden`` boolean attribute of the parameter:
|
|
|
|
.. code-block:: yaml
|
|
|
|
parameters:
|
|
database_password:
|
|
type: string
|
|
label: Database Password
|
|
description: Password to be used for database
|
|
hidden: true
|
|
|
|
Restricting user input
|
|
----------------------
|
|
You can restrict the values of an input parameter to make sure that the user
|
|
defines valid data for this parameter. The ``constraints`` property of an input
|
|
parameter defines a list of constraints to apply for the parameter.
|
|
The following example restricts the ``flavor`` parameter to a list of three
|
|
possible values:
|
|
|
|
.. code-block:: 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.
|
|
|
|
The following example defines multiple constraints for a password definition:
|
|
|
|
.. code-block:: 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.
|
|
|
|
The list of supported constraints is available in the
|
|
:ref:`hot_spec_parameters_constraints` section.
|
|
|
|
.. note::
|
|
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.
|
|
|
|
|
|
Template outputs
|
|
~~~~~~~~~~~~~~~~
|
|
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 ``outputs`` section of a template. In the following example
|
|
the output section provides the IP address of the ``my_instance`` resource:
|
|
|
|
.. code-block:: yaml
|
|
|
|
outputs:
|
|
instance_ip:
|
|
description: The IP address of the deployed instance
|
|
value: { get_attr: [my_instance, first_address] }
|
|
|
|
.. note::
|
|
Output values are typically resolved using intrinsic function such as
|
|
the ``get_attr``. See :ref:`hot_spec_intrinsic_functions` for more information
|
|
about intrinsic functions..
|
|
|
|
See :ref:`hot_spec_outputs` for more information about the ``outputs`` section.
|