86
This section allows for specifying output parameters available to users once
87
the template has been instantiated. This section is *optional* and can be
88
omitted when no output values are required.
88
This section allows for specifying output parameters available to users
89
once the template has been instantiated. This section is optional and can
90
be omitted when no output values are required.
91
93
.. _hot_spec_template_version:
97
The value of *heat_template_version* tells Heat not only the format of the
98
The value of ``heat_template_version`` tells Heat not only the format of the
98
99
template but also features that will be validated and supported.
99
100
For example, Heat currently supports the following values for the
100
*heat_template_version* key:
101
``heat_template_version`` key:
103
The key with value *2013-05-23* indicates that the YAML document is a HOT
104
template and it may contain features implemented until the Icehouse release.
105
This version supports the following functions (some are back ported
104
The key with value ``2013-05-23`` indicates that the YAML document is a HOT
105
template and it may contain features implemented until the Icehouse
106
release. This version supports the following functions (some are back
107
ported to this version)::
127
The key with value *2014-10-16* indicates that the YAML document is a HOT
127
The key with value ``2014-10-16`` indicates that the YAML document is a HOT
128
128
template and it may contain features added and/or removed up until the Juno
129
129
release. This version removes most CFN functions that were supported in
130
the Icehouse release, i.e. the *2013-05-23* version. So the supported functions
130
the Icehouse release, i.e. the ``2013-05-23`` version. So the supported
144
The key with value *2015-04-30* indicates that the YAML document is a HOT
143
The key with value ``2015-04-30`` indicates that the YAML document is a HOT
145
144
template and it may contain features added and/or removed up until the Kilo
146
release. This version adds the *repeat* function. So the complete list of
147
supported functions is:
145
release. This version adds the ``repeat`` function. So the complete list of
146
supported functions is::
160
The key with value ``2015-10-15`` indicates that the YAML document is a HOT
161
template and it may contain features added and/or removed up until the
162
Liberty release. This version removes the *Fn::Select* function, path based
163
``get_attr``/``get_param`` references should be used instead.
227
241
<parameter constraints>
230
The name of the parameter is defined at the top of each parameter block.
244
The name of the parameter.
233
This attribute specifies the type of parameter. Currently supported types
234
are *string*, *number*, *comma_delimited_list*, *json*, or *boolean*.
247
The type of the parameter. Supported types
248
are ``string``, ``number``, ``comma_delimited_list``, ``json`` and
250
This attribute is required.
237
This *optional* attribute allows for giving a human readable name of the
253
A human readable name for the parameter.
254
This attribute is optional.
241
This *optional* attribute allows for giving a human readable description of
257
A human readable description for the parameter.
258
This attribute is optional.
245
This *optional* attribute allows for defining a default value for the
246
parameters which will be used in case the parameter is not specified by the
247
user during deployment.
261
A default value for the parameter. This value is used if the user doesn't
262
specify his own value during deployment.
263
This attribute is optional.
250
This *optional* attribute allows for specifying whether the parameters
251
should be hidden when showing information about a stack created from the
252
template at runtime (e.g. for hiding passwords that were specified as
253
parameters). If not specified, the default value 'false' will be used.
266
Defines whether the parameters should be hidden when a user requests
267
information about a stack created from the template. This attribute can be
268
used to hide passwords specified as parameters.
270
This attribute is optional and defaults to ``false``.
256
This *optional* block allows for specifying additional constraints on the
257
parameter, such as minimum or maximum values for numeric parameters.
273
A list of constraints to apply. The constraints are validated by the
274
Orchestration engine when a user deploys a stack. The stack creation fails
275
if the parameter value doesn't comply to the constraints.
276
This attribute is optional.
259
278
The table below describes all currently supported types with examples:
297
312
label: Port Number
298
313
description: Port number to be configured for the web server
316
The description and the label are optional, but defining these attributes
317
is good practice to provide useful information about the role of the
318
parameter to the user.
301
320
.. _hot_spec_parameters_constraints:
303
322
Parameter Constraints
304
323
---------------------
306
The *constraints* block of a parameter definition allows for defining additional
307
validation constraints that apply to the value of the parameter. At
308
instantiation time of the template, user provided parameter values are validated
309
against those constraints to make sure the provided values match expectations of
311
Constraints are defined in the form of a bulleted list according to the
325
The ``constraints`` block of a parameter definition defines
326
additional validation constraints that apply to the value of the
327
parameter. The parameter values provided by a user are validated against the
328
constraints at instantiation time. The constraints are defined as a list with
329
the following syntax::
317
332
- <constraint type>: <constraint definition>
318
333
description: <constraint description>
321
The constraint type specifies the kind of constraint defined in the current
322
bulleted list item. The set of currently supported constraints is given
336
Type of constraint to apply. The set of currently supported constraints is
325
339
constraint definition
326
This value defines the actual constraint, depending on the constraint type.
327
The concrete syntax for each constraint type is given below.
340
The actual constraint, depending on the constraint type. The
341
concrete syntax for each constraint type is given below.
330
This *optional* attribute allows for specifying a concrete description of
331
the current constraint. This text will be presented to the user, for
332
example, when the provided input value for a parameter violates the
333
constraint. If omitted, a default validation message will be presented to
344
A description of the constraint. The text
345
is presented to the user when the value he defines violates the constraint.
346
If omitted, a default validation message is presented to the user.
347
This attribute is optional.
336
The following example show the definition of a string parameter with two
349
The following example shows the definition of a string parameter with two
337
350
constraints. Note that while the descriptions for each constraint are optional,
338
it is good practice to provide concrete descriptions so useful messages can be
339
presented to the user at deployment time.
351
it is good practice to provide concrete descriptions to present useful messages
352
to the user at deployment time.
351
364
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
352
365
description: User name must start with an uppercase character
368
While the descriptions for each constraint are optional, it is good practice
369
to provide concrete descriptions so useful messages can be presented to the
370
user at deployment time.
354
372
The following sections list the supported types of parameter constraints, along
355
373
with the concrete syntax for each type.
359
The *length* constraint applies to parameters of type *string* and allows for
360
defining a lower and upper limit for the length of the string value. The syntax
361
for the length constraint is:
365
length: { min: <lower limit>, max: <upper limit> }
377
The ``length`` constraint applies to parameters of type
378
``string``. It defines a lower and upper limit for the length of the
381
The syntax of the ``length`` constraint is::
383
length: { min: <lower limit>, max: <upper limit> }
367
385
It is possible to define a length constraint with only a lower limit or an
368
upper limit. However, at least one of *min* or *max* must be specified.
386
upper limit. However, at least one of ``min`` or ``max`` must be specified.
372
The *range* constraint applies to parameters of type *number* and allows for
373
defining a lower and upper limit for the numeric value of the parameter. The
374
syntax of the range constraint is:
378
range: { min: <lower limit>, max: <upper limit> }
390
The ``range`` constraint applies to parameters of type ``number``.
391
It defines a lower and upper limit for the numeric value of the
394
The syntax of the ``range`` constraint is::
396
range: { min: <lower limit>, max: <upper limit> }
380
398
It is possible to define a range constraint with only a lower limit or an
381
upper limit. However, at least one of *min* or *max* must be specified.
382
The minimum or maximum boundaries are included in the range. For example, the
383
following range constraint would allow for all numeric values between 0 and 10.
387
range: { min: 0, max: 10 }
399
upper limit. However, at least one of ``min`` or ``max`` must be specified.
401
The minimum and maximum boundaries are included in the range. For example, the
402
following range constraint would allow for all numeric values between 0 and
405
range: { min: 0, max: 10 }
392
The *allowed_values* constraint applies to parameters of type string or number
393
and allows for specifying a set of possible values for a parameter. At
394
deployment time, the user provided value for the respective parameter must
395
match one of the elements of the specified list. The syntax of the
396
allowed_values constraint is:
400
allowed_values: [ <value>, <value>, ... ]
402
Alternatively, the YAML bulleted list notation can be used:
419
description: Instance type for compute instances
410
The ``allowed_values`` constraint applies to parameters of type
411
``string`` or ``number``. It specifies a set of possible values for a
412
parameter. At deployment time, the user-provided value for the
413
respective parameter must match one of the elements of the list.
415
The syntax of the ``allowed_values`` constraint is::
417
allowed_values: [ <value>, <value>, ... ]
419
Alternatively, the following YAML list notation can be used::
432
description: Instance type for compute instances
428
The *allowed_pattern* constraint applies to parameters of type string and allows
429
for specifying a regular expression against which a user provided parameter
430
value must evaluate at deployment.
431
The syntax of the allowed_pattern constraint is:
435
allowed_pattern: <regular expression>
445
description: User name to be configured for the application
447
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
441
The ``allowed_pattern`` constraint applies to parameters of type
442
``string``. It specifies a regular expression against which a
443
user-provided parameter value must evaluate at deployment.
445
The syntax of the ``allowed_pattern`` constraint is::
447
allowed_pattern: <regular expression>
455
description: User name to be configured for the application
457
- allowed_pattern: "[A-Z]+[a-zA-Z0-9]*"
448
458
description: User name must start with an uppercase character
451
461
custom_constraint
453
The *custom_constraint* constraint adds an extra step of validation, generally
454
to check that the specified resource exists in the backend. Custom constraints
455
get implemented by plug-ins and can provide any kind of advanced constraint
458
The syntax of the custom_constraint constraint is:
462
custom_constraint: <name>
464
The *name* specifies the concrete type of custom constraint. It corresponds to
465
the name under which the respective validation plugin has been registered with
475
description: SSH key pair
477
- custom_constraint: nova.keypair
463
The ``custom_constraint`` constraint adds an extra step of validation,
464
generally to check that the specified resource exists in the backend. Custom
465
constraints get implemented by plug-ins and can provide any kind of advanced
466
constraint validation logic.
468
The syntax of the ``custom_constraint`` constraint is::
470
custom_constraint: <name>
472
The ``name`` attribute specifies the concrete type of custom constraint. It
473
corresponds to the name under which the respective validation plugin has been
474
registered in the Orchestration engine.
481
description: SSH key pair
483
- custom_constraint: nova.keypair
479
485
.. _hot_spec_pseudo_parameters:
482
488
-----------------
484
489
In addition to parameters defined by a template author, Heat also
485
490
creates three parameters for every stack that allow referential access
486
491
to the stack's name, stack's identifier and project's
487
492
identifier. These parameters are named ``OS::stack_name`` for the
488
493
stack name, ``OS::stack_id`` for the stack identifier and
489
494
``OS::project_id`` for the project identifier. These values are
490
accessible via the `get_param`_ intrinsic function just like
495
accessible via the `get_param`_ intrinsic function, just like
491
496
user-defined parameters.
497
502
.. _hot_spec_resources:
503
In the *resources* section, the templates for actual resources that will make up
504
a stack deployed from the HOT template (e.g. compute instances, networks,
505
storage volumes) are defined.
506
Each resource is defined as a separate block in the resources section according
513
type: <resource type>
515
<property name>: <property value>
517
<resource specific metadata>
518
depends_on: <resource ID or list of ID>
519
update_policy: <update policy>
520
deletion_policy: <deletion policy>
507
The ``resources`` section defines actual resources that make up a stack
508
deployed from the HOT template (for instance compute instances, networks,
511
Each resource is defined as a separate block in the ``resources`` section with
512
the following syntax::
516
type: <resource type>
518
<property name>: <property value>
520
<resource specific metadata>
521
depends_on: <resource ID or list of ID>
522
update_policy: <update policy>
523
deletion_policy: <deletion policy>
523
A resource block is headed by the resource ID, which must be unique within
524
the resource section of a template.
526
A resource ID which must be unique within the ``resources`` section of the
526
This attribute specifies the type of resource, such as OS::Nova::Server.
530
The resource type, such as ``OS::Nova::Server`` or ``OS::Neutron::Port``.
531
This attribute is required.
528
This *optional* section contains a list of resource specific properties.
529
The property value can be provided in place, or can be provided via a
530
function (see :ref:`hot_spec_intrinsic_functions`).
534
A list of resource-specific properties. The property value can be provided
535
in place, or via a function (see :ref:`hot_spec_intrinsic_functions`).
536
This section is optional.
532
This *optional* section contains resource type specific metadata.
539
Resource-specific metadata.
540
This section is optional.
534
This *optional* attribute allows for specifying dependencies of the current
535
resource on one or more other resources. Please refer to section
536
:ref:`hot_spec_resources_dependencies` for details.
538
This *optional* attribute allows for specifying an update policy for the
539
resource in the form of a nested dictionary (name-value pairs). Whether
540
update policies are supported and what the exact semantics are depends on
541
the type of the current resource.
543
This *optional* attribute allows for specifying a deletion policy for the
544
resource (one of the values Delete, Retain or Snapshot). Which type of
545
deletion policy is supported depends on the type of the current resource.
543
Dependencies of the resource on one or more resources of the template.
544
See :ref:`hot_spec_resources_dependencies` for details.
545
This attribute is optional.
548
Update policy for the resource, in the form of a nested dictionary. Whether
549
update policies are supported and what the exact semantics are depends on
550
the type of the current resource.
551
This attribute is optional.
554
Deletion policy for the resource. Which type of deletion policy is
555
supported depends on the type of the current resource.
556
This attribute is optional.
548
558
Depending on the type of resource, the resource block might include more
549
resource specific data. Basically all resource types that can be used in
550
CFN templates can also be used in HOT templates, adapted to the YAML structure
552
Below is an example of a simple compute resource definition with some fixed
559
type: OS::Nova::Server
562
image: F18-x86_64-cfntools
559
resource specific data.
561
All resource types that can be used in CFN templates can also be used in HOT
562
templates, adapted to the YAML structure as outlined above.
564
The following example demonstrates the definition of a simple compute resource
565
with some fixed property values::
569
type: OS::Nova::Server
572
image: F18-x86_64-cfntools
565
575
.. _hot_spec_resources_dependencies:
567
Resource Dependencies
577
Resource dependencies
568
578
---------------------
570
By means of the *depends_on* attribute within a resource section it is possible
571
to define a dependency between a resource and one or more other resources. If
572
a resource depends on just one other resource, the ID of the other resource is
573
specified as value of the *depends_on* attribute as shown in the following
580
type: OS::Nova::Server
584
type: OS::Nova::Server
586
If a resource depends on more than one other resource, the value of the
587
*depends_on* attribute is specified as a list of resource IDs as shown in the
594
type: OS::Nova::Server
595
depends_on: [ server2, server3 ]
598
type: OS::Nova::Server
601
type: OS::Nova::Server
579
The ``depends_on`` attribute of a resource defines a dependency between this
580
resource and one or more other resources.
582
If a resource depends on just one other resource, the ID of the other resource
583
is specified as string of the ``depends_on`` attribute, as shown in the
588
type: OS::Nova::Server
592
type: OS::Nova::Server
594
If a resource depends on more than one other resources, the value of the
595
``depends_on`` attribute is specified as a list of resource IDs, as shown in
596
the following example::
600
type: OS::Nova::Server
601
depends_on: [ server2, server3 ]
604
type: OS::Nova::Server
607
type: OS::Nova::Server
604
610
.. _hot_spec_outputs:
610
In the *outputs* section, any output parameters that should be available to the
611
user can be defined. Typically, this would be, for example, parameters such as
612
IP addresses of deployed instances, or URLs of web applications deployed as part
614
The ``outputs`` section defines output parameters that should be available to
615
the user after a stack has been created. This would be, for example, parameters
616
such as IP addresses of deployed instances, or URLs of web applications
617
deployed as part of a stack.
615
619
Each output parameter is defined as a separate block within the outputs section
616
according to the following syntax:
622
description: <description>
623
value: <parameter value>
620
according to the following syntax::
624
description: <description>
625
value: <parameter value>
626
An output parameter block is headed by the output parameter name, which must
627
be unique within the outputs section of a template.
628
The output parameter name, which must be unique within the ``outputs``
629
section of a template.
629
This element gives a short description of the output parameter.
632
A short description of the output parameter.
633
This attribute is optional.
631
This element specifies the value of the output parameter. Typically, this
632
will be resolved by means of a function, e.g. by getting an attribute value
633
of one of the stack's resources (see also
634
:ref:`hot_spec_intrinsic_functions`).
636
The example below shows, how the IP address of a compute resource can be defined
637
as an output parameter.
643
description: IP address of the deployed compute instance
644
value: { get_attr: [my_instance, first_address] }
636
The value of the output parameter. This value is usually resolved by means
637
of a function. See :ref:`hot_spec_intrinsic_functions` for details about
639
This attribute is required.
641
The example below shows how the IP address of a compute resource can
642
be defined as an output parameter::
646
description: IP address of the deployed compute instance
647
value: { get_attr: [my_instance, first_address] }
647
650
.. _hot_spec_intrinsic_functions:
652
HOT provides a set of intrinsic functions that can be used inside HOT templates
654
HOT provides a set of intrinsic functions that can be used inside templates
653
655
to perform specific tasks, such as getting the value of a resource attribute at
654
runtime. A definition of all intrinsic functions available in HOT is given
656
runtime. The following section describes the role and syntax of the intrinsic
660
The *get_attr* function allows referencing an attribute of a resource. At
661
runtime, it will be resolved to the value of an attribute of a resource instance
662
created from the respective resource definition of the template. Path based
663
attribute refrencing using keys or indexes requires heat_template_version
664
'2014-10-16'or higher.
665
The syntax of the get_attr function is as follows:
662
The ``get_attr`` function references an attribute of a
663
resource. The attribute value is resolved at runtime using the resource
664
instance created from the respective resource definition.
666
Path based attribute referencing using keys or indexes requires
667
``heat_template_version`` ``2014-10-16`` or higher.
669
The syntax of the ``get_attr`` function is::
670
672
- <resource name>
677
This parameter specifies the resource for which the attributes shall be
678
resolved. This resource must be defined within the *resources* section of
679
the template (see also :ref:`hot_spec_resources`).
679
The resource name for which the attribute needs to be resolved.
681
The resource name must exist in the ``resources`` section of the template.
681
The attribute name is required as it specifies the attribute
682
to be resolved. If the attribute returns a complex data structure
683
such as a list or a map, then subsequent keys or indexes can be specified
684
which navigate the data structure to return the desired value.
686
Some examples of how to use the get_attr function are shown below:
692
type: OS::Nova::Server
697
description: IP address of the deployed compute instance
698
value: { get_attr: [my_instance, first_address] }
700
description: Private IP address of the deployed compute instance
701
value: { get_attr: [my_instance, networks, private, 0] }
703
In this example, if the networks attribute contained the following data:
684
The attribute name to be resolved. If the attribute returns a complex data
685
structure such as a list or a map, then subsequent keys or indexes can be
686
specified. These additional parameters are used to navigate the data
687
structure to return the desired value.
689
The following example demonstrates how to use the :code:`get_attr` function::
693
type: OS::Nova::Server
698
description: IP address of the deployed compute instance
699
value: { get_attr: [my_instance, first_address] }
701
description: Private IP address of the deployed compute instance
702
value: { get_attr: [my_instance, networks, private, 0] }
704
In this example, if the ``networks`` attribute contained the following data::
707
706
{"public": ["2001:0db8:0000:0000:0000:ff00:0042:8329", "1.2.3.4"],
708
707
"private": ["10.0.0.1"]}
710
then the value of the get_attr function would resolve to "10.0.0.1".
709
then the value of :code:`get_attr` function would resolve to ``10.0.0.1``
710
(first item of the ``private`` entry in the ``networks`` map).
715
The *get_file* function allows string content to be substituted into the
716
template. It is generally used as a file inclusion mechanism for files
717
containing non-heat scripts or configuration files.
718
The syntax of the get_file function is as follows:
722
get_file: <content key>
724
The *content key* will be used to look up the files dictionary that is
725
provided in the REST API call. The *heat* client command from
726
python-heatclient is *get_file* aware and will populate the *files* with
727
the actual content of fetched paths and URLs. The *heat* client command
728
supports relative paths and will transform these to absolute URLs which
729
will be used as the *content key* in the files dictionary.
731
Note: The argument to *get_file* should be a static path or URL and not
732
rely on intrinsic functions like *get_param*. In general, the *heat* client
733
does not process intrinsic functions (they are only processed by the heat
736
The example below demonstrates *get_file* usage with both relative and
715
The ``get_file`` function returns the content of a file into the template.
716
It is generally used as a file inclusion mechanism for files
717
containing scripts or configuration files.
719
The syntax of ``get_file`` function is::
721
get_file: <content key>
723
The ``content key`` is used to look up the ``files`` dictionary that is
724
provided in the REST API call. The Orchestration client command
725
(``heat``) is ``get_file`` aware and populates the ``files``
726
dictionary with the actual content of fetched paths and URLs. The
727
Orchestration client command supports relative paths and transforms these
728
to the absolute URLs required by the Orchestration API.
731
The ``get_file`` argument must be a static path or URL and not rely on
732
intrinsic functions like ``get_param``. the Orchestration client does not
733
process intrinsic functions (they are only processed by the Orchestration
736
The example below demonstrates the ``get_file`` function usage with both
737
relative and absolute URLs::
753
751
get_file: http://example.com/my_other_instance_user_data.sh
755
If this template was launched from a local file this would result in
756
a *files* dictionary containing entries with keys
757
*file:///path/to/my_instance_user_data.sh* and
758
*http://example.com/my_other_instance_user_data.sh*.
753
The ``files`` dictionary generated by the Orchestration client during
754
instantiation of the stack would contain the following keys:
756
* :file:`file:///path/to/my_instance_user_data.sh`
757
* :file:`http://example.com/my_other_instance_user_data.sh`
763
The *get_param* function allows for referencing an input parameter of a template
764
from anywhere within a template. At runtime, it will be resolved to the value
765
provided for this input parameter. The syntax of the *get_param* function is as
772
- <key/index 1> (optional)
773
- <key/index 2> (optional)
762
The ``get_param`` function references an input parameter of a template. It
763
resolves to the value provided for this input parameter at runtime.
765
The syntax of the ``get_param`` function is::
769
- <key/index 1> (optional)
770
- <key/index 2> (optional)
777
The parameter name is required as it specifies the parameter
778
to be resolved. If the parameter returns a complex data structure
779
such as a list or a map, then subsequent keys or indexes can be specified
780
which navigate the data structure to return the desired value.
782
A sample use of this function in context of a resource definition
791
description: Instance type to be used.
797
type: OS::Nova::Server
799
flavor: { get_param: instance_type}
800
metadata: { get_param: [ server_data, metadata ] }
801
key_name: { get_param: [ server_data, keys, 0 ] }
804
In this example, if the instance_type/server_data parameters contained
809
{"instance_type": "m1.tiny",
810
{"server_data": {"metadata": {"foo": "bar"},
811
"keys": ["a_key","other_key"]}}}
813
then the value of the property 'flavor' would resolve to "m1.tiny", 'metadata'
814
would resolve to {"foo": "bar"} and 'key_name' would resolve to "a_key".
774
The parameter name to be resolved. If the parameters returns a complex data
775
structure such as a list or a map, then subsequent keys or indexes can be
776
specified. These additional parameters are used to navigate the data
777
structure to return the desired value.
779
The following example demonstrates the use of the ``get_param`` function::
785
description: Instance type to be used.
791
type: OS::Nova::Server
793
flavor: { get_param: instance_type}
794
metadata: { get_param: [ server_data, metadata ] }
795
key_name: { get_param: [ server_data, keys, 0 ] }
797
In this example, if the ``instance_type`` and ``server_data`` parameters
798
contained the following data::
800
{"instance_type": "m1.tiny",
801
{"server_data": {"metadata": {"foo": "bar"},
802
"keys": ["a_key","other_key"]}}}
804
then the value of the property ``flavor`` would resolve to ``m1.tiny``,
805
``metadata`` would resolve to ``{"foo": "bar"}`` and ``key_name`` would resolve
818
The *get_resource* function allows for referencing another resource within the
819
same template. At runtime, it will be resolved to reference ID of the resource,
820
which is resource type specific. For example, a reference to a floating IP
821
resource will return the respective IP address at runtime.
822
The syntax of the get_resource function is as follows:
826
get_resource: <resource ID>
828
The *resource ID* of the referenced resources as used in the current template is
829
given as single parameter to the get_resource function.
811
The ``get_resource`` function references another resource within the
812
same template. At runtime, it is resolved to reference the ID of the referenced
813
resource, which is resource type specific. For example, a reference to a
814
floating IP resource returns the respective IP address at runtime. The syntax
815
of the ``get_resource`` function is::
817
get_resource: <resource ID>
819
The resource ID of the referenced resource is given as single parameter to the
820
``get_resource`` function.
826
type: OS::Neutron::Port
830
type: OS::Nova::Server
834
port: { get_resource: instance_port }
834
The *list_join* function joins a list of strings with the given delimiter. This
835
function is introduced in the Juno release, usable in HOT versions later than
836
`2013-05-23`. The syntax of the list_join function is as follows:
844
A sample use of this function with a simple list is shown below.
848
list_join: [', ', ['one', 'two', 'and three']]
850
This would resolve to "one, two, and three".
839
The ``list_join`` function joins a list of strings with the given delimiter.
841
The syntax of the ``list_join`` function is::
849
list_join: [', ', ['one', 'two', 'and three']]
851
This resolve to the string ``one, two, and three``.
855
The *digest* function allows for performing digest operations on a given value.
856
This function has been introduced in the Kilo release and is usable with HOT versions
857
later than `2015-04-30`.
859
The syntax of the digest function is as follows:
856
The ``digest`` function allows for performing digest operations on a given
857
value. This function has been introduced in the Kilo release and is usable with
858
HOT versions later than ``2015-04-30``.
860
The syntax of the ``digest`` function is::
980
The *resource_facade* function allows a provider template to retrieve data
981
about its resource facade in the parent template. A provider template is used
982
to provide a custom definition of a resource - the facade - in the form of a
983
Heat template. The resource's properties are passed to the provider template as
984
its parameters, but other resource data can be included using this function.)
986
The syntax of the *resource_facade* function is as follows::
988
resource_facade: <data type>
990
The *data type* can be `metadata`, `deletion_policy` or `update_policy`.
971
The ``resource_facade`` function retrieves data in a parent
974
A provider template provides a custom definition of a resource, called its
975
facade. For more information about custom templates, see :ref:`composition`.
976
The syntax of the ``resource_facade`` function is::
978
resource_facade: <data type>
980
``data type`` can be one of ``metadata``, ``deletion_policy`` or
995
The *str_replace* function allows for dynamically constructing strings by
986
The ``str_replace`` function dynamically constructs strings by
996
987
providing a template string with placeholders and a list of mappings to assign
997
988
values to those placeholders at runtime. The placeholders are replaced with
998
989
mapping values wherever a mapping key exactly matches a placeholder.
999
The syntax of the str_replace function is as follows:
1004
template: <template string>
1005
params: <parameter mappings>
991
The syntax of the ``str_replace`` function is::
994
template: <template string>
995
params: <parameter mappings>
1008
The *template* argument defines the template string that contains
1009
placeholders which will be substituted at runtime.
998
Defines the template string that contains placeholders which will be
999
substituted at runtime.
1011
The *params* argument provides parameter mappings in the form of a
1012
dictionary, which will be used for placeholder substitution in the template
1013
string at runtime. Within parameter mappings one can make use of other
1014
functions (e.g. get_attr to use resource attribute values) for template
1017
The example below shows a simple use of the str_replace function in the outputs
1018
section of a template to build a URL for logging into a deployed application.
1024
type: OS::Nova::Server
1025
# general metadata and properties ...
1029
description: The URL to log into the deployed application
1032
template: http://host/MyApplication
1034
host: { get_attr: [ my_instance, first_address ] }
1036
The str_replace function can also be used for constructing bigger chunks of text
1037
like scripts for initializing compute instances as shown in the example below:
1044
label: Database Password
1045
description: Root password for MySQL
1050
type: OS::Nova::Server
1052
# general properties ...
1002
Provides parameter mappings in the form of dictionary. Each key refers to a
1003
placeholder used in the ``template`` attribute.
1005
The following example shows a simple use of the ``str_replace`` function in the
1006
outputs section of a template to build a URL for logging into a deployed
1011
type: OS::Nova::Server
1012
# general metadata and properties ...
1016
description: The URL to log into the deployed application
1058
echo "Setting MySQL root password"
1059
mysqladmin -u root password $db_rootpassword
1060
# do more things ...
1019
template: http://host/MyApplication
1062
$db_rootpassword: { get_param: DBRootPassword }
1021
host: { get_attr: [ my_instance, first_address ] }
1023
The following examples show the use of the ``str_replace``
1024
function to build an instance initialization script::
1029
label: Database Password
1030
description: Root password for MySQL
1035
type: OS::Nova::Server
1037
# general properties ...
1043
echo "Setting MySQL root password"
1044
mysqladmin -u root password $db_rootpassword
1045
# do more things ...
1047
$db_rootpassword: { get_param: DBRootPassword }
1064
1049
In the example above, one can imagine that MySQL is being configured on a
1065
1050
compute instance and the root password is going to be set based on a user
1066
1051
provided parameter. The script for doing this is provided as userdata to the
1067
compute instance, leveraging the str_replace function.
1071
*Fn::Select* is a function borrowed from CFN template. Please check the CFN
1072
template guide for a description.
1052
compute instance, leveraging the ``str_replace`` function.
1057
The ``str_split`` function allows for splitting a string into a list by
1058
providing an arbitrary delimiter, the opposite of ``list_join``.
1060
The syntax of the ``str_split`` function is as follows:
1070
str_split: [',', 'string,to,split']
1072
The result of which is::
1074
['string', 'to', 'split']
1076
Optionally, an index may be provided to select a specific entry from the
1077
resulting list, similar to ``get_attr``/``get_param``::
1079
str_split: [',', 'string,to,split', 0]
1081
The result of which is::
1085
Note: The index starts at zero, and any value outside the maximum (e.g the
1086
length of the list minus one) will cause an error.
added
removed
doc/source/template_guide/hot_spec.rst
