3 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
4 .. http://creativecommons.org/licenses/by/4.0
5 .. Copyright 2017 AT&T Intellectual Property. All rights reserved.
8 **5. VNF Modeling Requirements**
9 =====================================
18 This reference document is the VNF TOSCA Template Requirements for
19 ONAP, which provides recommendations and standards for building VNF
20 TOSCA templates compatible with ONAP initial implementations of
21 Network Cloud. It has the following features:
23 1. VNF TOSCA template designer supports GUI and CLI.
25 2. VNF TOSCA template is aligned to the newest TOSCA protocol, “Working
26 Draft 04-Revision 06”.
28 3. VNF TOSCA template supports EPA features, such as NUMA, Hyper
29 Threading, SRIOV， etc.
34 This document is intended for persons developing VNF TOSCA templates
35 that will be orchestrated by ONAP.
40 ONAP implementations of Network Cloud supports TOSCA Templates, also
41 referred to as TOSCA in this document.
43 ONAP requires the TOSCA Templates to follow a specific format. This
44 document provides the mandatory, recommended, and optional requirements
45 associated with this format.
50 The document includes three charters to help the VNF providers to use the
51 VNF model design tools and understand the VNF package structure and VNF
54 In the ONAP, VNF Package and VNFD template can be designed by manually
55 or via model designer tools. VNF model designer tools can provide the
56 GUI and CLI tools for the VNF provider to develop the VNF Package and VNFD
59 The VNF package structure is align to the NFV TOSCA protocol, and
62 The VNFD and VNF package are all align to the NFV TOSCA protocol, which
63 supports multiple TOSCA template yaml files, and also supports
64 self-defined node or other extensions.
69 TOSCA templates supported by ONAP must follow the requirements
70 enumerated in this section.
75 TOSCA defines a Meta model for defining IT services. This Meta model
76 defines both the structure of a service as well as how to manage it. A
77 Topology Template (also referred to as the topology model of a service)
78 defines the structure of a service. Plans define the process models that
79 are used to create and terminate a service as well as to manage a
80 service during its whole lifetime.
82 A Topology Template consists of a set of Node Templates and Relationship
83 Templates that together define the topology model of a service as a (not
84 necessarily connected) directed graph. A node in this graph is
85 represented by a *Node Template*. A Node Template specifies the
86 occurrence of a Node Type as a component of a service. A *Node Type*
87 defines the properties of such a component (via *Node Type Properties*)
88 and the operations (via *Interfaces*) available to manipulate the
89 component. Node Types are defined separately for reuse purposes and a
90 Node Template references a Node Type and adds usage constraints, such as
91 how many times the component can occur.
95 Figure 1: Structural Elements of Service Template and their Relations
97 TOSCA Modeling Principles & Data Model
98 --------------------------------------
100 This section describing TOSCA modeling principles and data model for
101 NFV, which shall be based on [TOSCA-1.0] and [TOSCA-Simple-Profile-YAML
102 V1.0], or new type based on ETSI NFV requirements, etc.
104 VNF Descriptor Template
105 -----------------------
107 The VNF Descriptor (VNFD) describes the topology of the VNF by means of
108 ETSI NFV IFA011 [IFA011] terms such as VDUs, Connection Points, Virtual
109 Links, External Connection Points, Scaling Aspects, Instantiation Levels
110 and Deployment Flavours.
112 The VNFD (VNF Descriptor) is read by both the NFVO and the VNFM. It
113 represents the contract & interface of a VNF and ensures the
114 interoperability across the NFV functional blocks.
116 The main parts of the VNFD are the following:
118 - VNF topology: it is modeled in a cloud agnostic way using virtualized
119 containers and their connectivity. Virtual Deployment Units (VDU)
120 describe the capabilities of the virtualized containers, such as
121 virtual CPU, RAM, disks; their connectivity is modeled with VDU
122 Connection Point Descriptors (VduCpd), Virtual Link Descriptors (Vld)
123 and VNF External Connection Point Descriptors (VnfExternalCpd);
125 - VNF deployment aspects: they are described in one or more deployment
126 flavours, including instantiation levels, supported LCM operations,
127 VNF LCM operation configuration parameters, placement constraints
128 (affinity / antiaffinity), minimum and maximum VDU instance numbers,
129 and scaling aspect for horizontal scaling.
131 The following table defines the TOSCA Type “derived from” values that
132 SHALL be used when using the TOSCA Simple Profile for NFV version 1.0
133 specification [TOSCA-Simple-Profile-NFV-v1.0] for NFV VNFD.
135 +-----------------------------------------+---------------------------------------+-----------------------+
136 | **ETSI NFV Element** | **TOSCA VNFD** | **Derived from** |
138 | **[IFA011]** | **[TOSCA-Simple-Profile-NFV-v1.0]** | |
139 +=========================================+=======================================+=======================+
140 | VNF | tosca.nodes.nfv.VNF | tosca.nodes.Root |
141 +-----------------------------------------+---------------------------------------+-----------------------+
142 | VDU | tosca.nodes.nfv.VDU | tosca.nodes.Root |
143 +-----------------------------------------+---------------------------------------+-----------------------+
144 | Cpd (Connection Point) | tosca.nodes.nfv.Cpd | tosca.nodes.Root |
145 +-----------------------------------------+---------------------------------------+-----------------------+
146 | VduCpd (internal connection point) | tosca.nodes.nfv.VduCpd | tosca.nodes.nfv.Cpd |
147 +-----------------------------------------+---------------------------------------+-----------------------+
148 | VnfVirtualLinkDesc (Virtual Link) | tosca.nodes.nfv.VnfVirtualLinkDesc | tosca.nodes.Root |
149 +-----------------------------------------+---------------------------------------+-----------------------+
150 | VnfExtCpd (External Connection Point) | tosca.nodes.nfv.VnfExtCpd | tosca.nodes.Root |
151 +-----------------------------------------+---------------------------------------+-----------------------+
152 | Virtual Storage | | |
153 +-----------------------------------------+---------------------------------------+-----------------------+
154 | Virtual Compute | | |
155 +-----------------------------------------+---------------------------------------+-----------------------+
156 | Software Image | | |
157 +-----------------------------------------+---------------------------------------+-----------------------+
158 | Deployment Flavour | | |
159 +-----------------------------------------+---------------------------------------+-----------------------+
160 | Scaling Aspect | | |
161 +-----------------------------------------+---------------------------------------+-----------------------+
162 | Element Group | | |
163 +-----------------------------------------+---------------------------------------+-----------------------+
164 | Instantiation Level | | |
165 +-----------------------------------------+---------------------------------------+-----------------------+
167 +--------------------------------------------------------------------+
168 | +--------------------------------------------------------------+ |
169 | | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 | |
171 | | description: VNFD TOSCA file demo | |
175 | | - TOSCA\_definition\_nfv\_1\_0.yaml | |
177 | | - TOSCA\_definition\_nfv\_ext\_1\_0.yaml | |
179 | | | **node\_types: | |
180 | | tosca.nodes.nfv.VNF.vOpenNAT: | |
181 | | derived\_from:** tosca.nodes.nfv.VNF | |
182 | | | **requirements: | |
183 | | **- **sriov\_plane: | |
184 | | capability:** tosca.capabilities.nfv.VirtualLinkable | |
185 | | | **node:** tosca.nodes.nfv.VnfVirtualLinkDesc | |
186 | | | **relationship:** tosca.relationships.nfv.VirtualLinksTo | |
187 | +--------------------------------------------------------------+ |
188 +====================================================================+
189 +--------------------------------------------------------------------+
194 1. SR-IOV Passthrought
196 Definitions of SRIOV\_Port are necessary if VDU supports SR-IOV. Here is
199 +------------------------------------------------+
208 | tosca\_name: SRIOV\_Port |
212 | virtual\_network\_interface\_requirements: |
216 | support\_mandatory: false |
218 | description: sriov |
226 | description: sriov port |
228 | layer\_protocol: ipv4 |
232 | - virtual\_binding: |
234 | capability: virtual\_binding |
240 | type: tosca.relationships.nfv.VirtualBindsTo |
244 | node: tosca.nodes.Root |
246 | type: tosca.nodes.nfv.VduCpd |
248 | substitution\_mappings: |
258 | node\_type: tosca.nodes.nfv.VNF.vOpenNAT |
259 +------------------------------------------------+
263 Definitions of mem\_page\_size as one property shall be added to
264 Properties and set the value to large if one VDU node supports
265 huagepages. Here is an example.
267 +----------------------------------+
276 | tosca\_name: Huge\_pages\_demo |
280 | mem\_page\_size:large |
281 +==================================+
282 +----------------------------------+
286 Likewise, we shall add definitions of numa to
287 requested\_additional\_capabilities if we wand VUD nodes to support
288 NUMA. Here is an example.
290 +-------------------------------------------------+
291 | topology\_template: |
299 | virtual\_compute: |
305 | numa\_enabled: true |
307 | virtual\_mem\_size: 2 GB |
309 | requested\_additional\_capabilities: |
313 | support\_mandatory: true |
315 | requested\_additional\_capability\_name: numa |
317 | target\_performance\_parameters: |
319 | hw:numa\_nodes: "2" |
321 | hw:numa\_cpus.0: "0,1" |
323 | hw:numa\_mem.0: "1024" |
325 | hw:numa\_cpus.1: "2,3,4,5" |
327 | hw:numa\_mem.1: "1024" |
328 +-------------------------------------------------+
332 Definitions of Hyper-Theading are necessary as one of
333 requested\_additional\_capabilities of one VUD node if that node
334 supports Hyper-Theading. Here is an example.
336 +-------------------------------------------------------------+
337 | topology\_template: |
345 | virtual\_compute: |
351 | numa\_enabled: true |
353 | virtual\_mem\_size: 2 GB |
355 | requested\_additional\_capabilities: |
357 | hyper\_threading: |
359 | support\_mandatory: true |
361 | requested\_additional\_capability\_name: hyper\_threading |
363 | target\_performance\_parameters: |
365 | hw:cpu\_sockets : "2" |
367 | hw:cpu\_threads : "2" |
369 | hw:cpu\_cores : "2" |
371 | hw:cpu\_threads\_policy: "isolate" |
372 +-------------------------------------------------------------+
376 Definitions of ovs\_dpdk are necessary as one of
377 requested\_additional\_capabilities of one VUD node if that node
378 supports dpdk. Here is an example.
380 +------------------------------------------------------+
381 | topology\_template: |
389 | virtual\_compute: |
395 | numa\_enabled: true |
397 | virtual\_mem\_size: 2 GB |
399 | requested\_additional\_capabilities: |
403 | support\_mandatory: true |
405 | requested\_additional\_capability\_name: ovs\_dpdk |
407 | target\_performance\_parameters: |
409 | sw:ovs\_dpdk: "true" |
410 +------------------------------------------------------+
412 NFV TOSCA Type Definition
413 -------------------------
415 tosca.capabilites.nfv.VirtualCompute
416 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
418 +---------------------------+-----------------------------------------+
419 | **Shorthand Name** | VirtualCompute |
420 +===========================+=========================================+
421 | **Type Qualified Name** | tosca: VirtualCompute |
422 +---------------------------+-----------------------------------------+
423 | **Type URI** | tosca.capabilities.nfv.VirtualCompute |
424 +---------------------------+-----------------------------------------+
425 | **derived from** | tosca.nodes.Root |
426 +---------------------------+-----------------------------------------+
431 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
432 | Name | Required | Type | Constraints | Description |
433 +=====================================+============+=====================================================+===============+=========================================================+
434 | request\_additional\_capabilities | No | tosca.datatypes.nfv.RequestedAdditionalCapability | | Describes additional capability for a particular VDU. |
435 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
436 | virtual\_memory | yes | tosca.datatypes.nfv.VirtualMemory | | Describes virtual memory of the virtualized compute |
437 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
438 | virtual\_cpu | yes | tosca.datatypes.nfv.VirtualCpu | | Describes virtual CPU(s) of the virtualized compute. |
439 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
440 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
442 +-------------------------------------+------------+-----------------------------------------------------+---------------+---------------------------------------------------------+
447 +-----------------------------------------------------------+
448 | tosca.capabilities.nfv.VirtualCompute: |
450 | derived\_from: tosca.capabilities.Root |
454 | requested\_additional\_capabilities: |
460 | type: tosca.datatypes.nfv.RequestedAdditionalCapability |
466 | type: tosca.datatypes.nfv.VirtualMemory |
472 | type: tosca.datatypes.nfv.VirtualCpu |
475 +-----------------------------------------------------------+
477 tosca.nodes.nfv.VDU.Compute
478 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
480 The NFV Virtualization Deployment Unit (VDU) compute node type
481 represents a VDU entity which it describes the deployment and
482 operational behavior of a VNF component (VNFC), as defined by **[ETSI
485 +-----------------------+-------------------------------+
486 | Shorthand Name | VDU.Compute |
487 +=======================+===============================+
488 | Type Qualified Name | tosca:VDU.Compute |
489 +-----------------------+-------------------------------+
490 | Type URI | tosca.nodes.nfv.VDU.Compute |
491 +-----------------------+-------------------------------+
492 | derived\_from | tosca.nodes.Compute |
493 +-----------------------+-------------------------------+
506 +-------------------------+-------------------------------------------------+---------------+-----------------------------------------------------------------------------------------------------+
507 | Name | Type | Constraints | Description |
508 +=========================+=================================================+===============+=====================================================================================================+
509 | virtual\_compute | tosca.capabilities.nfv.VirtualCompute | | Describes virtual compute resources capabilities. |
510 +-------------------------+-------------------------------------------------+---------------+-----------------------------------------------------------------------------------------------------+
511 | monitoring\_parameter | tosca.capabilities.nfv.Metric | None | Monitoring parameter, which can be tracked for a VNFC based on this VDU |
513 | | | | Examples include: memory-consumption, CPU-utilisation, bandwidth-consumption, VNFC downtime, etc. |
514 +-------------------------+-------------------------------------------------+---------------+-----------------------------------------------------------------------------------------------------+
515 | Virtual\_binding | tosca.capabilities.nfv.VirtualBindable | | Defines ability of VirtualBindable |
517 | | editor note: need to create a capability type | | |
518 +-------------------------+-------------------------------------------------+---------------+-----------------------------------------------------------------------------------------------------+
523 +-----------------------------------------------------------------------------------------------------+
524 | tosca.nodes.nfv.VDU.Compute: |
526 | derived\_from: tosca.nodes.Compute |
544 | type: list # explicit index (boot index) not necessary, contrary to IFA011 |
552 | nfvi\_constraints: |
562 | configurable\_properties: |
568 | type: tosca.datatypes.nfv.VnfcConfigurableProperties |
574 | private\_address: |
576 | status: deprecated |
580 | status: deprecated |
584 | status: deprecated |
588 | status: deprecated |
592 | virtual\_compute: |
594 | type: tosca.capabilities.nfv.VirtualCompute |
596 | virtual\_binding: |
598 | type: tosca.capabilities.nfv.VirtualBindable |
600 | #monitoring\_parameter: |
602 | # modeled as ad hoc (named) capabilities in VDU node template |
608 | # cpu\_load: tosca.capabilities.nfv.Metric |
610 | # memory\_usage: tosca.capabilities.nfv.Metric |
612 | host: #Editor note: FFS. How this capabilities should be used in NFV Profile |
614 | type: `*tosca.capabilities.Container* <#DEFN_TYPE_CAPABILITIES_CONTAINER>`__ |
616 | valid\_source\_types: [`*tosca.nodes.SoftwareComponent* <#DEFN_TYPE_NODES_SOFTWARE_COMPONENT>`__] |
618 | occurrences: [0,UNBOUNDED] |
622 | occurrences: [0,0] |
626 | occurrences: [0,0] |
628 | scalable: #Editor note: FFS. How this capabilities should be used in NFV Profile |
630 | type: `*tosca.capabilities.Scalable* <#DEFN_TYPE_CAPABILITIES_SCALABLE>`__ |
634 | occurrences: [0,UNBOUND] |
638 | - virtual\_storage: |
640 | capability: tosca.capabilities.nfv.VirtualStorage |
642 | relationship: tosca.relationships.nfv.VDU.AttachedTo |
644 | node: tosca.nodes.nfv.VDU.VirtualStorage |
646 | occurences: [ 0, UNBOUNDED ] |
648 | - local\_storage: #For NFV Profile, this requirement is deprecated. |
650 | occurrences: [0,0] |
658 | type: tosca.artifacts.nfv.SwImage |
659 +-----------------------------------------------------------------------------------------------------+
663 +-----------+------------+-------------------------------+---------------+------------------------------------------------+
664 | Name | Required | Type | Constraints | Description |
665 +===========+============+===============================+===============+================================================+
666 | SwImage | Yes | tosca.artifacts.nfv.SwImage | | Describes the software image which is |
667 | | | | | directly realizing this virtual storage |
668 +-----------+------------+-------------------------------+---------------+------------------------------------------------+
678 The TOSCA Cpd node represents network connectivity to a compute resource
679 or a VL as defined by [ETSI GS NFV-IFA 011]. This is an abstract type
680 used as parent for the various Cpd types.
682 +-----------------------+-----------------------+
683 | Shorthand Name | Cpd |
684 +=======================+=======================+
685 | Type Qualified Name | tosca:Cpd |
686 +-----------------------+-----------------------+
687 | Type URI | tosca.nodes.nfv.Cpd |
688 +-----------------------+-----------------------+
694 +--------+------------+--------+---------------+---------------+
695 | Name | Required | Type | Constraints | Description |
696 +========+============+========+===============+===============+
697 +--------+------------+--------+---------------+---------------+
712 +----------------------------------------------------------------------+
713 | tosca.nodes.nfv.Cpd: |
715 | derived\_from: tosca.nodes.Root |
725 | - valid\_values: [ethernet, mpls, odu2, ipv4, ipv6, pseudo\_wire ] |
729 | role: #Name in ETSI NFV IFA011 v0.7.3 cpRole |
735 | - valid\_values: [ root, leaf ] |
751 | type: tosca.datatype.nfv.AddressData |
754 +----------------------------------------------------------------------+
756 Additional Requirement
757 ^^^^^^^^^^^^^^^^^^^^^^
761 tosca.nodes.nfv.VduCpd
762 ~~~~~~~~~~~~~~~~~~~~~~
764 The TOSCA node VduCpd represents a type of TOSCA Cpd node and describes
765 network connectivity between a VNFC instance (based on this VDU) and an
766 internal VL as defined by [ETSI GS NFV-IFA 011].
768 +-----------------------+--------------------------+
769 | Shorthand Name | VduCpd |
770 +=======================+==========================+
771 | Type Qualified Name | tosca: VduCpd |
772 +-----------------------+--------------------------+
773 | Type URI | tosca.nodes.nfv.VduCpd |
774 +-----------------------+--------------------------+
780 +-------------------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
781 | Name | Required | Type | Constraints | Description |
782 +===============================+============+==========================================+==========================================================================+
783 | bitrate_requirement | no | integer | | Bitrate requirement on this connection point. |
784 +-------------------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
785 | virtual\_network\_interface_\ | no | VirtualNetworkInterfaceRequirements | | Specifies requirements on a virtual network |
786 | requirements | | | | realising the CPs instantiated from this CPD |
787 +-------------------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
797 +--------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
798 | Name | Required | Type | Constraints | Description |
799 +====================+============+==========================================+===============+==========================================================+
800 | virtual\_binding | yes | tosca.capabilities.nfv.VirtualBindable | | Describe the requirement for binding with VDU |
801 +--------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
802 | virtual\_link | no | tosca.capabilities.nfv.VirtualLinkable | | Describes the requirements for linking to virtual link |
803 +--------------------+------------+------------------------------------------+---------------+----------------------------------------------------------+
808 +----------------------------------------------------------------+
809 | tosca.nodes.nfv.VduCpd: |
811 | derived\_from: tosca.nodes.nfv.Cpd |
815 | bitrate\_requirement: |
821 | virtual\_network\_interface\_requirements |
827 | type: VirtualNetworkInterfaceRequirements |
835 | capability: tosca.capabilities.nfv.VirtualLinkable |
837 | relationship: tosca.relationships.nfv.VirtualLinksTo |
839 | node: tosca.nodes.nfv.VnfVirtualLinkDesc - virtual\_binding: |
841 | capability: tosca.capabilities.nfv.VirtualBindable |
843 | relationship: tosca.relationships.nfv.VirtualBindsTo |
845 | node: tosca.nodes.nfv.VDU |
846 +----------------------------------------------------------------+
848 tosca.nodes.nfv.VDU.VirtualStorage
849 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
851 The NFV VirtualStorage node type represents a virtual storage entity
852 which it describes the deployment and operational behavior of a virtual
853 storage resources, as defined by **[ETSI NFV IFA011].**
855 **[editor note]** open issue: should NFV profile use the current storage
856 model as described in YAML 1.1. Pending on Shitao proposal (see
857 NFVIFA(17)000110 discussion paper)
859 **[editor note]** new relationship type as suggested in Matt
860 presentation. Slide 8. With specific rules of “valid\_target\_type”
862 +---------------------------+--------------------------------------+
863 | **Shorthand Name** | VirtualStorage |
864 +===========================+======================================+
865 | **Type Qualified Name** | tosca: VirtualStorage |
866 +---------------------------+--------------------------------------+
867 | **Type URI** | tosca.nodes.nfv.VDU.VirtualStorage |
868 +---------------------------+--------------------------------------+
869 | **derived\_from** | tosca.nodes.Root |
870 +---------------------------+--------------------------------------+
872 tosca.artifacts.nfv.SwImage
873 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
875 +---------------------------+------------------------------------+
876 | **Shorthand Name** | SwImage |
877 +===========================+====================================+
878 | **Type Qualified Name** | tosca:SwImage |
879 +---------------------------+------------------------------------+
880 | **Type URI** | tosca.artifacts.nfv.SwImage |
881 +---------------------------+------------------------------------+
882 | **derived\_from** | tosca.artifacts.Deployment.Image |
883 +---------------------------+------------------------------------+
888 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
889 | Name | Required | Type | Constraints | Description |
890 +==========================================+============+====================+===============+====================================================================================================+
891 | name | yes | string | | Name of this software image |
892 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
893 | version | yes | string | | Version of this software image |
894 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
895 | checksum | yes | string | | Checksum of the software image file |
896 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
897 | container\_format | yes | string | | The container format describes the container file format in which software image is provided. |
898 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
899 | disk\_format | yes | string | | The disk format of a software image is the format of the underlying disk image |
900 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
901 | min\_disk | yes | scalar-unit.size | | The minimal disk size requirement for this software image. |
902 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
903 | min\_ram | no | scalar-unit.size | | The minimal RAM requirement for this software image. |
904 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
905 | Size | yes | scalar-unit.size | | The size of this software image |
906 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
907 | sw\_image | yes | string | | A reference to the actual software image within VNF Package, or url. |
908 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
909 | operating\_system | no | string | | Identifies the operating system used in the software image. |
910 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
911 | supported \_virtualization\_enviroment | no | list | | Identifies the virtualization environments (e.g. hypervisor) compatible with this software image |
912 +------------------------------------------+------------+--------------------+---------------+----------------------------------------------------------------------------------------------------+
917 +-----------------------------------------------------+
918 | tosca.artifacts.nfv.SwImage: |
920 | derived\_from: tosca.artifacts.Deployment.Image |
922 | properties or metadata: |
946 | container\_format: |
960 | type: scalar-unit.size # Number |
966 | type: scalar-unit.size # Number |
972 | type: scalar-unit.size # Number |
982 | operating\_system: |
988 | supported\_virtualisation\_environments: |
997 +-----------------------------------------------------+
1002 openovnf\_\_vOpenNAT.yaml
1003 ~~~~~~~~~~~~~~~~~~~~~~~~~
1005 +-------------------------------------------------------------+
1008 | - openonfv\_\_tosca.capabilities.Scalable.yaml |
1010 | - openonfv\_\_tosca.capabilities.nfv.Metric.yaml |
1012 | - openonfv\_\_tosca.capabilities.network.Bindable.yaml |
1014 | - openonfv\_\_tosca.capabilities.Attachment.yaml |
1016 | - openonfv\_\_tosca.capabilities.nfv.VirtualBindable.yaml |
1018 | - openonfv\_\_tosca.requirements.nfv.VirtualStorage.yaml |
1020 | - openonfv\_\_tosca.nodes.nfv.VDU.VirtualStorage.yaml |
1022 | - openonfv\_\_tosca.relationships.nfv.VirtualBindsTo.yaml |
1024 | - openonfv\_\_tosca.nodes.nfv.VDU.Compute.yaml |
1026 | - openonfv\_\_tosca.artifacts.nfv.SwImage.yaml |
1028 | - openonfv\_\_tosca.capabilities.nfv.VirtualCompute.yaml |
1030 | - openonfv\_\_tosca.capabilities.Container.yaml |
1032 | - openonfv\_\_tosca.capabilities.nfv.VirtualStorage.yaml |
1034 | - openonfv\_\_tosca.requirements.nfv.VirtualBinding.yaml |
1036 | - openovnf\_\_tosca.nodes.nfv.VNF.vOpenNAT.yaml |
1038 | - openonfv\_\_tosca.capabilities.Endpoint.Admin.yaml |
1040 | - openonfv\_\_tosca.capabilities.OperatingSystem.yaml |
1042 | - openonfv\_\_tosca.nodes.nfv.VduCpd.yaml |
1044 | - openonfv\_\_tosca.relationships.nfv.VDU.AttachedTo.yaml |
1048 | vnfProductName: openNAT |
1050 | vnfdVersion: 1.0.0 |
1052 | vnfProvider: intel |
1056 | csarVersion: 1.0.0 |
1058 | vnfdId: openNAT-1.0 |
1060 | csarProvider: intel |
1062 | vnfProductInfoDescription: openNAT |
1070 | localizationLanguage: '[english, chinese]' |
1074 | defaultLocalizationLanguage: english |
1076 | vnfProductInfoName: openNAT |
1078 | vnfSoftwareVersion: 1.0.0 |
1080 | topology\_template: |
1082 | node\_templates: |
1090 | file: /swimages/xenial-snat.qcow2 |
1092 | type: tosca.artifacts.nfv.SwImage |
1096 | name: vNatVNFImage |
1100 | checksum: "5000" |
1102 | container\_format: bare |
1104 | disk\_format: qcow2 |
1106 | min\_disk: 10 GB |
1112 | sw\_image: /swimages/xenial-snat.qcow2 |
1114 | operating\_system: unbantu |
1118 | tosca\_name: vdu\_vNat |
1122 | virtual\_compute: |
1126 | virtual\_memory: |
1128 | numa\_enabled: true |
1130 | virtual\_mem\_size: 2 GB |
1132 | requested\_additional\_capabilities: |
1136 | support\_mandatory: true |
1138 | requested\_additional\_capability\_name: numa |
1140 | target\_performance\_parameters: |
1142 | hw:numa\_nodes: "2" |
1144 | hw:numa\_cpus.0: "0,1" |
1146 | hw:numa\_mem.0: "1024" |
1148 | hw:numa\_cpus.1: "2,3,4,5" |
1150 | hw:numa\_mem.1: "1024" |
1152 | hyper\_threading: |
1154 | support\_mandatory: true |
1156 | requested\_additional\_capability\_name: hyper\_threading |
1158 | target\_performance\_parameters: |
1160 | hw:cpu\_sockets : "2" |
1162 | hw:cpu\_threads : "2" |
1164 | hw:cpu\_cores : "2" |
1166 | hw:cpu\_threads\_policy: "isolate" |
1170 | support\_mandatory: true |
1172 | requested\_additional\_capability\_name: ovs\_dpdk |
1174 | target\_performance\_parameters: |
1176 | sw:ovs\_dpdk: "true" |
1180 | cpu\_architecture: X86 |
1182 | num\_virtual\_cpu: 2 |
1186 | configurable\_properties: |
1190 | additional\_vnfc\_configurable\_properties: |
1196 | descrption: the virtual machine of vNat |
1204 | - virtual\_storage: |
1206 | capability: virtual\_storage |
1208 | node: vNAT\_Storage |
1214 | location: /mnt/volume\_0 |
1216 | type: tosca.relationships.nfv.VDU.AttachedTo |
1218 | - local\_storage: |
1220 | node: tosca.nodes.Root |
1222 | type: tosca.nodes.nfv.VDU.Compute |
1228 | tosca\_name: SRIOV\_Port |
1232 | virtual\_network\_interface\_requirements: |
1236 | support\_mandatory: false |
1238 | description: sriov |
1246 | description: sriov port |
1248 | layer\_protocol: ipv4 |
1252 | - virtual\_binding: |
1254 | capability: virtual\_binding |
1260 | type: tosca.relationships.nfv.VirtualBindsTo |
1262 | - virtual\_link: |
1264 | node: tosca.nodes.Root |
1266 | type: tosca.nodes.nfv.VduCpd |
1272 | tosca\_name: vNAT\_Storage |
1276 | id: vNAT\_Storage |
1278 | size\_of\_storage: 10 GB |
1280 | rdma\_enabled: false |
1282 | type\_of\_storage: volume |
1284 | type: tosca.nodes.nfv.VDU.VirtualStorage |
1286 | substitution\_mappings: |
1296 | node\_type: tosca.nodes.nfv.VNF.vOpenNAT |
1298 | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 |
1299 +-------------------------------------------------------------+
1301 openonfv\_\_tosca.nodes.nfv.VDU.VirtualStorage.yaml
1302 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1304 +------------------------------------------------------------+
1307 | - openonfv\_\_tosca.capabilities.nfv.VirtualStorage.yaml |
1311 | tosca.nodes.nfv.VDU.VirtualStorage: |
1315 | virtual\_storage: |
1317 | type: tosca.capabilities.nfv.VirtualStorage |
1319 | derived\_from: tosca.nodes.Root |
1327 | size\_of\_storage: |
1337 | type\_of\_storage: |
1341 | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 |
1342 +------------------------------------------------------------+
1344 openonfv\_\_tosca.nodes.nfv.VduCpd.yaml
1345 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1347 +-----------------------------------------------------------------+
1350 | tosca.datatypes.nfv.L3AddressData: |
1354 | number\_of\_ip\_address: |
1360 | ip\_address\_assignment: |
1364 | ip\_address\_type: |
1368 | - valid\_values: |
1378 | floating\_ip\_activated: |
1382 | tosca.datatypes.nfv.VirtualNetworkInterfaceRequirements: |
1392 | support\_mandatory: |
1410 | tosca.datatype.nfv.AddressData: |
1418 | - valid\_values: |
1426 | l2\_address\_data: |
1430 | type: tosca.datatypes.nfv.L2AddressData |
1432 | l3\_address\_data: |
1436 | type: tosca.datatypes.nfv.L3AddressData |
1438 | tosca.datatypes.nfv.L2AddressData: {} |
1442 | - openonfv\_\_tosca.requirements.nfv.VirtualBinding.yaml |
1444 | - openonfv\_\_tosca.requirements.nfv.VirtualBinding.yaml |
1448 | tosca.nodes.nfv.VduCpd: |
1450 | derived\_from: tosca.nodes.Root |
1454 | virtual\_network\_interface\_requirements: |
1458 | type: tosca.datatypes.nfv.VirtualNetworkInterfaceRequirements |
1468 | - valid\_values: |
1478 | bitrate\_requirement: |
1490 | layer\_protocol: |
1494 | - valid\_values: |
1514 | type: tosca.datatype.nfv.AddressData |
1522 | - virtual\_binding: |
1524 | capability: tosca.capabilities.nfv.VirtualBindable |
1532 | - virtual\_link: |
1534 | capability: tosca.capabilities.nfv.VirtualBindable |
1542 | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 |
1543 +-----------------------------------------------------------------+
1545 .. |image1| image:: Image1.png
1548 .. |image2| image:: Image2.png
1562 Heat Orchestration Templates must use valid YAML. YAML (YAML Ain't
1563 Markup Language) is a human friendly data serialization standard for all
1564 programming languages. See http://www.yaml.org/.
1566 Heat Orchestration Template Format
1567 ----------------------------------
1569 Heat Orchestration templates must be defined in YAML.
1573 - Tabs are NOT allowed, use spaces ONLY.
1575 - You MUST indent your properties and lists with 1 or more spaces.
1577 - All Resource IDs and resource property parameters are case-sensitive.
1578 (e.g., "ThIs", is not the same as "thiS")
1580 Heat Orchestration Template Structure
1581 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1583 Heat Orchestration template structure follows the following format, as
1584 defined by OpenStack at
1585 https://docs.openstack.org/developer/heat/template_guide/hot_spec.html.
1587 .. code-block:: yaml
1589 heat_template_version: <date>
1592 # a description of the template
1595 # a declaration of input parameter groups and order
1598 # declaration of input parameters
1601 # declaration of template resources
1604 # declaration of output parameters
1607 # declaration of conditions
1610 Heat Orchestration templates for ONAP must contain the following
1613 - heat\_template\_version:
1621 Heat Orchestration templates for ONAP may contain the following
1624 - parameter\_groups:
1628 heat\_template\_version
1629 ^^^^^^^^^^^^^^^^^^^^^^^
1631 This section is ONAP mandatory. The heat\_template\_version must be set
1632 to a date that is supported by the OpenStack environment.
1637 This ONAP mandatory section allows for a description of the template.
1642 This ONAP optional section allows for specifying how the input
1643 parameters should be grouped and the order to provide the parameters in.
1648 The parameter section is ONAP mandatory. This section allows for
1649 specifying input parameters that have to be provided when instantiating
1650 the template. Each parameter is specified in a separated nested block
1651 with the name of the parameters defined in the first line and additional
1652 attributes (e.g., type, label) defined as nested elements.
1654 The Pre-Amsterdam VNF Validation Program (i.e., ICE Project) process
1655 requires all parameters declared in a template to be used in a resource
1656 with the exception of the parameters for the OS::Nova::Server property
1657 availability\_zone. See `Property: availability\_zone`_. for more details on
1660 .. code-block:: yaml
1664 type: <string | number | json | comma_delimited_list | boolean>
1665 label: <human-readable name of the parameter>
1666 description: <description of the parameter>
1667 default: <default value for parameter>
1668 hidden: <true | false>
1670 <parameter constraints>
1671 immutable: <true | false>
1675 - The name of the parameter.
1677 - ONAP requires that the param name must contain only alphanumeric
1678 characters and “\_” underscores. Special characters must not be
1683 - The type of the parameter. Supported types are string, number,
1684 comma\_delimited\_list, json and boolean.
1686 - This attribute must be provided per the OpenStack Heat
1687 Orchestration Template standard.
1691 - A human readable name for the parameter.
1693 - This attribute is optional.
1697 - A human readable description for the parameter.
1699 - This attribute is ONAP mandatory; it must be provided. (Note that
1700 this attribute is OpenStack optional.)
1704 - A default value for the parameter.
1706 - ONAP does not support this attribute; it *must not* be provided in
1707 the Heat Orchestration Template. If a parameter has a default
1708 value, it must be provided in the environment file. (Note that
1709 this attribute is OpenStack optional.)
1713 - Defines whether the parameters should be hidden when a user
1714 requests information about a stack created from the template. This
1715 attribute can be used to hide passwords specified as parameters.
1717 - This attribute is optional and defaults to false.
1721 - A list of constraints to apply. The constraints block of a
1722 parameter definition defines additional validation constraints
1723 that apply to the value of the parameter. The parameter values
1724 provided in the Heat Orchestration Template are validated against
1725 the constraints at instantiation time. The constraints are defined
1726 as a list with the following syntax
1730 - <constraint type>: <constraint definition>
1732 description: <constraint description>
1734 - constraint type: Type of constraint to apply.
1736 - constraint definition: The actual constraint, depending on the
1739 - description: A description of the constraint. The text is presented
1740 to the user when the value the user defines violates the constraint.
1741 If omitted, a default validation message is presented to the user.
1742 This attribute is optional.
1744 - When the parameter type is set to number, the Heat Orchestration
1745 Template uploaded into ONAP must have constraints for range or
1748 - range: The range constraint applies to parameters of type number.
1749 It defines a lower and upper limit for the numeric value of the
1750 parameter. The syntax of the range constraint is
1752 range: { min: <lower limit>, max: <upper limit> }
1754 It is possible to define a range constraint with only a lower limit
1757 - allowed\_values: The allowed\_values constraint applies to parameters
1758 of type string or number. It specifies a set of possible values for a
1759 parameter. At deployment time, the user-provided value for the
1760 respective parameter must match one of the elements of the list. The
1761 syntax of the allowed\_values constraint is
1763 allowed\_values: [ <value>, <value>, ... ]
1765 Alternatively, the following YAML list notation can be used
1775 - Other <constraint type> are optional, they may be used (e.g., length,
1776 modulo, allowed\_pattern, custom\_constraint, allowed\_values (for
1779 - Note that constrains must not be defined for any parameter enumerated
1780 in a nested heat template.
1782 - Some ONAP parameters must never have constraints defined. See `ONAP Resource ID and Parameter Naming Convention`_ for the use cases where these exceptions exist.
1786 - Defines whether the parameter is updatable. Stack update fails, if
1787 this is set to true and the parameter value is changed.
1789 - This attribute is optional and defaults to false.
1794 This section is ONAP mandatory; it must be provided. This section
1795 contains the declaration of the single resources of the template. This
1796 section with at least one resource must be defined in the Heat
1797 Orchestration Template, or the template would not create any resources
1798 when being instantiated.
1800 Each resource is defined as a separate block in the resources section
1801 with the following syntax.
1803 .. code-block:: yaml
1807 type: <resource type>
1809 <property name>: <property value>
1811 <resource specific metadata>
1812 depends\_on: <resource ID or list of ID>
1813 update\_policy: <update policy>
1814 deletion\_policy: <deletion policy>
1815 external\_id: <external resource ID>
1816 condition: <condition name or expression or boolean>
1820 - A resource ID that must be unique within the resources section of
1821 the Heat Orchestration Template.
1823 - ONAP requires that the resource ID must be unique across all Heat
1824 Orchestration Templates that compose the VNF. This requirement
1825 also applies when a VNF is composed of more than one Heat
1826 Orchestration Template (see ONAP VNF Modularity Overview).
1828 - The naming convention for a resource ID is provided in `Resource IDs`_.
1832 - The resource type, such as OS::Nova::Server or OS::Neutron::Port.
1833 Note that the type may specify a nested heat file. This attribute
1838 - A list of resource-specific properties. The property value can be
1839 provided in place, or via a function (e.g., Intrinsic functions). This section is optional.
1841 - The naming convention for property parameters is provided in `ONAP Resource ID and Parameter Naming Convention`_.
1845 - Resource-specific metadata. This section is optional, except for
1846 the resource OS::Nova::Server. See `Resource: OS::Nova::Server - Parameters`_.
1850 - Dependencies of the resource on one or more resources of the
1851 template. This attribute is optional. See `Resource Data Synchronization`_ for additional details.
1855 - Update policy for the resource, in the form of a nested
1856 dictionary. Whether update policies are supported and what the
1857 exact semantics are depends on the type of the current resource.
1858 This attribute is optional.
1862 - Deletion policy for the resource. The allowed deletion policies
1863 are Delete, Retain, and Snapshot. Beginning with
1864 heat\_template\_version 2016-10-14, the lowercase equivalents
1865 delete, retain, and snapshot are also allowed. This attribute is
1866 optional; the default policy is to delete the physical resource
1867 when deleting a resource from the stack.
1871 - Allows for specifying the resource\_id for an existing external
1872 (to the stack) resource. External resources cannot depend on other
1873 resources, but we allow other resources to depend on external
1874 resource. This attribute is optional. Note: when this is
1875 specified, properties will not be used for building the resource
1876 and the resource is not managed by Heat. This is not possible to
1877 update that attribute. Also, resource won’t be deleted by heat
1878 when stack is deleted.
1882 - Condition for the resource. The condition decides whether to
1883 create the resource or not. This attribute is optional.
1888 This ONAP optional section allows for specifying output parameters
1889 available to users once the template has been instantiated. If the
1890 section is specified, it will need to adhere to specific requirements.
1891 See `ONAP Parameter Classifications Overview`_ and `ONAP Output Parameter Names`_ for additional details.
1893 Environment File Format
1894 -----------------------
1896 The environment file is a yaml text file.
1897 (https://docs.openstack.org/developer/heat/template_guide/environment.html)
1899 The environment file can contain the following sections:
1901 - parameters: A list of key/value pairs.
1903 - resource\_registry: Definition of custom resources.
1905 - parameter\_defaults: Default parameters passed to all template
1908 - encrypted\_parameters: List of encrypted parameters.
1910 - event\_sinks: List of endpoints that would receive stack events.
1912 - parameter\_merge\_strategies: Merge strategies for merging parameters
1913 and parameter defaults from the environment file.
1915 Environment files for ONAP must contain the following sections:
1919 Environment files for ONAP may contain the following sections:
1921 - resource\_registry:
1923 - parameter\_defaults:
1925 - encrypted\_parameters:
1929 - parameter\_merge\_strategies:
1931 The use of an environment file in OpenStack is optional. In ONAP, it is
1932 mandatory. A Heat Orchestration Template uploaded to ONAP must have a
1933 corresponding environment file, even if no parameters are enumerated in
1934 the mandatory parameter section.
1936 (Note that ONAP, the open source version of ONAP, does not
1937 programmatically enforce the use of an environment file.)
1939 SDC Treatment of Environment Files
1940 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1942 Parameter values enumerated in the environment file are used by SDC as
1943 the default value. However, the SDC user may use the SDC GUI to
1944 overwrite the default values in the environment file.
1946 SDC generates a new environment file for distribution to MSO based on
1947 the uploaded environment file and the user provided GUI updates. The
1948 user uploaded environment file is discarded when the new file is
1951 ONAP has requirements for what parameters must be enumerated in the
1952 environment file and what parameter must not be enumerated in the
1953 environment file. See `ONAP Parameter Classifications Overview`_ and `ONAP Resource ID and Parameter Naming Convention`_ for more details.
1955 Nested Heat Orchestration Templates Overview
1956 --------------------------------------------
1958 ONAP supports nested Heat Orchestration Templates per OpenStack
1961 A Base Module may utilize nested templates.
1963 An Incremental Module may utilize nested templates.
1965 A Cinder Volume Module may utilize nested templates.
1967 A nested template must not define parameter constraints in the parameter
1970 Nested templates may be suitable for larger VNFs that contain many
1971 repeated instances of the same VM type(s). A common usage pattern is to
1972 create a nested template for each VM type along with its supporting
1973 resources. The Heat Orchestration Template may then reference these
1974 nested templates either statically (by repeated definition) or
1975 dynamically (via OS::Heat::ResourceGroup).
1977 See `Nested Heat Templates`_ for additional details.
1979 ONAP Heat Orchestration Template Filenames
1980 ------------------------------------------
1982 In order to enable ONAP to understand the relationship between Heat
1983 files, the following Heat file naming convention must be utilized.
1985 In the examples below, <text> represents any alphanumeric string that
1986 must not contain any special characters and must not contain the word
1992 The file name for the base module must include “base” in the filename
1993 and must match one of the following options:
1995 - base\_<text>.y[a]ml
1997 - <text>\_base.y[a]ml
2001 - <text>\_base\_<text>.y[a]ml
2003 The base module’s corresponding environment file must be named identical
2004 to the base module with “.y[a]ml” replaced with “.env”.
2009 There is no explicit naming convention for the incremental modules. As
2010 noted above, <text> represents any alphanumeric string that must not
2011 contain any special characters and must not contain the word “base”.
2015 The incremental module’s corresponding environment file must be named
2016 identical to the incremental module with “.y[a]ml” replaced with “.env”.
2018 To clearly identify the incremental module, it is recommended to use the
2019 following naming options for modules:
2021 - module\_<text>.y[a]ml
2023 - <text>\_module.y[a]ml
2027 Cinder Volume Modules
2028 ~~~~~~~~~~~~~~~~~~~~~
2030 The file name for the Cinder volume module must be named the same as the
2031 corresponding module it is supporting (base module or incremental
2032 module) with “\_volume” appended
2034 - <base module name>\_volume.y[a]ml
2036 - <incremental module name>\_volume.y[a]ml
2038 The volume module’s corresponding environment file must be named
2039 identical to the volume module with “.y[a]ml” replaced with “.env”.
2044 There is no explicit naming convention for nested Heat files with the
2045 following exceptions; the name should contain “nest”. As noted above,
2046 <text> represents any alphanumeric string that must not contain any
2047 special characters and must not contain the word “base”.
2051 Nested Heat files do not have corresponding environment files, per
2052 OpenStack specifications. All parameter values associated with the
2053 nested heat file must be passed in as properties in the resource
2054 definition defined in the parent heat template.
2056 ONAP Parameter Classifications Overview
2057 ---------------------------------------
2059 In order for ONAP to support workflow automation, Heat Orchestration
2060 Template resource property parameters must adhere to specific naming
2061 conventions and requirements.
2063 Broadly, ONAP categorizes parameters into four categories:
2065 1. ONAP metadata parameters
2067 2. Instance specific parameters
2069 3. Constant parameters
2071 4. Output parameters.
2073 ONAP Metadata Parameters
2074 ~~~~~~~~~~~~~~~~~~~~~~~~
2076 There are both mandatory and optional ONAP metadata parameters
2077 associated with the resource OS::Nova::Server.
2079 - ONAP metadata parameters must not have parameter constraints defined.
2081 - Both mandatory and optional (if specified) ONAP metadata parameter
2082 names must follow the ONAP metadata parameter naming convention.
2084 `Resource: OS::Nova::Server – Metadata Parameters`_ provides more details on the metadata parameters.
2086 Instance specific parameters
2087 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2089 The instance specific parameters are VNF instance specific. The value of
2090 the parameter will be different for every instance of a VNF (e.g., IP
2091 address). The instance specific parameters are subdivided into two
2092 categories: **ONAP Orchestration Parameters** and **VNF Orchestration
2095 ONAP Orchestration Parameters
2096 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2098 ONAP Orchestration Parameters are per instance parameters where the
2099 value is assigned via ONAP automation. (Note that in some cases,
2100 automation is currently not available and the value is loaded into ONAP
2101 prior to instantiation.)
2103 - ONAP orchestration parameters must not be enumerated in the
2106 - When the ONAP orchestration parameter type is set to number, the
2107 parameter must have constraints for range and/or allowed\_values.
2109 - Parameter constraints for ONAP orchestration parameters are optional
2110 for all parameter types other than number. If constraints are
2111 specified, they must adhere to the OpenStack specifications.
2113 - The ONAP orchestration parameter names must follow the ONAP
2114 orchestration parameter naming convention. `ONAP Resource ID and Parameter Naming Convention`_ provides
2117 VNF Orchestration Parameters
2118 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2120 VNF Orchestration Parameters are per instance parameters where the
2121 values are assigned manually. They are not supported by ONAP automation.
2122 The per instance values are loaded into ONAP prior to VNF instantiation.
2124 - VNF orchestration parameters must not be enumerated in the
2127 - When the VNF orchestration parameter type is set to number, the
2128 parameter must have constraints for range or allowed\_values.
2130 - Parameter constraints for VNF orchestration parameters are optional
2131 for all parameter types other than number. If constraints are
2132 specified, they must adhere to the OpenStack specifications.
2134 - The VNF orchestration parameter names should follow the VNF
2135 orchestration parameter naming convention. `ONAP Resource ID and Parameter Naming Convention`_ provides
2141 The constant parameters are parameters that remain constant across many
2142 VNF instances (e.g., image, flavor). The constant parameters are
2143 subdivided into two categories: **ONAP Constant Parameters** and **VNF Constant Parameters.**
2145 ONAP Constant Parameters
2146 ^^^^^^^^^^^^^^^^^^^^^^^^
2148 - ONAP Constant Parameters must be enumerated in the environment file.
2149 These parameter values are not assigned by ONAP.
2151 - When the ONAP Constant Parameter type is set to number, the parameter
2152 must have constraints for range and/or allowed\_values.
2154 - Parameter constraints for ONAP constant parameters are optional for
2155 all parameter types other than number. If constraints are specified,
2156 they must adhere to the OpenStack specifications.
2158 - The ONAP Constant Parameter names must follow the ONAP orchestration
2159 parameter naming convention. `ONAP Resource ID and Parameter Naming Convention`_ provides additional details.
2161 VNF Constant Parameters
2162 ^^^^^^^^^^^^^^^^^^^^^^^
2164 - VNF Constant Parameters must be enumerated in the environment file.
2165 These parameter values are not assigned by ONAP.
2167 - When the VNF Constant Parameters type is set to number, the parameter
2168 must have constraints for range and/or allowed\_values.
2170 - Parameter constraints for ONAP constant parameters are optional for
2171 all parameter types other than number. If constraints are specified,
2172 they must adhere to the OpenStack specifications.
2174 - The VNF Constant Parameters names should follow the ONAP
2175 orchestration parameter naming convention. `ONAP Resource ID and Parameter Naming Convention`_ provides
2181 The output parameters are parameters defined in the output section of a
2182 Heat Orchestration Template. The ONAP output parameters are subdivided
2183 into three categories:
2185 1. ONAP Base Module Output Parameters
2187 2. ONAP Volume Module Output Parameters
2189 3. ONAP Predefined Output Parameters.
2191 ONAP Base Module Output Parameters
2192 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2194 ONAP Base Module Output Parameters are declared in the outputs: section
2195 of the base module Heat Orchestration Template. A Base Module Output
2196 Parameter is available as an input parameter (i.e., declared in the
2197 “parameters:” section) to all incremental modules in the VNF.
2199 - A Base Module Output Parameter may be used as an input parameter in
2200 an incremental module.
2202 - The Output parameter name and type must match the input parameter
2203 name and type unless the Output parameter is of the type
2204 comma\_delimited\_list.
2206 - If the Output parameter has a comma\_delimited\_list value (e.g.,
2207 a collection of UUIDs from a Resource Group), then the
2208 corresponding input parameter must be declared as type json and
2209 not a comma\_delimited\_list, which is actually a string value
2210 with embedded commas.
2212 - When a Base Module Output Parameter is declared as an input parameter
2213 in an incremental module Heat Orchestration Template, parameter
2214 constraints must not be declared.
2216 Additional details on ONAP Base Module Output Parameters are provided in
2217 `ONAP Output Parameter Names`_ and ONAP VNF Modularity.
2219 ONAP Volume Module Output Parameters
2220 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2222 The volume template output parameters are only available for the module
2223 (base or add on) that the volume is associated with.
2225 - ONAP Volume Module Output Parameters are declared in the “outputs:”
2226 section of the Cinder volume module Heat Orchestration Template
2228 - An ONAP Volume Module Output Parameter is available as an input
2229 parameter (i.e., declared in the parameters: section) only for the
2230 module (base or incremental) that the Cinder volume module is
2231 associated with. The Output parameter name and type must match the
2232 input parameter name and type unless the Output parameter is of the
2233 type comma\_delimited\_list.
2235 - If the Output parameter has a comma\_delimited\_list value (e.g., a
2236 collection of UUIDs from a Resource Group), then the corresponding
2237 input parameter must be declared as type json and not a
2238 comma\_delimited\_list, which is actually a string value with
2241 - When an ONAP Volume Module Output Parameter is declared as an input
2242 parameter in a base module or incremental module, parameter
2243 constraints must not be declared.
2245 Additional details on ONAP Base Module Output Parameters are provided in
2246 `ONAP Output Parameter Names`_ and `Cinder Volume Templates`_.
2248 ONAP Predefined Output Parameters
2249 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2251 ONAP will look for a small set of pre-defined Heat output parameters to
2252 capture resource attributes for inventory in ONAP. These output
2253 parameters are optional and are specified in `OAM Management IP Addresses`_.
2255 Support of heat stack update
2256 ----------------------------
2258 VNF Heat Orchestration Templates must not be designed to utilize the
2259 OpenStack heat stack-update command for scaling (growth/de-growth). ONAP
2260 does not support the use of heat stack-update command for scaling.
2262 It is important to note that ONAP only supports heat stack-update for
2268 ONAP defines two types of networks: External Networks and Internal
2271 ONAP defines an external network in relation to the VNF and not with
2272 regard to the Network Cloud site. External networks may also be referred
2273 to as “inter-VNF” networks. An external network connects VMs in a VNF to
2275 - VMs in another VNF or
2277 - an external gateway or router
2279 ONAP defines an internal network in relation to the VNF and not with
2280 regard to the Network Cloud site. Internal networks may also be referred
2281 to as “intra-VNF” networks or “private” networks. An internal network
2282 only connects VMs in a single VNF. It must not connect to other VNFs or
2283 an external gateway or router.
2288 VNF Heat Orchestration Templates must not include any resources for
2289 external networks connected to the VNF. External networks must be
2290 orchestrated separately, as independent, stand-alone VNF Heat
2291 Orchestration Templates, so they can be shared by multiple VNFs and
2292 managed independently.
2294 When the external network is created, it must be assigned a unique
2295 {network-role}. The {network-role} should describe the network (e.g.,
2296 oam). The {network-role} while unique to the LCP, can repeat across
2299 An External Network may be a Neutron Network or a Contrail Network
2301 External networks must be passed into the VNF Heat Orchestration
2302 Templates as parameters.
2304 - Neutron Network-id (UUID)
2306 - Neutron Network subnet ID (UUID)
2308 - Contrail Network Fully Qualified Domain Name (FQDN)
2310 ONAP enforces a naming convention for parameters associated with
2311 external networks. `ONAP Resource ID and Parameter Naming Convention`_ provides additional details.
2313 Parameter values associated with an external network will be generated
2314 and/or assigned by ONAP at orchestration time. Parameter values
2315 associated with an external network must not be enumerated in the
2316 environment file. `ONAP Resource ID and Parameter Naming Convention`_ provides additional details.
2318 VNFs may use **Cloud assigned IP addresses** or **ONAP SDN-C assigned IP addresses**
2319 when attaching VMs to an external network
2321 - A Cloud assigned IP address is assigned by OpenStack’s DHCP Service.
2323 - An ONAP SDN-C assigned IP address is assigned by the ONAP SDN-C
2326 - Note that Neutron Floating IPs must not be used. ONAP does not
2327 support Neutron Floating IPs (e.g., OS::Neutron::FloatingIP)
2329 - ONAP supports the property allowed\_address\_pairs in the resource
2330 OS::Neutron:Port and the property
2331 virtual\_machine\_interface\_allowed\_address\_pairs in
2332 OS::ContrailV2::VirtualMachineInterfaces. This allows the assignment
2333 of a virtual IP (VIP) address to a set of VMs.
2335 VNF Heat Orchestration Templates must pass the appropriate external
2336 network IDs into nested VM templates when nested Heat is used.
2341 The VNF Heat Orchestration Templates must include the resource(s) to
2342 create the internal network. The internal network must be either a
2343 Neutron Network or a Contrail Network.
2345 In the modular approach, internal networks must be created in the Base
2346 Module, with their resource IDs exposed as outputs (i.e., ONAP Base
2347 Module Output Parameters) for use by all incremental modules. If the
2348 Network resource ID is required in the base template, then a
2349 get\_resource must be used.
2351 When the internal network is created, it should be assigned a unique
2352 {network-role} in the context of the VNF. `ONAP Resource ID and Parameter Naming Convention`_ provides additional
2355 VNFs may use **Cloud assigned IP addresses** or
2356 **predetermined static IPs** when attaching VMs to an internal network.
2358 - A Cloud assigned IP address is assigned by OpenStack’s DHCP Service.
2360 - A predetermined static IP address is enumerated in the Heat
2361 environment file. Since an internal network is local to the VNF, IP
2362 addresses can be re-used at every VNF instance.
2364 - Note that Neutron Floating IPs must not be used. ONAP does not
2365 support Neutron Floating IPs (e.g., OS::Neutron::FloatingIP)
2367 - ONAP supports the property allowed\_address\_pairs in the resource
2368 OS::Neutron:Port and the property
2369 virtual\_machine\_interface\_allowed\_address\_pairs in
2370 OS::ContrailV2::VirtualMachineInterfaces. This allows the assignment
2371 of a virtual IP (VIP) address to a set of VMs.
2373 ONAP does not programmatically enforce a naming convention for
2374 parameters for internal network. However, a naming convention is
2375 provided that must be followed. `ONAP Resource ID and Parameter Naming Convention`_ provides additional details.
2377 ONAP Resource ID and Parameter Naming Convention
2378 ------------------------------------------------
2380 This section provides the ONAP naming requirements for
2384 2. Resource Property Parameters
2389 The Heat Orchestration Templates for a VNF must assign a VNF unique
2390 {vm-type} for each Virtual Machine type (i.e., OS::Nova::Server)
2391 instantiated in the VNF. While the {vm-type} must be unique to the VNF,
2392 it does not have to be globally unique across all VNFs that ONAP
2395 Any parameter that is associated with a unique Virtual Machine type in
2396 the VNF must include {vm-type} as part of the parameter name.
2398 Any resource ID that is associated with a unique Virtual Machine type in
2399 the VNF must include {vm-type} as part of the resource ID.
2401 Note that {vm-type} must not be a substring of {network-role}. A
2402 substring of a string is another string that occurs "in". For example,
2403 "oam" is a substring of "oam\_protected". It will cause the
2404 Pre-Amsterdam VNF Validation Program (i.e., ICE Project) process to
2405 produce erroneous error messages.
2407 The {vm-type} should not contain the string “\_int” or “int\_” or
2408 “\_int\_”. It may cause the Pre-Amsterdam VNF Validation Program (i.e.,
2409 ICE Project) process to produce erroneous error messages.
2411 The {vm-type} must be the same case in all parameter names in the VNF.
2413 The {vm-type} must be the same case in all Resource IDs in the VNF.
2415 It is recommended that the {vm-type} case in the parameter names matches
2416 the {vm-type} case in the Resource IDs.
2418 There are two exceptions to the above rules:
2420 1. The six ONAP Metadata parameters must not be prefixed with a common
2421 {vm-type} identifier. They are *vnf\_name*, *vnf\_id*,
2422 *vf\_module\_id*, *vf\_module\_name, vm\_role*. The ONAP Metadata
2423 parameters are described in `Resource: OS::Nova::Server – Metadata Parameters`_.
2425 2. The parameter referring to the OS::Nova::Server property
2426 availability\_zone must not be prefixed with a common {vm-type}
2427 identifier. availability\_zone is described in `Property: availability_zone`_.
2432 The assignment of a {network-role} is discussed in `Networking`_.
2434 Any parameter that is associated with an external network must include
2435 the {network-role} as part of the parameter name.
2437 Any resource ID that is associated with an external network must include
2438 the {network-role} as part of the resource ID.
2440 Any parameter that is associated with an internal network must include
2441 int\_{network-role} as part of the parameter name.
2443 Any resource ID that is associated with an internal network must include
2444 int\_{network-role} as part of the resource ID.
2446 Note that {network-role} must not be a substring of {vm-type}. A
2447 substring of a string is another string that occurs "in". For example,
2448 "oam" is a substring of "oam\_protected". It will cause the
2449 Pre-Amsterdam VNF Validation Program (i.e., ICE Project) process to
2450 produce erroneous error messages.
2452 The {network-role} should not contain the string “\_int” or “int\_” or
2453 “\_int\_”. It may cause the Pre-Amsterdam VNF Validation Program (i.e.,
2454 ICE Project) process to produce erroneous error messages.
2456 The {network-role} must be the same case in all parameter names in the
2459 The {network-role} must be the same case in all Resource IDs in the VNF.
2461 It is recommended that the {network-role} case in the parameter names
2462 matches the {network-role} case in the Resource IDs.
2467 Heat Orchestration Template resources are described in `resources`_
2469 A resource ID that must be unique within the resources section of a Heat
2470 Orchestration Template. This is an OpenStack Requirement.
2472 When a VNF is composed of more than one Heat Orchestration Template
2473 (i.e., modules), ONAP requires that the resource ID must be unique
2474 across all modules that compose the VNF.
2476 When a resource is associated with a single {vm-type}, the resource ID
2477 must contain {vm-type}.
2479 When a resource is associated with a single external network, the
2480 resource ID must contain {network-role}.
2482 When a resource is associated with a single internal network, the
2483 resource ID must contain int\_{network-role}.
2485 When a resource is associated with a single {vm-type} and a single
2486 external network, the resource ID must contain both the {vm-type} and
2489 - The {vm-type} must appear before the {network-role} and must be
2490 separated by an underscore (i.e., {vm-type}\_{network-role}).
2492 - Note that an {index} value may separate the {vm-type} and the
2493 {network-role}. An underscore will separate the three values (i.e.,
2494 {vm-type}\_{index}\_{network-role}).
2496 When a resource is associated with a single {vm-type} and a single
2497 internal network, the resource ID must contain both the {vm-type} and
2498 int\_{network-role}.
2500 - The {vm-type} must appear before the int\_{network-role} and must be
2501 separated by an underscore (i.e., {vm-type}\_int\_{network-role}).
2503 - Note that an {index} value may separate the {vm-type} and the
2504 int\_{network-role}. An underscore will separate the three values
2505 (i.e., {vm-type}\_{index}\_int\_{network-role}).
2507 When a resource is associated with more than one {vm-type} and/or more
2508 than one network, the resource ID
2510 - must not contain the {vm-type} and/or
2511 {network-role}/int\_{network-role}
2513 - should contain the term “shared” and/or contain text that identifies
2516 Only alphanumeric characters and “\_” underscores must be used in the
2517 resource ID. Special characters must not be used.
2519 All {index} values must be zero based. That is, the {index} must start
2520 at zero and increment by one.
2522 The table below provides example OpenStack Heat resource ID for
2523 resources only associated with one {vm-type} and/or one network.
2525 +--------------------------------+------------------------------------------------------------+
2526 | Resource Type | Resource ID Format |
2527 +================================+============================================================+
2528 | OS::Cinder::Volume | {vm\_type}\_volume\_{index} |
2529 +--------------------------------+------------------------------------------------------------+
2530 | OS::Cinder::VolumeAttachment | {vm\_type}\_volumeattachment\_{index} |
2531 +--------------------------------+------------------------------------------------------------+
2532 | OS::Heat::CloudConfig | {vm\_type}\_RCC |
2533 +--------------------------------+------------------------------------------------------------+
2534 | OS::Heat::MultipartMime | {vm\_type}\_RMM |
2535 +--------------------------------+------------------------------------------------------------+
2536 | OS::Heat::ResourceGroup | {vm\_type}\_RRG |
2537 +--------------------------------+------------------------------------------------------------+
2538 | OS::Heat::SoftwareConfig | {vm\_type}\_RSC |
2539 +--------------------------------+------------------------------------------------------------+
2540 | OS::Neutron::Port | {vm\_type}\_{index}\_{network\_role}\_{index}\_port |
2541 +--------------------------------+------------------------------------------------------------+
2542 | | {vm\_type}\_{index}\_int\_{network\_role}\_{index}\_port |
2543 +--------------------------------+------------------------------------------------------------+
2544 | OS::Neutron::SecurityGroup | {vm\_type}\_RSG |
2545 +--------------------------------+------------------------------------------------------------+
2546 | OS::Neutron::Subnet | {network\_role}\_subnet\_{index} |
2547 +--------------------------------+------------------------------------------------------------+
2548 | OS::Nova::Server | {vm\_type}\_{index} |
2549 +--------------------------------+------------------------------------------------------------+
2550 | OS::Nova::ServerGroup | {vm\_type}\_RSG |
2551 +--------------------------------+------------------------------------------------------------+
2552 | OS::Swift::Container | {vm\_type}\_RSwiftC |
2553 +--------------------------------+------------------------------------------------------------+
2555 Table 1: Example OpenStack Heat Resource ID
2557 The table below provides example Contrail Heat resource ID for resources
2558 only associated with one {vm-type} and/or one network.
2560 +-------------------------------------------+---------------------------------------------+
2561 | Resource Type | Resource ID Format |
2562 +===========================================+=============================================+
2563 | OS::ContrailV2::InstanceIp | {vm\_type}\_{index}\_{network\_role}\_RII |
2564 +-------------------------------------------+---------------------------------------------+
2565 | OS::ContrailV2::InterfaceRouteTable | {network\_role}\_RIRT |
2566 +-------------------------------------------+---------------------------------------------+
2567 | OS::ContrailV2::NetworkIpam | {network\_role}\_RNI |
2568 +-------------------------------------------+---------------------------------------------+
2569 | OS::ContrailV2::PortTuple | {vm\_type}\_RPT |
2570 +-------------------------------------------+---------------------------------------------+
2571 | OS::ContrailV2::ServiceHealthCheck | {vm\_type}\_RSHC\_{LEFT\|RIGHT} |
2572 +-------------------------------------------+---------------------------------------------+
2573 | OS::ContrailV2::ServiceTemplate | {vm\_type}\_RST\_{index} |
2574 +-------------------------------------------+---------------------------------------------+
2575 | OS::ContrailV2::VirtualMachineInterface | int\_{network\_role}\_RVMI |
2576 +-------------------------------------------+---------------------------------------------+
2577 | OS::ContrailV2::VirtualNetwork | int\_{network\_role}\_RVN |
2578 +-------------------------------------------+---------------------------------------------+
2580 Table 2: Example Contrail Heat resource ID
2582 Resource: OS::Nova::Server - Parameters
2583 ---------------------------------------
2585 The resource OS::Nova::Server manages the running virtual machine (VM)
2586 instance within an OpenStack cloud. (See
2587 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::Server.)
2589 Four properties of this resource must follow the ONAP parameter naming
2590 convention. The four properties are:
2598 4. availability\_zone
2600 The table below provides a summary. The sections that follow provides
2603 Note that the {vm\_type} must be identical across all four property
2604 parameter for a given OS::Nova::Server resource.
2606 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2607 | Resource OS::Nova::Server |
2608 +=============================+===============================+==================+==============================+=================================+
2609 | Property Name | ONAP Parameter Name | Parameter Type | Parameter Value Generation | ONAP Parameter Classification |
2610 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2611 | image | {vm-type}\_image\_name | string | Environment File | ONAP Constant |
2612 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2613 | flavor | {vm-type}\_flavor\_name | string | Environment File | ONAP Constant |
2614 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2615 | name | {vm-type}\_name\_{index} | string | ONAP | ONAP Orchestration |
2616 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2617 | | {vm-type}\_names | CDL | ONAP | ONAP Orchestration |
2618 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2619 | availability\_zone | availability\_zone\_{index} | string | ONAP | ONAP Orchestration |
2620 +-----------------------------+-------------------------------+------------------+------------------------------+---------------------------------+
2622 Table 3 Resource Property Parameter Names
2627 The parameter associated with the property image is an ONAP Constant
2630 The parameters must be named {vm-type}\_image\_name in the Heat
2631 Orchestration Template.
2633 The parameter must be declared as type: string
2635 The parameter must be enumerated in the Heat Orchestration Template
2638 Each VM type (i.e., {vm-type}) must have a separate parameter for image,
2639 even if more than one {vm-type} shares the same image. This provides
2640 maximum clarity and flexibility.
2642 *Example Parameter Definition*
2644 .. code-block:: yaml
2647 {vm-type}_image_name:
2649 description: {vm-type} server image
2654 The parameter associated with the property flavor is an ONAP Constant
2657 The parameters must be named {vm-type}\_flavor\_name in the Heat
2658 Orchestration Template.
2660 The parameter must be declared as type: string
2662 The parameter must be enumerated in the Heat Orchestration Template
2665 Each VM type (i.e., {vm-type}) must have a separate parameter for
2666 flavors, even if more than one {vm-type} shares the same flavor. This
2667 provides maximum clarity and flexibility.
2669 *Example Parameter Definition*
2671 .. code-block:: yaml
2674 {vm-type}_flavor_name:
2676 description: {vm-type} flavor
2681 The parameter associated with the property name is an ONAP Orchestration
2684 The parameter value is provided to the Heat template by ONAP. The
2685 parameter must not be enumerated in the environment file.
2687 The parameter must be declared as type: string or type:
2688 comma\_delimited\_list
2690 If the parameter is declared as type:string, the parameter must be named
2691 {vm-type}\_name\_{index}, where {index} is a numeric value that starts
2692 at zero and increments by one.
2694 If the parameter is declared as type:comma\_delimited\_list, the
2695 parameter must be named as {vm-type}\_names
2697 Each element in the VM Name list should be assigned to successive
2698 instances of that VM type.
2700 If a VNF contains more than three instances of a given {vm-type}, the
2701 comma\_delimited\_list form of the parameter name (i.e.,
2702 {vm-type}\_names) should be used to minimize the number of unique
2703 parameters defined in the Heat.
2705 *Example: Parameter Definition*
2707 .. code-block:: yaml
2711 type: comma_delimited_list
2712 description: VM Names for {vm-type} VMs
2713 {vm-type}_name_{index}:
2715 description: VM Name for {vm-type} VM {index}
2717 *Example: comma\_delimited\_list*
2719 In this example, the {vm-type} has been defined as “lb” for load
2722 .. code-block:: yaml
2726 type: comma_delimited_list
2727 description: VM Names for lb VMs
2731 type: OS::Nova::Server
2733 name: { get_param: [lb_names, 0] }
2737 type: OS::Nova::Server
2739 name: { get_param: [lb_names, 1] }
2742 *Example: fixed-index*
2744 In this example, the {vm-type} has been defined as “lb” for load
2747 .. code-block:: yaml
2752 description: VM Name for lb VM 0
2756 description: VM Name for lb VM 1
2760 type: OS::Nova::Server
2762 name: { get_param: lb_name_0 }
2766 type: OS::Nova::Server
2768 name: { get_param: lb_name_1 }
2771 Contrail Issue with Values for OS::Nova::Server Property Name
2772 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2774 The Contrail GUI has a limitation displaying special characters. The
2775 issue is documented in
2776 https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is
2777 recommended that special characters be avoided. However, if special
2778 characters must be used, the only special characters supported are:
2780 - “ ! $ ‘ ( ) = ~ ^ \| @ \` { } [ ] > , . \_
2782 Property: availability\_zone
2783 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2785 The parameter associated with the property availability\_zone is an ONAP
2786 Orchestration parameter.
2788 The parameter value is provided to the Heat template by ONAP. The
2789 parameter must not be enumerated in the environment file.
2791 The parameter must be named availability\_zone\_{index} in the Heat
2792 Orchestration Template. The {index} must start at zero. The {index} must
2793 increment by one. The parameter name must not include the {vm-type}.
2795 The parameter must be declared as type: string
2797 The parameter must not be declared as type: comma\_delimited\_list
2802 The example below depicts part of a Heat Orchestration Template that
2803 uses the four OS::Nova::Server properties discussed in this section.
2805 In the Heat Orchestration Template below, four Virtual Machines
2806 (OS::Nova::Server) are created: two dns servers with {vm-type} set to
2807 “dns” and two oam servers with {vm-type} set to “oam”. Note that the
2808 parameter associated with the property name is a comma\_delimited\_list
2809 for dns and a string for oam.
2811 .. code-block:: yaml
2816 description: dns server image
2819 description: dns server flavor
2821 type: comma_delimited_list
2822 description: dns server names
2825 description: oam server image
2828 description: oam server flavor
2831 description: oam server name 0
2834 description: oam server name 1
2835 availability_zone_0:
2837 description: availability zone ID or Name
2838 availability_zone_1:
2840 description: availability zone ID or Name
2844 type: OS::Nova::Server
2846 name: { get_param: [ dns_names, 0 ] }
2847 image: { get_param: dns_image_name }
2848 flavor: { get_param: dns_flavor_name }
2849 availability_zone: { get_param: availability_zone_0 }
2853 type: OS::Nova::Server
2855 name: { get_param: [ dns_names, 1 ] }
2856 image: { get_param: dns_image_name }
2857 flavor: { get_param: dns_flavor_name }
2858 availability_zone: { get_param: availability_zone_1 }
2862 type: OS::Nova::Server
2864 name: { get_param: oam_name_0 }
2865 image: { get_param: oam_image_name }
2866 flavor: { get_param: oam_flavor_name }
2867 availability_zone: { get_param: availability_zone_0 }
2871 type: OS::Nova::Server
2873 name: { get_param: oam_name_1 }
2874 image: { get_param: oam_image_name }
2875 flavor: { get_param: oam_flavor_name }
2876 availability_zone: { get_param: availability_zone_1 }
2879 Resource: OS::Nova::Server – Metadata Parameters
2880 ------------------------------------------------
2882 The resource OS::Nova::Server has an OpenStack optional property
2883 metadata. The metadata property is mandatory for ONAP Heat Orchestration
2884 Templates; it must be included.
2886 ONAP requires the following three mandatory metadata parameters for an
2887 OS::Nova::Server resource:
2895 ONAP allows the following three optional metadata parameters for an
2896 OS::Nova::Server resource. They may be included
2902 Note that the metadata parameters do not and must not contain {vm-type}
2905 When Metadata parameters are past into a nested heat template, the
2906 parameter names must not change.
2908 The table below provides a summary. The sections that follow provides
2911 +---------------------------+------------------+----------------------+------------------------------+
2912 | Metadata Parameter Name | Parameter Type | Mandatory/Optional | Parameter Value Generation |
2913 +===========================+==================+======================+==============================+
2914 | vnf\_id | string | Mandatory | ONAP |
2915 +---------------------------+------------------+----------------------+------------------------------+
2916 | vf\_module\_id | string | Mandatory | ONAP |
2917 +---------------------------+------------------+----------------------+------------------------------+
2918 | vnf\_name | string | Mandatory | ONAP |
2919 +---------------------------+------------------+----------------------+------------------------------+
2920 | vf\_module\_name | string | Optional | ONAP |
2921 +---------------------------+------------------+----------------------+------------------------------+
2922 | vm\_role | string | Optional | YAML or Environment File |
2923 +---------------------------+------------------+----------------------+------------------------------+
2924 +---------------------------+------------------+----------------------+------------------------------+
2926 Table 4: ONAP Metadata
2931 The vnf\_id parameter is mandatory; it must be included in the Heat
2932 Orchestration Template.
2934 The vnf\_id parameter value will be supplied by ONAP. ONAP generates the
2935 UUID that is the vnf\_id and supplies it to the Heat Orchestration
2936 Template at orchestration time.
2938 The parameter must be declared as type: string
2940 Parameter constraints must not be defined.
2942 The parameter must not be enumerated in the Heat environment file.
2944 *Example Parameter Definition*
2946 .. code-block:: yaml
2951 description: Unique ID for this VNF instance
2956 The vf\_module\_id parameter is mandatory; it must be included in the
2957 Heat Orchestration Template.
2959 The vf\_module\_id parameter value will be supplied by ONAP. ONAP
2960 generates the UUID that is the vf\_module\_id and supplies it to the
2961 Heat Orchestration Template at orchestration time.
2963 The parameter must be declared as type: string
2965 Parameter constraints must not be defined.
2967 The parameter must not be enumerated in the Heat environment file.
2969 *Example Parameter Definition*
2971 .. code-block:: yaml
2976 description: Unique ID for this VNF module instance
2981 The vnf\_name parameter is mandatory; it must be included in the Heat
2982 Orchestration Template.
2984 The vnf\_name parameter value will be generated and/or assigned by ONAP
2985 and supplied to the Heat Orchestration Template by ONAP at orchestration
2988 The parameter must be declared as type: string
2990 Parameter constraints must not be defined.
2992 The parameter must not be enumerated in the Heat environment file.
2994 *Example Parameter Definition*
2996 .. code-block:: yaml
3001 description: Unique name for this VNF instance
3006 The vf\_module\_name parameter is optional; it may be included in the
3007 Heat Orchestration Template.
3009 The vf\_module\_name parameter is the name of the name of the Heat stack
3010 (e.g., <STACK\_NAME>) in the command “Heat stack-create” (e.g., Heat
3011 stack-create [-f <FILE>] [-e <FILE>] <STACK\_NAME>). The <STACK\_NAME>
3012 needs to be specified as part of the orchestration process.
3014 The parameter must be declared as type: string
3016 Parameter constraints must not be defined.
3018 The parameter must not be enumerated in the Heat environment file.
3020 *Example Parameter Definition*
3022 .. code-block:: yaml
3027 description: Unique name for this VNF Module instance
3032 The vm\_role parameter is optional; it may be included in the Heat
3033 Orchestration Template.
3035 Any roles tagged to the VMs via metadata will be stored in ONAP’s A&AI
3036 system and available for use by other ONAP components and/or north bound
3039 The vm\_role values must be either
3041 - hard-coded into the Heat Orchestration Template or
3043 - enumerated in the environment file.
3045 Defining the vm\_role as the {vm-type} is a recommended convention
3047 The parameter must be declared as type: string
3049 Parameter constraints must not be defined.
3051 *Example Parameter Definition*
3053 .. code-block:: yaml
3058 description: Unique role for this VM
3060 *Example Resource Definition: Hard Coded*
3062 In this example, the {vm-role} is hard coded in the Heat Orchestration
3065 .. code-block:: yaml
3069 type: OS::Nova::Server
3075 *Example Resource Definition: get\_param*
3077 In this example, the {vm-role} is enumerated in the environment file.
3079 .. code-block:: yaml
3083 type: OS::Nova::Server
3087 vm_role: { get_param: vm_role }
3092 The example below depicts part of a Heat Orchestration Template that
3093 uses the five of the OS::Nova::Server metadata parameter discussed in
3094 this section. The {vm-type} has been defined as lb for load balancer.
3096 .. code-block:: yaml
3101 description: VM Name for lb VM 0
3104 description: Unique name for this VNF instance
3107 description: Unique ID for this VNF instance
3110 description: Unique name for this VNF Module instance
3113 description: Unique ID for this VNF Module instance
3116 description: Unique role for this VM
3121 type: OS::Nova::Server
3123 name: { get_param: lb_name_0 }
3126 vnf_name: { get_param: vnf_name }
3127 vnf_id: { get_param: vnf_id }
3128 vf_module_name: { get_param: vf_module_name }
3129 vf_module_id: { get_param: vf_module_id }
3132 Resource: OS::Neutron::Port - Parameters
3133 ----------------------------------------
3135 The resource OS::Neutron::Port is for managing Neutron ports (See
3136 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Port.)
3141 Four properties of the resource OS::Neutron::Port that must follow the
3142 ONAP parameter naming convention. The four properties are:
3146 2. fixed\_ips, ip\_address
3148 3. fixed\_ips, subnet\_id
3150 4. allowed\_address\_pairs, ip\_address
3152 The parameters associated with these properties may reference an
3153 external network or internal network. External networks and internal
3154 networks are defined in `Networking`_.
3159 When the parameter references an external network
3161 - the parameter name must contain {network-role}
3163 - the parameter must not be enumerated in the Heat environment file
3165 - the parameter is classified as an ONAP Orchestration Parameter
3167 +----------------------------------------+-----------------------------------------------+--------------------------+
3168 | Property Name | ONAP Parameter Name | Parameter Type |
3169 +========================================+===============================================+==========================+
3170 | network | {network-role}\_net\_id | string |
3171 +----------------------------------------+-----------------------------------------------+--------------------------+
3172 | | {network-role}\_net\_name | string |
3173 +----------------------------------------+-----------------------------------------------+--------------------------+
3174 | fixed\_ips, ip\_address | {vm-type}\_{network-role}\_ip\_{index} | string |
3175 +----------------------------------------+-----------------------------------------------+--------------------------+
3176 | | {vm-type}\_{network-role}\_ips | comma\_delimited\_list |
3177 +----------------------------------------+-----------------------------------------------+--------------------------+
3178 | | {vm-type}\_{network-role}\_v6\_ip\_{index} | string |
3179 +----------------------------------------+-----------------------------------------------+--------------------------+
3180 | | {vm-type}\_{network-role}\_v6\_ips | comma\_delimited\_list |
3181 +----------------------------------------+-----------------------------------------------+--------------------------+
3182 | fixed\_ips, subnet | {network-role}\_subnet\_id | string |
3183 +----------------------------------------+-----------------------------------------------+--------------------------+
3184 | | {network-role}\_v6\_subnet\_id | string |
3185 +----------------------------------------+-----------------------------------------------+--------------------------+
3186 | allowed\_address\_pairs, ip\_address | {vm-type}\_{network-role}\_floating\_ip | string |
3187 +----------------------------------------+-----------------------------------------------+--------------------------+
3188 | | {vm-type}\_{network-role}\_floating\_v6\_ip | string |
3189 +----------------------------------------+-----------------------------------------------+--------------------------+
3190 | | {vm-type}\_{network-role}\_ip\_{index} | string |
3191 +----------------------------------------+-----------------------------------------------+--------------------------+
3192 | | {vm-type}\_{network-role}\_ips | comma\_delimited\_list |
3193 +----------------------------------------+-----------------------------------------------+--------------------------+
3194 | | {vm-type}\_{network-role}\_v6\_ip\_{index} | string |
3195 +----------------------------------------+-----------------------------------------------+--------------------------+
3196 | | {vm-type}\_{network-role}\_v6\_ips | comma\_delimited\_list |
3197 +----------------------------------------+-----------------------------------------------+--------------------------+
3199 Table 5: OS::Neutron::Port Resource Property Parameters (External
3205 When the parameter references an internal network
3207 - the parameter name must contain int\_{network-role}
3209 - the parameter may be enumerated in the environment file.
3211 +----------------------------------------+----------------------------------------------------+--------------------------+
3212 | Property | Parameter Name for Internal Networks | Parameter Type |
3213 +========================================+====================================================+==========================+
3214 | network | int\_{network-role}\_net\_id | string |
3215 +----------------------------------------+----------------------------------------------------+--------------------------+
3216 | | int\_{network-role}\_net\_name | string |
3217 +----------------------------------------+----------------------------------------------------+--------------------------+
3218 | fixed\_ips, ip\_address | {vm-type}\_int\_{network-role}\_ip\_{index} | string |
3219 +----------------------------------------+----------------------------------------------------+--------------------------+
3220 | | {vm-type}\_int\_{network-role}\_ips | comma\_delimited\_list |
3221 +----------------------------------------+----------------------------------------------------+--------------------------+
3222 | | {vm-type}\_int\_{network-role}\_v6\_ip\_{index} | string |
3223 +----------------------------------------+----------------------------------------------------+--------------------------+
3224 | | {vm-type}\_int\_{network-role}\_v6\_ips | comma\_delimited\_list |
3225 +----------------------------------------+----------------------------------------------------+--------------------------+
3226 | fixed\_ips, subnet | int\_{network-role}\_subnet\_id | string |
3227 +----------------------------------------+----------------------------------------------------+--------------------------+
3228 | | int\_{network-role}\_v6\_subnet\_id | string |
3229 +----------------------------------------+----------------------------------------------------+--------------------------+
3230 | allowed\_address\_pairs, ip\_address | {vm-type}\_int\_{network-role}\_floating\_ip | string |
3231 +----------------------------------------+----------------------------------------------------+--------------------------+
3232 | | {vm-type}\_int\_{network-role}\_floating\_v6\_ip | string |
3233 +----------------------------------------+----------------------------------------------------+--------------------------+
3234 | | {vm-type}\_int\_{network-role}\_ip\_{index} | string |
3235 +----------------------------------------+----------------------------------------------------+--------------------------+
3236 | | {vm-type}\_int\_{network-role}\_ips | comma\_delimited\_list |
3237 +----------------------------------------+----------------------------------------------------+--------------------------+
3238 | | {vm-type}\_int\_{network-role}\_v6\_ip\_{index} | string |
3239 +----------------------------------------+----------------------------------------------------+--------------------------+
3240 | | {vm-type}\_int\_{network-role}\_v6\_ips | comma\_delimited\_list |
3241 +----------------------------------------+----------------------------------------------------+--------------------------+
3243 Table 6: Port Resource Property Parameters (Internal Networks)
3248 The property networks in the resource OS::Neutron::Port must be
3249 referenced by Neutron Network ID, a UUID value, or by the network name
3250 defined in OpenStack.
3255 When the parameter associated with the property network is referencing
3256 an “external” network, the parameter must adhere to the following naming
3257 convention in the Heat Orchestration Template
3259 - {network-role}\_net\_id for the Neutron network ID
3261 - {network-role}\_net\_name for the network name in OpenStack
3263 The parameter must be declared as type: string
3265 The parameter must not be enumerated in the Heat environment file.
3267 *Example Parameter Definition*
3269 .. code-block:: yaml
3272 {network-role}_net_id:
3274 description: Neutron UUID for the {network-role} network
3275 {network-role}_net_name:
3277 description: Neutron name for the {network-role} network
3279 *Example: One Cloud Assigned IP Address (DHCP) assigned to a network
3280 that has only one subnet*
3282 In this example, the {network-role} has been defined as oam to represent
3283 an oam network and the {vm-type} has been defined as lb for load
3284 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3285 to assign IP addresses.
3287 .. code-block:: yaml
3292 description: Neutron UUID for the oam network
3296 type: OS::Neutron::Port
3297 network: { get_param: oam_net_id }
3302 When the parameter associated with the property network is referencing
3303 an “internal” network, the parameter must adhere to the following naming
3306 - int\_{network-role}\_net\_id for the Neutron network ID
3308 - int\_{network-role}\_net\_name for the network name in OpenStack
3310 The parameter must be declared as type: string
3312 The assumption is that internal networks are created in the base module.
3313 The Neutron Network ID will be passed as an output parameter (e.g., ONAP
3314 Base Module Output Parameter) to the incremental modules. In the
3315 incremental modules, it will be defined as input parameter.
3317 *Example Parameter Definition*
3319 .. code-block:: yaml
3322 int_{network-role}_net_id:
3324 description: Neutron UUID for the {network-role} network
3325 int_{network-role}_net_name:
3327 description: Neutron name for the {network-role} network
3329 Property: fixed\_ips, Map Property: subnet\_id
3330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3332 The property fixed\_ips is used to assign IPs to a port. The Map
3333 Property subnet\_id specifies the subnet the IP is assigned from.
3335 The property fixed\_ips and Map Property subnet\_id must be used if a
3336 Cloud (i.e., DHCP) IP address assignment is being requested and the
3337 Cloud IP address assignment is targeted at a specific subnet when two or
3340 The property fixed\_ips and Map Property subnet\_id should not be used
3341 if all IP assignments are fixed, or if the Cloud IP address assignment
3342 does not target a specific subnet or there is only one subnet.
3344 Note that DHCP assignment of IP addresses is also referred to as cloud
3345 assigned IP addresses.
3347 Subnet of an External Networks
3348 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3350 When the parameter is referencing a subnet of an “external” network, the
3351 property fixed\_ips and Map Property subnet\_id parameter must adhere to
3352 the following naming convention.
3354 - {network-role}\_subnet\_id if the subnet is an IPv4 subnet
3356 - {network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
3358 The parameter must be declared as type: string
3360 The parameter must not be enumerated in the Heat environment file.
3362 *Example Parameter Definition*
3364 .. code-block:: yaml
3367 {network-role}_subnet_id:
3369 description: Neutron subnet UUID for the {network-role} network
3371 {network-role}_v6_subnet_id:
3373 description: Neutron subnet UUID for the {network-role} network
3375 *Example: One Cloud Assigned IPv4 Address (DHCP) assigned to a network
3376 that has two or more subnets subnet:*
3378 In this example, the {network-role} has been defined as oam to represent
3379 an oam network and the {vm-type} has been defined as lb for load
3380 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3381 to assign IP addresses.
3383 .. code-block:: yaml
3388 description: Neutron UUID for the oam network
3392 description: Neutron subnet UUID for the oam network
3396 type: OS::Neutron::Port
3397 network: { get_param: oam_net_id }
3399 - subnet_id: { get_param: oam_subnet_id }
3401 *Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6
3402 address assigned to a network that has at least one IPv4 subnet and one
3405 In this example, the {network-role} has been defined as oam to represent
3406 an oam network and the {vm-type} has been defined as lb for load
3409 .. code-block:: yaml
3414 description: Neutron UUID for the oam network
3418 description: Neutron subnet UUID for the oam network
3422 description: Neutron subnet UUID for the oam network
3426 type: OS::Neutron::Port
3428 network: { get_param: oam_net_id }
3430 - subnet_id: { get_param: oam_subnet_id }
3431 - subnet_id: { get_param: oam_v6_subnet_id }
3436 When the parameter is referencing the subnet of an “internal” network,
3437 the property fixed\_ips and Map Property subnet\_id parameter must
3438 adhere to the following naming convention.
3440 - int\_{network-role}\_subnet\_id if the subnet is an IPv4 subnet
3442 - int\_{network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
3444 The parameter must be declared as type: string
3446 The assumption is that internal networks are created in the base module.
3447 The Neutron subnet network ID will be passed as an output parameter
3448 (e.g., ONAP Base Module Output Parameter) to the incremental modules. In
3449 the incremental modules, it will be defined as input parameter.
3451 *Example Parameter Definition*
3453 .. code-block:: yaml
3456 int_{network-role}_subnet_id:
3458 description: Neutron subnet UUID for the {network-role} network
3460 int_{network-role}_v6_subnet_id:
3462 description: Neutron subnet UUID for the {network-role} network
3464 Property: fixed\_ips, Map Property: ip\_address
3465 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3467 The property fixed\_ips is used to assign IPs to a port. The Map
3468 Property ip\_address specifies the IP address to be assigned to the
3471 The property fixed\_ips and Map Property ip\_address must be used when
3472 statically assigning one or more IP addresses to a port. This is also
3473 referred to as ONAP SDN-C IP address assignment. ONAP’s SDN-C provides
3474 the IP address assignment.
3476 An IP address is assigned to a port on a VM (referenced by {vm-type})
3477 that is connected to an external network (referenced by {network-role})
3478 or internal network (referenced by int\_{network-role}).
3480 When a SDN-C IP assignment is made to a port connected to an external
3481 network, the parameter name must contain {vm-type} and {network-role}.
3483 When a SDN-C IP assignment is made to a port connected to an internal
3484 network, the parameter name must contain {vm-type} and
3485 int\_{network-role}.
3487 IP Address Assignments on External Networks
3488 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3490 When the property fixed\_ips and Map Property ip\_address is used to
3491 assign IP addresses to an external network, the parameter name is
3492 dependent on the parameter type (comma\_delimited\_list or string) and
3493 IP address type (IPv4 or IPv6).
3495 When the parameter for property fixed\_ips and Map Property ip\_address
3496 is declared type: comma\_delimited\_list, the parameter must adhere to
3497 the following naming convention
3499 - {vm-type}\_{network-role}\_ips for IPv4 address
3501 - {vm-type}\_{network-role}\_v6\_ips for IPv6 address
3503 Each element in the IP list should be assigned to successive instances
3504 of {vm-type} on {network-role}.
3506 The parameter must not be enumerated in the Heat environment file.
3508 *Example Parameter Definition*
3510 .. code-block:: yaml
3514 {vm-type}_{network-role}_ips:
3515 type: comma_delimited_list
3516 description: Fixed IPv4 assignments for {vm-type} VMs on the {Network-role} network
3518 {vm-type}_{network-role}_v6_ips:
3519 type: comma_delimited_list
3520 description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
3522 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
3523 Assignments to an external network*
3525 In this example, the {network-role} has been defined as oam to represent
3526 an oam network and the {vm-type} has been defined as db for database.
3528 .. code-block:: yaml
3533 description: Neutron UUID for a oam network
3536 type: comma_delimited_list
3537 description: Fixed IPv4 assignments for db VMs on the oam network
3540 type: comma_delimited_list
3541 description: Fixed IPv6 assignments for db VMs on the oam network
3545 type: OS::Neutron::Port
3546 network: { get_param: oam_net_id }
3547 fixed_ips: [ { “ip_address”: {get_param: [ db_oam_ips, 0 ]}}, {“ip_address”: {get_param: [ db_oam_v6_ips, 0 ]}}]
3550 type: OS::Neutron::Port
3552 network: { get_param: oam_net_id }
3554 - “ip_address”: {get_param: [ db_oam_ips, 1 ]}
3555 - “ip_address”: {get_param: [ db_oam_v6_ips, 1 ]}
3557 When the parameter for property fixed\_ips and Map Property ip\_address
3558 is declared type: string, the parameter must adhere to the following
3561 - {vm-type}\_{network-role}\_ip\_{index} for an IPv4 address
3563 - {vm-type}\_{network-role}\_v6\_ip\_{index} for an IPv6 address
3565 The value for {index} must start at zero (0) and increment by one.
3567 The parameter must not be enumerated in the Heat environment file.
3569 *Example Parameter Definition*
3571 .. code-block:: yaml
3574 {vm-type}_{network-role}_ip_{index}:
3576 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
3578 {vm-type}_{network-role}_v6_ip_{index}:
3580 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
3582 *Example: string parameters for IPv4 and IPv6 Address Assignments to an external network*
3584 In this example, the {network-role} has been defined as “oam” to
3585 represent an oam network and the {vm-type} has been defined as “db” for
3588 .. code-block:: yaml
3593 description: Neutron UUID for an OAM network
3597 description: Fixed IPv4 assignment for db VM 0 on the OAM network
3601 description: Fixed IPv4 assignment for db VM 1 on the OAM network
3605 description: Fixed IPv6 assignment for db VM 0 on the OAM network
3609 description: Fixed IPv6 assignment for db VM 1 on the OAM network
3613 type: OS::Neutron::Port
3615 network: { get_param: oam_net_id }
3616 fixed_ips: [ { “ip_address”: {get_param: db_oam_ip_0}}, {“ip_address”: {get_param: db_oam_v6_ip_0 ]}}]
3619 type: OS::Neutron::Port
3621 network: { get_param: oam_net_id }
3623 - “ip_address”: {get_param: db_oam_ip_1}}]
3624 - “ip_address”: {get_param: db_oam_v6_ip_1}}]
3626 IP Address Assignment on Internal Networks
3627 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3629 When the property fixed\_ips and Map Property ip\_address is used to
3630 assign IP addresses to an internal network, the parameter name is
3631 dependent on the parameter type (comma\_delimited\_list or string) and
3632 IP address type (IPv4 or IPv6).
3634 When the parameter for property fixed\_ips and Map Property ip\_address
3635 is declared type: comma\_delimited\_list, the parameter must adhere to
3636 the following naming convention
3638 - {vm-type}\_int\_{network-role}\_ips for IPv4 address
3640 - {vm-type}\_int\_{network-role}\_v6\_ips for IPv6 address
3642 Each element in the IP list should be assigned to successive instances
3643 of {vm-type} on {network-role}.
3645 The parameter must be enumerated in the Heat environment file. Since an
3646 internal network is local to the VNF, IP addresses can be re-used at
3649 *Example Parameter Definition*
3651 .. code-block:: yaml
3655 {vm-type}_int_{network-role}_ips:
3656 type: comma_delimited_list
3657 description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
3659 {vm-type}_int_{network-role}_v6_ips:
3660 type: comma_delimited_list
3661 description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
3663 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
3664 Assignments to an internal network*
3666 In this example, the {network-role} has been defined as oam\_int to
3667 represent an oam network internal to the vnf. The role oam\_int was
3668 picked to differentiate from an external oam network with a
3669 {network-role} of oam. The {vm-type} has been defined as db for
3672 .. code-block:: yaml
3677 description: Neutron UUID for the oam internal network
3680 type: comma_delimited_list
3681 description: Fixed IPv4 assignments for db VMs on the oam internal network
3683 db_int_oam_int_v6_ips:
3684 type: comma_delimited_list
3685 description: Fixed IPv6 assignments for db VMs on the oam internal network
3689 type: OS::Neutron::Port
3691 network: { get_param: int_oam_int_net_id }
3692 fixed_ips: [ { “ip_address”: {get_param: [ db_int_oam_int_ips, 0]}}, { “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 0 ]}}]
3695 type: OS::Neutron::Port
3697 network: { get_param: int_oam_int_net_id }
3699 - “ip_address”: {get_param: [ db_int_oam_int_ips, 1 ]}
3700 - “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 1 ]}
3702 When the parameter for property fixed\_ips and Map Property ip\_address
3703 is declared type: string, the parameter must adhere to the following
3706 - {vm-type}\_int\_{network-role}\_ip\_{index} for an IPv4 address
3708 - {vm-type}\_int\_{network-role}\_v6\_ip\_{index} for an IPv6 address
3710 The value for {index} must start at zero (0) and increment by one.
3712 The parameter must be enumerated in the Heat environment file. Since an
3713 internal network is local to the VNF, IP addresses can be re-used at
3716 *Example Parameter Definition*
3718 .. code-block:: yaml
3722 {vm-type}_int_{network-role}_ip_{index}:
3724 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
3726 {vm-type}_int_{network-role}_v6_ip_{index}:
3728 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
3730 *Example: string parameters for IPv4 and IPv6 Address Assignments to an internal network*
3732 In this example, the {network-role} has been defined as oam\_int to
3733 represent an oam network internal to the vnf. The role oam\_int was
3734 picked to differentiate from an external oam network with a
3735 {network-role} of oam. The {vm-type} has been defined as db for
3738 .. code-block:: yaml
3743 description: Neutron UUID for an OAM internal network
3747 description: Fixed IPv4 assignment for db VM on the oam_int network
3751 description: Fixed IPv4 assignment for db VM 1 on the oam_int network
3755 description: Fixed IPv6 assignment for db VM 0 on the oam_int network
3759 description: Fixed IPv6 assignment for db VM 1 on the oam_int network
3763 type: OS::Neutron::Port
3765 network: { get_param: int_oam_int_net_id }
3766 fixed_ips: [ { “ip_address”: {get_param: db_oam_int_ip_0}}, {“ip_address”: {get_param: db_oam_int_v6_ip_0 ]}}]
3769 type: OS::Neutron::Port
3771 network: { get_param: int_oam_int_net_id }
3773 - “ip_address”: {get_param: db_oam_int_ip_1}}]
3774 - “ip_address”: {get_param: db_oam_int_v6_ip_1}}]
3776 Property: allowed\_address\_pairs, Map Property: ip\_address
3777 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3779 The property allowed\_address\_pairs in the resource OS::Neutron::Port
3780 allows the user to specify a mac\_address and/or ip\_address that will
3781 pass through a port regardless of subnet. This enables the use of
3782 protocols such as VRRP, which floats an IP address between two instances
3783 to enable fast data plane failover. The map property ip\_address
3784 specifies the IP address.
3786 The allowed\_address\_pairs is an optional property. It is not required.
3788 An ONAP Heat Orchestration Template allows the assignment of one IPv4
3789 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
3790 and {network-role}/int\_{network-role} combination.
3792 An ONAP Heat Orchestration Template allows the assignment of one IPv6
3793 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
3794 and {network-role}/int\_{network-role} combination.
3796 Note that the management of these IP addresses (i.e. transferring
3797 ownership between active and standby VMs) is the responsibility of the
3800 Note that these parameters are **not** intended to represent Neutron
3801 “Floating IP” resources, for which OpenStack manages a pool of public IP
3802 addresses that are mapped to specific VM ports. In that case, the
3803 individual VMs are not even aware of the public IPs, and all assignment
3804 of public IPs to VMs is via OpenStack commands. ONAP does not support
3805 Neutron-style Floating IPs.
3810 When the parameter is referencing an “external” network, the property
3811 allowed\_address\_pairs and Map Property ip\_address parameter must
3812 adhere to the following naming convention.
3814 - {vm-type}\_{network-role}\_floating\_ip for an IPv4 address
3816 - {vm-type}\_{network-role}\_floating\_v6\_ip for an IPv6 address
3818 The parameter must be declared as type: string
3820 The parameter must not be enumerated in the Heat environment file.
3822 *Example Parameter Definition*
3824 .. code-block:: yaml
3828 {vm-type}_{network-role}_floating_ip:
3830 description: VIP for {vm-type} VMs on the {network-role} network
3832 {vm-type}_{network-role}_floating_v6_ip:
3834 description: VIP for {vm-type} VMs on the {network-role} network
3838 In this example, the {network-role} has been defined as oam to represent
3839 an oam network and the {vm-type} has been defined as db for database.
3841 .. code-block:: yaml
3846 description: Neutron UUID for the oam network
3849 type: comma_delimited_list
3850 description: Fixed IPs for db VMs on the oam network
3854 description: VIP IP for db VMs on the oam network
3858 type: OS::Neutron::Port
3860 network: { get_param: oam_net_id }
3861 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,0] }}]
3862 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
3865 type: OS::Neutron::Port
3867 network: { get_param: oam_net_id }
3868 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,1] }}]
3869 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
3874 When the parameter is referencing an “internal” network, the property
3875 allowed\_address\_pairs and Map Property ip\_address parameter must
3876 adhere to the following naming convention.
3878 - {vm-type}\_int\_{network-role}\_floating\_ip for an IPv4 address
3880 - {vm-type}\_int\_{network-role}\_floating\_v6\_ip for an IPv6 address
3882 The parameter must be declared as type: string
3884 The parameter must be enumerated in the Heat environment file.
3886 *Example Parameter Definition*
3888 .. code-block:: yaml
3892 {vm-type}_int_{network-role}_floating_ip:
3894 description: VIP for {vm-type} VMs on the int_{network-role} network
3896 {vm-type}_int_{network-role}_floating_v6_ip:
3898 description: VIP for {vm-type} VMs on the int_{network-role} network
3900 Multiple allowed\_address\_pairs for a {vm-type} / {network-role} combination
3901 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3903 The parameter {vm-type}\_{network-role}\_floating\_ip provides only one
3904 allowed address pair IPv4 address per {vm-type} and {network-role} pair.
3906 The parameter {vm-type}\_{network-role}\_floating\_v6\_ip provides only
3907 one allowed address pair IPv6 address per {vm-type} and {network-role}
3910 If there is a need for multiple allowed address pair IPs for a given
3911 {vm-type} and {network-role} combination within a VNF, then the
3912 parameter names defined for the property fixed\_ips and Map Property
3913 ip\_address should be used with the allowed\_address\_pairs property.
3914 The examples below illustrate this.
3916 *Example: A VNF has four load balancers. Each pair has a unique VIP.*
3918 In this example, there are two administrative VM pairs. Each pair has
3919 one VIP. The {network-role} has been defined as oam to represent an oam
3920 network and the {vm-type} has been defined as admin for an
3923 Pair 1: Resources admin\_0\_port\_0 and admin\_1\_port\_0 share a unique
3924 VIP, [admin\_oam\_ips,2]
3926 Pair 2: Resources admin\_2\_port\_0 and admin\_3\_port\_0 share a unique
3927 VIP, [admin\_oam\_ips,5]
3929 .. code-block:: yaml
3934 description: Neutron UUID for the oam network
3936 type: comma_delimited_list
3937 description: Fixed IP assignments for admin VMs on the oam network
3942 type: OS::Neutron::Port
3944 network: { get_param: oam_net_id }
3945 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,0] }}]
3946 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
3949 type: OS::Neutron::Port
3951 network: { get_param: oam_net_id }
3952 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,1] }}]
3953 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
3956 type: OS::Neutron::Port
3958 network: { get_param: oam_net_id }
3959 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,3] }}]
3960 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
3963 type: OS::Neutron::Port
3965 network: { get_param: oam_net_id }
3966 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,4] }}]
3967 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
3969 *Example: A VNF has two load balancers. The pair of load balancers share
3972 In this example, there is one load balancer pairs. The pair has two
3973 VIPs. The {network-role} has been defined as oam to represent an oam
3974 network and the {vm-type} has been defined as lb for a load balancer VM.
3976 .. code-block:: yaml
3980 type: OS::Neutron::Port
3982 network: { get_param: oam_net_id }
3983 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,0] }}]
3984 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
3987 type: OS::Neutron::Port
3989 network: { get_param: oam_net_id }
3990 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,1] }}]
3991 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
3993 As a general rule, provide the fixed IPs for the VMs indexed first in
3994 the CDL and then the VIPs as shown in the examples above.
3996 ONAP SDN-C Assignment of allowed\_address\_pair IP Addresses
3997 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
3999 The following items must be taken into consideration when designing Heat
4000 Orchestration Templates that expect ONAP’s SDN-C to assign
4001 allowed\_address\_pair IP addresses via automation.
4003 The VMs must be of the same {vm-type}.
4005 The VMs must be created in the same module (base or incremental).
4007 Resource Property “name”
4008 ------------------------
4010 The parameter naming convention of the property name for the resource
4011 OS::Nova::Server has been defined in `Resource: OS::Nova::Server – Metadata Parameters`_.
4013 This section provides the requirements how the property name for non
4014 OS::Nova::Server resources must be defined when the property is used.
4015 Not all resources require the property name (e.g., it is optional) and
4016 some resources do not support the property.
4018 When the property name for a non OS::Nova::Server resources is defined
4019 in a Heat Orchestration Template, the intrinsic function str\_replace
4020 must be used in conjunction with the ONAP supplied metadata parameter
4021 vnf\_name to generate a unique value. This prevents the enumeration of a
4022 unique value for the property name in a per instance environment file.
4026 - In most cases, only the use of the metadata value vnf\_name is
4027 required to create a unique property name
4029 - the Heat Orchestration Template pseudo parameter 'OS::stack\_name’
4030 may also be used in the str\_replace construct to generate a unique
4031 name when the vnf\_name does not provide uniqueness
4033 *Example: Property* name *for resource* OS::Neutron::SecurityGroup
4035 .. code-block:: yaml
4039 type: OS::Neutron::SecurityGroup
4041 description: vDNS security group
4044 template: VNF_NAME_sec_grp_DNS
4046 VNF_NAME: {get_param: vnf_name}
4050 *Example: Property name for resource* OS::Cinder::Volume
4052 .. code-block:: yaml
4056 type: OS::Cinder::Volume
4058 description: Cinder Volume
4061 template: VNF_NAME_STACK_NAME_dns_volume
4063 VNF_NAME: {get_param: vnf_name}
4064 STACK_NAME: { get_param: 'OS::stack_name' }
4067 Contrail Issue with Values for the Property Name
4068 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4070 The Contrail GUI has a limitation displaying special characters. The
4071 issue is documented in
4072 https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is
4073 recommended that special characters be avoided. However, if special
4074 characters must be used, note that for the following resources:
4088 the only special characters supported are:
4090 - “ ! $ ‘ ( ) = ~ ^ \| @ \` { } [ ] > , . \_
4092 ONAP Output Parameter Names
4093 ---------------------------
4095 ONAP defines three types of Output Parameters as detailed in `Output Parameters`_.
4097 ONAP Base Module Output Parameters:
4098 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4100 ONAP Base Module Output Parameters do not have an explicit naming
4101 convention. The parameter name must contain {vm-type} and {network-role}
4104 ONAP Volume Template Output Parameters:
4105 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4107 ONAP Base Module Output Parameters do not have an explicit naming
4108 convention. The parameter name must contain {vm-type} when appropriate.
4110 Predefined Output Parameters
4111 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4113 ONAP currently defines one predefined output parameter the OAM
4114 Management IP Addresses.
4116 OAM Management IP Addresses
4117 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
4119 A VNF may have a management interface for application controllers to
4120 interact with and configure the VNF. Typically, this will be via a
4121 specific VM that performs a VNF administration function. The IP address
4122 of this interface must be captured and inventoried by ONAP. The IP
4123 address might be a VIP if the VNF contains an HA pair of management VMs,
4124 or may be a single IP address assigned to one VM.
4126 The Heat template may define either (or both) of the following Output
4127 parameters to identify the management IP address.
4129 - oam\_management\_v4\_address
4131 - oam\_management\_v6\_address
4135 - The use of this output parameters are optional.
4137 - The Management IP Address should be defined only once per VNF, so it
4138 must only appear in one Module template
4140 - If a fixed IP for the admin VM is passed as an input parameter, it
4141 may be echoed in the output parameters. In this case, a IPv4 and/or
4142 IPv6 parameter must be defined in the parameter section of the YAML
4143 Heat template. The parameter maybe named oam\_management\_v4\_address
4144 and/or oam\_management\_v6\_address or may be named differently.
4146 - If the IP for the admin VM is obtained via DHCP, it may be obtained
4147 from the resource attributes. In this case,
4148 oam\_management\_v4\_address and/or oam\_management\_v6\_address must
4149 not be defined in the parameter section of the YAML Heat template.
4151 *Example: SDN-C Assigned IP Address echoed as*
4152 oam\_management\_v4\_address
4154 .. code-block:: yaml
4159 description: Fixed IPv4 assignment for admin VM 0 on the OAM network
4163 admin_oam_net_0_port:
4164 type: OS::Neutron::Port
4168 template: VNF_NAME_admin_oam_net_0_port
4170 VNF_NAME: {get_param: vnf_name}
4171 network: { get_param: oam_net_id }
4172 fixed_ips: [{ "ip_address": { get_param: admin_oam_ip_0 }}]
4173 security_groups: [{ get_param: security_group }]
4176 type: OS::Nova::Server
4178 name: { get_param: admin_names }
4179 image: { get_param: admin_image_name }
4180 flavor: { get_param: admin_flavor_name }
4181 availability_zone: { get_param: availability_zone_0 }
4183 - port: { get_resource: admin_oam_net_0_port }
4185 vnf_id: { get_param: vnf_id }
4186 vf_module_id: { get_param: vf_module_id }
4187 vnf_name: {get_param: vnf_name }
4189 oam_management_v4_address:
4190 value: {get_param: admin_oam_ip_0 }
4192 *Example: Cloud Assigned IP Address output as*
4193 oam\_management\_v4\_address
4195 .. code-block:: yaml
4200 admin_oam_net_0_port:
4201 type: OS::Neutron::Port
4205 template: VNF_NAME_admin_oam_net_0_port
4207 VNF_NAME: {get_param: vnf_name}
4208 network: { get_param: oam_net_id }
4209 security_groups: [{ get_param: security_group }]
4212 type: OS::Nova::Server
4214 name: { get_param: admin_names }
4215 image: { get_param: admin_image_name }
4216 flavor: { get_param: admin_flavor_name }
4217 availability_zone: { get_param: availability_zone_0 }
4219 - port: { get_resource: admin_oam_net_0_port }
4221 vnf_id: { get_param: vnf_id }
4222 vf_module_id: { get_param: vf_module_id }
4223 vnf_name: {get_param: vnf_name }
4226 oam_management_v4_address:
4227 value: {get_attr: [admin_server, networks, {get_param: oam_net_id}, 0] }
4229 Contrail Resource Parameters
4230 ----------------------------
4232 ONAP requires the parameter names of certain Contrail Resources to
4233 follow specific naming conventions. This section provides these
4236 Contrail Network Parameters
4237 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
4239 Contrail based resources may require references to a Contrail network
4240 using the network FQDN.
4245 When the parameter associated with the Contrail Network is referencing
4246 an “external” network, the parameter must adhere to the following naming
4247 convention in the Heat Orchestration Template
4249 - {network-role}\_net\_fqdn
4251 The parameter must be declared as type: string
4253 The parameter must not be enumerated in the Heat environment file.
4255 *Example: Parameter declaration*
4257 .. code-block:: yaml
4260 {network-role}_net_fqdn:
4262 description: Contrail FQDN for the {network-role} network
4264 *Example: Contrail Resource OS::ContrailV2::VirtualMachineInterface
4265 Reference to a Network FQDN.*
4267 In this example, the {network-role} has been defined as oam to represent
4268 an oam network and the {vm-type} has been defined as fw for firewall.
4269 The Contrail resource OS::ContrailV2::VirtualMachineInterface property
4270 virtual\_network\_refs references a contrail network FQDN.
4272 .. code-block:: yaml
4275 type: OS::ContrailV2::VirtualMachineInterface
4279 template: VM_NAME_virtual_machine_interface_1
4281 VM_NAME: { get_param: fw_name_0 }
4282 virtual_machine_interface_properties:
4283 virtual_machine_interface_properties_service_interface_type: { get_param: oam_protected_interface_type }
4284 virtual_network_refs:
4285 - get_param: oam_net_fqdn
4286 security_group_refs:
4287 - get_param: fw_sec_grp_id
4289 Interface Route Table Prefixes for Contrail InterfaceRoute Table
4290 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4292 The parameter associated with the resource
4293 OS::ContrailV2::InterfaceRouteTable property
4294 interface\_route\_table\_routes, map property
4295 interface\_route\_table\_routes\_route\_prefix is an ONAP Orchestration
4298 The parameters must be named {vm-type}\_{network-role}\_route\_prefixes
4299 in the Heat Orchestration Template.
4301 The parameter must be declared as type: json
4303 The parameter supports IP addresses in the format:
4305 1. Host IP Address (e.g., 10.10.10.10)
4307 2. CIDR Notation format (e.g., 10.0.0.0/28)
4309 The parameter must not be enumerated in the Heat environment file.
4311 *Example Parameter Definition*
4313 .. code-block:: yaml
4316 {vm-type}_{network-role}_route_prefixes:
4318 description: JSON list of Contrail Interface Route Table route prefixes
4322 .. code-block:: yaml
4327 description: Unique name for this VF instance
4328 fw_int_fw_route_prefixes:
4330 description: prefix for the ServiceInstance InterfaceRouteTable
4331 int_fw_dns_trusted_interface_type:
4333 description: service_interface_type for ServiceInstance
4336 type: OS::ContrailV2::InterfaceRouteTable
4337 depends_on: [*resource name of* *OS::ContrailV2::ServiceInstance*]
4341 template: VNF_NAME_interface_route_table
4343 VNF_NAME: { get_param: vnf_name }
4344 interface_route_table_routes:
4345 interface_route_table_routes_route: { get_param: fw_int_fw_route_prefixes }
4346 service_instance_refs:
4347 - get_resource: < *resource name of* *OS::ContrailV2::ServiceInstance* >
4348 service_instance_refs_data:
4349 - service_instance_refs_data_interface_type: { get_param: int_fw_interface_type }
4351 Parameter Names in Contrail Resources
4352 -------------------------------------
4354 Contrail Heat resource properties will use, when appropriate, the same
4355 naming convention as OpenStack Heat resources. For example, the resource
4356 OS::ContrailV2::InstanceIp has two properties that the parameter naming
4357 convention is identical to properties in OS::Neutron::Port.
4359 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4360 instance\_ip\_address*
4362 The property instance\_ip\_address uses the same parameter naming
4363 convention as the property fixed\_ips and Map Property ip\_address in
4364 OS::Neutron::Port. The resource is assigning an ONAP SDN-C Assigned IP
4365 Address. The {network-role} has been defined as oam\_protected to
4366 represent an oam protected network and the {vm-type} has been defined as
4369 .. code-block:: yaml
4371 CMD_FW_OAM_PROTECTED_RII:
4372 type: OS::ContrailV2::InstanceIp
4374 - FW_OAM_PROTECTED_RVMI
4376 virtual_machine_interface_refs:
4377 - get_resource: FW_OAM_PROTECTED_RVMI
4378 virtual_network_refs:
4379 - get_param: oam_protected_net_fqdn
4380 instance_ip_address: { get_param: [fw_oam_protected_ips, get_param: index ] }
4382 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4385 The property instance\_ip\_address uses the same parameter naming
4386 convention as the property fixed\_ips and Map Property subnet\_id in
4387 OS::Neutron::Port. The resource is assigning a Cloud Assigned IP
4388 Address. The {network-role} has been defined as “oam\_protected” to
4389 represent an oam protected network and the {vm-type} has been defined as
4392 .. code-block:: yaml
4394 CMD_FW_SGI_PROTECTED_RII:
4395 type: OS::ContrailV2::InstanceIp
4397 - FW_OAM_PROTECTED_RVMI
4399 virtual_machine_interface_refs:
4400 - get_resource: FW_OAM_PROTECTED_RVMI
4401 virtual_network_refs:
4402 - get_param: oam_protected_net_fqdn
4403 subnet_uuid: { get_param: oam_protected_subnet_id }
4405 Cinder Volume Templates
4406 -----------------------
4408 ONAP supports the independent deployment of a Cinder volume via separate
4409 Heat Orchestration Templates, the Cinder Volume module. This allows the
4410 volume to persist after VNF deletion so that they can be reused on
4411 another instance (e.g., during a failover activity).
4413 A Base Module or Incremental Module may have a corresponding volume
4414 module. Use of separate volume modules is optional. A Cinder volume may
4415 be embedded within the Base Module or Incremental Module if persistence
4418 If a VNF Base Module or Incremental Module has an independent volume
4419 module, the scope of volume templates must be 1:1 with Base module or
4420 Incremental module. A single volume module must create only the volumes
4421 required by a single Incremental module or Base module.
4423 The following rules apply to independent volume Heat templates:
4425 - Cinder volumes must be created in a separate Heat Orchestration
4426 Template from the Base Module or Incremental Module.
4428 - A single Cinder volume module must include all Cinder volumes
4429 needed by the Base/Incremental module.
4431 - The volume template must define “outputs” for each Cinder volume
4432 resource universally unique identifier (UUID) (i.e. ONAP Volume
4433 Template Output Parameters).
4435 - The VNF Incremental Module or Base Module must define input
4436 parameters that match each Volume output parameter (i.e., ONAP Volume
4437 Template Output Parameters).
4439 - ONAP will supply the volume template outputs automatically to the
4440 bases/incremental template input parameters.
4442 - Volume modules may utilize nested Heat templates.
4444 *Examples: Volume Template*
4446 A VNF has a Cinder volume module, named incremental\_volume.yaml, that
4447 creates an independent Cinder volume for a VM in the module
4448 incremental.yaml. The incremental\_volume.yaml defines a parameter in
4449 the output section, lb\_volume\_id\_0 which is the UUID of the cinder
4450 volume. lb\_volume\_id\_0 is defined as a parameter in incremental.yaml.
4451 ONAP captures the UUID value of lb\_volume\_id\_0 from the volume module
4452 output statement and provides the value to the incremental module.
4454 Note that the example below is not a complete Heat Orchestration
4455 Template. The {vm-type} has been defined as “lb” for load balancer
4457 incremental\_volume.yaml
4459 .. code-block:: yaml
4470 type: OS::Cinder::Volume
4474 template: VNF_NAME_volume_0
4476 VNF_NAME: { get_param: vnf_name }
4477 size: {get_param: dns_volume_size_0}
4482 value: {get_resource: dns_volume_0}
4488 .. code-block:: yaml
4499 type: OS::Nova::Server
4501 name: {get_param: dns_name_0}
4506 type: OS::Cinder::VolumeAttachment
4508 instance_uuid: { get_resource: lb_0 }
4509 volume_id: { get_param: lb_volume_id_0 }
4511 ONAP Support of Environment Files
4512 ---------------------------------
4514 The use of an environment file in OpenStack is optional. In ONAP, it is
4515 mandatory. A Heat Orchestration Template uploaded to ONAP must have a
4516 corresponding environment file, even if no parameters are required to be
4519 (Note that ONAP, the open source version of ONAP, does not
4520 programmatically enforce the use of an environment file.)
4522 A Base Module Heat Orchestration Template must have a corresponding
4525 An Incremental Module Heat Orchestration Template must have a
4526 corresponding environment file.
4528 A Cinder Volume Module Heat Orchestration Template must have a
4529 corresponding environment file.
4531 A nested heat template must not have an environment file; OpenStack does
4534 The environment file must contain parameter values for the ONAP
4535 Orchestration Constants and VNF Orchestration Constants. These
4536 parameters are identical across all instances of a VNF type, and
4537 expected to change infrequently. The ONAP Orchestration Constants are
4538 associated with OS::Nova::Server image and flavor properties (See
4539 `Property: image`_ and `Property: flavor`_). Examples of VNF Orchestration Constants are the networking
4540 parameters associated with an internal network (e.g., private IP ranges)
4541 and Cinder volume sizes.
4543 The environment file must not contain parameter values for parameters
4544 that are instance specific (ONAP Orchestration Parameters, VNF
4545 Orchestration Parameters). These parameters are supplied to the Heat by
4546 ONAP at orchestration time.
4548 SDC Treatment of Environment Files
4549 ----------------------------------
4551 Parameter values enumerated in the environment file are used by SDC as
4552 the default value. However, the SDC user may use the SDC GUI to
4553 overwrite the default values in the environment file.
4555 SDC generates a new environment file for distribution to MSO based on
4556 the uploaded environment file and the user provided GUI updates. The
4557 user uploaded environment file is discarded when the new file is
4558 created. Note that if the user did not change any values via GUI
4559 updates, the SDC generated environment file will contain the same values
4560 as the uploaded file.
4562 Use of Environment Files when using OpenStack “heat stack-create” CLI
4563 ---------------------------------------------------------------------
4565 When ONAP is instantiating the Heat Orchestration Template, certain
4566 parameter must not be enumerated in the environment file. This document
4567 provides the details of what parameters should not be enumerated.
4569 If the Heat Orchestration Template is to be instantiated from the
4570 OpenStack Command Line Interface (CLI) using the command “heat
4571 stack-create”, all parameters must be enumerated in the environment
4574 Heat Template Constructs
4575 ------------------------
4577 Nested Heat Templates
4578 ---------------------
4580 ONAP supports nested Heat templates per the OpenStack specifications.
4581 Nested templates may be suitable for larger VNFs that contain many
4582 repeated instances of the same VM type(s). A common usage pattern is to
4583 create a nested template for each {vm-type} along with its supporting
4584 resources. The VNF module may then reference these component templates
4585 either statically by repeated definition or dynamically by using the
4586 resource OS::Heat::ResourceGroup.
4588 Nested Heat Template Requirements
4589 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4591 ONAP supports nested Heat Orchestration Templates. A Base Module,
4592 Incremental Module, and Cinder Volume Module may use nested heat.
4594 A Heat Orchestration Template may reference the nested heat statically
4595 by repeated definition.
4597 A Heat Orchestration Template may reference the nested heat dynamically
4598 using the resource OS::Heat::ResourceGroup.
4600 A Heat Orchestration template must have no more than three levels of
4601 nesting. ONAP supports a maximum of three levels.
4603 Nested heat templates must be referenced by file name. The use of
4604 resource\_registry in the environment file is not supported and must not
4607 A nested heat yaml file must have a unique file names within the scope
4610 ONAP does not support a directory hierarchy for nested templates. All
4611 templates must be in a single, flat directory (per VNF)
4613 A nested heat template may be used by any module within a given VNF.
4617 - Constrains must not be defined for any parameter enumerated in a
4618 nested heat template.
4620 - All parameters defined in nested heat must be passed in as properties
4621 of the resource calling the nested yaml file.
4623 - When OS::Nova::Server metadata parameters are past into a nested heat
4624 template, the parameter names must not change
4626 - With nested templates, outputs are required to expose any resource
4627 properties of the child templates to the parent template. Those would
4628 not explicitly be declared as parameters but simply referenced as
4629 get\_attribute targets against the “parent” resource.
4631 Nested Heat Template Example: Static
4632 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4636 .. code-block:: yaml
4642 dns_image_name: { get_param: dns_image_name }
4643 dns_flavor_name: { get_param: dns_flavor_name }
4644 availability_zone: { get_param: availability_zone_0 }
4645 security_group: { get_param: DNS_shared_sec_grp_id }
4646 oam_net_id: { get_param: oam_protected_net_id }
4647 dns_oam_ip: { get_param: dns_oam_ip_0 }
4648 dns_name: { get_param: dns_name_0 }
4649 vnf_name: { get_param: vnf_name }
4650 vnf_id: { get_param: vnf_id }
4651 vf_module_id: {get_param: vf_module_id}
4656 dns_image_name: { get_param: dns_image_name }
4657 dns_flavor_name: { get_param: dns_flavor_name }
4658 availability_zone: { get_param: availability_zone_1 }
4659 security_group: { get_param: DNS_shared_sec_grp_id }
4660 oam_net_id: { get_param: oam_protected_net_id }
4661 dns_oam_ip: { get_param: dns_oam_ip_1 }
4662 dns_name: { get_param: dns_name_1 }
4663 vnf_name: { get_param: vnf_name }
4664 vnf_id: { get_param: vnf_id }
4665 vf_module_id: {get_param: vf_module_id}
4669 .. code-block:: yaml
4672 type: OS::Neutron::Port
4676 template: VNF_NAME_dns_oam_port
4678 VNF_NAME: {get_param: vnf_name}
4679 network: { get_param: oam_net_id }
4680 fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}]
4681 security_groups: [{ get_param: security_group }]
4684 type: OS::Nova::Server
4686 name: { get_param: dns_names }
4687 image: { get_param: dns_image_name }
4688 flavor: { get_param: dns_flavor_name }
4689 availability_zone: { get_param: availability_zone }
4691 - port: { get_resource: dns_oam_0_port }
4693 vnf_id: { get_param: vnf_id }
4694 vf_module_id: { get_param: vf_module_id }
4695 vnf_name {get_param: vnf_name }
4697 Use of Heat ResourceGroup
4698 ~~~~~~~~~~~~~~~~~~~~~~~~~
4700 The OS::Heat::ResourceGroup is a useful Heat element for creating
4701 multiple instances of a given resource or collection of resources.
4702 Typically it is used with a nested Heat template, to create, for
4703 example, a set of identical OS::Nova::Server resources plus their
4704 related OS::Neutron::Port resources via a single resource in a master
4707 ResourceGroup may be used in ONAP to simplify the structure of a Heat
4708 template that creates multiple instances of the same VM type.
4710 However, there are important caveats to be aware of:
4712 ResourceGroup does not deal with structured parameters
4713 (comma-delimited-list and json) as one might typically expect. In
4714 particular, when using a list-based parameter, where each list element
4715 corresponds to one instance of the ResourceGroup, it is not possible to
4716 use the intrinsic “loop variable” %index% in the ResourceGroup
4719 For instance, the following is **not** valid Heat for ResourceGroup:
4721 .. code-block:: yaml
4723 type: OS::Heat::ResourceGroup
4725 type: my_nested_vm_template.yaml
4727 name: {get_param: [vm_name_list, %index%]}
4729 Although this appears to use the nth entry of the vm\_name\_list list
4730 for the nth element of the ResourceGroup, it will in fact result in a
4731 Heat exception. When parameters are provided as a list (one for each
4732 element of a ResourceGroup), you must pass the complete parameter to the
4733 nested template along with the current index as separate parameters.
4735 Below is an example of an **acceptable** Heat Syntax for a
4738 .. code-block:: yaml
4740 type: OS::Heat::ResourceGroup
4742 type: my_nested_vm_template.yaml
4744 names: {get_param: vm_name_list}
4747 You can then reference within the nested template as:
4749 { get\_param: [names, {get\_param: index} ] }
4751 ResourceGroup Property count
4752 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4754 ONAP requires that the OS::Heat::ResourceGroup property count be defined
4755 (even if the value is one) and that the value must be enumerated in the
4756 environment file. This is required for ONAP to build the TOSCA model for
4759 .. code-block:: yaml
4761 type: OS::Heat::ResourceGroup
4763 count: { get_param: count }
4766 type: my_nested_vm_template.yaml
4768 names: {get_param: vm_name_list}
4771 Availability Zone and ResourceGroups
4772 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4774 The resource OS::Heat::ResourceGroup and the property availability\_zone
4775 has been an “issue” with a few VNFs since ONAP only supports
4776 availability\_zone as a string parameter and not a
4777 comma\_delimited\_list. This makes it difficult to use a ResourceGroup
4778 to create Virtual Machines in more than one availability zone.
4780 There are numerous solutions to this issue. Below are two suggested
4783 **Option 1:** create a CDL in the OS::Heat::ResourceGroup. In the
4784 resource type: OS::Heat::ResourceGroup, create a comma\_delimited\_list
4785 availability\_zones by using the intrinsic function list\_join.
4787 .. code-block:: yaml
4790 type: OS::Heat::ResourceGroup
4792 count: { get_param: node_count }
4798 avaialability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] }
4802 .. code-block:: yaml
4805 avaialability_zones:
4806 type: comma_delimited_list
4811 type: OS::Nova::Server
4813 name: { get_param: [ dns_names, get_param: index ] }
4814 image: { get_param: dns_image_name }
4815 flavor: { get_param: dns_flavor_name }
4816 availability_zone: { get_param: [ avaialability_zones, get_param: index ] }
4819 **Option 2:** Create a resource group per availability zone. A separate
4820 OS::Heat::ResourceGroup is created for each availability zone.
4825 Heat templates *should not* reference any HTTP-based resource
4826 definitions, any HTTP-based nested configurations, or any HTTP-based
4829 - During orchestration, ONAP *should not* retrieve any such resources
4830 from external/untrusted/unknown sources.
4832 - VNF images should not contain such references in user-data or other
4833 configuration/operational scripts that are specified via Heat or
4834 encoded into the VNF image itself.
4836 *Note:* HTTP-based references are acceptable if the HTTP-based reference
4837 is accessing information with the VM private/internal network.
4839 Heat Files Support (get\_file)
4840 ------------------------------
4842 Heat Templates may contain the inclusion of text files into Heat
4843 templates via the Heat get\_file directive. This may be used, for
4844 example, to define a common “user-data” script, or to inject files into
4845 a VM on startup via the “personality” property.
4847 Support for Heat Files is subject to the following limitations:
4849 - The get\_files targets must be referenced in Heat templates by file
4850 name, and the corresponding files should be delivered to ONAP along
4851 with the Heat templates.
4853 - URL-based file retrieval must not be used; it is not supported.
4855 - The included files must have unique file names within the scope of
4858 - ONAP does not support a directory hierarchy for included files.
4860 - All files must be in a single, flat directory per VNF.
4862 - Included files may be used by all Modules within a given VNF.
4864 - get\_file directives may be used in both non-nested and nested
4870 When Nova Servers are created via Heat templates, they may be passed a
4871 “keypair” which provides an ssh key to the ‘root’ login on the newly
4872 created VM. This is often done so that an initial root key/password does
4873 not need to be hard-coded into the image.
4875 Key pairs are unusual in OpenStack, because they are the one resource
4876 that is owned by an OpenStack User as opposed to being owned by an
4877 OpenStack Tenant. As a result, they are usable only by the User that
4878 created the keypair. This causes a problem when a Heat template attempts
4879 to reference a keypair by name, because it assumes that the keypair was
4880 previously created by a specific ONAP user ID.
4882 When a keypair is assigned to a server, the SSH public-key is
4883 provisioned on the VMs at instantiation time. They keypair itself is not
4884 referenced further by the VM (i.e. if the keypair is updated with a new
4885 public key, it would only apply to subsequent VMs created with that
4888 Due to this behavior, the recommended usage of keypairs is in a more
4889 generic manner which does not require the pre-requisite creation of a
4890 keypair. The Heat should be structured in such a way as to:
4892 - Pass a public key as a parameter value instead of a keypair name
4894 - Create a new keypair within the VNF Heat templates (in the base
4895 module) for use within that VNF
4897 By following this approach, the end result is the same as pre-creating
4898 the keypair using the public key – i.e., that public key will be
4899 provisioned in the new VM. However, this recommended approach also makes
4900 sure that a known public key is supplied (instead of having OpenStack
4901 generate a public/private pair to be saved and tracked outside of ONAP).
4902 It also removes any access/ownership issues over the created keypair.
4904 The public keys may be enumerated as a VNF Orchestration Constant in the
4905 environment file (since it is public, it is not a secret key), or passed
4906 at run-time as instance-specific parameters. ONAP will never
4907 automatically assign a public/private key pair.
4909 *Example (create keypair with an existing ssh public-key for {vm-type}
4910 of lb (for load balancer)):*
4912 .. code-block:: yaml
4922 type: OS::Nova::Keypair
4926 template: VNF_NAME_key_pair
4928 VNF_NAME: { get_param: vnf_name }
4929 public_key: {get_param: lb_ssh_public_key}
4930 save_private_key: false
4935 OpenStack allows a tenant to create Security groups and define rules
4936 within the security groups.
4938 Security groups, with their rules, may either be created in the Heat
4939 Orchestration Template or they can be pre-created in OpenStack and
4940 referenced within the Heat template via parameter(s). There can be a
4941 different approach for security groups assigned to ports on internal
4942 (intra-VNF) networks or external networks (inter-VNF). Furthermore,
4943 there can be a common security group across all VMs for a specific
4944 network or it can vary by VM (i.e., {vm-type}) and network type (i.e.,
4947 Anti-Affinity and Affinity Rules
4948 --------------------------------
4950 Anti-affinity or affinity rules are supported using normal OpenStack
4951 OS::Nova::ServerGroup resources. Separate ServerGroups are typically
4952 created for each VM type to prevent them from residing on the same host,
4953 but they can be applied to multiple VM types to extend the
4954 affinity/anti-affinity across related VM types as well.
4958 In this example, the {network-role} has been defined as oam to represent
4959 an oam network and the {vm-type} have been defined as lb for load
4960 balancer and db for database.
4962 .. code-block:: yaml
4966 type: OS::Nova::ServerGroup
4971 $vnf_name: {get_param: vnf_name}
4972 template: $vnf_name-server_group1
4977 type: OS::Nova::ServerGroup
4982 $vnf_name: {get_param: vnf_name}
4983 template: $vnf_name-server_group2
4988 type: OS::Nova::Server
4992 group: {get_resource: db_server_group}
4995 type: OS::Nova::Server
4999 group: {get_resource: db_server_group}
5002 type: OS::Nova::Server
5006 group: {get_resource: lb_server_group}
5008 Resource Data Synchronization
5009 -----------------------------
5011 For cases where synchronization is required in the orchestration of Heat
5012 resources, two approaches are recommended:
5014 - Standard Heat depends\_on property for resources
5016 - Assures that one resource completes before the dependent resource
5019 - Definition of completeness to OpenStack may not be sufficient
5020 (e.g., a VM is considered complete by OpenStack when it is ready
5021 to be booted, not when the application is up and running).
5023 - Use of Heat Notifications
5025 - Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle
5028 - Pre-requisite resources issue *wc\_notify* commands in user\_data.
5030 - Dependent resource define depends\_on in the
5031 OS::Heat::WaitCondition resource.
5033 *Example: “depends\_on” case*
5035 In this example, the {network-role} has been defined as oam to represent
5036 an oam network and the {vm-type} has been defined as oam to represent an
5039 .. code-block:: yaml
5043 type: OS::Nova::Server
5045 name: {get_param: [oam_ names, 0]}
5046 image: {get_param: oam_image_name}
5047 flavor: {get_param: oam_flavor_name}
5048 availability_zone: {get_param: availability_zone_0}
5050 - port: {get_resource: oam01_port_0}
5051 - port: {get_resource: oam01_port_1}
5053 scheduler_hints: {group: {get_resource: oam_servergroup}}
5054 user_data_format: RAW
5057 type: OS::Neutron::Port
5059 network: {get_resource: oam_net_name}
5060 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}]
5061 security_groups: [{get_resource: oam_security_group}]
5064 type: OS::Neutron::Port
5066 network: {get_param: oam_net_name}
5067 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}]
5068 security_groups: [{get_resource: oam_security_group}]
5070 oam_01_vol_attachment:
5071 type: OS::Cinder::VolumeAttachment
5072 depends_on: oam_server_01
5074 volume_id: {get_param: oam_vol_1}
5075 mountpoint: /dev/vdb
5076 instance_uuid: {get_resource: oam_server_01}
5081 VNF/VM parameters may include availability zone IDs for VNFs that
5082 require high availability.
5084 The Heat must comply with the following requirements to specific
5085 availability zone IDs:
5087 - The Heat template should spread Nova and Cinder resources across the
5088 availability zones as desired
5090 Post Orchestration & VNF Configuration
5091 --------------------------------------
5093 Heat templates should contain a minimum amount of post-orchestration
5094 configuration data. For instance, *do not* embed complex user-data
5095 scripts in the template with large numbers of configuration parameters
5096 to the Heat template.
5098 - VNFs may provide configuration APIs for use after VNF creation. Such
5099 APIs will be invoked via application and/or SDN controllers.
5101 *Note:* It is important to follow this convention to the extent possible
5102 even in the short-term as of the long-term direction.
5104 c. VNFM Driver Development Steps
5105 ================================
5107 Refer to the ONAP documentation for VNF Provider instructions on integrating
5108 vendor-specific VNFM adaptors with VF-C. The VNF driver development steps are
5111 1. Use the VNF SDK tools to design the VNF with TOSCA models to output
5112 the VNF TOSCA package. Using the VNF SDK tools, the VNF package can be
5113 validated and tested.
5115 2. The VNF Provider supplies a vendor-specific VNFM driver in ONAP, which
5116 is a microservice providing a translation interface from VF-C to
5117 the vendor-specific VNFM. The interface definitions of vendor-specific VNFM adaptors are supplied by
5118 the VNF Providers themselves.
5120 d. Creating Vendor-Specific VNFM Adaptor Microservices
5121 ======================================================
5123 VNFs can be managed by vendor-specific VNFMs. To add a vendor-specific VNFM to ONAP, a
5124 vendor-specific VNFM adaptor is added to ONAP implementing the interface of the vendor-specific VNFM.
5126 A vendor-specific VNFM adaptor is a microservice with a unique name and an appointed
5127 port. When started up, the vendor-specific VNFM adaptor microservice is automatically registered to the
5128 Microservices Bus (MSB). The following RESTful example describes the scenario of
5129 registering a vendor-specific VNFM adaptor to MSB:
5131 .. code-block:: java
5133 POST /api/microservices/v1/services
5135 "serviceName": "catalog",
5137 "url": "/api/catalog/v1",
5142 "ip": "10.74.56.36",
Code Review / vnfrqts / requirements.git / blob