5.2.2. ONAP Heat Orchestration Template Format

As stated above, Heat Orchestration templates must be defined in YAML.

Requirement: R-92635
validation_mode: static
target: VNF
keyword: MUST
introduced: casablanca

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
validation_mode: static
target: VNF
keyword: MUST

A VNF’s Heat Orchestration template MUST contain the section heat_template_version:.

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
validation_mode: static
target: VNF
keyword: MUST

A VNF’s Heat Orchestration Template MUST contain the section description:.

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
validation_mode: static
target: VNF
keyword: MUST

A VNF Heat Orchestration’s template MUST contain the section parameters:.

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
updated: casablanca
validation_mode: static
target: VNF
keyword: MUST

A VNF Heat Orchestration’s template’s parameter MUST be used in a resource with the exception of the parameters for the OS::Nova::Server resource property availability_zone.

Requirement: R-91273
updated: casablanca
validation_mode: none
target: VNF
keyword: MAY NOT

A VNF Heat Orchestration’s template’s parameter for the OS::Nova::Server resource property availability_zone MAY NOT be used in any OS::Nova::Server.

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
validation_mode: static
target: VNF
keyword: MUST

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
validation_mode: static
target: VNF
keyword: MUST

A VNF’s Heat Orchestration Template’s parameter MUST include the attribute type:.

Requirement: R-11441
updated: casablanca
validation_mode: static
target: VNF
keyword: MUST

A VNF’s Heat Orchestration Template’s parameter type MUST be one of the following values:

  • string
  • number
  • json
  • comma_delimited_list
  • boolean

5.2.2.1.4.3. label

Requirement: R-32094
validation_mode: none
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template parameter declaration MAY contain the attribute label:.

5.2.2.1.4.4. description

Requirement: R-44001
validation_mode: static
target: VNF
keyword: MUST

A VNF’s Heat Orchestration Template parameter declaration MUST contain the attribute description.

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
validation_mode: static
target: VNF
keyword: MUST

A VNF Heat Orchestration Template parameter declaration MUST NOT contain the default attribute.

Requirement: R-26124
updated: casablanca
validation_mode: none
target: VNF
keyword: MUST

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.6. hidden

Requirement: R-32557
validation_mode: none
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template parameter declaration MAY contain the attribute hidden:.

The parameter attribute hidden: is an OpenStack optional attribute that 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.

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
updated: dublin
validation_mode: none
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type number MAY have a parameter constraint defined.

Requirement: R-40518
updated: casablanca
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type string MAY have a parameter constraint defined.

Requirement: R-96227
updated: casablanca
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type json MAY have a parameter constraint defined.

Requirement: R-79817
updated: casablanca
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type comma_delimited_list MAY have a parameter constraint defined.

Requirement: R-06613
updated: casablanca
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template’s parameter defined in a non-nested YAML file as type boolean MAY have a parameter constraint defined.

Requirement: R-00011
updated: dublin
validation_mode: static
target: VNF
keyword: SHOULD NOT

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
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template parameter declaration MAY contain the attribute immutable:.

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.4.9. tags

Requirement: R-225891
target: VNF
keyword: MAY
introduced: el alto

A VNF’s Heat Orchestration Template parameter declaration MAY contain the attribute tags:.

5.2.2.1.5. resources

Requirement: R-23664
validation_mode: static
target: VNF
keyword: MUST

A VNF’s Heat Orchestration template MUST contain the section resources:.

Requirement: R-90152
validation_mode: static
target: VNF
keyword: MUST

A VNF’s Heat Orchestration Template’s resources: section MUST contain the declaration of at least one resource.

Requirement: R-40551
updated: casablanca
target: VNF
keyword: MAY

A VNF’s Heat Orchestration Template’s Nested YAML files MAY (or MAY NOT) contain the section resources:.

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
validation_mode: static
target: VNF
keyword: MUST

A VNF’s Heat Orchestration Template’s resource name (i.e., <resource ID>) MUST only contain alphanumeric characters and underscores (‘_’).

Requirement: R-16447
validation_mode: static
target: VNF
keyword: MUST

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
validation_mode: static
target: VNF
keyword: MUST NOT

A VNF’s Heat Orchestration Template’s Resource MUST NOT reference a HTTP-based resource definitions.

Requirement: R-71699
validation_mode: static
target: VNF
keyword: MUST NOT

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
updated: el alto
validation_mode: static
target: VNF
keyword: MUST NOT

A VNF’s Heat Orchestration Template resource attribute property: MUST NOT use more than two levels of nested get_param intrinsic functions when deriving a property value. SDC does not support nested get_param with recursive lists (i.e., a list inside list). The second get_param in a nested lookup must directly derive its value without further calls to get_param functions.

  • Example of valid nesting:
    • name: {get_param: [ {vm-type}_names, {get_param : index } ] }
  • Examples of invalid nesting. SDC will not support these examples since there is an array inside array.
    • name: {get_param: [ {vm-type}_names, { get_param: [ indexlist, 0 ] } ] }
    • name: {get_param: [ {vm-type}_names, { get_param: [ indexlist1, { get_param: indexlist2 } ] } ] }

5.2.2.1.5.4. metadata

The resource attribute metadata is an OpenStack optional attribute.

Requirement: R-67386
validation_mode: static
target: VNF
keyword: MAY
introduced: casablanca

A VNF’s Heat Orchestration Template’s Resource MAY declare the attribute metadata.

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
target: VNF
keyword: MAY

VNF’s Heat Orchestration Template’s Resource MAY declare the attribute depends_on:.

5.2.2.1.5.6. update_policy

Requirement: R-63137
target: VNF
keyword: MAY

VNF’s Heat Orchestration Template’s Resource MAY declare the attribute update_policy:.

5.2.2.1.5.7. deletion_policy

Requirement: R-43740
updated: casablanca
target: VNF
keyword: MAY

VNF’s Heat Orchestration Template’s Resource MAY declare the attribute deletion_policy:.

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
updated: casablanca
target: VNF
keyword: MAY

VNF’s Heat Orchestration Template’s Resource MAY declare the attribute external_id:.

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
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template MAY contain the outputs: section.

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
updated: casablanca
validation_mode: static
target: VNF
keyword: MUST

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
updated: casablanca
validation_mode: static
target: VNF
keyword: MUST

A VNF’s Heat Orchestration template’s Environment File MUST contain the parameters: section.

Requirement: R-68198
updated: casablanca
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template’s Environment File’s parameters: section MAY (or MAY NOT) enumerate parameters.

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
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template’s Environment File’s MAY contain the parameter_defaults: section.

The parameter_defaults: section contains default parameters that are passed to all template resources.

Requirement: R-46096
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template’s Environment File’s MAY contain the encrypted_parameters: section.

The encrypted_parameters: section contains a list of encrypted parameters.

Requirement: R-24893
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template’s Environment File’s MAY contain the event_sinks: section.

The event_sinks: section contains the list of endpoints that would receive stack events.

Requirement: R-42685
target: VNF
keyword: MAY

A VNF’s Heat Orchestration template’s Environment File’s MAY contain the parameter_merge_strategies: section.

The parameter_merge_strategies: section provides the merge strategies for merging parameters and parameter defaults from the environment file.

Requirement: R-67231
validation_mode: static
target: VNF
keyword: MUST NOT

A VNF’s Heat Orchestration template’s Environment File’s MUST NOT contain the resource_registry: section.

ONAP implementation does not support the Environment File resource_registry section. The resource_registry section allows for the definition of custom resources.