VNFRQTS - Breaking up Chapter 5 - Heat

Breaking up the Heat section to make it more granular.

Issue-ID: VNFRQTS-275

Change-Id: I020469d7aea199cd71c4d7c67664ad4dbc4071c9
Signed-off-by: Bozawglanian, Hagop (hb755d) <hb755d@att.com>

1 files changed, 746 insertions, 0 deletions

diff --git a/docs/Chapter5/Heat/ONAP Heat Resource ID and Parameter Naming Convention/Nova Metadata Parameters.rst b/docs/Chapter5/Heat/ONAP Heat Resource ID and Parameter Naming Convention/Nova Metadata Parameters.rst
new file mode 100644
index 0000000..adf3756
--- /dev/null
+++ b/docs/Chapter5/Heat/ONAP Heat Resource ID and Parameter Naming Convention/Nova Metadata Parameters.rst
@@ -0,0 +1,746 @@
+.. Licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+.. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
+
+.. _Nova Server - Metadata Parameters:
+
+Resource: OS::Nova::Server - Metadata Parameters
+--------------------------------------------------------------------------------
+
+The OS::Nova::Server Resource property metadata is an optional
+OpenStack property.
+The table below summarizes the mandatory and optional metadata
+supported by ONAP.
+
+The sections that follow provides the requirements associated with each
+metadata parameter.
+
+.. csv-table:: **Table 5 OS::Nova::Server Mandatory and Optional Metadata**
+   :header: Metadata Parameter Name, Parameter Type, Required, Parameter Value Provided to Heat
+   :align: center
+   :widths: auto
+
+   vnf_id, string, **MUST**, ONAP
+   vf_module_id, string, **MUST**, ONAP
+   vnf_name, string, **MUST**, ONAP
+   vf_module_name, string, **SHOULD**, ONAP
+   vm_role, string, **MAY**, YAML or Environment File
+   vf_module_index, string, **MAY**, ONAP
+   workload_context, string, **SHOULD**, ONAP
+   environment_context, string, **SHOULD**, ONAP
+
+vnf_id
+^^^^^^^^^
+
+The OS::Nova::Server Resource metadata map value parameter 'vnf_id'
+is an ONAP generated UUID that identifies the VNF.  The value
+is provided by ONAP to the VNF's Heat Orchestration
+Template at orchestration time.
+
+
+.. req::
+    :id: R-37437
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource **MUST** contain the metadata map value parameter 'vnf_id'.
+
+.. req::
+    :id: R-07507
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vnf_id' **MUST** be declared
+    as type: 'string'.
+
+.. req::
+    :id: R-55218
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vnf_id' **MUST NOT** have
+    parameter contraints defined.
+
+.. req::
+    :id: R-20856
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vnf_id' **MUST NOT** be
+    enumerated in the Heat Orchestration Template's environment file.
+
+.. req::
+    :id: R-44491
+    :target: VNF
+    :keyword: MUST NOT
+
+    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.
+
+*Example 'vnf_id' Parameter Definition*
+
+.. code-block:: yaml
+
+  parameters:
+
+    vnf_id:
+      type: string
+      description: Unique ID for this VNF instance
+
+vf_module_id
+^^^^^^^^^^^^^^^^^^^^
+
+The OS::Nova::Server Resource metadata map value parameter 'vf_module_id'
+is an ONAP generated UUID that identifies the VF Module (e.g., Heat
+Orchestration Template).  The value
+is provided by ONAP to the VNF's Heat Orchestration
+Template at orchestration time.
+
+
+.. req::
+    :id: R-71493
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource **MUST** contain the metadata map value parameter
+    'vf_module_id'.
+
+.. req::
+    :id: R-82134
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_id' **MUST**
+    be declared as type: 'string'.
+
+.. req::
+    :id: R-98374
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_id' **MUST NOT**
+    have parameter contraints defined.
+
+.. req::
+    :id: R-72871
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_id' **MUST NOT**
+    be enumerated in the Heat Orchestration Template's environment file.
+
+.. req::
+    :id: R-86237
+    :target: VNF
+    :keyword: MUST NOT
+
+    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.
+
+*Example 'vf_module_id' Parameter Definition*
+
+.. code-block:: yaml
+
+  parameters:
+
+    vnf_module_id:
+      type: string
+      description: Unique ID for this VNF module instance
+
+
+vnf_name
+^^^^^^^^^
+
+The OS::Nova::Server Resource metadata map value parameter 'vnf_name'
+is the ONAP generated alphanumeric name of the deployed VNF instance.
+The value
+is provided by ONAP to the VNF's Heat Orchestration
+Template at orchestration time.
+The parameter must be declared as type: string
+
+
+.. req::
+    :id: R-72483
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource **MUST** contain the metadata map value parameter
+    'vnf_name'.
+
+.. req::
+    :id: R-62428
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vnf_name' **MUST** be
+    declared as type: 'string'.
+
+.. req::
+    :id: R-44318
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vnf_name' **MUST NOT** have
+    parameter contraints defined.
+
+.. req::
+    :id: R-36542
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vnf_name' **MUST NOT** be
+    enumerated in the Heat Orchestration Template's environment file.
+
+.. req::
+    :id: R-16576
+    :target: VNF
+    :keyword: MUST NOT
+
+    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.
+
+*Example 'vnf_name' Parameter Definition*
+
+.. code-block:: yaml
+
+  parameters:
+
+    vnf_name:
+      type: string
+      description: Unique name for this VNF instance
+
+vf_module_name
+^^^^^^^^^^^^^^^^^^
+
+The OS::Nova::Server Resource metadata map value parameter 'vf_module_name'
+is the deployment name of the heat stack created (e.g., <STACK_NAME>) from the
+VNF's Heat Orchestration template
+in the command 'Heat stack-create'
+(e.g., 'Heat stack-create [-f <FILE>] [-e <FILE>] <STACK_NAME>').
+The 'vf_module_name' (e.g., <STACK_NAME> is specified as
+part of the orchestration process.
+
+
+.. req::
+    :id: R-68023
+    :target: VNF
+    :keyword: SHOULD
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource **SHOULD** contain the metadata map value parameter
+    'vf_module_name'.
+
+.. req::
+    :id: R-39067
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_name' **MUST**
+    be declared as type: 'string'.
+
+.. req::
+    :id: R-15480
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_name'
+    **MUST NOT** have parameter contraints defined.
+
+.. req::
+    :id: R-80374
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_name'
+    **MUST NOT** be enumerated in the Heat Orchestration Template's
+    environment file.
+
+.. req::
+    :id: R-49177
+    :target: VNF
+    :keyword: MUST
+
+    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.
+
+*Example 'vf_module_name' Parameter Definition*
+
+.. code-block:: yaml
+
+  parameters:
+
+    vf_module_name:
+      type: string
+      description: Unique name for this VNF Module instance
+
+vm_role
+^^^^^^^^^
+
+The OS::Nova::Server Resource metadata map value parameter 'vm-role'
+is a metadata tag that describes the role of the Virtual Machine.
+The 'vm_role' is stored in ONAP's A&AI module and is
+available for use by other ONAP components and/or north bound systems.
+
+
+.. req::
+    :id: R-85328
+    :target: VNF
+    :keyword: MAY
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource **MAY** contain the metadata map value parameter 'vm_role'.
+
+.. req::
+    :id: R-95430
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vm_role' **MUST** be
+    declared as type: 'string'.
+
+.. req::
+    :id: R-67597
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vm_role' **MUST NOT** have
+    parameter contraints defined.
+
+
+.. req::
+    :id: R-46823
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vnf_name' **MUST** be
+    either
+
+     - enumerated in the VNF's Heat Orchestration
+       Template's environment file.
+
+     - hard coded in the VNF's Heat Orchestration
+       Template's OS::Nova::Resource metadata property.
+
+Defining the 'vm_role' as the '{vm-type}' is a recommended convention
+
+
+.. req::
+    :id: R-86476
+    :target: VNF
+    :keyword: MUST
+
+    If a VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vm_role' value **MUST** only
+    contain alphanumeric characters and underscores '_'.
+
+.. req::
+    :id: R-70757
+    :target: VNF
+    :keyword: MUST NOT
+
+    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.
+
+*Example 'vm_role' Parameter Definition*
+
+.. code-block:: yaml
+
+  parameters:
+
+    vm_role:
+      type: string
+      description: Unique role for this VM
+
+*Example: 'vm-role' Definition: Hard Coded in
+OS::Nova::Resource metadata property*
+
+.. code-block:: yaml
+
+  resources:
+
+    dns_server_0
+      type: OS::Nova::Server
+      properties:
+        . . . .
+        metadata:
+          vm_role: dns
+
+*Example 'vm-role' Definition: Defined in Environment file
+and retrieved via 'get_param'*
+
+.. code-block:: yaml
+
+  resources:
+
+    dns_server_0:
+      type: OS::Nova::Server
+      properties:
+        . . . .
+        metadata:
+          vm_role: { get_param: vm_role }
+
+Example vnf_id, vf_module_id, vnf_name, vf_module_name, vm_role
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The example below depicts part of a Heat Orchestration Template
+that uses the five of the OS::Nova::Server metadata parameter
+discussed in this section. The {vm-type} has been defined as lb
+for load balancer.
+
+.. code-block:: yaml
+
+  parameters:
+    lb_name_0
+      type: string
+      description: VM Name for lb VM 0
+    vnf_name:
+      type: string
+      description: Unique name for this VNF instance
+    vnf_id:
+      type: string
+      description: Unique ID for this VNF instance
+    vf_module_name:
+      type: string
+      description: Unique name for this VNF Module instance
+    vf_module_id:
+      type: string
+      description: Unique ID for this VNF Module instance
+    vm_role:
+      type: string
+      description: Unique role for this VM
+  resources:
+    lb_server_0:
+      type: OS::Nova::Server
+      properties:
+        name: { get_param: lb_name_0 }
+        ...
+        metadata:
+          vnf_name: { get_param: vnf_name }
+          vnf_id: { get_param: vnf_id }
+          vf_module_name: { get_param: vf_module_name }
+          vf_module_id: { get_param: vf_module_id }
+          vm_role: lb
+
+vf_module_index
+^^^^^^^^^^^^^^^^^^
+
+
+.. req::
+    :id: R-50816
+    :target: VNF
+    :keyword: MAY
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource **MAY** contain the metadata map value parameter
+    'vf_module_index'.
+
+.. req::
+    :id: R-54340
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_index' **MUST** be
+    declared as type: 'number'.
+
+.. req::
+    :id: R-09811
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_index' **MUST NOT**
+    have parameter contraints defined.
+
+.. req::
+    :id: R-37039
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_index' **MUST NOT**
+    be enumerated in the Heat Orchestration Template's environment file.
+
+.. req::
+    :id: R-22441
+    :target: VNF
+    :keyword: MUST NOT
+
+    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.
+
+.. req::
+    :id: R-55306
+    :target: VNF
+    :keyword: MUST NOT
+
+    If a VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'vf_module_index' **MUST NOT** be
+    used in a VNF's Volume Template; it is not supported.
+
+The vf_module_index parameter indicates which instance of the module is being
+deployed into the VNF.
+This parameter may be used in cases where multiple instances of the same
+incremental module may be instantiated for scaling purposes. The index
+can be used in the Heat Orchestration Template for indexing into a
+pseudo-constant array parameter when unique values are required for each
+module instance, e.g., for fixed private IP addresses on VM types.
+
+The vf_module_index will start at 0 for the first instance of a module
+type. Subsequent instances of the same module type will receive the
+lowest unused index. This means that indexes will be reused if a module
+is deleted and re-added. As an example, if three copies of a module are
+deployed with vf_module_index values of 0, 1, and 2 then subsequently
+the second one is deleted (index 1), and then re-added, index 1 will be
+reused.
+
+*Example*
+
+In this example, the {vm-type} has been defined as oam_vm to represent
+an OAM VM. An incremental heat module is used to deploy the OAM VM. The
+OAM VM attaches to an internal control network which has a
+{network-role} of ctrl. A maximum of four OAM VMs can be deployed. The
+environment file contains the four IP addresses that each successive OAM
+VM will be assigned. The vf_module_index is used as the index to
+determine the IP assignment.
+
+Environment File
+
+.. code-block:: yaml
+
+  parameters:
+    oam_vm_int_ctrl_ips: 10.10.10.1,10.10.10.2,10.10.10.3,10.10.10.4
+
+YAML File
+
+.. code-block:: yaml
+
+ parameters:
+   vf_module_index:
+     type: number
+     description: Unique index for this VNF Module instance
+   oam_vm_name_0:
+     type: string
+     description: VM Name for lb VM 0
+   int_ctrl_net_id:
+     type: string
+     description: Neutron UUID for the internal control network
+   oam_vm_int_ctrl_ips:
+     type: comma_delimited_list
+     description: Fixed IP assignments for oam VMs on the internal control
+     network
+ resources:
+   oam_vm_server_0:
+     type: OS::Nova::Server
+     properties:
+       name: { get_param: oam_vm_name_0 }
+       networks:
+         port: { get_resource: oam_vm_0_int_ctrl_port_0 }
+
+       . . .
+
+       metadata:
+         vf_module_index: { get_param: vf_module_index }
+   oam_vm_0_int_ctrl_port_0:
+     type: OS::Neutron::Port
+     properties:
+       network: { get_param: int_ctrl_net_id }
+       fixed_ips: [ { "ip_address": {get_param: [ oam_vm_int_ctrl_ips, { get_param, vf_module_index}]}}]
+
+workload_context
+^^^^^^^^^^^^^^^^^^^^^
+
+.. req::
+    :id: R-47061
+    :target: VNF
+    :keyword: SHOULD
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource **SHOULD** contain the metadata map value parameter
+    'workload_context'.
+
+.. req::
+    :id: R-74978
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'workload_context' **MUST** be
+    declared as type: 'string'.
+
+.. req::
+    :id: R-34055
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'workload_context' **MUST NOT**
+    have parameter contraints defined.
+
+.. req::
+    :id: R-02691
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'workload_context' **MUST NOT**
+    be enumerated in the Heat Orchestration Template's environment file.
+
+.. req::
+    :id: R-75202
+    :target: VNF
+    :keyword: MUST NOT
+
+    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.
+
+The 'workload\_context' parameter value will be chosen by the Service Model
+Distribution context client in VID and will be supplied to the
+Heat Orchestration Template by ONAP at orchestration time.
+
+*Example Parameter Definition*
+
+.. code-block:: yaml
+
+  parameters:
+    workload_context:
+      type: string
+      description: Workload Context for this VNF instance
+
+
+*Example OS::Nova::Server with metadata*
+
+.. code-block:: yaml
+
+  resources:
+    . . .
+
+    {vm-type}_server_{index}:
+       type: OS::Nova::Server
+       properties:
+         name:
+         flavor:
+         image:
+        ...
+       metadata:
+          vnf_name: { get_param: vnf_name }
+          vnf_id: { get_param: vnf_id }
+          vf_module_name: { get_param: vf_module_name }
+          vf_module_id: { get_param: vf_module_id }
+          workload_context: {get_param: workload_context}
+
+environment_context
+^^^^^^^^^^^^^^^^^^^^^
+
+.. req::
+    :id: R-88536
+    :target: VNF
+    :keyword: SHOULD
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource **SHOULD** contain the metadata map value parameter
+    'environment_context'.
+
+.. req::
+    :id: R-20308
+    :target: VNF
+    :keyword: MUST
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'environment_context' **MUST**
+    be declared as type: 'string'.
+
+.. req::
+    :id: R-56183
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'environment_context' **MUST NOT**
+    have parameter contraints defined.
+
+.. req::
+    :id: R-13194
+    :target: VNF
+    :keyword: MUST NOT
+
+    A VNF's Heat Orchestration Template's OS::Nova::Server
+    Resource metadata map value parameter 'environment_context' **MUST NOT**
+    be enumerated in the Heat Orchestration Template's environment file.
+
+.. req::
+    :id: R-62954
+    :target: VNF
+    :keyword: MUST NOT
+
+    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.
+
+The 'environment_context' parameter value will be defined by the
+service designer as part of the service model during the SDC
+on-boarding process and will be supplied to the Heat Orchestration
+Template by ONAP at orchestration time.
+
+
+*Example Parameter Definition*
+
+.. code-block:: yaml
+
+  parameters:
+    environment_context:
+      type: string
+      description: Environment Context for this VNF instance
+
+
+*Example OS::Nova::Server with metadata*
+
+.. code-block:: yaml
+
+  resources:
+    . . .
+
+    {vm-type}_server_{index}:
+       type: OS::Nova::Server
+       properties:
+         name:
+         flavor:
+         image:
+        ...
+       metadata:
+          vnf_name: { get_param: vnf_name }
+          vnf_id: { get_param: vnf_id }
+          vf_module_name: { get_param: vf_module_name }
+          vf_module_id: { get_param: vf_module_id }
+          workload_context: {get_param: workload_context}
+          environment_context: {get_param: environment_context }