1 .. Licensed under a Creative Commons Attribution 4.0 International License.
 
   2 .. http://creativecommons.org/licenses/by/4.0
 
   3 .. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
 
   5 .. _Nova Server - Metadata Parameters:
 
   7 Resource: OS::Nova::Server - Metadata Parameters
 
   8 --------------------------------------------------------------------------------
 
  10 The OS::Nova::Server Resource property metadata is an optional
 
  12 The table below summarizes the mandatory and optional metadata
 
  15 The sections that follow provides the requirements associated with each
 
  18 .. csv-table:: **Table 5 OS::Nova::Server Mandatory and Optional Metadata**
 
  19    :header: Metadata Parameter Name, Parameter Type, Required, Parameter Value Provided to Heat
 
  23    vnf_id, string, **MUST**, ONAP
 
  24    vf_module_id, string, **MUST**, ONAP
 
  25    vnf_name, string, **MUST**, ONAP
 
  26    vf_module_name, string, **SHOULD**, ONAP
 
  27    vm_role, string, **MAY**, YAML or Environment File
 
  28    vf_module_index, string, **MAY**, ONAP
 
  29    workload_context, string, **SHOULD**, ONAP
 
  30    environment_context, string, **SHOULD**, ONAP
 
  35 The OS::Nova::Server Resource metadata map value parameter 'vnf_id'
 
  36 is an ONAP generated UUID that identifies the VNF.  The value
 
  37 is provided by ONAP to the VNF's Heat Orchestration
 
  38 Template at orchestration time.
 
  46     A VNF's Heat Orchestration Template's OS::Nova::Server
 
  47     Resource **MUST** contain the metadata map value parameter 'vnf_id'.
 
  54     A VNF's Heat Orchestration Template's OS::Nova::Server
 
  55     Resource metadata map value parameter 'vnf_id' **MUST** be declared
 
  63     A VNF's Heat Orchestration Template's OS::Nova::Server
 
  64     Resource metadata map value parameter 'vnf_id' **MUST NOT** have
 
  65     parameter contraints defined.
 
  72     A VNF's Heat Orchestration Template's OS::Nova::Server
 
  73     Resource metadata map value parameter 'vnf_id' **MUST NOT** be
 
  74     enumerated in the Heat Orchestration Template's environment file.
 
  81     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
  82     Resource metadata map value parameter 'vnf_id' is passed into a
 
  83     Nested YAML file, the parameter name 'vnf_id' **MUST NOT** change.
 
  85 *Example 'vnf_id' Parameter Definition*
 
  93       description: Unique ID for this VNF instance
 
  98 The OS::Nova::Server Resource metadata map value parameter 'vf_module_id'
 
  99 is an ONAP generated UUID that identifies the VF Module (e.g., Heat
 
 100 Orchestration Template).  The value
 
 101 is provided by ONAP to the VNF's Heat Orchestration
 
 102 Template at orchestration time.
 
 110     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 111     Resource **MUST** contain the metadata map value parameter
 
 119     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 120     Resource metadata map value parameter 'vf_module_id' **MUST**
 
 121     be declared as type: 'string'.
 
 128     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 129     Resource metadata map value parameter 'vf_module_id' **MUST NOT**
 
 130     have parameter contraints defined.
 
 137     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 138     Resource metadata map value parameter 'vf_module_id' **MUST NOT**
 
 139     be enumerated in the Heat Orchestration Template's environment file.
 
 146     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
 147     Resource metadata map value parameter 'vf_module_id' is passed
 
 148     into a Nested YAML file, the parameter name 'vf_module_id'
 
 151 *Example 'vf_module_id' Parameter Definition*
 
 159       description: Unique ID for this VNF module instance
 
 165 The OS::Nova::Server Resource metadata map value parameter 'vnf_name'
 
 166 is the ONAP generated alphanumeric name of the deployed VNF instance.
 
 168 is provided by ONAP to the VNF's Heat Orchestration
 
 169 Template at orchestration time.
 
 170 The parameter must be declared as type: string
 
 178     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 179     Resource **MUST** contain the metadata map value parameter
 
 187     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 188     Resource metadata map value parameter 'vnf_name' **MUST** be
 
 189     declared as type: 'string'.
 
 196     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 197     Resource metadata map value parameter 'vnf_name' **MUST NOT** have
 
 198     parameter contraints defined.
 
 205     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 206     Resource metadata map value parameter 'vnf_name' **MUST NOT** be
 
 207     enumerated in the Heat Orchestration Template's environment file.
 
 214     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
 215     Resource metadata map value parameter 'vnf_name' is passed into a
 
 216     Nested YAML file, the parameter name 'vnf_name' **MUST NOT** change.
 
 218 *Example 'vnf_name' Parameter Definition*
 
 226       description: Unique name for this VNF instance
 
 231 The OS::Nova::Server Resource metadata map value parameter 'vf_module_name'
 
 232 is the deployment name of the heat stack created (e.g., <STACK_NAME>) from the
 
 233 VNF's Heat Orchestration template
 
 234 in the command 'Heat stack-create'
 
 235 (e.g., 'Heat stack-create [-f <FILE>] [-e <FILE>] <STACK_NAME>').
 
 236 The 'vf_module_name' (e.g., <STACK_NAME> is specified as
 
 237 part of the orchestration process.
 
 245     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 246     Resource **SHOULD** contain the metadata map value parameter
 
 254     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 255     Resource metadata map value parameter 'vf_module_name' **MUST**
 
 256     be declared as type: 'string'.
 
 263     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 264     Resource metadata map value parameter 'vf_module_name'
 
 265     **MUST NOT** have parameter contraints defined.
 
 272     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 273     Resource metadata map value parameter 'vf_module_name'
 
 274     **MUST NOT** be enumerated in the Heat Orchestration Template's
 
 282     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
 283     Resource metadata map value parameter 'vf_module_name' is passed
 
 284     into a Nested YAML file, the parameter name 'vf_module_name'
 
 287 *Example 'vf_module_name' Parameter Definition*
 
 295       description: Unique name for this VNF Module instance
 
 300 The OS::Nova::Server Resource metadata map value parameter 'vm-role'
 
 301 is a metadata tag that describes the role of the Virtual Machine.
 
 302 The 'vm_role' is stored in ONAP's A&AI module and is
 
 303 available for use by other ONAP components and/or north bound systems.
 
 311     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 312     Resource **MAY** contain the metadata map value parameter 'vm_role'.
 
 319     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 320     Resource metadata map value parameter 'vm_role' **MUST** be
 
 321     declared as type: 'string'.
 
 328     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 329     Resource metadata map value parameter 'vm_role' **MUST NOT** have
 
 330     parameter contraints defined.
 
 338     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 339     Resource metadata map value parameter 'vnf_name' **MUST** be
 
 342      - enumerated in the VNF's Heat Orchestration
 
 343        Template's environment file.
 
 345      - hard coded in the VNF's Heat Orchestration
 
 346        Template's OS::Nova::Resource metadata property.
 
 348 Defining the 'vm_role' as the '{vm-type}' is a recommended convention
 
 356     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
 357     Resource metadata map value parameter 'vm_role' value **MUST** only
 
 358     contain alphanumeric characters and underscores '_'.
 
 365     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
 366     Resource metadata map value parameter 'vm_role' is passed into a
 
 367     Nested YAML file, the parameter name 'vm_role' **MUST NOT** change.
 
 369 *Example 'vm_role' Parameter Definition*
 
 377       description: Unique role for this VM
 
 379 *Example: 'vm-role' Definition: Hard Coded in
 
 380 OS::Nova::Resource metadata property*
 
 387       type: OS::Nova::Server
 
 393 *Example 'vm-role' Definition: Defined in Environment file
 
 394 and retrieved via 'get_param'*
 
 401       type: OS::Nova::Server
 
 405           vm_role: { get_param: vm_role }
 
 407 Example vnf_id, vf_module_id, vnf_name, vf_module_name, vm_role
 
 408 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 410 The example below depicts part of a Heat Orchestration Template
 
 411 that uses the five of the OS::Nova::Server metadata parameter
 
 412 discussed in this section. The {vm-type} has been defined as lb
 
 420       description: VM Name for lb VM 0
 
 423       description: Unique name for this VNF instance
 
 426       description: Unique ID for this VNF instance
 
 429       description: Unique name for this VNF Module instance
 
 432       description: Unique ID for this VNF Module instance
 
 435       description: Unique role for this VM
 
 438       type: OS::Nova::Server
 
 440         name: { get_param: lb_name_0 }
 
 443           vnf_name: { get_param: vnf_name }
 
 444           vnf_id: { get_param: vnf_id }
 
 445           vf_module_name: { get_param: vf_module_name }
 
 446           vf_module_id: { get_param: vf_module_id }
 
 458     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 459     Resource **MAY** contain the metadata map value parameter
 
 467     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 468     Resource metadata map value parameter 'vf_module_index' **MUST** be
 
 469     declared as type: 'number'.
 
 476     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 477     Resource metadata map value parameter 'vf_module_index' **MUST NOT**
 
 478     have parameter contraints defined.
 
 485     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 486     Resource metadata map value parameter 'vf_module_index' **MUST NOT**
 
 487     be enumerated in the Heat Orchestration Template's environment file.
 
 494     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
 495     Resource metadata map value parameter 'vf\_module\_index' is passed
 
 496     into a Nested YAML file, the parameter name 'vf\_module\_index'
 
 504     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
 505     Resource metadata map value parameter 'vf_module_index' **MUST NOT** be
 
 506     used in a VNF's Volume Template; it is not supported.
 
 508 The vf_module_index parameter indicates which instance of the module is being
 
 509 deployed into the VNF.
 
 510 This parameter may be used in cases where multiple instances of the same
 
 511 incremental module may be instantiated for scaling purposes. The index
 
 512 can be used in the Heat Orchestration Template for indexing into a
 
 513 pseudo-constant array parameter when unique values are required for each
 
 514 module instance, e.g., for fixed private IP addresses on VM types.
 
 516 The vf_module_index will start at 0 for the first instance of a module
 
 517 type. Subsequent instances of the same module type will receive the
 
 518 lowest unused index. This means that indexes will be reused if a module
 
 519 is deleted and re-added. As an example, if three copies of a module are
 
 520 deployed with vf_module_index values of 0, 1, and 2 then subsequently
 
 521 the second one is deleted (index 1), and then re-added, index 1 will be
 
 526 In this example, the {vm-type} has been defined as oam_vm to represent
 
 527 an OAM VM. An incremental heat module is used to deploy the OAM VM. The
 
 528 OAM VM attaches to an internal control network which has a
 
 529 {network-role} of ctrl. A maximum of four OAM VMs can be deployed. The
 
 530 environment file contains the four IP addresses that each successive OAM
 
 531 VM will be assigned. The vf_module_index is used as the index to
 
 532 determine the IP assignment.
 
 539     oam_vm_int_ctrl_ips: 10.10.10.1,10.10.10.2,10.10.10.3,10.10.10.4
 
 548      description: Unique index for this VNF Module instance
 
 551      description: VM Name for lb VM 0
 
 554      description: Neutron UUID for the internal control network
 
 556      type: comma_delimited_list
 
 557      description: Fixed IP assignments for oam VMs on the internal control
 
 561      type: OS::Nova::Server
 
 563        name: { get_param: oam_vm_name_0 }
 
 565          port: { get_resource: oam_vm_0_int_ctrl_port_0 }
 
 570          vf_module_index: { get_param: vf_module_index }
 
 571    oam_vm_0_int_ctrl_port_0:
 
 572      type: OS::Neutron::Port
 
 574        network: { get_param: int_ctrl_net_id }
 
 575        fixed_ips: [ { "ip_address": {get_param: [ oam_vm_int_ctrl_ips, { get_param, vf_module_index}]}}]
 
 578 ^^^^^^^^^^^^^^^^^^^^^
 
 585     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 586     Resource **SHOULD** contain the metadata map value parameter
 
 594     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 595     Resource metadata map value parameter 'workload_context' **MUST** be
 
 596     declared as type: 'string'.
 
 603     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 604     Resource metadata map value parameter 'workload_context' **MUST NOT**
 
 605     have parameter contraints defined.
 
 612     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 613     Resource metadata map value parameter 'workload_context' **MUST NOT**
 
 614     be enumerated in the Heat Orchestration Template's environment file.
 
 621     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
 622     Resource metadata map value parameter 'workload_context' is passed
 
 623     into a Nested YAML file, the parameter name 'workload_context'
 
 626 The 'workload\_context' parameter value will be chosen by the Service Model
 
 627 Distribution context client in VID and will be supplied to the
 
 628 Heat Orchestration Template by ONAP at orchestration time.
 
 630 *Example Parameter Definition*
 
 637       description: Workload Context for this VNF instance
 
 640 *Example OS::Nova::Server with metadata*
 
 647     {vm-type}_server_{index}:
 
 648        type: OS::Nova::Server
 
 655           vnf_name: { get_param: vnf_name }
 
 656           vnf_id: { get_param: vnf_id }
 
 657           vf_module_name: { get_param: vf_module_name }
 
 658           vf_module_id: { get_param: vf_module_id }
 
 659           workload_context: {get_param: workload_context}
 
 662 ^^^^^^^^^^^^^^^^^^^^^
 
 669     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 670     Resource **SHOULD** contain the metadata map value parameter
 
 671     'environment_context'.
 
 678     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 679     Resource metadata map value parameter 'environment_context' **MUST**
 
 680     be declared as type: 'string'.
 
 687     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 688     Resource metadata map value parameter 'environment_context' **MUST NOT**
 
 689     have parameter contraints defined.
 
 696     A VNF's Heat Orchestration Template's OS::Nova::Server
 
 697     Resource metadata map value parameter 'environment_context' **MUST NOT**
 
 698     be enumerated in the Heat Orchestration Template's environment file.
 
 705     If a VNF's Heat Orchestration Template's OS::Nova::Server
 
 706     Resource metadata map value parameter 'environment_context' is
 
 707     passed into a Nested YAML file, the parameter name
 
 708     'environment_context' **MUST NOT** change.
 
 710 The 'environment_context' parameter value will be defined by the
 
 711 service designer as part of the service model during the SDC
 
 712 on-boarding process and will be supplied to the Heat Orchestration
 
 713 Template by ONAP at orchestration time.
 
 716 *Example Parameter Definition*
 
 723       description: Environment Context for this VNF instance
 
 726 *Example OS::Nova::Server with metadata*
 
 733     {vm-type}_server_{index}:
 
 734        type: OS::Nova::Server
 
 741           vnf_name: { get_param: vnf_name }
 
 742           vnf_id: { get_param: vnf_id }
 
 743           vf_module_name: { get_param: vf_module_name }
 
 744           vf_module_id: { get_param: vf_module_id }
 
 745           workload_context: {get_param: workload_context}
 
 746           environment_context: {get_param: environment_context }