5.2.2. ONAP Heat Orchestration Template Format

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

Requirement: R-92635 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
introduced: casablanca
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF Heat Orchestration’s template MUST contain the section parameters: with at least one parameter defined.

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF Heat Orchestration’s template’s parameter MUST be used

  • in a resource AND/OR

  • in a output parameter (in the outputs section)

with the exception of the parameters for the OS::Nova::Server resource property availability_zone which is defined in R-98450.

Requirement: R-91273 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY NOT
updated: casablanca
validation_mode: none

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

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

Requirement: R-11441 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
validation_mode: none

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

5.2.2.1.4.4. description

Requirement: R-44001 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: static

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

Requirement: R-26124 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: none

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
validation_mode: none

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: dublin
validation_mode: none

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: SHOULD NOT
updated: dublin
validation_mode: static

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 ../../_images/arrow-right-circle.svg
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 ../../_images/arrow-right-circle.svg
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-23663 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: frankfurt

A VNF’s Heat Orchestration template’s base module MAY (or MAY NOT) contain the section resources:.

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: frankfurt
validation_mode: static

A VNF’s Heat Orchestration template’s incremental module and volume module MUST contain the section resources:.

Requirement: R-90152 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

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

Requirement: R-40551 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

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

Requirement: R-16447 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: static

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

Requirement: R-71699 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
updated: el alto
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
introduced: casablanca
validation_mode: static

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 ../../_images/arrow-right-circle.svg
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 ../../_images/arrow-right-circle.svg
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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

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 ../../_images/arrow-right-circle.svg
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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST
updated: casablanca
validation_mode: static

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

Requirement: R-68198 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MAY
updated: casablanca

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 ../../_images/arrow-right-circle.svg
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 ../../_images/arrow-right-circle.svg
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 ../../_images/arrow-right-circle.svg
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 ../../_images/arrow-right-circle.svg
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 ../../_images/arrow-right-circle.svg
target: VNF
keyword: MUST NOT
validation_mode: static

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.