5.2.2. ONAP Heat Orchestration Template Format
As stated above, Heat Orchestration templates must be defined in YAML.
Requirement: R-92635
|
A VNF’s Heat Orchestration Template MUST be compliant with the OpenStack Template Guide. |
The OpenStack Template Guide is defined at https://docs.openstack.org/heat/latest/template_guide/index.html#top.
5.2.2.1. Heat Orchestration Template Structure
Heat Orchestration template structure follows the following format, as defined by OpenStack at https://docs.openstack.org/developer/heat/template_guide/hot_spec.html.
heat_template_version: <date>
description:
# a description of the template
parameter_groups:
# a declaration of input parameter groups and order
parameters:
# declaration of input parameters
resources:
# declaration of template resources
outputs:
# declaration of output parameters
conditions:
# declaration of conditions
5.2.2.1.1. heat_template_version
Requirement: R-27078
|
A VNF’s Heat Orchestration template MUST contain the
section |
The section heat_template_version:
must be set to a date that
is supported by the OpenStack environment.
5.2.2.1.2. description
Requirement: R-39402
|
A VNF’s Heat Orchestration Template MUST contain the
section |
5.2.2.1.3. parameter_groups
A VNF Heat Orchestration template may contain the section “parameter_groups:”.
5.2.2.1.4. parameters
Requirement: R-35414
|
A VNF Heat Orchestration’s template
MUST contain the section |
parameters:
<param name>:
type: <string | number | json | comma_delimited_list | boolean>
label: <human-readable name of the parameter>
description: <description of the parameter>
default: <default value for parameter>
hidden: <true | false>
constraints:
<parameter constraints>
immutable: <true | false>
tags: <list of parameter categories>
This section allows for specifying input parameters that have to be provided when instantiating the template. Each parameter is specified in a separate nested block with the name of the parameters defined in the first line and additional attributes (e.g., type, label) defined as nested elements.
Requirement: R-90279
|
A VNF Heat Orchestration’s template’s parameter MUST be used
with the exception of the parameters for the |
Requirement: R-91273
|
A VNF Heat Orchestration’s template’s parameter for the
|
That is, the parameter associated with the property availability_zone
maybe declared but not used in a resource.
5.2.2.1.4.1. <param name>
The name of the parameter.
Requirement: R-25877
|
A VNF’s Heat Orchestration Template’s parameter name (i.e., <param name>) MUST contain only alphanumeric characters and underscores (‘_’). |
5.2.2.1.4.2. type
Requirement: R-36772
|
A VNF’s Heat Orchestration Template’s parameter MUST include the
attribute |
Requirement: R-11441
|
A VNF’s Heat Orchestration Template’s parameter type MUST be one of the following values:
|
5.2.2.1.4.3. label
Requirement: R-32094
|
A VNF’s Heat Orchestration Template parameter declaration MAY
contain the attribute |
5.2.2.1.4.4. description
Requirement: R-44001
|
A VNF’s Heat Orchestration Template parameter declaration MUST
contain the attribute |
Note that the parameter attribute description:
is an OpenStack optional
attribute that provides a description of the parameter.
ONAP implementation requires this attribute.
5.2.2.1.4.5. default
Requirement: R-90526
|
A VNF Heat Orchestration Template parameter declaration MUST NOT
contain the |
Requirement: R-26124
|
If a VNF Heat Orchestration Template parameter has a default value, it MUST be enumerated in the environment file. |
Note that the parameter attribute default:
is an OpenStack optional
attribute that declares the default value of the parameter.
ONAP implementation prohibits the use of this attribute.
5.2.2.1.4.7. constraints
The parameter attribute constraints:
is an OpenStack optional attribute
that defines a list of constraints to apply to the parameter.
Requirement: R-88863
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as type
|
Requirement: R-40518
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as type
|
Requirement: R-96227
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as type
|
Requirement: R-79817
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as
type |
Requirement: R-06613
|
A VNF’s Heat Orchestration Template’s parameter defined
in a non-nested YAML file as type
|
Requirement: R-00011
|
A VNF’s Heat Orchestration Template’s parameter defined in a nested YAML file SHOULD NOT have a parameter constraint defined. |
The constraints block of a parameter definition defines additional validation constraints that apply to the value of the parameter. The parameter values provided in the VNF Heat Orchestration Template are validated against the constraints at instantiation time. The stack creation fails if the parameter value doesn’t comply to the constraints.
The constraints are defined as a list with the following syntax
constraints:
- <constraint type>: <constraint definition>
description: <constraint description>
<constraint type> Provides the type of constraint to apply. The list of OpenStack supported constraints can be found at https://docs.openstack.org/heat/latest/template_guide/hot_spec.html .
<constraint definition> provides the actual constraint. The syntax and constraint is dependent of the <constraint type> used.
description: is an optional attribute that provides a description of the constraint. The text is presented to the user when the value the user defines violates the constraint. If omitted, a default validation message is presented to the user.
Below is a brief overview of the range
and allowed values
constraints.
For complete details on constraints, see
https://docs.openstack.org/heat/latest/template_guide/hot_spec.html#parameter-constraints
range
range
: 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: <lower limit>, max: <upper limit> }
It is possible to define a range constraint with only a lower limit or an upper limit.
allowed_values
allowed_values
: The allowed_values
constraint applies to parameters of
type string
or type 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: [ <value>, <value>, ... ]
Alternatively, the following YAML list notation can be used
allowed_values:
- <value>
- <value>
- ...
5.2.2.1.4.8. immutable
Requirement: R-22589
|
A VNF’s Heat Orchestration Template parameter declaration
MAY contain the attribute |
The parameter attribute immutable
is an OpenStack optional attribute
that defines whether the parameter is updatable. A Heat Orchestration Template
stack update fails if immutable
is set to true
and the parameter
value is changed. This attribute immutable
defaults to false
.
5.2.2.1.5. resources
Requirement: R-23663
|
A VNF’s Heat Orchestration template’s base module
MAY (or MAY NOT)
contain the section |
When a VNF is composed of two or more Heat Orchestration Templates (i.e., a base module and one or more incremental modules), it is valid for the base module to not declare a resource.
Requirement: R-23664
|
A VNF’s Heat Orchestration template’s incremental
module and volume module MUST
contain the section |
Requirement: R-90152
|
A VNF’s Heat Orchestration Template’s
|
Requirement: R-40551
|
A VNF’s Heat Orchestration Template’s Nested YAML files MAY
(or MAY NOT) contain the section |
Each resource is defined as a separate block in the resources section with the following syntax.
resources:
<resource ID>:
type: <resource type>
properties:
<property name>: <property value>
metadata:
<resource specific metadata>
depends_on: <resource ID or list of ID>
update_policy: <update policy>
deletion_policy: <deletion policy>
external_id: <external resource ID>
condition: <condition name or expression or boolean>
5.2.2.1.5.1. resource ID
Requirement: R-75141
|
A VNF’s Heat Orchestration Template’s resource name (i.e., <resource ID>) MUST only contain alphanumeric characters and underscores (‘_’). |
Requirement: R-16447
|
A VNF’s <resource ID> MUST be unique across all Heat Orchestration Templates and all HEAT Orchestration Template Nested YAML files that are used to create the VNF. |
Note that a VNF can be composed of one or more Heat Orchestration Templates.
Note that OpenStack requires the <resource ID> to be unique to the Heat Orchestration Template and not unique across all Heat Orchestration Templates the compose the VNF.
5.2.2.1.5.2. type
The resource attribute type
is an OpenStack required attribute that
defines the resource type, such as OS::Nova::Server
or
OS::Neutron::Port
.
The resource attribute type
may specify a VNF HEAT
Orchestration Template Nested YAML file.
Requirement: R-53952
|
A VNF’s Heat Orchestration Template’s Resource MUST NOT reference a HTTP-based resource definitions. |
Requirement: R-71699
|
A VNF’s Heat Orchestration Template’s Resource MUST NOT reference a HTTP-based Nested YAML file. |
5.2.2.1.5.3. properties
The resource attribute properties
is an OpenStack optional attribute that
provides a list of resource-specific properties. The property value can
be provided in place, or via a function
(e.g., Intrinsic functions).
Requirement: R-10834
|
A VNF’s Heat Orchestration Template resource attribute
|
5.2.2.1.5.4. metadata
The resource attribute metadata
is an OpenStack optional attribute.
Requirement: R-67386
|
A VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
5.2.2.1.5.5. depends_on
The resource attribute depends_on
is an OpenStack optional attribute.
See Section 9.7 for additional details.
Requirement: R-46968
|
VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
5.2.2.1.5.6. update_policy
Requirement: R-63137
|
VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
5.2.2.1.5.7. deletion_policy
Requirement: R-43740
|
VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
If specified, the deletion_policy
attribute for resources allows
values Delete
, Retain
, and Snapshot
.
Starting with heat_template_version 2016-10-14,
lowercase equivalents are also allowed.
The default policy is to delete the physical resource when deleting a resource from the stack.
5.2.2.1.5.8. external_id
Requirement: R-78569
|
VNF’s Heat Orchestration Template’s Resource MAY declare the
attribute |
This attribute allows for specifying the resource_id for an existing external (to the stack) resource. External resources cannot depend on other resources, but we allow other resources to depend on external resource. This attribute is optional. Note: when this is specified, properties will not be used for building the resource and the resource is not managed by Heat. This is not possible to update that attribute. Also, resource won’t be deleted by heat when stack is deleted.
5.2.2.1.5.9. condition
The resource attribute condition
is an OpenStack optional attribute.
5.2.2.1.6. outputs
Requirement: R-36982
|
A VNF’s Heat Orchestration template MAY contain the |
This section allows for specifying output parameters available to users once the template has been instantiated. If the section is specified, it will need to adhere to specific requirements. See Output Parameters and ONAP Output Parameter Names for additional details.
5.2.2.2. Environment File Format
A VNF’s Heat Orchestration Template’s environment file is a yaml text file. (https://docs.openstack.org/developer/heat/template_guide/environment.html)
Requirement: R-86285
|
A VNF’s Heat Orchestration template MUST have a corresponding environment file. |
The use of an environment file in OpenStack is optional. In ONAP, it is mandatory. A Heat Orchestration Template uploaded to ONAP must have a corresponding environment file, even if no parameters are enumerated in the mandatory parameter section.
Requirement: R-03324
|
A VNF’s Heat Orchestration template’s Environment File MUST
contain the |
Requirement: R-68198
|
A VNF’s Heat Orchestration template’s Environment File’s
|
ONAP implementation requires the parameters section in the environmental file to be declared. The parameters section contains a list of key/value pairs.
Requirement: R-59930
|
A VNF’s Heat Orchestration template’s Environment File’s
MAY contain the |
The parameter_defaults:
section contains default parameters that are
passed to all template resources.
Requirement: R-46096
|
A VNF’s Heat Orchestration template’s Environment File’s
MAY contain the |
The encrypted_parameters:
section contains a list of encrypted parameters.
Requirement: R-24893
|
A VNF’s Heat Orchestration template’s Environment File’s
MAY contain the |
The event_sinks:
section contains the list of endpoints that would receive
stack events.
Requirement: R-42685
|
A VNF’s Heat Orchestration template’s Environment File’s
MAY contain the |
The parameter_merge_strategies:
section provides the merge strategies for
merging parameters and parameter defaults from the environment file.
Requirement: R-67231
|
A VNF’s Heat Orchestration template’s Environment File’s
MUST NOT contain the |
ONAP implementation does not support the Environment File resource_registry section. The resource_registry section allows for the definition of custom resources.