1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3 .. Copyright 2017 AT&T Intellectual Property. All rights reserved.
6 **VNF Modeling Requirements**
7 =====================================
10 ----------------------
16 This reference document is the VNF TOSCA Template Requirements for
17 ONAP, which provides recommendations and standards for building VNF
18 TOSCA templates compatible with ONAP initial implementations of
19 Network Cloud. It has the following features:
21 1. VNF TOSCA template designer supports GUI and CLI.
23 2. VNF TOSCA template is aligned to the newest TOSCA protocol, “Working
24 Draft 04-Revision 06”.
26 3. VNF TOSCA template supports EPA features, such as NUMA, Hyper
27 Threading, SRIOV, etc.
32 This document is intended for persons developing VNF TOSCA templates
33 that will be orchestrated by ONAP.
38 ONAP implementations of Network Cloud supports TOSCA Templates, also
39 referred to as TOSCA in this document.
41 ONAP requires the TOSCA Templates to follow a specific format. This
42 document provides the mandatory, recommended, and optional requirements
43 associated with this format.
48 The document includes three charters to help the VNF providers to use the
49 VNF model design tools and understand the VNF package structure and VNF
52 In the ONAP, VNF Package and VNFD template can be designed by manually
53 or via model designer tools. VNF model designer tools can provide the
54 GUI and CLI tools for the VNF provider to develop the VNF Package and VNFD
57 The VNF package structure is align to the NFV TOSCA protocol, and
60 The VNFD and VNF package are all align to the NFV TOSCA protocol, which
61 supports multiple TOSCA template yaml files, and also supports
62 self-defined node or other extensions.
67 TOSCA templates supported by ONAP must follow the requirements
68 enumerated in this section.
73 TOSCA defines a Meta model for defining IT services. This Meta model
74 defines both the structure of a service as well as how to manage it. A
75 Topology Template (also referred to as the topology model of a service)
76 defines the structure of a service. Plans define the process models that
77 are used to create and terminate a service as well as to manage a
78 service during its whole lifetime.
80 A Topology Template consists of a set of Node Templates and Relationship
81 Templates that together define the topology model of a service as a (not
82 necessarily connected) directed graph. A node in this graph is
83 represented by a *Node Template*. A Node Template specifies the
84 occurrence of a Node Type as a component of a service. A *Node Type*
85 defines the properties of such a component (via *Node Type Properties*)
86 and the operations (via *Interfaces*) available to manipulate the
87 component. Node Types are defined separately for reuse purposes and a
88 Node Template references a Node Type and adds usage constraints, such as
89 how many times the component can occur.
93 Figure 1: Structural Elements of Service Template and their Relations
95 TOSCA Modeling Principles & Data Model
96 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98 This section describing TOSCA modeling principles and data model for
99 NFV, which shall be based on [TOSCA-1.0] and [TOSCA-Simple-Profile-YAML
100 V1.0], or new type based on ETSI NFV requirements, etc.
102 VNF Descriptor Template
103 ^^^^^^^^^^^^^^^^^^^^^^^^
105 The VNF Descriptor (VNFD) describes the topology of the VNF by means of
106 ETSI NFV IFA011 [IFA011] terms such as VDUs, Connection Points, Virtual
107 Links, External Connection Points, Scaling Aspects, Instantiation Levels
108 and Deployment Flavours.
110 The VNFD (VNF Descriptor) is read by both the NFVO and the VNFM. It
111 represents the contract & interface of a VNF and ensures the
112 interoperability across the NFV functional blocks.
114 The main parts of the VNFD are the following:
116 - VNF topology: it is modeled in a cloud agnostic way using virtualized
117 containers and their connectivity. Virtual Deployment Units (VDU)
118 describe the capabilities of the virtualized containers, such as
119 virtual CPU, RAM, disks; their connectivity is modeled with VDU
120 Connection Point Descriptors (VduCpd), Virtual Link Descriptors (Vld)
121 and VNF External Connection Point Descriptors (VnfExternalCpd);
123 - VNF deployment aspects: they are described in one or more deployment
124 flavours, including instantiation levels, supported LCM operations,
125 VNF LCM operation configuration parameters, placement constraints
126 (affinity / antiaffinity), minimum and maximum VDU instance numbers,
127 and scaling aspect for horizontal scaling.
129 The following table defines the TOSCA Type “derived from” values that
130 SHALL be used when using the TOSCA Simple Profile for NFV version 1.0
131 specification [TOSCA-Simple-Profile-NFV-v1.0] for NFV VNFD.
133 +-----------------------------------------+---------------------------------------+-----------------------+
134 | **ETSI NFV Element** | **TOSCA VNFD** | **Derived from** |
136 | **[IFA011]** | **[TOSCA-Simple-Profile-NFV-v1.0]** | |
137 +=========================================+=======================================+=======================+
138 | VNF | tosca.nodes.nfv.VNF | tosca.nodes.Root |
139 +-----------------------------------------+---------------------------------------+-----------------------+
140 | VDU | tosca.nodes.nfv.VDU | tosca.nodes.Root |
141 +-----------------------------------------+---------------------------------------+-----------------------+
142 | Cpd (Connection Point) | tosca.nodes.nfv.Cpd | tosca.nodes.Root |
143 +-----------------------------------------+---------------------------------------+-----------------------+
144 | VduCpd (internal connection point) | tosca.nodes.nfv.VduCpd | tosca.nodes.nfv.Cpd |
145 +-----------------------------------------+---------------------------------------+-----------------------+
146 | VnfVirtualLinkDesc (Virtual Link) | tosca.nodes.nfv.VnfVirtualLinkDesc | tosca.nodes.Root |
147 +-----------------------------------------+---------------------------------------+-----------------------+
148 | VnfExtCpd (External Connection Point) | tosca.nodes.nfv.VnfExtCpd | tosca.nodes.Root |
149 +-----------------------------------------+---------------------------------------+-----------------------+
150 | Virtual Storage | | |
151 +-----------------------------------------+---------------------------------------+-----------------------+
152 | Virtual Compute | | |
153 +-----------------------------------------+---------------------------------------+-----------------------+
154 | Software Image | | |
155 +-----------------------------------------+---------------------------------------+-----------------------+
156 | Deployment Flavour | | |
157 +-----------------------------------------+---------------------------------------+-----------------------+
158 | Scaling Aspect | | |
159 +-----------------------------------------+---------------------------------------+-----------------------+
160 | Element Group | | |
161 +-----------------------------------------+---------------------------------------+-----------------------+
162 | Instantiation Level | | |
163 +-----------------------------------------+---------------------------------------+-----------------------+
165 +--------------------------------------------------------------------+
166 | +--------------------------------------------------------------+ |
167 | | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 | |
169 | | description: VNFD TOSCA file demo | |
173 | | - TOSCA\_definition\_nfv\_1\_0.yaml | |
175 | | - TOSCA\_definition\_nfv\_ext\_1\_0.yaml | |
177 | | | **node\_types: | |
178 | | tosca.nodes.nfv.VNF.vOpenNAT: | |
179 | | derived\_from:** tosca.nodes.nfv.VNF | |
180 | | | **requirements: | |
181 | | **- **sriov\_plane: | |
182 | | capability:** tosca.capabilities.nfv.VirtualLinkable | |
183 | | | **node:** tosca.nodes.nfv.VnfVirtualLinkDesc | |
184 | | | **relationship:** tosca.relationships.nfv.VirtualLinksTo | |
185 | +--------------------------------------------------------------+ |
186 +====================================================================+
187 +--------------------------------------------------------------------+
192 1. SR-IOV Passthrought
194 Definitions of SRIOV\_Port are necessary if VDU supports SR-IOV. Here is
197 +------------------------------------------------+
206 | tosca\_name: SRIOV\_Port |
210 | virtual\_network\_interface\_requirements: |
214 | support\_mandatory: false |
216 | description: sriov |
224 | description: sriov port |
226 | layer\_protocol: ipv4 |
230 | - virtual\_binding: |
232 | capability: virtual\_binding |
238 | type: tosca.relationships.nfv.VirtualBindsTo |
242 | node: tosca.nodes.Root |
244 | type: tosca.nodes.nfv.VduCpd |
246 | substitution\_mappings: |
256 | node\_type: tosca.nodes.nfv.VNF.vOpenNAT |
257 +------------------------------------------------+
261 Definitions of mem\_page\_size as one property shall be added to
262 Properties and set the value to large if one VDU node supports
263 huagepages. Here is an example.
265 +----------------------------------+
274 | tosca\_name: Huge\_pages\_demo |
278 | mem\_page\_size:large |
279 +==================================+
280 +----------------------------------+
284 Likewise, we shall add definitions of numa to
285 requested\_additional\_capabilities if we wand VUD nodes to support
286 NUMA. Here is an example.
288 +-------------------------------------------------+
289 | topology\_template: |
297 | virtual\_compute: |
303 | numa\_enabled: true |
305 | virtual\_mem\_size: 2 GB |
307 | requested\_additional\_capabilities: |
311 | support\_mandatory: true |
313 | requested\_additional\_capability\_name: numa |
315 | target\_performance\_parameters: |
317 | hw:numa\_nodes: "2" |
319 | hw:numa\_cpus.0: "0,1" |
321 | hw:numa\_mem.0: "1024" |
323 | hw:numa\_cpus.1: "2,3,4,5" |
325 | hw:numa\_mem.1: "1024" |
326 +-------------------------------------------------+
330 Definitions of Hyper-Theading are necessary as one of
331 requested\_additional\_capabilities of one VUD node if that node
332 supports Hyper-Theading. Here is an example.
334 +-------------------------------------------------------------+
335 | topology\_template: |
343 | virtual\_compute: |
349 | numa\_enabled: true |
351 | virtual\_mem\_size: 2 GB |
353 | requested\_additional\_capabilities: |
355 | hyper\_threading: |
357 | support\_mandatory: true |
359 | requested\_additional\_capability\_name: hyper\_threading |
361 | target\_performance\_parameters: |
363 | hw:cpu\_sockets : "2" |
365 | hw:cpu\_threads : "2" |
367 | hw:cpu\_cores : "2" |
369 | hw:cpu\_threads\_policy: "isolate" |
370 +-------------------------------------------------------------+
374 Definitions of ovs\_dpdk are necessary as one of
375 requested\_additional\_capabilities of one VUD node if that node
376 supports dpdk. Here is an example.
378 +------------------------------------------------------+
379 | topology\_template: |
387 | virtual\_compute: |
393 | numa\_enabled: true |
395 | virtual\_mem\_size: 2 GB |
397 | requested\_additional\_capabilities: |
401 | support\_mandatory: true |
403 | requested\_additional\_capability\_name: ovs\_dpdk |
405 | target\_performance\_parameters: |
407 | sw:ovs\_dpdk: "true" |
408 +------------------------------------------------------+
410 NFV TOSCA Type Definition
411 ^^^^^^^^^^^^^^^^^^^^^^^^
413 tosca.capabilites.nfv.VirtualCompute
414 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
416 +---------------------------+-----------------------------------------+
417 | **Shorthand Name** | VirtualCompute |
418 +===========================+=========================================+
419 | **Type Qualified Name** | tosca: VirtualCompute |
420 +---------------------------+-----------------------------------------+
421 | **Type URI** | tosca.capabilities.nfv.VirtualCompute |
422 +---------------------------+-----------------------------------------+
423 | **derived from** | tosca.nodes.Root |
424 +---------------------------+-----------------------------------------+
429 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
430 | Name | Required | Type | Constraints | Description |
431 +=====================================+============+=====================================================+===============+=========================================================+
432 | request\_additional\_capabilities | No | tosca.datatypes.nfv.RequestedAdditionalCapability | | Describes additional capability for a particular VDU. |
433 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
434 | virtual\_memory | yes | tosca.datatypes.nfv.VirtualMemory | | Describes virtual memory of the virtualized compute |
435 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
436 | virtual\_cpu | yes | tosca.datatypes.nfv.VirtualCpu | | Describes virtual CPU(s) of the virtualized compute. |
437 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
438 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
440 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
445 +-----------------------------------------------------------+
446 | tosca.capabilities.nfv.VirtualCompute: |
448 | derived\_from: tosca.capabilities.Root |
452 | requested\_additional\_capabilities: |
458 | type: tosca.datatypes.nfv.RequestedAdditionalCapability |
464 | type: tosca.datatypes.nfv.VirtualMemory |
470 | type: tosca.datatypes.nfv.VirtualCpu |
473 +-----------------------------------------------------------+
475 tosca.nodes.nfv.VDU.Compute
476 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
478 The NFV Virtualization Deployment Unit (VDU) compute node type
479 represents a VDU entity which it describes the deployment and
480 operational behavior of a VNF component (VNFC), as defined by **[ETSI
483 +-----------------------+-------------------------------+
484 | Shorthand Name | VDU.Compute |
485 +=======================+===============================+
486 | Type Qualified Name | tosca:VDU.Compute |
487 +-----------------------+-------------------------------+
488 | Type URI | tosca.nodes.nfv.VDU.Compute |
489 +-----------------------+-------------------------------+
490 | derived\_from | tosca.nodes.Compute |
491 +-----------------------+-------------------------------+
504 +-------------------------+-------------------------------------------------+---------------+-----------------------------------------------------------------------------------------------------+
505 | Name | Type | Constraints | Description |
506 +=========================+=================================================+===============+=====================================================================================================+
507 | virtual\_compute | tosca.capabilities.nfv.VirtualCompute | | Describes virtual compute resources capabilities. |
508 +-------------------------+-------------------------------------------------+---------------+-----------------------------------------------------------------------------------------------------+
509 | monitoring\_parameter | tosca.capabilities.nfv.Metric | None | Monitoring parameter, which can be tracked for a VNFC based on this VDU |
511 | | | | Examples include: memory-consumption, CPU-utilisation, bandwidth-consumption, VNFC downtime, etc. |
512 +-------------------------+-------------------------------------------------+---------------+-----------------------------------------------------------------------------------------------------+
513 | Virtual\_binding | tosca.capabilities.nfv.VirtualBindable | | Defines ability of VirtualBindable |
515 | | editor note: need to create a capability type | | |
516 +-------------------------+-------------------------------------------------+---------------+-----------------------------------------------------------------------------------------------------+
521 +-----------------------------------------------------------------------------------------------------+
522 | tosca.nodes.nfv.VDU.Compute: |
524 | derived\_from: tosca.nodes.Compute |
542 | type: list # explicit index (boot index) not necessary, contrary to IFA011 |
550 | nfvi\_constraints: |
560 | configurable\_properties: |
566 | type: tosca.datatypes.nfv.VnfcConfigurableProperties |
572 | private\_address: |
574 | status: deprecated |
578 | status: deprecated |
582 | status: deprecated |
586 | status: deprecated |
590 | virtual\_compute: |
592 | type: tosca.capabilities.nfv.VirtualCompute |
594 | virtual\_binding: |
596 | type: tosca.capabilities.nfv.VirtualBindable |
598 | #monitoring\_parameter: |
600 | # modeled as ad hoc (named) capabilities in VDU node template |
606 | # cpu\_load: tosca.capabilities.nfv.Metric |
608 | # memory\_usage: tosca.capabilities.nfv.Metric |
610 | host: #Editor note: FFS. How this capabilities should be used in NFV Profile |
612 | type: `*tosca.capabilities.Container* <#DEFN_TYPE_CAPABILITIES_CONTAINER>`__ |
614 | valid\_source\_types: [`*tosca.nodes.SoftwareComponent* <#DEFN_TYPE_NODES_SOFTWARE_COMPONENT>`__] |
616 | occurrences: [0,UNBOUNDED] |
620 | occurrences: [0,0] |
624 | occurrences: [0,0] |
626 | scalable: #Editor note: FFS. How this capabilities should be used in NFV Profile |
628 | type: `*tosca.capabilities.Scalable* <#DEFN_TYPE_CAPABILITIES_SCALABLE>`__ |
632 | occurrences: [0,UNBOUND] |
636 | - virtual\_storage: |
638 | capability: tosca.capabilities.nfv.VirtualStorage |
640 | relationship: tosca.relationships.nfv.VDU.AttachedTo |
642 | node: tosca.nodes.nfv.VDU.VirtualStorage |
644 | occurences: [ 0, UNBOUNDED ] |
646 | - local\_storage: #For NFV Profile, this requirement is deprecated. |
648 | occurrences: [0,0] |
656 | type: tosca.artifacts.nfv.SwImage |
657 +-----------------------------------------------------------------------------------------------------+
661 +-----------+------------+-------------------------------+---------------+------------------------------------------------+
662 | Name | Required | Type | Constraints | Description |
663 +===========+============+===============================+===============+================================================+
664 | SwImage | Yes | tosca.artifacts.nfv.SwImage | | Describes the software image which is |
665 | | | | | directly realizing this virtual storage |
666 +-----------+------------+-------------------------------+---------------+------------------------------------------------+
676 The TOSCA Cpd node represents network connectivity to a compute resource
677 or a VL as defined by [ETSI GS NFV-IFA 011]. This is an abstract type
678 used as parent for the various Cpd types.
680 +-----------------------+-----------------------+
681 | Shorthand Name | Cpd |
682 +=======================+=======================+
683 | Type Qualified Name | tosca:Cpd |
684 +-----------------------+-----------------------+
685 | Type URI | tosca.nodes.nfv.Cpd |
686 +-----------------------+-----------------------+
692 +--------+------------+--------+---------------+---------------+
693 | Name | Required | Type | Constraints | Description |
694 +========+============+========+===============+===============+
695 +--------+------------+--------+---------------+---------------+
710 +----------------------------------------------------------------------+
711 | tosca.nodes.nfv.Cpd: |
713 | derived\_from: tosca.nodes.Root |
723 | - valid\_values: [ethernet, mpls, odu2, ipv4, ipv6, pseudo\_wire ] |
727 | role: #Name in ETSI NFV IFA011 v0.7.3 cpRole |
733 | - valid\_values: [ root, leaf ] |
749 | type: tosca.datatype.nfv.AddressData |
752 +----------------------------------------------------------------------+
754 Additional Requirement
755 ++++++++++++++++++++++++
759 tosca.nodes.nfv.VduCpd
760 ~~~~~~~~~~~~~~~~~~~~~~
762 The TOSCA node VduCpd represents a type of TOSCA Cpd node and describes
763 network connectivity between a VNFC instance (based on this VDU) and an
764 internal VL as defined by [ETSI GS NFV-IFA 011].
766 +-----------------------+--------------------------+
767 | Shorthand Name | VduCpd |
768 +=======================+==========================+
769 | Type Qualified Name | tosca: VduCpd |
770 +-----------------------+--------------------------+
771 | Type URI | tosca.nodes.nfv.VduCpd |
772 +-----------------------+--------------------------+
778 +-------------------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
779 | Name | Required | Type | Constraints | Description |
780 +===============================+============+==========================================+==========================================================================+
781 | bitrate_requirement | no | integer | | Bitrate requirement on this connection point. |
782 +-------------------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
783 | virtual\_network\_interface_\ | no | VirtualNetworkInterfaceRequirements | | Specifies requirements on a virtual network |
784 | requirements | | | | realising the CPs instantiated from this CPD |
785 +-------------------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
795 +--------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
796 | Name | Required | Type | Constraints | Description |
797 +====================+============+==========================================+===============+==========================================================+
798 | virtual\_binding | yes | tosca.capabilities.nfv.VirtualBindable | | Describe the requirement for binding with VDU |
799 +--------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
800 | virtual\_link | no | tosca.capabilities.nfv.VirtualLinkable | | Describes the requirements for linking to virtual link |
801 +--------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
806 +----------------------------------------------------------------+
807 | tosca.nodes.nfv.VduCpd: |
809 | derived\_from: tosca.nodes.nfv.Cpd |
813 | bitrate\_requirement: |
819 | virtual\_network\_interface\_requirements |
825 | type: VirtualNetworkInterfaceRequirements |
833 | capability: tosca.capabilities.nfv.VirtualLinkable |
835 | relationship: tosca.relationships.nfv.VirtualLinksTo |
837 | node: tosca.nodes.nfv.VnfVirtualLinkDesc - virtual\_binding: |
839 | capability: tosca.capabilities.nfv.VirtualBindable |
841 | relationship: tosca.relationships.nfv.VirtualBindsTo |
843 | node: tosca.nodes.nfv.VDU |
844 +----------------------------------------------------------------+
846 tosca.nodes.nfv.VDU.VirtualStorage
847 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
849 The NFV VirtualStorage node type represents a virtual storage entity
850 which it describes the deployment and operational behavior of a virtual
851 storage resources, as defined by **[ETSI NFV IFA011].**
853 **[editor note]** open issue: should NFV profile use the current storage
854 model as described in YAML 1.1. Pending on Shitao proposal (see
855 NFVIFA(17)000110 discussion paper)
857 **[editor note]** new relationship type as suggested in Matt
858 presentation. Slide 8. With specific rules of “valid\_target\_type”
860 +---------------------------+--------------------------------------+
861 | **Shorthand Name** | VirtualStorage |
862 +===========================+======================================+
863 | **Type Qualified Name** | tosca: VirtualStorage |
864 +---------------------------+--------------------------------------+
865 | **Type URI** | tosca.nodes.nfv.VDU.VirtualStorage |
866 +---------------------------+--------------------------------------+
867 | **derived\_from** | tosca.nodes.Root |
868 +---------------------------+--------------------------------------+
870 tosca.artifacts.nfv.SwImage
871 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
873 +---------------------------+------------------------------------+
874 | **Shorthand Name** | SwImage |
875 +===========================+====================================+
876 | **Type Qualified Name** | tosca:SwImage |
877 +---------------------------+------------------------------------+
878 | **Type URI** | tosca.artifacts.nfv.SwImage |
879 +---------------------------+------------------------------------+
880 | **derived\_from** | tosca.artifacts.Deployment.Image |
881 +---------------------------+------------------------------------+
886 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
887 | Name | Required | Type | Constraints | Description |
888 +==========================================+============+====================+===============+====================================================================================================+
889 | name | yes | string | | Name of this software image |
890 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
891 | version | yes | string | | Version of this software image |
892 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
893 | checksum | yes | string | | Checksum of the software image file |
894 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
895 | container\_format | yes | string | | The container format describes the container file format in which software image is provided. |
896 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
897 | disk\_format | yes | string | | The disk format of a software image is the format of the underlying disk image |
898 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
899 | min\_disk | yes | scalar-unit.size | | The minimal disk size requirement for this software image. |
900 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
901 | min\_ram | no | scalar-unit.size | | The minimal RAM requirement for this software image. |
902 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
903 | Size | yes | scalar-unit.size | | The size of this software image |
904 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
905 | sw\_image | yes | string | | A reference to the actual software image within VNF Package, or url. |
906 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
907 | operating\_system | no | string | | Identifies the operating system used in the software image. |
908 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
909 | supported \_virtualization\_enviroment | no | list | | Identifies the virtualization environments (e.g. hypervisor) compatible with this software image |
910 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
915 +-----------------------------------------------------+
916 | tosca.artifacts.nfv.SwImage: |
918 | derived\_from: tosca.artifacts.Deployment.Image |
920 | properties or metadata: |
944 | container\_format: |
958 | type: scalar-unit.size # Number |
964 | type: scalar-unit.size # Number |
970 | type: scalar-unit.size # Number |
980 | operating\_system: |
986 | supported\_virtualisation\_environments: |
995 +-----------------------------------------------------+
1000 openovnf\_\_vOpenNAT.yaml
1001 ~~~~~~~~~~~~~~~~~~~~~~~~~
1003 +-------------------------------------------------------------+
1006 | - openonfv\_\_tosca.capabilities.Scalable.yaml |
1008 | - openonfv\_\_tosca.capabilities.nfv.Metric.yaml |
1010 | - openonfv\_\_tosca.capabilities.network.Bindable.yaml |
1012 | - openonfv\_\_tosca.capabilities.Attachment.yaml |
1014 | - openonfv\_\_tosca.capabilities.nfv.VirtualBindable.yaml |
1016 | - openonfv\_\_tosca.requirements.nfv.VirtualStorage.yaml |
1018 | - openonfv\_\_tosca.nodes.nfv.VDU.VirtualStorage.yaml |
1020 | - openonfv\_\_tosca.relationships.nfv.VirtualBindsTo.yaml |
1022 | - openonfv\_\_tosca.nodes.nfv.VDU.Compute.yaml |
1024 | - openonfv\_\_tosca.artifacts.nfv.SwImage.yaml |
1026 | - openonfv\_\_tosca.capabilities.nfv.VirtualCompute.yaml |
1028 | - openonfv\_\_tosca.capabilities.Container.yaml |
1030 | - openonfv\_\_tosca.capabilities.nfv.VirtualStorage.yaml |
1032 | - openonfv\_\_tosca.requirements.nfv.VirtualBinding.yaml |
1034 | - openovnf\_\_tosca.nodes.nfv.VNF.vOpenNAT.yaml |
1036 | - openonfv\_\_tosca.capabilities.Endpoint.Admin.yaml |
1038 | - openonfv\_\_tosca.capabilities.OperatingSystem.yaml |
1040 | - openonfv\_\_tosca.nodes.nfv.VduCpd.yaml |
1042 | - openonfv\_\_tosca.relationships.nfv.VDU.AttachedTo.yaml |
1046 | vnfProductName: openNAT |
1048 | vnfdVersion: 1.0.0 |
1050 | vnfProvider: intel |
1054 | csarVersion: 1.0.0 |
1056 | vnfdId: openNAT-1.0 |
1058 | csarProvider: intel |
1060 | vnfProductInfoDescription: openNAT |
1068 | localizationLanguage: '[english, chinese]' |
1072 | defaultLocalizationLanguage: english |
1074 | vnfProductInfoName: openNAT |
1076 | vnfSoftwareVersion: 1.0.0 |
1078 | topology\_template: |
1080 | node\_templates: |
1088 | file: /swimages/xenial-snat.qcow2 |
1090 | type: tosca.artifacts.nfv.SwImage |
1094 | name: vNatVNFImage |
1098 | checksum: "5000" |
1100 | container\_format: bare |
1102 | disk\_format: qcow2 |
1104 | min\_disk: 10 GB |
1110 | sw\_image: /swimages/xenial-snat.qcow2 |
1112 | operating\_system: unbantu |
1116 | tosca\_name: vdu\_vNat |
1120 | virtual\_compute: |
1124 | virtual\_memory: |
1126 | numa\_enabled: true |
1128 | virtual\_mem\_size: 2 GB |
1130 | requested\_additional\_capabilities: |
1134 | support\_mandatory: true |
1136 | requested\_additional\_capability\_name: numa |
1138 | target\_performance\_parameters: |
1140 | hw:numa\_nodes: "2" |
1142 | hw:numa\_cpus.0: "0,1" |
1144 | hw:numa\_mem.0: "1024" |
1146 | hw:numa\_cpus.1: "2,3,4,5" |
1148 | hw:numa\_mem.1: "1024" |
1150 | hyper\_threading: |
1152 | support\_mandatory: true |
1154 | requested\_additional\_capability\_name: hyper\_threading |
1156 | target\_performance\_parameters: |
1158 | hw:cpu\_sockets : "2" |
1160 | hw:cpu\_threads : "2" |
1162 | hw:cpu\_cores : "2" |
1164 | hw:cpu\_threads\_policy: "isolate" |
1168 | support\_mandatory: true |
1170 | requested\_additional\_capability\_name: ovs\_dpdk |
1172 | target\_performance\_parameters: |
1174 | sw:ovs\_dpdk: "true" |
1178 | cpu\_architecture: X86 |
1180 | num\_virtual\_cpu: 2 |
1184 | configurable\_properties: |
1188 | additional\_vnfc\_configurable\_properties: |
1194 | descrption: the virtual machine of vNat |
1202 | - virtual\_storage: |
1204 | capability: virtual\_storage |
1206 | node: vNAT\_Storage |
1212 | location: /mnt/volume\_0 |
1214 | type: tosca.relationships.nfv.VDU.AttachedTo |
1216 | - local\_storage: |
1218 | node: tosca.nodes.Root |
1220 | type: tosca.nodes.nfv.VDU.Compute |
1226 | tosca\_name: SRIOV\_Port |
1230 | virtual\_network\_interface\_requirements: |
1234 | support\_mandatory: false |
1236 | description: sriov |
1244 | description: sriov port |
1246 | layer\_protocol: ipv4 |
1250 | - virtual\_binding: |
1252 | capability: virtual\_binding |
1258 | type: tosca.relationships.nfv.VirtualBindsTo |
1260 | - virtual\_link: |
1262 | node: tosca.nodes.Root |
1264 | type: tosca.nodes.nfv.VduCpd |
1270 | tosca\_name: vNAT\_Storage |
1274 | id: vNAT\_Storage |
1276 | size\_of\_storage: 10 GB |
1278 | rdma\_enabled: false |
1280 | type\_of\_storage: volume |
1282 | type: tosca.nodes.nfv.VDU.VirtualStorage |
1284 | substitution\_mappings: |
1294 | node\_type: tosca.nodes.nfv.VNF.vOpenNAT |
1296 | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 |
1297 +-------------------------------------------------------------+
1299 openonfv\_\_tosca.nodes.nfv.VDU.VirtualStorage.yaml
1300 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1302 +------------------------------------------------------------+
1305 | - openonfv\_\_tosca.capabilities.nfv.VirtualStorage.yaml |
1309 | tosca.nodes.nfv.VDU.VirtualStorage: |
1313 | virtual\_storage: |
1315 | type: tosca.capabilities.nfv.VirtualStorage |
1317 | derived\_from: tosca.nodes.Root |
1325 | size\_of\_storage: |
1335 | type\_of\_storage: |
1339 | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 |
1340 +------------------------------------------------------------+
1342 openonfv\_\_tosca.nodes.nfv.VduCpd.yaml
1343 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1345 +-----------------------------------------------------------------+
1348 | tosca.datatypes.nfv.L3AddressData: |
1352 | number\_of\_ip\_address: |
1358 | ip\_address\_assignment: |
1362 | ip\_address\_type: |
1366 | - valid\_values: |
1376 | floating\_ip\_activated: |
1380 | tosca.datatypes.nfv.VirtualNetworkInterfaceRequirements: |
1390 | support\_mandatory: |
1408 | tosca.datatype.nfv.AddressData: |
1416 | - valid\_values: |
1424 | l2\_address\_data: |
1428 | type: tosca.datatypes.nfv.L2AddressData |
1430 | l3\_address\_data: |
1434 | type: tosca.datatypes.nfv.L3AddressData |
1436 | tosca.datatypes.nfv.L2AddressData: {} |
1440 | - openonfv\_\_tosca.requirements.nfv.VirtualBinding.yaml |
1442 | - openonfv\_\_tosca.requirements.nfv.VirtualBinding.yaml |
1446 | tosca.nodes.nfv.VduCpd: |
1448 | derived\_from: tosca.nodes.Root |
1452 | virtual\_network\_interface\_requirements: |
1456 | type: tosca.datatypes.nfv.VirtualNetworkInterfaceRequirements |
1466 | - valid\_values: |
1476 | bitrate\_requirement: |
1488 | layer\_protocol: |
1492 | - valid\_values: |
1512 | type: tosca.datatype.nfv.AddressData |
1520 | - virtual\_binding: |
1522 | capability: tosca.capabilities.nfv.VirtualBindable |
1530 | - virtual\_link: |
1532 | capability: tosca.capabilities.nfv.VirtualBindable |
1540 | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 |
1541 +-----------------------------------------------------------------+
1543 .. |image1| image:: Image1.png
1546 .. |image2| image:: Image2.png
1560 Heat Orchestration Templates must use valid YAML. YAML (YAML Ain't
1561 Markup Language) is a human friendly data serialization standard for all
1562 programming languages. See http://www.yaml.org/.
1564 Heat Orchestration Template Format
1565 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1567 Heat Orchestration templates must be defined in YAML.
1571 - Tabs are NOT allowed, use spaces ONLY.
1573 - You MUST indent your properties and lists with 1 or more spaces.
1575 - All Resource IDs and resource property parameters are case-sensitive.
1576 (e.g., "ThIs", is not the same as "thiS")
1578 Heat Orchestration Template Structure
1579 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1581 Heat Orchestration template structure follows the following format, as
1582 defined by OpenStack at
1583 https://docs.openstack.org/developer/heat/template_guide/hot_spec.html.
1585 .. code-block:: yaml
1587 heat_template_version: <date>
1590 # a description of the template
1593 # a declaration of input parameter groups and order
1596 # declaration of input parameters
1599 # declaration of template resources
1602 # declaration of output parameters
1605 # declaration of conditions
1608 Heat Orchestration templates for ONAP must contain the following
1611 - heat\_template\_version:
1619 Heat Orchestration templates for ONAP may contain the following
1622 - parameter\_groups:
1626 heat\_template\_version
1627 ++++++++++++++++++++++
1629 This section is ONAP mandatory. The heat\_template\_version must be set
1630 to a date that is supported by the OpenStack environment.
1633 ++++++++++++++++++++++
1635 This ONAP mandatory section allows for a description of the template.
1638 ++++++++++++++++++++++
1640 This ONAP optional section allows for specifying how the input
1641 parameters should be grouped and the order to provide the parameters in.
1644 ++++++++++++++++++++++
1646 The parameter section is ONAP mandatory. This section allows for
1647 specifying input parameters that have to be provided when instantiating
1648 the template. Each parameter is specified in a separated nested block
1649 with the name of the parameters defined in the first line and additional
1650 attributes (e.g., type, label) defined as nested elements.
1652 The Pre-Amsterdam VNF Validation Program (i.e., ICE Project) process
1653 requires all parameters declared in a template to be used in a resource
1654 with the exception of the parameters for the OS::Nova::Server property
1655 availability\_zone. See `Property: availability\_zone`_. for more details on
1658 .. code-block:: yaml
1662 type: <string | number | json | comma_delimited_list | boolean>
1663 label: <human-readable name of the parameter>
1664 description: <description of the parameter>
1665 default: <default value for parameter>
1666 hidden: <true | false>
1668 <parameter constraints>
1669 immutable: <true | false>
1673 - The name of the parameter.
1675 - ONAP requires that the param name must contain only alphanumeric
1676 characters and “\_” underscores. Special characters must not be
1681 - The type of the parameter. Supported types are string, number,
1682 comma\_delimited\_list, json and boolean.
1684 - This attribute must be provided per the OpenStack Heat
1685 Orchestration Template standard.
1689 - A human readable name for the parameter.
1691 - This attribute is optional.
1695 - A human readable description for the parameter.
1697 - This attribute is ONAP mandatory; it must be provided. (Note that
1698 this attribute is OpenStack optional.)
1702 - A default value for the parameter.
1704 - ONAP does not support this attribute; it *must not* be provided in
1705 the Heat Orchestration Template. If a parameter has a default
1706 value, it must be provided in the environment file. (Note that
1707 this attribute is OpenStack optional.)
1711 - Defines whether the parameters should be hidden when a user
1712 requests information about a stack created from the template. This
1713 attribute can be used to hide passwords specified as parameters.
1715 - This attribute is optional and defaults to false.
1719 - A list of constraints to apply. The constraints block of a
1720 parameter definition defines additional validation constraints
1721 that apply to the value of the parameter. The parameter values
1722 provided in the Heat Orchestration Template are validated against
1723 the constraints at instantiation time. The constraints are defined
1724 as a list with the following syntax
1728 - <constraint type>: <constraint definition>
1730 description: <constraint description>
1732 - constraint type: Type of constraint to apply.
1734 - constraint definition: The actual constraint, depending on the
1737 - description: A description of the constraint. The text is presented
1738 to the user when the value the user defines violates the constraint.
1739 If omitted, a default validation message is presented to the user.
1740 This attribute is optional.
1742 - When the parameter type is set to number, the Heat Orchestration
1743 Template uploaded into ONAP must have constraints for range or
1746 - range: The range constraint applies to parameters of type number.
1747 It defines a lower and upper limit for the numeric value of the
1748 parameter. The syntax of the range constraint is
1750 range: { min: <lower limit>, max: <upper limit> }
1752 It is possible to define a range constraint with only a lower limit
1755 - allowed\_values: The allowed\_values constraint applies to parameters
1756 of type string or number. It specifies a set of possible values for a
1757 parameter. At deployment time, the user-provided value for the
1758 respective parameter must match one of the elements of the list. The
1759 syntax of the allowed\_values constraint is
1761 allowed\_values: [ <value>, <value>, ... ]
1763 Alternatively, the following YAML list notation can be used
1773 - Other <constraint type> are optional, they may be used (e.g., length,
1774 modulo, allowed\_pattern, custom\_constraint, allowed\_values (for
1777 - Note that constrains must not be defined for any parameter enumerated
1778 in a nested heat template.
1780 - Some ONAP parameters must never have constraints defined. See `ONAP Resource ID and Parameter Naming Convention`_ for the use cases where these exceptions exist.
1784 - Defines whether the parameter is updatable. Stack update fails, if
1785 this is set to true and the parameter value is changed.
1787 - This attribute is optional and defaults to false.
1792 This section is ONAP mandatory; it must be provided. This section
1793 contains the declaration of the single resources of the template. This
1794 section with at least one resource must be defined in the Heat
1795 Orchestration Template, or the template would not create any resources
1796 when being instantiated.
1798 Each resource is defined as a separate block in the resources section
1799 with the following syntax.
1801 .. code-block:: yaml
1805 type: <resource type>
1807 <property name>: <property value>
1809 <resource specific metadata>
1810 depends\_on: <resource ID or list of ID>
1811 update\_policy: <update policy>
1812 deletion\_policy: <deletion policy>
1813 external\_id: <external resource ID>
1814 condition: <condition name or expression or boolean>
1818 - A resource ID that must be unique within the resources section of
1819 the Heat Orchestration Template.
1821 - ONAP requires that the resource ID must be unique across all Heat
1822 Orchestration Templates that compose the VNF. This requirement
1823 also applies when a VNF is composed of more than one Heat
1824 Orchestration Template (see ONAP VNF Modularity Overview).
1826 - The naming convention for a resource ID is provided in `Resource IDs`_.
1830 - The resource type, such as OS::Nova::Server or OS::Neutron::Port.
1831 Note that the type may specify a nested heat file. This attribute
1836 - A list of resource-specific properties. The property value can be
1837 provided in place, or via a function (e.g., Intrinsic functions). This section is optional.
1839 - The naming convention for property parameters is provided in `ONAP Resource ID and Parameter Naming Convention`_.
1843 - Resource-specific metadata. This section is optional, except for
1844 the resource OS::Nova::Server. See `Resource: OS::Nova::Server - Parameters`_.
1848 - Dependencies of the resource on one or more resources of the
1849 template. This attribute is optional. See `Resource Data Synchronization`_ for additional details.
1853 - Update policy for the resource, in the form of a nested
1854 dictionary. Whether update policies are supported and what the
1855 exact semantics are depends on the type of the current resource.
1856 This attribute is optional.
1860 - Deletion policy for the resource. The allowed deletion policies
1861 are Delete, Retain, and Snapshot. Beginning with
1862 heat\_template\_version 2016-10-14, the lowercase equivalents
1863 delete, retain, and snapshot are also allowed. This attribute is
1864 optional; the default policy is to delete the physical resource
1865 when deleting a resource from the stack.
1869 - Allows for specifying the resource\_id for an existing external
1870 (to the stack) resource. External resources cannot depend on other
1871 resources, but we allow other resources to depend on external
1872 resource. This attribute is optional. Note: when this is
1873 specified, properties will not be used for building the resource
1874 and the resource is not managed by Heat. This is not possible to
1875 update that attribute. Also, resource won’t be deleted by heat
1876 when stack is deleted.
1880 - Condition for the resource. The condition decides whether to
1881 create the resource or not. This attribute is optional.
1886 This ONAP optional section allows for specifying output parameters
1887 available to users once the template has been instantiated. If the
1888 section is specified, it will need to adhere to specific requirements.
1889 See `ONAP Parameter Classifications Overview`_ and `ONAP Output Parameter Names`_ for additional details.
1891 Environment File Format
1892 ^^^^^^^^^^^^^^^^^^^^^^
1894 The environment file is a yaml text file.
1895 (https://docs.openstack.org/developer/heat/template_guide/environment.html)
1897 The environment file can contain the following sections:
1899 - parameters: A list of key/value pairs.
1901 - resource\_registry: Definition of custom resources.
1903 - parameter\_defaults: Default parameters passed to all template
1906 - encrypted\_parameters: List of encrypted parameters.
1908 - event\_sinks: List of endpoints that would receive stack events.
1910 - parameter\_merge\_strategies: Merge strategies for merging parameters
1911 and parameter defaults from the environment file.
1913 Environment files for ONAP must contain the following sections:
1917 Environment files for ONAP may contain the following sections:
1919 - resource\_registry:
1921 - parameter\_defaults:
1923 - encrypted\_parameters:
1927 - parameter\_merge\_strategies:
1929 The use of an environment file in OpenStack is optional. In ONAP, it is
1930 mandatory. A Heat Orchestration Template uploaded to ONAP must have a
1931 corresponding environment file, even if no parameters are enumerated in
1932 the mandatory parameter section.
1934 (Note that ONAP, the open source version of ONAP, does not
1935 programmatically enforce the use of an environment file.)
1937 SDC Treatment of Environment Files
1938 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1940 Parameter values enumerated in the environment file are used by SDC as
1941 the default value. However, the SDC user may use the SDC GUI to
1942 overwrite the default values in the environment file.
1944 SDC generates a new environment file for distribution to MSO based on
1945 the uploaded environment file and the user provided GUI updates. The
1946 user uploaded environment file is discarded when the new file is
1949 ONAP has requirements for what parameters must be enumerated in the
1950 environment file and what parameter must not be enumerated in the
1951 environment file. See `ONAP Parameter Classifications Overview`_ and `ONAP Resource ID and Parameter Naming Convention`_ for more details.
1953 Nested Heat Orchestration Templates Overview
1954 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1956 ONAP supports nested Heat Orchestration Templates per OpenStack
1959 A Base Module may utilize nested templates.
1961 An Incremental Module may utilize nested templates.
1963 A Cinder Volume Module may utilize nested templates.
1965 A nested template must not define parameter constraints in the parameter
1968 Nested templates may be suitable for larger VNFs that contain many
1969 repeated instances of the same VM type(s). A common usage pattern is to
1970 create a nested template for each VM type along with its supporting
1971 resources. The Heat Orchestration Template may then reference these
1972 nested templates either statically (by repeated definition) or
1973 dynamically (via OS::Heat::ResourceGroup).
1975 See `Nested Heat Templates`_ for additional details.
1977 ONAP Heat Orchestration Template Filenames
1978 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1980 In order to enable ONAP to understand the relationship between Heat
1981 files, the following Heat file naming convention must be utilized.
1983 In the examples below, <text> represents any alphanumeric string that
1984 must not contain any special characters and must not contain the word
1990 The file name for the base module must include “base” in the filename
1991 and must match one of the following options:
1993 - base\_<text>.y[a]ml
1995 - <text>\_base.y[a]ml
1999 - <text>\_base\_<text>.y[a]ml
2001 The base module’s corresponding environment file must be named identical
2002 to the base module with “.y[a]ml” replaced with “.env”.
2007 There is no explicit naming convention for the incremental modules. As
2008 noted above, <text> represents any alphanumeric string that must not
2009 contain any special characters and must not contain the word “base”.
2013 The incremental module’s corresponding environment file must be named
2014 identical to the incremental module with “.y[a]ml” replaced with “.env”.
2016 To clearly identify the incremental module, it is recommended to use the
2017 following naming options for modules:
2019 - module\_<text>.y[a]ml
2021 - <text>\_module.y[a]ml
2025 Cinder Volume Modules
2026 ~~~~~~~~~~~~~~~~~~~~~
2028 The file name for the Cinder volume module must be named the same as the
2029 corresponding module it is supporting (base module or incremental
2030 module) with “\_volume” appended
2032 - <base module name>\_volume.y[a]ml
2034 - <incremental module name>\_volume.y[a]ml
2036 The volume module’s corresponding environment file must be named
2037 identical to the volume module with “.y[a]ml” replaced with “.env”.
2042 There is no explicit naming convention for nested Heat files with the
2043 following exceptions; the name should contain “nest”. As noted above,
2044 <text> represents any alphanumeric string that must not contain any
2045 special characters and must not contain the word “base”.
2049 Nested Heat files do not have corresponding environment files, per
2050 OpenStack specifications. All parameter values associated with the
2051 nested heat file must be passed in as properties in the resource
2052 definition defined in the parent heat template.
2054 ONAP Parameter Classifications Overview
2055 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2057 In order for ONAP to support workflow automation, Heat Orchestration
2058 Template resource property parameters must adhere to specific naming
2059 conventions and requirements.
2061 Broadly, ONAP categorizes parameters into four categories:
2063 1. ONAP metadata parameters
2065 2. Instance specific parameters
2067 3. Constant parameters
2069 4. Output parameters.
2071 ONAP Metadata Parameters
2072 ~~~~~~~~~~~~~~~~~~~~~~~~
2074 There are both mandatory and optional ONAP metadata parameters
2075 associated with the resource OS::Nova::Server.
2077 - ONAP metadata parameters must not have parameter constraints defined.
2079 - Both mandatory and optional (if specified) ONAP metadata parameter
2080 names must follow the ONAP metadata parameter naming convention.
2082 `Resource: OS::Nova::Server – Metadata Parameters`_ provides more details on the metadata parameters.
2084 Instance specific parameters
2085 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2087 The instance specific parameters are VNF instance specific. The value of
2088 the parameter will be different for every instance of a VNF (e.g., IP
2089 address). The instance specific parameters are subdivided into two
2090 categories: **ONAP Orchestration Parameters** and **VNF Orchestration
2093 ONAP Orchestration Parameters
2094 +++++++++++++++++++++++++++++
2096 ONAP Orchestration Parameters are per instance parameters where the
2097 value is assigned via ONAP automation. (Note that in some cases,
2098 automation is currently not available and the value is loaded into ONAP
2099 prior to instantiation.)
2101 - ONAP orchestration parameters must not be enumerated in the
2104 - When the ONAP orchestration parameter type is set to number, the
2105 parameter must have constraints for range and/or allowed\_values.
2107 - Parameter constraints for ONAP orchestration parameters are optional
2108 for all parameter types other than number. If constraints are
2109 specified, they must adhere to the OpenStack specifications.
2111 - The ONAP orchestration parameter names must follow the ONAP
2112 orchestration parameter naming convention. `ONAP Resource ID and Parameter Naming Convention`_ provides
2115 VNF Orchestration Parameters
2116 +++++++++++++++++++++++++++++
2118 VNF Orchestration Parameters are per instance parameters where the
2119 values are assigned manually. They are not supported by ONAP automation.
2120 The per instance values are loaded into ONAP prior to VNF instantiation.
2122 - VNF orchestration parameters must not be enumerated in the
2125 - When the VNF orchestration parameter type is set to number, the
2126 parameter must have constraints for range or allowed\_values.
2128 - Parameter constraints for VNF orchestration parameters are optional
2129 for all parameter types other than number. If constraints are
2130 specified, they must adhere to the OpenStack specifications.
2132 - The VNF orchestration parameter names should follow the VNF
2133 orchestration parameter naming convention. `ONAP Resource ID and Parameter Naming Convention`_ provides
2139 The constant parameters are parameters that remain constant across many
2140 VNF instances (e.g., image, flavor). The constant parameters are
2141 subdivided into two categories: **ONAP Constant Parameters** and **VNF Constant Parameters.**
2143 ONAP Constant Parameters
2144 +++++++++++++++++++++++++++++
2146 - ONAP Constant Parameters must be enumerated in the environment file.
2147 These parameter values are not assigned by ONAP.
2149 - When the ONAP Constant Parameter type is set to number, the parameter
2150 must have constraints for range and/or allowed\_values.
2152 - Parameter constraints for ONAP constant parameters are optional for
2153 all parameter types other than number. If constraints are specified,
2154 they must adhere to the OpenStack specifications.
2156 - The ONAP Constant Parameter names must follow the ONAP orchestration
2157 parameter naming convention. `ONAP Resource ID and Parameter Naming Convention`_ provides additional details.
2159 VNF Constant Parameters
2160 +++++++++++++++++++++++++++++
2162 - VNF Constant Parameters must be enumerated in the environment file.
2163 These parameter values are not assigned by ONAP.
2165 - When the VNF Constant Parameters type is set to number, the parameter
2166 must have constraints for range and/or allowed\_values.
2168 - Parameter constraints for ONAP constant parameters are optional for
2169 all parameter types other than number. If constraints are specified,
2170 they must adhere to the OpenStack specifications.
2172 - The VNF Constant Parameters names should follow the ONAP
2173 orchestration parameter naming convention. `ONAP Resource ID and Parameter Naming Convention`_ provides
2179 The output parameters are parameters defined in the output section of a
2180 Heat Orchestration Template. The ONAP output parameters are subdivided
2181 into three categories:
2183 1. ONAP Base Module Output Parameters
2185 2. ONAP Volume Module Output Parameters
2187 3. ONAP Predefined Output Parameters.
2189 ONAP Base Module Output Parameters
2190 +++++++++++++++++++++++++++++
2192 ONAP Base Module Output Parameters are declared in the outputs: section
2193 of the base module Heat Orchestration Template. A Base Module Output
2194 Parameter is available as an input parameter (i.e., declared in the
2195 “parameters:” section) to all incremental modules in the VNF.
2197 - A Base Module Output Parameter may be used as an input parameter in
2198 an incremental module.
2200 - The Output parameter name and type must match the input parameter
2201 name and type unless the Output parameter is of the type
2202 comma\_delimited\_list.
2204 - If the Output parameter has a comma\_delimited\_list value (e.g.,
2205 a collection of UUIDs from a Resource Group), then the
2206 corresponding input parameter must be declared as type json and
2207 not a comma\_delimited\_list, which is actually a string value
2208 with embedded commas.
2210 - When a Base Module Output Parameter is declared as an input parameter
2211 in an incremental module Heat Orchestration Template, parameter
2212 constraints must not be declared.
2214 Additional details on ONAP Base Module Output Parameters are provided in
2215 `ONAP Output Parameter Names`_ and ONAP VNF Modularity.
2217 ONAP Volume Module Output Parameters
2218 ++++++++++++++++++++++++++++++++++++
2220 The volume template output parameters are only available for the module
2221 (base or add on) that the volume is associated with.
2223 - ONAP Volume Module Output Parameters are declared in the “outputs:”
2224 section of the Cinder volume module Heat Orchestration Template
2226 - An ONAP Volume Module Output Parameter is available as an input
2227 parameter (i.e., declared in the parameters: section) only for the
2228 module (base or incremental) that the Cinder volume module is
2229 associated with. The Output parameter name and type must match the
2230 input parameter name and type unless the Output parameter is of the
2231 type comma\_delimited\_list.
2233 - If the Output parameter has a comma\_delimited\_list value (e.g., a
2234 collection of UUIDs from a Resource Group), then the corresponding
2235 input parameter must be declared as type json and not a
2236 comma\_delimited\_list, which is actually a string value with
2239 - When an ONAP Volume Module Output Parameter is declared as an input
2240 parameter in a base module or incremental module, parameter
2241 constraints must not be declared.
2243 Additional details on ONAP Base Module Output Parameters are provided in
2244 `ONAP Output Parameter Names`_ and `Cinder Volume Templates`_.
2246 ONAP Predefined Output Parameters
2247 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2249 ONAP will look for a small set of pre-defined Heat output parameters to
2250 capture resource attributes for inventory in ONAP. These output
2251 parameters are optional and are specified in `OAM Management IP Addresses`_.
2253 Support of heat stack update
2254 +++++++++++++++++++++++++++++
2256 VNF Heat Orchestration Templates must not be designed to utilize the
2257 OpenStack heat stack-update command for scaling (growth/de-growth). ONAP
2258 does not support the use of heat stack-update command for scaling.
2260 It is important to note that ONAP only supports heat stack-update for
2266 ONAP defines two types of networks: External Networks and Internal
2269 ONAP defines an external network in relation to the VNF and not with
2270 regard to the Network Cloud site. External networks may also be referred
2271 to as “inter-VNF” networks. An external network connects VMs in a VNF to
2273 - VMs in another VNF or
2275 - an external gateway or router
2277 ONAP defines an internal network in relation to the VNF and not with
2278 regard to the Network Cloud site. Internal networks may also be referred
2279 to as “intra-VNF” networks or “private” networks. An internal network
2280 only connects VMs in a single VNF. It must not connect to other VNFs or
2281 an external gateway or router.
2286 VNF Heat Orchestration Templates must not include any resources for
2287 external networks connected to the VNF. External networks must be
2288 orchestrated separately, as independent, stand-alone VNF Heat
2289 Orchestration Templates, so they can be shared by multiple VNFs and
2290 managed independently.
2292 When the external network is created, it must be assigned a unique
2293 {network-role}. The {network-role} should describe the network (e.g.,
2294 oam). The {network-role} while unique to the LCP, can repeat across
2297 An External Network may be a Neutron Network or a Contrail Network
2299 External networks must be passed into the VNF Heat Orchestration
2300 Templates as parameters.
2302 - Neutron Network-id (UUID)
2304 - Neutron Network subnet ID (UUID)
2306 - Contrail Network Fully Qualified Domain Name (FQDN)
2308 ONAP enforces a naming convention for parameters associated with
2309 external networks. `ONAP Resource ID and Parameter Naming Convention`_ provides additional details.
2311 Parameter values associated with an external network will be generated
2312 and/or assigned by ONAP at orchestration time. Parameter values
2313 associated with an external network must not be enumerated in the
2314 environment file. `ONAP Resource ID and Parameter Naming Convention`_ provides additional details.
2316 VNFs may use **Cloud assigned IP addresses** or **ONAP SDN-C assigned IP addresses**
2317 when attaching VMs to an external network
2319 - A Cloud assigned IP address is assigned by OpenStack’s DHCP Service.
2321 - An ONAP SDN-C assigned IP address is assigned by the ONAP SDN-C
2324 - Note that Neutron Floating IPs must not be used. ONAP does not
2325 support Neutron Floating IPs (e.g., OS::Neutron::FloatingIP)
2327 - ONAP supports the property allowed\_address\_pairs in the resource
2328 OS::Neutron:Port and the property
2329 virtual\_machine\_interface\_allowed\_address\_pairs in
2330 OS::ContrailV2::VirtualMachineInterfaces. This allows the assignment
2331 of a virtual IP (VIP) address to a set of VMs.
2333 VNF Heat Orchestration Templates must pass the appropriate external
2334 network IDs into nested VM templates when nested Heat is used.
2339 The VNF Heat Orchestration Templates must include the resource(s) to
2340 create the internal network. The internal network must be either a
2341 Neutron Network or a Contrail Network.
2343 In the modular approach, internal networks must be created in the Base
2344 Module, with their resource IDs exposed as outputs (i.e., ONAP Base
2345 Module Output Parameters) for use by all incremental modules. If the
2346 Network resource ID is required in the base template, then a
2347 get\_resource must be used.
2349 When the internal network is created, it should be assigned a unique
2350 {network-role} in the context of the VNF. `ONAP Resource ID and Parameter Naming Convention`_ provides additional
2353 VNFs may use **Cloud assigned IP addresses** or
2354 **predetermined static IPs** when attaching VMs to an internal network.
2356 - A Cloud assigned IP address is assigned by OpenStack’s DHCP Service.
2358 - A predetermined static IP address is enumerated in the Heat
2359 environment file. Since an internal network is local to the VNF, IP
2360 addresses can be re-used at every VNF instance.
2362 - Note that Neutron Floating IPs must not be used. ONAP does not
2363 support Neutron Floating IPs (e.g., OS::Neutron::FloatingIP)
2365 - ONAP supports the property allowed\_address\_pairs in the resource
2366 OS::Neutron:Port and the property
2367 virtual\_machine\_interface\_allowed\_address\_pairs in
2368 OS::ContrailV2::VirtualMachineInterfaces. This allows the assignment
2369 of a virtual IP (VIP) address to a set of VMs.
2371 ONAP does not programmatically enforce a naming convention for
2372 parameters for internal network. However, a naming convention is
2373 provided that must be followed. `ONAP Resource ID and Parameter Naming Convention`_ provides additional details.
2375 ONAP Resource ID and Parameter Naming Convention
2376 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2378 This section provides the ONAP naming requirements for
2382 2. Resource Property Parameters
2387 The Heat Orchestration Templates for a VNF must assign a VNF unique
2388 {vm-type} for each Virtual Machine type (i.e., OS::Nova::Server)
2389 instantiated in the VNF. While the {vm-type} must be unique to the VNF,
2390 it does not have to be globally unique across all VNFs that ONAP
2393 Any parameter that is associated with a unique Virtual Machine type in
2394 the VNF must include {vm-type} as part of the parameter name.
2396 Any resource ID that is associated with a unique Virtual Machine type in
2397 the VNF must include {vm-type} as part of the resource ID.
2399 Note that {vm-type} must not be a substring of {network-role}. A
2400 substring of a string is another string that occurs "in". For example,
2401 "oam" is a substring of "oam\_protected". It will cause the
2402 Pre-Amsterdam VNF Validation Program (i.e., ICE Project) process to
2403 produce erroneous error messages.
2405 The {vm-type} should not contain the string “\_int” or “int\_” or
2406 “\_int\_”. It may cause the Pre-Amsterdam VNF Validation Program (i.e.,
2407 ICE Project) process to produce erroneous error messages.
2409 The {vm-type} must be the same case in all parameter names in the VNF.
2411 The {vm-type} must be the same case in all Resource IDs in the VNF.
2413 It is recommended that the {vm-type} case in the parameter names matches
2414 the {vm-type} case in the Resource IDs.
2416 There are two exceptions to the above rules:
2418 1. The six ONAP Metadata parameters must not be prefixed with a common
2419 {vm-type} identifier. They are *vnf\_name*, *vnf\_id*,
2420 *vf\_module\_id*, *vf\_module\_name, vm\_role*. The ONAP Metadata
2421 parameters are described in `Resource: OS::Nova::Server – Metadata Parameters`_.
2423 2. The parameter referring to the OS::Nova::Server property
2424 availability\_zone must not be prefixed with a common {vm-type}
2425 identifier. availability\_zone is described in `Property: availability_zone`_.
2430 The assignment of a {network-role} is discussed in `Networking`_.
2432 Any parameter that is associated with an external network must include
2433 the {network-role} as part of the parameter name.
2435 Any resource ID that is associated with an external network must include
2436 the {network-role} as part of the resource ID.
2438 Any parameter that is associated with an internal network must include
2439 int\_{network-role} as part of the parameter name.
2441 Any resource ID that is associated with an internal network must include
2442 int\_{network-role} as part of the resource ID.
2444 Note that {network-role} must not be a substring of {vm-type}. A
2445 substring of a string is another string that occurs "in". For example,
2446 "oam" is a substring of "oam\_protected". It will cause the
2447 Pre-Amsterdam VNF Validation Program (i.e., ICE Project) process to
2448 produce erroneous error messages.
2450 The {network-role} should not contain the string “\_int” or “int\_” or
2451 “\_int\_”. It may cause the Pre-Amsterdam VNF Validation Program (i.e.,
2452 ICE Project) process to produce erroneous error messages.
2454 The {network-role} must be the same case in all parameter names in the
2457 The {network-role} must be the same case in all Resource IDs in the VNF.
2459 It is recommended that the {network-role} case in the parameter names
2460 matches the {network-role} case in the Resource IDs.
2465 Heat Orchestration Template resources are described in `resources`_
2467 A resource ID that must be unique within the resources section of a Heat
2468 Orchestration Template. This is an OpenStack Requirement.
2470 When a VNF is composed of more than one Heat Orchestration Template
2471 (i.e., modules), ONAP requires that the resource ID must be unique
2472 across all modules that compose the VNF.
2474 When a resource is associated with a single {vm-type}, the resource ID
2475 must contain {vm-type}.
2477 When a resource is associated with a single external network, the
2478 resource ID must contain {network-role}.
2480 When a resource is associated with a single internal network, the
2481 resource ID must contain int\_{network-role}.
2483 When a resource is associated with a single {vm-type} and a single
2484 external network, the resource ID must contain both the {vm-type} and
2487 - The {vm-type} must appear before the {network-role} and must be
2488 separated by an underscore (i.e., {vm-type}\_{network-role}).
2490 - Note that an {index} value may separate the {vm-type} and the
2491 {network-role}. An underscore will separate the three values (i.e.,
2492 {vm-type}\_{index}\_{network-role}).
2494 When a resource is associated with a single {vm-type} and a single
2495 internal network, the resource ID must contain both the {vm-type} and
2496 int\_{network-role}.
2498 - The {vm-type} must appear before the int\_{network-role} and must be
2499 separated by an underscore (i.e., {vm-type}\_int\_{network-role}).
2501 - Note that an {index} value may separate the {vm-type} and the
2502 int\_{network-role}. An underscore will separate the three values
2503 (i.e., {vm-type}\_{index}\_int\_{network-role}).
2505 When a resource is associated with more than one {vm-type} and/or more
2506 than one network, the resource ID
2508 - must not contain the {vm-type} and/or
2509 {network-role}/int\_{network-role}
2511 - should contain the term “shared” and/or contain text that identifies
2514 Only alphanumeric characters and “\_” underscores must be used in the
2515 resource ID. Special characters must not be used.
2517 All {index} values must be zero based. That is, the {index} must start
2518 at zero and increment by one.
2520 The table below provides example OpenStack Heat resource ID for
2521 resources only associated with one {vm-type} and/or one network.
2523 +--------------------------------+------------------------------------------------------------+
2524 | Resource Type | Resource ID Format |
2525 +================================+============================================================+
2526 | OS::Cinder::Volume | {vm\_type}\_volume\_{index} |
2527 +--------------------------------+------------------------------------------------------------+
2528 | OS::Cinder::VolumeAttachment | {vm\_type}\_volumeattachment\_{index} |
2529 +--------------------------------+------------------------------------------------------------+
2530 | OS::Heat::CloudConfig | {vm\_type}\_RCC |
2531 +--------------------------------+------------------------------------------------------------+
2532 | OS::Heat::MultipartMime | {vm\_type}\_RMM |
2533 +--------------------------------+------------------------------------------------------------+
2534 | OS::Heat::ResourceGroup | {vm\_type}\_RRG |
2535 +--------------------------------+------------------------------------------------------------+
2536 | OS::Heat::SoftwareConfig | {vm\_type}\_RSC |
2537 +--------------------------------+------------------------------------------------------------+
2538 | OS::Neutron::Port | {vm\_type}\_{index}\_{network\_role}\_{index}\_port |
2539 +--------------------------------+------------------------------------------------------------+
2540 | | {vm\_type}\_{index}\_int\_{network\_role}\_{index}\_port |
2541 +--------------------------------+------------------------------------------------------------+
2542 | OS::Neutron::SecurityGroup | {vm\_type}\_RSG |
2543 +--------------------------------+------------------------------------------------------------+
2544 | OS::Neutron::Subnet | {network\_role}\_subnet\_{index} |
2545 +--------------------------------+------------------------------------------------------------+
2546 | OS::Nova::Server | {vm\_type}\_{index} |
2547 +--------------------------------+------------------------------------------------------------+
2548 | OS::Nova::ServerGroup | {vm\_type}\_RSG |
2549 +--------------------------------+------------------------------------------------------------+
2550 | OS::Swift::Container | {vm\_type}\_RSwiftC |
2551 +--------------------------------+------------------------------------------------------------+
2553 Table 1: Example OpenStack Heat Resource ID
2555 The table below provides example Contrail Heat resource ID for resources
2556 only associated with one {vm-type} and/or one network.
2558 +-------------------------------------------+---------------------------------------------+
2559 | Resource Type | Resource ID Format |
2560 +===========================================+=============================================+
2561 | OS::ContrailV2::InstanceIp | {vm\_type}\_{index}\_{network\_role}\_RII |
2562 +-------------------------------------------+---------------------------------------------+
2563 | OS::ContrailV2::InterfaceRouteTable | {network\_role}\_RIRT |
2564 +-------------------------------------------+---------------------------------------------+
2565 | OS::ContrailV2::NetworkIpam | {network\_role}\_RNI |
2566 +-------------------------------------------+---------------------------------------------+
2567 | OS::ContrailV2::PortTuple | {vm\_type}\_RPT |
2568 +-------------------------------------------+---------------------------------------------+
2569 | OS::ContrailV2::ServiceHealthCheck | {vm\_type}\_RSHC\_{LEFT\|RIGHT} |
2570 +-------------------------------------------+---------------------------------------------+
2571 | OS::ContrailV2::ServiceTemplate | {vm\_type}\_RST\_{index} |
2572 +-------------------------------------------+---------------------------------------------+
2573 | OS::ContrailV2::VirtualMachineInterface | int\_{network\_role}\_RVMI |
2574 +-------------------------------------------+---------------------------------------------+
2575 | OS::ContrailV2::VirtualNetwork | int\_{network\_role}\_RVN |
2576 +-------------------------------------------+---------------------------------------------+
2578 Table 2: Example Contrail Heat resource ID
2580 Resource: OS::Nova::Server - Parameters
2581 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2583 The resource OS::Nova::Server manages the running virtual machine (VM)
2584 instance within an OpenStack cloud. (See
2585 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::Server.)
2587 Four properties of this resource must follow the ONAP parameter naming
2588 convention. The four properties are:
2596 4. availability\_zone
2598 The table below provides a summary. The sections that follow provides
2601 Note that the {vm\_type} must be identical across all four property
2602 parameter for a given OS::Nova::Server resource.
2604 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2605 | Resource OS::Nova::Server |
2606 +=============================+===============================+==================+==============================+=================================+
2607 | Property Name | ONAP Parameter Name | Parameter Type | Parameter Value Generation | ONAP Parameter Classification |
2608 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2609 | image | {vm-type}\_image\_name | string | Environment File | ONAP Constant |
2610 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2611 | flavor | {vm-type}\_flavor\_name | string | Environment File | ONAP Constant |
2612 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2613 | name | {vm-type}\_name\_{index} | string | ONAP | ONAP Orchestration |
2614 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2615 | | {vm-type}\_names | CDL | ONAP | ONAP Orchestration |
2616 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2617 | availability\_zone | availability\_zone\_{index} | string | ONAP | ONAP Orchestration |
2618 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2620 Table 3 Resource Property Parameter Names
2625 The parameter associated with the property image is an ONAP Constant
2628 The parameters must be named {vm-type}\_image\_name in the Heat
2629 Orchestration Template.
2631 The parameter must be declared as type: string
2633 The parameter must be enumerated in the Heat Orchestration Template
2636 Each VM type (i.e., {vm-type}) must have a separate parameter for image,
2637 even if more than one {vm-type} shares the same image. This provides
2638 maximum clarity and flexibility.
2640 *Example Parameter Definition*
2642 .. code-block:: yaml
2645 {vm-type}_image_name:
2647 description: {vm-type} server image
2652 The parameter associated with the property flavor is an ONAP Constant
2655 The parameters must be named {vm-type}\_flavor\_name in the Heat
2656 Orchestration Template.
2658 The parameter must be declared as type: string
2660 The parameter must be enumerated in the Heat Orchestration Template
2663 Each VM type (i.e., {vm-type}) must have a separate parameter for
2664 flavors, even if more than one {vm-type} shares the same flavor. This
2665 provides maximum clarity and flexibility.
2667 *Example Parameter Definition*
2669 .. code-block:: yaml
2672 {vm-type}_flavor_name:
2674 description: {vm-type} flavor
2679 The parameter associated with the property name is an ONAP Orchestration
2682 The parameter value is provided to the Heat template by ONAP. The
2683 parameter must not be enumerated in the environment file.
2685 The parameter must be declared as type: string or type:
2686 comma\_delimited\_list
2688 If the parameter is declared as type:string, the parameter must be named
2689 {vm-type}\_name\_{index}, where {index} is a numeric value that starts
2690 at zero and increments by one.
2692 If the parameter is declared as type:comma\_delimited\_list, the
2693 parameter must be named as {vm-type}\_names
2695 Each element in the VM Name list should be assigned to successive
2696 instances of that VM type.
2698 If a VNF contains more than three instances of a given {vm-type}, the
2699 comma\_delimited\_list form of the parameter name (i.e.,
2700 {vm-type}\_names) should be used to minimize the number of unique
2701 parameters defined in the Heat.
2703 *Example: Parameter Definition*
2705 .. code-block:: yaml
2709 type: comma_delimited_list
2710 description: VM Names for {vm-type} VMs
2711 {vm-type}_name_{index}:
2713 description: VM Name for {vm-type} VM {index}
2715 *Example: comma\_delimited\_list*
2717 In this example, the {vm-type} has been defined as “lb” for load
2720 .. code-block:: yaml
2724 type: comma_delimited_list
2725 description: VM Names for lb VMs
2729 type: OS::Nova::Server
2731 name: { get_param: [lb_names, 0] }
2735 type: OS::Nova::Server
2737 name: { get_param: [lb_names, 1] }
2740 *Example: fixed-index*
2742 In this example, the {vm-type} has been defined as “lb” for load
2745 .. code-block:: yaml
2750 description: VM Name for lb VM 0
2754 description: VM Name for lb VM 1
2758 type: OS::Nova::Server
2760 name: { get_param: lb_name_0 }
2764 type: OS::Nova::Server
2766 name: { get_param: lb_name_1 }
2769 Contrail Issue with Values for OS::Nova::Server Property Name
2770 +++++++++++++++++++++++++++++++++++++++++++++++++++++
2772 The Contrail GUI has a limitation displaying special characters. The
2773 issue is documented in
2774 https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is
2775 recommended that special characters be avoided. However, if special
2776 characters must be used, the only special characters supported are:
2778 - “ ! $ ‘ ( ) = ~ ^ \| @ \` { } [ ] > , . \_
2780 Property: availability\_zone
2781 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2783 The parameter associated with the property availability\_zone is an ONAP
2784 Orchestration parameter.
2786 The parameter value is provided to the Heat template by ONAP. The
2787 parameter must not be enumerated in the environment file.
2789 The parameter must be named availability\_zone\_{index} in the Heat
2790 Orchestration Template. The {index} must start at zero. The {index} must
2791 increment by one. The parameter name must not include the {vm-type}.
2793 The parameter must be declared as type: string
2795 The parameter must not be declared as type: comma\_delimited\_list
2800 The example below depicts part of a Heat Orchestration Template that
2801 uses the four OS::Nova::Server properties discussed in this section.
2803 In the Heat Orchestration Template below, four Virtual Machines
2804 (OS::Nova::Server) are created: two dns servers with {vm-type} set to
2805 “dns” and two oam servers with {vm-type} set to “oam”. Note that the
2806 parameter associated with the property name is a comma\_delimited\_list
2807 for dns and a string for oam.
2809 .. code-block:: yaml
2814 description: dns server image
2817 description: dns server flavor
2819 type: comma_delimited_list
2820 description: dns server names
2823 description: oam server image
2826 description: oam server flavor
2829 description: oam server name 0
2832 description: oam server name 1
2833 availability_zone_0:
2835 description: availability zone ID or Name
2836 availability_zone_1:
2838 description: availability zone ID or Name
2842 type: OS::Nova::Server
2844 name: { get_param: [ dns_names, 0 ] }
2845 image: { get_param: dns_image_name }
2846 flavor: { get_param: dns_flavor_name }
2847 availability_zone: { get_param: availability_zone_0 }
2851 type: OS::Nova::Server
2853 name: { get_param: [ dns_names, 1 ] }
2854 image: { get_param: dns_image_name }
2855 flavor: { get_param: dns_flavor_name }
2856 availability_zone: { get_param: availability_zone_1 }
2860 type: OS::Nova::Server
2862 name: { get_param: oam_name_0 }
2863 image: { get_param: oam_image_name }
2864 flavor: { get_param: oam_flavor_name }
2865 availability_zone: { get_param: availability_zone_0 }
2869 type: OS::Nova::Server
2871 name: { get_param: oam_name_1 }
2872 image: { get_param: oam_image_name }
2873 flavor: { get_param: oam_flavor_name }
2874 availability_zone: { get_param: availability_zone_1 }
2877 Resource: OS::Nova::Server – Metadata Parameters
2878 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2880 The resource OS::Nova::Server has an OpenStack optional property
2881 metadata. The metadata property is mandatory for ONAP Heat Orchestration
2882 Templates; it must be included.
2884 ONAP requires the following three mandatory metadata parameters for an
2885 OS::Nova::Server resource:
2893 ONAP allows the following three optional metadata parameters for an
2894 OS::Nova::Server resource. They may be included
2900 Note that the metadata parameters do not and must not contain {vm-type}
2903 When Metadata parameters are past into a nested heat template, the
2904 parameter names must not change.
2906 The table below provides a summary. The sections that follow provides
2909 +---------------------------+------------------+----------------------+------------------------------+
2910 | Metadata Parameter Name | Parameter Type | Mandatory/Optional | Parameter Value Generation |
2911 +===========================+==================+======================+==============================+
2912 | vnf\_id | string | Mandatory | ONAP |
2913 +---------------------------+------------------+----------------------+------------------------------+
2914 | vf\_module\_id | string | Mandatory | ONAP |
2915 +---------------------------+------------------+----------------------+------------------------------+
2916 | vnf\_name | string | Mandatory | ONAP |
2917 +---------------------------+------------------+----------------------+------------------------------+
2918 | vf\_module\_name | string | Optional | ONAP |
2919 +---------------------------+------------------+----------------------+------------------------------+
2920 | vm\_role | string | Optional | YAML or Environment File |
2921 +---------------------------+------------------+----------------------+------------------------------+
2922 +---------------------------+------------------+----------------------+------------------------------+
2924 Table 4: ONAP Metadata
2929 The vnf\_id parameter is mandatory; it must be included in the Heat
2930 Orchestration Template.
2932 The vnf\_id parameter value will be supplied by ONAP. ONAP generates the
2933 UUID that is the vnf\_id and supplies it to the Heat Orchestration
2934 Template at orchestration time.
2936 The parameter must be declared as type: string
2938 Parameter constraints must not be defined.
2940 The parameter must not be enumerated in the Heat environment file.
2942 *Example Parameter Definition*
2944 .. code-block:: yaml
2949 description: Unique ID for this VNF instance
2954 The vf\_module\_id parameter is mandatory; it must be included in the
2955 Heat Orchestration Template.
2957 The vf\_module\_id parameter value will be supplied by ONAP. ONAP
2958 generates the UUID that is the vf\_module\_id and supplies it to the
2959 Heat Orchestration Template at orchestration time.
2961 The parameter must be declared as type: string
2963 Parameter constraints must not be defined.
2965 The parameter must not be enumerated in the Heat environment file.
2967 *Example Parameter Definition*
2969 .. code-block:: yaml
2974 description: Unique ID for this VNF module instance
2979 The vnf\_name parameter is mandatory; it must be included in the Heat
2980 Orchestration Template.
2982 The vnf\_name parameter value will be generated and/or assigned by ONAP
2983 and supplied to the Heat Orchestration Template by ONAP at orchestration
2986 The parameter must be declared as type: string
2988 Parameter constraints must not be defined.
2990 The parameter must not be enumerated in the Heat environment file.
2992 *Example Parameter Definition*
2994 .. code-block:: yaml
2999 description: Unique name for this VNF instance
3004 The vf\_module\_name parameter is optional; it may be included in the
3005 Heat Orchestration Template.
3007 The vf\_module\_name parameter is the name of the name of the Heat stack
3008 (e.g., <STACK\_NAME>) in the command “Heat stack-create” (e.g., Heat
3009 stack-create [-f <FILE>] [-e <FILE>] <STACK\_NAME>). The <STACK\_NAME>
3010 needs to be specified as part of the orchestration process.
3012 The parameter must be declared as type: string
3014 Parameter constraints must not be defined.
3016 The parameter must not be enumerated in the Heat environment file.
3018 *Example Parameter Definition*
3020 .. code-block:: yaml
3025 description: Unique name for this VNF Module instance
3030 The vm\_role parameter is optional; it may be included in the Heat
3031 Orchestration Template.
3033 Any roles tagged to the VMs via metadata will be stored in ONAP’s A&AI
3034 system and available for use by other ONAP components and/or north bound
3037 The vm\_role values must be either
3039 - hard-coded into the Heat Orchestration Template or
3041 - enumerated in the environment file.
3043 Defining the vm\_role as the {vm-type} is a recommended convention
3045 The parameter must be declared as type: string
3047 Parameter constraints must not be defined.
3049 *Example Parameter Definition*
3051 .. code-block:: yaml
3056 description: Unique role for this VM
3058 *Example Resource Definition: Hard Coded*
3060 In this example, the {vm-role} is hard coded in the Heat Orchestration
3063 .. code-block:: yaml
3067 type: OS::Nova::Server
3073 *Example Resource Definition: get\_param*
3075 In this example, the {vm-role} is enumerated in the environment file.
3077 .. code-block:: yaml
3081 type: OS::Nova::Server
3085 vm_role: { get_param: vm_role }
3090 The example below depicts part of a Heat Orchestration Template that
3091 uses the five of the OS::Nova::Server metadata parameter discussed in
3092 this section. The {vm-type} has been defined as lb for load balancer.
3094 .. code-block:: yaml
3099 description: VM Name for lb VM 0
3102 description: Unique name for this VNF instance
3105 description: Unique ID for this VNF instance
3108 description: Unique name for this VNF Module instance
3111 description: Unique ID for this VNF Module instance
3114 description: Unique role for this VM
3119 type: OS::Nova::Server
3121 name: { get_param: lb_name_0 }
3124 vnf_name: { get_param: vnf_name }
3125 vnf_id: { get_param: vnf_id }
3126 vf_module_name: { get_param: vf_module_name }
3127 vf_module_id: { get_param: vf_module_id }
3130 Resource: OS::Neutron::Port - Parameters
3131 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3133 The resource OS::Neutron::Port is for managing Neutron ports (See
3134 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Port.)
3139 Four properties of the resource OS::Neutron::Port that must follow the
3140 ONAP parameter naming convention. The four properties are:
3144 2. fixed\_ips, ip\_address
3146 3. fixed\_ips, subnet\_id
3148 4. allowed\_address\_pairs, ip\_address
3150 The parameters associated with these properties may reference an
3151 external network or internal network. External networks and internal
3152 networks are defined in `Networking`_.
3157 When the parameter references an external network
3159 - the parameter name must contain {network-role}
3161 - the parameter must not be enumerated in the Heat environment file
3163 - the parameter is classified as an ONAP Orchestration Parameter
3165 +----------------------------------------+-----------------------------------------------+--------------------------+
3166 | Property Name | ONAP Parameter Name | Parameter Type |
3167 +========================================+===============================================+==========================+
3168 | network | {network-role}\_net\_id | string |
3169 +----------------------------------------+-----------------------------------------------+--------------------------+
3170 | | {network-role}\_net\_name | string |
3171 +----------------------------------------+-----------------------------------------------+--------------------------+
3172 | fixed\_ips, ip\_address | {vm-type}\_{network-role}\_ip\_{index} | string |
3173 +----------------------------------------+-----------------------------------------------+--------------------------+
3174 | | {vm-type}\_{network-role}\_ips | comma\_delimited\_list |
3175 +----------------------------------------+-----------------------------------------------+--------------------------+
3176 | | {vm-type}\_{network-role}\_v6\_ip\_{index} | string |
3177 +----------------------------------------+-----------------------------------------------+--------------------------+
3178 | | {vm-type}\_{network-role}\_v6\_ips | comma\_delimited\_list |
3179 +----------------------------------------+-----------------------------------------------+--------------------------+
3180 | fixed\_ips, subnet | {network-role}\_subnet\_id | string |
3181 +----------------------------------------+-----------------------------------------------+--------------------------+
3182 | | {network-role}\_v6\_subnet\_id | string |
3183 +----------------------------------------+-----------------------------------------------+--------------------------+
3184 | allowed\_address\_pairs, ip\_address | {vm-type}\_{network-role}\_floating\_ip | string |
3185 +----------------------------------------+-----------------------------------------------+--------------------------+
3186 | | {vm-type}\_{network-role}\_floating\_v6\_ip | string |
3187 +----------------------------------------+-----------------------------------------------+--------------------------+
3188 | | {vm-type}\_{network-role}\_ip\_{index} | string |
3189 +----------------------------------------+-----------------------------------------------+--------------------------+
3190 | | {vm-type}\_{network-role}\_ips | comma\_delimited\_list |
3191 +----------------------------------------+-----------------------------------------------+--------------------------+
3192 | | {vm-type}\_{network-role}\_v6\_ip\_{index} | string |
3193 +----------------------------------------+-----------------------------------------------+--------------------------+
3194 | | {vm-type}\_{network-role}\_v6\_ips | comma\_delimited\_list |
3195 +----------------------------------------+-----------------------------------------------+--------------------------+
3197 Table 5: OS::Neutron::Port Resource Property Parameters (External
3203 When the parameter references an internal network
3205 - the parameter name must contain int\_{network-role}
3207 - the parameter may be enumerated in the environment file.
3209 +----------------------------------------+----------------------------------------------------+--------------------------+
3210 | Property | Parameter Name for Internal Networks | Parameter Type |
3211 +========================================+====================================================+==========================+
3212 | network | int\_{network-role}\_net\_id | string |
3213 +----------------------------------------+----------------------------------------------------+--------------------------+
3214 | | int\_{network-role}\_net\_name | string |
3215 +----------------------------------------+----------------------------------------------------+--------------------------+
3216 | fixed\_ips, ip\_address | {vm-type}\_int\_{network-role}\_ip\_{index} | string |
3217 +----------------------------------------+----------------------------------------------------+--------------------------+
3218 | | {vm-type}\_int\_{network-role}\_ips | comma\_delimited\_list |
3219 +----------------------------------------+----------------------------------------------------+--------------------------+
3220 | | {vm-type}\_int\_{network-role}\_v6\_ip\_{index} | string |
3221 +----------------------------------------+----------------------------------------------------+--------------------------+
3222 | | {vm-type}\_int\_{network-role}\_v6\_ips | comma\_delimited\_list |
3223 +----------------------------------------+----------------------------------------------------+--------------------------+
3224 | fixed\_ips, subnet | int\_{network-role}\_subnet\_id | string |
3225 +----------------------------------------+----------------------------------------------------+--------------------------+
3226 | | int\_{network-role}\_v6\_subnet\_id | string |
3227 +----------------------------------------+----------------------------------------------------+--------------------------+
3228 | allowed\_address\_pairs, ip\_address | {vm-type}\_int\_{network-role}\_floating\_ip | string |
3229 +----------------------------------------+----------------------------------------------------+--------------------------+
3230 | | {vm-type}\_int\_{network-role}\_floating\_v6\_ip | string |
3231 +----------------------------------------+----------------------------------------------------+--------------------------+
3232 | | {vm-type}\_int\_{network-role}\_ip\_{index} | string |
3233 +----------------------------------------+----------------------------------------------------+--------------------------+
3234 | | {vm-type}\_int\_{network-role}\_ips | comma\_delimited\_list |
3235 +----------------------------------------+----------------------------------------------------+--------------------------+
3236 | | {vm-type}\_int\_{network-role}\_v6\_ip\_{index} | string |
3237 +----------------------------------------+----------------------------------------------------+--------------------------+
3238 | | {vm-type}\_int\_{network-role}\_v6\_ips | comma\_delimited\_list |
3239 +----------------------------------------+----------------------------------------------------+--------------------------+
3241 Table 6: Port Resource Property Parameters (Internal Networks)
3246 The property networks in the resource OS::Neutron::Port must be
3247 referenced by Neutron Network ID, a UUID value, or by the network name
3248 defined in OpenStack.
3253 When the parameter associated with the property network is referencing
3254 an “external” network, the parameter must adhere to the following naming
3255 convention in the Heat Orchestration Template
3257 - {network-role}\_net\_id for the Neutron network ID
3259 - {network-role}\_net\_name for the network name in OpenStack
3261 The parameter must be declared as type: string
3263 The parameter must not be enumerated in the Heat environment file.
3265 *Example Parameter Definition*
3267 .. code-block:: yaml
3270 {network-role}_net_id:
3272 description: Neutron UUID for the {network-role} network
3273 {network-role}_net_name:
3275 description: Neutron name for the {network-role} network
3277 *Example: One Cloud Assigned IP Address (DHCP) assigned to a network
3278 that has only one subnet*
3280 In this example, the {network-role} has been defined as oam to represent
3281 an oam network and the {vm-type} has been defined as lb for load
3282 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3283 to assign IP addresses.
3285 .. code-block:: yaml
3290 description: Neutron UUID for the oam network
3294 type: OS::Neutron::Port
3295 network: { get_param: oam_net_id }
3300 When the parameter associated with the property network is referencing
3301 an “internal” network, the parameter must adhere to the following naming
3304 - int\_{network-role}\_net\_id for the Neutron network ID
3306 - int\_{network-role}\_net\_name for the network name in OpenStack
3308 The parameter must be declared as type: string
3310 The assumption is that internal networks are created in the base module.
3311 The Neutron Network ID will be passed as an output parameter (e.g., ONAP
3312 Base Module Output Parameter) to the incremental modules. In the
3313 incremental modules, it will be defined as input parameter.
3315 *Example Parameter Definition*
3317 .. code-block:: yaml
3320 int_{network-role}_net_id:
3322 description: Neutron UUID for the {network-role} network
3323 int_{network-role}_net_name:
3325 description: Neutron name for the {network-role} network
3327 Property: fixed\_ips, Map Property: subnet\_id
3328 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3330 The property fixed\_ips is used to assign IPs to a port. The Map
3331 Property subnet\_id specifies the subnet the IP is assigned from.
3333 The property fixed\_ips and Map Property subnet\_id must be used if a
3334 Cloud (i.e., DHCP) IP address assignment is being requested and the
3335 Cloud IP address assignment is targeted at a specific subnet when two or
3338 The property fixed\_ips and Map Property subnet\_id should not be used
3339 if all IP assignments are fixed, or if the Cloud IP address assignment
3340 does not target a specific subnet or there is only one subnet.
3342 Note that DHCP assignment of IP addresses is also referred to as cloud
3343 assigned IP addresses.
3345 Subnet of an External Networks
3346 +++++++++++++++++++++++++++++
3348 When the parameter is referencing a subnet of an “external” network, the
3349 property fixed\_ips and Map Property subnet\_id parameter must adhere to
3350 the following naming convention.
3352 - {network-role}\_subnet\_id if the subnet is an IPv4 subnet
3354 - {network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
3356 The parameter must be declared as type: string
3358 The parameter must not be enumerated in the Heat environment file.
3360 *Example Parameter Definition*
3362 .. code-block:: yaml
3365 {network-role}_subnet_id:
3367 description: Neutron subnet UUID for the {network-role} network
3369 {network-role}_v6_subnet_id:
3371 description: Neutron subnet UUID for the {network-role} network
3373 *Example: One Cloud Assigned IPv4 Address (DHCP) assigned to a network
3374 that has two or more subnets subnet:*
3376 In this example, the {network-role} has been defined as oam to represent
3377 an oam network and the {vm-type} has been defined as lb for load
3378 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3379 to assign IP addresses.
3381 .. code-block:: yaml
3386 description: Neutron UUID for the oam network
3390 description: Neutron subnet UUID for the oam network
3394 type: OS::Neutron::Port
3395 network: { get_param: oam_net_id }
3397 - subnet_id: { get_param: oam_subnet_id }
3399 *Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6
3400 address assigned to a network that has at least one IPv4 subnet and one
3403 In this example, the {network-role} has been defined as oam to represent
3404 an oam network and the {vm-type} has been defined as lb for load
3407 .. code-block:: yaml
3412 description: Neutron UUID for the oam network
3416 description: Neutron subnet UUID for the oam network
3420 description: Neutron subnet UUID for the oam network
3424 type: OS::Neutron::Port
3426 network: { get_param: oam_net_id }
3428 - subnet_id: { get_param: oam_subnet_id }
3429 - subnet_id: { get_param: oam_v6_subnet_id }
3434 When the parameter is referencing the subnet of an “internal” network,
3435 the property fixed\_ips and Map Property subnet\_id parameter must
3436 adhere to the following naming convention.
3438 - int\_{network-role}\_subnet\_id if the subnet is an IPv4 subnet
3440 - int\_{network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
3442 The parameter must be declared as type: string
3444 The assumption is that internal networks are created in the base module.
3445 The Neutron subnet network ID will be passed as an output parameter
3446 (e.g., ONAP Base Module Output Parameter) to the incremental modules. In
3447 the incremental modules, it will be defined as input parameter.
3449 *Example Parameter Definition*
3451 .. code-block:: yaml
3454 int_{network-role}_subnet_id:
3456 description: Neutron subnet UUID for the {network-role} network
3458 int_{network-role}_v6_subnet_id:
3460 description: Neutron subnet UUID for the {network-role} network
3462 Property: fixed\_ips, Map Property: ip\_address
3463 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3465 The property fixed\_ips is used to assign IPs to a port. The Map
3466 Property ip\_address specifies the IP address to be assigned to the
3469 The property fixed\_ips and Map Property ip\_address must be used when
3470 statically assigning one or more IP addresses to a port. This is also
3471 referred to as ONAP SDN-C IP address assignment. ONAP’s SDN-C provides
3472 the IP address assignment.
3474 An IP address is assigned to a port on a VM (referenced by {vm-type})
3475 that is connected to an external network (referenced by {network-role})
3476 or internal network (referenced by int\_{network-role}).
3478 When a SDN-C IP assignment is made to a port connected to an external
3479 network, the parameter name must contain {vm-type} and {network-role}.
3481 When a SDN-C IP assignment is made to a port connected to an internal
3482 network, the parameter name must contain {vm-type} and
3483 int\_{network-role}.
3485 IP Address Assignments on External Networks
3486 +++++++++++++++++++++++++++++++++++++++
3488 When the property fixed\_ips and Map Property ip\_address is used to
3489 assign IP addresses to an external network, the parameter name is
3490 dependent on the parameter type (comma\_delimited\_list or string) and
3491 IP address type (IPv4 or IPv6).
3493 When the parameter for property fixed\_ips and Map Property ip\_address
3494 is declared type: comma\_delimited\_list, the parameter must adhere to
3495 the following naming convention
3497 - {vm-type}\_{network-role}\_ips for IPv4 address
3499 - {vm-type}\_{network-role}\_v6\_ips for IPv6 address
3501 Each element in the IP list should be assigned to successive instances
3502 of {vm-type} on {network-role}.
3504 The parameter must not be enumerated in the Heat environment file.
3506 *Example Parameter Definition*
3508 .. code-block:: yaml
3512 {vm-type}_{network-role}_ips:
3513 type: comma_delimited_list
3514 description: Fixed IPv4 assignments for {vm-type} VMs on the {Network-role} network
3516 {vm-type}_{network-role}_v6_ips:
3517 type: comma_delimited_list
3518 description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
3520 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
3521 Assignments to an external network*
3523 In this example, the {network-role} has been defined as oam to represent
3524 an oam network and the {vm-type} has been defined as db for database.
3526 .. code-block:: yaml
3531 description: Neutron UUID for a oam network
3534 type: comma_delimited_list
3535 description: Fixed IPv4 assignments for db VMs on the oam network
3538 type: comma_delimited_list
3539 description: Fixed IPv6 assignments for db VMs on the oam network
3543 type: OS::Neutron::Port
3544 network: { get_param: oam_net_id }
3545 fixed_ips: [ { “ip_address”: {get_param: [ db_oam_ips, 0 ]}}, {“ip_address”: {get_param: [ db_oam_v6_ips, 0 ]}}]
3548 type: OS::Neutron::Port
3550 network: { get_param: oam_net_id }
3552 - “ip_address”: {get_param: [ db_oam_ips, 1 ]}
3553 - “ip_address”: {get_param: [ db_oam_v6_ips, 1 ]}
3555 When the parameter for property fixed\_ips and Map Property ip\_address
3556 is declared type: string, the parameter must adhere to the following
3559 - {vm-type}\_{network-role}\_ip\_{index} for an IPv4 address
3561 - {vm-type}\_{network-role}\_v6\_ip\_{index} for an IPv6 address
3563 The value for {index} must start at zero (0) and increment by one.
3565 The parameter must not be enumerated in the Heat environment file.
3567 *Example Parameter Definition*
3569 .. code-block:: yaml
3572 {vm-type}_{network-role}_ip_{index}:
3574 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
3576 {vm-type}_{network-role}_v6_ip_{index}:
3578 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
3580 *Example: string parameters for IPv4 and IPv6 Address Assignments to an external network*
3582 In this example, the {network-role} has been defined as “oam” to
3583 represent an oam network and the {vm-type} has been defined as “db” for
3586 .. code-block:: yaml
3591 description: Neutron UUID for an OAM network
3595 description: Fixed IPv4 assignment for db VM 0 on the OAM network
3599 description: Fixed IPv4 assignment for db VM 1 on the OAM network
3603 description: Fixed IPv6 assignment for db VM 0 on the OAM network
3607 description: Fixed IPv6 assignment for db VM 1 on the OAM network
3611 type: OS::Neutron::Port
3613 network: { get_param: oam_net_id }
3614 fixed_ips: [ { “ip_address”: {get_param: db_oam_ip_0}}, {“ip_address”: {get_param: db_oam_v6_ip_0 ]}}]
3617 type: OS::Neutron::Port
3619 network: { get_param: oam_net_id }
3621 - “ip_address”: {get_param: db_oam_ip_1}}]
3622 - “ip_address”: {get_param: db_oam_v6_ip_1}}]
3624 IP Address Assignment on Internal Networks
3625 ++++++++++++++++++++++++++++++++++++++
3627 When the property fixed\_ips and Map Property ip\_address is used to
3628 assign IP addresses to an internal network, the parameter name is
3629 dependent on the parameter type (comma\_delimited\_list or string) and
3630 IP address type (IPv4 or IPv6).
3632 When the parameter for property fixed\_ips and Map Property ip\_address
3633 is declared type: comma\_delimited\_list, the parameter must adhere to
3634 the following naming convention
3636 - {vm-type}\_int\_{network-role}\_ips for IPv4 address
3638 - {vm-type}\_int\_{network-role}\_v6\_ips for IPv6 address
3640 Each element in the IP list should be assigned to successive instances
3641 of {vm-type} on {network-role}.
3643 The parameter must be enumerated in the Heat environment file. Since an
3644 internal network is local to the VNF, IP addresses can be re-used at
3647 *Example Parameter Definition*
3649 .. code-block:: yaml
3653 {vm-type}_int_{network-role}_ips:
3654 type: comma_delimited_list
3655 description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
3657 {vm-type}_int_{network-role}_v6_ips:
3658 type: comma_delimited_list
3659 description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
3661 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
3662 Assignments to an internal network*
3664 In this example, the {network-role} has been defined as oam\_int to
3665 represent an oam network internal to the vnf. The role oam\_int was
3666 picked to differentiate from an external oam network with a
3667 {network-role} of oam. The {vm-type} has been defined as db for
3670 .. code-block:: yaml
3675 description: Neutron UUID for the oam internal network
3678 type: comma_delimited_list
3679 description: Fixed IPv4 assignments for db VMs on the oam internal network
3681 db_int_oam_int_v6_ips:
3682 type: comma_delimited_list
3683 description: Fixed IPv6 assignments for db VMs on the oam internal network
3687 type: OS::Neutron::Port
3689 network: { get_param: int_oam_int_net_id }
3690 fixed_ips: [ { “ip_address”: {get_param: [ db_int_oam_int_ips, 0]}}, { “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 0 ]}}]
3693 type: OS::Neutron::Port
3695 network: { get_param: int_oam_int_net_id }
3697 - “ip_address”: {get_param: [ db_int_oam_int_ips, 1 ]}
3698 - “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 1 ]}
3700 When the parameter for property fixed\_ips and Map Property ip\_address
3701 is declared type: string, the parameter must adhere to the following
3704 - {vm-type}\_int\_{network-role}\_ip\_{index} for an IPv4 address
3706 - {vm-type}\_int\_{network-role}\_v6\_ip\_{index} for an IPv6 address
3708 The value for {index} must start at zero (0) and increment by one.
3710 The parameter must be enumerated in the Heat environment file. Since an
3711 internal network is local to the VNF, IP addresses can be re-used at
3714 *Example Parameter Definition*
3716 .. code-block:: yaml
3720 {vm-type}_int_{network-role}_ip_{index}:
3722 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
3724 {vm-type}_int_{network-role}_v6_ip_{index}:
3726 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
3728 *Example: string parameters for IPv4 and IPv6 Address Assignments to an internal network*
3730 In this example, the {network-role} has been defined as oam\_int to
3731 represent an oam network internal to the vnf. The role oam\_int was
3732 picked to differentiate from an external oam network with a
3733 {network-role} of oam. The {vm-type} has been defined as db for
3736 .. code-block:: yaml
3741 description: Neutron UUID for an OAM internal network
3745 description: Fixed IPv4 assignment for db VM on the oam_int network
3749 description: Fixed IPv4 assignment for db VM 1 on the oam_int network
3753 description: Fixed IPv6 assignment for db VM 0 on the oam_int network
3757 description: Fixed IPv6 assignment for db VM 1 on the oam_int network
3761 type: OS::Neutron::Port
3763 network: { get_param: int_oam_int_net_id }
3764 fixed_ips: [ { “ip_address”: {get_param: db_oam_int_ip_0}}, {“ip_address”: {get_param: db_oam_int_v6_ip_0 ]}}]
3767 type: OS::Neutron::Port
3769 network: { get_param: int_oam_int_net_id }
3771 - “ip_address”: {get_param: db_oam_int_ip_1}}]
3772 - “ip_address”: {get_param: db_oam_int_v6_ip_1}}]
3774 Property: allowed\_address\_pairs, Map Property: ip\_address
3775 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3777 The property allowed\_address\_pairs in the resource OS::Neutron::Port
3778 allows the user to specify a mac\_address and/or ip\_address that will
3779 pass through a port regardless of subnet. This enables the use of
3780 protocols such as VRRP, which floats an IP address between two instances
3781 to enable fast data plane failover. The map property ip\_address
3782 specifies the IP address.
3784 The allowed\_address\_pairs is an optional property. It is not required.
3786 An ONAP Heat Orchestration Template allows the assignment of one IPv4
3787 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
3788 and {network-role}/int\_{network-role} combination.
3790 An ONAP Heat Orchestration Template allows the assignment of one IPv6
3791 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
3792 and {network-role}/int\_{network-role} combination.
3794 Note that the management of these IP addresses (i.e. transferring
3795 ownership between active and standby VMs) is the responsibility of the
3798 Note that these parameters are **not** intended to represent Neutron
3799 “Floating IP” resources, for which OpenStack manages a pool of public IP
3800 addresses that are mapped to specific VM ports. In that case, the
3801 individual VMs are not even aware of the public IPs, and all assignment
3802 of public IPs to VMs is via OpenStack commands. ONAP does not support
3803 Neutron-style Floating IPs.
3808 When the parameter is referencing an “external” network, the property
3809 allowed\_address\_pairs and Map Property ip\_address parameter must
3810 adhere to the following naming convention.
3812 - {vm-type}\_{network-role}\_floating\_ip for an IPv4 address
3814 - {vm-type}\_{network-role}\_floating\_v6\_ip for an IPv6 address
3816 The parameter must be declared as type: string
3818 The parameter must not be enumerated in the Heat environment file.
3820 *Example Parameter Definition*
3822 .. code-block:: yaml
3826 {vm-type}_{network-role}_floating_ip:
3828 description: VIP for {vm-type} VMs on the {network-role} network
3830 {vm-type}_{network-role}_floating_v6_ip:
3832 description: VIP for {vm-type} VMs on the {network-role} network
3836 In this example, the {network-role} has been defined as oam to represent
3837 an oam network and the {vm-type} has been defined as db for database.
3839 .. code-block:: yaml
3844 description: Neutron UUID for the oam network
3847 type: comma_delimited_list
3848 description: Fixed IPs for db VMs on the oam network
3852 description: VIP IP for db VMs on the oam network
3856 type: OS::Neutron::Port
3858 network: { get_param: oam_net_id }
3859 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,0] }}]
3860 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
3863 type: OS::Neutron::Port
3865 network: { get_param: oam_net_id }
3866 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,1] }}]
3867 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
3872 When the parameter is referencing an “internal” network, the property
3873 allowed\_address\_pairs and Map Property ip\_address parameter must
3874 adhere to the following naming convention.
3876 - {vm-type}\_int\_{network-role}\_floating\_ip for an IPv4 address
3878 - {vm-type}\_int\_{network-role}\_floating\_v6\_ip for an IPv6 address
3880 The parameter must be declared as type: string
3882 The parameter must be enumerated in the Heat environment file.
3884 *Example Parameter Definition*
3886 .. code-block:: yaml
3890 {vm-type}_int_{network-role}_floating_ip:
3892 description: VIP for {vm-type} VMs on the int_{network-role} network
3894 {vm-type}_int_{network-role}_floating_v6_ip:
3896 description: VIP for {vm-type} VMs on the int_{network-role} network
3898 Multiple allowed\_address\_pairs for a {vm-type} / {network-role} combination
3899 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3901 The parameter {vm-type}\_{network-role}\_floating\_ip provides only one
3902 allowed address pair IPv4 address per {vm-type} and {network-role} pair.
3904 The parameter {vm-type}\_{network-role}\_floating\_v6\_ip provides only
3905 one allowed address pair IPv6 address per {vm-type} and {network-role}
3908 If there is a need for multiple allowed address pair IPs for a given
3909 {vm-type} and {network-role} combination within a VNF, then the
3910 parameter names defined for the property fixed\_ips and Map Property
3911 ip\_address should be used with the allowed\_address\_pairs property.
3912 The examples below illustrate this.
3914 *Example: A VNF has four load balancers. Each pair has a unique VIP.*
3916 In this example, there are two administrative VM pairs. Each pair has
3917 one VIP. The {network-role} has been defined as oam to represent an oam
3918 network and the {vm-type} has been defined as admin for an
3921 Pair 1: Resources admin\_0\_port\_0 and admin\_1\_port\_0 share a unique
3922 VIP, [admin\_oam\_ips,2]
3924 Pair 2: Resources admin\_2\_port\_0 and admin\_3\_port\_0 share a unique
3925 VIP, [admin\_oam\_ips,5]
3927 .. code-block:: yaml
3932 description: Neutron UUID for the oam network
3934 type: comma_delimited_list
3935 description: Fixed IP assignments for admin VMs on the oam network
3940 type: OS::Neutron::Port
3942 network: { get_param: oam_net_id }
3943 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,0] }}]
3944 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
3947 type: OS::Neutron::Port
3949 network: { get_param: oam_net_id }
3950 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,1] }}]
3951 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
3954 type: OS::Neutron::Port
3956 network: { get_param: oam_net_id }
3957 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,3] }}]
3958 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
3961 type: OS::Neutron::Port
3963 network: { get_param: oam_net_id }
3964 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,4] }}]
3965 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
3967 *Example: A VNF has two load balancers. The pair of load balancers share
3970 In this example, there is one load balancer pairs. The pair has two
3971 VIPs. The {network-role} has been defined as oam to represent an oam
3972 network and the {vm-type} has been defined as lb for a load balancer VM.
3974 .. code-block:: yaml
3978 type: OS::Neutron::Port
3980 network: { get_param: oam_net_id }
3981 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,0] }}]
3982 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
3985 type: OS::Neutron::Port
3987 network: { get_param: oam_net_id }
3988 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,1] }}]
3989 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
3991 As a general rule, provide the fixed IPs for the VMs indexed first in
3992 the CDL and then the VIPs as shown in the examples above.
3994 ONAP SDN-C Assignment of allowed\_address\_pair IP Addresses
3995 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3997 The following items must be taken into consideration when designing Heat
3998 Orchestration Templates that expect ONAP’s SDN-C to assign
3999 allowed\_address\_pair IP addresses via automation.
4001 The VMs must be of the same {vm-type}.
4003 The VMs must be created in the same module (base or incremental).
4005 Resource Property “name”
4006 ^^^^^^^^^^^^^^^^^^^^^^^
4008 The parameter naming convention of the property name for the resource
4009 OS::Nova::Server has been defined in `Resource: OS::Nova::Server – Metadata Parameters`_.
4011 This section provides the requirements how the property name for non
4012 OS::Nova::Server resources must be defined when the property is used.
4013 Not all resources require the property name (e.g., it is optional) and
4014 some resources do not support the property.
4016 When the property name for a non OS::Nova::Server resources is defined
4017 in a Heat Orchestration Template, the intrinsic function str\_replace
4018 must be used in conjunction with the ONAP supplied metadata parameter
4019 vnf\_name to generate a unique value. This prevents the enumeration of a
4020 unique value for the property name in a per instance environment file.
4024 - In most cases, only the use of the metadata value vnf\_name is
4025 required to create a unique property name
4027 - the Heat Orchestration Template pseudo parameter 'OS::stack\_name’
4028 may also be used in the str\_replace construct to generate a unique
4029 name when the vnf\_name does not provide uniqueness
4031 *Example: Property* name *for resource* OS::Neutron::SecurityGroup
4033 .. code-block:: yaml
4037 type: OS::Neutron::SecurityGroup
4039 description: vDNS security group
4042 template: VNF_NAME_sec_grp_DNS
4044 VNF_NAME: {get_param: vnf_name}
4048 *Example: Property name for resource* OS::Cinder::Volume
4050 .. code-block:: yaml
4054 type: OS::Cinder::Volume
4056 description: Cinder Volume
4059 template: VNF_NAME_STACK_NAME_dns_volume
4061 VNF_NAME: {get_param: vnf_name}
4062 STACK_NAME: { get_param: 'OS::stack_name' }
4065 Contrail Issue with Values for the Property Name
4066 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4068 The Contrail GUI has a limitation displaying special characters. The
4069 issue is documented in
4070 https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is
4071 recommended that special characters be avoided. However, if special
4072 characters must be used, note that for the following resources:
4086 the only special characters supported are:
4088 - “ ! $ ‘ ( ) = ~ ^ \| @ \` { } [ ] > , . \_
4090 ONAP Output Parameter Names
4091 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4093 ONAP defines three types of Output Parameters as detailed in `Output Parameters`_.
4095 ONAP Base Module Output Parameters:
4096 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4098 ONAP Base Module Output Parameters do not have an explicit naming
4099 convention. The parameter name must contain {vm-type} and {network-role}
4102 ONAP Volume Template Output Parameters:
4103 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4105 ONAP Base Module Output Parameters do not have an explicit naming
4106 convention. The parameter name must contain {vm-type} when appropriate.
4108 Predefined Output Parameters
4109 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4111 ONAP currently defines one predefined output parameter the OAM
4112 Management IP Addresses.
4114 OAM Management IP Addresses
4115 +++++++++++++++++++++++++++++
4117 A VNF may have a management interface for application controllers to
4118 interact with and configure the VNF. Typically, this will be via a
4119 specific VM that performs a VNF administration function. The IP address
4120 of this interface must be captured and inventoried by ONAP. The IP
4121 address might be a VIP if the VNF contains an HA pair of management VMs,
4122 or may be a single IP address assigned to one VM.
4124 The Heat template may define either (or both) of the following Output
4125 parameters to identify the management IP address.
4127 - oam\_management\_v4\_address
4129 - oam\_management\_v6\_address
4133 - The use of this output parameters are optional.
4135 - The Management IP Address should be defined only once per VNF, so it
4136 must only appear in one Module template
4138 - If a fixed IP for the admin VM is passed as an input parameter, it
4139 may be echoed in the output parameters. In this case, a IPv4 and/or
4140 IPv6 parameter must be defined in the parameter section of the YAML
4141 Heat template. The parameter maybe named oam\_management\_v4\_address
4142 and/or oam\_management\_v6\_address or may be named differently.
4144 - If the IP for the admin VM is obtained via DHCP, it may be obtained
4145 from the resource attributes. In this case,
4146 oam\_management\_v4\_address and/or oam\_management\_v6\_address must
4147 not be defined in the parameter section of the YAML Heat template.
4149 *Example: SDN-C Assigned IP Address echoed as*
4150 oam\_management\_v4\_address
4152 .. code-block:: yaml
4157 description: Fixed IPv4 assignment for admin VM 0 on the OAM network
4161 admin_oam_net_0_port:
4162 type: OS::Neutron::Port
4166 template: VNF_NAME_admin_oam_net_0_port
4168 VNF_NAME: {get_param: vnf_name}
4169 network: { get_param: oam_net_id }
4170 fixed_ips: [{ "ip_address": { get_param: admin_oam_ip_0 }}]
4171 security_groups: [{ get_param: security_group }]
4174 type: OS::Nova::Server
4176 name: { get_param: admin_names }
4177 image: { get_param: admin_image_name }
4178 flavor: { get_param: admin_flavor_name }
4179 availability_zone: { get_param: availability_zone_0 }
4181 - port: { get_resource: admin_oam_net_0_port }
4183 vnf_id: { get_param: vnf_id }
4184 vf_module_id: { get_param: vf_module_id }
4185 vnf_name: {get_param: vnf_name }
4187 oam_management_v4_address:
4188 value: {get_param: admin_oam_ip_0 }
4190 *Example: Cloud Assigned IP Address output as*
4191 oam\_management\_v4\_address
4193 .. code-block:: yaml
4198 admin_oam_net_0_port:
4199 type: OS::Neutron::Port
4203 template: VNF_NAME_admin_oam_net_0_port
4205 VNF_NAME: {get_param: vnf_name}
4206 network: { get_param: oam_net_id }
4207 security_groups: [{ get_param: security_group }]
4210 type: OS::Nova::Server
4212 name: { get_param: admin_names }
4213 image: { get_param: admin_image_name }
4214 flavor: { get_param: admin_flavor_name }
4215 availability_zone: { get_param: availability_zone_0 }
4217 - port: { get_resource: admin_oam_net_0_port }
4219 vnf_id: { get_param: vnf_id }
4220 vf_module_id: { get_param: vf_module_id }
4221 vnf_name: {get_param: vnf_name }
4224 oam_management_v4_address:
4225 value: {get_attr: [admin_server, networks, {get_param: oam_net_id}, 0] }
4227 Contrail Resource Parameters
4228 ^^^^^^^^^^^^^^^^^^^^^^^^^^
4230 ONAP requires the parameter names of certain Contrail Resources to
4231 follow specific naming conventions. This section provides these
4234 Contrail Network Parameters
4235 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
4237 Contrail based resources may require references to a Contrail network
4238 using the network FQDN.
4243 When the parameter associated with the Contrail Network is referencing
4244 an “external” network, the parameter must adhere to the following naming
4245 convention in the Heat Orchestration Template
4247 - {network-role}\_net\_fqdn
4249 The parameter must be declared as type: string
4251 The parameter must not be enumerated in the Heat environment file.
4253 *Example: Parameter declaration*
4255 .. code-block:: yaml
4258 {network-role}_net_fqdn:
4260 description: Contrail FQDN for the {network-role} network
4262 *Example: Contrail Resource OS::ContrailV2::VirtualMachineInterface
4263 Reference to a Network FQDN.*
4265 In this example, the {network-role} has been defined as oam to represent
4266 an oam network and the {vm-type} has been defined as fw for firewall.
4267 The Contrail resource OS::ContrailV2::VirtualMachineInterface property
4268 virtual\_network\_refs references a contrail network FQDN.
4270 .. code-block:: yaml
4273 type: OS::ContrailV2::VirtualMachineInterface
4277 template: VM_NAME_virtual_machine_interface_1
4279 VM_NAME: { get_param: fw_name_0 }
4280 virtual_machine_interface_properties:
4281 virtual_machine_interface_properties_service_interface_type: { get_param: oam_protected_interface_type }
4282 virtual_network_refs:
4283 - get_param: oam_net_fqdn
4284 security_group_refs:
4285 - get_param: fw_sec_grp_id
4287 Interface Route Table Prefixes for Contrail InterfaceRoute Table
4288 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4290 The parameter associated with the resource
4291 OS::ContrailV2::InterfaceRouteTable property
4292 interface\_route\_table\_routes, map property
4293 interface\_route\_table\_routes\_route\_prefix is an ONAP Orchestration
4296 The parameters must be named {vm-type}\_{network-role}\_route\_prefixes
4297 in the Heat Orchestration Template.
4299 The parameter must be declared as type: json
4301 The parameter supports IP addresses in the format:
4303 1. Host IP Address (e.g., 10.10.10.10)
4305 2. CIDR Notation format (e.g., 10.0.0.0/28)
4307 The parameter must not be enumerated in the Heat environment file.
4309 *Example Parameter Definition*
4311 .. code-block:: yaml
4314 {vm-type}_{network-role}_route_prefixes:
4316 description: JSON list of Contrail Interface Route Table route prefixes
4320 .. code-block:: yaml
4325 description: Unique name for this VF instance
4326 fw_int_fw_route_prefixes:
4328 description: prefix for the ServiceInstance InterfaceRouteTable
4329 int_fw_dns_trusted_interface_type:
4331 description: service_interface_type for ServiceInstance
4334 type: OS::ContrailV2::InterfaceRouteTable
4335 depends_on: [*resource name of* *OS::ContrailV2::ServiceInstance*]
4339 template: VNF_NAME_interface_route_table
4341 VNF_NAME: { get_param: vnf_name }
4342 interface_route_table_routes:
4343 interface_route_table_routes_route: { get_param: fw_int_fw_route_prefixes }
4344 service_instance_refs:
4345 - get_resource: < *resource name of* *OS::ContrailV2::ServiceInstance* >
4346 service_instance_refs_data:
4347 - service_instance_refs_data_interface_type: { get_param: int_fw_interface_type }
4349 Parameter Names in Contrail Resources
4350 ++++++++++++++++++++++++++++++++++
4352 Contrail Heat resource properties will use, when appropriate, the same
4353 naming convention as OpenStack Heat resources. For example, the resource
4354 OS::ContrailV2::InstanceIp has two properties that the parameter naming
4355 convention is identical to properties in OS::Neutron::Port.
4357 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4358 instance\_ip\_address*
4360 The property instance\_ip\_address uses the same parameter naming
4361 convention as the property fixed\_ips and Map Property ip\_address in
4362 OS::Neutron::Port. The resource is assigning an ONAP SDN-C Assigned IP
4363 Address. The {network-role} has been defined as oam\_protected to
4364 represent an oam protected network and the {vm-type} has been defined as
4367 .. code-block:: yaml
4369 CMD_FW_OAM_PROTECTED_RII:
4370 type: OS::ContrailV2::InstanceIp
4372 - FW_OAM_PROTECTED_RVMI
4374 virtual_machine_interface_refs:
4375 - get_resource: FW_OAM_PROTECTED_RVMI
4376 virtual_network_refs:
4377 - get_param: oam_protected_net_fqdn
4378 instance_ip_address: { get_param: [fw_oam_protected_ips, get_param: index ] }
4380 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4383 The property instance\_ip\_address uses the same parameter naming
4384 convention as the property fixed\_ips and Map Property subnet\_id in
4385 OS::Neutron::Port. The resource is assigning a Cloud Assigned IP
4386 Address. The {network-role} has been defined as “oam\_protected” to
4387 represent an oam protected network and the {vm-type} has been defined as
4390 .. code-block:: yaml
4392 CMD_FW_SGI_PROTECTED_RII:
4393 type: OS::ContrailV2::InstanceIp
4395 - FW_OAM_PROTECTED_RVMI
4397 virtual_machine_interface_refs:
4398 - get_resource: FW_OAM_PROTECTED_RVMI
4399 virtual_network_refs:
4400 - get_param: oam_protected_net_fqdn
4401 subnet_uuid: { get_param: oam_protected_subnet_id }
4403 Cinder Volume Templates
4404 ^^^^^^^^^^^^^^^^^^^^^^
4406 ONAP supports the independent deployment of a Cinder volume via separate
4407 Heat Orchestration Templates, the Cinder Volume module. This allows the
4408 volume to persist after VNF deletion so that they can be reused on
4409 another instance (e.g., during a failover activity).
4411 A Base Module or Incremental Module may have a corresponding volume
4412 module. Use of separate volume modules is optional. A Cinder volume may
4413 be embedded within the Base Module or Incremental Module if persistence
4416 If a VNF Base Module or Incremental Module has an independent volume
4417 module, the scope of volume templates must be 1:1 with Base module or
4418 Incremental module. A single volume module must create only the volumes
4419 required by a single Incremental module or Base module.
4421 The following rules apply to independent volume Heat templates:
4423 - Cinder volumes must be created in a separate Heat Orchestration
4424 Template from the Base Module or Incremental Module.
4426 - A single Cinder volume module must include all Cinder volumes
4427 needed by the Base/Incremental module.
4429 - The volume template must define “outputs” for each Cinder volume
4430 resource universally unique identifier (UUID) (i.e. ONAP Volume
4431 Template Output Parameters).
4433 - The VNF Incremental Module or Base Module must define input
4434 parameters that match each Volume output parameter (i.e., ONAP Volume
4435 Template Output Parameters).
4437 - ONAP will supply the volume template outputs automatically to the
4438 bases/incremental template input parameters.
4440 - Volume modules may utilize nested Heat templates.
4442 *Examples: Volume Template*
4444 A VNF has a Cinder volume module, named incremental\_volume.yaml, that
4445 creates an independent Cinder volume for a VM in the module
4446 incremental.yaml. The incremental\_volume.yaml defines a parameter in
4447 the output section, lb\_volume\_id\_0 which is the UUID of the cinder
4448 volume. lb\_volume\_id\_0 is defined as a parameter in incremental.yaml.
4449 ONAP captures the UUID value of lb\_volume\_id\_0 from the volume module
4450 output statement and provides the value to the incremental module.
4452 Note that the example below is not a complete Heat Orchestration
4453 Template. The {vm-type} has been defined as “lb” for load balancer
4455 incremental\_volume.yaml
4457 .. code-block:: yaml
4468 type: OS::Cinder::Volume
4472 template: VNF_NAME_volume_0
4474 VNF_NAME: { get_param: vnf_name }
4475 size: {get_param: dns_volume_size_0}
4480 value: {get_resource: dns_volume_0}
4486 .. code-block:: yaml
4497 type: OS::Nova::Server
4499 name: {get_param: dns_name_0}
4504 type: OS::Cinder::VolumeAttachment
4506 instance_uuid: { get_resource: lb_0 }
4507 volume_id: { get_param: lb_volume_id_0 }
4509 ONAP Support of Environment Files
4510 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4512 The use of an environment file in OpenStack is optional. In ONAP, it is
4513 mandatory. A Heat Orchestration Template uploaded to ONAP must have a
4514 corresponding environment file, even if no parameters are required to be
4517 (Note that ONAP, the open source version of ONAP, does not
4518 programmatically enforce the use of an environment file.)
4520 A Base Module Heat Orchestration Template must have a corresponding
4523 An Incremental Module Heat Orchestration Template must have a
4524 corresponding environment file.
4526 A Cinder Volume Module Heat Orchestration Template must have a
4527 corresponding environment file.
4529 A nested heat template must not have an environment file; OpenStack does
4532 The environment file must contain parameter values for the ONAP
4533 Orchestration Constants and VNF Orchestration Constants. These
4534 parameters are identical across all instances of a VNF type, and
4535 expected to change infrequently. The ONAP Orchestration Constants are
4536 associated with OS::Nova::Server image and flavor properties (See
4537 `Property: image`_ and `Property: flavor`_). Examples of VNF Orchestration Constants are the networking
4538 parameters associated with an internal network (e.g., private IP ranges)
4539 and Cinder volume sizes.
4541 The environment file must not contain parameter values for parameters
4542 that are instance specific (ONAP Orchestration Parameters, VNF
4543 Orchestration Parameters). These parameters are supplied to the Heat by
4544 ONAP at orchestration time.
4546 SDC Treatment of Environment Files
4547 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4549 Parameter values enumerated in the environment file are used by SDC as
4550 the default value. However, the SDC user may use the SDC GUI to
4551 overwrite the default values in the environment file.
4553 SDC generates a new environment file for distribution to MSO based on
4554 the uploaded environment file and the user provided GUI updates. The
4555 user uploaded environment file is discarded when the new file is
4556 created. Note that if the user did not change any values via GUI
4557 updates, the SDC generated environment file will contain the same values
4558 as the uploaded file.
4560 Use of Environment Files when using OpenStack “heat stack-create” CLI
4561 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4563 When ONAP is instantiating the Heat Orchestration Template, certain
4564 parameter must not be enumerated in the environment file. This document
4565 provides the details of what parameters should not be enumerated.
4567 If the Heat Orchestration Template is to be instantiated from the
4568 OpenStack Command Line Interface (CLI) using the command “heat
4569 stack-create”, all parameters must be enumerated in the environment
4572 Heat Template Constructs
4573 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4575 Nested Heat Templates
4576 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4578 ONAP supports nested Heat templates per the OpenStack specifications.
4579 Nested templates may be suitable for larger VNFs that contain many
4580 repeated instances of the same VM type(s). A common usage pattern is to
4581 create a nested template for each {vm-type} along with its supporting
4582 resources. The VNF module may then reference these component templates
4583 either statically by repeated definition or dynamically by using the
4584 resource OS::Heat::ResourceGroup.
4586 Nested Heat Template Requirements
4587 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4589 ONAP supports nested Heat Orchestration Templates. A Base Module,
4590 Incremental Module, and Cinder Volume Module may use nested heat.
4592 A Heat Orchestration Template may reference the nested heat statically
4593 by repeated definition.
4595 A Heat Orchestration Template may reference the nested heat dynamically
4596 using the resource OS::Heat::ResourceGroup.
4598 A Heat Orchestration template must have no more than three levels of
4599 nesting. ONAP supports a maximum of three levels.
4601 Nested heat templates must be referenced by file name. The use of
4602 resource\_registry in the environment file is not supported and must not
4605 A nested heat yaml file must have a unique file names within the scope
4608 ONAP does not support a directory hierarchy for nested templates. All
4609 templates must be in a single, flat directory (per VNF)
4611 A nested heat template may be used by any module within a given VNF.
4615 - Constrains must not be defined for any parameter enumerated in a
4616 nested heat template.
4618 - All parameters defined in nested heat must be passed in as properties
4619 of the resource calling the nested yaml file.
4621 - When OS::Nova::Server metadata parameters are past into a nested heat
4622 template, the parameter names must not change
4624 - With nested templates, outputs are required to expose any resource
4625 properties of the child templates to the parent template. Those would
4626 not explicitly be declared as parameters but simply referenced as
4627 get\_attribute targets against the “parent” resource.
4629 Nested Heat Template Example: Static
4630 +++++++++++++++++++++++++++++++++
4634 .. code-block:: yaml
4640 dns_image_name: { get_param: dns_image_name }
4641 dns_flavor_name: { get_param: dns_flavor_name }
4642 availability_zone: { get_param: availability_zone_0 }
4643 security_group: { get_param: DNS_shared_sec_grp_id }
4644 oam_net_id: { get_param: oam_protected_net_id }
4645 dns_oam_ip: { get_param: dns_oam_ip_0 }
4646 dns_name: { get_param: dns_name_0 }
4647 vnf_name: { get_param: vnf_name }
4648 vnf_id: { get_param: vnf_id }
4649 vf_module_id: {get_param: vf_module_id}
4654 dns_image_name: { get_param: dns_image_name }
4655 dns_flavor_name: { get_param: dns_flavor_name }
4656 availability_zone: { get_param: availability_zone_1 }
4657 security_group: { get_param: DNS_shared_sec_grp_id }
4658 oam_net_id: { get_param: oam_protected_net_id }
4659 dns_oam_ip: { get_param: dns_oam_ip_1 }
4660 dns_name: { get_param: dns_name_1 }
4661 vnf_name: { get_param: vnf_name }
4662 vnf_id: { get_param: vnf_id }
4663 vf_module_id: {get_param: vf_module_id}
4667 .. code-block:: yaml
4670 type: OS::Neutron::Port
4674 template: VNF_NAME_dns_oam_port
4676 VNF_NAME: {get_param: vnf_name}
4677 network: { get_param: oam_net_id }
4678 fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}]
4679 security_groups: [{ get_param: security_group }]
4682 type: OS::Nova::Server
4684 name: { get_param: dns_names }
4685 image: { get_param: dns_image_name }
4686 flavor: { get_param: dns_flavor_name }
4687 availability_zone: { get_param: availability_zone }
4689 - port: { get_resource: dns_oam_0_port }
4691 vnf_id: { get_param: vnf_id }
4692 vf_module_id: { get_param: vf_module_id }
4693 vnf_name {get_param: vnf_name }
4695 Use of Heat ResourceGroup
4696 ~~~~~~~~~~~~~~~~~~~~~~~~~
4698 The OS::Heat::ResourceGroup is a useful Heat element for creating
4699 multiple instances of a given resource or collection of resources.
4700 Typically it is used with a nested Heat template, to create, for
4701 example, a set of identical OS::Nova::Server resources plus their
4702 related OS::Neutron::Port resources via a single resource in a master
4705 ResourceGroup may be used in ONAP to simplify the structure of a Heat
4706 template that creates multiple instances of the same VM type.
4708 However, there are important caveats to be aware of:
4710 ResourceGroup does not deal with structured parameters
4711 (comma-delimited-list and json) as one might typically expect. In
4712 particular, when using a list-based parameter, where each list element
4713 corresponds to one instance of the ResourceGroup, it is not possible to
4714 use the intrinsic “loop variable” %index% in the ResourceGroup
4717 For instance, the following is **not** valid Heat for ResourceGroup:
4719 .. code-block:: yaml
4721 type: OS::Heat::ResourceGroup
4723 type: my_nested_vm_template.yaml
4725 name: {get_param: [vm_name_list, %index%]}
4727 Although this appears to use the nth entry of the vm\_name\_list list
4728 for the nth element of the ResourceGroup, it will in fact result in a
4729 Heat exception. When parameters are provided as a list (one for each
4730 element of a ResourceGroup), you must pass the complete parameter to the
4731 nested template along with the current index as separate parameters.
4733 Below is an example of an **acceptable** Heat Syntax for a
4736 .. code-block:: yaml
4738 type: OS::Heat::ResourceGroup
4740 type: my_nested_vm_template.yaml
4742 names: {get_param: vm_name_list}
4745 You can then reference within the nested template as:
4747 { get\_param: [names, {get\_param: index} ] }
4749 ResourceGroup Property count
4750 +++++++++++++++++++++++++++++++++
4752 ONAP requires that the OS::Heat::ResourceGroup property count be defined
4753 (even if the value is one) and that the value must be enumerated in the
4754 environment file. This is required for ONAP to build the TOSCA model for
4757 .. code-block:: yaml
4759 type: OS::Heat::ResourceGroup
4761 count: { get_param: count }
4764 type: my_nested_vm_template.yaml
4766 names: {get_param: vm_name_list}
4769 Availability Zone and ResourceGroups
4770 +++++++++++++++++++++++++++++++++
4772 The resource OS::Heat::ResourceGroup and the property availability\_zone
4773 has been an “issue” with a few VNFs since ONAP only supports
4774 availability\_zone as a string parameter and not a
4775 comma\_delimited\_list. This makes it difficult to use a ResourceGroup
4776 to create Virtual Machines in more than one availability zone.
4778 There are numerous solutions to this issue. Below are two suggested
4781 **Option 1:** create a CDL in the OS::Heat::ResourceGroup. In the
4782 resource type: OS::Heat::ResourceGroup, create a comma\_delimited\_list
4783 availability\_zones by using the intrinsic function list\_join.
4785 .. code-block:: yaml
4788 type: OS::Heat::ResourceGroup
4790 count: { get_param: node_count }
4796 avaialability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] }
4800 .. code-block:: yaml
4803 avaialability_zones:
4804 type: comma_delimited_list
4809 type: OS::Nova::Server
4811 name: { get_param: [ dns_names, get_param: index ] }
4812 image: { get_param: dns_image_name }
4813 flavor: { get_param: dns_flavor_name }
4814 availability_zone: { get_param: [ avaialability_zones, get_param: index ] }
4817 **Option 2:** Create a resource group per availability zone. A separate
4818 OS::Heat::ResourceGroup is created for each availability zone.
4823 Heat templates *should not* reference any HTTP-based resource
4824 definitions, any HTTP-based nested configurations, or any HTTP-based
4827 - During orchestration, ONAP *should not* retrieve any such resources
4828 from external/untrusted/unknown sources.
4830 - VNF images should not contain such references in user-data or other
4831 configuration/operational scripts that are specified via Heat or
4832 encoded into the VNF image itself.
4834 *Note:* HTTP-based references are acceptable if the HTTP-based reference
4835 is accessing information with the VM private/internal network.
4837 Heat Files Support (get\_file)
4838 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4840 Heat Templates may contain the inclusion of text files into Heat
4841 templates via the Heat get\_file directive. This may be used, for
4842 example, to define a common “user-data” script, or to inject files into
4843 a VM on startup via the “personality” property.
4845 Support for Heat Files is subject to the following limitations:
4847 - The get\_files targets must be referenced in Heat templates by file
4848 name, and the corresponding files should be delivered to ONAP along
4849 with the Heat templates.
4851 - URL-based file retrieval must not be used; it is not supported.
4853 - The included files must have unique file names within the scope of
4856 - ONAP does not support a directory hierarchy for included files.
4858 - All files must be in a single, flat directory per VNF.
4860 - Included files may be used by all Modules within a given VNF.
4862 - get\_file directives may be used in both non-nested and nested
4868 When Nova Servers are created via Heat templates, they may be passed a
4869 “keypair” which provides an ssh key to the ‘root’ login on the newly
4870 created VM. This is often done so that an initial root key/password does
4871 not need to be hard-coded into the image.
4873 Key pairs are unusual in OpenStack, because they are the one resource
4874 that is owned by an OpenStack User as opposed to being owned by an
4875 OpenStack Tenant. As a result, they are usable only by the User that
4876 created the keypair. This causes a problem when a Heat template attempts
4877 to reference a keypair by name, because it assumes that the keypair was
4878 previously created by a specific ONAP user ID.
4880 When a keypair is assigned to a server, the SSH public-key is
4881 provisioned on the VMs at instantiation time. They keypair itself is not
4882 referenced further by the VM (i.e. if the keypair is updated with a new
4883 public key, it would only apply to subsequent VMs created with that
4886 Due to this behavior, the recommended usage of keypairs is in a more
4887 generic manner which does not require the pre-requisite creation of a
4888 keypair. The Heat should be structured in such a way as to:
4890 - Pass a public key as a parameter value instead of a keypair name
4892 - Create a new keypair within the VNF Heat templates (in the base
4893 module) for use within that VNF
4895 By following this approach, the end result is the same as pre-creating
4896 the keypair using the public key – i.e., that public key will be
4897 provisioned in the new VM. However, this recommended approach also makes
4898 sure that a known public key is supplied (instead of having OpenStack
4899 generate a public/private pair to be saved and tracked outside of ONAP).
4900 It also removes any access/ownership issues over the created keypair.
4902 The public keys may be enumerated as a VNF Orchestration Constant in the
4903 environment file (since it is public, it is not a secret key), or passed
4904 at run-time as instance-specific parameters. ONAP will never
4905 automatically assign a public/private key pair.
4907 *Example (create keypair with an existing ssh public-key for {vm-type}
4908 of lb (for load balancer)):*
4910 .. code-block:: yaml
4920 type: OS::Nova::Keypair
4924 template: VNF_NAME_key_pair
4926 VNF_NAME: { get_param: vnf_name }
4927 public_key: {get_param: lb_ssh_public_key}
4928 save_private_key: false
4933 OpenStack allows a tenant to create Security groups and define rules
4934 within the security groups.
4936 Security groups, with their rules, may either be created in the Heat
4937 Orchestration Template or they can be pre-created in OpenStack and
4938 referenced within the Heat template via parameter(s). There can be a
4939 different approach for security groups assigned to ports on internal
4940 (intra-VNF) networks or external networks (inter-VNF). Furthermore,
4941 there can be a common security group across all VMs for a specific
4942 network or it can vary by VM (i.e., {vm-type}) and network type (i.e.,
4945 Anti-Affinity and Affinity Rules
4946 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4948 Anti-affinity or affinity rules are supported using normal OpenStack
4949 OS::Nova::ServerGroup resources. Separate ServerGroups are typically
4950 created for each VM type to prevent them from residing on the same host,
4951 but they can be applied to multiple VM types to extend the
4952 affinity/anti-affinity across related VM types as well.
4956 In this example, the {network-role} has been defined as oam to represent
4957 an oam network and the {vm-type} have been defined as lb for load
4958 balancer and db for database.
4960 .. code-block:: yaml
4964 type: OS::Nova::ServerGroup
4969 $vnf_name: {get_param: vnf_name}
4970 template: $vnf_name-server_group1
4975 type: OS::Nova::ServerGroup
4980 $vnf_name: {get_param: vnf_name}
4981 template: $vnf_name-server_group2
4986 type: OS::Nova::Server
4990 group: {get_resource: db_server_group}
4993 type: OS::Nova::Server
4997 group: {get_resource: db_server_group}
5000 type: OS::Nova::Server
5004 group: {get_resource: lb_server_group}
5006 Resource Data Synchronization
5007 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5009 For cases where synchronization is required in the orchestration of Heat
5010 resources, two approaches are recommended:
5012 - Standard Heat depends\_on property for resources
5014 - Assures that one resource completes before the dependent resource
5017 - Definition of completeness to OpenStack may not be sufficient
5018 (e.g., a VM is considered complete by OpenStack when it is ready
5019 to be booted, not when the application is up and running).
5021 - Use of Heat Notifications
5023 - Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle
5026 - Pre-requisite resources issue *wc\_notify* commands in user\_data.
5028 - Dependent resource define depends\_on in the
5029 OS::Heat::WaitCondition resource.
5031 *Example: “depends\_on” case*
5033 In this example, the {network-role} has been defined as oam to represent
5034 an oam network and the {vm-type} has been defined as oam to represent an
5037 .. code-block:: yaml
5041 type: OS::Nova::Server
5043 name: {get_param: [oam_ names, 0]}
5044 image: {get_param: oam_image_name}
5045 flavor: {get_param: oam_flavor_name}
5046 availability_zone: {get_param: availability_zone_0}
5048 - port: {get_resource: oam01_port_0}
5049 - port: {get_resource: oam01_port_1}
5051 scheduler_hints: {group: {get_resource: oam_servergroup}}
5052 user_data_format: RAW
5055 type: OS::Neutron::Port
5057 network: {get_resource: oam_net_name}
5058 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}]
5059 security_groups: [{get_resource: oam_security_group}]
5062 type: OS::Neutron::Port
5064 network: {get_param: oam_net_name}
5065 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}]
5066 security_groups: [{get_resource: oam_security_group}]
5068 oam_01_vol_attachment:
5069 type: OS::Cinder::VolumeAttachment
5070 depends_on: oam_server_01
5072 volume_id: {get_param: oam_vol_1}
5073 mountpoint: /dev/vdb
5074 instance_uuid: {get_resource: oam_server_01}
5079 VNF/VM parameters may include availability zone IDs for VNFs that
5080 require high availability.
5082 The Heat must comply with the following requirements to specific
5083 availability zone IDs:
5085 - The Heat template should spread Nova and Cinder resources across the
5086 availability zones as desired
5088 Post Orchestration & VNF Configuration
5089 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5091 Heat templates should contain a minimum amount of post-orchestration
5092 configuration data. For instance, *do not* embed complex user-data
5093 scripts in the template with large numbers of configuration parameters
5094 to the Heat template.
5096 - VNFs may provide configuration APIs for use after VNF creation. Such
5097 APIs will be invoked via application and/or SDN controllers.
5099 *Note:* It is important to follow this convention to the extent possible
5100 even in the short-term as of the long-term direction.
5102 VNFM Driver Development Steps
5103 ---------------------------------------------------------
5105 Refer to the ONAP documentation for VNF Provider instructions on integrating
5106 vendor-specific VNFM adaptors with VF-C. The VNF driver development steps are
5109 1. Use the VNF SDK tools to design the VNF with TOSCA models to output
5110 the VNF TOSCA package. Using the VNF SDK tools, the VNF package can be
5111 validated and tested.
5113 2. The VNF Provider supplies a vendor-specific VNFM driver in ONAP, which
5114 is a microservice providing a translation interface from VF-C to
5115 the vendor-specific VNFM. The interface definitions of vendor-specific VNFM adaptors are supplied by
5116 the VNF Providers themselves.
5118 Creating Vendor-Specific VNFM Adaptor Microservices
5119 ------------------------------------------------------------------------------------------------------------------
5121 VNFs can be managed by vendor-specific VNFMs. To add a vendor-specific VNFM to ONAP, a
5122 vendor-specific VNFM adaptor is added to ONAP implementing the interface of the vendor-specific VNFM.
5124 A vendor-specific VNFM adaptor is a microservice with a unique name and an appointed
5125 port. When started up, the vendor-specific VNFM adaptor microservice is automatically registered to the
5126 Microservices Bus (MSB). The following RESTful example describes the scenario of
5127 registering a vendor-specific VNFM adaptor to MSB:
5129 .. code-block:: java
5131 POST /api/microservices/v1/services
5133 "serviceName": "catalog",
5135 "url": "/api/catalog/v1",
5140 "ip": "10.74.56.36",