diff options
Diffstat (limited to 'docs/Chapter5/Heat')
3 files changed, 343 insertions, 289 deletions
diff --git a/docs/Chapter5/Heat/General Guidelines for Heat.rst b/docs/Chapter5/Heat/General Guidelines for Heat.rst index 378a057..bacf6fa 100644 --- a/docs/Chapter5/Heat/General Guidelines for Heat.rst +++ b/docs/Chapter5/Heat/General Guidelines for Heat.rst @@ -35,9 +35,17 @@ YAML Format :id: R-95303 :target: VNF :keyword: MUST + :validation_mode: static A VNF's Heat Orchestration Template **MUST** be defined using valid YAML. YAML (YAML Ain't Markup Language) is a human friendly data serialization standard for all programming languages. See http://www.yaml.org/. + +YAML rules include: + + - Tabs are not allowed, use spaces ONLY + - You must indent your properties and lists with 1 or more spaces + - All Resource IDs and resource property parameters are case-sensitive. + (e.g., "ThIs", is not the same as "thiS") diff --git a/docs/Chapter5/Heat/ONAP Heat Orchestration Template Format.rst b/docs/Chapter5/Heat/ONAP Heat Orchestration Template Format.rst index 40aa3ce..f6c4541 100644 --- a/docs/Chapter5/Heat/ONAP Heat Orchestration Template Format.rst +++ b/docs/Chapter5/Heat/ONAP Heat Orchestration Template Format.rst @@ -6,25 +6,25 @@ ONAP Heat Orchestration Template Format ------------------------------------------------ +As stated above, Heat Orchestration templates must be defined in YAML. -As stated in the previous section, Heat Orchestration templates must be -defined in YAML. - -YAML rules include: - - - Tabs are not allowed, use spaces ONLY +.. req:: + :id: R-92635 + :keyword: MUST + :validation_mode: static - - You must indent your properties and lists with 1 or more spaces + A VNF's Heat Orchestration Template **MUST** be compliant with the + OpenStack Template Guide. - - All Resource IDs and resource property parameters are - case-sensitive. (e.g., "ThIs", is not the same as "thiS") +The OpenStack Template Guide is defined at +https://docs.openstack.org/heat/latest/template_guide/index.html#top. 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 Orchestration template structure follows the following format, as +defined by OpenStack at +https://docs.openstack.org/developer/heat/template_guide/hot_spec.html. .. code-block:: yaml @@ -48,20 +48,22 @@ https://docs.openstack.org/developer/heat/template_guide/hot_spec.html conditions: # declaration of conditions + heat_template_version ~~~~~~~~~~~~~~~~~~~~~~~ .. req:: :id: R-27078 - :target: VNF :keyword: MUST + :target: VNF + :validation_mode: static - A VNF's Heat Orchestration template **MUST** contain - the section "heat_template_version:". + 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. +The section ``heat_template_version:`` must be set to a date that +is supported by the OpenStack environment. description ~~~~~~~~~~~~ @@ -69,11 +71,11 @@ description .. req:: :id: R-39402 - :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration Template **MUST** - contain the section "description:". + A VNF's Heat Orchestration Template **MUST** contain the + section ``description:``. parameter_groups ~~~~~~~~~~~~~~~~~~~~~~ @@ -88,9 +90,10 @@ parameters :id: R-35414 :target: VNF :keyword: MUST + :validation_mode: static - A VNF Heat Orchestration's template **MUST** - contain the section "parameters:". + A VNF Heat Orchestration's template **MUST** contain the + section ``parameters:``. .. code-block:: yaml @@ -126,21 +129,22 @@ attributes (e.g., type, label) defined as nested elements. :id: R-90279 :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration template's parameter **MUST** - be used in a resource with the exception of the parameters - for the OS::Nova::Server resource property availability_zone. + 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``. .. req:: :id: R-91273 :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::Resource. + 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' +That is, the parameter associated with the property ``availability_zone`` maybe declared but not used in a resource. <param name> @@ -153,10 +157,11 @@ The name of the parameter. :id: R-25877 :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 ('_'). + A VNF's Heat Orchestration Template's parameter name + (i.e., <param name>) **MUST** contain only alphanumeric + characters and underscores ('_'). type ++++ @@ -166,18 +171,25 @@ type :id: R-36772 :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration Template's parameter - **MUST** include the attribute "type:". + A VNF's Heat Orchestration Template's parameter **MUST** include the + attribute ``type:``. .. req:: :id: R-11441 :target: VNF :keyword: MUST + :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" or "boolean". + A VNF's Heat Orchestration Template's parameter type **MUST** be one of + the following values: + + * ``string`` + * ``number`` + * ``json`` + * ``comma_delimited_list`` + * ``boolean`` label ++++++ @@ -188,8 +200,8 @@ label :target: VNF :keyword: MAY - A VNF's Heat Orchestration Template parameter - declaration **MAY** contain the attribute "label:". + A VNF's Heat Orchestration Template parameter declaration **MAY** + contain the attribute ``label:``. description +++++++++++++ @@ -199,12 +211,13 @@ description :id: R-44001 :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration Template parameter - declaration **MUST** contain the attribute "description". + 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. +Note that the parameter attribute ``description:`` is an OpenStack optional +attribute that provides a description of the parameter. ONAP implementation requires this attribute. default @@ -215,21 +228,23 @@ default :id: R-90526 :target: VNF :keyword: MUST + :validation_mode: static - A VNF Heat Orchestration Template parameter - declaration **MUST** not contain the default attribute. + A VNF Heat Orchestration Template parameter declaration **MUST NOT** + contain the ``default`` attribute. .. req:: :id: R-26124 :target: VNF :keyword: MUST + :validation_mode: static - If a VNF Heat Orchestration Template parameter - requires a default value, it **MUST** be enumerated in the environment file. + 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. +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. hidden +++++++ @@ -240,75 +255,82 @@ hidden :target: VNF :keyword: MAY - A VNF's Heat Orchestration Template parameter - declaration **MAY** contain the attribute "hidden:". + 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. +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. constraints ++++++++++++ -The parameter attribute "constraints:" is an OpenStack optional -attribute that defines a list of constraints to apply to the parameter. +The parameter attribute ``constraints:`` is an OpenStack optional attribute +that defines a list of constraints to apply to the parameter. .. req:: :id: R-88863 :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration Template's parameter defined as - type "number" **MUST** have a parameter constraint of "range" or - "allowed_values" defined. + A VNF's Heat Orchestration Template's parameter defined + in a non-nested YAML file as type + ``number`` **MUST** have a parameter constraint of ``range`` or + ``allowed_values`` defined. .. req:: :id: R-40518 :target: VNF :keyword: MAY - A VNF's Heat Orchestration Template's parameter defined as - type "string" **MAY** have a parameter constraint defined. + A VNF's Heat Orchestration Template's parameter defined + in a non-nested YAML file as type + ``string`` **MAY** have a parameter constraint defined. .. req:: :id: R-96227 :target: VNF :keyword: MAY - A VNF's Heat Orchestration Template's parameter defined as - type "json" **MAY** have a parameter constraint defined. + A VNF's Heat Orchestration Template's parameter defined + in a non-nested YAML file as type + ``json`` **MAY** have a parameter constraint defined. .. req:: :id: R-79817 :target: VNF :keyword: MAY - A VNF's Heat Orchestration Template's parameter defined as - type "comma_delimited_list" **MAY** have a parameter constraint defined. + 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. .. req:: :id: R-06613 :target: VNF :keyword: MAY - A VNF's Heat Orchestration Template's parameter defined as - type "boolean" **MAY** have a parameter constraint defined. + A VNF's Heat Orchestration Template's parameter defined + in a non-nested YAML file as type + ``boolean`` **MAY** have a parameter constraint defined. .. req:: :id: R-00011 :target: VNF :keyword: MUST NOT + :validation_mode: static - A VNF's Heat Orchestration Template's Nested YAML files - parameter's **MUST NOT** have a parameter constraint defined. + A VNF's Heat Orchestration Template's parameter defined + in a nested YAML file + **MUST 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 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. @@ -331,20 +353,23 @@ 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. +**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. +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``: 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 @@ -352,16 +377,16 @@ parameter. The syntax of the range constraint is .. -It is possible to define a range constraint with only a lower -limit or an 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``: 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 .. code-block:: yaml @@ -377,8 +402,6 @@ list. The syntax of the allowed_values constraint is - ... -. . - immutable ++++++++++++ @@ -389,13 +412,12 @@ immutable :keyword: MAY A VNF's Heat Orchestration Template parameter declaration - **MAY** contain the attribute "immutable:". + **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. +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``. .. _resources: @@ -407,25 +429,28 @@ resources :id: R-23664 :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration template **MUST** contain - the section "resources:". + A VNF's Heat Orchestration template **MUST** + contain the section ``resources:``. .. req:: :id: R-90152 :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. + A VNF's Heat Orchestration Template's + ``resources:`` section **MUST** contain the declaration of at + least one resource. .. req:: :id: R-40551 :target: VNF :keyword: MAY - A VNF's Heat Orchestration Template's Nested YAML files - **MAY** contain the section "resources:". + 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. @@ -466,6 +491,7 @@ resource ID :id: R-75141 :target: VNF :keyword: MUST + :validation_mode: static A VNF's Heat Orchestration Template's resource name (i.e., <resource ID>) **MUST** only contain alphanumeric @@ -475,9 +501,10 @@ resource ID :id: R-16447 :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 + 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. @@ -489,11 +516,10 @@ Orchestration Templates the compose the VNF. 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`` 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 +The resource attribute ``type`` may specify a VNF HEAT Orchestration Template Nested YAML file. @@ -501,6 +527,7 @@ Orchestration Template Nested YAML file. :id: R-53952 :target: VNF :keyword: MUST NOT + :validation_mode: static A VNF's Heat Orchestration Template's Resource **MUST NOT** reference a HTTP-based resource definitions. @@ -509,6 +536,7 @@ Orchestration Template Nested YAML file. :id: R-71699 :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. @@ -516,9 +544,9 @@ Orchestration Template Nested YAML file. 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 +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 <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-intrinsic-functions>`__). @@ -526,37 +554,33 @@ The property value can be provided in place, or via a function :id: R-10834 :target: VNF :keyword: MUST - :test: no test found - :test_case: no test found - :test_file: no test found + :validation_mode: static - If a VNF Heat Orchestration Template resource attribute - "property:" uses a nested "get_param", one level of nesting is - supported and the nested "get_param" **MUST** reference an index. + If a VNF's Heat Orchestration Template resource attribute + ``property:`` uses a nested ``get_param``, the nested + ``get_param`` **MUST** reference an index. metadata ++++++++++ -The resource attribute \"metadata:\" is an OpenStack optional attribute. +The resource attribute ``metadata`` is an OpenStack optional attribute. .. req:: - :id: R-97199 + :id: R-67386 :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration Template's OS::Nova::Server - resource **MUST** contain the attribute "metadata". + A VNF's Heat Orchestration Template's Resource **MAY** declare the + attribute ``metadata``. -Section 5.4 contains the OS::Nova::Server mandatory and optional metadata. depends_on +++++++++++ -The resource attribute \"depends_on:\" is an OpenStack optional -attribute. -See `OpenStack documentation <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-resources-dependencies>`__ -for additional details. +The resource attribute ``depends_on`` is an OpenStack optional attribute. +See `Section <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-resources-dependencies>`__ 9.7 for additional details. .. req:: @@ -564,8 +588,8 @@ for additional details. :target: VNF :keyword: MAY - VNF's Heat Orchestration Template's Resource **MAY** - declare the attribute "depends_on:". + VNF's Heat Orchestration Template's Resource **MAY** declare the + attribute ``depends_on:``. update_policy ++++++++++++++ @@ -576,8 +600,8 @@ update_policy :target: VNF :keyword: MAY - VNF's Heat Orchestration Template's Resource **MAY** - declare the attribute "update_policy:". + VNF's Heat Orchestration Template's Resource **MAY** declare the + attribute ``update_policy:``. deletion_policy +++++++++++++++++++ @@ -588,13 +612,13 @@ deletion_policy :target: VNF :keyword: MAY - A VNF's Heat Orchestration Template's Resource - **MAY** declare the attribute "deletion_policy:". + 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. +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. @@ -608,26 +632,22 @@ external_id :target: VNF :keyword: MAY - A VNF's Heat Orchestration Template's Resouce **MAY** - declare the attribute "external_id:". + 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. +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. condition +++++++++++ -The resource attribute \"condition:\" is an OpenStack optional attribute. - -Support for the resource condition attribute was added -in the Newton release of OpenStack. +The resource attribute ``condition`` is an OpenStack optional attribute. outputs ~~~~~~~~~ @@ -638,8 +658,8 @@ outputs :target: VNF :keyword: MAY - A VNF's Heat Orchestration template **MAY** - contain the "outputs:" section. + 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 @@ -650,7 +670,7 @@ See :ref:`Output Parameters` and Environment File Format ^^^^^^^^^^^^^^^^^^^^^^^^^^ -The environment file is a yaml text file. +A VNF's Heat Orchestration Template's environment file is a yaml text file. (https://docs.openstack.org/developer/heat/template_guide/environment.html) @@ -658,21 +678,25 @@ The environment file is a yaml text file. :id: R-86285 :target: VNF :keyword: MUST + :validation_mode: static - The VNF Heat Orchestration Template **MUST** have a corresponding - environment file, even if no parameters are required to be enumerated. + 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. +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. .. req:: :id: R-03324 :target: VNF :keyword: MUST + :validation_mode: static - The VNF Heat Orchestration Template **MUST** contain the - "parameters" section in the environment file. + A VNF's Heat Orchestration template's Environment File **MUST** + contain the ``parameters:`` section. .. req:: :id: R-68198 @@ -680,11 +704,11 @@ In ONAP, it is mandatory. :keyword: MAY A VNF's Heat Orchestration template's Environment File's - "parameters:" section **MAY** enumerate parameters. + ``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. +ONAP implementation requires the parameters section in the environmental +file to be declared. The parameters section contains a list of key/value +pairs. .. req:: @@ -692,11 +716,11 @@ contains a list of key/value pairs. :target: VNF :keyword: MAY - A VNF's Heat Orchestration template's Environment - File's **MAY** contain the "parameter_defaults:" section. + 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. +The ``parameter_defaults:`` section contains default parameters that are +passed to all template resources. .. req:: @@ -705,9 +729,9 @@ that are passed to all template resources. :keyword: MAY A VNF's Heat Orchestration template's Environment File's - **MAY** contain the "encrypted_parameters:" section. + **MAY** contain the ``encrypted_parameters:`` section. -The "encrypted_parameters:" section contains a list of encrypted parameters. +The ``encrypted_parameters:`` section contains a list of encrypted parameters. .. req:: @@ -716,10 +740,10 @@ The "encrypted_parameters:" section contains a list of encrypted parameters. :keyword: MAY A VNF's Heat Orchestration template's Environment File's - **MAY** contain the "event_sinks:" section. + **MAY** contain the ``event_sinks:`` section. -The "event_sinks:" section contains the list of endpoints that would -receive stack events. +The ``event_sinks:`` section contains the list of endpoints that would receive +stack events. .. req:: @@ -728,23 +752,24 @@ receive stack events. :keyword: MAY A VNF's Heat Orchestration template's Environment File's - **MAY** contain the "parameter_merge_strategies:" section. + **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. +The ``parameter_merge_strategies:`` section provides the merge strategies for +merging parameters and parameter defaults from the environment file. .. req:: :id: R-67231 :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. + 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. +ONAP implementation does not support the Environment File resource_registry +section. The resource_registry section allows for the definition of custom +resources. SDC Treatment of Environment Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/Chapter5/Heat/ONAP Heat Orchestration Templates: Overview.rst b/docs/Chapter5/Heat/ONAP Heat Orchestration Templates: Overview.rst index fd4f76a..f8f0425 100644 --- a/docs/Chapter5/Heat/ONAP Heat Orchestration Templates: Overview.rst +++ b/docs/Chapter5/Heat/ONAP Heat Orchestration Templates: Overview.rst @@ -22,9 +22,9 @@ ONAP VNF Modularity Overview A VNF **MAY** be composed from one or more Heat Orchestration Templates, each of which represents a subset of the overall VNF. -The Heat Orchestration Templates can be thought of a components or -modules of the VNF and are referred to as "\ *VNF Modules*\ ". -During orchestration, these modules are +The Heat Orchestration Templates can be thought of a components or modules of +the VNF and are referred to as *VNF Modules*. During orchestration, +these modules are deployed incrementally to create the complete VNF. @@ -34,22 +34,19 @@ deployed incrementally to create the complete VNF. :keyword: MAY A VNF's Heat Orchestration Template **MAY** be - - * a Base Module Heat Orchestration Template - (also referred to as a Base Module) - - * an Incremental Module Heat Orchestration Template - (referred to as an Incremental Module) - - * a Cinder Volume Module Heat Orchestration Template - (referred to as Cinder Volume Module). + 1.) Base Module Heat Orchestration Template (also referred to as a + Base Module), + 2.) Incremental Module Heat Orchestration Template (referred to as + an Incremental Module), or + 3.) a Cinder Volume Module Heat Orchestration Template (referred to as + Cinder Volume Module). .. req:: :id: R-37028 :target: VNF :keyword: MUST - The VNF **MUST** be composed of one "base" module. + A VNF **MUST** be composed of one Base Module .. req:: :id: R-13196 @@ -63,16 +60,15 @@ deployed incrementally to create the complete VNF. :target: VNF :keyword: MUST - The VNF **MUST** deploy the base module first, prior to - the incremental modules. + At orchestration time, the VNF's Base Module **MUST** + be deployed first, prior to any incremental modules. .. req:: :id: R-28980 :target: VNF :keyword: MAY - A VNF's incremental module **MAY** be used for initial VNF - deployment only. + A VNF's incremental module **MAY** be used for initial VNF deployment only. .. req:: :id: R-86926 @@ -81,8 +77,8 @@ deployed incrementally to create the complete VNF. A VNF's incremental module **MAY** be used for scale out only. -A VNF's Incremental Module that is used for scale out is deployed -sometime after initial VNF deployment to add capacity. +A VNF's Incremental Module that is used for scale out is deployed sometime +after initial VNF deployment to add capacity. .. req:: @@ -90,8 +86,8 @@ sometime after initial VNF deployment to add capacity. :target: VNF :keyword: MAY - A VNF's incremental module **MAY** be used for both deployment - and scale out. + A VNF's incremental module **MAY** be used for both deployment and + scale out. .. req:: :id: R-68122 @@ -135,9 +131,10 @@ on another instance (e.g., during a failover activity). :id: R-11200 :target: VNF :keyword: MUST + :validation_mode: static - The VNF **MUST** keep the scope of a Cinder volume module, - when it exists, to be 1:1 with the VNF Base Module or Incremental Module. + A VNF's Cinder Volume Module, when it exists, **MUST** be 1:1 + with a Base module or Incremental module. It is strongly recommended that Cinder Volumes be created in a Cinder Volume Module. @@ -146,6 +143,7 @@ Module. :id: R-38474 :target: VNF :keyword: MUST + :validation_mode: static The VNF **MUST** have a corresponding environment file for a Base Module. @@ -153,15 +151,17 @@ Module. :id: R-81725 :target: VNF :keyword: MUST + :validation_mode: static - The VNF **MUST** have a corresponding environment file for an Incremental Module. + A VNF's Incremental Module **MUST** have a corresponding Environment File .. req:: :id: R-53433 :target: VNF :keyword: MUST + :validation_mode: static - The VNF **MUST** have a corresponding environment file for a Cinder Volume Module. + A VNF's Cinder Volume Module **MUST** have a corresponding environment file These concepts will be described in more detail throughout the document. This overview is provided to set the stage and help clarify the concepts @@ -219,101 +219,108 @@ must not contain any special characters and must not contain the word :id: R-87485 :target: VNF :keyword: MUST + :validation_mode: static A VNF's Heat Orchestration Template's file extension **MUST** - be in the lower case format '.yaml' or '.yml'. + be in the lower case format ``.yaml`` or ``.yml``. .. req:: :id: R-56438 :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration Template's Nested YAML file extension - **MUST** be in the lower case format '.yaml' or '.yml'. + A VNF's Heat Orchestration Template's Nested YAML file extension **MUST** + be in the lower case format ``.yaml`` or ``.yml``. .. req:: :id: R-74304 :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration Template's Environment file extension - **MUST** be in the lower case format '.env'. + A VNF's Heat Orchestration Template's Environment file extension **MUST** + be in the lower case format ``.env``. .. req:: :id: R-99646 :target: VNF :keyword: MUST - :test: no test found - :test_case: no test found - :test_file: no test found + :validation_mode: static A VNF's YAML files (i.e, Heat Orchestration Template files and Nested files) **MUST** have a unique name in the scope of the VNF. Base Modules -~~~~~~~~~~~~~~ +~~~~~~~~~~~~ .. req:: :id: R-81339 :target: VNF :keyword: MUST + :validation_mode: static - A VNF Heat Orchestration Template's Base Module file name **MUST** - include 'base' in the filename and **MUST** match one of the following four + A VNF Heat Orchestration Template's Base Module file name **MUST** include + case insensitive 'base' in the filename and + **MUST** match one of the following four formats: - * 'base_<text>.y[a]ml' - * '<text>_base.y[a]ml' - * 'base.y[a]ml' - * '<text>_base_<text>'.y[a]ml + 1.) ``base_<text>.y[a]ml`` + + 2.) ``<text>_base.y[a]ml`` + + 3.) ``base.y[a]ml`` + + 4.) ``<text>_base_<text>``.y[a]ml - where 'base' is case insensitive and where '<text>' - **MUST** contain only alphanumeric characters - and underscores '_' and **MUST NOT** contain the case - insensitive word 'base'. + where ``<text>`` **MUST** contain only alphanumeric characters and + underscores '_' and **MUST NOT** contain the case insensitive word ``base``. .. req:: :id: R-91342 :target: VNF :keyword: MUST + :validation_mode: static A VNF Heat Orchestration Template's Base Module's Environment File - **MUST** be named identical to the VNF Heat Orchestration Template's Base - Module with '.y[a]ml' replaced with '.env'. + **MUST** be named identical to the VNF Heat Orchestration Template's + Base Module with ``.y[a]ml`` replaced with ``.env``. Incremental Modules -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~ .. req:: :id: R-87247 :target: VNF :keyword: MUST + :validation_mode: static - A VNF Heat Orchestration Template's Incremental Module file name - **MUST** contain only alphanumeric characters and underscores '_' and - **MUST NOT** contain the case insensitive word 'base'. + VNF Heat Orchestration Template's Incremental Module file name + **MUST** contain only alphanumeric characters and underscores + '_' and **MUST NOT** contain the case insensitive word ``base``. .. req:: :id: R-94509 :target: VNF :keyword: MUST + :validation_mode: static - A VNF Heat Orchestration Template's Incremental Module's Environment - File **MUST** be named identical to the VNF Heat Orchestration Template's - Incremental Module with '.y[a]ml' replaced with '.env'. + A VNF Heat Orchestration Template's Incremental Module's Environment File + **MUST** be named identical to the VNF Heat Orchestration Template's + Incremental Module with ``.y[a]ml`` replaced with ``.env``. To clearly identify the incremental module, it is recommended to use the following naming options for modules: - - module_<text>.y[a]ml + - ``module_<text>.y[a]ml`` - - <text>_module.y[a]ml + - ``<text>_module.y[a]ml`` - - module.y[a]ml + - ``module.y[a]ml`` - - <text>_module_<text>.y[a]ml + - ``<text>_module_<text>.y[a]ml`` Cinder Volume Modules ~~~~~~~~~~~~~~~~~~~~~ @@ -323,56 +330,57 @@ Cinder Volume Modules :id: R-82732 :target: VNF :keyword: MUST + :validation_mode: static - A VNF Heat Orchestration Template's Cinder Volume Module **MUST** be - named identical to the base or incremental module it is supporting with - '_volume appended' + A VNF Heat Orchestration Template's Cinder Volume Module **MUST** + be named identical to the base or incremental module it is supporting with + ``_volume`` appended. .. req:: :id: R-31141 :target: VNF :keyword: MUST + :validation_mode: static - A VNF Heat Orchestration Template's Cinder Volume Module's Environment - File **MUST** be named identical to the VNF Heat Orchestration Template's - Cinder Volume Module with .y[a]ml replaced with '.env'. + VNF Heat Orchestration Template's Cinder Volume Module's Environment File + **MUST** be named identical to the VNF Heat Orchestration Template's + Cinder Volume Module with ``.y[a]ml`` replaced with ``.env``. Nested Heat file -~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~ .. req:: :id: R-76057 :target: VNF :keyword: MUST + :validation_mode: static - A VNF Heat Orchestration Template's Nested YAML file name **MUST** - contain only alphanumeric characters and underscores '_' and **MUST NOT** - contain the case insensitive word 'base'. + VNF Heat Orchestration Template's Nested YAML file name **MUST** contain + only alphanumeric characters and underscores '_' and + **MUST NOT** contain the case insensitive word ``base``. .. req:: :id: R-70276 :target: VNF :keyword: MUST NOT - :test: no test found - :test_case: no test found - :test_file: no test found + :validation_mode: static - A VNF HEAT's Orchestration Nested Template's YAML file - name **MUST NOT** be in the format '{vm-type}.y[a]ml' where - '{vm-type}' is defined in the Heat Orchestration Template. + A VNF HEAT's Orchestration Nested Template's YAML file name **MUST NOT** + be in the format ``{vm-type}.y[a]ml`` where ``{vm-type}`` is defined + in the Heat Orchestration Template. Examples include - - <text>.y[a]ml + - ``<text>.y[a]ml`` - - nest_<text>.y[a]ml + - ``nest_<text>.y[a]ml`` - - <text>_nest.y[a]ml + - ``<text>_nest.y[a]ml`` - - nest.y[a]ml + - ``nest.y[a]ml`` - - <text>_nest_<text>.y[a]ml + - ``<text>_nest_<text>.y[a]ml`` VNF Heat Orchestration Template's Nested YAML file does not have a corresponding environment files, per OpenStack specifications. @@ -395,57 +403,62 @@ into three categories: ONAP Base Module Output Parameters ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -ONAP Base Module Output Parameters are declared in the 'outputs:'' section of -the VNF's Heat Orchestration Template's Base Module. A Base Module Output -Parameter is available as an input parameter (i.e., declared in the -'parameters:'' section) to all Incremental Modules in the VNF. +ONAP Base Module Output Parameters are declared in the ``outputs:`` section +of the VNF's Heat Orchestration Template's Base Module. A Base Module Output +Parameter is available as an input parameter (i.e., declared in +the ``parameters:`` section) to all Incremental Modules in the VNF. A Base Module Output Parameter may be used as an input parameter in any -incremental module in the VNF. Note that the parameter is not -available to other VNFs. +incremental module in the VNF. Note that the parameter is not available to +other VNFs. .. req:: :id: R-52753 :target: VNF :keyword: MUST + :validation_mode: static VNF's Heat Orchestration Template's Base Module's output parameter's name and type **MUST** match the VNF's Heat Orchestration Template's - incremental Module's name and type unless the output parameter is of type - 'comma_delimited_list', then the corresponding input parameter **MUST** - be declared as type 'json'. + incremental Module's name and type unless the output parameter is of + type ``comma_delimited_list``, then the corresponding input parameter + **MUST** be declared as type ``json``. If the Output parameter has a comma_delimited_list value (e.g., a collection -of UUIDs from a Resource Group), then the corresponding input parameter -must be declared as type json and not a comma_delimited_list, which is -actually a string value with embedded commas. +of UUIDs from a Resource Group), then the corresponding input parameter must +be declared as type ``json`` and not a ``comma_delimited_list``, +which is actually a string value with embedded commas. .. req:: :id: R-22608 :target: VNF :keyword: MUST NOT + :validation_mode: static When a VNF's Heat Orchestration Template's Base Module's output parameter is declared as an input parameter in an Incremental Module, - the parameter attribute 'constraints:' **MUST NOT** be declared. + the parameter attribute ``constraints:`` **MUST NOT** be declared. Additional details on ONAP Base Module Output Parameters are provided in :ref:`ONAP Output Parameter Names` and ONAP VNF Modularity. ONAP Volume Module Output Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. req:: :id: R-89913 :target: VNF :keyword: MUST + :validation_mode: static A VNF's Heat Orchestration Template's Cinder Volume Module Output - Parameter(s) **MUST** include the UUID(s) of the Cinder Volumes created in - template, while other Output Parameters **MAY** be included. + Parameter(s) + **MUST** include the + UUID(s) of the Cinder Volumes created in template, + while others **MAY** be included. A VNF's Heat Orchestration Template's Cinder Volume Module Output Parameter(s) are only available for the module (base or incremental) that the volume @@ -456,27 +469,29 @@ template is associated with. :id: R-07443 :target: VNF :keyword: MUST + :validation_mode: static A VNF's Heat Orchestration Templates' Cinder Volume Module Output Parameter's name and type **MUST** match the input parameter name and type in the corresponding Base Module or Incremental Module unless the Output - Parameter is of the type 'comma_delimited_list', then the corresponding input - parameter **MUST** be declared as type 'json'. + Parameter is of the type ``comma_delimited_list``, then the corresponding + input parameter **MUST** be declared as type ``json``. If the Output parameter has a comma_delimited_list value (e.g., a collection of UUIDs from a Resource Group), then the corresponding input parameter must -be declared as type json and not a comma_delimited_list, which is actually a -string value with embedded commas. +be declared as type json and not a comma_delimited_list, which is actually +a string value with embedded commas. .. req:: :id: R-20547 :target: VNF :keyword: MUST NOT + :validation_mode: static When an ONAP Volume Module Output Parameter is declared as an input - parameter in a base or an incremental module Heat Orchestration Template, - parameter constraints **MUST NOT** be declared. + parameter in a base or an incremental module Heat Orchestration + Template, parameter constraints **MUST NOT** be declared. Additional details on ONAP Base Module Output Parameters are provided in :ref:`ONAP Output Parameter Names` and :ref:`ONAP Heat Cinder Volumes`. @@ -501,18 +516,22 @@ ONAP does not support the use of heat stack-update command for scaling :id: R-39349 :target: VNF :keyword: MUST NOT + :validation_mode: static - A VNF Heat Orchestration Template **MUST NOT** be designed to - utilize the OpenStack 'heat stack-update' command for scaling - (growth/de-growth). + A VNF Heat Orchestration Template **MUST NOT** be designed to utilize the + OpenStack ``heat stack-update`` command for scaling (growth/de-growth). .. req:: :id: R-43413 :target: VNF :keyword: MUST + :validation_mode: static + + A VNF **MUST** utilize a modular Heat Orchestration Template design to + support scaling (growth/de-growth). - A VNF **MUST** utilize a modular Heat Orchestration Template - design to support scaling (growth/de-growth). +It is important to note that ONAP only supports heat stack-update for +image upgrades. Scope of a Heat Orchestration Template ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -522,9 +541,10 @@ Scope of a Heat Orchestration Template :id: R-59482 :target: VNF :keyword: MUST NOT + :validation_mode: static A VNF's Heat Orchestration Template **MUST NOT** be VNF instance - specific or Cloud site specific. + specific or cloud site specific. ONAP provides the instance specific parameter values to the Heat Orchestration Template at orchestration time. @@ -534,9 +554,10 @@ Orchestration Template at orchestration time. :id: R-01896 :target: VNF :keyword: MUST + :validation_mode: static - A VNF's Heat Orchestration Template's parameter values that are - constant across all deployments **MUST** be declared in a Heat Orchestration + A VNF's Heat Orchestration Template's parameter values that are constant + across all deployments **MUST** be declared in a Heat Orchestration Template Environment File. |