diff --git a/doc/hot-guide/source/hello_world.rst b/doc/hot-guide/source/hello_world.rst new file mode 100644 index 0000000000..9e49d78b06 --- /dev/null +++ b/doc/hot-guide/source/hello_world.rst @@ -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. diff --git a/doc/hot-guide/source/hot_guide.rst b/doc/hot-guide/source/hot_guide.rst deleted file mode 100644 index 87bf8aba22..0000000000 --- a/doc/hot-guide/source/hot_guide.rst +++ /dev/null @@ -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`). diff --git a/doc/hot-guide/source/index.rst b/doc/hot-guide/source/index.rst index aecbfd8b92..c134b052a2 100644 --- a/doc/hot-guide/source/index.rst +++ b/doc/hot-guide/source/index.rst @@ -4,7 +4,7 @@ HOT guide .. toctree:: :maxdepth: 2 - hot_guide + hello_world hot_spec basic_resources software_deployment