diff options
Diffstat (limited to 'docs/Chapter5')
| -rw-r--r-- | docs/Chapter5/Heat/ONAP Heat Cinder Volumes.rst | 122 | ||||
| -rw-r--r-- | docs/Chapter5/Heat/ONAP Heat Support of Environment Files.rst | 30 | ||||
| -rw-r--r-- | docs/Chapter5/Heat/ONAP Heat Template Constructs.rst | 629 | ||||
| -rw-r--r-- | docs/Chapter5/Heat/ONAP Heat VNF Modularity.rst | 20 |
4 files changed, 409 insertions, 392 deletions
diff --git a/docs/Chapter5/Heat/ONAP Heat Cinder Volumes.rst b/docs/Chapter5/Heat/ONAP Heat Cinder Volumes.rst index 90fb33b..8c10e4b 100644 --- a/docs/Chapter5/Heat/ONAP Heat Cinder Volumes.rst +++ b/docs/Chapter5/Heat/ONAP Heat Cinder Volumes.rst @@ -45,8 +45,8 @@ while others **MAY** be included. As stated in :need:`R-07443`, 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'. +the Output Parameter is of the type ``comma_delimited_list``, +then the corresponding input parameter **MUST** be declared as type ``json``. A single volume module must create only the volumes required by a single Incremental module or Base module. @@ -79,94 +79,90 @@ Optional Property availability_zone :id: R-25190 :target: VNF :keyword: SHOULD NOT + :updated: casablanca - A VNF's Heat Orchestration Template's Resource 'OS::Cinder::Volume' - **SHOULD NOT** declare the property 'availability_zone'. + A VNF's Heat Orchestration Template's Resource ``OS::Cinder::Volume`` + **SHOULD NOT** declare the property ``availability_zone``. If the property is used, the value **MUST** -be enumerated in the environment file and must be set to nova', which +be enumerated in the environment file and must be set to ``nova``, which is the default. There are no requirements on the parameter naming convention with the exception that the naming convention **MUST NOT** be the -same as the 'OS::Nova::Server' property 'availability_zone' (i.e., -'availability_zone_{index}'). +same as the ``OS::Nova::Server`` property ``availability_zone`` (i.e., +``availability_zone_{index}``). Optional Property volume_type ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -OpenStack supports multiple volume types. If the OS::Cinder::Volume optional -property volume_type is not specified, the OpenStack default volume type is -used. If a specific volume type is required, the property is used and -the value **MUST** be enumerated in the environment file. There are no -requirements on the parameter naming convention +OpenStack supports multiple volume types. If the ``OS::Cinder::Volume`` +optional property ``volume_type`` is not specified, the OpenStack default +``volume type`` is used. If a specific volume type is required, the property +is used and the value **MUST** be enumerated in the environment file. There +are no requirements on the parameter naming convention. Cinder Volume Examples ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ *Examples: Volume Template* -A VNF has a Cinder volume module, named incremental\_volume.yaml, that -creates an independent Cinder volume for a VM in the module -incremental.yaml. The incremental\_volume.yaml defines a parameter in -the output section, lb\_volume\_id\_0 which is the UUID of the cinder -volume. lb\_volume\_id\_0 is defined as a parameter in incremental.yaml. -ONAP captures the UUID value of lb\_volume\_id\_0 from the volume module +A VNF has a Cinder volume module, named incremental_volume.yaml, +that creates an independent Cinder volume for a VM in the module +incremental.yaml. The incremental_volume.yaml defines a parameter in +the output section, dns_volume_id_0 which is the UUID of the cinder volume. +dns_volume_id_0 is defined as a parameter in incremental.yaml. +ONAP captures the UUID value of dns_volume_id_0 from the volume module output statement and provides the value to the incremental module. Note that the example below is not a complete Heat Orchestration -Template. The {vm-type} has been defined as "lb" for load balancer +Template. The {vm-type} has been defined as "dns". -incremental\_volume.yaml +incremental_volume.yaml .. code-block:: yaml - parameters: + parameters: vnf_name: - type: string - lb_volume_size_0: - type: number - ... + type: string + dns_volume_size_0: + type: number + ... - resources: + resources: dns_volume_0: - type: OS::Cinder::Volume - properties: - name: - str_replace: - template: VNF_NAME_volume_0 - params: - VNF_NAME: { get_param: vnf_name } - size: {get_param: dns_volume_size_0} - ... - - outputs: - lb_volume_id_0: - value: {get_resource: dns_volume_0} - ... - + type: OS::Cinder::Volume + properties: + name: + str_replace: + template: VNF_NAME_volume_0 + params: + VNF_NAME: { get_param: vnf_name } + size: {get_param: dns_volume_size_0} + ... + outputs: + dns_volume_id_0: + value: {get_resource: dns_volume_0} + ... incremental.yaml .. code-block:: yaml - parameters: - lb_name_0: - type: string - lb_volume_id_0: - type: string - ... - - resources: - lb_0: - type: OS::Nova::Server - properties: - name: {get_param: dns_name_0} - networks: - ... - - lb_0_volume_attach: - type: OS::Cinder::VolumeAttachment - properties: - instance_uuid: { get_resource: lb_0 } - volume_id: { get_param: lb_volume_id_0 } - - + parameters: + dns_server_0: + type: string + dns_volume_id_0: + type: string + ... + + resources: + dns_server_0: + type: OS::Nova::Server + properties: + name: {get_param: dns_name_0} + networks: + ... + dns_volume_attach_0: + type: OS::Cinder::VolumeAttachment + properties: + instance_uuid: { get_resource: dns_server_0 } + volume_id: { get_param: dns_volume_id_0 } diff --git a/docs/Chapter5/Heat/ONAP Heat Support of Environment Files.rst b/docs/Chapter5/Heat/ONAP Heat Support of Environment Files.rst index ba8cd68..aed56e5 100644 --- a/docs/Chapter5/Heat/ONAP Heat Support of Environment Files.rst +++ b/docs/Chapter5/Heat/ONAP Heat Support of Environment Files.rst @@ -12,32 +12,14 @@ mandatory. A Heat Orchestration Template uploaded to ONAP must have a corresponding environment file, even if no parameters are required to be enumerated. -(Note that ONAP does not programmatically enforce the use of -an environment file.) +*(Note that ONAP does not programmatically enforce the use of +an environment file.)* -.. req:: - :id: R-67205 - :target: VNF - :keyword: MUST +As stated in :need:`R-38474`, :need:`R-81725`, and :need:`R-53433`: - The VNF Heat Orchestration Template **MUST** have a corresponding - environment file for a Base Module. - -.. req:: - :id: R-35727 - :target: VNF - :keyword: MUST - - The VNF Heat Orchestration Template **MUST** have a - corresponding environment file for an Incremental module. - -.. req:: - :id: R-22656 - :target: VNF - :keyword: MUST - - The VNF Heat Orchestration Template **MUST** have a - corresponding environment file for a Cinder Volume Module. + * A VNF's Base Module **MUST** have a corresponding Environment File. + * A VNF's Incremental Module **MUST** have a corresponding Environment File. + * A VNF's Cinder Volume Module **MUST** have a corresponding environment File. A nested heat template must not have an environment file; OpenStack does not support it. diff --git a/docs/Chapter5/Heat/ONAP Heat Template Constructs.rst b/docs/Chapter5/Heat/ONAP Heat Template Constructs.rst index f24d2f4..76ec0c1 100644 --- a/docs/Chapter5/Heat/ONAP Heat Template Constructs.rst +++ b/docs/Chapter5/Heat/ONAP Heat Template Constructs.rst @@ -21,11 +21,13 @@ either statically by repeated definition or dynamically by using the resource OS::Heat::ResourceGroup. Nested Heat Template Requirements -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -ONAP supports nested Heat Orchestration Templates. A Base Module, -Incremental Module, and Cinder Volume Module may use nested heat. +ONAP supports nested Heat Orchestration Templates. +As stated in Requirements :need:`R-36582`, :need:`R-56721`, and +:need:`R-30395`, a Base Module, Incremental Module, and Cinder Volume +Module may use nested heat. .. req:: :id: R-00228 @@ -39,42 +41,50 @@ Incremental Module, and Cinder Volume Module may use nested heat. :id: R-01101 :target: VNF :keyword: MAY + :updated: casablanca A VNF's Heat Orchestration Template **MAY** reference the nested heat dynamically using the resource - 'OS::Heat::ResourceGroup'. + ``OS::Heat::ResourceGroup``. .. req:: :id: R-60011 :target: VNF :keyword: MUST + :validation_mode: static + :updated: casablanca A VNF's Heat Orchestration Template **MUST** have no more than two levels of nesting. -As stated in :need:`R-67231` a VNF's Heat Orchestration template's -Environment File's **MUST NOT** contain the "resource_registry:" section. +.. req:: + :id: R-70112 + :target: VNF + :keyword: MUST + :validation_mode: static + :introduced: casablanca + + A VNF's Heat Orchestration Template **MUST** reference a Nested YAML + file by name. The use of ``resource_registry`` in the VNF's Heat + Orchestration Templates Environment File **MUST NOT** be used. Two levels of nesting is defined as follows: A base module, incremental module, or cinder volume module references a nested heat file either -statically or by using the resource 'OS::Heat::ResourceGroup'. -This file is the first level of nesting. -If first level file then references a nested file, that file is -the second level of nesting. - +statically or by using the resource ``OS::Heat::ResourceGroup``. +The referenced YAML heat file is the first level of nested heat. +If first level nested YAML file references a nested heat file, that file is +the second level of nested heat. -.. req:: - :id: R-89868 - :target: VNF - :keyword: MUST - - The VNF Heat Orchestration Template **MUST** have unique - file names within the scope of the VNF for a nested heat yaml file. +As stated in requirement :need:`R-99646`, 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. .. req:: :id: R-52530 :target: VNF :keyword: MUST + :validation_mode: static + :updated: casablanca A VNF's Heat Orchestration Template's Nested YAML file **MUST** be in the same directory hierarchy as the VNF's Heat @@ -97,10 +107,16 @@ the second level of nesting. a VNF's Heat Orchestration Templates (when the VNF is composed of two or more Heat Orchestration Templates). +Note that as stated in requirement :need:`R-00011`, a VNF's Heat Orchestration +Template's Nested YAML file's parameter's **MUST NOT** have a parameter +constraint defined. + .. req:: :id: R-11041 :target: VNF :keyword: MUST + :validation_mode: static + :updated: casablanca All parameters defined in a VNFs Nested YAML file **MUST** be passed in as properties of the resource calling @@ -108,66 +124,64 @@ the second level of nesting. Note that: -- As stated in requirement :need:`R-00011`, a VNF's Heat Orchestration - Template's Nested YAML file's parameter's **MUST NOT** have - a parameter constraint defined. - -- As stated in Requirement :need:`R-44491`, if a VNF's Heat Orchestration - Template's OS::Nova::Server Resource metadata map value parameter - 'vnf\_id' is passed into a Nested YAML - file, the parameter name 'vnf\_id' **MUST NOT** change. - -- As stated in Requirement :need:`R-86237`, if a VNF's Heat Orchestration - Template's OS::Nova::Server Resource metadata map value parameter - 'vf\_module\_id' is passed into a Nested YAML - file, the parameter name 'vf\_module\_id' **MUST NOT** change. - -- As stated in Requirement :need:`R-16576`, if a VNF's Heat Orchestration - Template's OS::Nova::Server Resource metadata map value parameter - 'vnf\_name' is passed into a Nested YAML - file, the parameter name 'vnf\_name' **MUST NOT** change. - -- As stated in Requirement :need:`R-49177`, if a VNF's Heat Orchestration - Template's OS::Nova::Server Resource metadata map value parameter - 'vf\_module\_name' is passed into a Nested YAML - file, the parameter name 'vf\_module\_name' **MUST NOT** change. - -- As stated in Requirement :need:`R-70757`, if a VNF's Heat Orchestration - Template's OS::Nova::Server Resource metadata map value parameter - 'vm\_role' is passed into a Nested YAML - file, the parameter name 'vm\_role' **MUST NOT** change. - -- As stated in Requirement :need:`R-22441`, if a VNF's Heat Orchestration - Template's OS::Nova::Server Resource metadata map value parameter - 'vf\_module\_index' is passed into a Nested YAML - file, the parameter name 'vf\_module\_index' **MUST NOT** change. - -- As stated in Requirement :need:`R-75202`, if a VNF's Heat Orchestration - Template's OS::Nova::Server Resource metadata map value parameter - 'workload\_context' is passed into a Nested YAML - file, the parameter name 'workload\_context' **MUST NOT** change. - -- As stated in Requirement :need:`R-62954`, if a VNF's Heat Orchestration - Template's OS::Nova::Server Resource metadata map value parameter - 'environment\_context' is passed into a Nested YAML - file, the parameter name 'environment\_context' **MUST NOT** change. - -- With nested templates, outputs are required to expose any resource - properties of the child templates to the parent template. Those would - not explicitly be declared as parameters but simply referenced as - get\_attribute targets against the "parent" resource. - -- A parameter declared in the outputs: section of a nested template can - be accessed from the parent template as an attribute (i.e., via - get\_attr) of the "pseudo resource" whose type is in the nested - template. In the case of a OS::Heat::ResourceGroup, an output will be - an attribute of the OS::Heat::ResourceGroup itself, and will be an - array from the perspective of the parent template. +As stated in Requirement :need:`R-44491`, if a VNF's Heat Orchestration +Template's ``OS::Nova::Server`` Resource ``metadata`` map value parameter +``vnf_id`` is passed into a Nested YAML file, the parameter name +``vnf_id`` **MUST NOT** change. + +As stated in Requirement :need:`R-86237`, if a VNF's Heat Orchestration +Template's ``OS::Nova::Server`` Resource ``metadata`` map value parameter +``vf_module_id`` is passed into a Nested YAML file, the parameter name +``vf_module_id`` **MUST NOT** change. + +As stated in Requirement :need:`R-16576`, if a VNF's Heat Orchestration +Template's ``OS::Nova::Server`` Resource ``metadata`` map value parameter +``vnf_name`` is passed into a Nested YAML file, the parameter name +``vnf_name`` **MUST NOT** change. + +As stated in Requirement :need:`R-49177`, if a VNF's Heat Orchestration +Template's ``OS::Nova::Server`` Resource ``metadata`` map value parameter +``vf_module_name`` is passed into a Nested YAML file, the parameter name +``vf_module_name`` **MUST NOT** change. + +As stated in Requirement :need:`R-70757`, if a VNF's Heat Orchestration +Template's ``OS::Nova::Server`` Resource ``metadata`` map value parameter +``vm_role`` is passed into a Nested YAML file, the parameter name +``vm_role`` **MUST NOT** change. + +As stated in Requirement :need:`R-22441`, if a VNF's Heat Orchestration +Template's ``OS::Nova::Server`` Resource ``metadata`` map value parameter +``vf_module_index`` is passed into a Nested YAML file, the parameter +name ``vf_module_index`` **MUST NOT** change. + +As stated in Requirement :need:`R-75202`, if a VNF's Heat Orchestration +Template's ``OS::Nova::Server`` Resource ``metadata`` map value parameter +``workload_context`` is passed into a Nested YAML file, the parameter +name ``workload_context`` **MUST NOT** change. + +As stated in Requirement :need:`R-62954`, if a VNF's Heat Orchestration +Template's ``OS::Nova::Server`` Resource ``metadata`` map value parameter +``environment_context`` is passed into a Nested YAML file, the parameter +name ``environment_context`` **MUST NOT** change. + +With nested templates, outputs are required to expose any resource +properties of the child templates to the parent template. Those would +not explicitly be declared as parameters but simply referenced as +``get_attribute`` targets against the "parent" resource. + +A parameter declared in the outputs: section of a nested template can +be accessed from the parent template as an attribute (i.e., via +``get_attr``) of the "pseudo resource" whose type is in the nested +template. In the case of a ``OS::Heat::ResourceGroup``, an output will be +an attribute of the ``OS::Heat::ResourceGroup`` itself, and will be an +array from the perspective of the parent template. .. req:: :id: R-17528 :target: VNF :keyword: MUST + :validation_mode: static + :updated: casablanca A VNF's Heat Orchestration Template's first level Nested YAML file **MUST NOT** contain more than one ``OS::Nova::Server`` resource. @@ -181,71 +195,71 @@ incremental.yaml .. code-block:: yaml - Resources: - dns_server_0: - type: nested.yaml - properties: - dns_image_name: { get_param: dns_image_name } - dns_flavor_name: { get_param: dns_flavor_name } - availability_zone: { get_param: availability_zone_0 } - security_group: { get_param: DNS_shared_sec_grp_id } - oam_net_id: { get_param: oam_protected_net_id } - dns_oam_ip: { get_param: dns_oam_ip_0 } - dns_name: { get_param: dns_name_0 } - vnf_name: { get_param: vnf_name } - vnf_id: { get_param: vnf_id } - vf_module_id: {get_param: vf_module_id} - - dns_server_1: - type: nested.yaml - properties: - dns_image_name: { get_param: dns_image_name } - dns_flavor_name: { get_param: dns_flavor_name } - availability_zone: { get_param: availability_zone_1 } - security_group: { get_param: DNS_shared_sec_grp_id } - oam_net_id: { get_param: oam_protected_net_id } - dns_oam_ip: { get_param: dns_oam_ip_1 } - dns_name: { get_param: dns_name_1 } - vnf_name: { get_param: vnf_name } - vnf_id: { get_param: vnf_id } - vf_module_id: {get_param: vf_module_id} + resources: + dns_server_0: + type: nested.yaml + properties: + dns_image_name: { get_param: dns_image_name } + dns_flavor_name: { get_param: dns_flavor_name } + availability_zone: { get_param: availability_zone_0 } + security_group: { get_param: DNS_shared_sec_grp_id } + oam_net_id: { get_param: oam_protected_net_id } + dns_oam_ip: { get_param: dns_oam_ip_0 } + dns_name: { get_param: dns_name_0 } + vnf_name: { get_param: vnf_name } + vnf_id: { get_param: vnf_id } + vf_module_id: {get_param: vf_module_id} + + dns_server_1: + type: nested.yaml + properties: + dns_image_name: { get_param: dns_image_name } + dns_flavor_name: { get_param: dns_flavor_name } + availability_zone: { get_param: availability_zone_1 } + security_group: { get_param: DNS_shared_sec_grp_id } + oam_net_id: { get_param: oam_protected_net_id } + dns_oam_ip: { get_param: dns_oam_ip_1 } + dns_name: { get_param: dns_name_1 } + vnf_name: { get_param: vnf_name } + vnf_id: { get_param: vnf_id } + vf_module_id: {get_param: vf_module_id} nested.yaml .. code-block:: yaml - dns_oam_0_port: - type: OS::Neutron::Port - properties: - name: - str_replace: - template: VNF_NAME_dns_oam_port - params: - VNF_NAME: {get_param: vnf_name} - network: { get_param: oam_net_id } - fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}] - security_groups: [{ get_param: security_group }] - - dns_servers: - type: OS::Nova::Server - properties: - name: { get_param: dns_names } - image: { get_param: dns_image_name } - flavor: { get_param: dns_flavor_name } - availability_zone: { get_param: availability_zone } - networks: - - port: { get_resource: dns_oam_0_port } - metadata: - vnf_id: { get_param: vnf_id } - vf_module_id: { get_param: vf_module_id } - vnf_name {get_param: vnf_name } + dns_oam_0_port: + type: OS::Neutron::Port + properties: + name: + str_replace: + template: VNF_NAME_dns_oam_port + params: + VNF_NAME: {get_param: vnf_name} + network: { get_param: oam_net_id } + fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}] + security_groups: [{ get_param: security_group }] + + dns_servers: + type: OS::Nova::Server + properties: + name: { get_param: dns_names } + image: { get_param: dns_image_name } + flavor: { get_param: dns_flavor_name } + availability_zone: { get_param: availability_zone } + networks: + - port: { get_resource: dns_oam_0_port } + metadata: + vnf_id: { get_param: vnf_id } + vf_module_id: { get_param: vf_module_id } + vnf_name {get_param: vnf_name } Use of Heat ResourceGroup ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The OS::Heat::ResourceGroup is a useful Heat element for creating multiple instances of a given resource or collection of resources. -Typically, it is used with a nested Heat template, to create, for +Typically, it is used with a nested Heat template to create, for example, a set of identical OS::Nova::Server resources plus their related OS::Neutron::Port resources via a single resource in a master template. @@ -267,11 +281,13 @@ OS::Heat::ResourceGroup: .. code-block:: yaml - type: OS::Heat::ResourceGroup - resource_def: - type: my_nested_vm_template.yaml - properties: - name: {get_param: [vm_name_list, "%index%"]} + type: OS::Heat::ResourceGroup + properties: + . . . + resource_def: + type: my_nested_vm_template.yaml + properties: + name: {get_param: [vm_name_list, "%index%"]} Although this appears to use the nth entry of the vm_name_list list for the nth element of the OS::Heat::ResourceGroup, it will in fact result @@ -285,16 +301,18 @@ ResourceGroup: .. code-block:: yaml - type: OS::Heat::ResourceGroup - resource_def: - type: my_nested_vm_template.yaml - properties: - names: {get_param: vm_name_list} - index: "%index%" + type: OS::Heat::ResourceGroup + properties: + . . . + resource_def: + type: my_nested_vm_template.yaml + properties: + names: {get_param: vm_name_list} + index: "%index%" You can then reference within the nested template as: -{ get\_param: [names, {get\_param: index} ] } +{ get_param: [names, {get_param: index} ] } OS::Heat::ResourceGroup Property count ++++++++++++++++++++++++++++++++++++++++ @@ -304,9 +322,11 @@ OS::Heat::ResourceGroup Property count :id: R-50011 :target: VNF :keyword: MUST + :validation_mode: static + :updated: casablanca - A VNF's Heat Orchestration Template's 'OS::Heat::ResourceGroup' - property 'count' **MUST** be enumerated in the VNF's + A VNF's Heat Orchestration Template's ``OS::Heat::ResourceGroup`` + property ``count`` **MUST** be enumerated in the VNF's Heat Orchestration Template's Environment File and **MUST** be assigned a value. @@ -314,63 +334,63 @@ This is required for ONAP to build the TOSCA model for the VNF. .. code-block:: yaml - type: OS::Heat::ResourceGroup - properties: - count: { get_param: count } - index_var: index - resource_def: - type: my_nested_vm_template.yaml - properties: - names: {get_param: vm_name_list} - index: index + type: OS::Heat::ResourceGroup + properties: + count: { get_param: count } + index_var: index + resource_def: + type: my_nested_vm_template.yaml + properties: + names: {get_param: vm_name_list} + index: index Availability Zone and ResourceGroups ++++++++++++++++++++++++++++++++++++++++ -The resource OS::Heat::ResourceGroup and the property availability\_zone +The resource OS::Heat::ResourceGroup and the property availability_zone has been an "issue" with a few VNFs since ONAP only supports -availability\_zone as a string parameter and not a -comma\_delimited\_list. This makes it difficult to use a -OS::Heat::ResourceGroup to create Virtual Machines in more -than one availability zone. +availability_zone as a string parameter and not as a +comma_delimited_list. This makes it difficult to use a +OS::Heat::ResourceGroup to create Virtual Machines in more than one +availability zone. There are numerous solutions to this issue. Below are two suggested usage patterns. **Option 1:** create a CDL in the OS::Heat::ResourceGroup. In the -resource type: OS::Heat::ResourceGroup, create a comma\_delimited\_list -availability\_zones by using the intrinsic function list\_join. +resource type: OS::Heat::ResourceGroup, create a comma_delimited_list +availability_zones by using the intrinsic function list_join. .. code-block:: yaml - <resource name>: - type: OS::Heat::ResourceGroup - properties: - count: { get_param: node_count } - index_var: index - resource_def: - type: nested.yaml - properties: - index: index - avaialability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] } + <resource name>: + type: OS::Heat::ResourceGroup + properties: + count: { get_param: node_count } + index_var: index + resource_def: + type: nested.yaml + properties: + index: index + availability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] } In the nested heat .. code-block:: yaml - parameters: - avaialability_zones: - type: comma_delimited_list - description: + parameters: + availability_zones: + type: comma_delimited_list + description: - resources: - servers: - type: OS::Nova::Server - properties: - name: { get_param: [ dns_names, get_param: index ] } - image: { get_param: dns_image_name } - flavor: { get_param: dns_flavor_name } - availability_zone: { get_param: [ avaialability_zones, get_param: index ] } + resources: + servers: + type: OS::Nova::Server + properties: + name: { get_param: [ dns_names, get_param: index ] } + image: { get_param: dns_image_name } + flavor: { get_param: dns_flavor_name } + availability_zone: { get_param: [ availability_zones, get_param: index ] } **Option 2:** Create a CDL by passing the availability zone parameter into a nested heat template. An example is provided below. @@ -426,21 +446,21 @@ az_list_generate.yaml Nested Heat Template Example: OS::Heat::ResourceGroup ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -In this example, ocgapp\_volume.yml creates volumes using a +In this example, ocgapp_volume.yml creates volumes using a OS::Heat::ResourceGroup that uses nested heat by calling -ocgapp_nested_volume.yml. ocgapp\_volume.yml has an outputs: parameter -ocgapp\_volume\_ids which is declared a input parameter of type: json in -ocgapp\_volume.yml. +ocgapp_nested_volume.yml. ocgapp_volume.yml has an outputs: parameter +ocgapp_volume_ids which is declared a input parameter of type: json in +ocgapp_volume.yml. This is an example of requirement :need:`R-07443`, where 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``. -ocgapp\_volume.yml +ocgapp_volume.yml .. code-block:: yaml @@ -532,6 +552,14 @@ ocgapp_nested_volume.yml description: the ocgapp volume uuid value: {get_resource: ocgapp_volume_0} +Below is a screen shot of parameter ocgapp_volume_ids from the OpenStack +Horizon GUI showing the output. + +.. image:: ../../heat_picture3.png + :height: 334px + :width: 1186px + :scale: 50 % + The heat template below is a partial heat template, ocgapp.yml @@ -571,19 +599,19 @@ ocgapp.yml External References ^^^^^^^^^^^^^^^^^^^^^^ -Heat templates *should not* reference any HTTP-based resource +Heat templates *must not* reference any HTTP-based resource definitions, any HTTP-based nested configurations, or any HTTP-based environment files. -- During orchestration, ONAP *should not* retrieve any such resources +- During orchestration, ONAP *must not* retrieve any such resources from external/untrusted/unknown sources. -- VNF images should not contain such references in user-data or other +- VNF images must not contain external references in user-data or other configuration/operational scripts that are specified via Heat or encoded into the VNF image itself. -*Note:* HTTP-based references are acceptable if the HTTP-based reference -is accessing information with the VM private/internal network. +*Note: HTTP-based references are acceptable if the HTTP-based reference +is accessing information utilizing the VM private/internal network.* Note that Namespaces in XML (defined at http://www.w3.org/TR/2009/REC-xml-names-20091208/) are allowed if the @@ -597,11 +625,11 @@ Name (URN). The namespace URI is not used by XML the parser to look up information. The purpose of using an URI is to give the namespace a unique name. -Heat Files Support (get\_file) +Heat Files Support (get_file) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Heat Templates may contain the inclusion of text files into Heat -templates via the Heat get\_file directive. This may be used, for +templates via the Heat get_file directive. This may be used, for example, to define a common "user-data" script, or to inject files into a VM on startup via the "personality" property. @@ -612,12 +640,14 @@ Support for Heat Files is subject to the following limitations: :id: R-76718 :target: VNF :keyword: MUST + :validation_mode: static + :updated: casablanca If a VNF's Heat Orchestration Template uses the intrinsic function - 'get\_file', the 'get\_file' target **MUST** be referenced in + ``get_file``, the ``get_file`` target **MUST** be referenced in the Heat Orchestration Template by file name. -The 'get\_file' target files are on-boarded to SDC in the same package +The ``get_file`` target files are on-boarded to SDC in the same package that contains the VNF's complete Heat Orchestration Template. @@ -625,14 +655,18 @@ that contains the VNF's complete Heat Orchestration Template. :id: R-41888 :target: VNF :keyword: MUST NOT + :validation_mode: static + :updated: casablanca A VNF's Heat Orchestration Template intrinsic function - 'get\_file' **MUST NOT** utilize URL-based file retrieval. + ``get_file`` **MUST NOT** utilize URL-based file retrieval. .. req:: :id: R-62177 :target: VNF :keyword: MUST + :validation_mode: static + :updated: casablanca When using the intrinsic function get_file, the included files **MUST** have unique file names within the scope of the VNF. @@ -641,22 +675,26 @@ that contains the VNF's complete Heat Orchestration Template. :id: R-87848 :target: VNF :keyword: MUST + :validation_mode: static + :updated: casablanca - A VNF's Heat Orchestration Template's 'get\_file' target files - **MUST** be in the same directory hierarchy as the VNF's Heat - Orchestration Templates. + When using the intrinsic function get_file, ONAP does not support + a directory hierarchy for included files. All files must be in a + single, flat directory per VNF. A VNF's Heat Orchestration + Template's ``get_file`` target files **MUST** be in the same + directory hierarchy as the VNF's Heat Orchestration Templates. ONAP does not support a hierarchical structure. A VNF's YAML files must be in a single, flat directory. - .. req:: :id: R-05050 :target: VNF :keyword: MAY + :updated: casablanca A VNF's Heat Orchestration Templates intrinsic function - 'get\_file' <content key> **MAY** be used: + ``get_file`` <content key> **MAY** be used: * more than once in a VNF's Heat Orchestration Template * in two or more of a VNF's Heat Orchestration Templates @@ -687,10 +725,10 @@ Due to this behavior, the recommended usage of keypairs is in a more generic manner which does not require the pre-requisite creation of a keypair. The Heat should be structured in such a way as to: -- Pass a public key as a parameter value instead of a keypair name + - Pass a public key as a parameter value instead of a keypair name -- Create a new keypair within The VNF Heat Orchestration Template (in the - base module) based on an existing public key for use within that VNF + - Create a new keypair within the VNF Heat templates (in the base module) + based on an existing public key for use within that VNF By following this approach, the end result is the same as pre-creating the keypair using the public key – i.e., that public key will be @@ -709,23 +747,23 @@ of lb (for load balancer)):* .. code-block:: yaml - parameters: + parameters: vnf_name: - type: string + type: string lb_ssh_public_key: - type: string + type: string - resources: - my_keypair: - type: OS::Nova::Keypair - properties: - name: - str_replace: - template: VNF_NAME_key_pair - params: - VNF_NAME: { get_param: vnf_name } - public_key: {get_param: lb_ssh_public_key} - save_private_key: false + resources: + lb_keypair_0: + type: OS::Nova::Keypair + properties: + name: + str_replace: + template: VNF_NAME_key_pair + params: + VNF_NAME: { get_param: vnf_name } + public_key: {get_param: lb_ssh_public_key} + save_private_key: false Security Groups ^^^^^^^^^^^^^^^^^ @@ -759,49 +797,45 @@ balancer and db for database. .. code-block:: yaml - resources: - db_server_group: - type: OS::Nova::ServerGroup - properties: - name: + resources: + db_server_group: + type: OS::Nova::ServerGroup + properties: + name: str_replace: - params: - $vnf_name: {get_param: vnf_name} - template: $vnf_name-server_group1 - policies: - - anti-affinity - - lb_server_group: - type: OS::Nova::ServerGroup - properties: - name: + params: + $vnf_name: {get_param: vnf_name} + template: $vnf_name-server_group1 + policies: + - anti-affinity + lb_server_group: + type: OS::Nova::ServerGroup + properties: + name: str_replace: - params: - $vnf_name: {get_param: vnf_name} - template: $vnf_name-server_group2 - policies: - - affinity - - db_0: - type: OS::Nova::Server - properties: - ... - scheduler_hints: - group: {get_resource: db_server_group} - - db_1: - type: OS::Nova::Server - properties: - ... - scheduler_hints: - group: {get_resource: db_server_group} - - lb_0: - type: OS::Nova::Server - properties: - ... - scheduler_hints: - group: {get_resource: lb_server_group} + params: + $vnf_name: {get_param: vnf_name} + template: $vnf_name-server_group2 + policies: + - affinity + db_server_0: + type: OS::Nova::Server + properties: + ... + scheduler_hints: + group: {get_resource: db_server_group} + db_server_1: + type: OS::Nova::Server + properties: + ... + scheduler_hints: + group: {get_resource: db_server_group} + lb_server_0: + type: OS::Nova::Server + properties: + ... + scheduler_hints: + group: {get_resource: lb_server_group} Resource Data Synchronization ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -809,7 +843,7 @@ Resource Data Synchronization For cases where synchronization is required in the orchestration of Heat resources, two approaches are recommended: -- Standard Heat depends\_on property for resources +- Standard Heat depends_on property for resources - Assures that one resource completes before the dependent resource is orchestrated. @@ -823,12 +857,12 @@ resources, two approaches are recommended: - Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle resources. - - Pre-requisite resources issue *wc\_notify* commands in user\_data. + - Pre-requisite resources issue *wc_notify* commands in user_data. - - Dependent resource define depends\_on in the + - Dependent resource define depends_on in the OS::Heat::WaitCondition resource. -*Example: "depends\_on" case* +*Example: "depends_on" case* In this example, the {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as oam to represent an @@ -836,41 +870,38 @@ oam server. .. code-block:: yaml - resources: - oam_server_01: - type: OS::Nova::Server - properties: - name: {get_param: [oam_ names, 0]} - image: {get_param: oam_image_name} - flavor: {get_param: oam_flavor_name} - availability_zone: {get_param: availability_zone_0} - networks: - - port: {get_resource: oam01_port_0} - - port: {get_resource: oam01_port_1} - user_data: - scheduler_hints: {group: {get_resource: oam_servergroup}} - user_data_format: RAW - - oam_01_port_0: - type: OS::Neutron::Port - properties: - network: {get_resource: oam_net_name} - fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}] - security_groups: [{get_resource: oam_security_group}] - - oam_01_port_1: - type: OS::Neutron::Port - properties: - network: {get_param: oam_net_name} - fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}] - security_groups: [{get_resource: oam_security_group}] - - oam_01_vol_attachment: - type: OS::Cinder::VolumeAttachment - depends_on: oam_server_01 - properties: - volume_id: {get_param: oam_vol_1} - mountpoint: /dev/vdb - instance_uuid: {get_resource: oam_server_01} + resources: + oam_server_01: + type: OS::Nova::Server + properties: + name: {get_param: [oam_names, 0]} + image: {get_param: oam_image_name} + flavor: {get_param: oam_flavor_name} + availability_zone: {get_param: availability_zone_0} + networks: + - port: {get_resource: oam01_port_0} + - port: {get_resource: oam01_port_1} + user_data: + scheduler_hints: {group: {get_resource: oam_servergroup}} + user_data_format: RAW + oam_01_port_0: + type: OS::Neutron::Port + properties: + network: {get_resource: oam_net_name} + fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}] + security_groups: [{get_resource: oam_security_group}] + oam_01_port_1: + type: OS::Neutron::Port + properties: + network: {get_param: oam_net_name} + fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}] + security_groups: [{get_resource: oam_security_group}] + oam_volume_attachment_0: + type: OS::Cinder::VolumeAttachment + depends_on: oam_server_01 + properties: + volume_id: {get_param: oam_vol_1} + mountpoint: /dev/vdb + instance_uuid: {get_resource: oam_server_01} diff --git a/docs/Chapter5/Heat/ONAP Heat VNF Modularity.rst b/docs/Chapter5/Heat/ONAP Heat VNF Modularity.rst index 70ba197..7e1ebe3 100644 --- a/docs/Chapter5/Heat/ONAP Heat VNF Modularity.rst +++ b/docs/Chapter5/Heat/ONAP Heat VNF Modularity.rst @@ -15,12 +15,12 @@ referred to as *VNF Modules*. During orchestration, these modules are deployed incrementally to create the complete VNF. As stated in :need:`R-33132`, a VNF's Heat Orchestration Template **MAY** be - 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). + 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). As stated in :need:`R-20974`, at orchestration time, the VNF's Base Module **MUST** be deployed first, prior to any incremental modules. @@ -39,6 +39,9 @@ As stated in :need:`R-37028` and :need:`R-13196`, a VNF **MUST** be composed of one Base Module and *MAY** be composed of zero to many Incremental Modules. +As stated in :need:`R-20974`, at orchestration time, the VNF's Base Module +**MUST** be deployed first, prior to any incremental modules. + ONAP also supports the concept of an optional, independently deployed Cinder volume via a separate Heat Orchestration Templates, referred to as a Cinder Volume Module. This allows the volume to persist after a VM @@ -58,6 +61,8 @@ Incremental Module. :id: R-61001 :target: VNF :keyword: MUST + :validation_mode: static + :updated: casablanca A shared Heat Orchestration Template resource must be defined in the base module. A shared resource is a resource that that will @@ -71,6 +76,9 @@ When the shared resource needs to be referenced by a resource in an incremental module, the UUID of the shared resource must be exposed by declaring an ONAP Base Module Output Parameter. +Note that a Cinder volume is not a shared resource. A volume template +must correspond 1:1 with a base module or incremental module. + An example of a shared resource is the resource OS::Neutron::SecurityGroup. Security groups are sets of IP filter rules that are applied to a VNF’s networking. The resource OS::Neutron::Port |