.. 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 }