summaryrefslogtreecommitdiffstats
path: root/docs/Chapter5
diff options
context:
space:
mode:
authorstark, steven <ss820f@att.com>2018-09-11 09:22:03 -0700
committerstark, steven <ss820f@att.com>2018-09-11 09:23:32 -0700
commit034f8119225ff656acb53326fc85c3aa075e574f (patch)
treebcdd9532ed64327874a55940ad07b759a2aeaa62 /docs/Chapter5
parent116d208c43795f3737e356bf305f881344835fe2 (diff)
[VNFRQTS] update HEAT syntax, verbiage, reqs
commit 1, chapter 5.2.1 - 5.2.3 Issue-ID: VNFRQTS-438 Change-Id: Iddd70a450e5b782dd0930b74a5f86aa96aa8a35f Signed-off-by: stark, steven <ss820f@att.com>
Diffstat (limited to 'docs/Chapter5')
-rw-r--r--docs/Chapter5/Heat/General Guidelines for Heat.rst8
-rw-r--r--docs/Chapter5/Heat/ONAP Heat Orchestration Template Format.rst387
-rw-r--r--docs/Chapter5/Heat/ONAP Heat Orchestration Templates: Overview.rst237
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.