From 670bf6d6cbcb57230a20222966271f7c462b7a6a Mon Sep 17 00:00:00 2001 From: Brian Moss Date: Fri, 19 Jun 2015 17:57:31 +1000 Subject: [PATCH] Merge HOT Guide files into Template Guide The HOT Guide was formerly located in the User Guide. This patch merges those files into the heat docs repository in the Template Guide directory. Change-Id: I559b1b3edb42b1de40013c37e5967d8898c8a916 Closes-Bug: #1461720 --- doc/source/template_guide/advanced_topics.rst | 38 + doc/source/template_guide/basic_resources.rst | 500 ++++++++ doc/source/template_guide/composition.rst | 65 +- doc/source/template_guide/environment.rst | 208 ++-- .../template_guide/existing_templates.rst | 28 + doc/source/template_guide/hello_world.rst | 233 ++++ doc/source/template_guide/hot_spec.rst | 1019 ++++++++--------- doc/source/template_guide/index.rst | 6 + .../template_guide/software_deployment.rst | 801 +++++++++++++ 9 files changed, 2222 insertions(+), 676 deletions(-) create mode 100644 doc/source/template_guide/advanced_topics.rst create mode 100644 doc/source/template_guide/basic_resources.rst create mode 100644 doc/source/template_guide/existing_templates.rst create mode 100644 doc/source/template_guide/hello_world.rst create mode 100644 doc/source/template_guide/software_deployment.rst diff --git a/doc/source/template_guide/advanced_topics.rst b/doc/source/template_guide/advanced_topics.rst new file mode 100644 index 0000000000..d6dae28e14 --- /dev/null +++ b/doc/source/template_guide/advanced_topics.rst @@ -0,0 +1,38 @@ +:orphan: + +.. _advanced_topics: + +=============== +Advanced topics +=============== + +Networking +~~~~~~~~~~ + +Load balancer +------------- + +TODO + +Firewall +-------- + +TODO + +VPN +--- + +TODO + +Auto scaling +~~~~~~~~~~~~ + +Alarming +-------- + +TODO + +Up scaling and down scaling +--------------------------- + +TODO diff --git a/doc/source/template_guide/basic_resources.rst b/doc/source/template_guide/basic_resources.rst new file mode 100644 index 0000000000..1812241f89 --- /dev/null +++ b/doc/source/template_guide/basic_resources.rst @@ -0,0 +1,500 @@ +.. highlight: yaml + :linenothreshold: 5 + +.. _basic_resources: + +========= +Instances +========= + +.. 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" + +Manage instances +~~~~~~~~~~~~~~~~ + +Create an instance +------------------ +Use the :hotref:`OS::Nova::Server` resource to create a Compute instance. The +``flavor`` property is the only mandatory one, but you need to define a boot +source using one of the ``image`` or ``block_device_mapping`` properties. + +You also need to define the ``networks`` property to indicate to which networks +your instance must connect if multiple networks are available in your tenant. + +The following example creates a simple instance, booted from an image, and +connecting to the ``private`` network: + +.. code-block:: yaml + :linenos: + + resources: + instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + networks: + - network: private + + +Connect an instance to a network +-------------------------------- +Use the ``networks`` property of an :hotref:`OS::Nova::Server` resource to +define which networks an instance should connect to. Define each network as a +YAML map, containing one of the following keys: + +``port`` + The ID of an existing Networking port. You usually create this port in the + same template using an :hotref:`OS::Neutron::Port` resource. You will be + able to associate a floating IP to this port, and the port to your Compute + instance. + +``network`` + The name or ID of an existing network. You don't need to create an + :hotref:`OS::Neutron::Port` resource if you use this property, but you will + not be able to associate a floating IP with the instance interface in the + template. + +The following example demonstrates the use of the ``port`` and ``network`` +properties: + +.. code-block:: yaml + :linenos: + + 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 + + +Create and associate security groups to an instance +--------------------------------------------------- +Use the :hotref:`OS::Neutron::SecurityGroup` resource to create security +groups. + +Define the ``security_groups`` property of the :hotref:`OS::Neutron::Port` +resource to associate security groups to a port, then associate the port to an +instance. + +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: + +.. code-block:: yaml + :linenos: + + 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 } + + +Create and associate a floating IP to an instance +------------------------------------------------- +You can use two sets of resources to create and associate floating IPs to +instances. + +OS::Nova resources +++++++++++++++++++ +Use the :hotref:`OS::Nova::FloatingIP` resource to create a floating IP, and +the :hotref:`OS::Nova::FloatingIPAssociation` resource to associate the +floating IP to an instance. + +The following example creates an instance and a floating IP, and associate the +floating IP to the instance: + +.. code-block:: yaml + :linenos: + + 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 } + +OS::Neutron resources ++++++++++++++++++++++ +.. note:: + The Networking service (neutron) must be enabled on your OpenStack + deployment to use these resources. + +Use the :hotref:`OS::Neutron::FloatingIP` resource to create a floating IP, and +the :hotref:`OS::Neutron::FloatingIPAssociation` resource to associate the +floating IP to a port: + +.. code-block:: yaml + :linenos: + + parameters: + net: + description: name of network used to launch instance. + type: string + default: private + + resources: + inst1: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + networks: + - network: {get_param: net} + + floating_ip: + type: OS::Neutron::FloatingIP + properties: + floating_network: public + + association: + type: OS::Neutron::FloatingIPAssociation + properties: + floatingip_id: { get_resource: floating_ip } + port_id: {get_attr: [inst1, addresses, {get_param: net}, 0, port]} + +You can also create an OS::Neutron::Port and associate that with the server and +the floating IP. However the approach mentioned above will work better +with stack updates. + +.. code-block:: yaml + :linenos: + + 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 + + association: + type: OS::Neutron::FloatingIPAssociation + properties: + floatingip_id: { get_resource: floating_ip } + port_id: { get_resource: instance_port } + +Enable remote access to an instance +----------------------------------- +The ``key_name`` attribute of the :hotref:`OS::Nova::Server` resource defines +the key pair to use to enable SSH remote access: + +.. code-block:: yaml + :linenos: + + resources: + my_instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: ubuntu-trusty-x86_64 + key_name: my_key + +.. note:: + For more information about key pairs, see the :doc:`../cli_nova_configure_access_security_for_instances`. + +Create a key pair +----------------- +You can create new key pairs with the :hotref:`OS::Nova::KeyPair` resource. Key +pairs can be imported or created during the stack creation. + +If the ``public_key`` property is not specified, the Orchestration module +creates a new key pair. If the ``save_private_key`` property is set to +``true``, the ``private_key`` attribute of the resource holds the private key. + +The following example creates a new key pair and uses it as authentication key +for an instance: + +.. code-block:: yaml + :linenos: + + 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 ] } + +Manage networks +~~~~~~~~~~~~~~~ +Create a network and a subnet +----------------------------- +.. note:: + 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). + +Use the :hotref:`OS::Neutron::Net` resource to create a network, and the +:hotref:`OS::Neutron::Subnet` resource to provide a subnet for this network: + +.. code-block:: yaml + :linenos: + + 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 + + +Create and manage a router +-------------------------- +Use the :hotref:`OS::Neutron::Router` resource to create a router. You can +define its gateway with the ``external_gateway_info`` property: + +.. code-block:: yaml + :linenos: + + resources: + router1: + type: OS::Neutron::Router + properties: + external_gateway_info: { network: public } + +You can connect subnets to routers with the +:hotref:`OS::Neutron::RouterInterface` resource: + +.. code-block:: yaml + :linenos: + + resources: + subnet1_interface: + type: OS::Neutron::RouterInterface + properties: + router_id: { get_resource: router1 } + subnet: private-subnet + + +Complete network example +------------------------ +The following example creates a network stack: + +* A network and an associated subnet. +* A router with an external gateway. +* An interface to the new subnet for the new router. + +In this example, the ``public`` network is an existing shared network: + +.. code-block:: yaml + :linenos: + + 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 } + + +Manage volumes +~~~~~~~~~~~~~~ +Create a volume +--------------- +Use the :hotref:`OS::Cinder::Volume` resource to create a new Block Storage +volume. + +For example: + +.. code-block:: yaml + :linenos: + + resources: + my_new_volume: + type: OS::Cinder::Volume + properties: + size: 10 + +The volumes that you create are empty by default. Use the ``image`` property to +create a bootable volume from an existing image: + +.. code-block:: yaml + :linenos: + + resources: + my_new_bootable_volume: + type: OS::Cinder::Volume + properties: + size: 10 + image: ubuntu-trusty-x86_64 + + +You can also create new volumes from another volume, a volume snapshot, or a +volume backup. Use the ``source_volid``, ``snapshot_id`` or ``backup_id`` +properties to create a new volume from an existing source. + +For example, to create a new volume from a backup: + +.. code-block:: yaml + :linenos: + + resources: + another_volume: + type: OS::Cinder::Volume + properties: + backup_id: 2fff50ab-1a9c-4d45-ae60-1d054d6bc868 + +In this example the ``size`` property is not defined because the Block Storage +service uses the size of the backup to define the size of the new volume. + +Attach a volume to an instance +------------------------------ +Use the :hotref:`OS::Cinder::VolumeAttachment` resource to attach a volume to +an instance. + +The following example creates a volume and an instance, and attaches the volume +to the instance: + +.. code-block:: yaml + :linenos: + + 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 } + +Boot an instance from a volume +------------------------------ +Use the ``block_device_mapping`` property of the :hotref:`OS::Nova::Server` +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. + +The following example creates a bootable volume from an image, and uses it to +boot an instance: + +.. code-block:: yaml + :linenos: + + 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 + +.. TODO + A few elements that probably belong here: + - OS::Swift::Container + - OS::Trove::Instance diff --git a/doc/source/template_guide/composition.rst b/doc/source/template_guide/composition.rst index 2e5eb63169..6c79700530 100644 --- a/doc/source/template_guide/composition.rst +++ b/doc/source/template_guide/composition.rst @@ -1,3 +1,6 @@ +.. 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 @@ -39,9 +42,7 @@ To achieve this: 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 -:file:`my_nova.yaml` file: - -.. code-block:: yaml +:file:`my_nova.yaml` file:: heat_template_version: 2014-10-16 @@ -58,15 +59,10 @@ new types of resources. These examples use a custom template stored in a flavor: m1.small image: ubuntu-trusty-x86_64 - - Use the template filename as type -================================= - +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following template defines the :file:`my_nova.yaml` file as value for the -``type`` property of a resource: - -.. code-block:: yaml +``type`` property of a resource:: heat_template_version: 2014-10-16 @@ -81,34 +77,29 @@ the ``key_name`` property of the new template. .. note:: - The above reference to ``my_nova.yaml`` assumes it is in the same directory. + The above reference to :file:`my_nova.yaml` assumes it is in the same directory. You can use any of the following forms: - * Relative path (``my_nova.yaml``) - * Absolute path (``file:///home/user/templates/my_nova.yaml``) + * Relative path (:file:`my_nova.yaml`) + * Absolute path (:file:`file:///home/user/templates/my_nova.yaml`) * Http URL (``http://example.com/templates/my_nova.yaml``) * Https URL (``https://example.com/templates/my_nova.yaml``) -To create the stack run: - -.. code-block:: console +To create the stack run:: $ heat stack-create -f main.yaml stack1 Define a new resource type -========================== - -You can associate a name to the ``my_nova.yaml`` template in an environment +~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can associate a name to the :file:`my_nova.yaml` template in an environment file. If the name is already known by the Orchestration module then your new resource will override the default one. In the following example a new ``OS::Nova::Server`` resource overrides the default resource of the same name. -An :file:`env.yaml` environment file holds the definition of the new resource: - -.. code-block:: yaml +An :file:`env.yaml` environment file holds the definition of the new resource:: resource_registry: "OS::Nova::Server": my_nova.yaml @@ -117,9 +108,7 @@ An :file:`env.yaml` environment file holds the definition of the new resource: See :ref:`environments` for more detail about environment files. -You can now use the new ``OS::Nova::Server`` in your new template: - -.. code-block:: yaml +You can now use the new ``OS::Nova::Server`` in your new template:: heat_template_version: 2014-10-16 @@ -129,20 +118,15 @@ You can now use the new ``OS::Nova::Server`` in your new template: properties: key_name: my_key -To create the stack run: - -.. code-block:: console +To create the stack run:: $ heat stack-create -f main.yaml -e env.yaml example-two - Get access to nested attributes -=============================== -There are implicit attributes of a template resource. Accessing -nested attributes require heat_template_version '2014-10-16' or -higher and can be accessed as follows: - -.. code-block:: yaml +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +There are implicit attributes of a template resource. Accessing nested +attributes requires ``heat_template_version`` 2014-10-16 or higher. These are +accessible as follows:: heat_template_version: 2014-10-16 @@ -154,18 +138,15 @@ higher and can be accessed as follows: test_out: value: {get_attr: my_server, resource.server, first_address} - Making your template resource more "transparent" -================================================ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. note:: - Available since 2015.1 (Kilo). + Available since 2015.1 (Kilo). If you wish to be able to return the ID of one of the inner resources instead of the nested stack's identifier, you can add the special reserved -output "OS::stack_id" to your template resource. - -.. code-block:: yaml +output ``OS::stack_id`` to your template resource:: heat_template_version: 2014-10-16 @@ -177,5 +158,5 @@ output "OS::stack_id" to your template resource. OS::stack_id: value: {get_resource: server} -Now when you use "get_resource" from the outer template heat +Now when you use ``get_resource`` from the outer template heat will use the nova server id and not the template resource identifier. diff --git a/doc/source/template_guide/environment.rst b/doc/source/template_guide/environment.rst index 40422f93b5..603d13bca8 100644 --- a/doc/source/template_guide/environment.rst +++ b/doc/source/template_guide/environment.rst @@ -1,3 +1,6 @@ +.. 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 @@ -17,136 +20,135 @@ Environments ============ -The environment is used to affect the runtime behavior of the -template. It provides a way to override the resource -implementations and provide a mechanism to place parameters +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. -To fully understand the runtime behavior you also have to consider -what plug-ins the cloud operator has installed. +To fully understand the runtime behavior you have to consider what plug-ins are +installed on the cloud you're using. ------- -Format ------- +Environment file format +~~~~~~~~~~~~~~~~~~~~~~~ +The environment is a yaml text file that contains two main sections: -It is a yaml text file with three main sections "resource_registry", -"parameters" and "parameter_defaults". +``parameters`` + A list of key/value pairs. ------------------- -Command line usage ------------------- -:: +``resource_registry`` + Definition of custom resources. + +Use the :option:`-e` option of the :command:`heat stack-create` command to +create a stack using the environment defined in such a file. + +You can also provide environment parameters as a list of key/value pairs using +the :option:`-P` option of the :command:`heat stack-create` command. + +In the following example the environment is read from the :file:`my_env.yaml` +file and an extra parameter is provided using the :option:`-P` option:: + + $ heat stack-create my_stack -e my_env.yaml -P "param1=val1;param2=val2" -f my_tmpl.yaml - heat stack-create my_stack -e my_env.yaml -P "some_parm=bla" -f my_tmpl.yaml ---------------------------------- Global and effective environments ---------------------------------- - -The environment used for a stack is the combination of (1) the -environment given by the user with the template for the stack and (2) -a global environment that is determined by the cloud operator. -Combination is asymmetric: an entry in the user environment takes -precedence over the global environment. The OpenStack software -includes a default global environment, which supplies some resource -types that are included in the standard documentation. The cloud -operator can add additional environment entries. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +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 your cloud operator can add additional environment entries. The cloud operator can add to the global environment by putting environment files in a configurable directory wherever -the heat-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 +the Orchestration engine runs. The configuration variable is named +``environment_dir`` and is found in the ``[DEFAULT]`` section +of :file:`/etc/heat/heat.conf`. The default for that directory is +:file:`/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 :file:`my_env.yaml` file from the example above had been put in the +``environment_dir`` then the user's command line could be this:: -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 -:: - - heat stack-create my_stack -P "some_parm=bla" -f my_tmpl.yaml - --------------- Usage examples --------------- +~~~~~~~~~~~~~~ -1) Pass parameters into heat -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +Define values for template arguments +------------------------------------ +You can define values for the template arguments in the ``parameters`` section +of an environment file:: parameters: KeyName: heat_key InstanceType: m1.micro ImageId: F18-x86_64-cfntools -2) Define defaults to parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -This is especially useful when you have many template resources and -you want the same value in each. Note: these defaults will get passed -down into all template resources. -:: +Define defaults to parameters +-------------------------------- +You can define default values for all template arguments in the +``parameter_defaults`` section of an environment file. These defaults are +passed into all template resources:: parameter_defaults: KeyName: heat_key +Mapping resources +----------------- +You can map one resource to another in the ``resource_registry`` section +of an evironment file. The resource you provide in this manner must have an +identifier, and must reference either another resource's ID or the URL of an +existing template file. -3) Deal with the mapping of Quantum to Neutron -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: - - resource_registry: - "OS::Quantum*": "OS::Neutron*" - -So all existing resources which can be matched with "OS::Neutron*" -will be mapped to "OS::Quantum*" accordingly. - -4) Override a resource type with a custom template resource -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: - - resource_registry: - "AWS::EC2::Instance": file:///home/mine/my_instance_with_better_defaults.yaml - -Please note that the template resource URL here must end with ".yaml" -or ".template", or it will not be treated as a custom template -resource. The supported URL types are "http, https and file". - -5) Always map resource type X to Y -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +The following example maps a new ``OS::Networking::FloatingIP`` +resource to an existing ``OS::Nova::FloatingIP`` resource:: resource_registry: "OS::Networking::FloatingIP": "OS::Nova::FloatingIP" - -6) Use default resources except one for a particular resource in the template -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:: +You can use wildcards to map multiple resources, for example to map all +``OS::Neutron`` resources to ``OS::Network``:: resource_registry: - resources: - my_db_server: - "OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml + "OS::Network*": "OS::Neutron*" -7) Pause stack creation/update on a given resource -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -If you want to debug your stack as it's being created or updated or if you want -to run it in phases you can set `pre-create` and `pre-update` hooks in the -`resources` section of `resource_registry`. -To set a hook, add either `hooks: pre-create` or `hooks: pre-update` to the -resource's dictionary. You can also use the `[pre-create, pre-update]` to stop +Override a resource with a custom resource +------------------------------------------ +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:: + + resource_registry: + "AWS::EC2::Instance": file:///path/to/my_instance.yaml + +The supported URL schemes are ``file``, ``http`` and ``https``. + +.. note:: + + The template file extension must be ``.yaml`` or ``.template``, or it will + not be treated as a custom template resource. + +You can limit the usage of a custom resource to a specific resource of the +template:: + + resource_registry: + resources: + my_db_server: + "OS::DBInstance": file:///home/mine/all_my_cool_templates/db.yaml + +Pause stack creation or update on a given resource +-------------------------------------------------- +If you want to debug your stack as it's being created or updated, or if you want +to run it in phases, you can set ``pre-create`` and ``pre-update`` hooks in the +``resources`` section of ``resource_registry``. + +To set a hook, add either ``hooks: pre-create`` or ``hooks: pre-update`` to the +resource's dictionary. You can also use ``[pre-create, pre-update]`` to stop on both actions. -Hooks can be combined with other `resources` properties (e.g. provider -templates or type mapping). - -Example: - -:: +You can combine hooks with other ``resources`` properties such as provider +templates or type mapping:: resource_registry: resources: @@ -159,25 +161,19 @@ Example: another_resource: hooks: [pre-create, pre-update] -When heat encounters a resource that has a hook, it will pause the resource -action until the hook is cleared. Any resources that depend on it will wait as -well. Any resources that don't will be created in parallel (unless they have -hooks, too). +When heat encounters a resource that has a hook, it pauses the resource +action until the hook clears. Any resources that depend on the paused action +wait as well. Non-dependant resources are created in parallel unless they have +their own hooks. -It is also possible to do a partial match by putting an asterisk (`*`) in the -name. - -This example: - -:: +It is possible to perform a wild card match using an asterisk (`*`) in the +resource name. For example, the following entry pauses while creating +``app_server`` and ``database_server``, but not ``server`` or ``app_network``:: resource_registry: resources: "*_server": hooks: pre-create -will pause while creating `app_server` and `database_server` but not `server` -or `app_network`. - -Hook is cleared by signaling the resource with `{unset_hook: pre-create}` (or -`pre-update`). +Clear hooks by signaling the resource with ``{unset_hook: pre-create}`` +or ``{unset_hook: pre-update}``. diff --git a/doc/source/template_guide/existing_templates.rst b/doc/source/template_guide/existing_templates.rst new file mode 100644 index 0000000000..711c24a450 --- /dev/null +++ b/doc/source/template_guide/existing_templates.rst @@ -0,0 +1,28 @@ +:orphan: + +.. _existing_templates: + +================================ +Where to find existing templates +================================ + +There are several repositories where you can find existing HOT templates. + +The `OpenStack Heat Templates repository`_ contains example templates +demonstrating core Heat functionality, related image-building templates, +and template-related scripts and conversion tools. + +.. _OpenStack Heat Templates Repository: https://git.openstack.org/cgit/openstack/heat-templates/tree/ + +The `OpenStack TripleO Heat Templates repository`_ contains a variety of +heat templates that are included in the tripleo-heat-templates codebase. + +.. _OpenStack TripleO Heat Templates repository: https://git.openstack.org/cgit/openstack/tripleo-heat-templates/tree/ + +Rackspace has provided a set of Heat templates at the `RCB Ops repository`_ +that can be used by cloud operators to launch applications, templates for +building a multi-node OpenStack cluster, as well as templates for CI +development. Heat templates for deployment of Magento, Hadoop, MongoDB, +ELK, Drupal and more can be found here. + +.. _RCB Ops repository: http://github.com/rcbops/ diff --git a/doc/source/template_guide/hello_world.rst b/doc/source/template_guide/hello_world.rst new file mode 100644 index 0000000000..4a2f9fb16b --- /dev/null +++ b/doc/source/template_guide/hello_world.rst @@ -0,0 +1,233 @@ +.. 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 + :linenos: + + 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 must include the ``heat_template_version`` key with +the HOT version value, for example, ``2013-05-23``. A list of HOT template +versions can be found at `Heat Template Version +file `__ + +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 + :linenos: + + 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 + :linenos: + + 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 + :linenos: + + 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 + :linenos: + + 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 + :linenos: + + 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/source/template_guide/hot_spec.rst b/doc/source/template_guide/hot_spec.rst index 838ed36832..59766fa326 100644 --- a/doc/source/template_guide/hot_spec.rst +++ b/doc/source/template_guide/hot_spec.rst @@ -1,3 +1,6 @@ +.. 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 @@ -14,7 +17,7 @@ .. _hot_spec: =============================================== -Heat Orchestration Template (HOT) Specification +Heat Orchestration Template (HOT) specification =============================================== HOT is a new template format meant to replace the Heat CloudFormation-compatible @@ -23,9 +26,8 @@ This specification explains in detail all elements of the HOT template format. An example driven guide to writing HOT templates can be found at :ref:`hot_guide`. ------- Status ------- +~~~~~~ HOT is considered reliable, supported, and standardized as of our Icehouse (April 2014) release. The Heat core team may make improvements @@ -33,9 +35,8 @@ to the standard, which very likely would be backward compatible. The template format is also versioned. Since Juno release, Heat supports multiple different versions of the HOT specification. ------------------- -Template Structure ------------------- +Template structure +~~~~~~~~~~~~~~~~~~ HOT templates are defined in YAML and follow the structure outlined below. @@ -59,21 +60,21 @@ HOT templates are defined in YAML and follow the structure outlined below. # declaration of output parameters heat_template_version - This key with value *2013-05-23* (or a later date) indicates that the YAML + This key with value ``2013-05-23`` (or a later date) indicates that the YAML document is a HOT template of the specified version. description - This *optional* key allows for giving a description of the template, or the + This optional key allows for giving a description of the template, or the workload that can be deployed using the template. parameter_groups This section allows for specifying how the input parameters should be grouped and the order to provide the parameters in. This section is - *optional* and can be omitted when necessary. + optional and can be omitted when necessary. parameters This section allows for specifying input parameters that have to be provided - when instantiating the template. The section is *optional* and can be + when instantiating the template. The section is optional and can be omitted when no input is required. resources @@ -84,95 +85,90 @@ resources outputs This section allows for specifying output parameters available to users once - the template has been instantiated. This section is *optional* and can be + the template has been instantiated. This section is optional and can be omitted when no output values are required. .. _hot_spec_template_version: ---------------------- -Heat Template Version ---------------------- +Heat template version +~~~~~~~~~~~~~~~~~~~~~ -The value of *heat_template_version* tells Heat not only the format of the +The value of ``heat_template_version`` tells Heat not only the format of the template but also features that will be validated and supported. For example, Heat currently supports the following values for the -*heat_template_version* key: +``heat_template_version`` key: 2013-05-23 - The key with value *2013-05-23* indicates that the YAML document is a HOT + The key with value ``2013-05-23`` indicates that the YAML document is a HOT template and it may contain features implemented until the Icehouse release. This version supports the following functions (some are back ported - to this version): + to this version):: -:: - get_attr - get_file - get_param - get_resource - list_join - resource_facade - str_replace - Fn::Base64 - Fn::GetAZs - Fn::Join - Fn::MemberListToMap - Fn::Replace - Fn::ResourceFacade - Fn::Select - Fn::Split - Ref + get_attr + get_file + get_param + get_resource + list_join + resource_facade + str_replace + Fn::Base64 + Fn::GetAZs + Fn::Join + Fn::MemberListToMap + Fn::Replace + Fn::ResourceFacade + Fn::Select + Fn::Split + Ref 2014-10-16 - The key with value *2014-10-16* indicates that the YAML document is a HOT + The key with value ``2014-10-16`` indicates that the YAML document is a HOT template and it may contain features added and/or removed up until the Juno release. This version removes most CFN functions that were supported in - the Icehouse release, i.e. the *2013-05-23* version. So the supported functions - now are: + the Icehouse release, i.e. the ``2013-05-23`` version. So the supported functions + now are:: -:: - get_attr - get_file - get_param - get_resource - list_join - resource_facade - str_replace - Fn::Select + get_attr + get_file + get_param + get_resource + list_join + resource_facade + str_replace + Fn::Select 2015-04-30 - The key with value *2015-04-30* indicates that the YAML document is a HOT + The key with value ``2015-04-30`` indicates that the YAML document is a HOT template and it may contain features added and/or removed up until the Kilo - release. This version adds the *repeat* function. So the complete list of - supported functions is: + release. This version adds the ``repeat`` function. So the complete list of + supported functions is:: -:: - get_attr - get_file - get_param - get_resource - list_join - repeat - digest - resource_facade - str_replace - Fn::Select + get_attr + get_file + get_param + get_resource + list_join + repeat + digest + resource_facade + str_replace + Fn::Select .. _hot_spec_parameter_groups: ------------------------- -Parameter Groups Section ------------------------- +Parameter groups section +~~~~~~~~~~~~~~~~~~~~~~~~ -The *parameter_groups* section allows for specifying how the input parameters +The ``parameter_groups`` section allows for specifying 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. 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. Each parameter should be associated to a specific group only once -using the parameter name to bind it to a defined parameter in the parameters +using the parameter name to bind it to a defined parameter in the ``parameters`` section. :: @@ -195,17 +191,16 @@ parameters A list of parameters associated with this parameter group. param name - The name of the parameter that is defined in the associated parameters + The name of the parameter that is defined in the associated ``parameters`` section. .. _hot_spec_parameters: ------------------- -Parameters Section ------------------- +Parameters section +~~~~~~~~~~~~~~~~~~ -The *parameters* section allows for specifying input parameters that have to be +The ``parameters`` section allows for specifying input parameters that have to be provided when instantiating the template. Such parameters are typically used to customize each deployment (e.g. by setting custom user names or passwords) or for binding to environment-specifics like certain images. @@ -227,34 +222,39 @@ default value defined as nested elements. param name - The name of the parameter is defined at the top of each parameter block. + The name of the parameter. type - This attribute specifies the type of parameter. Currently supported types - are *string*, *number*, *comma_delimited_list*, *json*, or *boolean*. + The type of the parameter. Supported types + are ``string``, ``number``, ``comma_delimited_list``, ``json`` and + ``boolean``. + This attribute is required. label - This *optional* attribute allows for giving a human readable name of the - parameter. + A human readable name for the parameter. + This attribute is optional. description - This *optional* attribute allows for giving a human readable description of - the parameter. + A human readable description for the parameter. + This attribute is optional. default - This *optional* attribute allows for defining a default value for the - parameters which will be used in case the parameter is not specified by the - user during deployment. + A default value for the parameter. This value is used if the user doesn't + specify his own value during deployment. + This attribute is optional. hidden - This *optional* attribute allows for specifying whether the parameters - should be hidden when showing information about a stack created from the - template at runtime (e.g. for hiding passwords that were specified as - parameters). If not specified, the default value 'false' will be used. + 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. + + This attribute is optional and defaults to ``false``. constraints - This *optional* block allows for specifying additional constraints on the - parameter, such as minimum or maximum values for numeric parameters. + 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. + This attribute is optional. The table below describes all currently supported types with examples: @@ -281,11 +281,7 @@ The table below describes all currently supported types with examples: | | false value. | | +----------------------+-------------------------------+------------------+ -The following example shows a minimalistic definition of two parameters. Note -that the description and label are actually optional, but is good practice to -provide a useful description and label for each parameter. - -:: +The following example shows a minimalistic definition of two parameters:: parameters: user_name: @@ -297,46 +293,44 @@ provide a useful description and label for each parameter. label: Port Number description: Port number to be configured for the web server +.. note:: + 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. .. _hot_spec_parameters_constraints: Parameter Constraints --------------------- -The *constraints* block of a parameter definition allows for defining additional -validation constraints that apply to the value of the parameter. At -instantiation time of the template, user provided parameter values are validated -against those constraints to make sure the provided values match expectations of -the template author. -Constraints are defined in the form of a bulleted list according to the -following syntax: - -:: +The ``constraints`` 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 +constraints at instantiation time. The constraints are defined as a list with +the following syntax:: constraints: - : description: constraint type - The constraint type specifies the kind of constraint defined in the current - bulleted list item. The set of currently supported constraints is given - below. + Type of constraint to apply. The set of currently supported constraints is + given below. constraint definition - This value defines the actual constraint, depending on the constraint type. - The concrete syntax for each constraint type is given below. + The actual constraint, depending on the constraint type. The + concrete syntax for each constraint type is given below. description - This *optional* attribute allows for specifying a concrete description of - the current constraint. This text will be presented to the user, for - example, when the provided input value for a parameter violates the - constraint. If omitted, a default validation message will be presented to - the user. + A description of the constraint. The text + is presented to the user when the value he defines violates the constraint. + If omitted, a default validation message is presented to the user. + This attribute is optional. -The following example show the definition of a string parameter with two +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 so useful messages can be -presented to the user at deployment time. +it is good practice to provide concrete descriptions to present useful messages +to the user at deployment time. :: @@ -351,143 +345,134 @@ presented to the user at deployment time. - allowed_pattern: "[A-Z]+[a-zA-Z0-9]*" description: User name must start with an uppercase character +.. note:: + 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. + The following sections list the supported types of parameter constraints, along with the concrete syntax for each type. length -~~~~~~ -The *length* constraint applies to parameters of type *string* and allows for -defining a lower and upper limit for the length of the string value. The syntax -for the length constraint is: +++++++ +The ``length`` constraint applies to parameters of type +``string``. It defines a lower and upper limit for the length of the +string value. -:: +The syntax of the ``length`` constraint is:: - length: { min: , max: } + length: { min: , max: } It is possible to define a length constraint with only a lower limit or an -upper limit. However, at least one of *min* or *max* must be specified. +upper limit. However, at least one of ``min`` or ``max`` must be specified. range -~~~~~ -The *range* constraint applies to parameters of type *number* and allows for -defining a lower and upper limit for the numeric value of the parameter. The -syntax of the range constraint is: ++++++ +The ``range`` constraint applies to parameters of type ``number``. +It defines a lower and upper limit for the numeric value of the +parameter. -:: +The syntax of the ``range`` constraint is:: - range: { min: , max: } + range: { min: , max: } It is possible to define a range constraint with only a lower limit or an -upper limit. However, at least one of *min* or *max* must be specified. -The minimum or maximum boundaries are included in the range. For example, the -following range constraint would allow for all numeric values between 0 and 10. +upper limit. However, at least one of ``min`` or ``max`` must be specified. -:: +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:: - range: { min: 0, max: 10 } + range: { min: 0, max: 10 } allowed_values -~~~~~~~~~~~~~~ -The *allowed_values* constraint applies to parameters of type string or number -and allows for specifying 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 specified list. The syntax of the -allowed_values constraint is: +++++++++++++++ +The ``allowed_values`` constraint applies to parameters of type +``string`` or ``number``. 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. -:: +The syntax of the ``allowed_values`` constraint is:: - allowed_values: [ , , ... ] + allowed_values: [ , , ... ] -Alternatively, the YAML bulleted list notation can be used: +Alternatively, the following YAML list notation can be used:: -:: + allowed_values: + - + - + - ... - allowed_values: - - - - - - ... +For example:: -For example: - -:: - - parameters: - instance_type: - type: string - label: Instance Type - description: Instance type for compute instances - constraints: - - allowed_values: - - m1.small - - m1.medium - - m1.large + parameters: + instance_type: + type: string + label: Instance Type + description: Instance type for compute instances + constraints: + - allowed_values: + - m1.small + - m1.medium + - m1.large allowed_pattern -~~~~~~~~~~~~~~~ -The *allowed_pattern* constraint applies to parameters of type string and allows -for specifying a regular expression against which a user provided parameter -value must evaluate at deployment. -The syntax of the allowed_pattern constraint is: ++++++++++++++++ +The ``allowed_pattern`` constraint applies to parameters of type +``string``. It specifies a regular expression against which a +user-provided parameter value must evaluate at deployment. -:: +The syntax of the ``allowed_pattern`` constraint is:: - allowed_pattern: + allowed_pattern: -For example: +For example:: -:: - - 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]*" + 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 custom_constraint -~~~~~~~~~~~~~~~~~ -The *custom_constraint* 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. ++++++++++++++++++ +The ``custom_constraint`` 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. -The syntax of the custom_constraint constraint is: +The syntax of the ``custom_constraint`` constraint is:: -:: + custom_constraint: - custom_constraint: +The ``name`` 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. -The *name* specifies the concrete type of custom constraint. It corresponds to -the name under which the respective validation plugin has been registered with -the heat-engine. +For example:: -For example: - -:: - - parameters: - key_name - type: string - description: SSH key pair - constraints: - - custom_constraint: nova.keypair + parameters: + key_name + type: string + description: SSH key pair + constraints: + - custom_constraint: nova.keypair .. _hot_spec_pseudo_parameters: -Pseudo Parameters +Pseudo parameters ----------------- - In addition to parameters defined by a template author, Heat also creates three parameters for every stack that allow referential access to the stack's name, stack's identifier and project's identifier. These parameters are named ``OS::stack_name`` for the stack name, ``OS::stack_id`` for the stack identifier and ``OS::project_id`` for the project identifier. These values are -accessible via the `get_param`_ intrinsic function just like +accessible via the `get_param`_ intrinsic function, just like user-defined parameters. .. note:: @@ -496,175 +481,171 @@ user-defined parameters. .. _hot_spec_resources: ------------------ -Resources Section ------------------ -In the *resources* section, the templates for actual resources that will make up -a stack deployed from the HOT template (e.g. compute instances, networks, -storage volumes) are defined. -Each resource is defined as a separate block in the resources section according -to the syntax below. +Resources section +~~~~~~~~~~~~~~~~~ +The ``resources`` section defines actual resources that make up a stack +deployed from the HOT template (for instance compute instances, networks, +storage volumes). -:: +Each resource is defined as a separate block in the ``resources`` section with +the following syntax:: - resources: - : - type: - properties: - : - metadata: - - depends_on: - update_policy: - deletion_policy: + resources: + : + type: + properties: + : + metadata: + + depends_on: + update_policy: + deletion_policy: resource ID - A resource block is headed by the resource ID, which must be unique within - the resource section of a template. -type - This attribute specifies the type of resource, such as OS::Nova::Server. -properties - This *optional* section contains a list of resource specific properties. - The property value can be provided in place, or can be provided via a - function (see :ref:`hot_spec_intrinsic_functions`). -metadata - This *optional* section contains resource type specific metadata. -depends_on - This *optional* attribute allows for specifying dependencies of the current - resource on one or more other resources. Please refer to section - :ref:`hot_spec_resources_dependencies` for details. -update_policy: - This *optional* attribute allows for specifying an update policy for the - resource in the form of a nested dictionary (name-value pairs). Whether - update policies are supported and what the exact semantics are depends on - the type of the current resource. -deletion_policy: - This *optional* attribute allows for specifying a deletion policy for the - resource (one of the values Delete, Retain or Snapshot). Which type of - deletion policy is supported depends on the type of the current resource. + A resource ID which must be unique within the ``resources`` section of the + template. +type + The resource type, such as ``OS::Nova::Server`` or ``OS::Neutron::Port``. + This attribute is required. + +properties + A list of resource-specific properties. The property value can be provided + in place, or via a function (see :ref:`hot_spec_intrinsic_functions`). + This section is optional. + +metadata + Resource-specific metadata. + This section is optional. + +depends_on + Dependencies of the resource on one or more resources of the template. + See :ref:`hot_spec_resources_dependencies` for details. + This attribute is optional. + +update_policy + 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. + This attribute is optional. + +deletion_policy + Deletion policy for the resource. Which type of deletion policy is + supported depends on the type of the current resource. + This attribute is optional. Depending on the type of resource, the resource block might include more -resource specific data. Basically 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. -Below is an example of a simple compute resource definition with some fixed -property values. +resource specific data. -:: +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. - resources: - my_instance: - type: OS::Nova::Server - properties: - flavor: m1.small - image: F18-x86_64-cfntools +The following example demonstrates the definition of a simple compute resource +with some fixed property values:: + + resources: + my_instance: + type: OS::Nova::Server + properties: + flavor: m1.small + image: F18-x86_64-cfntools .. _hot_spec_resources_dependencies: -Resource Dependencies +Resource dependencies --------------------- +The ``depends_on`` attribute of a resource defines a dependency between this +resource and one or more other resources. -By means of the *depends_on* attribute within a resource section it is possible -to define a dependency between a resource and one or more other resources. If -a resource depends on just one other resource, the ID of the other resource is -specified as value of the *depends_on* attribute as shown in the following -example. +If a resource depends on just one other resource, the ID of the other resource +is specified as string of the ``depends_on`` attribute, as shown in the +following example:: -:: + resources: + server1: + type: OS::Nova::Server + depends_on: server2 - resources: - server1: - type: OS::Nova::Server - depends_on: server2 + server2: + type: OS::Nova::Server - server2: - type: OS::Nova::Server +If a resource depends on more than one other resources, the value of the +``depends_on`` attribute is specified as a list of resource IDs, as shown in +the following example:: -If a resource depends on more than one other resource, the value of the -*depends_on* attribute is specified as a list of resource IDs as shown in the -following example: + resources: + server1: + type: OS::Nova::Server + depends_on: [ server2, server3 ] -:: + server2: + type: OS::Nova::Server - resources: - server1: - type: OS::Nova::Server - depends_on: [ server2, server3 ] - - server2: - type: OS::Nova::Server - - server3: - type: OS::Nova::Server + server3: + type: OS::Nova::Server .. _hot_spec_outputs: ---------------- -Outputs Section ---------------- - -In the *outputs* section, any output parameters that should be available to the -user can be defined. Typically, this would be, for example, parameters such as -IP addresses of deployed instances, or URLs of web applications deployed as part -of a stack. +Outputs section +~~~~~~~~~~~~~~~ +The ``outputs`` section defines output parameters that should be available to +the user after 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. Each output parameter is defined as a separate block within the outputs section -according to the following syntax: +according to the following syntax:: -:: - - outputs: - : - description: - value: + outputs: + : + description: + value: parameter name - An output parameter block is headed by the output parameter name, which must - be unique within the outputs section of a template. + The output parameter name, which must be unique within the ``outputs`` + section of a template. + description - This element gives a short description of the output parameter. + A short description of the output parameter. + This attribute is optional. + parameter value - This element specifies the value of the output parameter. Typically, this - will be resolved by means of a function, e.g. by getting an attribute value - of one of the stack's resources (see also - :ref:`hot_spec_intrinsic_functions`). + The value of the output parameter. This value is usually resolved by means + of a function. See :ref:`hot_spec_intrinsic_functions` for details about + the functions. + This attribute is required. -The example below shows, how the IP address of a compute resource can be defined -as an output parameter. +The example below shows how the IP address of a compute resource can +be defined as an output parameter:: -:: - - outputs: - instance_ip: - description: IP address of the deployed compute instance - value: { get_attr: [my_instance, first_address] } + outputs: + instance_ip: + description: IP address of the deployed compute instance + value: { get_attr: [my_instance, first_address] } .. _hot_spec_intrinsic_functions: -------------------- -Intrinsic Functions -------------------- -HOT provides a set of intrinsic functions that can be used inside HOT templates +Intrinsic functions +~~~~~~~~~~~~~~~~~~~ +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. A definition of all intrinsic functions available in HOT is given -below. - +runtime. The following section describes the role and syntax of the intrinsic +functions. get_attr -------- -The *get_attr* function allows referencing an attribute of a resource. At -runtime, it will be resolved to the value of an attribute of a resource instance -created from the respective resource definition of the template. Path based -attribute refrencing using keys or indexes requires heat_template_version -'2014-10-16'or higher. -The syntax of the get_attr function is as follows: +The ``get_attr`` function references an attribute of a +resource. The attribute value is resolved at runtime using the resource +instance created from the respective resource definition. -:: +Path based attribute refrencing using keys or indexes requires +``heat_template_version`` '2014-10-16' or higher. + +The syntax of the ``get_attr`` function is:: get_attr: - @@ -674,69 +655,65 @@ The syntax of the get_attr function is as follows: - ... resource name - This parameter specifies the resource for which the attributes shall be - resolved. This resource must be defined within the *resources* section of - the template (see also :ref:`hot_spec_resources`). + The resource name for which the attribute needs to be resolved. + + The resource name must exist in the ``resources`` section of the template. + attribute name - The attribute name is required as it specifies the attribute - 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 - which navigate the data structure to return the desired value. + 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. -Some examples of how to use the get_attr function are shown below: +The following example demonstrates how to use the :code:`get_param` function:: -:: + resources: + my_instance: + type: OS::Nova::Server + # ... - 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] } - 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] } - -In this example, if the networks attribute contained the following data: - -:: +In this example, if the ``networks`` attribute contained the following data:: {"public": ["2001:0db8:0000:0000:0000:ff00:0042:8329", "1.2.3.4"], "private": ["10.0.0.1"]} -then the value of the get_attr function would resolve to "10.0.0.1". +then the value of :code:`the get_attr` function would resolve to ``10.0.0.1`` +(first item of the ``private`` entry in the ``networks`` map). get_file ------------- -The *get_file* function allows string content to be substituted into the -template. It is generally used as a file inclusion mechanism for files -containing non-heat scripts or configuration files. -The syntax of the get_file function is as follows: +-------- +The ``get_file`` 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. -:: +The syntax of ``the get_file`` function is:: - get_file: + get_file: -The *content key* will be used to look up the files dictionary that is -provided in the REST API call. The *heat* client command from -python-heatclient is *get_file* aware and will populate the *files* with -the actual content of fetched paths and URLs. The *heat* client command -supports relative paths and will transform these to absolute URLs which -will be used as the *content key* in the files dictionary. +The ``content key`` is used to look up the ``files`` dictionary that is +provided in the REST API call. The Orchestration client command +(``heat``) is ``get_file`` aware and populates the ``files`` +dictionary with the actual content of fetched paths and URLs. The +Orchestration client command supports relative paths and transforms these +to the absolute URLs required by the Orchestration API. -Note: The argument to *get_file* should be a static path or URL and not -rely on intrinsic functions like *get_param*. In general, the *heat* client -does not process intrinsic functions (they are only processed by the heat -server). +.. note:: + The ``get_file`` argument must be a static path or URL and not rely on + intrinsic functions like ``get_param``. the Orchestration client does not + process intrinsic functions (they are only processed by the Orchestration + engine). -The example below demonstrates *get_file* usage with both relative and -absolute URLs. - -:: +The example below demonstrates the ``get_file`` function usage with both +relative and absolute URLs:: resources: my_instance: @@ -752,113 +729,113 @@ absolute URLs. user_data: get_file: http://example.com/my_other_instance_user_data.sh -If this template was launched from a local file this would result in -a *files* dictionary containing entries with keys -*file:///path/to/my_instance_user_data.sh* and -*http://example.com/my_other_instance_user_data.sh*. +The ``files`` dictionary generated by the Orchestration client during +instantiation of the stack would contain the following keys: +* :file:`file:///path/to/my_instance_user_data.sh` +* :file:`http://example.com/my_other_instance_user_data.sh` get_param --------- -The *get_param* function allows for referencing an input parameter of a template -from anywhere within a template. At runtime, it will be resolved to the value -provided for this input parameter. The syntax of the *get_param* function is as -follows: +The ``get_param`` function references an input parameter of a template. It +resolves to the value provided for this input parameter at runtime. -:: +The syntax of the ``get_param`` function is:: - get_param: - - - - (optional) - - (optional) - - ... + get_param: + - + - (optional) + - (optional) + - ... parameter name - The parameter name is required as it specifies the parameter - to be resolved. If the parameter returns a complex data structure - such as a list or a map, then subsequent keys or indexes can be specified - which navigate the data structure to return the desired value. + 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. -A sample use of this function in context of a resource definition -is shown below. +The following example demonstrates the use of the ``get_param`` function:: -:: + parameters: + instance_type: + type: string + label: Instance Type + description: Instance type to be used. + server_data: + type: json - 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 ] } - 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 ] } +In this example, if the ``instance_type`` and ``server_data`` parameters +contained the following data:: + {"instance_type": "m1.tiny", + {"server_data": {"metadata": {"foo": "bar"}, + "keys": ["a_key","other_key"]}}} -In this example, if the instance_type/server_data parameters contained -the following data: - -:: - - {"instance_type": "m1.tiny", - {"server_data": {"metadata": {"foo": "bar"}, - "keys": ["a_key","other_key"]}}} - -then the value of the property 'flavor' would resolve to "m1.tiny", 'metadata' -would resolve to {"foo": "bar"} and 'key_name' would resolve to "a_key". +then the value of the property ``flavor`` would resolve to ``m1.tiny``, +``metadata`` would resolve to ``{"foo": "bar"}`` and ``key_name`` would resolve +to ``a_key``. get_resource ------------ -The *get_resource* function allows for referencing another resource within the -same template. At runtime, it will be resolved to reference ID of the resource, -which is resource type specific. For example, a reference to a floating IP -resource will return the respective IP address at runtime. -The syntax of the get_resource function is as follows: +The ``get_resource`` 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 ``get_resource`` function is:: -:: + get_resource: - get_resource: +The resource ID of the referenced resource is given as single parameter to the +get_resource function. -The *resource ID* of the referenced resources as used in the current template is -given as single parameter to the get_resource function. +For example:: + + resources: + instance_port: + type: OS::Neutron::Port + properties: ... + + instance: + type: OS::Nova::Server + properties: + ... + networks: + port: { get_resource: instance_port } list_join --------- -The *list_join* function joins a list of strings with the given delimiter. This -function is introduced in the Juno release, usable in HOT versions later than -`2013-05-23`. The syntax of the list_join function is as follows: +The ``list_join`` function joins a list of strings with the given +delimiter. -:: +The syntax of the ``list_join`` function is:: - list_join: - - - - + list_join: + - + - -A sample use of this function with a simple list is shown below. +For example:: -:: + list_join: [', ', ['one', 'two', 'and three']] - list_join: [', ', ['one', 'two', 'and three']] - -This would resolve to "one, two, and three". +This resolve to the string ``one, two, and three``. digest -------- -The *digest* function allows for performing digest operations on a given value. +The ``digest`` function allows for performing digest operations on a given value. This function has been introduced in the Kilo release and is usable with HOT versions -later than `2015-04-30`. +later than 2015-04-30. -The syntax of the digest function is as follows: - -:: +The syntax of the digest function is:: digest: - @@ -873,27 +850,23 @@ value the value. -An example of how to use the digest function is shown below: - -:: +For example:: # from a user supplied parameter pwd_hash: { digest: ['sha512', { get_param: raw_password }] } The value of the digest function would resolve to the corresponding hash of -the value of 'raw_password'. +the value of ``raw_password``. repeat ------ -The *repeat* function allows for dynamically transforming lists by iterating +The ``repeat`` function allows for dynamically transforming lists by iterating over the contents of one or more source lists and replacing the list elements into a template. The result of this function is a new list, where the elements are set to the template, rendered for each list item. -The syntax of the repeat function is as follows: - -:: +The syntax of the repeat function is:: repeat: template: @@ -902,11 +875,11 @@ The syntax of the repeat function is as follows: : template - The *template* argument defines the content generated for each iteration, + The ``template`` argument defines the content generated for each iteration, with placeholders for the elements that need to be replaced at runtime. This argument can be of any supported type. for_each - The *for_each* argument is a dictionary that defines how to generate the + The ``for_each`` argument is a dictionary that defines how to generate the repetitions of the template and perform substitutions. In this dictionary the keys are the placeholder names that will be replaced in the template, and the values are the lists to iterate on. On each iteration, the function @@ -915,12 +888,10 @@ for_each template will be rendered once for each element in the list. When more than one key/value pairs are given, the iterations will be performed on all the permutations of values between the given lists. The values in this - dictionary can be given as functions such as get_attr or get_param. + dictionary can be given as functions such as ``get_attr`` or ``get_param``. -The example below shows how a security group resource can be defined to -include a list of ports given as a parameter. - -:: +The following example shows how a security group resource can be defined to +include a list of ports given as a parameter:: parameters: ports: @@ -942,10 +913,8 @@ include a list of ports given as a parameter. port_range_min: %port% port_range_max: %port% -The next example demonstrates how the use of multiple lists enables the -security group to also include parameterized protocols. - -:: +The following example demonstrates how the use of multiple lists enables the +security group to also include parameterized protocols:: parameters: ports: @@ -977,96 +946,90 @@ nested for-loops in most programming languages. resource_facade --------------- -The *resource_facade* function allows a provider template to retrieve data -about its resource facade in the parent template. A provider template is used -to provide a custom definition of a resource - the facade - in the form of a -Heat template. The resource's properties are passed to the provider template as -its parameters, but other resource data can be included using this function.) +The ``resource_facade`` function retrieves data in a parent +provider template. -The syntax of the *resource_facade* function is as follows:: +A provider template provides a custom definition of a resource, called its +facade. For more information about custom templates, see :ref:`composition`. +The syntax of the ``resource_facade`` function is:: - resource_facade: + resource_facade: -The *data type* can be `metadata`, `deletion_policy` or `update_policy`. +``data type`` can be one of ``metadata``, ``deletion_policy`` or +``update_policy``. str_replace ----------- -The *str_replace* function allows for dynamically constructing strings by +The ``str_replace`` 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. -The syntax of the str_replace function is as follows: -:: +The syntax of the ``str_replace`` function is:: - str_replace: - template: