diff options
Diffstat (limited to 'docs/Chapter5/Heat/ONAP Heat Resource ID and Parameter Naming Convention/Nova Metadata Parameters.rst')
| -rw-r--r-- | docs/Chapter5/Heat/ONAP Heat Resource ID and Parameter Naming Convention/Nova Metadata Parameters.rst | 746 |
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 } |