diff options
| author |   stark, steven <ss820f@att.com> | 2018-06-26 13:34:59 -0700 |
|---|---|---|
| committer | stark, steven <ss820f@att.com> | 2018-06-27 12:18:17 -0700 |
| commit | 2cbffc5b71c88fd858b654335731ea72fd80220c (patch) | |
| tree | 695110bcb0d91fa22f607363b9803643dc67d233 /docs/Chapter5.rst | |
| parent | 8274f893dd8e46a320a3a2b7a5c44430a8d4e765 (diff) | |
[VNFRQTS] break up larger rst files into toxtree
Broke all chapter files up so they follow the same patter
Change-Id: I8a2152b92f0568cf4858615054bb66fabf0ea343
Issue-ID: VNFRQTS-253
Signed-off-by: stark, steven <ss820f@att.com>
Diffstat (limited to 'docs/Chapter5.rst')
| -rw-r--r-- | docs/Chapter5.rst | 5437 |
1 files changed, 0 insertions, 5437 deletions
diff --git a/docs/Chapter5.rst b/docs/Chapter5.rst deleted file mode 100644 index 830dd5e..0000000 --- a/docs/Chapter5.rst +++ /dev/null @@ -1,5437 +0,0 @@ -.. This work is 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. - - -VNF Modeling Requirements -========================= - -TOSCA YAML ----------- - - -Introduction -^^^^^^^^^^^^^^ - -This reference document is the VNF TOSCA Template Requirements for -ONAP, which provides recommendations and standards for building VNF -TOSCA templates compatible with ONAP initial implementations of -Network Cloud. It has the following features: - -1. VNF TOSCA template designer supports GUI and CLI. - -2. VNF TOSCA template is aligned to the newest TOSCA protocol, “Working - Draft 04-Revision 06”. - -3. VNF TOSCA template supports HPA features, such as NUMA, Hyper - Threading, SRIOV， etc. - -Intended Audience -^^^^^^^^^^^^^^^^^^ - -This document is intended for persons developing VNF TOSCA templates -that will be orchestrated by ONAP. - -Scope -^^^^^^^^^^^^^^^^ - -ONAP implementations of Network Cloud supports TOSCA Templates, also -referred to as TOSCA in this document. - -ONAP requires the TOSCA Templates to follow a specific format. This -document provides the mandatory, recommended, and optional requirements -associated with this format. - -Overview -^^^^^^^^^^^^^^^^ - -The document includes three charters to help the VNF providers to use the -VNF model design tools and understand the VNF package structure and VNF -TOSCA templates. - -In the ONAP, VNF Package and VNFD template can be designed by manually -or via model designer tools. VNF model designer tools can provide the -GUI and CLI tools for the VNF provider to develop the VNF Package and VNFD -template. - -The VNF package structure is align to the NFV TOSCA protocol, and -supports CSAR - -The VNFD and VNF package are all align to the NFV TOSCA protocol, which -supports multiple TOSCA template yaml files, and also supports -self-defined node or other extensions. - -NFV TOSCA Template -^^^^^^^^^^^^^^^^^^^^ - -TOSCA templates supported by ONAP must follow the requirements -enumerated in this section. - -TOSCA Introduction -^^^^^^^^^^^^^^^^^^^ - -TOSCA defines a Meta model for defining IT services. This Meta model -defines both the structure of a service as well as how to manage it. A -Topology Template (also referred to as the topology model of a service) -defines the structure of a service. Plans define the process models that -are used to create and terminate a service as well as to manage a -service during its whole lifetime. - -A Topology Template consists of a set of Node Templates and Relationship -Templates that together define the topology model of a service as a (not -necessarily connected) directed graph. A node in this graph is -represented by a *Node Template*. A Node Template specifies the -occurrence of a Node Type as a component of a service. A *Node Type* -defines the properties of such a component (via *Node Type Properties*) -and the operations (via *Interfaces*) available to manipulate the -component. Node Types are defined separately for reuse purposes and a -Node Template references a Node Type and adds usage constraints, such as -how many times the component can occur. - -|image1| - -Figure 1: Structural Elements of Service Template and their Relations - -TOSCA Modeling Principles & Data Model -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This section describing TOSCA modeling principles and data model for -NFV, which shall be based on [TOSCA-1.0] and [TOSCA-Simple-Profile-YAML -V1.0], or new type based on ETSI NFV requirements, etc. - -VNF Descriptor Template -^^^^^^^^^^^^^^^^^^^^^^^^^ - -The VNF Descriptor (VNFD) describes the topology of the VNF by means of -ETSI NFV IFA011 [IFA011] terms such as VDUs, Connection Points, Virtual -Links, External Connection Points, Scaling Aspects, Instantiation Levels -and Deployment Flavours. - -The VNFD (VNF Descriptor) is read by both the NFVO and the VNFM. It -represents the contract & interface of a VNF and ensures the -interoperability across the NFV functional blocks. - -The main parts of the VNFD are the following: - -- VNF topology: it is modeled in a cloud agnostic way using virtualized - containers and their connectivity. Virtual Deployment Units (VDU) - describe the capabilities of the virtualized containers, such as - virtual CPU, RAM, disks; their connectivity is modeled with VDU - Connection Point Descriptors (VduCpd), Virtual Link Descriptors (Vld) - and VNF External Connection Point Descriptors (VnfExternalCpd); - -- VNF deployment aspects: they are described in one or more deployment - flavours, including instantiation levels, supported LCM operations, - VNF LCM operation configuration parameters, placement constraints - (affinity / antiaffinity), minimum and maximum VDU instance numbers, - and scaling aspect for horizontal scaling. - -The following table defines the TOSCA Type “derived from” values that -SHALL be used when using the TOSCA Simple Profile for NFV version 1.0 -specification [TOSCA-Simple-Profile-NFV-v1.0] for NFV VNFD with aggreed -changes from ETSI SOL001 draft. - -+---------------------+------------------------------------+-----------------+ -| **ETSI NFV Element**| **TOSCA VNFD** | **Derived from**| -| | | | -| **[IFA011]** | **[TOSCA-Simple-Profile-NFV-v1.0]**| | -+=====================+====================================+=================+ -| VNF | tosca.nodes.nfv.VNF | tosca.nodes.Root| -+---------------------+------------------------------------+-----------------+ -| Cpd (Connection | tosca.nodes.nfv.Cp | tosca.nodes.Root| -| Point) | tosca.nodes.nfv.Cp | tosca.nodes.Root| -+---------------------+------------------------------------+-----------------+ -| VduCpd (internal | tosca.nodes.nfv.VduCp | tosca.nodes.\ | -| connection point) | | nfv.Cp | -+---------------------+------------------------------------+-----------------+ -| VnfVirtualLinkDesc | tosca.nodes.nfv.VnfVirtualLink | tosca.nodes.Root| -| (Virtual Link) | | | -+---------------------+------------------------------------+-----------------+ -| VDU Virtual Storage | tosca.nodes.nfv.VDU.VirtualStorage | tosca.nodes.Root| -+---------------------+------------------------------------+-----------------+ -| VDU Virtual Compute | tosca.nodes.nfv.VDU.Compute | tosca.nodes.Root| -+---------------------+------------------------------------+-----------------+ -| Software Image | | | -+---------------------+------------------------------------+-----------------+ -| Deployment Flavour | | | -+---------------------+------------------------------------+-----------------+ -| Scaling Aspect | | | -+---------------------+------------------------------------+-----------------+ -| Element Group | | | -+---------------------+------------------------------------+-----------------+ -| Instantiation | | | -| Level | | | -+---------------------+------------------------------------+-----------------+ - - -+--------------------------------------------------------------------+ -| +--------------------------------------------------------------+ | -| | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 | | -| | | | -| | description: VNFD TOSCA file demo | | -| | | | -| | imports: | | -| | | | -| | - TOSCA\_definition\_nfv\_1\_0.yaml | | -| | | | -| | - TOSCA\_definition\_nfv\_ext\_1\_0.yaml | | -| | | | -| | | **node\_types: | | -| | tosca.nodes.nfv.VNF.vOpenNAT: | | -| | derived\_from:** tosca.nodes.nfv.VNF | | -| | | **requirements: | | -| | **- **sriov\_plane: | | -| | capability:** tosca.capabilities.nfv.VirtualLinkable | | -| | | **node:** tosca.nodes.nfv.VnfVirtualLinkDesc | | -| | | **relationship:** tosca.relationships.nfv.VirtualLinksTo | | -| +--------------------------------------------------------------+ | -+====================================================================+ -+--------------------------------------------------------------------+ - -HPA Requirements -^^^^^^^^^^^^^^^^^^ - -1. SR-IOV Passthrought - -Definitions of SRIOV\_Port are necessary if VDU supports SR-IOV. Here is -an example. - -+------------------------------------------------+ -| node\_templates: | -| | -| vdu\_vNat: | -| | -| SRIOV\_Port: | -| | -| attributes: | -| | -| tosca\_name: SRIOV\_Port | -| | -| properties: | -| | -| virtual\_network\_interface\_requirements: | -| | -| - name: sriov | -| | -| support\_mandatory: false | -| | -| description: sriov | -| | -| requirement: | -| | -| SRIOV: true | -| | -| role: root | -| | -| description: sriov port | -| | -| layer\_protocol: ipv4 | -| | -| requirements: | -| | -| - virtual\_binding: | -| | -| capability: virtual\_binding | -| | -| node: vdu\_vNat | -| | -| relationship: | -| | -| type: tosca.relationships.nfv.VirtualBindsTo | -| | -| - virtual\_link: | -| | -| node: tosca.nodes.Root | -| | -| type: tosca.nodes.nfv.VduCpd | -| | -| substitution\_mappings: | -| | -| requirements: | -| | -| sriov\_plane: | -| | -| - SRIOV\_Port | -| | -| - virtual\_link | -| | -| node\_type: tosca.nodes.nfv.VNF.vOpenNAT | -+------------------------------------------------+ - -2. Hugepages - -Definitions of mem\_page\_size as one property shall be added to -Properties and set the value to large if one VDU node supports -huagepages. Here is an example. - -+----------------------------------+ -| node\_templates: | -| | -| vdu\_vNat: | -| | -| Hugepages: | -| | -| attributes: | -| | -| tosca\_name: Huge\_pages\_demo | -| | -| properties: | -| | -| mem\_page\_size:large | -+==================================+ -+----------------------------------+ - -3. NUMA (CPU/Mem) - -Likewise, we shall add definitions of numa to -requested\_additional\_capabilities if we wand VUD nodes to support -NUMA. Here is an example. - -+-------------------------------------------------+ -| topology\_template: | -| | -| node\_templates: | -| | -| vdu\_vNat: | -| | -| capabilities: | -| | -| virtual\_compute: | -| | -| properties: | -| | -| virtual\_memory: | -| | -| numa\_enabled: true | -| | -| virtual\_mem\_size: 2 GB | -| | -| requested\_additional\_capabilities: | -| | -| numa: | -| | -| support\_mandatory: true | -| | -| requested\_additional\_capability\_name: numa | -| | -| target\_performance\_parameters: | -| | -| hw:numa\_nodes: "2" | -| | -| hw:numa\_cpus.0: "0,1" | -| | -| hw:numa\_mem.0: "1024" | -| | -| hw:numa\_cpus.1: "2,3,4,5" | -| | -| hw:numa\_mem.1: "1024" | -+-------------------------------------------------+ - -4. Hyper-Theading - -Definitions of Hyper-Theading are necessary as one of -requested\_additional\_capabilities of one VUD node if that node -supports Hyper-Theading. Here is an example. - -+-------------------------------------------------------------+ -| topology\_template: | -| | -| node\_templates: | -| | -| vdu\_vNat: | -| | -| capabilities: | -| | -| virtual\_compute: | -| | -| properties: | -| | -| virtual\_memory: | -| | -| numa\_enabled: true | -| | -| virtual\_mem\_size: 2 GB | -| | -| requested\_additional\_capabilities: | -| | -| hyper\_threading: | -| | -| support\_mandatory: true | -| | -| requested\_additional\_capability\_name: hyper\_threading | -| | -| target\_performance\_parameters: | -| | -| hw:cpu\_sockets : "2" | -| | -| hw:cpu\_threads : "2" | -| | -| hw:cpu\_cores : "2" | -| | -| hw:cpu\_threads\_policy: "isolate" | -+-------------------------------------------------------------+ - -5. OVS+DPDK - -Definitions of ovs\_dpdk are necessary as one of -requested\_additional\_capabilities of one VUD node if that node -supports dpdk. Here is an example. - -+------------------------------------------------------+ -| topology\_template: | -| | -| node\_templates: | -| | -| vdu\_vNat: | -| | -| capabilities: | -| | -| virtual\_compute: | -| | -| properties: | -| | -| virtual\_memory: | -| | -| numa\_enabled: true | -| | -| virtual\_mem\_size: 2 GB | -| | -| requested\_additional\_capabilities: | -| | -| ovs\_dpdk: | -| | -| support\_mandatory: true | -| | -| requested\_additional\_capability\_name: ovs\_dpdk | -| | -| target\_performance\_parameters: | -| | -| sw:ovs\_dpdk: "true" | -+------------------------------------------------------+ - -NFV TOSCA Type Definition -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -tosca.capabilites.nfv.VirtualCompute -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -This capability is used with the properties specified in ETSI SOL001 draft. - -tosca.nodes.nfv.VDU.Compute -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The NFV Virtualization Deployment Unit (VDU) compute node type -represents a VDU entity which it describes the deployment and -operational behavior of a VNF component (VNFC), as defined by **[ETSI -NFV IFA011].** - -+-----------------------+-------------------------------+ -| Shorthand Name | VDU.Compute | -+=======================+===============================+ -| Type Qualified Name | tosca:VDU.Compute | -+-----------------------+-------------------------------+ -| Type URI | tosca.nodes.nfv.VDU.Compute | -+-----------------------+-------------------------------+ -| derived\_from | tosca.nodes.Compute | -+-----------------------+-------------------------------+ - - - -Attributes -++++++++++++ - -None - - -Capabilities -++++++++++++++ - -+------------+--------------------+------------+------------------------------+ -| Name | Type | Constraints| Description | -+============+====================+============+==============================+ -| virtual\ | tosca.\ | | Describes virtual compute | -| _compute | capabilities.nfv.\ | | resources capabilities. | -| | VirtualCompute | | | -+------------+--------------------+------------+------------------------------+ -| monitoring\| tosca.\ | None | Monitoring parameter, which | -| _parameter | capabilities.nfv.\ | | can be tracked for a VNFC | -| | Metric | | based on this VDU | -| | | | | -| | | | Examples include: | -| | | | memory-consumption, | -| | | | CPU-utilisation, | -| | | | bandwidth-consumption, VNFC | -| | | | downtime, etc. | -+------------+--------------------+------------+------------------------------+ -| Virtual\ | tosca.\ | | Defines ability of | -| _binding | capabilities.nfv.\ | | VirtualBindable | -| | VirtualBindable | | | -| | | | | -| | editor note: need | | | -| | to create a | | | -| | capability type | | | -+------------+--------------------+------------+------------------------------+ - -Definition -++++++++++++ - -+-----------------------------------------------------------------------------+ -| tosca.nodes.nfv.VDU.Compute: | -| | -| derived\_from: tosca.nodes.Compute | -| | -| properties: | -| | -| name: | -| | -| type: string | -| | -| required: true | -| | -| description: | -| | -| type: string | -| | -| required: true | -| | -| boot\_order: | -| | -| type: list # explicit index (boot index) not necessary, contrary to IFA011 | -| | -| entry\_schema: | -| | -| type: string | -| | -| required: false | -| | -| nfvi\_constraints: | -| | -| type: list | -| | -| entry\_schema: | -| | -| type: string | -| | -| required: false | -| | -| configurable\_properties: | -| | -| type: map | -| | -| entry\_schema: | -| | -| type: tosca.datatypes.nfv.VnfcConfigurableProperties | -| | -| required: true | -| | -| attributes: | -| | -| private\_address: | -| | -| status: deprecated | -| | -| public\_address: | -| | -| status: deprecated | -| | -| networks: | -| | -| status: deprecated | -| | -| ports: | -| | -| status: deprecated | -| | -| capabilities: | -| | -| virtual\_compute: | -| | -| type: tosca.capabilities.nfv.VirtualCompute | -| | -| virtual\_binding: | -| | -| type: tosca.capabilities.nfv.VirtualBindable | -| | -| #monitoring\_parameter: | -| | -| # modeled as ad hoc (named) capabilities in VDU node template | -| | -| # for example: | -| | -| #capabilities: | -| | -| # cpu\_load: tosca.capabilities.nfv.Metric | -| | -| # memory\_usage: tosca.capabilities.nfv.Metric | -| | -| host: #Editor note: FFS. How this capabilities should be used in NFV Profile| -| | -| type: `*tosca.capabilities.Container* <#DEFN_TYPE_CAPABILITIES_CONTAINER>`__| -| | -| valid\_source\_types: | -| [`*tosca.nodes.SoftwareComponent* <#DEFN_TYPE_NODES_SOFTWARE_COMPONENT>`__] | -| | -| occurrences: [0,UNBOUNDED] | -| | -| endpoint: | -| | -| occurrences: [0,0] | -| | -| os: | -| | -| occurrences: [0,0] | -| | -| scalable: | -| #Editor note: FFS. How this capabilities should be used in NFV Profile | -| | -| type: `*tosca.capabilities.Scalable* <#DEFN_TYPE_CAPABILITIES_SCALABLE>`__ | -| | -| binding: | -| | -| occurrences: [0,UNBOUND] | -| | -| requirements: | -| | -| - virtual\_storage: | -| | -| capability: tosca.capabilities.nfv.VirtualStorage | -| | -| relationship: tosca.relationships.nfv.VDU.AttachedTo | -| | -| node: tosca.nodes.nfv.VDU.VirtualStorage | -| | -| occurences: [ 0, UNBOUNDED ] | -| | -| - local\_storage: #For NFV Profile, this requirement is deprecated. | -| | -| occurrences: [0,0] | -| | -| artifacts: | -| | -| - sw\_image: | -| | -| file: | -| | -| type: tosca.artifacts.nfv.SwImage | -+-----------------------------------------------------------------------------+ - -Artifact -++++++++++ - -Note: currently not supported. - -+--------+---------+----------------+------------+------------------------+ -| Name | Required| Type | Constraints| Description | -+========+=========+================+============+========================+ -| SwImage| Yes | tosca.\ | | Describes the software | -| | | artifacts.nfv.\| | image which is directly| -| | | SwImage | | realizing this virtual | -| | | | | storage | -+--------+---------+----------------+------------+------------------------+ - - -|image2| - - - -tosca.nodes.nfv.VDU.VirtualStorage -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The NFV VirtualStorage node type represents a virtual storage entity -which it describes the deployment and operational behavior of a virtual -storage resources, as defined by **[ETSI NFV IFA011].** - -**[editor note]** open issue: should NFV profile use the current storage -model as described in YAML 1.1. Pending on Shitao proposal (see -NFVIFA(17)000110 discussion paper) - -**[editor note]** new relationship type as suggested in Matt -presentation. Slide 8. With specific rules of “valid\_target\_type” - -+---------------------------+--------------------------------------+ -| **Shorthand Name** | VirtualStorage | -+===========================+======================================+ -| **Type Qualified Name** | tosca: VirtualStorage | -+---------------------------+--------------------------------------+ -| **Type URI** | tosca.nodes.nfv.VDU.VirtualStorage | -+---------------------------+--------------------------------------+ -| **derived\_from** | tosca.nodes.Root | -+---------------------------+--------------------------------------+ - -tosca.artifacts.nfv.SwImage -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -+---------------------------+------------------------------------+ -| **Shorthand Name** | SwImage | -+===========================+====================================+ -| **Type Qualified Name** | tosca:SwImage | -+---------------------------+------------------------------------+ -| **Type URI** | tosca.artifacts.nfv.SwImage | -+---------------------------+------------------------------------+ -| **derived\_from** | tosca.artifacts.Deployment.Image | -+---------------------------+------------------------------------+ - -Properties -++++++++++++ - -+-----------------+---------+----------+------------+-------------------------+ -| Name | Required| Type | Constraints| Description | -+=================+=========+==========+============+=========================+ -| name | yes | string | | Name of this software | -| | | | | image | -+-----------------+---------+----------+------------+-------------------------+ -| version | yes | string | | Version of this software| -| | | | | image | -+-----------------+---------+----------+------------+-------------------------+ -| checksum | yes | string | | Checksum of the software| -| | | | | image file | -+-----------------+---------+----------+------------+-------------------------+ -| container\ | yes | string | | The container format | -| _format | | | | describes the container | -| | | | | file format in which | -| | | | | software image is | -| | | | | provided. | -+-----------------+---------+----------+------------+-------------------------+ -| disk\_format | yes | string | | The disk format of a | -| | | | | software image is the | -| | | | | format of the underlying| -| | | | | disk image | -+-----------------+---------+----------+------------+-------------------------+ -| min\_disk | yes | scalar-\ | | The minimal disk size | -| | | unit.size| | requirement for this | -| | | | | software image. | -+-----------------+---------+----------+------------+-------------------------+ -| min\_ram | no | scalar-\ | | The minimal RAM | -| | | unit.size| | requirement for this | -| | | | | software image. | -+-----------------+---------+----------+------------+-------------------------+ -| Size | yes | scalar-\ | | The size of this | -| | | unit.size| | software image | -+-----------------+---------+----------+------------+-------------------------+ -| sw\_image | yes | string | | A reference to the | -| | | | | actual software image | -| | | | | within VNF Package, or | -| | | | | url. | -+-----------------+---------+----------+------------+-------------------------+ -| operating\ | no | string | | Identifies the operating| -| _system | | | | system used in the | -| | | | | software image. | -+-----------------+---------+----------+------------+-------------------------+ -| supported\ | no | list | | Identifies the | -| _virtualization\| | | | virtualization | -| _enviroment | | | | environments (e.g. | -| | | | | hypervisor) compatible | -| | | | | with this software image| -+-----------------+---------+----------+------------+-------------------------+ - -Definition -+++++++++++ - -+-----------------------------------------------------+ -| tosca.artifacts.nfv.SwImage: | -| | -| derived\_from: tosca.artifacts.Deployment.Image | -| | -| properties or metadata: | -| | -| #id: | -| | -| # node name | -| | -| name: | -| | -| type: string | -| | -| required: true | -| | -| version: | -| | -| type: string | -| | -| required: true | -| | -| checksum: | -| | -| type: string | -| | -| required: true | -| | -| container\_format: | -| | -| type: string | -| | -| required: true | -| | -| disk\_format: | -| | -| type: string | -| | -| required: true | -| | -| min\_disk: | -| | -| type: scalar-unit.size # Number | -| | -| required: true | -| | -| min\_ram: | -| | -| type: scalar-unit.size # Number | -| | -| required: false | -| | -| size: | -| | -| type: scalar-unit.size # Number | -| | -| required: true | -| | -| sw\_image: | -| | -| type: string | -| | -| required: true | -| | -| operating\_system: | -| | -| type: string | -| | -| required: false | -| | -| supported\_virtualisation\_environments: | -| | -| type: list | -| | -| entry\_schema: | -| | -| type: string | -| | -| required: false | -+-----------------------------------------------------+ - -.. |image1| image:: Image1.png - :width: 5.76806in - :height: 4.67161in -.. |image2| image:: Image2.png - :width: 5.40486in - :height: 2.46042in - - -Heat -------------- - -General Guidelines -^^^^^^^^^^^^^^^^^^ -This section contains general Heat Orchestration Template guidelines. - -YAML Format -~~~~~~~~~~~ - -R-95303 A VNF's Heat Orchestration Template **MUST** be defined -using valid YAML. - -YAML (YAML Ain't -Markup Language) is a human friendly data serialization standard for all -programming languages. See http://www.yaml.org/. - -Heat Orchestration Template Format -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -As stated above, Heat Orchestration templates must be defined in YAML. - -YAML rules include: - - - Tabs are not allowed, use spaces ONLY - - - You must indent your properties and lists with 1 or more spaces - - - All Resource IDs and resource property parameters are - case-sensitive. (e.g., "ThIs", is not the same as "thiS") - -Heat Orchestration Template Structure -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Heat Orchestration template structure follows the following format, -as defined by OpenStack at -https://docs.openstack.org/developer/heat/template_guide/hot_spec.html - -.. code-block:: python - - heat_template_version: <date> - - description: - # a description of the template - - parameter_groups: - # a declaration of input parameter groups and order - - parameters: - # declaration of input parameters - - resources: - # declaration of template resources - - outputs: - # declaration of output parameters - - conditions: - # declaration of conditions - -heat_template_version -+++++++++++++++++++++ - -R-27078 A VNF's Heat Orchestration template **MUST** contain -the section "heat_template_version:". - -The section "heat_template_version:" must be set to a date -that is supported by the OpenStack environment. - -description -+++++++++++ - -R-39402 A VNF's Heat Orchestration Template **MUST** -contain the section "description:". - -parameter_groups -++++++++++++++++ - -A VNF Heat Orchestration template may -contain the section "parameter_groups:". - -parameters -++++++++++ - -R-35414 A VNF Heat Orchestration's template **MUST** -contain the section "parameters:". - - -.. code-block:: python - - parameters: - - <param name>: - - type: <string | number | json | comma_delimited_list | boolean> - - label: <human-readable name of the parameter> - - description: <description of the parameter> - - default: <default value for parameter> - - hidden: <true | false> - - constraints: - - <parameter constraints> - - immutable: <true | false> - -This section allows for -specifying input parameters that have to be provided when instantiating -the template. Each parameter is specified in a separate nested block -with the name of the parameters defined in the first line and additional -attributes (e.g., type, label) defined as nested elements. - -R-90279 A VNF Heat Orchestration's template's parameter **MUST** -be used in a resource with the exception of the parameters -for the OS::Nova::Server resource property availability_zone. - -R-91273 A VNF Heat Orchestration’s template’s parameter for -the OS::Nova::Server resource property availability_zone -**MAY NOT** be used in any OS::Nova::Resource. - -<param name> -____________ - -The name of the parameter. - -R-25877 A VNF's Heat Orchestration Template's parameter -name (i.e., <param name>) **MUST** contain only -alphanumeric characters and underscores ('_'). - -type -____ - -R-36772 A VNF’s Heat Orchestration Template’s parameter -**MUST** include the attribute “type:”. - -R-11441 A VNF’s Heat Orchestration Template’s parameter -type **MUST** be one of the following values: "string", -"number", "json", "comma_delimited_list" or "boolean". - -label -_____ - -R-32094 A VNF's Heat Orchestration Template parameter -declaration **MAY** contain the attribute "label:" - -description -___________ - -R-44001 A VNF's Heat Orchestration Template parameter -declaration **MUST** contain the attribute "description". - -Note that the parameter attribute “description:” is an -OpenStack optional attribute that provides a description -of the parameter. ONAP implementation requires this attribute. - -default -_______ - -R-90526 A VNF Heat Orchestration Template parameter -declaration **MUST** not contain the default attribute. - -R-26124 If a VNF Heat Orchestration Template parameter -requires a default value, it **MUST** be enumerated in the environment file. - -Note that the parameter attribute “default:” is an OpenStack -optional attribute that declares the default value of the -parameter. ONAP implementation prohibits the use of this attribute. - -hidden -______ - -R-32557 A VNF's Heat Orchestration Template parameter -declaration MAY contain the attribute "hidden:". - -The parameter attribute "hidden:" is an OpenStack optional -attribute that defines whether the parameters should be -hidden when a user requests information about a stack -created from the template. This attribute can be used -to hide passwords specified as parameters. - -constraints -___________ - -The parameter attribute "constraints:" is an OpenStack optional -attribute that defines a list of constraints to apply to the parameter. - -R-88863 A VNF's Heat Orchestration Template's parameter defined as -type "number" **MUST** have a parameter constraint of "range" or -"allowed_values" defined. - -R-40518 A VNF's Heat Orchestration Template’s parameter defined as -type "string" **MAY** have a parameter constraint defined. - -R-96227 A VNF's Heat Orchestration Template’s parameter defined as -type "json" **MAY** have a parameter constraint defined. - -R-79817 A VNF's Heat Orchestration Template’s parameter defined as -type "comma_delimited_list" **MAY** have a parameter constraint defined. - -R-06613 A VNF's Heat Orchestration Template’s parameter defined as -type "boolean" **MAY** have a parameter constraint defined. - -R-00011 A VNF's Heat Orchestration Template's Nested YAML files -parameter's **MUST NOT** have a parameter constraint defined. - -The constraints block of a parameter definition defines additional -validation constraints that apply to the value of the parameter. -The parameter values provided in the VNF Heat Orchestration Template -are validated against the constraints at instantiation time. -The stack creation fails if the parameter value doesn’t comply to -the constraints. - -The constraints are defined as a list with the following syntax - -.. code-block:: python - - constraints: - - <constraint type>: <constraint definition> - - description: <constraint description> - -.. - -**<constraint type>** Provides the type of constraint to apply. -The list of OpenStack supported constraints can be found at -https://docs.openstack.org/heat/latest/template_guide/hot_spec.html . - -**<constraint definition>** provides the actual constraint. -The syntax and constraint is dependent of the <constraint type> used. - -**description** is an optional attribute that provides a description of the -constraint. The text is presented to the user when the value the user -defines violates the constraint. If omitted, a default validation -message is presented to the user. - -Below is a brief overview of the "range" and "allowed values" constraints. -For complete details on constraints, see -https://docs.openstack.org/heat/latest/template_guide/hot_spec.html#parameter-constraints - -**range** - -range: The range constraint applies to parameters of type: number. -It defines a lower and upper limit for the numeric value of the -parameter. The syntax of the range constraint is - -.. code-block:: python - - range: { min: <lower limit>, max: <upper limit> } - -.. - -It is possible to define a range constraint with only a lower -limit or an upper limit. - -**allowed_values** - -allowed_values: The allowed_values constraint applies to parameters of -type \"string\" or type \"number\". It specifies a set of possible -values for a parameter. At deployment time, the user-provided value -for the respective parameter must match one of the elements of the -list. The syntax of the allowed_values constraint is - -.. code-block:: python - - allowed_values: [ <value>, <value>, ... ] - - Alternatively, the following YAML list notation can be used - - allowed_values: - - - <value> - - - <value> - - - ... - -. . - -immutable -_________ - -R-22589 A VNF’s Heat Orchestration Template parameter declaration -**MAY** contain the attribute "immutable:". - -The parameter attribute \"immutable:\" is an OpenStack optional -attribute that defines whether the parameter is updatable. A Heat -Orchestration Template stack update fails if immutable is set to -true and the parameter value is changed. This attribute -\"immutable:\" defaults to false. - -resources -+++++++++ - -R-23664 A VNF's Heat Orchestration template **MUST** contain -the section "resources:". - -R-90152 A VNF's Heat Orchestration Template's "resources:" -section **MUST** contain the declaration of at least one resource. - -R-40551 A VNF's Heat Orchestration Template's Nested YAML files -**MAY** contain the section "resources:". - -Each resource is defined as a -separate block in the resources section with the following syntax. - -.. code-block:: python - - resources: - - <resource ID>: - - type: <resource type> - - properties: - - <property name>: <property value> - - metadata: - - <resource specific metadata> - - depends_on: <resource ID or list of ID> - - update_policy: <update policy> - - deletion_policy: <deletion policy> - - external_id: <external resource ID> - - condition: <condition name or expression or boolean> - - - -resource ID -___________ - -R-75141 A VNF's Heat Orchestration Template's resource name -(i.e., <resource ID>) **MUST** only contain alphanumeric -characters and underscores ('_'). - -R-16447 A VNF's <resource ID> **MUST** be unique across all -Heat Orchestration Templates and all HEAT Orchestration Template -Nested YAML files that are used to create the VNF. - -Note that a VNF can be composed of one or more Heat Orchestration Templates. - -Note that OpenStack requires the <resource ID> to be unique to the -Heat Orchestration Template and not unique across all Heat -Orchestration Templates the compose the VNF. - -type -____ - -The resource attribute \"type:\" is an OpenStack required -attribute that defines the resource type, such as -OS::Nova::Server or OS::Neutron::Port. - -The resource attribute \"type:\" may specify a VNF HEAT -Orchestration Template Nested YAML file. - -R-53952 A VNF’s Heat Orchestration Template’s Resource -**MUST NOT** reference a HTTP-based resource definitions. - -R-71699 A VNF’s Heat Orchestration Template’s Resource -**MUST NOT** reference a HTTP-based Nested YAML file. - -properties -__________ - -The resource attribute \"properties:\" is an OpenStack optional -attribute that provides a list of resource-specific properties. -The property value can be provided in place, or via a function -(e.g., `Intrinsic functions <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-intrinsic-functions>`__). - -R-10834 If a VNF Heat Orchestration Template resource attribute -"property:" uses a nested "get_param", one level of nesting is -supported and the nested "get_param" **MUST** reference an index - -metadata -________ - -The resource attribute \"metadata:\" is an OpenStack optional attribute. - -R-97199 A VNF's Heat Orchestration Template's OS::Nova::Server -resource **MUST** contain the attribute "metadata". - -Section 5.4 contains the OS::Nova::Server mandatory and optional metadata. - - -depends_on -__________ - -The resource attribute \"depends_on:\" is an OpenStack optional -attribute. -See `OpenStack documentation <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-resources-dependencies>`__ -for additional details. - -R-46968 VNF’s Heat Orchestration Template’s Resource **MAY** -declare the attribute “depends_on:”. - -update_policy -_____________ - -R-63137 VNF’s Heat Orchestration Template’s Resource **MAY** -declare the attribute “update_policy:”. - -deletion_policy -_______________ - -R-43740 A VNF’s Heat Orchestration Template’s Resource -**MAY** declare the attribute “deletion_policy:”. - -If specified, the \"deletion_policy:\" attribute for resources -allows values 'Delete', 'Retain', and 'Snapshot'. -Starting with heat_template_version 2016-10-14, lowercase -equivalents are also allowed. - -The default policy is to delete the physical resource when -deleting a resource from the stack. - -external_id -___________ - -R-78569 A VNF’s Heat Orchestration Template’s Resouce **MAY** -declare the attribute “external_id:”. - -This attribute allows for specifying the resource_id for an -existing external (to the stack) resource. External resources -cannot depend on other resources, but we allow other resources to -depend on external resource. This attribute is optional. -Note: when this is specified, properties will not be used for -building the resource and the resource is not managed by Heat. -This is not possible to update that attribute. Also, -resource won’t be deleted by heat when stack is deleted. - - -condition -_________ - -The resource attribute \"condition:\" is an OpenStack optional attribute. - -Support for the resource condition attribute was added -in the Newton release of OpenStack. - -outputs -+++++++ - -R-36982 A VNF’s Heat Orchestration template **MAY** -contain the “outputs:” section. - -This section allows for specifying output parameters -available to users once the template has been instantiated. If the -section is specified, it will need to adhere to specific requirements. -See `ONAP Parameter Classifications Overview`_ and -`ONAP Output Parameter Names`_ for additional details. - -Environment File Format -~~~~~~~~~~~~~~~~~~~~~~~ - -The environment file is a yaml text file. -(https://docs.openstack.org/developer/heat/template_guide/environment.html) - -R-86285 The VNF Heat Orchestration Template **MUST** have a corresponding -environment file, even if no parameters are required to be enumerated. - -The use of an environment file in OpenStack is optional. -In ONAP, it is mandatory. - -R-03324 The VNF Heat Orchestration Template **MUST** contain the -"parameters" section in the -environment file - -R-68198 A VNF’s Heat Orchestration template’s Environment File’s -“parameters:” section **MAY** enumerate parameters. - -ONAP implementation requires the parameters section in the -environmental file to be declared. The parameters section -contains a list of key/value pairs. - -R-59930 A VNF’s Heat Orchestration template’s Environment -File’s **MAY** contain the “parameter_defaults:” section. - -The “parameter_defaults:” section contains default parameters -that are passed to all template resources. - -R-46096 A VNF’s Heat Orchestration template’s Environment File’s -**MAY** contain the “encrypted_parameters:” section. - -The “encrypted_parameters:” section contains a list of encrypted parameters. - -R-24893 A VNF’s Heat Orchestration template’s Environment File’s -**MAY** contain the “event_sinks:” section. - -The “event_sinks:” section contains the list of endpoints that would -receive stack events. - -R-42685 A VNF’s Heat Orchestration template’s Environment File’s -**MAY** contain the “parameter_merge_strategies:” section. - -The “parameter_merge_strategies:” section provides the merge strategies -for merging parameters and parameter defaults from the environment file. - -R-67231 A VNF’s Heat Orchestration template’s Environment File’s **MUST NOT** -contain the “resource_registry:” section. - -ONAP implementation does not support the Environment File -resource_registry section. The resource_registry section -allows for the definition of custom resources. - - -SDC Treatment of Environment Files -++++++++++++++++++++++++++++++++++ - -Parameter values enumerated in the environment file are used by SDC as -the default value. However, the SDC user may use the SDC GUI to -overwrite the default values in the environment file. - -SDC generates a new environment file for distribution to MSO based on -the uploaded environment file and the user provided GUI updates. The -user uploaded environment file is discarded when the new file is -created. - -ONAP has requirements for what parameters must be enumerated in the -environment file and what parameter must not be enumerated in the -environment file. See `ONAP Parameter Classifications Overview`_ and -`ONAP Resource ID and Parameter Naming Convention`_ for more details. - -ONAP Heat Orchestration Templates: Overview -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -ONAP supports a modular Heat Orchestration Template design pattern, -referred to as *VNF Modularity.* - -ONAP VNF Modularity Overview -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -R-69663 A VNF **MAY** be composed from one or more Heat Orchestration -Templates, each of which represents a subset of the overall VNF. - -The Heat Orchestration Templates can be thought of a components or -modules of the VNF and are referred to as “\ *VNF Modules*\ ”. -During orchestration, these modules are -deployed incrementally to create the complete VNF. - -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). - -R-37028 The VNF **MUST** be composed of one “base” module. - -R-13196 A VNF **MAY** be composed of zero to many Incremental Modules - -R-20974 The VNF **MUST** deploy the base module first, prior to -the incremental modules. - -R-28980 A VNF’s incremental module **MAY** be used for initial VNF -deployment only. - -R-86926 A VNF’s incremental module **MAY** be used for scale out only. - -A VNF’s Incremental Module that is used for scale out is deployed -sometime after initial VNF deployment to add capacity. - -R-91497 A VNF’s incremental module **MAY** be used for both deployment -and scale out. - -R-68122 A VNF’s incremental module **MAY** be deployed more than once, -either during initial VNF deployment and/or scale out. - -R-46119 A VNF’s Heat Orchestration Template’s Resource OS::Heat::CinderVolume -**MAY** be defined in a Base Module. - -R-90748 A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume -**MAY** be defined in an Incremental Module. - -R-03251 A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume -**MAY** be defined in a Cinder Volume Module. - -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 Virtual Machine -(VM) (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused -on another instance (e.g., during a failover activity). - -R-11200 The VNF **MUST** keep the scope of a Cinder volume module, when it -exists, to be 1:1 with the VNF Base Module or Incremental Module - -It is strongly recommended that Cinder Volumes be created in a Cinder Volume -Module. - -R-38474 The VNF **MUST** have a corresponding environment file for a -Base Module. - -R-81725 The VNF **MUST** have a corresponding environment file for an -Incremental Module. - -R-53433 The VNF **MUST** have a corresponding environment file for a -Cinder Volume Module. - -These concepts will be described in more detail throughout the document. -This overview is provided to set the stage and help clarify the concepts -that will be introduced. - -Nested Heat Orchestration Templates Overview -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -ONAP supports nested Heat Orchestration Templates per OpenStack -specifications. - -R-36582 A VNF’s Base Module **MAY** utilize nested heat. - -R-56721 A VNF’s Incremental Module **MAY** utilize nested heat. - -R-30395 A VNF’s Cinder Volume Module **MAY** utilize nested heat. - -Nested templates may be suitable for larger VNFs that contain many -repeated instances of the same VM type(s). A common usage pattern is to -create a nested template for each VM type along with its supporting -resources. The Heat Orchestration Template may then reference these -nested templates either statically (by repeated definition) or -dynamically (via OS::Heat::ResourceGroup). - -See `Nested Heat Templates`_ for additional details. - -ONAP Heat Orchestration Template Filenames -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -In order to enable ONAP to understand the relationship between Heat -files, the following Heat file naming convention must be utilized. - -In the examples below, <text> represents any alphanumeric string that -must not contain any special characters and must not contain the word -“base”. - -R-87485 A VNF’s Heat Orchestration Template’s file extension **MUST** -be in the lower case format ‘.yaml’ or ‘.yml’. - -R-56438 A VNF’s Heat Orchestration Template’s Nested YAML file extension -**MUST** be in the lower case format ‘.yaml’ or ‘.yml’. - -R-74304 A VNF’s Heat Orchestration Template’s Environment file extension -**MUST** be in the lower case format ‘.env’. - -Base Modules -++++++++++++ - -R-81339 A VNF Heat Orchestration Template’s Base Module file name **MUST** -include ‘base’ in the filename and **MUST** match one of the following four -formats: 1.) ‘base_<text>.y[a]ml’, 2.) ‘<text>_base.y[a]ml’, 3.) -‘base.y[a]ml’, or 4.) ‘<text>_base_<text>’.y[a]ml; where ‘base’ is case -insensitive and where ‘<text>’ **MUST** contain only alphanumeric characters -and underscores ‘_’ and **MUST NOT** contain the case insensitive word ‘base’. - -R-91342 A VNF Heat Orchestration Template’s Base Module’s Environment File -**MUST** be named identical to the VNF Heat Orchestration Template’s Base -Module with ‘.y[a]ml’ replaced with ‘.env’. - -Incremental Modules -+++++++++++++++++++ - -R-87247 A VNF Heat Orchestration Template’s Incremental Module file name -**MUST** contain only alphanumeric characters and underscores ‘_’ and -**MUST NOT** contain the case insensitive word ‘base’. - -R-94509 A VNF Heat Orchestration Template’s Incremental Module’s Environment -File **MUST** be named identical to the VNF Heat Orchestration Template’s -Incremental Module with ‘.y[a]ml’ replaced with ‘.env’. - -To clearly identify the incremental module, it is recommended to use the -following naming options for modules: - - - module_<text>.y[a]ml - - - <text>_module.y[a]ml - - - module.y[a]ml - - - <text>_module_<text>.y[a]ml - -Cinder Volume Modules -+++++++++++++++++++++ - -R-82732 A VNF Heat Orchestration Template’s Cinder Volume Module **MUST** be -named identical to the base or incremental module it is supporting with -‘_volume appended’ - -R-31141 A VNF Heat Orchestration Template’s Cinder Volume Module’s Environment -File **MUST** be named identical to the VNF Heat Orchestration Template’s -Cinder Volume Module with .y[a]ml replaced with ‘.env’. - -Nested Heat file -++++++++++++++++ - -R-76057 A VNF Heat Orchestration Template’s Nested YAML file name **MUST** -contain only alphanumeric characters and underscores ‘_’ and **MUST NOT** -contain the case insensitive word ‘base’. - -Examples include - - - <text>.y[a]ml - - - nest_<text>.y[a]ml - - - <text>_nest.y[a]ml - - - nest.y[a]ml - - - <text>_nest_<text>.y[a]ml - -VNF Heat Orchestration Template's Nested YAML file does not have a -corresponding environment files, per OpenStack specifications. - -R-18224 The VNF Heat Orchestration Template **MUST** pass in as properties -all parameter values -associated with the nested heat file in the resource definition defined -in the parent heat template. - -Output Parameters -~~~~~~~~~~~~~~~~~ - -The output parameters are parameters defined in the output section of a -Heat Orchestration Template. The ONAP output parameters are subdivided -into three categories: - -1. ONAP Base Module Output Parameters - -2. ONAP Volume Module Output Parameters - -3. ONAP Predefined Output Parameters. - -ONAP Base Module Output Parameters -++++++++++++++++++++++++++++++++++++ - -ONAP Base Module Output Parameters are declared in the 'outputs:'' section of -the VNF's Heat Orchestration Template's Base Module. A Base Module Output -Parameter is available as an input parameter (i.e., declared in the -'parameters:'' section) to all Incremental Modules in the VNF. - -A Base Module Output Parameter may be used as an input parameter in any -incremental module in the VNF. Note that the parameter is not -available to other VNFs. - -R-52753 VNF’s Heat Orchestration Template’s Base Module’s output parameter’s -name and type **MUST** match the VNF’s Heat Orchestration Template’s -incremental Module’s name and type unless the output parameter is of type -‘comma_delimited_list’, then the corresponding input parameter **MUST** -be declared as type ‘json’. - -If the Output parameter has a comma_delimited_list value (e.g., a collection -of UUIDs from a Resource Group), then the corresponding input parameter -must be declared as type json and not a comma_delimited_list, which is -actually a string value with embedded commas. - -R-22608 When a VNF’s Heat Orchestration Template’s Base Module’s output -parameter is declared as an input parameter in an Incremental Module, -the parameter attribute ‘constraints:’ **MUST NOT** be declared. - -Additional details on ONAP Base Module Output Parameters are provided in -`ONAP Output Parameter Names`_ and ONAP VNF Modularity. - -ONAP Volume Module Output Parameters -++++++++++++++++++++++++++++++++++++ - -R-89913 A VNF’s Heat Orchestration Template’s Cinder Volume Module Output -Parameter(s) **MUST** include the UUID(s) of the Cinder Volumes created in -template, while other Output Parameters **MAY** be included. - -A VNF’s Heat Orchestration Template’s Cinder Volume Module Output Parameter(s) -are only available for the module (base or incremental) that the volume -template is associated with. - -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’. - -If the Output parameter has a comma_delimited_list value (e.g., a collection -of UUIDs from a Resource Group), then the corresponding input parameter must -be declared as type json and not a comma_delimited_list, which is actually a -string value with embedded commas. - -R-20547 When an ONAP Volume Module Output Parameter is declared as an input -parameter in a base or an incremental module Heat Orchestration Template, -parameter constraints **MUST NOT** be declared. - -Additional details on ONAP Base Module Output Parameters are provided in -`ONAP Output Parameter Names`_ and `Cinder Volume Templates`_. - -ONAP Predefined Output Parameters -+++++++++++++++++++++++++++++++++++ - -ONAP will look for a small set of pre-defined Heat output parameters to -capture resource attributes for inventory in ONAP. These output parameters -are optional and currently only two parameters are supported. These output -parameters are optional and are specified in `OAM Management IP Addresses`_. - -Support of heat stack update -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -ONAP does not support the use of heat stack-update command for scaling -(growth/de-growth). - -R-39349 A VNF Heat Orchestration Template **MUST NOT** be designed to -utilize the OpenStack ‘heat stack-update’ command for scaling -(growth/de-growth). - -R-43413 A VNF **MUST** utilize a modular Heat Orchestration Template -design to support scaling (growth/de-growth). - -Scope of a Heat Orchestration Template -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -R-59482 A VNF’s Heat Orchestration Template **MUST NOT** be VNF instance -specific or Cloud site specific - -R-56750 A VNF’s Heat Orchestration Template’s parameter values that are -constant across all deployments **MUST** be declared in a Heat Orchestration -Template Environment File. - -ONAP provides the instance specific parameter values to the Heat -Orchestration Template at orchestration time. - -R-01896 A VNF’s Heat Orchestration Template’s parameter values that are -constant across all deployments **MUST** be declared in a Heat Orchestration -Template Environment File. - -Networking -^^^^^^^^^^ - -ONAP defines two types of networks: External Networks and Internal Networks. - -External Networks -~~~~~~~~~~~~~~~~~ - -ONAP defines an external network in relation to the VNF and not with regard -to the Network Cloud site. External networks may also be referred to as -“inter-VNF” networks. An external network must connect VMs in a VNF to -VMs in another VNF or an external gateway or external router. - -An External Network may be a Neutron Network or a Contrail Network. - -R-16968 A VNF’s Heat Orchestration Templates **MUST NOT** include heat -resources to create external networks. - -External networks must be orchestrated separately, independent of the VNF. -This allows the network to be shared by multiple VNFs and managed -independently of VNFs. - -R-00606 A VNF **MAY** be connected to zero, one or more than one external -networks. - -R-57424 A VNF’s port connected to an external network **MUST** connect the -port to VMs in another VNF and/or an external gateway and/or external router. - -R-29865 A VNF’s port connected to an external network **MUST NOT** connect -the port to VMs in the same VNF. - -R-69014 When a VNF connects to an external network, a network role, referred -to as the ‘{network-role}’ **MUST** be assigned to the external network -for use in the VNF’s Heat Orchestration Template. - -R-05201 When a VNF connects to two or more external networks, each external -network **MUST** be assigned a unique ‘{network-role}’ in the context of -the VNF for use in the VNF’s Heat Orchestration Template. - -R-83015 A VNF’s ‘{network-role}’ assigned to an external network **MUST** -be different than the ‘{network-role}’ assigned to the VNF’s internal -networks, if internal networks exist. - -ONAP enforces a naming convention for parameters associated with -external networks. `ONAP Resource ID and Parameter Naming Convention`_ -provides additional details. - -Internal Networks -~~~~~~~~~~~~~~~~~ - -ONAP defines an internal network in relation to the VNF and not with -regard to the Network Cloud site. Internal networks may also be referred -to as “intra-VNF” networks or “private” networks. An internal network -only connects VMs in a single VNF; it must not connect to other VNFs -or an external gateway or router - -R-87096 A VNF **MAY** contain zero, one or more than one internal networks. - -R-35666 If a VNF has an internal network, the VNF Heat Orchestration -Template **MUST** include the heat resources to create the internal network. - -R-86972 A VNF **SHOULD** create the internal network in the VNF’s Heat -Orchestration Template Base Module. - -An Internal Network may be created using Neutron Heat Resources and/or -Contrail Heat Resources. - -R-52425 A VNF’s port connected to an internal network **MUST** connect -the port to VMs in the same VNF. - -R-46461 A VNF’s port connected to an internal network **MUST NOT** connect -the port to VMs in another VNF and/or an external gateway and/or -external router. - -R-68936 When a VNF creates an internal network, a network role, referred to -as the ‘{network-role}’ **MUST** be assigned to the internal network for -use in the VNF’s Heat Orchestration Template. - -R-32025 When a VNF creates two or more internal networks, each internal -network **MUST** be assigned a unique ‘{network-role}’ in the context of -the VNF for use in the VNF’s Heat Orchestration Template. - -R-69874 A VNF’s ‘{network-role}’ assigned to an internal network **MUST** -be different than the ‘{network-role}’ assigned to the VNF’s external -networks. - -R-34726 If a VNF’s port is connected to an internal network and the port -is created in the same Heat Orchestration Template as the internal network, -then the port resource **MUST** use a ‘get_resource’ to obtain -the network UUID. - -R-22688 If a VNF’s port is connected to an internal network and the -port is created in an Incremental Module and the internal network is created -in the Base Module then the UUID of the internal network **MUST** be exposed -as a parameter in the ‘outputs:’ section of the Base Module and the port -resource **MUST** use a ‘get_param’ to obtain the network UUID. - -ONAP does not programmatically enforce a naming convention for -parameters for internal network. However, a naming convention is -provided that must be followed. -`ONAP Resource ID and Parameter Naming Convention`_ -provides additional details. - -ONAP Resource ID and Parameter Naming Convention -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This section provides the ONAP naming requirements for - -1. Resource IDs - -2. Resource Property Parameters - -{vm-type} -~~~~~~~~~ - -R-01455 When a VNF's Heat Orchestration Template creates a -Virtual Machine (i.e., 'OS::Nova::Server'), each 'class' of VMs -**MUST** be assigned a VNF unique '{vm-type}'; where 'class' -defines VMs that **MUST** have the following identical characteristics: - - 1.) OS::Nova::Server property flavor value - - 2.) OS::Nova::Server property image value - - 3.) Cinder Volume attachments - - Each VM in the 'class' **MUST** have the identical Cinder Volume - configuration - - 4.) Network attachments and IP address requirements - - Each VM in the 'class' **MUST** have the the identical number - of ports connecting to the identical networks and requiring the - identical IP address configuration. - -R-82481 A VNF's Heat Orchestration Template's Resource property -parameter that is -associated with a unique Virtual Machine type **MUST** -include '{vm-type}' as part of the parameter name with two -exceptions: - - 1.) The Resource OS::Nova::Server property availability_zone parameter - **MUST NOT** be prefixed with a common '{vm-type} identifier, - - 2.) The Resource OS::Nova::Server eight mandatory and optional metadata - parameters (vnf_name, vnf_id, vf_module_id, vf_module_name, vm_role, - vf_module_index, environment_context, workload_context) **MUST NOT** - be prefixed with a common '{vm-type}' identifier. - - -R-66729 A VNF’s Heat Orchestration Template’s Resource that is -associated with a unique Virtual Machine type **MUST** include -‘{vm-type}’ as part of the resource ID. - -R-98407 A VNF's Heat Orchestration Template's '{vm-type}' **MUST** contain -only alphanumeric characters and/or underscores '_' and -**MUST NOT** contain any of the following strings: '_int' or 'int\_' -or '\_int\_'. - -R-48067 A VNF's Heat Orchestration Template's {vm-type} **MUST NOT** be a -substring of {network-role}. - -It may cause the Pre-Amsterdam VNF Validation Program (i.e., -ICE Project) process to produce erroneous error messages. - -R-32394 A VNF’s Heat Orchestration Template’s use of ‘{vm-type}’ -in all Resource property parameter names **MUST** be the same case. - -R-46839 A VNF’s Heat Orchestration Template’s use of -‘{vm-type}’ in all Resource IDs **MUST** be the same case. - -R-36687 A VNF’s Heat Orchestration Template’s ‘{vm-type}’ case in -Resource property parameter names **SHOULD** match the case of -‘{vm-type}’ in Resource IDs and vice versa. - -{network-role} -~~~~~~~~~~~~~~ - -The assignment of a {network-role} is discussed in `Networking`_. - -R-21330 A VNF’s Heat Orchestration Template’s Resource property -parameter that is associated with external network **MUST** -include the ‘{network-role}’’ as part of the parameter name - -R-11168 A VNF's Heat Orchestration Template's Resource ID that is -associated with an external network **MUST** include the -'{network-role}' as part of the resource ID. - -R-84322 A VNF's Heat Orchestration Template's Resource property -parameter that is associated with an internal network -**MUST** include 'int\_{network-role}' as part of the parameter -name, where 'int\_' is a hard coded string. - -R-96983 A VNF's Heat Orchestration Template's Resource ID that is -associated with an internal network **MUST** include -'int\_{network-role}' as part of the Resource ID, where -'int\_' is a hard coded string. - -R-26506 A VNF's Heat Orchestration Template's '{network-role}' -**MUST** contain only alphanumeric characters and/or -underscores '_' and **MUST NOT** contain any of the following -strings: '_int' or 'int\_' or '\_int\_'. - -R-00977 A VNF’s Heat Orchestration Template’s ‘{network-role}’ -**MUST NOT** be a substring of ‘{vm-type}’. - -For example, if a VNF has a ‘{vm-type}’ of ‘oam’ and a -‘{network-role}’ of ‘oam_protected’ would be a violation of the requirement. - -R-58424 A VNF’s Heat Orchestration Template’s use of ‘{network-role}’ -in all Resource property parameter names **MUST** be the same case - -R-21511 A VNF’s Heat Orchestration Template’s use of ‘{network-role}’ -in all Resource IDs **MUST** be the same case. - -R-86588 A VNF’s Heat Orchestration Template’s ‘{network-role}’ case -in Resource property parameter names **SHOULD** match the case -of ‘{network-role}’ in Resource IDs and vice versa. - -Resource IDs -~~~~~~~~~~~~ - -Requirement R-75141 states a VNF’s Heat Orchestration Template’s -resource name (i.e., <resource ID>) MUST only contain alphanumeric -characters and underscores (‘_’).* - -Requirement R-16447 states a VNF’s <resource ID> MUST be unique -across all Heat Orchestration Templates and all HEAT Orchestration -Template Nested YAML files that are used to create the VNF. - -As stated previously, OpenStack requires the <resource ID> to be unique -to the Heat Orchestration Template and not unique across all Heat -Orchestration Templates the compose the VNF. - -Heat Orchestration Template resources are described in `resources`_ - -R-54517 When a VNF’s Heat Orchestration Template’s resource is associated -with a single ‘{vm-type}’, the Resource ID **MUST** contain the ‘{vm-type}’. - -R-96482 When a VNF’s Heat Orchestration Template’s resource is associated -with a single external network, the Resource ID MUST contain the text -‘{network-role}’. - -R-98138 When a VNF’s Heat Orchestration Template’s resource is associated -with a single internal network, the Resource ID MUST contain the text -‘int\_{network-role}’. - -R-82115 When a VNF's Heat Orchestration Template's resource is associated -with a single '{vm-type}' and a single external network, the Resource -ID text **MUST** contain both the '{vm-type}' and the '{network-role}' - -- the '{vm-type}' **MUST** appear before the '{network-role}' and **MUST** - be separated by an underscore '_' - - - e.g., '{vm-type}_{network-role}', '{vm-type}_{index}_{network-role}' - -- note that an '{index}' value **MAY** separate the '{vm-type}' and the - '{network-role}' and when this occurs underscores **MUST** separate the - three values. - -R-82551 When a VNF's Heat Orchestration Template's resource is associated -with a single '{vm-type}' and a single internal network, the Resource ID -**MUST** contain both the '{vm-type}' and the 'int\_{network-role}' and - -- the '{vm-type}' **MUST** appear before the 'int\_{network-role}' and - **MUST** be separated by an underscore '_' - - - (e.g., '{vm-type}\_int\_{network-role}', - '{vm-type}_{index}\_int\_{network-role}') - -- note that an '{index}' value **MAY** separate the '{vm-type}' and the - 'int\_{network-role}' and when this occurs underscores **MUST** separate - the three values. - -R-67793 When a VNF’s Heat Orchestration Template’s resource is associated -with more than one ‘{vm-type}’ and/or more than one internal and/or -external network, the Resource ID **MUST NOT** contain the ‘{vm-type}’ -and/or ‘{network-role}’/’int\_{network-role}’. It also should contain the -term ‘shared’ and/or contain text that identifies the VNF - -R-27970 When a VNF’s Heat Orchestration Template’s resource is associated -with more than one ‘{vm-type}’ and/or more than one internal and/or -external network, the Resource ID **MAY** contain the term ‘shared’ -and/or **MAY** contain text that identifies the VNF. - -R-11690 When a VNF’s Heat Orchestration Template’s Resource ID contains -an {index} value (e.g. multiple VMs of same {vm-type}), the ‘{index}’ -**MUST** start at zero and increment by one. - -The table below provides example OpenStack Heat resource ID for -resources only associated with one {vm-type} and/or one network. - -The Requirements column states if the Resource ID Format MUST be followed -or SHOULD be followed. Resource ID formats that are marked MUST must be -followed, no deviations are permitted. Resource ID formats that are marked -SHOULD should be followed. However, deviations are permissible to meet -the needs of the VNF’s Heat Orchestration Template. - -+-----------------+-------------------------+-------------+------------------+ -|Resource Type |Resource ID Format | Requirements| Notes | -| | | | | -+=================+=========================+=============+==================+ -| OS::Cinder:: | {vm-type}\_volume\ | **SHOULD** | | -| Volume | _{index} | | | -+-----------------+-------------------------+-------------+------------------+ -| OS::Cinder:: | {vm-type}\ | **SHOULD** | | -| VolumeAttachment| _volumeattachment\ | | | -| | _{index} | | | -+-----------------+-------------------------+-------------+------------------+ -| OS::Heat:: | {vm-type}_RCC | **SHOULD** | | -| CloudConfig | | | | -+-----------------+-------------------------+-------------+------------------+ -| OS::Heat:: | {vm-type}_RMM | **SHOULD** | | -| MultipartMime | | | | -+-----------------+-------------------------+-------------+------------------+ -| OS::Heat:: | {vm-type}_RRG | **SHOULD** | | -| ResourceGroup | | | | -+-----------------+-------------------------+-------------+------------------+ -| | {vm-type}\_{index}\ | **MUST** for| Resource ID for | -| | _subint\_{network-role}\| subinterface| the OS::Heat:: | -| | _port\_{index}\ | creation | ResourceGroup | -| | _subinterfaces | | that creates | -| | | | subinterfaces | -+-----------------+-------------------------+-------------+------------------+ -| OS::Heat:: | {vm-type}_RSC | **SHOULD** | | -| SoftwareConfig | | | | -+-----------------+-------------------------+-------------+------------------+ -| OS::Neutron:: | {vm-type}\ | **MUST** | Resource ID for | -| Port | _{vm-type-index}\ | | port connecting | -| | _{network-role}\_port\ | | to an external | -| | _{port-index} | | network. The | -| | | | {vm-type-index} | -| | | | is the instance | -| | | | of the {vm_type}.| -| | | | The {port-index} | -| | | | is the instance | -| | | | of the “port” on | -| | | | the {vm-type}. | -| | | | There is no index| -| | | | after | -| | | | {network_role} | -| | | | since | -| | | | {network-role} is| -| | | | unique to the | -| | | | VNF, there should| -| | | | only be one | -| | | | instance. | -+-----------------+-------------------------+-------------+------------------+ -| | {vm-type}\_{index}\_int\| **MUST** | Resource ID for | -| | _{network-role}\_port\ | | port connecting | -| | _{index} | | to an internal | -| | | | network. The | -| | | | {index} that | -| | | | follows {vm-type}| -| | | | is the instance | -| | | | of the {vm_type}.| -| | | | The {index} that | -| | | | follows “port” is| -| | | | the instance of | -| | | | the “port” on the| -| | | | {vm-type}. There | -| | | | is no index after| -| | | | {network_role} | -| | | | since | -| | | | {network-role} is| -| | | | unque to the AIC | -| | | | LCP; there should| -| | | | only be one | -| | | | instance. | -+-----------------+-------------------------+-------------+------------------+ -| | Reserve_Port\_{vm-type}\| | Resource ID for a| -| | _{network-role}\ | **MUST** | reserve port that| -| | _floating_ip\_{index} | | is used for an | -| | | | allowed_address | -| | Reserve_Port\_{vm-type}\| | \_pair. See | -| | _{network-role}\ | | Section 5.6.5.5 | -| | _floating_v6_ip\ | | for additional | -| | _{index} | | details. | -| | | | | -| | | | There is no | -| | | | {index} that | -| | | | follows {vm-type}| -+-----------------+-------------------------+-------------+------------------+ -| OS::Neutron:: | {vm-type}\_Sec\_Grp | **SHOULD** | Security Group | -| SecurityGroup | | | applicable to one| -| | | | {vm-type} and | -| | | | more than one | -| | | | network (internal| -| | | | and/or external) | -+-----------------+-------------------------+-------------+------------------+ -| | {network-role}\_Sec\_Grp| **SHOULD** | Security Group | -| | | | applicable to | -| | | | more than one | -| | | | {vm-type} and one| -| | | | external network | -+-----------------+-------------------------+-------------+------------------+ -| | int\_{network-role}\ | **SHOULD** | Security Group | -| | _Sec\_Grp | | applicable to | -| | | | more than one | -| | | | {vm-type} and one| -| | | | internal network | -+-----------------+-------------------------+-------------+------------------+ -| | {vm-type}\ | **SHOULD** | Security Group | -| | _{network-role}\_Sec\ | | applicable to one| -| | _Grp | | {vm-type} and one| -| | | | external network | -+-----------------+-------------------------+-------------+------------------+ -| | {vm-type}\_int\ | **SHOULD** | Security Group | -| | _{network-role}\_Sec\ | | applicable to one| -| | _Grp | | {vm-type} and one| -| | | | internal network | -+-----------------+-------------------------+-------------+------------------+ -| | Shared\_Sec\_Grp | **SHOULD** | Security Group | -| | | | applicable to | -| | | | more than one | -| | | | {vm-type} and | -| | | | more than one | -| | | | network (internal| -| | | | and/or external) | -+-----------------+-------------------------+-------------+------------------+ -| OS::Neutron:: | int\_{network-role}\ | **MUST** | VNF Heat | -| Subnet | _subnet\_{index} | | Orchestration | -| | | | Templates can | -| | | | only create | -| | | | internal | -| | | | networks. | -+-----------------+-------------------------+-------------+------------------+ -| OS::Neutron::Net| int\_{network-role}\ | **MUST** | VNF Heat | -| | _network | | Orchestration | -| | | | Templates can | -| | | | only create | -| | | | internal | -| | | | networks. There | -| | | | is no {index} | -| | | | because | -| | | | {nework-role} | -| | | |should be unique. | -+-----------------+-------------------------+-------------+------------------+ -| OS::Nova:: | {vm-type}\_keypair\ | **SHOULD** | Key Pair | -| Keypair | _{index} | | applicable to one| -| | | | a{vm-type} | -+-----------------+-------------------------+-------------+------------------+ -| | {vnf-type}_keypair | **SHOULD** | Key Pair | -| | | | applicable to all| -| | | | {vm-type} in the | -| | | | VNF | -+-----------------+-------------------------+-------------+------------------+ -| OS::Nova::Server| {vm-type}\_server\ | Mandatory | | -| | _{index} | | | -+-----------------+-------------------------+-------------+------------------+ -| OS::Nova:: | {vm-type}_RSG | **SHOULD** | Both formats are | -| ServerGroup | | | valid. | -+-----------------+-------------------------+-------------+------------------+ -| | {vm-type}_Server_Grp | **SHOULD** | | -+-----------------+-------------------------+-------------+------------------+ -| | {vm-type}_ServerGroup | **SHOULD** | | -+-----------------+-------------------------+-------------+------------------+ -| OS::Swift:: | {vm-type}\_RSwiftC | **SHOULD** | | -| Container | | | | -+-----------------+-------------------------+-------------+------------------+ - - - Table 2: Example OpenStack Heat Resource ID - -The table below provides Resource ID Formats for Contrail heat resources. - - The Resource ID formats that are marked mandatory must be followed. - No deviations are permitted. - - The Resource ID formats that are marked optional should be followed. - However, deviations in the Resource ID format that is shown is - permitted. - -+-----------------+---------------------+-----------------+-----------------+ -| Resource | Resource ID | Mandatory / | Notes | -| Type | Format | Optional | | -+=================+=====================+=================+=================+ -| OS::ContrailV2: | {vm-type}\_{index}\ | **MUST** – | The {index} | -| :InstanceIp | _{network-role}\ | IPv4 address on | that follows | -| | _vmi\_{index}\ | vmi external | {vm-type} is | -| | _IP\_{index} | network | the instance of | -| | | | the {vm_type}. | -| | | | The {index} | -| | | | that follows | -| | | | “vmi” is the | -| | | | instance of the | -| | | | “vmi” on the | -| | | | {vm-type}. | -| | | | There is no | -| | | | index after | -| | | | {network_role} | -| | | | since since | -| | | | {network-role} | -| | | | is unque. The | -| | | | {index} that | -| | | | follows the | -| | | | “IP” is the | -| | | | instance of the | -| | | | “IP” on the | -| | | | “vmi” | -+-----------------+---------------------+-----------------+-----------------+ -| | {vm-type}\_{index}\ | **MUST** – | | -| | _{network-role}\ | IPv6 address on | | -| | _vmi\_{index}\_v6\ | vmi external | | -| | _IP\_{index} | network | | -+-----------------+---------------------+-----------------+-----------------+ -| | {vm-type}\_{index}\ | **MUST** – | | -| | _int\ | IPv4 address on | | -| | _{network-role}\ | vmi internal | | -| | _vmi\_{index}\_IP\ | network | | -| | _{index} | | | -+-----------------+---------------------+-----------------+-----------------+ -| | {vm-type}\_{index}\ | **MUST** – | | -| | _int\ | IPv6 address on | | -| | _{network-role}\ | vmi internal | | -| | _vmi\_{index}\_v6\ | network | | -| | _IP\_{index} | | | -+-----------------+---------------------+-----------------+-----------------+ -| | {vm-type}\_{index}\ | **MUST** – | | -| | _subint\ | IPv4 address on | | -| | _{network-role}\ | sub-interface | | -| | _vmi\_{index}\_IP\ | vmi external | | -| | _{index} | network | | -+-----------------+---------------------+-----------------+-----------------+ -| | {vm-type}\_{index}\ | **MUST** – | | -| | _subint\ | IPv6 address on | | -| | _{network-role}\ | sub-interface | | -| | _vmi\_{index}\_v6\ | vmi external | | -| | _IP\_{index} | network | | -+-----------------+---------------------+-----------------+-----------------+ -| OS::ContrailV2: | {network-role}\_RIRT| **MAY** | | -| :InterfaceRoute | | | | -| Table | | | | -+-----------------+---------------------+-----------------+-----------------+ -| OS::ContrailV2: | {network-role}\_RNI | **MAY** | | -| :NetworkIpam | | | | -+-----------------+---------------------+-----------------+-----------------+ -| OS::ContrailV2: | {vm-type}\_RPT | **MAY** | | -| :PortTuple | | | | -+-----------------+---------------------+-----------------+-----------------+ -| OS::ContrailV2: | {vm-type}\_RSHC\ | **MAY** | | -| :ServiceHealthC | _{LEFT/RIGHT} | | | -| heck | | | | -+-----------------+---------------------+-----------------+-----------------+ -| OS::ContrailV2: | {vm-type}\_RST\ | **MAY** | | -| :ServiceTemplat | _{index} | | | -| e | | | | -+-----------------+---------------------+-----------------+-----------------+ -| OS::ContrailV2: | {vm-type}\_{index}\ | **MUST** - vmi | Resource ID for | -| :VirtualMachine | _{network-role}\ | attached to an | virtual machine | -| Interface | _vmi\_{index} | external | interface (vmi) | -| | | network | connecting to | -| | | | an external | -| | | | network. The | -| | | | {index} that | -| | | | follows | -| | | | {vm-type} is | -| | | | the instance of | -| | | | the {vm_type}. | -| | | | The {index} | -| | | | that follows | -| | | | “vmi” is the | -| | | | instance of the | -| | | | “vmi” on the | -| | | | {vm-type}. | -| | | | There is no | -| | | | index after | -| | | | {network_role} | -| | | | since since | -| | | | {network-role} | -| | | | is unque to the | -| | | | AIC LCP; there | -| | | | should only be | -| | | | one instance. | -+-----------------+---------------------+-----------------+-----------------+ -| | {vm-type}\_{index}\ | **MUST** - vmi | | -| | _int\ | attached to an | | -| | _{network-role}\ | internal | | -| | _vmi\_{index} | network | | -+-----------------+---------------------+-----------------+-----------------+ -| | {vm-type}\_{index}\ | **MUST** - vmi | | -| | _subint\ | attached to a | | -| | _{network-role}\ | sub-interface | | -| | _vmi\_{index} | network | | -+-----------------+---------------------+-----------------+-----------------+ -| OS::ContrailV2: | int\_{network-role}\| **MAY** | VNF Heat | -| :VirtualNetwork | _RVN | | Orchestration | -| | | | Templates can | -| | | | only create | -| | | | internal | -| | | | networks. There | -| | | | is no {index} | -| | | | because | -| | | | {nework-role} | -| | | | should be | -| | | | unique. Both | -| | | | formats are | -| | | | valid. | -+-----------------+---------------------+-----------------+-----------------+ -| | int\_{network-role}\| **MAY** | | -| | _network | | | -+-----------------+---------------------+-----------------+-----------------+ - - Table 3: Example Contrail Heat resource ID - -There is a use case where the template filename is used as the type: as -shown in the example below. There is no suggested Resource ID naming -convention for this use case. - -Example: Template Filename used as the type: - -.. code-block:: python - - heat_template_version: 2015-04-30 - - resources: - <Resource ID>: - type: file.yaml - properties: - ... - -Resource: OS::Nova::Server - Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The resource OS::Nova::Server manages the running virtual machine (VM) -instance within an OpenStack cloud. (See -https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::Server.) - -Four properties of this resource must follow the ONAP parameter naming -convention. The four properties are: - -1. image - -2. flavor - -3. name - -4. availability\_zone - -Requirement R-01455 defines how the ‘{vm-type]’ is defined. - -Requirement R-82481 defines how the ‘{vm-type} is used.’ - -The table below provides a summary. The sections that follow provides -the detailed requirements. - -.. csv-table:: **Table 4 OS::Nova::Server Resource Property Parameter Naming Convention** - :header: Property Name,Parameter Type,Parameter Name,Parameter Value Provided to Heat - :align: center - :widths: auto - - image, string, {vm-type}\_image\_name, Environment File - flavor, string, {vm-type}\_flavor\_name, Environment File - name, string, {vm-type}\_name\_{index}, ONAP - name, CDL, {vm-type}_names, ONAP - availability_zone, string, availability\_zone\_{index}, ONAP - -Property: image -+++++++++++++++ - -R-71152 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘image’ parameter **MUST** be declared as -type: ‘string’. - -R-58670 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘image’ parameter name **MUST** follow the -naming convention ‘{vm-type}_image_name’. - -R-91125 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘image’ parameter **MUST** be enumerated in -the Heat Orchestration Template’s Environment File and a value **MUST** be -assigned. - -R-57282 Each VNF’s Heat Orchestration Template’s ‘{vm-type}’ -**MUST** have a unique parameter name for the ‘OS::Nova::Server’ -property ‘image’ even if more than one {vm-type} shares the same image. - -*Example Parameter Definition* - -.. code-block:: yaml - - parameters: - {vm-type}_image_name: - type: string - description: {vm-type} server image - -Property: flavor -++++++++++++++++ - -R-50436 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘flavor’ parameter **MUST** be declared as -type: ‘string’. - -R-45188 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘flavor’ parameter name **MUST** follow the -naming convention ‘{vm-type}_flavor_name’. - -R-69431 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘flavor’ parameter **MUST** be enumerated in the -Heat Orchestration Template’s Environment File and a value **MUST** be -assigned. - -R-40499 Each VNF’s Heat Orchestration Template’s ‘{vm-type}’ **MUST** -have a unique parameter name for the ‘OS::Nova::Server’ property -‘flavor’ even if more than one {vm-type} shares the same flavor. - -*Example Parameter Definition* - -.. code-block:: yaml - - parameters: - {vm-type}_flavor_name: - type: string - description: {vm-type} flavor - -Property: Name -++++++++++++++ - -R-51430 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘name’ parameter **MUST** be declared as -either type ‘string’ or type ‘comma_delimited_list”. - -R-54171 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘name’ parameter is defined as a ‘string’, -the parameter name **MUST** follow the naming convention -‘{vm-type}\_name\_{index}’, where {index} is a numeric value that starts -at zero and increments by one. - -R-40899 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘name’ parameter is defined as a ‘string’, -a parameter **MUST** be declared for each ‘OS::Nova::Server’ resource -associated with the ‘{vm-type}’. - -R-87817 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘name’ parameter is defined as a -‘comma_delimited_list’, the parameter name **MUST** follow the naming -convention ‘{vm-type}_names’. - -R-85800 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘name’ parameter is defined as a -‘comma_delimited_list’, a parameter **MUST** be delcared once for all -‘OS::Nova::Server’ resources associated with the ‘{vm-type}’. - -R-22838 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘name’ parameter **MUST NOT** be enumerated -in the Heat Orchestration Template’s Environment File. - -If a VNF’s Heat Orchestration Template’s contains more than three -OS::Nova::Server resources of a given {vm-type}, the comma_delimited_list -form of the parameter name (i.e., ‘{vm-type}_names’) should be used to -minimize the number of unique parameters defined in the template. - - -*Example: Parameter Definition* - -.. code-block:: python - - parameters: - - {vm-type}_names: - type: comma_delimited_list - description: VM Names for {vm-type} VMs - - {vm-type}_name_{index}: - type: string - description: VM Name for {vm-type} VM {index} - -*Example: comma_delimited_list* - -In this example, the {vm-type} has been defined as “lb” for load balancer. - -.. code-block:: python - - parameters: - - lb_names: - type: comma_delimited_list - description: VM Names for lb VMs - - resources: - lb_server_0: - type: OS::Nova::Server - properties: - name: { get_param: [lb_names, 0] } - ... - - lb_server_1: - type: OS::Nova::Server - properties: - name: { get_param: [lb_names, 1] } - ... - -*Example: fixed-index* - -In this example, the {vm-type} has been defined as “lb” for load balancer. - -.. code-block:: python - - parameters: - - lb_name_0: - type: string - description: VM Name for lb VM 0 - - lb_name_1: - type: string - description: VM Name for lb VM 1 - - resources: - - lb_server_0: - type: OS::Nova::Server - properties: - name: { get_param: lb_name_0 } - ... - - lb_server_1: - type: OS::Nova::Server - properties: - name: { get_param: lb_name_1 } - ... - -Contrail Issue with Values for OS::Nova::Server Property Name -_____________________________________________________________ - -R-44271 The VNF's Heat Orchestration Template's Resource -'OS::Nova::Server' property 'name' parameter value **SHOULD NOT** -contain special characters since the Contrail GUI has a limitation -displaying special characters. - -However, if special characters must be used, the only special characters -supported are: - ---- \" ! $ ' (\ \ ) = ~ ^ | @ ` { } [ ] > , . _ - - -Property: availability\_zone -++++++++++++++++++++++++++++ - -R-98450 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘availability_zone’ parameter name -**MUST** follow the naming convention ‘availability\_zone\_{index}’ -where the ‘{index}’ **MUST** start at zero and increment by one. - -R-23311 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘availability_zone’ parameter **MUST** -be declared as type: ‘string’. - -The parameter must not be declared as type ‘comma_delimited_list’, -ONAP does not support it. - -R-59568 The VNF’s Heat Orchestration Template’s Resource -‘OS::Nova::Server’ property ‘availability_zone’ parameter **MUST NOT** -be enumerated in the Heat Orchestration Template’s Environment File. - -Example Parameter Definition - -.. code-block:: python - - parameters: - availability_zone_{index}: - type: string - description: availability zone {index} name - -Requirement R-90279 states that a VNF Heat Orchestration’s template’s -parameter MUST be used in a resource with the exception of the parameters -for the OS::Nova::Server resource property availability_zone. - -R-01359 A VNF’s Heat Orchstration Template that contains an -‘OS::Nova:Server’ Resource **MAY** define a parameter for the property -‘availability_zone’ that is not utilized in any ‘OS::Nova::Server’ -resources in the Heat Orchestration Template. - -Example -+++++++ - -The example below depicts part of a Heat Orchestration Template that -uses the four OS::Nova::Server properties discussed in this section. - -In the Heat Orchestration Template below, four Virtual -Machines (OS::Nova::Server) are created: two dns servers with -{vm-type} set to “dns” and two oam servers with {vm-type} set to “oam”. -Note that the parameter associated with the property name is a -comma_delimited_list for dns and a string for oam. - -.. code-block:: python - - parameters: - - dns_image_name: - type: string - description: dns server image - - dns_flavor_name: - type: string - description: dns server flavor - - dns_names: - type: comma_delimited_list - description: dns server names - - oam_image_name: - type: string - description: oam server image - - oam_flavor_name: - type: string - description: oam server flavor - - oam_name_0: - type: string - description: oam server name 0 - - oam_name_1: - type: string - description: oam server name 1 - - availability_zone_0: - type: string - description: availability zone ID or Name - - availability_zone_1: - type: string - description: availability zone ID or Name - - resources: - - dns_server_0: - type: OS::Nova::Server - properties: - name: { get_param: [ dns_names, 0 ] } - image: { get_param: dns_image_name } - flavor: { get_param: dns_flavor_name } - availability_zone: { get_param: availability_zone_0 } - - . . . - - dns_server_1: - type: OS::Nova::Server - properties: - name: { get_param: [ dns_names, 1 ] } - image: { get_param: dns_image_name } - flavor: { get_param: dns_flavor_name } - availability_zone: { get_param: availability_zone_1 } - - . . . - - oam_server_0: - type: OS::Nova::Server - properties: - name: { get_param: oam_name_0 } - image: { get_param: oam_image_name } - flavor: { get_param: oam_flavor_name } - availability_zone: { get_param: availability_zone_0 } - - . . . - - oam_server_1: - type: OS::Nova::Server - properties: - name: { get_param: oam_name_1 } - image: { get_param: oam_image_name } - flavor: { get_param: oam_flavor_name } - availability_zone: { get_param: availability_zone_1 } - - . . . - -Boot Options -++++++++++++ - -R-99798 A VNF’s Heat Orchestration Template’s Virtual Machine -(i.e., OS::Nova::Server Resource) **MAY** boot from an image or **MAY** -boot from a Cinder Volume. - -R-83706 When a VNF’s Heat Orchestration Template’s Virtual Machine -(i.e., ‘OS::Nova::Server’ Resource) boots from an image, the -‘OS::Nova::Server’ resource property ‘image’ **MUST** be used. - -The requirements associated with -the 'image' property are detailed in `Property: image`_ - -R-69588 When a VNF’s Heat Orchestration Template’s Virtual Machine -(i.e., ‘OS::Nova::Server’ Resource) boots from Cinder Volume, the -‘OS::Nova::Server’ resource property ‘block_device_mapping’ or -‘block_device_mapping_v2’ **MUST** be used. - -There are currently no heat guidelines -associated with these two properties: -'block_device_mapping' and 'block_device_mapping_v2'. - -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. - -R-37437 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource **MUST** contain the metadata map value parameter ‘vnf_id’. - -R-07507 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vnf_id’ **MUST** be declared -as type: ‘string’. - -R-55218 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vnf_id’ **MUST NOT** have -parameter contraints defined. - -R-20856 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. - -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. - - -*Example 'vnf_id' Parameter Definition* - -.. code-block:: python - - 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. - -R-71493 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource **MUST** contain the metadata map value parameter -‘vf\_module\_id’. - -R-82134 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vf\_module\_id’ **MUST** -be declared as type: ‘string’. - -R-98374 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vf\_module\_id’ **MUST NOT** -have parameter contraints defined. - -R-72871 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. - -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. - -*Example 'vf\_module\_id' Parameter Definition* - -.. code-block:: python - - 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 - -R-72483 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource **MUST** contain the metadata map value parameter -‘vnf_name’. - -R-62428 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vnf_name’ **MUST** be -declared as type: ‘string’. - -R-44318 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vnf_name’ **MUST NOT** have -parameter contraints defined. - -R-36542 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. - -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. - -*Example 'vnf_name' Parameter Definition* - -.. code-block:: python - - 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. - -R-68023 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource **SHOULD** contain the metadata map value parameter -‘vf\_module\_name’. - -R-39067 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vf\_module\_name’ **MUST** -be declared as type: ‘string’. - -R-15480 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vf\_module\_name’ -**MUST NOT** have parameter contraints defined. - -R-80374 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. - -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. - -*Example 'vf_module_name' Parameter Definition* - -.. code-block:: python - - 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. - -R-85328 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource **MAY** contain the metadata map value parameter ‘vm_role’. - -R-95430 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vm_role’ **MUST** be -declared as type: ‘string’. - -R-67597 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vm_role’ **MUST NOT** have -parameter contraints defined. - -R-46823 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 - -R-86476 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 ‘_’. - -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. - - -*Example 'vm_role' Parameter Definition* - -.. code-block:: python - - 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:: python - - 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:: python - - 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:: python - - 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 -+++++++++++++++++ - -R-50816 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource **MAY** contain the metadata map value parameter -‘vf\_module\_index’. - -R-54340 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vf\_module\_index’ **MUST** be -declared as type: ‘number’. - -R-09811 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘vf\_module\_index’ **MUST NOT** -have parameter contraints defined. - -R-37039 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. - -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. - -R-55306 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:: python - - 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:: python - - 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 -++++++++++++++++ - -R-47061 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource **SHOULD** contain the metadata map value parameter -‘workload_context’. - -R-74978 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘workload_context’ **MUST** be -declared as type: ‘string’. - -R-34055 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘workload_context’ **MUST NOT** -have parameter contraints defined. - -R-02691 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. - -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. - -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:: python - - parameters: - workload_context: - type: string - description: Workload Context for this VNF instance - - -*Example OS::Nova::Server with metadata* - -.. code-block:: python - - 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 -+++++++++++++++++++ - -R-88536 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource **SHOULD** contain the metadata map value parameter -‘environment_context’. - -R-20308 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘environment_context’ **MUST** -be declared as type: ‘string’. - -R-56183 A VNF’s Heat Orchestration Template’s OS::Nova::Server -Resource metadata map value parameter ‘environment_context’ **MUST NOT** -have parameter contraints defined. - -R-13194 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. - -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. - -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:: python - - parameters: - environment_context: - type: string - description: Environment Context for this VNF instance - - -*Example OS::Nova::Server with metadata* - -.. code-block:: python - - 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 } - - -Resource: OS::Neutron::Port - Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The resource OS::Neutron::Port is for managing Neutron ports (See -https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Port.) - -Introduction -++++++++++++ - -Four properties of the resource OS::Neutron::Port that must follow the -ONAP parameter naming convention. The four properties are: - -1. network -2. fixed_ips, ip_address -3. fixed_ips, subnet_id or fixed_ips, subnet - - * Note that in many examples in this document fixed_ips, subnet_id is used. - -4. allowed_address_pairs, ip_address - -Below is a generic example. Note that for some parameters -comma_delimited_list are supported in addition to String. - -.. code-block:: python - - resources: - - ... - - <resource ID>: - type: OS::Neutron::Port - properties: - allowed_address_pairs: [{"ip_address": String, "mac_address": String}, - {"ip_address": String, "mac_address": String}, ...] - fixed_ips: [{"ip_address": String, "subnet_id": String, "subnet": - String}, {"ip_address": String, "subnet_id": String, "subnet": String}, - ...] - network: String - -The parameters associated with these properties may reference an -external network or internal network. External networks and internal -networks are defined in `Networking`_. - -When the OS::Neutron::Port is attaching to an external network, all -property values are parameters that are retrieved via the intrinsic -function 'get_param'. - -When the OS::Neutron::Port is attaching to an internal network, a -property value maybe retrieved via the intrinsic -function 'get_param', 'get_resource', or 'get_attr'. - -This will be described in the forth coming sections. - -Items to Note -_____________ - -A network (internal or external) may contain one or or more subnets. - -A VNF can have one or more ports connected to the same network. - -A port can have one or more IP addresses assigned. - -The IP address assignments can be IPv4 addresses and/or IPv6 addresses. - -The IP addresses assignments for a unique external network **MUST** -be all Cloud Assigned addresses OR **MUST** be all ONAP -SDN-C assigned IP addresses. - -If the IP addresses are Cloud Assigned, all the IPv4 Addresses **MUST** -be from -the same subnet and all the IPv6 Addresses **MUST** be from the -same subnet. - -If the IP addresses are ONAP SDN-C assigned, -the IPv4 Addresses **MAY** -be from -different subnets and the IPv6 Addresses **MAY** be from different -subnets. - -If a VNF's Port is attached to an external network the IP addresses **MAY** -either be assigned by - - 1. ONAP's SDN-Controller (SDN-C) - 2. Cloud Assigned by OpenStack’s DHCP Service - -If a VNF's Port is attached to an external network and the port's IP addresses -are assigned by ONAP's SDN-Controller, the 'OS::Neutron::Port' Resource's - - * property 'fixed_ips' map property 'ip_address' **MUST** be used - * property 'fixed_ips' map property 'subnet'/'subnet_id' **MUST NOT** be used - -If a VNF's Port is attached to an external network and the port's IP addresses -are Cloud Assigned by OpenStack’s DHCP Service, -the 'OS::Neutron::Port' Resource's - - * property 'fixed_ips' map property 'ip_address' **MUST NOT** be used - * property fixed_ips' map property 'subnet'/'subnet_id' **MAY** be used - -If a VNF's Port is attached to an internal network and the port's IP addresses -are assigned by the VNF's Heat Orchestration Template -(i.e., enumerated in the Heat Orchestration Template's environment file), -the 'OS::Neutron::Port' Resource's - - * property 'fixed_ips' map property 'ip_address' **MUST** be used - * property 'fixed_ips' map property 'subnet'/'subnet_id' - **MUST NOT** be used - -If a VNF's Port is attached to an internal network and the port's IP addresses -are Cloud Assigned by OpenStack’s DHCP Service, -the 'OS::Neutron::Port' Resource's - - * property 'fixed_ips' map property 'ip_address' **MUST NOT** be used - * property 'fixed_ips' map property 'subnet'/'subnet_id' **MAY** be used - -If a VNF's Heat Orchestration Template 'OS::Neutron::Port' Resource property -'fixed_ips' map property 'ip_address' is specified, then the -'fixed_ips' map property 'subnet'/'subnet_id' **MUST NOT** -be specified. - -If a VNF's Heat Orchestration Template 'OS::Neutron::Port' Resource property -'fixed_ips' map property 'subnet'/'subnet_id' is specified, then the -'fixed_ips' map property 'ip_address' **MUST NOT** -be specified. - -.. csv-table:: **Table 4 OS::Nova::Server Resource Property Parameter Naming Convention** - :header: Resource,Property,Parameter Type,Parameter Name,Parameter Value Provided to Heat - :align: center - :widths: auto - - OS::Nova::Server, image, string, {vm-type}_image_name, Environment File - -Property: network -+++++++++++++++++ - -The Resource 'OS::Neutron::Port' property 'network' determines what network -the port is attached to. - - -R-18008 The VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’ -property ‘network’ parameter **MUST** be declared as type: ‘string’. - -R-62983 When the VNF’s Heat Orchestration Template’s -Resource ‘OS::Neutron::Port’ is attaching to an external network, -the ‘network’ parameter name **MUST** - -- follow the naming convention ‘{network-role}_net_id’ if the Neutron - network UUID value is used to reference the network -- follow the naming convention ‘{network-role}_net_name’ if the OpenStack - network name is used to reference the network. - -where ‘{network-role}’ is the network-role of the external network and -a ‘get_param’ **MUST** be used as the intrinsic function. - -R-86182 When the VNF’s Heat Orchestration Template’s -Resource ‘OS::Neutron::Port’ is attaching to an internal network, -and the internal network is created in a different -Heat Orchestration Template than the ‘OS::Neutron::Port’, the ‘network’ -parameter name **MUST** - -- follow the naming convention ‘int\_{network-role}_net_id’ if the Neutron - network UUID value is used to reference the network -- follow the naming convention ‘int\_{network-role}_net_name’ if the - OpenStack network name in is used to reference the network. - -where ‘{network-role}’ is the network-role of the internal network -and a ‘get_param’ **MUST** be used as the intrinsic function. - -In Requirement R-86182, the internal network is created in the VNF's -Base Module (Heat Orchestration Template) and the parameter name is -declared in the Base Module's outputs' section. -The output parameter name will be declared as a parameter in the -'parameters' section of the incremental module. - -R-93177 When the VNF’s Heat Orchestration Template’s -Resource ‘OS::Neutron::Port’ is attaching to an internal -network, and the internal network is created in the same Heat -Orchestration Template than the ‘OS::Neutron::Port’, the ‘network’ -parameter name **MUST** obtain the UUID of the internal network -by using the intrinsic function ‘get_resource’ or ‘get_attr’ -and referencing the Resource ID of the internal network. - -R-29872 The VNF’s Heat Orchestration Template’s Resource ‘OS::Nova::Server’ -property ‘network’ parameter **MUST NOT** be enumerated in the Heat -Orchestration Template’s Environment File. - -The parameter values for external networks are provided by ONAP -to the VNF's Heat Orchestration Template at orchestration time. - -The parameter values for internal networks created in the VNF's Base Module -Heat Orchestration Template -are provided to the VNF's Incremental Module Heat Orchestration Template -at orchestration time. - -*Example Parameter Definition of External Networks* - -.. code-block:: python - - parameters: - - {network-role}_net_id: - type: string - description: Neutron UUID for the external {network-role} network - - {network-role}_net_name: - type: string - description: Neutron name for the external {network-role} network - - -*Example Parameter Definition of Internal Networks in an Incremental Module* - -.. code-block:: python - - parameters: - - int_{network-role}_net_id: - type: string - description: Neutron UUID for the internal int_{network-role} network - - int_{network-role}_net_name: - type: string - description: Neutron name for the internal int_{network-role} network - -Property: fixed_ips, Map Property: ip_address -+++++++++++++++++++++++++++++++++++++++++++++ - -The resource 'OS::Neutron::Port' property 'fixed_ips' -map property 'ip_address' -is used to assign one IPv4 or IPv6 -addresses to port. - -One 'OS::Neutron::Port' resource may assign one or more -IPv4 and/or IPv6 addresses. - -R-34037 The VNF’s Heat Orchestration Template’s resource ‘OS::Neutron::Port’ -property ‘fixed_ips’ map property ‘ip_address’ parameter **MUST** -be declared as either type ‘string’ or type ‘comma_delimited_list’. - -R-40971 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ is attaching to an external network, and an IPv4 address is -assigned using the property -‘fixed_ips’ map property ‘ip_address’ and the parameter type is defined -as a string, the parameter name **MUST** follow the naming -convention ‘{vm-type}_{network-role}\_ip\_{index}’, where - -- ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server -- ‘{network-role}’ is the {network-role} of the external network -- the value for {index} must start at zero (0) and increment by one - -R-39841 The VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’ -property ‘fixed_ips’ map property ‘ip_address’ parameter -‘{vm-type}_{network-role}\_ip\_{index}’ **MUST NOT** be enumerated in the -VNF’s Heat Orchestration Template’s Environment File. - -ONAP's SDN-Controller assigns the IP Address and ONAP provides -the value at orchestration to the Heat Orchestration Template. - -*Example External Network IPv4 Address string Parameter Definition* - -.. code-block:: python - - parameters: - - {vm-type}_{network-role}_ip_{index}: - type: string - description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network - -R-04697 When the VNF’s Heat Orchestration Template’s -Resource ‘OS::Neutron::Port’ is attaching to an external -network, and an IPv4 address is assigned using the property -‘fixed_ips’ map property ‘ip_address’ and the parameter type -is defined as a comma_delimited_list, the parameter name **MUST** -follow the naming convention ‘{vm-type}_{network-role}_ips’, -where - -- ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server -- ‘{network-role}’ is the {network-role} of the external network - -R-98905 The VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’ -property ‘fixed_ips’ map property ‘ip_address’ parameter -‘{vm-type}_{network-role}_ips’ **MUST NOT** be enumerated in the VNF’s -Heat Orchestration Template’s Environment File. - -ONAP's SDN-Controller assigns the IP Address and ONAP provides -the value at orchestration to the Heat Orchestration Template. - -*Example External Network IPv4 Address comma_delimited_list -Parameter Definition* - -.. code-block:: python - - parameters: - - {vm-type}_{network-role}_ips: - type: comma_delimited_list - description: Fixed IPv4 assignments for {vm-type} VMs on the {network-role} network - -R-71577 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ is attaching to an external network, and an IPv6 address -is assigned using the property ‘fixed_ips’ map property ‘ip_address’ and -the parameter type is defined as a string, the parameter name **MUST** follow -the naming convention ‘{vm-type}_{network-role}\_v6\_ip\_{index}’, where - -- ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server -- ‘{network-role}’ is the {network-role} of the external network -- the value for {index} must start at zero (0) and increment by one - - -R-87123 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’ -parameter ‘{vm-type}_{network-role}\_v6\_ip\_{index}’ -**MUST NOT** be enumerated in the VNF’s Heat Orchestration -Template’s Environment File. - -ONAP's SDN-Controller assigns the IP Address and ONAP provides -the value at orchestration to the Heat Orchestration Template. - -*Example External Network IPv6 Address string Parameter Definition* - -.. code-block:: python - - parameters: - - {vm-type}_{network-role}_v6_ip_{index}: - type: string - description: Fixed IPv6 assignment for {vm-type} VM {index} on the {network-role} network - -R-23503 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ is attaching to an external network, and an IPv6 -address is assigned using the property ‘fixed_ips’ map property ‘ip_address’ -and the parameter type is defined as a comma_delimited_list, the parameter -name **MUST** follow the naming convention -‘{vm-type}_{network-role}_v6_ips’, where - -- ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server -- ‘{network-role}’ is the {network-role} of the external network - -R-93030 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’ -parameter ‘{vm-type}_{network-role}_v6_ips’ **MUST NOT** be enumerated in the -VNF’s Heat Orchestration Template’s Environment File. - -ONAP's SDN-Controller assigns the IP Address and ECOMP provides -the value at orchestration to the Heat Orchestration Template. - -*Example External Network IPv6 Address comma_delimited_list Parameter -Definition* - -.. code-block:: python - - parameters: - - {vm-type}_{network-role}_v6_ips: - type: comma_delimited_list - description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network - -R-78380 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ is attaching to an internal network, and an IPv4 address -is assigned using the property ‘fixed_ips’ map property ‘ip_address’ and -the parameter type is defined as a string, the parameter name **MUST** follow -the naming convention ‘{vm-type}\_int\_{network-role}\_ip\_{index}’, where - -- ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server -- ‘{network-role}’ is the {network-role} of the internal network -- the value for {index} must start at zero (0) and increment by one - -R-28795 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’ -parameter ‘{vm-type}\_int\_{network-role}\_ip\_{index}’ **MUST** be enumerated -in the VNF’s Heat Orchestration Template’s Environment File. - -The IP address is local to the VNF's internal network and is (re)used -in every VNF spin up, thus the constant value is declared in the VNF's -Heat Orchestration Template's Environment File. - -*Example Internal Network IPv4 Address string Parameter Definition* - -.. code-block:: python - - parameters: - - {vm-type}_int_{network-role}_ip_{index}: - type: string - description: Fixed IPv4 assignment for {vm-type} VM {index} on the int_{network-role} network - -R-85235 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ is attaching to an internal network, and an IPv4 -address is assigned using the property ‘fixed_ips’ map property ‘ip_address’ -and the parameter type is defined as a comma_delimited_list, the parameter -name **MUST** follow the naming convention -‘{vm-type}\_int\_{network-role}_ips’, where - -- ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server -- ‘{network-role}’ is the {network-role} of the internal network - -R-90206 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’ -parameter ‘{vm-type}\_int\_{network-role}_int_ips’ **MUST** be enumerated in -the VNF’s Heat Orchestration Template’s Environment File. - -The IP address is local to the VNF's internal network and is (re)used -in every VNF spin up, thus the constant value is declared in the VNF's -Heat Orchestration Template's Environment File. - -.. code-block:: python - - parameters: - - {vm-type}_int_{network-role}_ips: - type: comma_delimited_list - description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network - -R-27818 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ is attaching to an internal network, and an IPv6 address -is assigned using the property ‘fixed_ips’ map property ‘ip_address’ and -the parameter type is defined as a string, the parameter name **MUST** follow -the naming convention ‘{vm-type}\_int\_{network-role}\_v6\_ip\_{index}’, where - -- ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server -- ‘{network-role}’ is the {network-role} of the internal network -- the value for {index} must start at zero (0) and increment by one - -R-97201 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’ -parameter ‘{vm-type}\_int\_{network-role}\_v6\_ip\_{index}’ -**MUST** be enumerated in the VNF’s Heat Orchestration -Template’s Environment File. - -The IP address is local to the VNF's internal network and is (re)used -in every VNF spin up, thus the constant value is declared in the VNF's -Heat Orchestration Template's Environment File. - -*Example Internal Network IPv6 Address string Parameter Definition* - -.. code-block:: python - - parameters: - - {vm-type}_int_{network-role}_v6_ip_{index}: - type: string - description: Fixed IPv6 assignment for {vm-type} VM {index} on the int_{network-role} network - -R-29765 When the VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ is attaching to an internal network, and an IPv6 -address is assigned using the property ‘fixed_ips’ map property ‘ip_address’ -and the parameter type is defined as a comma_delimited_list, the parameter -name **MUST** follow the naming convention -‘{vm-type}\_int\_{network-role}_v6_ips’, where - -- ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server -- ‘{network-role}’ is the {network-role} of the internal network - -*Example Internal Network IPv6 Address comma_delimited_list Parameter -Definition* - -.. code-block:: python - - parameters: - - {vm-type}_int_{network-role}_v6_ips: - type: comma_delimited_list - description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network - -R-98569 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’ -parameter ‘{vm-type}\_int\_{network-role}_v6_ips’ **MUST** be enumerated in -the VNF’s Heat Orchestration Template’s Environment File. - -The IP address is local to the VNF's internal network and is (re)used -in every VNF spin up, thus the constant value is declared in the VNF's -Heat Orchestration Template's Environment File. - -R-62590 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’ -parameter associated with an external network, i.e., - -- {vm-type}_{network-role}\_ip\_{index} -- {vm-type}_{network-role}\_ip\_v6\_{index} -- {vm-type}_{network-role}_ips -- {vm-type}_{network-role}_v6_ips - -**MUST NOT** be enumerated in the Heat Orchestration Template’s -Environment File. ONAP provides the IP address assignments at -orchestration time. - -R-93496 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’ -parameter associated with an internal network, i.e., - -- {vm-type}\_int\_{network-role}\_ip\_{index} -- {vm-type}\_int\_{network-role}\_ip\_v6\_{index} -- {vm-type}\_int\_{network-role}_ips -- {vm-type}\_int\_{network-role}_v6_ips - -**MUST** be enumerated in the Heat Orchestration Template’s Environment -File and IP addresses **MUST** be assigned. - -Summary Table -_____________ - -.. csv-table:: **Table # OS::Neutron::Port Property fixed_ips map property ip_address Parameter Naming Convention** - :header: Resource,Property,Map Property,Network Type,IP Address,Parameter Type,Parameter Name, Environment File - :align: center - :widths: auto - - OS::Neutron::Port, fixed_ips, ip_address, external, IPv4, string, {vm-type}\_{network-role}\_ip\_{index}, NO - OS::Neutron::Port, fixed_ips, ip_address, external, IPv4, comma\_delimited\_list, {vm-type}\_{network-role}\_ips, NO - OS::Neutron::Port, fixed_ips, ip_address, external, IPv6, string, {vm-type}\_{network-role}\_v6\_ip\_{index}, NO - OS::Neutron::Port, fixed_ips, ip_address, external, IPv6, comma\_delimited\_list, {vm-type}\_{network-role}\_v6\_ips, NO - OS::Neutron::Port, fixed_ips, ip_address, internal, IPv4, string, {vm-type}\_int\_{network-role}\_ip\_{index}, YES - OS::Neutron::Port, fixed_ips, ip_address, internal, IPv4, comma\_delimited\_list, {vm-type}\_int\_{network-role}\_ips, YES - OS::Neutron::Port, fixed_ips, ip_address, internal, IPv6, string, {vm-type}\_int\_{network-role}\_v6\_ip\_{index}, YES - OS::Neutron::Port, fixed_ips, ip_address, internal, IPv6, comma\_delimited\_list, {vm-type}\_int\_{network-role}\_v6\_ips, YES - - -Examples -________ - -*Example: comma_delimited_list parameters for IPv4 and IPv6 Address -Assignments to an external network* - -In this example, the '{network-role}' has been defined as 'oam' to represent -an oam network and the '{vm-type}' has been defined as 'db' for database. - -.. code-block:: python - - parameters: - oam_net_id: - type: string - description: Neutron UUID for a oam network - db_oam_ips: - type: comma_delimited_list - description: Fixed IPv4 assignments for db VMs on the oam network - db_oam_v6_ips: - type: comma_delimited_list - description: Fixed IPv6 assignments for db VMs on the oam network - resources: - db_0_oam_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: [ db_oam_ips, 0 ]}}, { - “ip_address”: {get_param: [ db_oam_v6_ips, 0 ]}}] - db_1_oam_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: - - “ip_address”: {get_param: [ db_oam_ips, 1 ]} - - “ip_address”: {get_param: [ db_oam_v6_ips, 1 ]} - -*Example: string parameters for IPv4 and IPv6 Address Assignments to an -external network* - -In this example, the '{network-role}' has been defined as 'oam' to -represent an oam network and the '{vm-type}' has been defined as 'db' for -database. - -.. code-block:: python - - parameters: - oam_net_id: - type: string - description: Neutron UUID for an OAM network - db_oam_ip_0: - type: string - description: Fixed IPv4 assignment for db VM 0 on the OAM network - db_oam_ip_1: - type: string - description: Fixed IPv4 assignment for db VM 1 on the OAM network - db_oam_v6_ip_0: - type: string - description: Fixed IPv6 assignment for db VM 0 on the OAM network - db_oam_v6_ip_1: - type: string - description: Fixed IPv6 assignment for db VM 1 on the OAM network - resources: - db_0_oam_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: db_oam_ip_0}}, { “ip_address”: {get_param: db_oam_v6_ip_0 ]}}] - db_1_oam_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: - - “ip_address”: {get_param: db_oam_ip_1}}] - - “ip_address”: {get_param: db_oam_v6_ip_1}}] - - -*Example: comma_delimited_list parameters for IPv4 and IPv6 Address -Assignments to an internal network* - -In this example, the '{network-role}' has been defined as 'ctrl' to -represent an ctrl network internal to the vnf. -The '{vm-type}' has been defined as 'db' for -database. - -.. code-block:: python - - parameters: - int_ctrl_net_id: - type: string - description: Neutron UUID for the ctrl internal network - db_int_ctrl_ips: - type: comma_delimited_list - description: Fixed IPv4 assignments for db VMs on the ctrl internal - network - db_int_ctrl_v6_ips: - type: comma_delimited_list - description: Fixed IPv6 assignments for db VMs on the ctrl internal - network - resources: - db_0_int_ctrl_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: int_ctrl_net_id } - fixed_ips: [ { “ip_address”: {get_param: [ db_int_ctrl_ips, 0 ]}}, { - “ip_address”: {get_param: [ db_int_ctrl_v6_ips, 0 ]}}] - db_1_int_ctrl_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: int_ctrl_net_id } - fixed_ips: - - “ip_address”: {get_param: [ db_int_ctrl_ips, 1 ]} - - “ip_address”: {get_param: [ db_int_ctrl_v6_ips, 1 ]} - - -*Example: string parameters for IPv4 and IPv6 Address Assignments to an -internal network* - -In this example, the int\_{network-role} has been defined as -int_ctrl to represent a control network internal to the vnf. -The {vm-type} has been defined as db for database. - -.. code-block:: python - - parameters: - int_ctrl_net_id: - type: string - description: Neutron UUID for an OAM internal network - db_int_ctrl_ip_0: - type: string - description: Fixed IPv4 assignment for db VM on the oam_int network - db_int_ctrl_ip_1: - type: string - description: Fixed IPv4 assignment for db VM 1 on the oam_int network - db_int_ctrl_v6_ip_0: - type: string - description: Fixed IPv6 assignment for db VM 0 on the oam_int network - db_int_ctrl_v6_ip_1: - type: string - description: Fixed IPv6 assignment for db VM 1 on the oam_int network - resources: - db_0_int_ctrl_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: int_oam_int_net_id } - fixed_ips: [ { “ip_address”: {get_param: db_oam_int_ip_0}}, { - “ip_address”: {get_param: db_oam_int_v6_ip_0 ]}}] - db_1_int_ctrl_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: int_oam_int_net_id } - fixed_ips: - - “ip_address”: {get_param: db_oam_int_ip_1}}] - - “ip_address”: {get_param: db_oam_int_v6_ip_1}}] - - -Property: fixed\_ips, Map Property: subnet\_id -++++++++++++++++++++++++++++++++++++++++++++++ - -The resource 'OS::Neutron::Port' property 'fixed_ips' map -property 'subnet'/'subnet_id' is used when a -port is requesting an IP assignment via -OpenStack’s DHCP Service (i.e., Cloud Assigned). - -The IP address assignment will be made from the specified subnet. - -Specifying the subnet is not required; it is optional. - -If the network (external or internal) that the port is attaching -to only contains one subnet, specifying the subnet is -superfluous. The IP address will be assigned from the one existing -subnet. - -If the network (external or internal) that the port is attaching -to contains two or more subnets, specifying the subnet in the -'fixed_ips' map property 'subnet'/'subnet_id' determines which -subnet the IP address will be assigned from. - -If the network (external or internal) that the port is attaching -to contains two or more subnets, and the subnet is not is not -specified, OpenStack will randomly(?) determine which subnet -the IP address will be assigned from. - -The property fixed_ips is used to assign IPs to a port. The Map Property -subnet_id specifies the subnet the IP is assigned from. - -R-38236 The VNF’s Heat Orchestration Template’s resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property -‘subnet’/’subnet_id’ parameter **MUST** be declared type ‘string’. - -R-62802 When the VNF’s Heat Orchestration Template’s resource -‘OS::Neutron::Port’ is attaching to an external network, and an IPv4 -address is being Cloud Assigned by OpenStack’s DHCP Service and the -external network IPv4 subnet is to be specified using the property -‘fixed_ips’ map property ‘subnet’/’subnet_id’, the parameter **MUST** -follow the naming convention ‘{network-role}_subnet_id’, where -‘{network-role}’ is the network role of the network. - -R-83677 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property -subnet’/’subnet_id’ parameter ‘{network-role}_subnet_id’ -**MUST NOT** be enumerated in the VNF’s Heat Orchestration Template’s -Environment File. - -ONAP's SDN-Controller provides the network's subnet's UUID -value at orchestration to the Heat Orchestration Template. - -*Example Parameter Definition* - -.. code-block:: python - - parameters: - - {network-role}_subnet_id: - type: string - description: Neutron IPv4 subnet UUID for the {network-role} network - -R-15287 When the VNF’s Heat Orchestration Template’s resource -‘OS::Neutron::Port’ is attaching to an external network, and an IPv6 -address is being Cloud Assigned by OpenStack’s DHCP Service and the -external network IPv6 subnet is to be specified using the property -‘fixed_ips’ map property ‘subnet’/’subnet_id’, the parameter **MUST** -follow the naming convention ‘{network-role}_subnet_v6_id’, where -‘{network-role}’ is the network role of the network. - -R-80829 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property -subnet’/’subnet_id’ parameter ‘{network-role}_subnet_v6_id’ -**MUST NOT** be enumerated in the VNF’s Heat Orchestration Template’s -Environment File. - -ONAP's SDN-Controller provides the network's subnet's UUID -value at orchestration to the Heat Orchestration Template. - -*Example Parameter Definition* - -.. code-block:: python - - parameters: - - {network-role}_v6_subnet_id: - type: string - description: Neutron IPv6 subnet UUID for the {network-role} network - - -*Example: One Cloud Assigned IPv4 Address (DHCP) assigned to a network -that has two or more IPv4 subnets* - -In this example, the '{network-role}' has been defined as 'oam' to represent -an oam network and the '{vm-type}' has been defined as 'lb' for load -balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service -to assign IP addresses. - -.. code-block:: python - - parameters: - oam_net_id: - type: string - description: Neutron UUID for the oam network - oam_subnet_id: - type: string - description: Neutron IPv4 subnet UUID for the oam network - resources: - lb_0_oam_port_0: - type: OS::Neutron::Port - parameters: - network: { get_param: oam_net_id } - fixed_ips: - - subnet_id: { get_param: oam_subnet_id } - -*Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6 -address assigned to a network that has at least one IPv4 subnet and one -IPv6 subnet* - -In this example, the '{network-role}' has been defined as 'oam' to represent -an oam network and the '{vm-type}' has been defined as 'lb' for load -balancer. - -.. code-block:: python - - parameters: - oam_net_id: - type: string - description: Neutron UUID for the oam network - oam_subnet_id: - type: string - description: Neutron IPv4 subnet UUID for the oam network - oam_v6_subnet_id: - type: string - description: Neutron IPv6 subnet UUID for the oam network - resources: - lb_0_oam_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: - - subnet_id: { get_param: oam_subnet_id } - - subnet_id: { get_param: oam_v6_subnet_id } - -R-84123 When - -- the VNF’s Heat Orchestration Template’s resource ‘OS::Neutron::Port’ - in an Incremental Module is attaching to an internal network - that is created in the Base Module, AND -- an IPv4 address is being Cloud Assigned by OpenStack’s DHCP Service AND -- the internal network IPv4 subnet is to be specified using the - property ‘fixed_ips’ map property ‘subnet’/’subnet_id’, - -the parameter **MUST** follow the naming convention -‘int\_{network-role}_subnet_id’, where ‘{network-role}’ is the -network role of the internal network - -- Note that the parameter **MUST** be defined as an ‘output’ parameter in - the base module. - -R-69634 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property -subnet’/’subnet_id’ parameter ‘int\_{network-role}_subnet_id’ -**MUST NOT** be enumerated in the VNF’s Heat Orchestration Template’s -Environment File. - -The assumption is that internal networks are created in the base module. -The Neutron subnet network ID will be passed as an output parameter -(e.g., ECOMP Base Module Output Parameter) to the incremental modules. -In the incremental modules, the output parameter name will be defined as -input parameter. - -*Example Parameter Definition* - -.. code-block:: python - - parameters: - - int_{network-role}_subnet_id: - type: string - description: Neutron IPv4 subnet UUID for the int_{network-role} network - -R-76160 When - -- the VNF’s Heat Orchestration Template’s resource - ‘OS::Neutron::Port’ in an Incremental Module is attaching to an - internal network that is created in the Base Module, AND -- an IPv6 address is being Cloud Assigned by OpenStack’s DHCP Service AND -- the internal network IPv6 subnet is to be specified using the property - ‘fixed_ips’ map property ‘subnet’/’subnet_id’, - -the parameter **MUST** follow the naming convention -‘int\_{network-role}_v6_subnet_id’, where ‘{network-role}’ -is the network role of the internal network - -- Note that the parameter **MUST** be defined as an ‘output’ parameter in - the base module. - -R-22288 The VNF’s Heat Orchestration Template’s Resource -‘OS::Neutron::Port’ property ‘fixed_ips’ map property -‘subnet’/’subnet_id’ parameter ‘int\_{network-role}_v6_subnet_id’ -**MUST NOT** be enumerated in the VNF’s Heat Orchestration Template’s -Environment File. - -*Example Parameter Definition* - -.. code-block:: python - - parameters: - - int_{network-role}_v6_subnet_id: - type: string - description: Neutron subnet UUID for the int_{network-role} network - - -Property: allowed\_address\_pairs, Map Property: ip\_address -+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The property allowed\_address\_pairs in the resource OS::Neutron::Port -allows the user to specify a mac\_address and/or ip\_address that will -pass through a port regardless of subnet. This enables the use of -protocols such as VRRP, which floats an IP address between two instances -to enable fast data plane failover. The map property ip\_address -specifies the IP address. - -The allowed\_address\_pairs is an optional property. It is not required. - -An ONAP Heat Orchestration Template allows the assignment of one IPv4 -address allowed\_address\_pairs and/or one IPv6 address to a {vm-type} -and {network-role}/int\_{network-role} combination. - -An ONAP Heat Orchestration Template allows the assignment of one IPv6 -address allowed\_address\_pairs and/or one IPv6 address to a {vm-type} -and {network-role}/int\_{network-role} combination. - -Note that the management of these IP addresses (i.e. transferring -ownership between active and standby VMs) is the responsibility of the -application itself. - -Note that these parameters are **not** intended to represent Neutron -“Floating IP” resources, for which OpenStack manages a pool of public IP -addresses that are mapped to specific VM ports. In that case, the -individual VMs are not even aware of the public IPs, and all assignment -of public IPs to VMs is via OpenStack commands. ONAP does not support -Neutron-style Floating IPs. - -External Networks -_________________ - -R-61282 The VNF Heat Orchestration Template **MUST** -adhere to the following naming convention for the property -allowed\_address\_pairs and Map Property ip\_address parameter, -when the parameter is referencing an “external” network: - -- {vm-type}\_{network-role}\_floating\_ip for an IPv4 address - -- {vm-type}\_{network-role}\_floating\_v6\_ip for an IPv6 address - -The parameter must be declared as type: string - -The parameter must not be enumerated in the Heat environment file. - -*Example Parameter Definition* - -.. code-block:: yaml - - parameters: - - {vm-type}_{network-role}_floating_ip: - type: string - description: VIP for {vm-type} VMs on the {network-role} network - - {vm-type}_{network-role}_floating_v6_ip: - type: string - description: VIP for {vm-type} VMs on the {network-role} network - -*Example:* - -In this example, the {network-role} has been defined as oam to represent -an oam network and the {vm-type} has been defined as db for database. - -.. code-block:: yaml - - parameters: - oam_net_id: - type: string - description: Neutron UUID for the oam network - - db_oam_ips: - type: comma_delimited_list - description: Fixed IPs for db VMs on the oam network - - db_oam_floating_ip: - type: string - description: VIP IP for db VMs on the oam network - - resources: - db_0_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,0] }}] - allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}] - - db_1_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,1] }}] - allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}] - -Internal Networks -_________________ - -R-16805 The VNF Heat Orchestration Template **MUST** adhere to the -following naming convention for the property allowed\_address\_pairs -and Map Property ip\_address parameter when the parameter is -referencing an “internal” network. - -- {vm-type}\_int\_{network-role}\_floating\_ip for an IPv4 address - -- {vm-type}\_int\_{network-role}\_floating\_v6\_ip for an IPv6 address - -The parameter must be declared as type: string - -The parameter must be enumerated in the Heat environment file. - -*Example Parameter Definition* - -.. code-block:: yaml - - parameters: - - {vm-type}_int_{network-role}_floating_ip: - type: string - description: VIP for {vm-type} VMs on the int_{network-role} network - - {vm-type}_int_{network-role}_floating_v6_ip: - type: string - description: VIP for {vm-type} VMs on the int_{network-role} network - -Multiple allowed\_address\_pairs for a {vm-type} / {network-role} combination -______________________________________________________________________________ - -The parameter {vm-type}\_{network-role}\_floating\_ip provides only one -allowed address pair IPv4 address per {vm-type} and {network-role} pair. - -The parameter {vm-type}\_{network-role}\_floating\_v6\_ip provides only -one allowed address pair IPv6 address per {vm-type} and {network-role} -pair. - -If there is a need for multiple allowed address pair IPs for a given -{vm-type} and {network-role} combination within a VNF, then the -parameter names defined for the property fixed\_ips and Map Property -ip\_address should be used with the allowed\_address\_pairs property. -The examples below illustrate this. - -*Example: A VNF has four load balancers. Each pair has a unique VIP.* - -In this example, there are two administrative VM pairs. Each pair has -one VIP. The {network-role} has been defined as oam to represent an oam -network and the {vm-type} has been defined as admin for an -administrative VM. - -Pair 1: Resources admin\_0\_port\_0 and admin\_1\_port\_0 share a unique -VIP, [admin\_oam\_ips,2] - -Pair 2: Resources admin\_2\_port\_0 and admin\_3\_port\_0 share a unique -VIP, [admin\_oam\_ips,5] - -.. code-block:: yaml - - parameters: - oam_net_id: - type: string - description: Neutron UUID for the oam network - admin_oam_ips: - type: comma_delimited_list - description: Fixed IP assignments for admin VMs on the oam network - - resources: - - admin_0_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,0] }}] - allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}] - - admin_1_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,1] }}] - allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}] - - admin_2_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,3] }}] - allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}] - - admin_3_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,4] }}] - allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}] - -*Example: A VNF has two load balancers. The pair of load balancers share -two VIPs.* - -In this example, there is one load balancer pairs. The pair has two -VIPs. The {network-role} has been defined as oam to represent an oam -network and the {vm-type} has been defined as lb for a load balancer VM. - -.. code-block:: yaml - - resources: - lb_0_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,0] }}] - allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}] - - lb_1_port_0: - type: OS::Neutron::Port - properties: - network: { get_param: oam_net_id } - fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,1] }}] - allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}] - -As a general rule, provide the fixed IPs for the VMs indexed first in -the CDL and then the VIPs as shown in the examples above. - -ONAP SDN-C Assignment of allowed\_address\_pair IP Addresses -__________________________________________________________________ - -The following items must be taken into consideration when designing Heat -Orchestration Templates that expect ONAP’s SDN-C to assign -allowed\_address\_pair IP addresses via automation. - -The VMs must be of the same {vm-type}. - -The VMs must be created in the same module (base or incremental). - -Resource Property “name” -~~~~~~~~~~~~~~~~~~~~~~~~ - -The parameter naming convention of the property name for the resource -OS::Nova::Server has been defined in -`Resource: OS::Nova::Server – Metadata Parameters`_. - -This section provides the requirements how the property name for non -OS::Nova::Server resources must be defined when the property is used. -Not all resources require the property name (e.g., it is optional) and -some resources do not support the property. - -R-85734 The VNF Heat Orchestration Template **MUST** use the -intrinsic function str\_replace in conjunction with the ONAP -supplied metadata parameter vnf\_name to generate a unique -value, when the property name for a non OS::Nova::Server -resources is defined in a Heat Orchestration Template. - -This prevents the enumeration of a -unique value for the property name in a per instance environment file. - -Note that - -- In most cases, only the use of the metadata value vnf\_name is - required to create a unique property name - -- the Heat Orchestration Template pseudo parameter 'OS::stack\_name’ - may also be used in the str\_replace construct to generate a unique - name when the vnf\_name does not provide uniqueness - -*Example: Property* name *for resource* OS::Neutron::SecurityGroup - -.. code-block:: yaml - - resources: - DNS_SECURITY_GROUP: - type: OS::Neutron::SecurityGroup - properties: - description: vDNS security group - name: - str_replace: - template: VNF_NAME_sec_grp_DNS - params: - VNF_NAME: {get_param: vnf_name} - rules: [. . . . . - ] - -*Example: Property name for resource* OS::Cinder::Volume - -.. code-block:: yaml - - resources: - DNS_Cinder_Volume: - type: OS::Cinder::Volume - properties: - description: Cinder Volume - name: - str_replace: - template: VNF_NAME_STACK_NAME_dns_volume - params: - VNF_NAME: {get_param: vnf_name} - STACK_NAME: { get_param: 'OS::stack_name' } - . . . . - -Contrail Issue with Values for the Property Name -++++++++++++++++++++++++++++++++++++++++++++++++ - -The Contrail GUI has a limitation displaying special characters. The -issue is documented in -https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is -recommended that special characters be avoided. However, if special -characters must be used, note that for the following resources: - -- Virtual Machine - -- Virtual Network - -- Port - -- Security Group - -- Policies - -- IPAM Creation - -the only special characters supported are: - -- “ ! $ ‘ ( ) = ~ ^ \| @ \` { } [ ] > , . \_ - -ONAP Output Parameter Names -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -ONAP defines three types of Output Parameters as detailed in -`Output Parameters`_. - -ONAP Base Module Output Parameters: -+++++++++++++++++++++++++++++++++++ - -ONAP Base Module Output Parameters do not have an explicit naming -convention. The parameter name must contain {vm-type} and {network-role} -when appropriate. - -ONAP Volume Template Output Parameters: -+++++++++++++++++++++++++++++++++++++++ - -ONAP Base Module Output Parameters do not have an explicit naming -convention. The parameter name must contain {vm-type} when appropriate. - -Predefined Output Parameters -++++++++++++++++++++++++++++ - -ONAP currently defines one predefined output parameter the OAM -Management IP Addresses. - -OAM Management IP Addresses -___________________________ - -A VNF may have a management interface for application controllers to -interact with and configure the VNF. Typically, this will be via a -specific VM that performs a VNF administration function. The IP address -of this interface must be captured and inventoried by ONAP. The IP -address might be a VIP if the VNF contains an HA pair of management VMs, -or may be a single IP address assigned to one VM. - -The Heat template may define either (or both) of the following Output -parameters to identify the management IP address. - -- oam\_management\_v4\_address - -- oam\_management\_v6\_address - -*Notes*: - -- The use of this output parameters are optional. - -- The Management IP Address should be defined only once per VNF, so it - must only appear in one Module template - -- If a fixed IP for the admin VM is passed as an input parameter, it - may be echoed in the output parameters. In this case, a IPv4 and/or - IPv6 parameter must be defined in the parameter section of the YAML - Heat template. The parameter maybe named oam\_management\_v4\_address - and/or oam\_management\_v6\_address or may be named differently. - -- If the IP for the admin VM is obtained via DHCP, it may be obtained - from the resource attributes. In this case, - oam\_management\_v4\_address and/or oam\_management\_v6\_address must - not be defined in the parameter section of the YAML Heat template. - -*Example: SDN-C Assigned IP Address echoed as* -oam\_management\_v4\_address - -.. code-block:: yaml - - parameters: - admin_oam_ip_0: - type: string - description: Fixed IPv4 assignment for admin VM 0 on the OAM network - . . . - - resources: - admin_oam_net_0_port: - type: OS::Neutron::Port - properties: - name: - str_replace: - template: VNF_NAME_admin_oam_net_0_port - params: - VNF_NAME: {get_param: vnf_name} - network: { get_param: oam_net_id } - fixed_ips: [{ "ip_address": { get_param: admin_oam_ip_0 }}] - security_groups: [{ get_param: security_group }] - - admin_server: - type: OS::Nova::Server - properties: - name: { get_param: admin_names } - image: { get_param: admin_image_name } - flavor: { get_param: admin_flavor_name } - availability_zone: { get_param: availability_zone_0 } - networks: - - port: { get_resource: admin_oam_net_0_port } - metadata: - vnf_id: { get_param: vnf_id } - vf_module_id: { get_param: vf_module_id } - vnf_name: {get_param: vnf_name } - Outputs: - oam_management_v4_address: - value: {get_param: admin_oam_ip_0 } - -*Example: Cloud Assigned IP Address output as* -oam\_management\_v4\_address - -.. code-block:: yaml - - parameters: - . . . - resources: - admin_oam_net_0_port: - type: OS::Neutron::Port - properties: - name: - str_replace: - template: VNF_NAME_admin_oam_net_0_port - params: - VNF_NAME: {get_param: vnf_name} - network: { get_param: oam_net_id } - security_groups: [{ get_param: security_group }] - - admin_server: - type: OS::Nova::Server - properties: - name: { get_param: admin_names } - image: { get_param: admin_image_name } - flavor: { get_param: admin_flavor_name } - availability_zone: { get_param: availability_zone_0 } - networks: - - port: { get_resource: admin_oam_net_0_port } - metadata: - vnf_id: { get_param: vnf_id } - vf_module_id: { get_param: vf_module_id } - vnf_name: {get_param: vnf_name } - - Outputs: - oam_management_v4_address: - value: {get_attr: [admin_server, networks, {get_param: oam_net_id}, 0] } - -Contrail Resource Parameters -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -ONAP requires the parameter names of certain Contrail Resources to -follow specific naming conventions. This section provides these -requirements. - -Contrail Network Parameters -+++++++++++++++++++++++++++ - -Contrail based resources may require references to a Contrail network -using the network FQDN. - -External Networks -_________________ - -When the parameter associated with the Contrail Network is referencing -an “external” network, the parameter must adhere to the following naming -convention in the Heat Orchestration Template - -- {network-role}\_net\_fqdn - -The parameter must be declared as type: string - -The parameter must not be enumerated in the Heat environment file. - -*Example: Parameter declaration* - -.. code-block:: yaml - - parameters: - {network-role}_net_fqdn: - type: string - description: Contrail FQDN for the {network-role} network - -*Example: Contrail Resource OS::ContrailV2::VirtualMachineInterface -Reference to a Network FQDN.* - -In this example, the {network-role} has been defined as oam to represent -an oam network and the {vm-type} has been defined as fw for firewall. -The Contrail resource OS::ContrailV2::VirtualMachineInterface property -virtual\_network\_refs references a contrail network FQDN. - -.. code-block:: yaml - - FW_OAM_VMI: - type: OS::ContrailV2::VirtualMachineInterface - properties: - name: - str_replace: - template: VM_NAME_virtual_machine_interface_1 - params: - VM_NAME: { get_param: fw_name_0 } - virtual_machine_interface_properties: - virtual_machine_interface_properties_service_interface_type: { get_param: oam_protected_interface_type } - virtual_network_refs: - - get_param: oam_net_fqdn - security_group_refs: - - get_param: fw_sec_grp_id - -Interface Route Table Prefixes for Contrail InterfaceRoute Table -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -The parameter associated with the resource -OS::ContrailV2::InterfaceRouteTable property -interface\_route\_table\_routes, map property -interface\_route\_table\_routes\_route\_prefix is an ONAP Orchestration -Parameter. - -The parameters must be named {vm-type}\_{network-role}\_route\_prefixes -in the Heat Orchestration Template. - -The parameter must be declared as type: json - -The parameter supports IP addresses in the format: - -1. Host IP Address (e.g., 10.10.10.10) - -2. CIDR Notation format (e.g., 10.0.0.0/28) - -The parameter must not be enumerated in the Heat environment file. - -*Example Parameter Definition* - -.. code-block:: yaml - - parameters: - {vm-type}_{network-role}_route_prefixes: - type: json - description: JSON list of Contrail Interface Route Table route prefixes - -*Example:* - -.. code-block:: yaml - - parameters: - vnf_name: - type: string - description: Unique name for this VF instance - fw_int_fw_route_prefixes: - type: json - description: prefix for the ServiceInstance InterfaceRouteTable - int_fw_dns_trusted_interface_type: - type: string - description: service_interface_type for ServiceInstance - - <resource name>: - type: OS::ContrailV2::InterfaceRouteTable - depends_on: [*resource name of* *OS::ContrailV2::ServiceInstance*] - properties: - name: - str_replace: - template: VNF_NAME_interface_route_table - params: - VNF_NAME: { get_param: vnf_name } - interface_route_table_routes: - interface_route_table_routes_route: { get_param: fw_int_fw_route_prefixes } - service_instance_refs: - - get_resource: < *resource name of* *OS::ContrailV2::ServiceInstance* > - service_instance_refs_data: - - service_instance_refs_data_interface_type: { get_param: int_fw_interface_type } - -Parameter Names in Contrail Resources -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Contrail Heat resource properties will use, when appropriate, the same -naming convention as OpenStack Heat resources. For example, the resource -OS::ContrailV2::InstanceIp has two properties that the parameter naming -convention is identical to properties in OS::Neutron::Port. - -*Example: Contrail Resource OS::ContrailV2::InstanceIp, Property -instance\_ip\_address* - -The property instance\_ip\_address uses the same parameter naming -convention as the property fixed\_ips and Map Property ip\_address in -OS::Neutron::Port. The resource is assigning an ONAP SDN-C Assigned IP -Address. The {network-role} has been defined as oam\_protected to -represent an oam protected network and the {vm-type} has been defined as -fw for firewall. - -.. code-block:: yaml - - CMD_FW_OAM_PROTECTED_RII: - type: OS::ContrailV2::InstanceIp - depends_on: - - FW_OAM_PROTECTED_RVMI - properties: - virtual_machine_interface_refs: - - get_resource: FW_OAM_PROTECTED_RVMI - virtual_network_refs: - - get_param: oam_protected_net_fqdn - instance_ip_address: { get_param: [fw_oam_protected_ips, get_param: index ] } - -*Example: Contrail Resource OS::ContrailV2::InstanceIp, Property -subnet\_uuid* - -The property instance\_ip\_address uses the same parameter naming -convention as the property fixed\_ips and Map Property subnet\_id in -OS::Neutron::Port. The resource is assigning a Cloud Assigned IP -Address. The {network-role} has been defined as “oam\_protected” to -represent an oam protected network and the {vm-type} has been defined as -“fw” for firewall. - -.. code-block:: yaml - - CMD_FW_SGI_PROTECTED_RII: - type: OS::ContrailV2::InstanceIp - depends_on: - - FW_OAM_PROTECTED_RVMI - properties: - virtual_machine_interface_refs: - - get_resource: FW_OAM_PROTECTED_RVMI - virtual_network_refs: - - get_param: oam_protected_net_fqdn - subnet_uuid: { get_param: oam_protected_subnet_id } - -Cinder Volume Templates -^^^^^^^^^^^^^^^^^^^^^^^^ - -ONAP supports the independent deployment of a Cinder volume via separate -Heat Orchestration Templates, the Cinder Volume module. This allows the -volume to persist after VNF deletion so that they can be reused on -another instance (e.g., during a failover activity). - -A Base Module or Incremental Module may have a corresponding volume -module. Use of separate volume modules is optional. A Cinder volume may -be embedded within the Base Module or Incremental Module if persistence -is not required. - -R-47788 The VNF Heat Orchestration Template **MUST** have a 1:1 -scope of a cinder volume module, when it exists, with the -Base Module or Incremental Module - -A single volume module must create only the volumes -required by a single Incremental module or Base module. - -The following rules apply to independent volume Heat templates: - -- Cinder volumes must be created in a separate Heat Orchestration - Template from the Base Module or Incremental Module. - -- A single Cinder volume module must include all Cinder volumes - needed by the Base/Incremental module. - -- R-79531 The VNF Heat Orchestration Template **MUST** define - “outputs” in the volume template for each Cinder volume - resource universally unique identifier (UUID) (i.e. ONAP - Volume Template Output Parameters). - -- The VNF Incremental Module or Base Module must define input - parameters that match each Volume output parameter (i.e., ONAP Volume - Template Output Parameters). - - - ONAP will supply the volume template outputs automatically to the - bases/incremental template input parameters. - -- Volume modules may utilize nested Heat templates. - -*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 -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 - -incremental\_volume.yaml - -.. code-block:: yaml - - parameters: - vnf_name: - type: string - lb_volume_size_0: - type: number - ... - - 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} - ... - - -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 } - -ONAP Support of Environment Files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The use of an environment file in OpenStack is optional. In ONAP, it is -mandatory. - -R-86285 The VNF Heat Orchestration Template **MUST** have a -corresponding environment file, even if no parameters are required to be -enumerated. - -(Note that ONAP, the open source version of ONAP, does not -programmatically enforce the use of an environment file.) - -R-67205 The VNF Heat Orchestration Template **MUST** have a corresponding -environment file for a Base Module. - -R-35727 The VNF Heat Orchestration Template **MUST** have a -corresponding environment file for an Incremental module. - -R-22656 The VNF Heat Orchestration Template **MUST** have a -corresponding environment file for a Cinder Volume Module. - -A nested heat template must not have an environment file; OpenStack does -not support it. - -The environment file must contain parameter values for the ONAP -Orchestration Constants and VNF Orchestration Constants. These -parameters are identical across all instances of a VNF type, and -expected to change infrequently. The ONAP Orchestration Constants are -associated with OS::Nova::Server image and flavor properties (See -`Property: image`_ and `Property: flavor`_). Examples of VNF -Orchestration Constants are the networking parameters associated -with an internal network (e.g., private IP ranges) and Cinder -volume sizes. - -The environment file must not contain parameter values for parameters -that are instance specific (ONAP Orchestration Parameters, VNF -Orchestration Parameters). These parameters are supplied to the Heat by -ONAP at orchestration time. - -SDC Treatment of Environment Files -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Parameter values enumerated in the environment file are used by SDC as -the default value. However, the SDC user may use the SDC GUI to -overwrite the default values in the environment file. - -SDC generates a new environment file for distribution to MSO based on -the uploaded environment file and the user provided GUI updates. The -user uploaded environment file is discarded when the new file is -created. Note that if the user did not change any values via GUI -updates, the SDC generated environment file will contain the same values -as the uploaded file. - -Use of Environment Files when using OpenStack “heat stack-create” CLI -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When ONAP is instantiating the Heat Orchestration Template, certain -parameter must not be enumerated in the environment file. This document -provides the details of what parameters should not be enumerated. - -If the Heat Orchestration Template is to be instantiated from the -OpenStack Command Line Interface (CLI) using the command “heat -stack-create”, all parameters must be enumerated in the environment -file. - -Heat Template Constructs -^^^^^^^^^^^^^^^^^^^^^^^^^ - -Nested Heat Templates -~~~~~~~~~~~~~~~~~~~~~ - -ONAP supports nested Heat templates per the OpenStack specifications. -Nested templates may be suitable for larger VNFs that contain many -repeated instances of the same VM type(s). A common usage pattern is to -create a nested template for each {vm-type} along with its supporting -resources. The VNF module may then reference these component templates -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. - -A Heat Orchestration Template may reference the nested heat statically -by repeated definition. - -A Heat Orchestration Template may reference the nested heat dynamically -using the resource OS::Heat::ResourceGroup. - -A Heat Orchestration template must have no more than three levels of -nesting. ONAP supports a maximum of three levels. - -Nested heat templates must be referenced by file name. The use of -resource\_registry in the environment file is not supported and must not -be used. - -R-89868 The VNF Heat Orchestration Template **MUST** have unique -file names within the scope of the VNF for a nested heat yaml file. - -R-52530 The VNF Heat Orchestration Template **MUST NOT** use a -directory hierarchy for nested templates. All templates must -be in a single, flat directory (per VNF). - -A nested heat template may be used by any module within a given VNF. - -Note that: - -- Constrains must not be defined for any parameter enumerated in a - nested heat template. - -- R-11041 The VNF Heat Orchestration Template **MUST** have the - resource calling the nested yaml file pass in as properties - all parameters defined in nested yaml file. - -- R-61183 The VNF Heat Orchestration Template **MUST NOT** - change the parameter names, when OS::Nova::Server metadata - parameters are past into a nested heat template. - -- 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. - -Nested Heat Template Example: Static -++++++++++++++++++++++++++++++++++++++ - -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} - -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 } - -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 -example, a set of identical OS::Nova::Server resources plus their -related OS::Neutron::Port resources via a single resource in a master -template. - -ResourceGroup may be used in ONAP to simplify the structure of a Heat -template that creates multiple instances of the same VM type. - -However, there are important caveats to be aware of: - -ResourceGroup does not deal with structured parameters -(comma-delimited-list and json) as one might typically expect. In -particular, when using a list-based parameter, where each list element -corresponds to one instance of the ResourceGroup, it is not possible to -use the intrinsic “loop variable” %index% in the ResourceGroup -definition. - -For instance, the following is **not** valid Heat for ResourceGroup: - -.. code-block:: yaml - - type: OS::Heat::ResourceGroup - 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 ResourceGroup, it will in fact result in a -Heat exception. When parameters are provided as a list (one for each -element of a ResourceGroup), you must pass the complete parameter to the -nested template along with the current index as separate parameters. - -Below is an example of an **acceptable** Heat Syntax for a -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% - -You can then reference within the nested template as: - -{ get\_param: [names, {get\_param: index} ] } - -ResourceGroup Property count -____________________________ - -ONAP requires that the OS::Heat::ResourceGroup property count be defined -(even if the value is one) and that the value must be enumerated in the -environment file. 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 - -Availability Zone and ResourceGroups -____________________________________ - -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 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. - -.. 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 } ] ] } - -In the nested heat - -.. code-block:: yaml - - parameters: - avaialability_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 ] } - - -**Option 2:** Create a resource group per availability zone. A separate -OS::Heat::ResourceGroup is created for each availability zone. - -External References -~~~~~~~~~~~~~~~~~~~ - -Heat templates *should 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 - from external/untrusted/unknown sources. - -- VNF images should not contain such 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. - -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 -example, to define a common “user-data” script, or to inject files into -a VM on startup via the “personality” property. - -Support for Heat Files is subject to the following limitations: - -R-76718 The VNF Heat Orchestration Template **MUST** reference -the get\_files targets in Heat templates by file name, and the -corresponding files should be delivered to ONAP along with the -Heat templates. - -R-41888 The VNE Heat **MUST NOT** use URL-based file retrieval. - -R-62177 The VNF Heat Orchestration Template **MUST** have unique -file names for the included files within the scope of the VNF. - -R-87848 The VNF Heat Orchestration Template **MUST** have all -included files in a single, flat directory per VNF. ONAP does -not support a directory hierarchy. - -- Included files may be used by all Modules within a given VNF. - -- get\_file directives may be used in both non-nested and nested - templates - -Key Pairs -~~~~~~~~~ - -When Nova Servers are created via Heat templates, they may be passed a -“keypair” which provides an ssh key to the ‘root’ login on the newly -created VM. This is often done so that an initial root key/password does -not need to be hard-coded into the image. - -Key pairs are unusual in OpenStack, because they are the one resource -that is owned by an OpenStack User as opposed to being owned by an -OpenStack Tenant. As a result, they are usable only by the User that -created the keypair. This causes a problem when a Heat template attempts -to reference a keypair by name, because it assumes that the keypair was -previously created by a specific ONAP user ID. - -When a keypair is assigned to a server, the SSH public-key is -provisioned on the VMs at instantiation time. They keypair itself is not -referenced further by the VM (i.e. if the keypair is updated with a new -public key, it would only apply to subsequent VMs created with that -keypair). - -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 - -- Create a new keypair within The VNF Heat Orchestration Template (in the base - module) 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 -provisioned in the new VM. However, this recommended approach also makes -sure that a known public key is supplied (instead of having OpenStack -generate a public/private pair to be saved and tracked outside of ONAP). -It also removes any access/ownership issues over the created keypair. - -The public keys may be enumerated as a VNF Orchestration Constant in the -environment file (since it is public, it is not a secret key), or passed -at run-time as instance-specific parameters. ONAP will never -automatically assign a public/private key pair. - -*Example (create keypair with an existing ssh public-key for {vm-type} -of lb (for load balancer)):* - -.. code-block:: yaml - - parameters: - vnf_name: - type: string - lb_ssh_public_key: - 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 - -Security Groups -~~~~~~~~~~~~~~~ - -OpenStack allows a tenant to create Security groups and define rules -within the security groups. - -Security groups, with their rules, may either be created in the Heat -Orchestration Template or they can be pre-created in OpenStack and -referenced within the Heat template via parameter(s). There can be a -different approach for security groups assigned to ports on internal -(intra-VNF) networks or external networks (inter-VNF). Furthermore, -there can be a common security group across all VMs for a specific -network or it can vary by VM (i.e., {vm-type}) and network type (i.e., -{network-role}). - -Anti-Affinity and Affinity Rules -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Anti-affinity or affinity rules are supported using normal OpenStack -OS::Nova::ServerGroup resources. Separate ServerGroups are typically -created for each VM type to prevent them from residing on the same host, -but they can be applied to multiple VM types to extend the -affinity/anti-affinity across related VM types as well. - -*Example:* - -In this example, the {network-role} has been defined as oam to represent -an oam network and the {vm-type} have been defined as lb for load -balancer and db for database. - -.. code-block:: yaml - - 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: - 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} - -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 - - - Assures that one resource completes before the dependent resource - is orchestrated. - - - Definition of completeness to OpenStack may not be sufficient - (e.g., a VM is considered complete by OpenStack when it is ready - to be booted, not when the application is up and running). - -- Use of Heat Notifications - - - Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle - resources. - - - Pre-requisite resources issue *wc\_notify* commands in user\_data. - - - Dependent resource define depends\_on in the - OS::Heat::WaitCondition resource. - -*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 -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} - -High Availability -^^^^^^^^^^^^^^^^^ - -VNF/VM parameters may include availability zone IDs for VNFs that -require high availability. - -The Heat must comply with the following requirements to specific -availability zone IDs: - -- The Heat template should spread Nova and Cinder resources across the - availability zones as desired - -Post Orchestration & VNF Configuration -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Heat templates should contain a minimum amount of post-orchestration -configuration data. For instance, *do not* embed complex user-data -scripts in the template with large numbers of configuration parameters -to the Heat template. - -- VNFs may provide configuration APIs for use after VNF creation. Such - APIs will be invoked via application and/or SDN controllers. - -*Note:* It is important to follow this convention to the extent possible -even in the short-term as of the long-term direction. - -VNFM Driver Development Steps ------------------------------------------------------------ - -Refer to the ONAP documentation for VNF Provider instructions on integrating -vendor-specific VNFM adaptors with VF-C. The VNF driver development steps are -highlighted below. - -1. Use the VNF SDK tools to design the VNF with TOSCA models to output -the VNF TOSCA package. Using the VNF SDK tools, the VNF package can be -validated and tested. - -2. The VNF Provider supplies a vendor-specific VNFM driver in ONAP, which -is a microservice providing a translation interface from VF-C to -the vendor-specific VNFM. The interface definitions of vendor-specific -VNFM adaptors are supplied by the VNF Providers themselves. - -Creating Vendor-Specific VNFM Adaptor Microservices ------------------------------------------------------------------------------------------------- - -VNFs can be managed by vendor-specific VNFMs. To add a vendor-specific -VNFM to ONAP, a vendor-specific VNFM adaptor is added to ONAP implementing -the interface of the vendor-specific VNFM. - -A vendor-specific VNFM adaptor is a microservice with a unique name and -an appointed port. When started up, the vendor-specific VNFM adaptor -microservice is automatically registered to the Microservices Bus (MSB). -The following RESTful example describes the scenario of registering a -vendor-specific VNFM adaptor to MSB: - -.. code-block:: java - - POST /api/microservices/v1/services - { - "serviceName": "catalog", - "version": "v1", - "url": "/api/catalog/v1", - "protocol": "REST", - "visualRange": "1", - "nodes": [ - { - "ip": "10.74.56.36", - "port": "8988", - "ttl": 0 - } - ] - } |