diff --git a/doc/hot-guide/source/hot_spec.rst b/doc/hot-guide/source/hot_spec.rst index 2db9c224f1..3b1bd9d8c8 100644 --- a/doc/hot-guide/source/hot_spec.rst +++ b/doc/hot-guide/source/hot_spec.rst @@ -14,43 +14,24 @@ .. _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 format (CFN) as the native format supported -by the Heat over time. 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:`hello_world`. - ------- -Status ------- - -HOT is considered reliable, supported, and standardized as of our -Icehouse (April 2014) release. The Heat core team may make -improvements to the standard, which very likely would be backward -compatible. The template format is also versioned. In our Juno -release, Heat will support multiple different versions of the HOT -specification if there is a need driven by the introduction of new -features. - - ------------------ -Template Structure +Template structure ------------------ -HOT templates are defined in YAML and follow the structure outlined below. +HOT templates are defined in YAML and use the following structure: -:: +.. code-block:: yaml heat_template_version: 2013-05-23 description: - # a description of the template + # description of the template parameter_groups: - # a declaration of input parameter groups and order + # declaration of input parameter groups and order parameters: # declaration of input parameters @@ -62,52 +43,55 @@ 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 - document is a HOT template of the specified version. + 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 - workload that can be deployed using the template. + This optional key gives 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. + This section specifies how the input parameters should be + grouped and the order to provide the parameters in. + + This section is optional. parameters - This section allows for specifying input parameters that have to - be provided when instantiating the template. The section is - *optional* and can be omitted when no input is required. + This section specifies input parameters that have to + be provided when instantiating the template. + + This section is optional. resources - This section contains the declaration of the single resources of the - template. This section with at least one resource should be defined in any - HOT template, or the template would not really do anything when being + This section contains the declaration of the resources of the template. + This section with at least one resource must be defined in any HOT + template, or the template would not really do anything when being instantiated. outputs - This section allows for specifying output parameters available to - users once the template has been instantiated. This section is - *optional* and can be omitted when no output values are required. + This section specifies output parameters available to users once the + template has been instantiated. + + This section is optional. .. _hot_spec_parameter_groups: ------------------------ -Parameter Groups Section +Parameter groups section ------------------------ -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. +The ``parameter_groups`` section specifies 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 -section. +parameters. A parameter can only be included in one group. Use the name of the +parameter to add it to a group. The parameters details are defined in +the ``parameters`` section. -:: +.. code-block:: yaml parameter_groups: - label: @@ -120,33 +104,31 @@ label A human-readable label that defines the associated group of parameters. description - This attribute allows for giving a human-readable description of the - parameter group. + A human-readable description of the parameter group. parameters - A list of parameters associated with this parameter group. + A list of parameters that belong with this parameter group. param name - The name of the parameter that is defined in the associated parameters - section. + The name of a parameter defined in the ``parameters`` section. .. _hot_spec_parameters: ------------------ -Parameters Section +Parameters section ------------------ -The *parameters* section allows for specifying input parameters that have to be +The ``parameters`` section defines 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. +customize each deployment, or for binding to environment specifics like certain +images. Each parameter is specified in a separated nested block with the name of the -parameters defined in the first line and additional attributes such as type or -default value defined as nested elements. +parameter defined in the first line and additional attributes such as a type or +a default value defined as nested elements: -:: +.. code-block:: yaml parameters: : @@ -159,40 +141,46 @@ 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``. 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. -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. + This attribute is optional. -:: +The following example shows a minimalistic definition of two parameters: + +.. code-block:: yaml parameters: user_name: @@ -204,48 +192,50 @@ 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 +Parameter constraints --------------------- -The *constraints* block of a parameter definition allows for defining +The ``constraints`` block of a parameter definition defines 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 +parameter. The parameter values provided by a user are validated against the +contrainsts at instantiation time. The contrainsts are defined as a list with the following syntax: -:: +.. code-block:: yaml 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 ommitted, a default validation message is presented to the user. -The following example show the definition of a string parameter with two + This attribute is optional. + +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. -:: +.. code-block:: yaml parameters: user_name: @@ -258,57 +248,69 @@ 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. +with the 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: + +.. code-block:: yaml 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: + +.. code-block:: yaml 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: + +.. code-block:: yaml 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: + +.. code-block:: yaml allowed_values: [ , , ... ] -Alternatively, the YAML bulleted list notation can be used: +Alternatively, the following YAML list notation can be used: -:: +.. code-block:: yaml allowed_values: - @@ -317,7 +319,7 @@ Alternatively, the YAML bulleted list notation can be used: For example: -:: +.. code-block:: yaml parameters: instance_type: @@ -332,18 +334,20 @@ For example: 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: + +.. code-block:: yaml allowed_pattern: For example: -:: +.. code-block:: yaml parameters: user_name: @@ -357,24 +361,25 @@ For example: 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 syntax of the custom_constraint constraint is: +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: + +.. code-block:: yaml custom_constraint: -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. +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. For example: -:: +.. code-block:: yaml parameters: key_name @@ -388,25 +393,27 @@ For example: Pseudo Parameters ----------------- -In addition to parameters defined by a template author, Heat also creates two -parameters for every stack that allow referential access to the stack's name -and identifier. These parameters are named ``OS::stack_name`` for the stack -name and ``OS::stack_id`` for the stack identifier. These values are accessible -via the ``get_param`` intrinsic function just like user-defined parameters. +In addition to parameters defined by a template author, the Orchestration +module also creates two parameters for every stack that allow referential +access to the stack's name and identifier. These parameters are named +``OS::stack_name`` for the stack name and ``OS::stack_id`` for the stack +identifier. These values are accessible via the ``get_param`` intrinsic +function, just like user-defined parameters. .. _hot_spec_resources: ----------------- -Resources Section +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. +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: + +.. code-block:: yaml resources: : @@ -420,39 +427,53 @@ according to the syntax below. 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``. + +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. + +The following example demonstrates the definition of a simple compute resource +with some fixed property values: + +.. code-block:: yaml resources: my_instance: @@ -464,16 +485,17 @@ property values. .. _hot_spec_resources_dependencies: -Resource Dependencies +Resource dependencies --------------------- -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. +The ``depends_on`` attribute of a resource defines a dependency between this +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 string of the ``depends_on`` attribute, as shown in the +following example: + +.. code-block:: yaml resources: server1: @@ -483,11 +505,11 @@ example. server2: type: OS::Nova::Server -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: +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: -:: +.. code-block:: yaml resources: server1: @@ -504,18 +526,18 @@ following example: .. _hot_spec_outputs: --------------- -Outputs Section +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. +The ``outputs`` section defines output parameters that should be available to +the user once 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: -:: +.. code-block:: yaml outputs: : @@ -523,20 +545,21 @@ according to the following syntax: 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. + 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. -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: -:: +.. code-block:: yaml outputs: instance_ip: @@ -547,23 +570,24 @@ be defined as an output parameter. .. _hot_spec_intrinsic_functions: ------------------- -Intrinsic Functions +Intrinsic functions ------------------- -HOT provides a set of intrinsic functions that can be used inside HOT 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. +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. 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. -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. + +The syntax of the ``get_attr`` function is: + +.. code-block:: yaml get_attr: - @@ -573,18 +597,19 @@ The syntax of the get_attr function is as follows: - ... resource ID - 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 ID for which the attribute needs to be resolved. + + The resource ID 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 ``get_param`` function: -:: +.. code-block:: yaml resources: my_instance: @@ -601,41 +626,45 @@ Some examples of how to use the get_attr function are shown below: In this example, if the networks attribute contained the following data: -:: +.. code-block:: yaml {"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 ``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: + +.. code-block:: yaml 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 +(:command:`heat`) is ``get_file`` aware and will populate the ``files`` +dictionnary with the actual content of fetched paths and URLs. The +Orchestration client command supports relative paths and will transform these +to the absolute URLs required by the Orcestration 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: -:: +.. code-block:: yaml resources: my_instance: @@ -644,6 +673,7 @@ absolute URLs. # general properties ... user_data: get_file: my_instance_user_data.sh + my_other_instance: type: OS::Nova::Server properties: @@ -651,20 +681,21 @@ 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:///path/to/my_instance_user_data.sh`` +* ``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: + +.. code-block:: yaml get_param: - @@ -673,15 +704,14 @@ the get_param function is as follows: - ... 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: -:: +.. code-block:: yaml parameters: instance_type: @@ -700,98 +730,120 @@ is shown below. key_name: { get_param: [ server_data, keys, 0 ] } -In this example, if the instance_type/server_data parameters contained -the following data: +In this example, if the ``instance_type`` and ``server_data`` parameters +contained the following data: -:: +.. code-block:: yaml {"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: + +.. code-block:: yaml get_resource: -The *resource ID* of the referenced resources as used in the current -template is given as single parameter to the get_resource function. +The resource ID of the referenced resource is given as single parameter to the +get_resource function. + +For exemple: + +.. code-block:: yaml + + 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. -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: + +.. code-block:: yaml list_join: - - -A sample use of this function with a simple list is shown below. +For example: -:: +.. code-block:: yaml list_join: [', ', ['one', 'two', 'and three']] -This would resolve to "one, two, and three". +This resolve to the string ``one, two, and three``. 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 syntax of the -*resource_facade* function is as follows:: +The ``resource_facade`` function retrieves data in a parent provider template. + +A provider template provdes 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: + +.. code-block:: yaml 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: + +.. code-block:: yaml str_replace: template: