Rework the HOT hello world section
This patch mostly brings editing changes, the samples are the same. Rename hot_guide.rst to hello_world.rst. Change-Id: I28e1a2523a4c88383ecb878e67f6e15d0a6408fb
This commit is contained in:
Gauvain Pocentek
parent
4d56783202
commit
3ad169d475
234
doc/hot-guide/source/hello_world.rst
Normal file
234
doc/hot-guide/source/hello_world.rst
Normal file
@ -0,0 +1,234 @@
|
||||
..
|
||||
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.
|
||||
|
||||
.. _hot_guide:
|
||||
|
||||
==================================
|
||||
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: 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
|
||||
|
||||
Each HOT template has to include the ``heat_template_version`` key with value
|
||||
``2013-05-23``, the current HOT version. While the ``description`` 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:
|
||||
|
||||
.. 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: 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 }
|
||||
|
||||
|
||||
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.
|
||||
|
||||
Hidding 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 contraints 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.
|
||||
@ -1,235 +0,0 @@
|
||||
..
|
||||
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.
|
||||
|
||||
.. _hot_guide:
|
||||
|
||||
=======================================
|
||||
Heat Orchestration Template (HOT) Guide
|
||||
=======================================
|
||||
|
||||
HOT is a new template format meant to replace the Heat
|
||||
CloudFormation-compatible format (CFN) as the native format supported
|
||||
by the Heat 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`.
|
||||
|
||||
------
|
||||
Status
|
||||
------
|
||||
|
||||
HOT support is still under development and needs more work to provide
|
||||
access to all functionality currently available via the CFN compatible
|
||||
template interface. This guide will be updated periodically whenever
|
||||
new features get implemented for HOT.
|
||||
|
||||
----------------------------------
|
||||
Writing a hello world HOT template
|
||||
----------------------------------
|
||||
|
||||
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 may contain only a single resource
|
||||
definition using only predefined properties (along with the mandatory Heat
|
||||
template version tag). For example, the template below could be used to simply
|
||||
deploy a single compute instance.
|
||||
|
||||
::
|
||||
|
||||
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: F18-x86_64-cfntools
|
||||
flavor: m1.small
|
||||
|
||||
Each HOT template has to include the *heat_template_version* key with
|
||||
value '2013-05-23' (the current version of HOT). While the
|
||||
*description* 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:
|
||||
|
||||
::
|
||||
|
||||
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 example above, a compute instance is defined with fixed
|
||||
values for the 'key_name', 'image' and 'flavor' parameters.
|
||||
|
||||
Note that all those elements, i.e. a key-pair with the given name, the
|
||||
image and the flavor have to exist in the OpenStack environment where
|
||||
the template is used. Typically a template is made more easily
|
||||
reusable, though, by defining a set of *input parameters* instead of
|
||||
hard-coding such values.
|
||||
|
||||
|
||||
Template input parameters
|
||||
-------------------------
|
||||
Input parameters defined in the *parameters* section of a HOT template
|
||||
(see also :ref:`hot_spec_parameters`) 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.
|
||||
|
||||
Sticking to the example used above, it makes sense to allow users to provide
|
||||
their custom key-pairs, provide their own image, and to select a flavor for the
|
||||
compute instance. This can be achieved by extending the initial template as
|
||||
follows:
|
||||
|
||||
::
|
||||
|
||||
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
|
||||
instance_type:
|
||||
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: instance_type }
|
||||
|
||||
In the example above, three input parameters have been defined that have to be
|
||||
provided by the user upon deployment. The fixed values for the respective
|
||||
resource properties have been replaced by references to the corresponding
|
||||
input parameters by means of the *get_param* function (see also
|
||||
:ref:`hot_spec_intrinsic_functions`).
|
||||
|
||||
You can also define default values for input parameters which will be
|
||||
used in case the user does not provide the respective parameter during
|
||||
deployment. For example, the following definition for the
|
||||
*instance_type* parameter would select the 'm1.small' flavor unless
|
||||
specified otherwise by the user.
|
||||
|
||||
::
|
||||
|
||||
parameters:
|
||||
instance_type:
|
||||
type: string
|
||||
label: Instance Type
|
||||
description: Type of instance (flavor) to be used
|
||||
default: m1.small
|
||||
|
||||
Another option that can be specified for a parameter is to hide its value when
|
||||
users request information about a stack deployed from a template. This is
|
||||
achieved by the *hidden* attribute and useful, for example when requesting
|
||||
passwords as user input:
|
||||
|
||||
::
|
||||
|
||||
parameters:
|
||||
database_password:
|
||||
type: string
|
||||
label: Database Password
|
||||
description: Password to be used for database
|
||||
hidden: true
|
||||
|
||||
|
||||
Restricting user input
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
In some cases you might want to restrict the values of input
|
||||
parameters that users can supply. For example, you might know that the
|
||||
software running in a compute instance needs a certain amount of
|
||||
resources so you might want to restrict the *instance_type* parameter
|
||||
introduced above. Parameters in HOT templates can be restricted by
|
||||
adding a *constraints* section (see also
|
||||
:ref:`hot_spec_parameters_constraints`).
|
||||
For example, the following would allow only three values to be
|
||||
provided as input for the *instance_type* parameter:
|
||||
|
||||
::
|
||||
|
||||
parameters:
|
||||
instance_type:
|
||||
type: string
|
||||
label: Instance Type
|
||||
description: Type of instance (flavor) to be used
|
||||
constraints:
|
||||
- allow_values: [ m1.medium, m1.large, m1.xlarge ]
|
||||
description: Value must be one of m1.medium, m1.large or m1.xlarge.
|
||||
|
||||
The *constraints* section allows for defining a list of constraints that must
|
||||
all be fulfilled by user input. For example, the following list of constraints
|
||||
could be used to clearly specify format requirements on a password to be
|
||||
provided by users:
|
||||
|
||||
::
|
||||
|
||||
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.
|
||||
|
||||
Note that 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.
|
||||
|
||||
|
||||
Providing template outputs
|
||||
--------------------------
|
||||
In addition to template customization through input parameters, you will
|
||||
typically want to provide outputs to users, which can be done in the
|
||||
*outputs* section of a template (see also :ref:`hot_spec_outputs`).
|
||||
For example, the IP address by which the instance defined in the example
|
||||
above can be accessed should be provided to users. Otherwise, users would have
|
||||
to look it up themselves. The definition for providing the IP address of the
|
||||
compute instance as an output is shown in the following snippet:
|
||||
|
||||
::
|
||||
|
||||
outputs:
|
||||
instance_ip:
|
||||
description: The IP address of the deployed instance
|
||||
value: { get_attr: [my_instance, first_address] }
|
||||
|
||||
Output values are typically resolved using intrinsic function such as
|
||||
the *get_attr* function in the example above (see also
|
||||
:ref:`hot_spec_intrinsic_functions`).
|
||||
@ -4,7 +4,7 @@ HOT guide
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
hot_guide
|
||||
hello_world
|
||||
hot_spec
|
||||
basic_resources
|
||||
software_deployment
|
||||
|
||||
Loading…
Reference in New Issue
Block a user