1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
2 .. http://creativecommons.org/licenses/by/4.0
3 .. Copyright 2017 AT&T Intellectual Property. All rights reserved.
6 **VNF Modeling Requirements**
7 =====================================
10 --------------------------
16 This reference document is the VNF TOSCA Template Requirements for
17 ONAP, which provides recommendations and standards for building VNF
18 TOSCA templates compatible with ONAP initial implementations of
19 Network Cloud. It has the following features:
21 1. VNF TOSCA template designer supports GUI and CLI.
23 2. VNF TOSCA template is aligned to the newest TOSCA protocol, “Working
24 Draft 04-Revision 06”.
26 3. VNF TOSCA template supports HPA features, such as NUMA, Hyper
27 Threading, SRIOV， etc.
32 This document is intended for persons developing VNF TOSCA templates
33 that will be orchestrated by ONAP.
38 ONAP implementations of Network Cloud supports TOSCA Templates, also
39 referred to as TOSCA in this document.
41 ONAP requires the TOSCA Templates to follow a specific format. This
42 document provides the mandatory, recommended, and optional requirements
43 associated with this format.
48 The document includes three charters to help the VNF providers to use the
49 VNF model design tools and understand the VNF package structure and VNF
52 In the ONAP, VNF Package and VNFD template can be designed by manually
53 or via model designer tools. VNF model designer tools can provide the
54 GUI and CLI tools for the VNF provider to develop the VNF Package and VNFD
57 The VNF package structure is align to the NFV TOSCA protocol, and
60 The VNFD and VNF package are all align to the NFV TOSCA protocol, which
61 supports multiple TOSCA template yaml files, and also supports
62 self-defined node or other extensions.
67 TOSCA templates supported by ONAP must follow the requirements
68 enumerated in this section.
73 TOSCA defines a Meta model for defining IT services. This Meta model
74 defines both the structure of a service as well as how to manage it. A
75 Topology Template (also referred to as the topology model of a service)
76 defines the structure of a service. Plans define the process models that
77 are used to create and terminate a service as well as to manage a
78 service during its whole lifetime.
80 A Topology Template consists of a set of Node Templates and Relationship
81 Templates that together define the topology model of a service as a (not
82 necessarily connected) directed graph. A node in this graph is
83 represented by a *Node Template*. A Node Template specifies the
84 occurrence of a Node Type as a component of a service. A *Node Type*
85 defines the properties of such a component (via *Node Type Properties*)
86 and the operations (via *Interfaces*) available to manipulate the
87 component. Node Types are defined separately for reuse purposes and a
88 Node Template references a Node Type and adds usage constraints, such as
89 how many times the component can occur.
93 Figure 1: Structural Elements of Service Template and their Relations
95 TOSCA Modeling Principles & Data Model
96 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
98 This section describing TOSCA modeling principles and data model for
99 NFV, which shall be based on [TOSCA-1.0] and [TOSCA-Simple-Profile-YAML
100 V1.0], or new type based on ETSI NFV requirements, etc.
102 VNF Descriptor Template
103 ^^^^^^^^^^^^^^^^^^^^^^^^^
105 The VNF Descriptor (VNFD) describes the topology of the VNF by means of
106 ETSI NFV IFA011 [IFA011] terms such as VDUs, Connection Points, Virtual
107 Links, External Connection Points, Scaling Aspects, Instantiation Levels
108 and Deployment Flavours.
110 The VNFD (VNF Descriptor) is read by both the NFVO and the VNFM. It
111 represents the contract & interface of a VNF and ensures the
112 interoperability across the NFV functional blocks.
114 The main parts of the VNFD are the following:
116 - VNF topology: it is modeled in a cloud agnostic way using virtualized
117 containers and their connectivity. Virtual Deployment Units (VDU)
118 describe the capabilities of the virtualized containers, such as
119 virtual CPU, RAM, disks; their connectivity is modeled with VDU
120 Connection Point Descriptors (VduCpd), Virtual Link Descriptors (Vld)
121 and VNF External Connection Point Descriptors (VnfExternalCpd);
123 - VNF deployment aspects: they are described in one or more deployment
124 flavours, including instantiation levels, supported LCM operations,
125 VNF LCM operation configuration parameters, placement constraints
126 (affinity / antiaffinity), minimum and maximum VDU instance numbers,
127 and scaling aspect for horizontal scaling.
129 The following table defines the TOSCA Type “derived from” values that
130 SHALL be used when using the TOSCA Simple Profile for NFV version 1.0
131 specification [TOSCA-Simple-Profile-NFV-v1.0] for NFV VNFD.
133 +---------------------+------------------------------------+-----------------+
134 | **ETSI NFV Element**| **TOSCA VNFD** | **Derived from**|
136 | **[IFA011]** | **[TOSCA-Simple-Profile-NFV-v1.0]**| |
137 +=====================+====================================+=================+
138 | VNF | tosca.nodes.nfv.VNF | tosca.nodes.Root|
139 +---------------------+------------------------------------+-----------------+
140 | VDU | tosca.nodes.nfv.VDU | tosca.nodes.Root|
141 +---------------------+------------------------------------+-----------------+
142 | Cpd (Connection | tosca.nodes.nfv.Cpd | tosca.nodes.Root|
143 | Point) | tosca.nodes.nfv.Cpd | tosca.nodes.Root|
144 +---------------------+------------------------------------+-----------------+
145 | VduCpd (internal | tosca.nodes.nfv.VduCpd | tosca.nodes.\ |
146 | connection point) | | nfv.Cpd |
147 +---------------------+------------------------------------+-----------------+
148 | VnfVirtualLinkDesc | tosca.nodes.nfv.VnfVirtualLinkDesc | tosca.nodes.Root|
149 | (Virtual Link) | | |
150 +---------------------+------------------------------------+-----------------+
151 | VnfExtCpd (External | tosca.nodes.nfv.VnfExtCpd | tosca.nodes.Root|
152 | Connection Point) | | |
153 +---------------------+------------------------------------+-----------------+
154 | Virtual Storage | | |
155 +---------------------+------------------------------------+-----------------+
156 | Virtual Compute | | |
157 +---------------------+------------------------------------+-----------------+
158 | Software Image | | |
159 +---------------------+------------------------------------+-----------------+
160 | Deployment Flavour | | |
161 +---------------------+------------------------------------+-----------------+
162 | Scaling Aspect | | |
163 +---------------------+------------------------------------+-----------------+
164 | Element Group | | |
165 +---------------------+------------------------------------+-----------------+
166 | Instantiation | | |
168 +---------------------+------------------------------------+-----------------+
171 +--------------------------------------------------------------------+
172 | +--------------------------------------------------------------+ |
173 | | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 | |
175 | | description: VNFD TOSCA file demo | |
179 | | - TOSCA\_definition\_nfv\_1\_0.yaml | |
181 | | - TOSCA\_definition\_nfv\_ext\_1\_0.yaml | |
183 | | | **node\_types: | |
184 | | tosca.nodes.nfv.VNF.vOpenNAT: | |
185 | | derived\_from:** tosca.nodes.nfv.VNF | |
186 | | | **requirements: | |
187 | | **- **sriov\_plane: | |
188 | | capability:** tosca.capabilities.nfv.VirtualLinkable | |
189 | | | **node:** tosca.nodes.nfv.VnfVirtualLinkDesc | |
190 | | | **relationship:** tosca.relationships.nfv.VirtualLinksTo | |
191 | +--------------------------------------------------------------+ |
192 +====================================================================+
193 +--------------------------------------------------------------------+
198 1. SR-IOV Passthrought
200 Definitions of SRIOV\_Port are necessary if VDU supports SR-IOV. Here is
203 +------------------------------------------------+
212 | tosca\_name: SRIOV\_Port |
216 | virtual\_network\_interface\_requirements: |
220 | support\_mandatory: false |
222 | description: sriov |
230 | description: sriov port |
232 | layer\_protocol: ipv4 |
236 | - virtual\_binding: |
238 | capability: virtual\_binding |
244 | type: tosca.relationships.nfv.VirtualBindsTo |
248 | node: tosca.nodes.Root |
250 | type: tosca.nodes.nfv.VduCpd |
252 | substitution\_mappings: |
262 | node\_type: tosca.nodes.nfv.VNF.vOpenNAT |
263 +------------------------------------------------+
267 Definitions of mem\_page\_size as one property shall be added to
268 Properties and set the value to large if one VDU node supports
269 huagepages. Here is an example.
271 +----------------------------------+
280 | tosca\_name: Huge\_pages\_demo |
284 | mem\_page\_size:large |
285 +==================================+
286 +----------------------------------+
290 Likewise, we shall add definitions of numa to
291 requested\_additional\_capabilities if we wand VUD nodes to support
292 NUMA. Here is an example.
294 +-------------------------------------------------+
295 | topology\_template: |
303 | virtual\_compute: |
309 | numa\_enabled: true |
311 | virtual\_mem\_size: 2 GB |
313 | requested\_additional\_capabilities: |
317 | support\_mandatory: true |
319 | requested\_additional\_capability\_name: numa |
321 | target\_performance\_parameters: |
323 | hw:numa\_nodes: "2" |
325 | hw:numa\_cpus.0: "0,1" |
327 | hw:numa\_mem.0: "1024" |
329 | hw:numa\_cpus.1: "2,3,4,5" |
331 | hw:numa\_mem.1: "1024" |
332 +-------------------------------------------------+
336 Definitions of Hyper-Theading are necessary as one of
337 requested\_additional\_capabilities of one VUD node if that node
338 supports Hyper-Theading. Here is an example.
340 +-------------------------------------------------------------+
341 | topology\_template: |
349 | virtual\_compute: |
355 | numa\_enabled: true |
357 | virtual\_mem\_size: 2 GB |
359 | requested\_additional\_capabilities: |
361 | hyper\_threading: |
363 | support\_mandatory: true |
365 | requested\_additional\_capability\_name: hyper\_threading |
367 | target\_performance\_parameters: |
369 | hw:cpu\_sockets : "2" |
371 | hw:cpu\_threads : "2" |
373 | hw:cpu\_cores : "2" |
375 | hw:cpu\_threads\_policy: "isolate" |
376 +-------------------------------------------------------------+
380 Definitions of ovs\_dpdk are necessary as one of
381 requested\_additional\_capabilities of one VUD node if that node
382 supports dpdk. Here is an example.
384 +------------------------------------------------------+
385 | topology\_template: |
393 | virtual\_compute: |
399 | numa\_enabled: true |
401 | virtual\_mem\_size: 2 GB |
403 | requested\_additional\_capabilities: |
407 | support\_mandatory: true |
409 | requested\_additional\_capability\_name: ovs\_dpdk |
411 | target\_performance\_parameters: |
413 | sw:ovs\_dpdk: "true" |
414 +------------------------------------------------------+
416 NFV TOSCA Type Definition
417 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
419 tosca.capabilites.nfv.VirtualCompute
420 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
422 +---------------------------+-----------------------------------------+
423 | **Shorthand Name** | VirtualCompute |
424 +===========================+=========================================+
425 | **Type Qualified Name** | tosca: VirtualCompute |
426 +---------------------------+-----------------------------------------+
427 | **Type URI** | tosca.capabilities.nfv.VirtualCompute |
428 +---------------------------+-----------------------------------------+
429 | **derived from** | tosca.nodes.Root |
430 +---------------------------+-----------------------------------------+
435 +---------------+---------+---------------+------------+----------------------+
436 | Name | Required| Type | Constraints| Description |
437 +===============+=========+===============+============+======================+
438 | request\ | No | tosca.\ | | Describes additional |
439 | _additional\ | | datatypes.\ | | capability for a |
440 | _capabilities | | nfv.Requested\| | particular VDU. |
441 | | | Additional\ | | |
442 | | | Capability | | |
443 +---------------+---------+---------------+------------+----------------------+
444 | virtual\ | yes | tosca.\ | | Describes virtual |
445 | _memory | | datatypes.\ | | memory of the |
446 | | | nfv.Virtual\ | | virtualized compute. |
448 +---------------+---------+---------------+------------+----------------------+
449 | virtual\ | yes | tosca.\ | | Describes virtual |
450 | _cpu | | datatypes.\ | | CPU(s) of the |
451 | | | nfv.Virtual\ | | virtualized compute. |
453 +---------------+---------+---------------+------------+----------------------+
455 +---------------+---------+---------------+------------+----------------------+
460 +-----------------------------------------------------------+
461 | tosca.capabilities.nfv.VirtualCompute: |
463 | derived\_from: tosca.capabilities.Root |
467 | requested\_additional\_capabilities: |
473 | type: tosca.datatypes.nfv.RequestedAdditionalCapability |
479 | type: tosca.datatypes.nfv.VirtualMemory |
485 | type: tosca.datatypes.nfv.VirtualCpu |
488 +-----------------------------------------------------------+
490 tosca.nodes.nfv.VDU.Compute
491 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
493 The NFV Virtualization Deployment Unit (VDU) compute node type
494 represents a VDU entity which it describes the deployment and
495 operational behavior of a VNF component (VNFC), as defined by **[ETSI
498 +-----------------------+-------------------------------+
499 | Shorthand Name | VDU.Compute |
500 +=======================+===============================+
501 | Type Qualified Name | tosca:VDU.Compute |
502 +-----------------------+-------------------------------+
503 | Type URI | tosca.nodes.nfv.VDU.Compute |
504 +-----------------------+-------------------------------+
505 | derived\_from | tosca.nodes.Compute |
506 +-----------------------+-------------------------------+
519 +------------+--------------------+------------+------------------------------+
520 | Name | Type | Constraints| Description |
521 +============+====================+============+==============================+
522 | virtual\ | tosca.\ | | Describes virtual compute |
523 | _compute | capabilities.nfv.\ | | resources capabilities. |
524 | | VirtualCompute | | |
525 +------------+--------------------+------------+------------------------------+
526 | monitoring\| tosca.\ | None | Monitoring parameter, which |
527 | _parameter | capabilities.nfv.\ | | can be tracked for a VNFC |
528 | | Metric | | based on this VDU |
530 | | | | Examples include: |
531 | | | | memory-consumption, |
532 | | | | CPU-utilisation, |
533 | | | | bandwidth-consumption, VNFC |
534 | | | | downtime, etc. |
535 +------------+--------------------+------------+------------------------------+
536 | Virtual\ | tosca.\ | | Defines ability of |
537 | _binding | capabilities.nfv.\ | | VirtualBindable |
538 | | VirtualBindable | | |
540 | | editor note: need | | |
541 | | to create a | | |
542 | | capability type | | |
543 +------------+--------------------+------------+------------------------------+
548 +-----------------------------------------------------------------------------+
549 | tosca.nodes.nfv.VDU.Compute: |
551 | derived\_from: tosca.nodes.Compute |
569 | type: list # explicit index (boot index) not necessary, contrary to IFA011 |
577 | nfvi\_constraints: |
587 | configurable\_properties: |
593 | type: tosca.datatypes.nfv.VnfcConfigurableProperties |
599 | private\_address: |
601 | status: deprecated |
605 | status: deprecated |
609 | status: deprecated |
613 | status: deprecated |
617 | virtual\_compute: |
619 | type: tosca.capabilities.nfv.VirtualCompute |
621 | virtual\_binding: |
623 | type: tosca.capabilities.nfv.VirtualBindable |
625 | #monitoring\_parameter: |
627 | # modeled as ad hoc (named) capabilities in VDU node template |
633 | # cpu\_load: tosca.capabilities.nfv.Metric |
635 | # memory\_usage: tosca.capabilities.nfv.Metric |
637 | host: #Editor note: FFS. How this capabilities should be used in NFV Profile|
639 | type: `*tosca.capabilities.Container* <#DEFN_TYPE_CAPABILITIES_CONTAINER>`__|
641 | valid\_source\_types: |
642 | [`*tosca.nodes.SoftwareComponent* <#DEFN_TYPE_NODES_SOFTWARE_COMPONENT>`__] |
644 | occurrences: [0,UNBOUNDED] |
648 | occurrences: [0,0] |
652 | occurrences: [0,0] |
655 | #Editor note: FFS. How this capabilities should be used in NFV Profile |
657 | type: `*tosca.capabilities.Scalable* <#DEFN_TYPE_CAPABILITIES_SCALABLE>`__ |
661 | occurrences: [0,UNBOUND] |
665 | - virtual\_storage: |
667 | capability: tosca.capabilities.nfv.VirtualStorage |
669 | relationship: tosca.relationships.nfv.VDU.AttachedTo |
671 | node: tosca.nodes.nfv.VDU.VirtualStorage |
673 | occurences: [ 0, UNBOUNDED ] |
675 | - local\_storage: #For NFV Profile, this requirement is deprecated. |
677 | occurrences: [0,0] |
685 | type: tosca.artifacts.nfv.SwImage |
686 +-----------------------------------------------------------------------------+
691 +--------+---------+----------------+------------+------------------------+
692 | Name | Required| Type | Constraints| Description |
693 +========+=========+================+============+========================+
694 | SwImage| Yes | tosca.\ | | Describes the software |
695 | | | artifacts.nfv.\| | image which is directly|
696 | | | SwImage | | realizing this virtual |
698 +--------+---------+----------------+------------+------------------------+
706 ~~~~~~~~~~~~~~~~~~~~~
708 The TOSCA Cpd node represents network connectivity to a compute resource
709 or a VL as defined by [ETSI GS NFV-IFA 011]. This is an abstract type
710 used as parent for the various Cpd types.
712 +-----------------------+-----------------------+
713 | Shorthand Name | Cpd |
714 +=======================+=======================+
715 | Type Qualified Name | tosca:Cpd |
716 +-----------------------+-----------------------+
717 | Type URI | tosca.nodes.nfv.Cpd |
718 +-----------------------+-----------------------+
724 +--------+------------+--------+---------------+---------------+
725 | Name | Required | Type | Constraints | Description |
726 +========+============+========+===============+===============+
727 +--------+------------+--------+---------------+---------------+
742 +----------------------------------------------------------------------+
743 | tosca.nodes.nfv.Cpd: |
745 | derived\_from: tosca.nodes.Root |
755 | - valid\_values: [ethernet, mpls, odu2, ipv4, ipv6, pseudo\_wire ] |
759 | role: #Name in ETSI NFV IFA011 v0.7.3 cpRole |
765 | - valid\_values: [ root, leaf ] |
781 | type: tosca.datatype.nfv.AddressData |
784 +----------------------------------------------------------------------+
786 Additional Requirement
787 +++++++++++++++++++++++
791 tosca.nodes.nfv.VduCpd
792 ~~~~~~~~~~~~~~~~~~~~~~~
794 The TOSCA node VduCpd represents a type of TOSCA Cpd node and describes
795 network connectivity between a VNFC instance (based on this VDU) and an
796 internal VL as defined by [ETSI GS NFV-IFA 011].
798 +-----------------------+--------------------------+
799 | Shorthand Name | VduCpd |
800 +=======================+==========================+
801 | Type Qualified Name | tosca: VduCpd |
802 +-----------------------+--------------------------+
803 | Type URI | tosca.nodes.nfv.VduCpd |
804 +-----------------------+--------------------------+
810 +-----------------+---------+---------------+------------+--------------------+
811 | Name | Required| Type | Constraints| Description |
812 +=================+=========+===============+============+====================+
813 | bitrate\ | no | integer | | Bitrate requirement|
814 | _requirement | | | | on this connection |
816 +-----------------+---------+---------------+------------+--------------------+
817 | virtual\ | | Virtual\ | | Specifies |
818 | _network\ | no | Network\ | | requirements on a |
819 | _interface_\ | | Interface\ | | virtual network |
820 | requirements | | Requirements\ | | realising the CPs |
821 | | | | | instantiated from |
823 +-----------------+---------+---------------+------------+--------------------+
833 +----------+---------+--------------------+------------+----------------------+
834 | Name | Required| Type | Constraints| Description |
835 +==========+=========+====================+============+======================+
836 | virtual\ | yes | tosca.\ | | Describe the |
837 | _binding | | capabilities.nfv.\ | | requirement for |
838 | | | VirtualBindable\ | | binding with VDU |
839 +----------+---------+--------------------+------------+----------------------+
840 | virtual\ | no | tosca.\ | | Describes the |
841 | _link | | capabilities.nfv.\ | | requirements for |
842 | | | VirtualLinkable | | linking to virtual |
844 +----------+---------+--------------------+------------+----------------------+
849 +----------------------------------------------------------------+
850 | tosca.nodes.nfv.VduCpd: |
852 | derived\_from: tosca.nodes.nfv.Cpd |
856 | bitrate\_requirement: |
862 | virtual\_network\_interface\_requirements |
868 | type: VirtualNetworkInterfaceRequirements |
876 | capability: tosca.capabilities.nfv.VirtualLinkable |
878 | relationship: tosca.relationships.nfv.VirtualLinksTo |
880 | node: tosca.nodes.nfv.VnfVirtualLinkDesc - virtual\_binding: |
882 | capability: tosca.capabilities.nfv.VirtualBindable |
884 | relationship: tosca.relationships.nfv.VirtualBindsTo |
886 | node: tosca.nodes.nfv.VDU |
887 +----------------------------------------------------------------+
889 tosca.nodes.nfv.VDU.VirtualStorage
890 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
892 The NFV VirtualStorage node type represents a virtual storage entity
893 which it describes the deployment and operational behavior of a virtual
894 storage resources, as defined by **[ETSI NFV IFA011].**
896 **[editor note]** open issue: should NFV profile use the current storage
897 model as described in YAML 1.1. Pending on Shitao proposal (see
898 NFVIFA(17)000110 discussion paper)
900 **[editor note]** new relationship type as suggested in Matt
901 presentation. Slide 8. With specific rules of “valid\_target\_type”
903 +---------------------------+--------------------------------------+
904 | **Shorthand Name** | VirtualStorage |
905 +===========================+======================================+
906 | **Type Qualified Name** | tosca: VirtualStorage |
907 +---------------------------+--------------------------------------+
908 | **Type URI** | tosca.nodes.nfv.VDU.VirtualStorage |
909 +---------------------------+--------------------------------------+
910 | **derived\_from** | tosca.nodes.Root |
911 +---------------------------+--------------------------------------+
913 tosca.artifacts.nfv.SwImage
914 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
916 +---------------------------+------------------------------------+
917 | **Shorthand Name** | SwImage |
918 +===========================+====================================+
919 | **Type Qualified Name** | tosca:SwImage |
920 +---------------------------+------------------------------------+
921 | **Type URI** | tosca.artifacts.nfv.SwImage |
922 +---------------------------+------------------------------------+
923 | **derived\_from** | tosca.artifacts.Deployment.Image |
924 +---------------------------+------------------------------------+
929 +-----------------+---------+----------+------------+-------------------------+
930 | Name | Required| Type | Constraints| Description |
931 +=================+=========+==========+============+=========================+
932 | name | yes | string | | Name of this software |
934 +-----------------+---------+----------+------------+-------------------------+
935 | version | yes | string | | Version of this software|
937 +-----------------+---------+----------+------------+-------------------------+
938 | checksum | yes | string | | Checksum of the software|
939 | | | | | image file |
940 +-----------------+---------+----------+------------+-------------------------+
941 | container\ | yes | string | | The container format |
942 | _format | | | | describes the container |
943 | | | | | file format in which |
944 | | | | | software image is |
945 | | | | | provided. |
946 +-----------------+---------+----------+------------+-------------------------+
947 | disk\_format | yes | string | | The disk format of a |
948 | | | | | software image is the |
949 | | | | | format of the underlying|
950 | | | | | disk image |
951 +-----------------+---------+----------+------------+-------------------------+
952 | min\_disk | yes | scalar-\ | | The minimal disk size |
953 | | | unit.size| | requirement for this |
954 | | | | | software image. |
955 +-----------------+---------+----------+------------+-------------------------+
956 | min\_ram | no | scalar-\ | | The minimal RAM |
957 | | | unit.size| | requirement for this |
958 | | | | | software image. |
959 +-----------------+---------+----------+------------+-------------------------+
960 | Size | yes | scalar-\ | | The size of this |
961 | | | unit.size| | software image |
962 +-----------------+---------+----------+------------+-------------------------+
963 | sw\_image | yes | string | | A reference to the |
964 | | | | | actual software image |
965 | | | | | within VNF Package, or |
967 +-----------------+---------+----------+------------+-------------------------+
968 | operating\ | no | string | | Identifies the operating|
969 | _system | | | | system used in the |
970 | | | | | software image. |
971 +-----------------+---------+----------+------------+-------------------------+
972 | supported\ | no | list | | Identifies the |
973 | _virtualization\| | | | virtualization |
974 | _enviroment | | | | environments (e.g. |
975 | | | | | hypervisor) compatible |
976 | | | | | with this software image|
977 +-----------------+---------+----------+------------+-------------------------+
982 +-----------------------------------------------------+
983 | tosca.artifacts.nfv.SwImage: |
985 | derived\_from: tosca.artifacts.Deployment.Image |
987 | properties or metadata: |
1011 | container\_format: |
1025 | type: scalar-unit.size # Number |
1031 | type: scalar-unit.size # Number |
1037 | type: scalar-unit.size # Number |
1047 | operating\_system: |
1053 | supported\_virtualisation\_environments: |
1062 +-----------------------------------------------------+
1067 openovnf\_\_vOpenNAT.yaml
1068 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
1070 +-------------------------------------------------------------+
1073 | - openonfv\_\_tosca.capabilities.Scalable.yaml |
1075 | - openonfv\_\_tosca.capabilities.nfv.Metric.yaml |
1077 | - openonfv\_\_tosca.capabilities.network.Bindable.yaml |
1079 | - openonfv\_\_tosca.capabilities.Attachment.yaml |
1081 | - openonfv\_\_tosca.capabilities.nfv.VirtualBindable.yaml |
1083 | - openonfv\_\_tosca.requirements.nfv.VirtualStorage.yaml |
1085 | - openonfv\_\_tosca.nodes.nfv.VDU.VirtualStorage.yaml |
1087 | - openonfv\_\_tosca.relationships.nfv.VirtualBindsTo.yaml |
1089 | - openonfv\_\_tosca.nodes.nfv.VDU.Compute.yaml |
1091 | - openonfv\_\_tosca.artifacts.nfv.SwImage.yaml |
1093 | - openonfv\_\_tosca.capabilities.nfv.VirtualCompute.yaml |
1095 | - openonfv\_\_tosca.capabilities.Container.yaml |
1097 | - openonfv\_\_tosca.capabilities.nfv.VirtualStorage.yaml |
1099 | - openonfv\_\_tosca.requirements.nfv.VirtualBinding.yaml |
1101 | - openovnf\_\_tosca.nodes.nfv.VNF.vOpenNAT.yaml |
1103 | - openonfv\_\_tosca.capabilities.Endpoint.Admin.yaml |
1105 | - openonfv\_\_tosca.capabilities.OperatingSystem.yaml |
1107 | - openonfv\_\_tosca.nodes.nfv.VduCpd.yaml |
1109 | - openonfv\_\_tosca.relationships.nfv.VDU.AttachedTo.yaml |
1113 | vnfProductName: openNAT |
1115 | vnfdVersion: 1.0.0 |
1117 | vnfProvider: intel |
1121 | csarVersion: 1.0.0 |
1123 | vnfdId: openNAT-1.0 |
1125 | csarProvider: intel |
1127 | vnfProductInfoDescription: openNAT |
1135 | localizationLanguage: '[english, chinese]' |
1139 | defaultLocalizationLanguage: english |
1141 | vnfProductInfoName: openNAT |
1143 | vnfSoftwareVersion: 1.0.0 |
1145 | topology\_template: |
1147 | node\_templates: |
1155 | file: /swimages/xenial-snat.qcow2 |
1157 | type: tosca.artifacts.nfv.SwImage |
1161 | name: vNatVNFImage |
1165 | checksum: "5000" |
1167 | container\_format: bare |
1169 | disk\_format: qcow2 |
1171 | min\_disk: 10 GB |
1177 | sw\_image: /swimages/xenial-snat.qcow2 |
1179 | operating\_system: unbantu |
1183 | tosca\_name: vdu\_vNat |
1187 | virtual\_compute: |
1191 | virtual\_memory: |
1193 | numa\_enabled: true |
1195 | virtual\_mem\_size: 2 GB |
1197 | requested\_additional\_capabilities: |
1201 | support\_mandatory: true |
1203 | requested\_additional\_capability\_name: numa |
1205 | target\_performance\_parameters: |
1207 | hw:numa\_nodes: "2" |
1209 | hw:numa\_cpus.0: "0,1" |
1211 | hw:numa\_mem.0: "1024" |
1213 | hw:numa\_cpus.1: "2,3,4,5" |
1215 | hw:numa\_mem.1: "1024" |
1217 | hyper\_threading: |
1219 | support\_mandatory: true |
1221 | requested\_additional\_capability\_name: hyper\_threading |
1223 | target\_performance\_parameters: |
1225 | hw:cpu\_sockets : "2" |
1227 | hw:cpu\_threads : "2" |
1229 | hw:cpu\_cores : "2" |
1231 | hw:cpu\_threads\_policy: "isolate" |
1235 | support\_mandatory: true |
1237 | requested\_additional\_capability\_name: ovs\_dpdk |
1239 | target\_performance\_parameters: |
1241 | sw:ovs\_dpdk: "true" |
1245 | cpu\_architecture: X86 |
1247 | num\_virtual\_cpu: 2 |
1251 | configurable\_properties: |
1255 | additional\_vnfc\_configurable\_properties: |
1261 | descrption: the virtual machine of vNat |
1269 | - virtual\_storage: |
1271 | capability: virtual\_storage |
1273 | node: vNAT\_Storage |
1279 | location: /mnt/volume\_0 |
1281 | type: tosca.relationships.nfv.VDU.AttachedTo |
1283 | - local\_storage: |
1285 | node: tosca.nodes.Root |
1287 | type: tosca.nodes.nfv.VDU.Compute |
1293 | tosca\_name: SRIOV\_Port |
1297 | virtual\_network\_interface\_requirements: |
1301 | support\_mandatory: false |
1303 | description: sriov |
1311 | description: sriov port |
1313 | layer\_protocol: ipv4 |
1317 | - virtual\_binding: |
1319 | capability: virtual\_binding |
1325 | type: tosca.relationships.nfv.VirtualBindsTo |
1327 | - virtual\_link: |
1329 | node: tosca.nodes.Root |
1331 | type: tosca.nodes.nfv.VduCpd |
1337 | tosca\_name: vNAT\_Storage |
1341 | id: vNAT\_Storage |
1343 | size\_of\_storage: 10 GB |
1345 | rdma\_enabled: false |
1347 | type\_of\_storage: volume |
1349 | type: tosca.nodes.nfv.VDU.VirtualStorage |
1351 | substitution\_mappings: |
1361 | node\_type: tosca.nodes.nfv.VNF.vOpenNAT |
1363 | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 |
1364 +-------------------------------------------------------------+
1366 openonfv\_\_tosca.nodes.nfv.VDU.VirtualStorage.yaml
1367 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1369 +------------------------------------------------------------+
1372 | - openonfv\_\_tosca.capabilities.nfv.VirtualStorage.yaml |
1376 | tosca.nodes.nfv.VDU.VirtualStorage: |
1380 | virtual\_storage: |
1382 | type: tosca.capabilities.nfv.VirtualStorage |
1384 | derived\_from: tosca.nodes.Root |
1392 | size\_of\_storage: |
1402 | type\_of\_storage: |
1406 | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 |
1407 +------------------------------------------------------------+
1409 openonfv\_\_tosca.nodes.nfv.VduCpd.yaml
1410 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1412 +-----------------------------------------------------------------+
1415 | tosca.datatypes.nfv.L3AddressData: |
1419 | number\_of\_ip\_address: |
1425 | ip\_address\_assignment: |
1429 | ip\_address\_type: |
1433 | - valid\_values: |
1443 | floating\_ip\_activated: |
1447 | tosca.datatypes.nfv.VirtualNetworkInterfaceRequirements: |
1457 | support\_mandatory: |
1475 | tosca.datatype.nfv.AddressData: |
1483 | - valid\_values: |
1491 | l2\_address\_data: |
1495 | type: tosca.datatypes.nfv.L2AddressData |
1497 | l3\_address\_data: |
1501 | type: tosca.datatypes.nfv.L3AddressData |
1503 | tosca.datatypes.nfv.L2AddressData: {} |
1507 | - openonfv\_\_tosca.requirements.nfv.VirtualBinding.yaml |
1509 | - openonfv\_\_tosca.requirements.nfv.VirtualBinding.yaml |
1513 | tosca.nodes.nfv.VduCpd: |
1515 | derived\_from: tosca.nodes.Root |
1519 | virtual\_network\_interface\_requirements: |
1523 | type: tosca.datatypes.nfv.VirtualNetworkInterfaceRequirements |
1533 | - valid\_values: |
1543 | bitrate\_requirement: |
1555 | layer\_protocol: |
1559 | - valid\_values: |
1579 | type: tosca.datatype.nfv.AddressData |
1587 | - virtual\_binding: |
1589 | capability: tosca.capabilities.nfv.VirtualBindable |
1597 | - virtual\_link: |
1599 | capability: tosca.capabilities.nfv.VirtualBindable |
1607 | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 |
1608 +-----------------------------------------------------------------+
1610 .. |image1| image:: Image1.png
1613 .. |image2| image:: Image2.png
1623 This section contains general Heat Orchestration Template guidelines.
1628 R-95303 A VNF's Heat Orchestration Template **MUST** be defined using valid YAML.
1631 Markup Language) is a human friendly data serialization standard for all
1632 programming languages. See http://www.yaml.org/.
1634 Heat Orchestration Template Format
1635 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1637 As stated above, Heat Orchestration templates must be defined in YAML.
1641 - Tabs are not allowed, use spaces ONLY
1643 - You must indent your properties and lists with 1 or more spaces
1645 - All Resource IDs and resource property parameters are case-sensitive. (e.g., "ThIs", is not the same as "thiS")
1647 Heat Orchestration Template Structure
1648 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1650 Heat Orchestration template structure follows the following format,
1651 as defined by OpenStack at
1652 https://docs.openstack.org/developer/heat/template_guide/hot_spec.html
1654 .. code-block:: python
1656 heat_template_version: <date>
1659 # a description of the template
1662 # a declaration of input parameter groups and order
1665 # declaration of input parameters
1668 # declaration of template resources
1671 # declaration of output parameters
1674 # declaration of conditions
1676 heat_template_version
1677 +++++++++++++++++++++
1679 R-27078 A VNF's Heat Orchestration template **MUST** contain
1680 the section "heat_template_version:".
1682 The section "heat_template_version:" must be set to a date
1683 that is supported by the OpenStack environment.
1688 R-39402 A VNF's Heat Orchestration Template **MUST**
1689 contain the section "description:".
1694 A VNF Heat Orchestration template may
1695 contain the section "parameter_groups:".
1700 R-35414 A VNF Heat Orchestration's template **MUST**
1701 contain the section "parameters:".
1704 .. code-block:: python
1710 type: <string | number | json | comma_delimited_list | boolean>
1712 label: <human-readable name of the parameter>
1714 description: <description of the parameter>
1716 default: <default value for parameter>
1718 hidden: <true | false>
1722 <parameter constraints>
1724 immutable: <true | false>
1726 This section allows for
1727 specifying input parameters that have to be provided when instantiating
1728 the template. Each parameter is specified in a separate nested block
1729 with the name of the parameters defined in the first line and additional
1730 attributes (e.g., type, label) defined as nested elements.
1732 R-90279 A VNF Heat Orchestration's template's parameter **MUST**
1733 be used in a resource with the exception of the parameters
1734 for the OS::Nova::Server resource property availability_zone.
1736 R-91273 A VNF Heat Orchestration’s template’s parameter for
1737 the OS::Nova::Server resource property availability_zone
1738 **MAY NOT** be used in any OS::Nova::Resource.
1743 The name of the parameter.
1745 R-25877 A VNF's Heat Orchestration Template's parameter
1746 name (i.e., <param name>) **MUST** contain only
1747 alphanumeric characters and underscores ('_').
1752 R-36772 A VNF’s Heat Orchestration Template’s parameter
1753 **MUST** include the attribute “type:”.
1755 R-11441 A VNF’s Heat Orchestration Template’s parameter
1756 type **MUST** be one of the following values: "string",
1757 "number", "json", "comma_delimited_list" or "boolean".
1762 R-32094 A VNF's Heat Orchestration Template parameter
1763 declaration **MAY** contain the attribute "label:"
1768 R-44001 A VNF's Heat Orchestration Template parameter
1769 declaration **MUST** contain the attribute "description".
1771 Note that the parameter attribute “description:” is an
1772 OpenStack optional attribute that provides a description
1773 of the parameter. ONAP implementation requires this attribute.
1778 R-90526 A VNF Heat Orchestration Template parameter
1779 declaration **MUST** not contain the default attribute.
1781 R-26124 If a VNF Heat Orchestration Template parameter
1782 requires a default value, it **MUST** be enumerated in the environment file.
1784 Note that the parameter attribute “default:” is an OpenStack
1785 optional attribute that declares the default value of the
1786 parameter. ONAP implementation prohibits the use of this attribute.
1791 R-32557 A VNF's Heat Orchestration Template parameter
1792 declaration MAY contain the attribute "hidden:".
1794 The parameter attribute "hidden:" is an OpenStack optional
1795 attribute that defines whether the parameters should be
1796 hidden when a user requests information about a stack
1797 created from the template. This attribute can be used
1798 to hide passwords specified as parameters.
1803 The parameter attribute "constraints:" is an OpenStack optional
1804 attribute that defines a list of constraints to apply to the parameter.
1806 R-88863 A VNF's Heat Orchestration Template's parameter defined as
1807 type "number" **MUST** have a parameter constraint of "range" or
1808 "allowed_values" defined.
1810 R-40518 A VNF's Heat Orchestration Template’s parameter defined as
1811 type "string" **MAY** have a parameter constraint defined.
1813 R-96227 A VNF's Heat Orchestration Template’s parameter defined as
1814 type "json" **MAY** have a parameter constraint defined.
1816 R-79817 A VNF's Heat Orchestration Template’s parameter defined as
1817 type "comma_delimited_list" **MAY** have a parameter constraint defined.
1819 R-06613 A VNF's Heat Orchestration Template’s parameter defined as
1820 type "boolean" **MAY** have a parameter constraint defined.
1822 R-00011 A VNF's Heat Orchestration Template's Nested YAML files
1823 parameter's **MUST NOT** have a parameter constraint defined.
1825 The constraints block of a parameter definition defines additional
1826 validation constraints that apply to the value of the parameter.
1827 The parameter values provided in the VNF Heat Orchestration Template
1828 are validated against the constraints at instantiation time.
1829 The stack creation fails if the parameter value doesn’t comply to the constraints.
1831 The constraints are defined as a list with the following syntax
1833 .. code-block:: python
1837 <constraint type>: <constraint definition>
1839 description: <constraint description>
1843 **<constraint type>** Provides the type of constraint to apply.
1844 The list of OpenStack supported constraints can be found at
1845 https://docs.openstack.org/heat/latest/template_guide/hot_spec.html .
1847 **<constraint definition>** provides the actual constraint.
1848 The syntax and constraint is dependent of the <constraint type> used.
1850 **description** is an optional attribute that provides a description of the
1851 constraint. The text is presented to the user when the value the user
1852 defines violates the constraint. If omitted, a default validation
1853 message is presented to the user.
1855 Below is a brief overview of the "range" and "allowed values" constraints.
1856 For complete details on constraints, see
1857 https://docs.openstack.org/heat/latest/template_guide/hot_spec.html#parameter-constraints
1861 range: The range constraint applies to parameters of type: number.
1862 It defines a lower and upper limit for the numeric value of the
1863 parameter. The syntax of the range constraint is
1865 .. code-block:: python
1867 range: { min: <lower limit>, max: <upper limit> }
1871 It is possible to define a range constraint with only a lower
1872 limit or an upper limit.
1876 allowed_values: The allowed_values constraint applies to parameters of
1877 type \"string\" or type \"number\". It specifies a set of possible
1878 values for a parameter. At deployment time, the user-provided value
1879 for the respective parameter must match one of the elements of the
1880 list. The syntax of the allowed_values constraint is
1882 .. code-block:: python
1884 allowed_values: [ <value>, <value>, ... ]
1886 Alternatively, the following YAML list notation can be used
1901 R-22589 A VNF’s Heat Orchestration Template parameter declaration
1902 **MAY** contain the attribute "immutable:".
1904 The parameter attribute \"immutable:\" is an OpenStack optional
1905 attribute that defines whether the parameter is updatable. A Heat
1906 Orchestration Template stack update fails if immutable is set to
1907 true and the parameter value is changed. This attribute
1908 \"immutable:\" defaults to false.
1913 R-23664 A VNF's Heat Orchestration template **MUST** contain
1914 the section "resources:".
1916 R-90152 A VNF's Heat Orchestration Template's "resources:"
1917 section **MUST** contain the declaration of at least one resource.
1919 R-40551 A VNF's Heat Orchestration Template's Nested YAML files
1920 **MAY** contain the section "resources:".
1922 Each resource is defined as a
1923 separate block in the resources section with the following syntax.
1925 .. code-block:: python
1931 type: <resource type>
1935 <property name>: <property value>
1939 <resource specific metadata>
1941 depends_on: <resource ID or list of ID>
1943 update_policy: <update policy>
1945 deletion_policy: <deletion policy>
1947 external_id: <external resource ID>
1949 condition: <condition name or expression or boolean>
1956 R-75141 A VNF's Heat Orchestration Template's resource name
1957 (i.e., <resource ID>) **MUST** only contain alphanumeric
1958 characters and underscores ('_').
1960 R-16447 A VNF's <resource ID> **MUST** be unique across all
1961 Heat Orchestration Templates and all HEAT Orchestration Template
1962 Nested YAML files that are used to create the VNF.
1964 Note that a VNF can be composed of one or more Heat Orchestration Templates.
1966 Note that OpenStack requires the <resource ID> to be unique to the
1967 Heat Orchestration Template and not unique across all Heat
1968 Orchestration Templates the compose the VNF.
1973 The resource attribute \"type:\" is an OpenStack required
1974 attribute that defines the resource type, such as
1975 OS::Nova::Server or OS::Neutron::Port.
1977 The resource attribute \"type:\" may specify a VNF HEAT
1978 Orchestration Template Nested YAML file.
1980 R-53952 A VNF’s Heat Orchestration Template’s Resource
1981 **MUST NOT** reference a HTTP-based resource definitions.
1983 R-71699 A VNF’s Heat Orchestration Template’s Resource
1984 **MUST NOT** reference a HTTP-based Nested YAML file.
1989 The resource attribute \"properties:\" is an OpenStack optional
1990 attribute that provides a list of resource-specific properties.
1991 The property value can be provided in place, or via a function
1992 (e.g., `Intrinsic functions <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-intrinsic-functions>`__).
1994 R-10834 If a VNF Heat Orchestration Template resource attribute
1995 "property:" uses a nested "get_param", one level of nesting is
1996 supported and the nested "get_param" **MUST** reference an index
2001 The resource attribute \"metadata:\" is an OpenStack optional attribute.
2003 R-97199 A VNF's Heat Orchestration Template's OS::Nova::Server
2004 resource **MUST** contain the attribute "metadata".
2006 Section 5.4 contains the OS::Nova::Server mandatory and optional metadata.
2012 The resource attribute \"depends_on:\" is an OpenStack optional
2014 See `OpenStack documentation <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-resources-dependencies>`__
2015 for additional details.
2017 R-46968 VNF’s Heat Orchestration Template’s Resource **MAY**
2018 declare the attribute “depends_on:”.
2023 R-63137 VNF’s Heat Orchestration Template’s Resource **MAY**
2024 declare the attribute “update_policy:”.
2029 R-43740 A VNF’s Heat Orchestration Template’s Resource
2030 **MAY** declare the attribute “deletion_policy:”.
2032 If specified, the \"deletion_policy:\" attribute for resources
2033 allows values 'Delete', 'Retain', and 'Snapshot'.
2034 Starting with heat_template_version 2016-10-14, lowercase
2035 equivalents are also allowed.
2037 The default policy is to delete the physical resource when
2038 deleting a resource from the stack.
2043 R-78569 A VNF’s Heat Orchestration Template’s Resouce **MAY**
2044 declare the attribute “external_id:”.
2046 This attribute allows for specifying the resource_id for an
2047 existing external (to the stack) resource. External resources
2048 cannot depend on other resources, but we allow other resources to
2049 depend on external resource. This attribute is optional.
2050 Note: when this is specified, properties will not be used for
2051 building the resource and the resource is not managed by Heat.
2052 This is not possible to update that attribute. Also,
2053 resource won’t be deleted by heat when stack is deleted.
2059 The resource attribute \"condition:\" is an OpenStack optional attribute.
2061 Support for the resource condition attribute was added
2062 in the Newton release of OpenStack.
2067 R-36982 A VNF’s Heat Orchestration template **MAY** contain the “outputs:” section.
2069 This section allows for specifying output parameters
2070 available to users once the template has been instantiated. If the
2071 section is specified, it will need to adhere to specific requirements.
2072 See `ONAP Parameter Classifications Overview`_ and
2073 `ONAP Output Parameter Names`_ for additional details.
2075 Environment File Format
2076 ~~~~~~~~~~~~~~~~~~~~~~~
2078 The environment file is a yaml text file.
2079 (https://docs.openstack.org/developer/heat/template_guide/environment.html)
2081 R-86285 The VNF Heat Orchestration Template **MUST** have a corresponding
2082 environment file, even if no parameters are required to be enumerated.
2084 The use of an environment file in OpenStack is optional.
2085 In ONAP, it is mandatory.
2087 R-03324 The VNF Heat Orchestration Template **MUST** contain the
2088 "parameters" section in the
2091 R-68198 A VNF’s Heat Orchestration template’s Environment File’s
2092 “parameters:” section **MAY** enumerate parameters.
2094 ONAP implementation requires the parameters section in the
2095 environmental file to be declared. The parameters section
2096 contains a list of key/value pairs.
2098 R-59930 A VNF’s Heat Orchestration template’s Environment
2099 File’s **MAY** contain the “parameter_defaults:” section.
2101 The “parameter_defaults:” section contains default parameters
2102 that are passed to all template resources.
2104 R-46096 A VNF’s Heat Orchestration template’s Environment File’s
2105 **MAY** contain the “encrypted_parameters:” section.
2107 The “encrypted_parameters:” section contains a list of encrypted parameters.
2109 R-24893 A VNF’s Heat Orchestration template’s Environment File’s
2110 **MAY** contain the “event_sinks:” section.
2112 The “event_sinks:” section contains the list of endpoints that would
2113 receive stack events.
2115 R-42685 A VNF’s Heat Orchestration template’s Environment File’s
2116 **MAY** contain the “parameter_merge_strategies:” section.
2118 The “parameter_merge_strategies:” section provides the merge strategies
2119 for merging parameters and parameter defaults from the environment file.
2121 R-67231 A VNF’s Heat Orchestration template’s Environment File’s **MUST NOT**
2122 contain the “resource_registry:” section.
2124 ONAP implementation does not support the Environment File resource_registry
2125 section. The resource_registry section allows for the definition of custom resources.
2128 SDC Treatment of Environment Files
2129 ++++++++++++++++++++++++++++++++++
2131 Parameter values enumerated in the environment file are used by SDC as
2132 the default value. However, the SDC user may use the SDC GUI to
2133 overwrite the default values in the environment file.
2135 SDC generates a new environment file for distribution to MSO based on
2136 the uploaded environment file and the user provided GUI updates. The
2137 user uploaded environment file is discarded when the new file is
2140 ONAP has requirements for what parameters must be enumerated in the
2141 environment file and what parameter must not be enumerated in the
2142 environment file. See `ONAP Parameter Classifications Overview`_ and
2143 `ONAP Resource ID and Parameter Naming Convention`_ for more details.
2145 ONAP Heat Orchestration Templates: Overview
2146 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2148 ONAP supports a modular Heat Orchestration Template design pattern,
2149 referred to as *VNF Modularity.*
2151 ONAP VNF Modularity Overview
2152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2154 R-69663 A VNF **MAY** be composed from one or more Heat Orchestration
2155 Templates, each of which represents a subset of the overall VNF.
2157 The Heat Orchestration Templates can be thought of a components or
2158 modules of the VNF and are referred to as “\ *VNF Modules*\ ”.
2159 During orchestration, these modules are
2160 deployed incrementally to create the complete VNF.
2162 R-33132 A VNF’s Heat Orchestration Template **MAY** be 1.) Base Module
2163 Heat Orchestration Template (also referred to as a Base Module), 2.)
2164 Incremental Module Heat Orchestration Template (referred to as an Incremental
2165 Module), or 3.) a Cinder Volume Module Heat Orchestration Template
2166 (referred to as Cinder Volume Module).
2168 R-37028 The VNF **MUST** be composed of one “base” module.
2170 R-13196 A VNF **MAY** be composed of zero to many Incremental Modules
2172 R-20974 The VNF **MUST** deploy the base module first, prior to
2173 the incremental modules.
2175 R-28980 A VNF’s incremental module **MAY** be used for initial VNF
2178 R-86926 A VNF’s incremental module **MAY** be used for scale out only.
2180 A VNF’s Incremental Module that is used for scale out is deployed
2181 sometime after initial VNF deployment to add capacity.
2183 R-91497 A VNF’s incremental module **MAY** be used for both deployment
2186 R-68122 A VNF’s incremental module **MAY** be deployed more than once,
2187 either during initial VNF deployment and/or scale out.
2189 R-46119 A VNF’s Heat Orchestration Template’s Resource OS::Heat::CinderVolume
2190 **MAY** be defined in a Base Module.
2192 R-90748 A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume
2193 **MAY** be defined in an Incremental Module.
2195 R-03251 A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume
2196 **MAY** be defined in a Cinder Volume Module.
2198 ONAP also supports the concept of an optional, independently deployed Cinder
2199 volume via a separate Heat Orchestration Templates, referred to as a Cinder
2200 Volume Module. This allows the volume to persist after a Virtual Machine
2201 (VM) (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused
2202 on another instance (e.g., during a failover activity).
2204 R-11200 The VNF **MUST** keep the scope of a Cinder volume module, when it
2205 exists, to be 1:1 with the VNF Base Module or Incremental Module
2207 It is strongly recommended that Cinder Volumes be created in a Cinder Volume
2210 R-38474 The VNF **MUST** have a corresponding environment file for a
2213 R-81725 The VNF **MUST** have a corresponding environment file for an
2216 R-53433 The VNF **MUST** have a corresponding environment file for a
2217 Cinder Volume Module.
2219 These concepts will be described in more detail throughout the document.
2220 This overview is provided to set the stage and help clarify the concepts
2221 that will be introduced.
2223 Nested Heat Orchestration Templates Overview
2224 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2226 ONAP supports nested Heat Orchestration Templates per OpenStack
2229 R-36582 A VNF’s Base Module **MAY** utilize nested heat.
2231 R-56721 A VNF’s Incremental Module **MAY** utilize nested heat.
2233 R-30395 A VNF’s Cinder Volume Module **MAY** utilize nested heat.
2235 Nested templates may be suitable for larger VNFs that contain many
2236 repeated instances of the same VM type(s). A common usage pattern is to
2237 create a nested template for each VM type along with its supporting
2238 resources. The Heat Orchestration Template may then reference these
2239 nested templates either statically (by repeated definition) or
2240 dynamically (via OS::Heat::ResourceGroup).
2242 See `Nested Heat Templates`_ for additional details.
2244 ONAP Heat Orchestration Template Filenames
2245 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2247 In order to enable ONAP to understand the relationship between Heat
2248 files, the following Heat file naming convention must be utilized.
2250 In the examples below, <text> represents any alphanumeric string that
2251 must not contain any special characters and must not contain the word
2254 R-87485 A VNF’s Heat Orchestration Template’s file extension **MUST**
2255 be in the lower case format ‘.yaml’ or ‘.yml’.
2257 R-56438 A VNF’s Heat Orchestration Template’s Nested YAML file extension
2258 **MUST** be in the lower case format ‘.yaml’ or ‘.yml’.
2260 R-74304 A VNF’s Heat Orchestration Template’s Environment file extension
2261 **MUST** be in the lower case format ‘.env’.
2266 R-81339 A VNF Heat Orchestration Template’s Base Module file name **MUST**
2267 include ‘base’ in the filename and **MUST** match one of the following four
2268 formats: 1.) ‘base_<text>.y[a]ml’, 2.) ‘<text>_base.y[a]ml’, 3.)
2269 ‘base.y[a]ml’, or 4.) ‘<text>_base_<text>’.y[a]ml; where ‘base’ is case
2270 insensitive and where ‘<text>’ **MUST** contain only alphanumeric characters
2271 and underscores ‘_’ and **MUST NOT** contain the case insensitive word ‘base’.
2273 R-91342 A VNF Heat Orchestration Template’s Base Module’s Environment File
2274 **MUST** be named identical to the VNF Heat Orchestration Template’s Base
2275 Module with ‘.y[a]ml’ replaced with ‘.env’.
2280 R-87247 A VNF Heat Orchestration Template’s Incremental Module file name
2281 **MUST** contain only alphanumeric characters and underscores ‘_’ and
2282 **MUST NOT** contain the case insensitive word ‘base’.
2284 R-94509 A VNF Heat Orchestration Template’s Incremental Module’s Environment
2285 File **MUST** be named identical to the VNF Heat Orchestration Template’s
2286 Incremental Module with ‘.y[a]ml’ replaced with ‘.env’.
2288 To clearly identify the incremental module, it is recommended to use the
2289 following naming options for modules:
2291 - module_<text>.y[a]ml
2293 - <text>_module.y[a]ml
2297 - <text>_module_<text>.y[a]ml
2299 Cinder Volume Modules
2300 +++++++++++++++++++++
2302 R-82732 A VNF Heat Orchestration Template’s Cinder Volume Module **MUST** be
2303 named identical to the base or incremental module it is supporting with
2306 R-31141 A VNF Heat Orchestration Template’s Cinder Volume Module’s Environment
2307 File **MUST** be named identical to the VNF Heat Orchestration Template’s
2308 Cinder Volume Module with .y[a]ml replaced with ‘.env’.
2313 R-76057 A VNF Heat Orchestration Template’s Nested YAML file name **MUST**
2314 contain only alphanumeric characters and underscores ‘_’ and **MUST NOT**
2315 contain the case insensitive word ‘base’.
2321 - nest_<text>.y[a]ml
2323 - <text>_nest.y[a]ml
2327 - <text>_nest_<text>.y[a]ml
2329 VNF Heat Orchestration Template's Nested YAML file does not have a
2330 corresponding environment files, per OpenStack specifications.
2332 R-18224 The VNF Heat Orchestration Template **MUST** pass in as properties
2333 all parameter values
2334 associated with the nested heat file in the resource definition defined
2335 in the parent heat template.
2340 The output parameters are parameters defined in the output section of a
2341 Heat Orchestration Template. The ONAP output parameters are subdivided
2342 into three categories:
2344 1. ONAP Base Module Output Parameters
2346 2. ONAP Volume Module Output Parameters
2348 3. ONAP Predefined Output Parameters.
2350 ONAP Base Module Output Parameters
2351 ++++++++++++++++++++++++++++++++++++
2353 ONAP Base Module Output Parameters are declared in the 'outputs:'' section of
2354 the VNF's Heat Orchestration Template's Base Module. A Base Module Output
2355 Parameter is available as an input parameter (i.e., declared in the
2356 'parameters:'' section) to all Incremental Modules in the VNF.
2358 A Base Module Output Parameter may be used as an input parameter in any
2359 incremental module in the VNF. Note that the parameter is not
2360 available to other VNFs.
2362 R-52753 VNF’s Heat Orchestration Template’s Base Module’s output parameter’s
2363 name and type **MUST** match the VNF’s Heat Orchestration Template’s
2364 incremental Module’s name and type unless the output parameter is of type
2365 ‘comma_delimited_list’, then the corresponding input parameter **MUST**
2366 be declared as type ‘json’.
2368 If the Output parameter has a comma_delimited_list value (e.g., a collection
2369 of UUIDs from a Resource Group), then the corresponding input parameter
2370 must be declared as type json and not a comma_delimited_list, which is
2371 actually a string value with embedded commas.
2373 R-22608 When a VNF’s Heat Orchestration Template’s Base Module’s output
2374 parameter is declared as an input parameter in an Incremental Module,
2375 the parameter attribute ‘constraints:’ **MUST NOT** be declared.
2377 Additional details on ONAP Base Module Output Parameters are provided in
2378 `ONAP Output Parameter Names`_ and ONAP VNF Modularity.
2380 ONAP Volume Module Output Parameters
2381 ++++++++++++++++++++++++++++++++++++
2383 R-89913 A VNF’s Heat Orchestration Template’s Cinder Volume Module Output
2384 Parameter(s) **MUST** include the UUID(s) of the Cinder Volumes created in
2385 template, while other Output Parameters **MAY** be included.
2387 A VNF’s Heat Orchestration Template’s Cinder Volume Module Output Parameter(s)
2388 are only available for the module (base or incremental) that the volume
2389 template is associated with.
2391 R-07443 A VNF’s Heat Orchestration Templates’ Cinder Volume Module Output
2392 Parameter’s name and type **MUST** match the input parameter name and type
2393 in the corresponding Base Module or Incremental Module unless the Output
2394 Parameter is of the type ‘comma_delimited_list’, then the corresponding input
2395 parameter **MUST** be declared as type ‘json’.
2397 If the Output parameter has a comma_delimited_list value (e.g., a collection
2398 of UUIDs from a Resource Group), then the corresponding input parameter must
2399 be declared as type json and not a comma_delimited_list, which is actually a
2400 string value with embedded commas.
2402 R-20547 When an ONAP Volume Module Output Parameter is declared as an input
2403 parameter in a base or an incremental module Heat Orchestration Template,
2404 parameter constraints **MUST NOT** be declared.
2406 Additional details on ONAP Base Module Output Parameters are provided in
2407 `ONAP Output Parameter Names`_ and `Cinder Volume Templates`_.
2409 ONAP Predefined Output Parameters
2410 +++++++++++++++++++++++++++++++++++
2412 ONAP will look for a small set of pre-defined Heat output parameters to
2413 capture resource attributes for inventory in ONAP. These output parameters
2414 are optional and currently only two parameters are supported. These output
2415 parameters are optional and are specified in `OAM Management IP Addresses`_.
2417 Support of heat stack update
2418 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2420 ONAP does not support the use of heat stack-update command for scaling
2423 R-39349 A VNF Heat Orchestration Template **MUST NOT** be designed to
2424 utilize the OpenStack ‘heat stack-update’ command for scaling
2427 R-43413 A VNF **MUST** utilize a modular Heat Orchestration Template
2428 design to support scaling (growth/de-growth).
2430 Scope of a Heat Orchestration Template
2431 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2433 R-59482 A VNF’s Heat Orchestration Template **MUST NOT** be VNF instance
2434 specific or Cloud site specific
2436 R-56750 A VNF’s Heat Orchestration Template’s parameter values that are
2437 constant across all deployments **MUST** be declared in a Heat Orchestration
2438 Template Environment File.
2440 ONAP provides the instance specific parameter values to the Heat
2441 Orchestration Template at orchestration time.
2443 R-01896 A VNF’s Heat Orchestration Template’s parameter values that are
2444 constant across all deployments **MUST** be declared in a Heat Orchestration
2445 Template Environment File.
2450 ONAP defines two types of networks: External Networks and Internal Networks.
2455 ONAP defines an external network in relation to the VNF and not with regard
2456 to the Network Cloud site. External networks may also be referred to as
2457 “inter-VNF” networks. An external network must connect VMs in a VNF to
2458 VMs in another VNF or an external gateway or external router.
2460 An External Network may be a Neutron Network or a Contrail Network.
2462 R-16968 A VNF’s Heat Orchestration Templates **MUST NOT** include heat
2463 resources to create external networks.
2465 External networks must be orchestrated separately, independent of the VNF.
2466 This allows the network to be shared by multiple VNFs and managed
2467 independently of VNFs.
2469 R-00606 A VNF **MAY** be connected to zero, one or more than one external
2472 R-57424 A VNF’s port connected to an external network **MUST** connect the
2473 port to VMs in another VNF and/or an external gateway and/or external router.
2475 R-29865 A VNF’s port connected to an external network **MUST NOT** connect
2476 the port to VMs in the same VNF.
2478 R-69014 When a VNF connects to an external network, a network role, referred
2479 to as the ‘{network-role}’ **MUST** be assigned to the external network
2480 for use in the VNF’s Heat Orchestration Template.
2482 R-05201 When a VNF connects to two or more external networks, each external
2483 network **MUST** be assigned a unique ‘{network-role}’ in the context of
2484 the VNF for use in the VNF’s Heat Orchestration Template.
2486 R-83015 A VNF’s ‘{network-role}’ assigned to an external network **MUST**
2487 be different than the ‘{network-role}’ assigned to the VNF’s internal
2488 networks, if internal networks exist.
2490 ONAP enforces a naming convention for parameters associated with
2491 external networks. `ONAP Resource ID and Parameter Naming Convention`_
2492 provides additional details.
2497 ONAP defines an internal network in relation to the VNF and not with
2498 regard to the Network Cloud site. Internal networks may also be referred
2499 to as “intra-VNF” networks or “private” networks. An internal network
2500 only connects VMs in a single VNF; it must not connect to other VNFs
2501 or an external gateway or router
2503 R-87096 A VNF **MAY** contain zero, one or more than one internal networks.
2505 R-35666 If a VNF has an internal network, the VNF Heat Orchestration
2506 Template **MUST** include the heat resources to create the internal network.
2508 R-86972 A VNF **SHOULD** create the internal network in the VNF’s Heat
2509 Orchestration Template Base Module.
2511 An Internal Network may be created using Neutron Heat Resources and/or
2512 Contrail Heat Resources.
2514 R-52425 A VNF’s port connected to an internal network **MUST** connect
2515 the port to VMs in the same VNF.
2517 R-46461 A VNF’s port connected to an internal network **MUST NOT** connect
2518 the port to VMs in another VNF and/or an external gateway and/or
2521 R-68936 When a VNF creates an internal network, a network role, referred to
2522 as the ‘{network-role}’ **MUST** be assigned to the internal network for
2523 use in the VNF’s Heat Orchestration Template.
2525 R-32025 When a VNF creates two or more internal networks, each internal
2526 network **MUST** be assigned a unique ‘{network-role}’ in the context of
2527 the VNF for use in the VNF’s Heat Orchestration Template.
2529 R-69874 A VNF’s ‘{network-role}’ assigned to an internal network **MUST**
2530 be different than the ‘{network-role}’ assigned to the VNF’s external
2533 R-34726 If a VNF’s port is connected to an internal network and the port
2534 is created in the same Heat Orchestration Template as the internal network,
2535 then the port resource **MUST** use a ‘get_resource’ to obtain
2538 R-22688 If a VNF’s port is connected to an internal network and the
2539 port is created in an Incremental Module and the internal network is created
2540 in the Base Module then the UUID of the internal network **MUST** be exposed
2541 as a parameter in the ‘outputs:’ section of the Base Module and the port
2542 resource **MUST** use a ‘get_param’ to obtain the network UUID.
2544 ONAP does not programmatically enforce a naming convention for
2545 parameters for internal network. However, a naming convention is
2546 provided that must be followed.
2547 `ONAP Resource ID and Parameter Naming Convention`_
2548 provides additional details.
2550 ONAP Resource ID and Parameter Naming Convention
2551 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2553 This section provides the ONAP naming requirements for
2557 2. Resource Property Parameters
2562 R-01455 When a VNF's Heat Orchestration Template creates a Virtual Machine (i.e., 'OS::Nova::Server'),
2563 each 'class' of VMs **MUST** be assigned a VNF unique
2564 '{vm-type}'; where 'class' defines VMs that **MUST** have the following
2565 identical characteristics:
2567 1.) OS::Nova::Server property flavor value
2569 2.) OS::Nova::Server property image value
2571 3.) Cinder Volume attachments
2572 - Each VM in the 'class' **MUST** have the identical Cinder Volume
2575 4.) Network attachments and IP address requirements
2576 - Each VM in the 'class' **MUST** have the the identical number
2577 of ports connecting to the identical networks and requiring the
2578 identical IP address configuration.
2580 R-82481 A VNF's Heat Orchestration Template's Resource property
2582 associated with a unique Virtual Machine type **MUST**
2583 include '{vm-type}' as part of the parameter name with two
2586 1.) The Resource OS::Nova::Server property availability_zone parameter
2587 **MUST NOT** be prefixed with a common '{vm-type} identifier,
2589 2.) The Resource OS::Nova::Server eight mandatory and optional metadata
2590 parameters (vnf_name, vnf_id, vf_module_id, vf_module_name, vm_role,
2591 vf_module_index, environment_context, workload_context) **MUST NOT**
2592 be prefixed with a common '{vm-type}' identifier.
2595 R-66729 A VNF’s Heat Orchestration Template’s Resource that is
2596 associated with a unique Virtual Machine type **MUST** include
2597 ‘{vm-type}’ as part of the resource ID.
2599 R-98407 A VNF's Heat Orchestration Template's '{vm-type}' **MUST** contain
2600 only alphanumeric characters and/or underscores '_' and
2601 **MUST NOT** contain any of the following strings: '_int' or 'int\_'
2604 R-48067 A VNF's Heat Orchestration Template's {vm-type} **MUST NOT** be a
2605 substring of {network-role}.
2607 It may cause the Pre-Amsterdam VNF Validation Program (i.e.,
2608 ICE Project) process to produce erroneous error messages.
2610 R-32394 A VNF’s Heat Orchestration Template’s use of ‘{vm-type}’
2611 in all Resource property parameter names **MUST** be the same case.
2613 R-46839 A VNF’s Heat Orchestration Template’s use of
2614 ‘{vm-type}’ in all Resource IDs **MUST** be the same case.
2616 R-36687 A VNF’s Heat Orchestration Template’s ‘{vm-type}’ case in
2617 Resource property parameter names **SHOULD** match the case of
2618 ‘{vm-type}’ in Resource IDs and vice versa.
2623 The assignment of a {network-role} is discussed in `Networking`_.
2625 R-21330 A VNF’s Heat Orchestration Template’s Resource property parameter
2626 that is associated with external network **MUST** include the ‘{network-role}’’ as part of the parameter name
2628 R-11168 A VNF's Heat Orchestration Template's Resource ID that is
2629 associated with an external network **MUST** include the
2630 '{network-role}' as part of the resource ID.
2632 R-84322 A VNF's Heat Orchestration Template's Resource property
2633 parameter that is associated with an internal network
2634 **MUST** include 'int\_{network-role}' as part of the parameter
2635 name, where 'int\_' is a hard coded string.
2637 R-96983 A VNF's Heat Orchestration Template's Resource ID that is
2638 associated with an internal network **MUST** include
2639 'int\_{network-role}' as part of the Resource ID, where
2640 'int\_' is a hard coded string.
2642 R-26506 A VNF's Heat Orchestration Template's '{network-role}'
2643 **MUST** contain only alphanumeric characters and/or
2644 underscores '_' and **MUST NOT** contain any of the following
2645 strings: '_int' or 'int\_' or '\_int\_'.
2647 R-00977 A VNF’s Heat Orchestration Template’s ‘{network-role}’
2648 **MUST NOT** be a substring of ‘{vm-type}’.
2650 For example, if a VNF has a ‘{vm-type}’ of ‘oam’ and a
2651 ‘{network-role}’ of ‘oam_protected’ would be a violation of the requirement.
2653 R-58424 A VNF’s Heat Orchestration Template’s use of ‘{network-role}’
2654 in all Resource property parameter names **MUST** be the same case
2656 R-21511 A VNF’s Heat Orchestration Template’s use of ‘{network-role}’
2657 in all Resource IDs **MUST** be the same case.
2659 R-86588 A VNF’s Heat Orchestration Template’s ‘{network-role}’ case
2660 in Resource property parameter names **SHOULD** match the case
2661 of ‘{network-role}’ in Resource IDs and vice versa.
2666 Requirement R-75141 states a VNF’s Heat Orchestration Template’s
2667 resource name (i.e., <resource ID>) MUST only contain alphanumeric
2668 characters and underscores (‘_’).*
2670 Requirement R-16447 states a VNF’s <resource ID> MUST be unique
2671 across all Heat Orchestration Templates and all HEAT Orchestration
2672 Template Nested YAML files that are used to create the VNF.
2674 As stated previously, OpenStack requires the <resource ID> to be unique
2675 to the Heat Orchestration Template and not unique across all Heat
2676 Orchestration Templates the compose the VNF.
2678 Heat Orchestration Template resources are described in `resources`_
2680 R-54517 When a VNF’s Heat Orchestration Template’s resource is associated
2681 with a single ‘{vm-type}’, the Resource ID **MUST** contain the ‘{vm-type}’.
2683 R-96482 When a VNF’s Heat Orchestration Template’s resource is associated
2684 with a single external network, the Resource ID MUST contain the text
2687 R-98138 When a VNF’s Heat Orchestration Template’s resource is associated
2688 with a single internal network, the Resource ID MUST contain the text
2689 ‘int\_{network-role}’.
2691 R-82115 When a VNF's Heat Orchestration Template's resource is associated
2692 with a single '{vm-type}' and a single external network, the Resource
2693 ID text **MUST** contain both the '{vm-type}' and the '{network-role}'
2695 - the '{vm-type}' **MUST** appear before the '{network-role}' and **MUST**
2696 be separated by an underscore '_'
2698 - e.g., '{vm-type}_{network-role}', '{vm-type}_{index}_{network-role}'
2700 - note that an '{index}' value **MAY** separate the '{vm-type}' and the
2701 '{network-role}' and when this occurs underscores **MUST** separate the
2704 R-82551 When a VNF's Heat Orchestration Template's resource is associated
2705 with a single '{vm-type}' and a single internal network, the Resource ID
2706 **MUST** contain both the '{vm-type}' and the 'int\_{network-role}' and
2708 - the '{vm-type}' **MUST** appear before the 'int\_{network-role}' and
2709 **MUST** be separated by an underscore '_'
2711 - (e.g., '{vm-type}\_int\_{network-role}', '{vm-type}_{index}\_int\_{network-role}')
2713 - note that an '{index}' value **MAY** separate the '{vm-type}' and the
2714 'int\_{network-role}' and when this occurs underscores **MUST** separate
2717 R-67793 When a VNF’s Heat Orchestration Template’s resource is associated
2718 with more than one ‘{vm-type}’ and/or more than one internal and/or
2719 external network, the Resource ID **MUST NOT** contain the ‘{vm-type}’
2720 and/or ‘{network-role}’/’int\_{network-role}’. It also should contain the
2721 term ‘shared’ and/or contain text that identifies the VNF
2723 R-27970 When a VNF’s Heat Orchestration Template’s resource is associated
2724 with more than one ‘{vm-type}’ and/or more than one internal and/or
2725 external network, the Resource ID **MAY** contain the term ‘shared’
2726 and/or **MAY** contain text that identifies the VNF.
2728 R-11690 When a VNF’s Heat Orchestration Template’s Resource ID contains
2729 an {index} value (e.g. multiple VMs of same {vm-type}), the ‘{index}’
2730 **MUST** start at zero and increment by one.
2732 The table below provides example OpenStack Heat resource ID for
2733 resources only associated with one {vm-type} and/or one network.
2735 The Requirements column states if the Resource ID Format MUST be followed
2736 or SHOULD be followed. Resource ID formats that are marked MUST must be
2737 followed, no deviations are permitted. Resource ID formats that are marked
2738 SHOULD should be followed. However, deviations are permissible to meet
2739 the needs of the VNF’s Heat Orchestration Template.
2741 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2742 | Resource Type | Resource ID Format | Requirements | Notes |
2744 +==============================+=================================================================+====================================+=========================+
2745 | OS::Cinder::Volume | {vm-type}\_volume\_{index} | **SHOULD** | |
2747 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2748 | OS::Cinder::VolumeAttachment | {vm-type}\_volumeattachment\_{index} | **SHOULD** | |
2749 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2750 | OS::Heat::CloudConfig | {vm-type}_RCC | **SHOULD** | |
2751 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2752 | OS::Heat::MultipartMime | {vm-type}_RMM | **SHOULD** | |
2754 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2755 | OS::Heat::ResourceGroup | {vm-type}_RRG | **SHOULD** | |
2757 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2760 | | | | Resource ID for the |
2761 | | {vm-type}_{index}\_subint\_{network-role}_ | **MUST** for subinterface creation | OS::Heat::ResourceGroup |
2762 | | port\_{index}_subinterfaces | | that creates |
2763 | | | | subinterfaces |
2764 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2765 | OS::Heat::SoftwareConfig | {vm-type}_RSC | **SHOULD** | |
2767 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2768 | OS::Neutron::Port | {vm-type}_{vm-type-index}_{network-role}\_port\_{port-index} | **MUST** | Resource ID for port |
2769 | | | | connecting to an |
2770 | | | | external network. The |
2771 | | | | {vm-type-index} |
2773 | | | | instance of the |
2774 | | | | {vm_type}. The |
2775 | | | | {port-index} |
2777 | | | | instance of the |
2778 | | | | “port” on the |
2779 | | | | {vm-type}. There is |
2780 | | | | no index after |
2781 | | | | {network_role} since |
2782 | | | | since {network-role} |
2783 | | | | is unque to the VNF, |
2784 | | | | there should |
2785 | | | | only be one instance. |
2786 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2787 | | {vm-type}_{index}\_int\_{network-role}\_port\_{index} | | Resource ID for port |
2788 | | | **MUST** | connecting to an |
2789 | | | | internal network. The |
2790 | | | | {index} that follows |
2791 | | | | {vm-type} is the |
2792 | | | | instance of the |
2793 | | | | {vm_type}. The |
2794 | | | | {index} that follows |
2795 | | | | “port” is the |
2796 | | | | instance of the |
2797 | | | | “port” on the |
2798 | | | | {vm-type}. There is |
2799 | | | | no index after |
2800 | | | | {network_role} since |
2801 | | | | since {network-role} |
2802 | | | | is unque to the AIC |
2803 | | | | LCP; there should |
2804 | | | | only be one instance. |
2805 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2806 | | Reserve_Port\_{vm-type}_{network-role}\_floating_ip\_{index} | | Resource ID for a |
2807 | | | **MUST** | reserve port that is |
2808 | | | | used for an |
2809 | | | | allowed_address_pair. |
2810 | | Reserve_Port\_{vm-type}_{network-role}\_floating_v6_ip\_{index} | | See Section 5.6.5.5 |
2811 | | | | for additional |
2814 | | | | There is no {index} |
2815 | | | | that follows |
2817 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2818 | OS::Neutron::SecurityGroup | {vm-type}_Sec_Grp | | Security Group |
2819 | | | **SHOULD** | applicable to one |
2820 | | | | {vm-type} and more |
2821 | | | | than one network |
2822 | | | | (internal and/or |
2824 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2825 | | {network-role}_Sec_Grp | | Security Group |
2826 | | | **SHOULD** | applicable to more |
2827 | | | | than one {vm-type} |
2828 | | | | and one external |
2830 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2831 | | int\_{network-role}_Sec_Grp | | Security Group |
2832 | | | **SHOULD** | applicable to more |
2833 | | | | than one {vm-type} |
2834 | | | | and one internal |
2836 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2837 | | {vm-type}_{network-role}_Sec_Grp | | Security Group |
2838 | | | **SHOULD** | applicable to one |
2839 | | | | {vm-type} and one |
2840 | | | | external network |
2841 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2842 | | {vm-type}\_int\_{network-role}_Sec_Grp | | Security Group |
2843 | | | **SHOULD** | applicable to one |
2844 | | | | {vm-type} and one |
2845 | | | | internal network |
2846 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2847 | | Shared_Sec_Grp | | Security Group |
2848 | | | **SHOULD** | applicable to more |
2849 | | | | than one {vm-type} |
2850 | | | | and more than one |
2851 | | | | network (internal |
2852 | | | | and/or external) |
2853 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2854 | OS::Neutron::Subnet | int\_{network-role}\_subnet\_{index} | | VNF Heat |
2855 | | | **MUST** | Orchestration |
2856 | | | | Templates can only |
2857 | | | | create internal |
2859 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2860 | OS::Neutron::Net | int\_{network-role}\_network | | VNF Heat |
2861 | | | **MUST** | Orchestration |
2862 | | | | Templates can only |
2863 | | | | create internal |
2864 | | | | networks. There is no |
2865 | | | | {index} because |
2866 | | | | {nework-role} should |
2867 | | | | be unique. |
2869 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2870 | OS::Nova::Keypair | {vm-type}\_keypair\_{index} | **SHOULD** | Key Pair applicable to |
2871 | | | | one {vm-type} |
2872 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2873 | | {vnf-type}_keypair | **SHOULD** | Key Pair applicable |
2874 | | | | to all {vm-type} in the |
2876 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2877 | OS::Nova::Server | {vm-type}\_server\_{index} | Mandatory | |
2879 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2880 | OS::Nova::ServerGroup | {vm-type}_RSG | **SHOULD** | Both formats are |
2882 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2883 | | {vm-type}_Server_Grp | **SHOULD** | |
2884 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2885 | | {vm-type}_ServerGroup | **SHOULD** | |
2886 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2887 | OS::Swift::Container | {vm-type}_RSwiftC | **SHOULD** | |
2888 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2891 Table 2: Example OpenStack Heat Resource ID
2893 The table below provides Resource ID Formats for Contrail heat resources.
2894 - The Resource ID formats that are marked mandatory must be followed.
2895 No deviations are permitted.
2896 - The Resource ID formats that are marked optional should be followed.
2897 However, deviations in the Resource ID format that is shown is
2900 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2901 | Resource | Resource ID | Mandatory / | Notes | |
2902 | Type | Format | Optional | | |
2903 +=================+==========================================================================+=================+=================+===+
2904 | OS::ContrailV2: | {vm-type}_{index}_{network-role}\_vmi\_{index}\_IP\_{index} | **MUST** – | The {index} | |
2905 | :InstanceIp | | IPv4 address on | that follows | |
2906 | | | vmi external | {vm-type} is | |
2907 | | | network | the instance of | |
2908 | | | | the {vm_type}. | |
2909 | | | | The {index} | |
2910 | | | | that follows | |
2911 | | | | “vmi” is the | |
2912 | | | | instance of the | |
2913 | | | | “vmi” on the | |
2914 | | | | {vm-type}. | |
2915 | | | | There is no | |
2916 | | | | index after | |
2917 | | | | {network_role} | |
2918 | | | | since since | |
2919 | | | | {network-role} | |
2920 | | | | is unque. The | |
2921 | | | | {index} that | |
2922 | | | | follows the | |
2923 | | | | “IP” is the | |
2924 | | | | instance of the | |
2925 | | | | “IP” on the | |
2927 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2928 | | {vm-type}_{index}_{network-role}\_vmi\_{index}\_v6\_IP\_{index} | **MUST** – | | |
2929 | | | IPv6 address on | | |
2930 | | | vmi external | | |
2932 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2933 | | {vm-type}_{index}\_int\_{network-role}\_vmi\_{index}\_IP\_{index} | **MUST** – | | |
2934 | | | IPv4 address on | | |
2935 | | | vmi internal | | |
2937 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2938 | | {vm-type}_{index}\_int\_{network-role}\_vmi\_{index}\_v6\_IP\_{index} | **MUST** – | | |
2939 | | | IPv6 address on | | |
2940 | | | vmi internal | | |
2943 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2944 | | {vm-type}_{index}\_subint\_{network-role}\_vmi\_{index}\_IP\_{index} | **MUST** – | | |
2945 | | | IPv4 address on | | |
2946 | | | sub-interface | | |
2947 | | | vmi external | | |
2949 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2950 | | {vm-type}_{index}\_subint\_{network-role}\_vmi\_{index}\_v6\_IP\_{index} | **MUST** – | | |
2951 | | | IPv6 address on | | |
2952 | | | sub-interface | | |
2953 | | | vmi external | | |
2955 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2956 | OS::ContrailV2: | {network-role}_RIRT | **MAY** | | |
2957 | :InterfaceRoute | | | | |
2959 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2960 | OS::ContrailV2: | {network-role}_RNI | **MAY** | | |
2961 | :NetworkIpam | | | | |
2962 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2963 | OS::ContrailV2: | {vm-type}_RPT | **MAY** | | |
2964 | :PortTuple | | | | |
2965 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2966 | OS::ContrailV2: | {vm-type}\_RSHC\_{LEFT/RIGHT} | **MAY** | | |
2967 | :ServiceHealthC | | | | |
2969 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2970 | OS::ContrailV2: | {vm-type}\_RST\_{index} | **MAY** | | |
2971 | :ServiceTemplat | | | | |
2973 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2974 | OS::ContrailV2: | {vm-type}\_{index}\_{network-role}\_vmi\_{index} | **MUST** - vmi | Resource ID for | |
2975 | :VirtualMachine | | attached to an | virtual machine | |
2976 | Interface | | external | interface (vmi) | |
2977 | | | network | connecting to | |
2978 | | | | an external | |
2979 | | | | network. The | |
2980 | | | | {index} that | |
2982 | | | | {vm-type} is | |
2983 | | | | the instance of | |
2984 | | | | the {vm_type}. | |
2985 | | | | The {index} | |
2986 | | | | that follows | |
2987 | | | | “vmi” is the | |
2988 | | | | instance of the | |
2989 | | | | “vmi” on the | |
2990 | | | | {vm-type}. | |
2991 | | | | There is no | |
2992 | | | | index after | |
2993 | | | | {network_role} | |
2994 | | | | since since | |
2995 | | | | {network-role} | |
2996 | | | | is unque to the | |
2997 | | | | AIC LCP; there | |
2998 | | | | should only be | |
2999 | | | | one instance. | |
3000 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
3001 | | {vm-type}_{index}\_int\_{network-role}\_vmi\_{index} | **MUST** - vmi | | |
3002 | | | attached to an | | |
3003 | | | internal | | |
3005 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
3006 | | {vm-type}_{index}\_subint\_{network-role}\_vmi\_{index} | **MUST** - vmi | | |
3007 | | | attached to a | | |
3008 | | | sub-interface | | |
3010 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
3011 | OS::ContrailV2: | int\_{network-role}\_RVN | **MAY** | VNF Heat | |
3012 | :VirtualNetwork | | | Orchestration | |
3013 | | | | Templates can | |
3014 | | | | only create | |
3015 | | | | internal | |
3016 | | | | networks. There | |
3017 | | | | is no {index} | |
3019 | | | | {nework-role} | |
3020 | | | | should be | |
3021 | | | | unique. Both | |
3022 | | | | formats are | |
3024 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
3025 | | int\_{network-role}\_network | **MAY** | | |
3027 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
3029 Table 3: Example Contrail Heat resource ID
3031 There is a use case where the template filename is used as the type: as
3032 shown in the example below. There is no suggested Resource ID naming
3033 convention for this use case.
3035 Example: Template Filename used as the type:
3037 .. code-block:: python
3039 heat_template_version: 2015-04-30
3047 Resource: OS::Nova::Server - Parameters
3048 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3050 The resource OS::Nova::Server manages the running virtual machine (VM)
3051 instance within an OpenStack cloud. (See
3052 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::Server.)
3054 Four properties of this resource must follow the ONAP parameter naming
3055 convention. The four properties are:
3063 4. availability\_zone
3065 Requirement R-01455 defines how the ‘{vm-type]’ is defined.
3067 Requirement R-82481 defines how the ‘{vm-type} is used.’
3069 The table below provides a summary. The sections that follow provides
3070 the detailed requirements.
3072 .. csv-table:: **Table 4 OS::Nova::Server Resource Property Parameter Naming Convention**
3073 :header: Property Name,Parameter Type,Parameter Name,Parameter Value Provided to Heat
3077 image, string, {vm-type}\_image\_name, Environment File
3078 flavor, string, {vm-type}\_flavor\_name, Environment File
3079 name, string, {vm-type}\_name\_{index}, ONAP
3080 name, CDL, {vm-type}_names, ONAP
3081 availability_zone, string, availability\_zone\_{index}, ONAP
3086 R-71152 The VNF’s Heat Orchestration Template’s Resource
3087 ‘OS::Nova::Server’ property ‘image’ parameter **MUST** be declared as
3090 R-58670 The VNF’s Heat Orchestration Template’s Resource
3091 ‘OS::Nova::Server’ property ‘image’ parameter name **MUST** follow the
3092 naming convention ‘{vm-type}_image_name’.
3094 R-91125 The VNF’s Heat Orchestration Template’s Resource
3095 ‘OS::Nova::Server’ property ‘image’ parameter **MUST** be enumerated in
3096 the Heat Orchestration Template’s Environment File and a value **MUST** be
3099 R-57282 Each VNF’s Heat Orchestration Template’s ‘{vm-type}’
3100 **MUST** have a unique parameter name for the ‘OS::Nova::Server’
3101 property ‘image’ even if more than one {vm-type} shares the same image.
3103 *Example Parameter Definition*
3105 .. code-block:: yaml
3108 {vm-type}_image_name:
3110 description: {vm-type} server image
3115 R-50436 The VNF’s Heat Orchestration Template’s Resource
3116 ‘OS::Nova::Server’ property ‘flavor’ parameter **MUST** be declared as
3119 R-45188 The VNF’s Heat Orchestration Template’s Resource
3120 ‘OS::Nova::Server’ property ‘flavor’ parameter name **MUST** follow the
3121 naming convention ‘{vm-type}_flavor_name’.
3123 R-69431 The VNF’s Heat Orchestration Template’s Resource
3124 ‘OS::Nova::Server’ property ‘flavor’ parameter **MUST** be enumerated in the
3125 Heat Orchestration Template’s Environment File and a value **MUST** be
3128 R-40499 Each VNF’s Heat Orchestration Template’s ‘{vm-type}’ **MUST**
3129 have a unique parameter name for the ‘OS::Nova::Server’ property
3130 ‘flavor’ even if more than one {vm-type} shares the same flavor.
3132 *Example Parameter Definition*
3134 .. code-block:: yaml
3137 {vm-type}_flavor_name:
3139 description: {vm-type} flavor
3144 R-51430 The VNF’s Heat Orchestration Template’s Resource
3145 ‘OS::Nova::Server’ property ‘name’ parameter **MUST** be declared as
3146 either type ‘string’ or type ‘comma_delimited_list”.
3148 R-54171 When the VNF’s Heat Orchestration Template’s Resource
3149 ‘OS::Nova::Server’ property ‘name’ parameter is defined as a ‘string’,
3150 the parameter name **MUST** follow the naming convention
3151 ‘{vm-type}\_name\_{index}’, where {index} is a numeric value that starts
3152 at zero and increments by one.
3154 R-40899 When the VNF’s Heat Orchestration Template’s Resource
3155 ‘OS::Nova::Server’ property ‘name’ parameter is defined as a ‘string’,
3156 a parameter **MUST** be declared for each ‘OS::Nova::Server’ resource
3157 associated with the ‘{vm-type}’.
3159 R-87817 When the VNF’s Heat Orchestration Template’s Resource
3160 ‘OS::Nova::Server’ property ‘name’ parameter is defined as a
3161 ‘comma_delimited_list’, the parameter name **MUST** follow the naming
3162 convention ‘{vm-type}_names’.
3164 R-85800 When the VNF’s Heat Orchestration Template’s Resource
3165 ‘OS::Nova::Server’ property ‘name’ parameter is defined as a
3166 ‘comma_delimited_list’, a parameter **MUST** be delcared once for all
3167 ‘OS::Nova::Server’ resources associated with the ‘{vm-type}’.
3169 R-22838 The VNF’s Heat Orchestration Template’s Resource
3170 ‘OS::Nova::Server’ property ‘name’ parameter **MUST NOT** be enumerated
3171 in the Heat Orchestration Template’s Environment File.
3173 If a VNF’s Heat Orchestration Template’s contains more than three
3174 OS::Nova::Server resources of a given {vm-type}, the comma_delimited_list
3175 form of the parameter name (i.e., ‘{vm-type}_names’) should be used to
3176 minimize the number of unique parameters defined in the template.
3179 *Example: Parameter Definition*
3181 .. code-block:: python
3186 type: comma_delimited_list
3187 description: VM Names for {vm-type} VMs
3189 {vm-type}_name_{index}:
3191 description: VM Name for {vm-type} VM {index}
3193 *Example: comma_delimited_list*
3195 In this example, the {vm-type} has been defined as “lb” for load balancer.
3197 .. code-block:: python
3202 type: comma_delimited_list
3203 description: VM Names for lb VMs
3207 type: OS::Nova::Server
3209 name: { get_param: [lb_names, 0] }
3213 type: OS::Nova::Server
3215 name: { get_param: [lb_names, 1] }
3218 *Example: fixed-index*
3220 In this example, the {vm-type} has been defined as “lb” for load balancer.
3222 .. code-block:: python
3228 description: VM Name for lb VM 0
3232 description: VM Name for lb VM 1
3237 type: OS::Nova::Server
3239 name: { get_param: lb_name_0 }
3243 type: OS::Nova::Server
3245 name: { get_param: lb_name_1 }
3248 Contrail Issue with Values for OS::Nova::Server Property Name
3249 _____________________________________________________________
3251 R-44271 The VNF's Heat Orchestration Template's Resource 'OS::Nova::Server' property
3252 'name' parameter value **SHOULD NOT** contain special characters
3253 since the Contrail GUI has a limitation displaying special characters.
3255 However, if special characters must be used, the only special characters
3258 --- \" ! $ ' (\ \ ) = ~ ^ | @ ` { } [ ] > , . _
3261 Property: availability\_zone
3262 ++++++++++++++++++++++++++++
3264 R-98450 The VNF’s Heat Orchestration Template’s Resource
3265 ‘OS::Nova::Server’ property ‘availability_zone’ parameter name
3266 **MUST** follow the naming convention ‘availability\_zone\_{index}’
3267 where the ‘{index}’ **MUST** start at zero and increment by one.
3269 R-23311 The VNF’s Heat Orchestration Template’s Resource
3270 ‘OS::Nova::Server’ property ‘availability_zone’ parameter **MUST**
3271 be declared as type: ‘string’.
3273 The parameter must not be declared as type ‘comma_delimited_list’,
3274 ONAP does not support it.
3276 R-59568 The VNF’s Heat Orchestration Template’s Resource
3277 ‘OS::Nova::Server’ property ‘availability_zone’ parameter **MUST NOT**
3278 be enumerated in the Heat Orchestration Template’s Environment File.
3280 Example Parameter Definition
3282 .. code-block:: python
3285 availability_zone_{index}:
3287 description: availability zone {index} name
3289 Requirement R-90279 states that a VNF Heat Orchestration’s template’s
3290 parameter MUST be used in a resource with the exception of the parameters
3291 for the OS::Nova::Server resource property availability_zone.
3293 R-01359 A VNF’s Heat Orchstration Template that contains an
3294 ‘OS::Nova:Server’ Resource **MAY** define a parameter for the property
3295 ‘availability_zone’ that is not utilized in any ‘OS::Nova::Server’
3296 resources in the Heat Orchestration Template.
3301 The example below depicts part of a Heat Orchestration Template that
3302 uses the four OS::Nova::Server properties discussed in this section.
3304 In the Heat Orchestration Template below, four Virtual
3305 Machines (OS::Nova::Server) are created: two dns servers with
3306 {vm-type} set to “dns” and two oam servers with {vm-type} set to “oam”.
3307 Note that the parameter associated with the property name is a
3308 comma_delimited_list for dns and a string for oam.
3310 .. code-block:: python
3316 description: dns server image
3320 description: dns server flavor
3323 type: comma_delimited_list
3324 description: dns server names
3328 description: oam server image
3332 description: oam server flavor
3336 description: oam server name 0
3340 description: oam server name 1
3342 availability_zone_0:
3344 description: availability zone ID or Name
3346 availability_zone_1:
3348 description: availability zone ID or Name
3353 type: OS::Nova::Server
3355 name: { get_param: [ dns_names, 0 ] }
3356 image: { get_param: dns_image_name }
3357 flavor: { get_param: dns_flavor_name }
3358 availability_zone: { get_param: availability_zone_0 }
3363 type: OS::Nova::Server
3365 name: { get_param: [ dns_names, 1 ] }
3366 image: { get_param: dns_image_name }
3367 flavor: { get_param: dns_flavor_name }
3368 availability_zone: { get_param: availability_zone_1 }
3373 type: OS::Nova::Server
3375 name: { get_param: oam_name_0 }
3376 image: { get_param: oam_image_name }
3377 flavor: { get_param: oam_flavor_name }
3378 availability_zone: { get_param: availability_zone_0 }
3383 type: OS::Nova::Server
3385 name: { get_param: oam_name_1 }
3386 image: { get_param: oam_image_name }
3387 flavor: { get_param: oam_flavor_name }
3388 availability_zone: { get_param: availability_zone_1 }
3395 R-99798 A VNF’s Heat Orchestration Template’s Virtual Machine
3396 (i.e., OS::Nova::Server Resource) **MAY** boot from an image or **MAY**
3397 boot from a Cinder Volume.
3399 R-83706 When a VNF’s Heat Orchestration Template’s Virtual Machine
3400 (i.e., ‘OS::Nova::Server’ Resource) boots from an image, the
3401 ‘OS::Nova::Server’ resource property ‘image’ **MUST** be used.
3403 The requirements associated with
3404 the 'image' property are detailed in `Property: image`_
3406 R-69588 When a VNF’s Heat Orchestration Template’s Virtual Machine
3407 (i.e., ‘OS::Nova::Server’ Resource) boots from Cinder Volume, the
3408 ‘OS::Nova::Server’ resource property ‘block_device_mapping’ or
3409 ‘block_device_mapping_v2’ **MUST** be used.
3411 There are currently no heat guidelines
3412 associated with these two properties:
3413 'block_device_mapping' and 'block_device_mapping_v2'.
3415 Resource: OS::Nova::Server – Metadata Parameters
3416 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3418 The resource OS::Nova::Server has an OpenStack optional property
3419 metadata. The metadata property is mandatory for ONAP Heat Orchestration
3420 Templates; it must be included.
3422 R-17020 The VNF Heat Orchestration Template **MUST** include the following three mandatory
3423 metadata parameters for an OS::Nova::Server resource:
3431 ONAP allows the following three optional metadata parameters for an
3432 OS::Nova::Server resource. They may be included
3438 Note that the metadata parameters do not and must not contain {vm-type}
3441 When Metadata parameters are past into a nested heat template, the
3442 parameter names must not change.
3444 The table below provides a summary. The sections that follow provides
3447 +-------------------+----------+-------------------+----------------+
3448 | Metadata Parameter| Parameter| Mandatory/Optional| Parameter Value|
3449 | Name | Type | | Generation |
3450 +===================+==========+===================+================+
3451 | vnf\_id | string | Mandatory | ONAP |
3452 +-------------------+----------+-------------------+----------------+
3453 | vf\_module\_id | string | Mandatory | ONAP |
3454 +-------------------+----------+-------------------+----------------+
3455 | vnf\_name | string | Mandatory | ONAP |
3456 +-------------------+----------+-------------------+----------------+
3457 | vf\_module\_name | string | Optional | ONAP |
3458 +-------------------+----------+-------------------+----------------+
3459 | vm\_role | string | Optional | YAML or |
3460 | | | | Environment |
3462 +-------------------+----------+-------------------+----------------+
3464 Table 4: ONAP Metadata
3469 The vnf\_id parameter is mandatory; it must be included in the Heat
3470 Orchestration Template.
3472 The vnf\_id parameter value will be supplied by ONAP. ONAP generates the
3473 UUID that is the vnf\_id and supplies it to the Heat Orchestration
3474 Template at orchestration time.
3476 The parameter must be declared as type: string
3478 R-55218 The VNF Heat Orchestration Template **MUST NOT** have parameter constraints defined
3479 for the OS::Nova::Server metadata parameter vnf\_id.
3481 R-20856 The VNF Heat Orchestration Template **MUST NOT** enumerate the OS::Nova::Server
3482 metadata parameter vnf\_id in environment file.
3484 *Example Parameter Definition*
3486 .. code-block:: yaml
3491 description: Unique ID for this VNF instance
3496 The vf\_module\_id parameter is mandatory; it must be included in the
3497 Heat Orchestration Template.
3499 The vf\_module\_id parameter value will be supplied by ONAP. ONAP
3500 generates the UUID that is the vf\_module\_id and supplies it to the
3501 Heat Orchestration Template at orchestration time.
3503 The parameter must be declared as type: string
3505 R-98374 The VNF Heat Orchestration Template **MUST NOT** have parameter constraints
3506 defined for the OS::Nova::Server metadata parameter vf\_module\_id.
3508 R-72871 The VNF Heat Orchestration Template **MUST NOT** enumerate the OS::Nova::Server
3509 metadata parameter vf\_module\_id in environment file.
3511 *Example Parameter Definition*
3513 .. code-block:: yaml
3518 description: Unique ID for this VNF module instance
3523 The vnf\_name parameter is mandatory; it must be included in the Heat
3524 Orchestration Template.
3526 The vnf\_name parameter value will be generated and/or assigned by ONAP
3527 and supplied to the Heat Orchestration Template by ONAP at orchestration
3530 The parameter must be declared as type: string
3532 R-44318 The VNF Heat Orchestration Template **MUST NOT** have parameter constraints defined
3533 for the OS::Nova::Server metadata parameter vnf\_name.
3535 R-36542 The VNF Heat Orchestration Template **MUST NOT** enumerate the OS::Nova::Server
3536 metadata parameter vnf\_name in the environment file.
3538 *Example Parameter Definition*
3540 .. code-block:: yaml
3545 description: Unique name for this VNF instance
3550 The vf\_module\_name parameter is optional; it may be included in the
3551 Heat Orchestration Template.
3553 The vf\_module\_name parameter is the name of the name of the Heat stack
3554 (e.g., <STACK\_NAME>) in the command “Heat stack-create” (e.g., Heat
3555 stack-create [-f <FILE>] [-e <FILE>] <STACK\_NAME>). The <STACK\_NAME>
3556 needs to be specified as part of the orchestration process.
3558 The parameter must be declared as type: string
3560 Parameter constraints must not be defined.
3562 The parameter must not be enumerated in the Heat environment file.
3564 *Example Parameter Definition*
3566 .. code-block:: yaml
3571 description: Unique name for this VNF Module instance
3576 The vm\_role parameter is optional; it may be included in the Heat
3577 Orchestration Template.
3579 Any roles tagged to the VMs via metadata will be stored in ONAP’s A&AI
3580 system and available for use by other ONAP components and/or north bound
3583 The vm\_role values must be either
3585 - hard-coded into the Heat Orchestration Template or
3587 - enumerated in the environment file.
3589 Defining the vm\_role as the {vm-type} is a recommended convention
3591 The parameter must be declared as type: string
3593 Parameter constraints must not be defined.
3595 *Example Parameter Definition*
3597 .. code-block:: yaml
3602 description: Unique role for this VM
3604 *Example Resource Definition: Hard Coded*
3606 In this example, the {vm-role} is hard coded in the Heat Orchestration
3609 .. code-block:: yaml
3613 type: OS::Nova::Server
3619 *Example Resource Definition: get\_param*
3621 In this example, the {vm-role} is enumerated in the environment file.
3623 .. code-block:: yaml
3627 type: OS::Nova::Server
3631 vm_role: { get_param: vm_role }
3636 The example below depicts part of a Heat Orchestration Template that
3637 uses the five of the OS::Nova::Server metadata parameter discussed in
3638 this section. The {vm-type} has been defined as lb for load balancer.
3640 .. code-block:: yaml
3645 description: VM Name for lb VM 0
3648 description: Unique name for this VNF instance
3651 description: Unique ID for this VNF instance
3654 description: Unique name for this VNF Module instance
3657 description: Unique ID for this VNF Module instance
3660 description: Unique role for this VM
3665 type: OS::Nova::Server
3667 name: { get_param: lb_name_0 }
3670 vnf_name: { get_param: vnf_name }
3671 vnf_id: { get_param: vnf_id }
3672 vf_module_name: { get_param: vf_module_name }
3673 vf_module_id: { get_param: vf_module_id }
3676 Resource: OS::Neutron::Port - Parameters
3677 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3679 The resource OS::Neutron::Port is for managing Neutron ports (See
3680 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Port.)
3685 Four properties of the resource OS::Neutron::Port that must follow the
3686 ONAP parameter naming convention. The four properties are:
3690 2. fixed\_ips, ip\_address
3692 3. fixed\_ips, subnet\_id
3694 4. allowed\_address\_pairs, ip\_address
3696 The parameters associated with these properties may reference an
3697 external network or internal network. External networks and internal
3698 networks are defined in `Networking`_.
3703 When the parameter references an external network
3705 - R-72050 The VNF Heat Orchestration Template **MUST** contain {network-role} in the parameter name
3707 - the parameter must not be enumerated in the Heat environment file
3709 - the parameter is classified as an ONAP Orchestration Parameter
3711 +----------------------+---------------------------+--------------------------+
3712 | Property Name | ONAP Parameter Name | Parameter Type |
3713 +======================+===========================+==========================+
3714 | network | {network-role}\_net\_id | string |
3715 | +---------------------------+--------------------------+
3716 | | {network-role}\_net\_name | string |
3717 +----------------------+---------------------------+--------------------------+
3718 | fixed\_ips, | {vm-type}\_{network-role}\| string |
3719 | ip\_address | _ip\_{index} | |
3720 | +---------------------------+--------------------------+
3721 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
3723 | +---------------------------+--------------------------+
3724 | | {vm-type}\_{network-role}\| string |
3725 | | _v6\_ip\_{index} | |
3726 | +---------------------------+--------------------------+
3727 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
3729 +----------------------+---------------------------+--------------------------+
3730 | fixed\_ips, subnet | {network-role}\ | string |
3732 | +---------------------------+--------------------------+
3733 | | {network-role}\ | string |
3734 | | _v6\_subnet\_id | |
3735 +----------------------+---------------------------+--------------------------+
3736 | allowed\_address | {vm-type}\_{network-role}\| string |
3737 | \_pairs, ip\_address | _floating\_ip | |
3738 | +---------------------------+--------------------------+
3739 | | {vm-type}\_{network-role}\| string |
3740 | | _floating\_v6\_ip | |
3741 | +---------------------------+--------------------------+
3742 | | {vm-type}\_{network-role}\| string |
3743 | | _ip\_{index} | |
3744 | +---------------------------+--------------------------+
3745 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
3747 | +---------------------------+--------------------------+
3748 | | {vm-type}\_{network-role}\| string |
3749 | | _v6\_ip\_{index} | |
3750 | +---------------------------+--------------------------+
3751 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
3753 +----------------------+---------------------------+--------------------------+
3755 Table 5: OS::Neutron::Port Resource Property Parameters (External
3761 When the parameter references an internal network
3763 - R-57576 The VNF Heat Orchestration Template **MUST** contain int\_{network-role}
3764 in the parameter name.
3766 - the parameter may be enumerated in the environment file.
3768 +-------------------------+--------------------------------+-----------------+
3769 | Property | Parameter Name for | Parameter Type |
3770 | | Internal Networks | |
3771 +=========================+================================+=================+
3772 | network | int\_{network-role}\ | string |
3774 | +--------------------------------+-----------------+
3775 | | int\_{network-role}\ | string |
3777 +-------------------------+--------------------------------+-----------------+
3778 | fixed\_ips, ip\_address | {vm-type}\_int\_{network-role}\| string |
3779 | | _ip\_{index} | |
3780 | +--------------------------------+-----------------+
3781 | | {vm-type}\_int\_{network-role}\| comma\ |
3782 | | _ips | _delimited\_list|
3783 | +--------------------------------+-----------------+
3784 | | {vm-type}\_int\_{network-role}\| string |
3785 | | _v6\_ip\_{index} | |
3786 | +--------------------------------+-----------------+
3787 | | {vm-type}\_int\_{network-role}\| comma\ |
3788 | | _v6\_ips | _delimited\_list|
3789 +-------------------------+--------------------------------+-----------------+
3790 | fixed\_ips, subnet | int\_{network-role}\ | string |
3792 | +--------------------------------+-----------------+
3793 | | int\_{network-role}\ | string |
3794 | | _v6\_subnet\_id | |
3795 +-------------------------+--------------------------------+-----------------+
3796 | allowed\_address\_pairs,| {vm-type}\_int\_{network-role}\| string |
3797 | ip\_address | _floating\_ip | |
3798 | +--------------------------------+-----------------+
3799 | | {vm-type}\_int\_{network-role}\| string |
3800 | | _floating\_v6\_ip | |
3801 | +--------------------------------+-----------------+
3802 | | {vm-type}\_int\_{network-role}\| string |
3803 | | _ip\_{index} | |
3804 | +--------------------------------+-----------------+
3805 | | {vm-type}\_int\_{network-role}\| comma\ |
3806 | | _ips | _delimited\_list|
3807 | +--------------------------------+-----------------+
3808 | | {vm-type}\_int\_{network-role}\| string |
3809 | | _v6\_ip\_{index} | |
3810 | +--------------------------------+-----------------+
3811 | | {vm-type}\_int\_{network-role}\| comma\ |
3812 | | _v6\_ips | _delimited\_list|
3813 +-------------------------+--------------------------------+-----------------+
3815 Table 6: Port Resource Property Parameters (Internal Networks)
3820 The property networks in the resource OS::Neutron::Port must be
3821 referenced by Neutron Network ID, a UUID value, or by the network name
3822 defined in OpenStack.
3827 R-93272 The VNF Heat Orchestration Template **MUST** adhere to the following parameter naming
3828 convention in the Heat Orchestration Template, when the parameter
3829 associated with the property network is referencing an “external” network:
3831 - {network-role}\_net\_id for the Neutron network ID
3833 - {network-role}\_net\_name for the network name in OpenStack
3835 The parameter must be declared as type: string
3837 The parameter must not be enumerated in the Heat environment file.
3839 *Example Parameter Definition*
3841 .. code-block:: yaml
3844 {network-role}_net_id:
3846 description: Neutron UUID for the {network-role} network
3847 {network-role}_net_name:
3849 description: Neutron name for the {network-role} network
3851 *Example: One Cloud Assigned IP Address (DHCP) assigned to a network
3852 that has only one subnet*
3854 In this example, the {network-role} has been defined as oam to represent
3855 an oam network and the {vm-type} has been defined as lb for load
3856 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3857 to assign IP addresses.
3859 .. code-block:: yaml
3864 description: Neutron UUID for the oam network
3868 type: OS::Neutron::Port
3869 network: { get_param: oam_net_id }
3874 R-65373 The VNF Heat Orchestration Template **MUST** adhere to the following parameter naming
3875 convention, when the parameter associated with the property network is
3876 referencing an “internal” network:
3878 - int\_{network-role}\_net\_id for the Neutron network ID
3880 - int\_{network-role}\_net\_name for the network name in OpenStack
3882 The parameter must be declared as type: string
3884 The assumption is that internal networks are created in the base module.
3885 The Neutron Network ID will be passed as an output parameter (e.g., ONAP
3886 Base Module Output Parameter) to the incremental modules. In the
3887 incremental modules, it will be defined as input parameter.
3889 *Example Parameter Definition*
3891 .. code-block:: yaml
3894 int_{network-role}_net_id:
3896 description: Neutron UUID for the {network-role} network
3897 int_{network-role}_net_name:
3899 description: Neutron name for the {network-role} network
3901 Property: fixed\_ips, Map Property: subnet\_id
3902 ++++++++++++++++++++++++++++++++++++++++++++++
3904 The property fixed\_ips is used to assign IPs to a port. The Map
3905 Property subnet\_id specifies the subnet the IP is assigned from.
3907 The property fixed\_ips and Map Property subnet\_id must be used if a
3908 Cloud (i.e., DHCP) IP address assignment is being requested and the
3909 Cloud IP address assignment is targeted at a specific subnet when two or
3912 The property fixed\_ips and Map Property subnet\_id should not be used
3913 if all IP assignments are fixed, or if the Cloud IP address assignment
3914 does not target a specific subnet or there is only one subnet.
3916 Note that DHCP assignment of IP addresses is also referred to as cloud
3917 assigned IP addresses.
3919 Subnet of an External Networks
3920 ______________________________
3922 R-47716 The VNF Heat Orchestration Template **MUST** adhere to the following parameter naming
3923 convention for the property fixed\_ips and Map Property subnet\_id
3924 parameter, when the parameter is referencing a subnet of an
3927 - {network-role}\_subnet\_id if the subnet is an IPv4 subnet
3929 - {network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
3931 The parameter must be declared as type: string
3933 The parameter must not be enumerated in the Heat environment file.
3935 *Example Parameter Definition*
3937 .. code-block:: yaml
3940 {network-role}_subnet_id:
3942 description: Neutron subnet UUID for the {network-role} network
3944 {network-role}_v6_subnet_id:
3946 description: Neutron subnet UUID for the {network-role} network
3948 *Example: One Cloud Assigned IPv4 Address (DHCP) assigned to a network
3949 that has two or more subnets subnet:*
3951 In this example, the {network-role} has been defined as oam to represent
3952 an oam network and the {vm-type} has been defined as lb for load
3953 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3954 to assign IP addresses.
3956 .. code-block:: yaml
3961 description: Neutron UUID for the oam network
3965 description: Neutron subnet UUID for the oam network
3969 type: OS::Neutron::Port
3970 network: { get_param: oam_net_id }
3972 - subnet_id: { get_param: oam_subnet_id }
3974 *Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6
3975 address assigned to a network that has at least one IPv4 subnet and one
3978 In this example, the {network-role} has been defined as oam to represent
3979 an oam network and the {vm-type} has been defined as lb for load
3982 .. code-block:: yaml
3987 description: Neutron UUID for the oam network
3991 description: Neutron subnet UUID for the oam network
3995 description: Neutron subnet UUID for the oam network
3999 type: OS::Neutron::Port
4001 network: { get_param: oam_net_id }
4003 - subnet_id: { get_param: oam_subnet_id }
4004 - subnet_id: { get_param: oam_v6_subnet_id }
4009 R-20106 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention for
4010 the property fixed\_ips and Map Property subnet\_id parameter,
4011 when the parameter is referencing the subnet of an “internal” network:
4013 - int\_{network-role}\_subnet\_id if the subnet is an IPv4 subnet
4015 - int\_{network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
4017 The parameter must be declared as type: string
4019 The assumption is that internal networks are created in the base module.
4020 The Neutron subnet network ID will be passed as an output parameter
4021 (e.g., ONAP Base Module Output Parameter) to the incremental modules. In
4022 the incremental modules, it will be defined as input parameter.
4024 *Example Parameter Definition*
4026 .. code-block:: yaml
4029 int_{network-role}_subnet_id:
4031 description: Neutron subnet UUID for the {network-role} network
4033 int_{network-role}_v6_subnet_id:
4035 description: Neutron subnet UUID for the {network-role} network
4037 Property: fixed\_ips, Map Property: ip\_address
4038 +++++++++++++++++++++++++++++++++++++++++++++++
4040 The property fixed\_ips is used to assign IPs to a port. The Map
4041 Property ip\_address specifies the IP address to be assigned to the
4044 The property fixed\_ips and Map Property ip\_address must be used when
4045 statically assigning one or more IP addresses to a port. This is also
4046 referred to as ONAP SDN-C IP address assignment. ONAP’s SDN-C provides
4047 the IP address assignment.
4049 An IP address is assigned to a port on a VM (referenced by {vm-type})
4050 that is connected to an external network (referenced by {network-role})
4051 or internal network (referenced by int\_{network-role}).
4053 R-41177 The VNF Heat Orchestration Template **MUST** include {vm-type} and {network-role}
4054 in the parameter name, when a SDN-C IP assignment is made to a
4055 port connected to an external network.
4057 When a SDN-C IP assignment is made to a port connected to an internal
4058 network, the parameter name must contain {vm-type} and
4059 int\_{network-role}.
4061 IP Address Assignments on External Networks
4062 ___________________________________________
4064 When the property fixed\_ips and Map Property ip\_address is used to
4065 assign IP addresses to an external network, the parameter name is
4066 dependent on the parameter type (comma\_delimited\_list or string) and
4067 IP address type (IPv4 or IPv6).
4069 R-84898 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention,
4070 when the parameter for property fixed\_ips and Map Property ip\_address
4071 is declared type: comma\_delimited\_list:
4073 - {vm-type}\_{network-role}\_ips for IPv4 address
4075 - {vm-type}\_{network-role}\_v6\_ips for IPv6 address
4077 Each element in the IP list should be assigned to successive instances
4078 of {vm-type} on {network-role}.
4080 The parameter must not be enumerated in the Heat environment file.
4082 *Example Parameter Definition*
4084 .. code-block:: yaml
4088 {vm-type}_{network-role}_ips:
4089 type: comma_delimited_list
4090 description: Fixed IPv4 assignments for {vm-type} VMs on the {Network-role} network
4092 {vm-type}_{network-role}_v6_ips:
4093 type: comma_delimited_list
4094 description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
4096 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
4097 Assignments to an external network*
4099 In this example, the {network-role} has been defined as oam to represent
4100 an oam network and the {vm-type} has been defined as db for database.
4102 .. code-block:: yaml
4107 description: Neutron UUID for a oam network
4110 type: comma_delimited_list
4111 description: Fixed IPv4 assignments for db VMs on the oam network
4114 type: comma_delimited_list
4115 description: Fixed IPv6 assignments for db VMs on the oam network
4119 type: OS::Neutron::Port
4120 network: { get_param: oam_net_id }
4121 fixed_ips: [ { “ip_address”: {get_param: [ db_oam_ips, 0 ]}}, {“ip_address”: {get_param: [ db_oam_v6_ips, 0 ]}}]
4124 type: OS::Neutron::Port
4126 network: { get_param: oam_net_id }
4128 - “ip_address”: {get_param: [ db_oam_ips, 1 ]}
4129 - “ip_address”: {get_param: [ db_oam_v6_ips, 1 ]}
4131 R-34960 The VNF Heat Orchestration Template **MUST** adhere to the following
4133 when the parameter for property fixed\_ips and Map Property ip\_address
4134 is declared type: string:
4136 - {vm-type}\_{network-role}\_ip\_{index} for an IPv4 address
4138 - {vm-type}\_{network-role}\_v6\_ip\_{index} for an IPv6 address
4140 The value for {index} must start at zero (0) and increment by one.
4142 The parameter must not be enumerated in the Heat environment file.
4144 *Example Parameter Definition*
4146 .. code-block:: yaml
4149 {vm-type}_{network-role}_ip_{index}:
4151 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
4153 {vm-type}_{network-role}_v6_ip_{index}:
4155 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
4157 *Example: string parameters for IPv4 and IPv6 Address Assignments
4158 to an external network*
4160 In this example, the {network-role} has been defined as “oam” to
4161 represent an oam network and the {vm-type} has been defined as “db” for
4164 .. code-block:: yaml
4169 description: Neutron UUID for an OAM network
4173 description: Fixed IPv4 assignment for db VM 0 on the OAM network
4177 description: Fixed IPv4 assignment for db VM 1 on the OAM network
4181 description: Fixed IPv6 assignment for db VM 0 on the OAM network
4185 description: Fixed IPv6 assignment for db VM 1 on the OAM network
4189 type: OS::Neutron::Port
4191 network: { get_param: oam_net_id }
4192 fixed_ips: [ { “ip_address”: {get_param: db_oam_ip_0}}, {“ip_address”: {get_param: db_oam_v6_ip_0 ]}}]
4195 type: OS::Neutron::Port
4197 network: { get_param: oam_net_id }
4199 - “ip_address”: {get_param: db_oam_ip_1}}]
4200 - “ip_address”: {get_param: db_oam_v6_ip_1}}]
4202 IP Address Assignment on Internal Networks
4203 __________________________________________
4205 When the property fixed\_ips and Map Property ip\_address is used to
4206 assign IP addresses to an internal network, the parameter name is
4207 dependent on the parameter type (comma\_delimited\_list or string) and
4208 IP address type (IPv4 or IPv6).
4210 R-62584 The VNF Heat Orchestration Template **MUST** adhere to
4211 the following naming convention,
4212 when the parameter for property fixed\_ips and Map Property ip\_address
4213 is declared type: comma\_delimited\_list:
4215 - {vm-type}\_int\_{network-role}\_ips for IPv4 address
4217 - {vm-type}\_int\_{network-role}\_v6\_ips for IPv6 address
4219 Each element in the IP list should be assigned to successive instances
4220 of {vm-type} on {network-role}.
4222 The parameter must be enumerated in the Heat environment file. Since an
4223 internal network is local to the VNF, IP addresses can be re-used at
4226 *Example Parameter Definition*
4228 .. code-block:: yaml
4232 {vm-type}_int_{network-role}_ips:
4233 type: comma_delimited_list
4234 description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
4236 {vm-type}_int_{network-role}_v6_ips:
4237 type: comma_delimited_list
4238 description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
4240 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
4241 Assignments to an internal network*
4243 In this example, the {network-role} has been defined as oam\_int to
4244 represent an oam network internal to the vnf. The role oam\_int was
4245 picked to differentiate from an external oam network with a
4246 {network-role} of oam. The {vm-type} has been defined as db for
4249 .. code-block:: yaml
4254 description: Neutron UUID for the oam internal network
4257 type: comma_delimited_list
4258 description: Fixed IPv4 assignments for db VMs on the oam internal network
4260 db_int_oam_int_v6_ips:
4261 type: comma_delimited_list
4262 description: Fixed IPv6 assignments for db VMs on the oam internal network
4266 type: OS::Neutron::Port
4268 network: { get_param: int_oam_int_net_id }
4269 fixed_ips: [ { “ip_address”: {get_param: [ db_int_oam_int_ips, 0]}}, { “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 0 ]}}]
4272 type: OS::Neutron::Port
4274 network: { get_param: int_oam_int_net_id }
4276 - “ip_address”: {get_param: [ db_int_oam_int_ips, 1 ]}
4277 - “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 1 ]}
4279 R-29256 The VNF Heat Orchestration Template **MUST** must adhere to the following
4281 when the parameter for property fixed\_ips and Map Property ip\_address
4282 is declared type: string:
4284 - {vm-type}\_int\_{network-role}\_ip\_{index} for an IPv4 address
4286 - {vm-type}\_int\_{network-role}\_v6\_ip\_{index} for an IPv6 address
4288 The value for {index} must start at zero (0) and increment by one.
4290 The parameter must be enumerated in the Heat environment file. Since an
4291 internal network is local to the VNF, IP addresses can be re-used at
4294 *Example Parameter Definition*
4296 .. code-block:: yaml
4300 {vm-type}_int_{network-role}_ip_{index}:
4302 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
4304 {vm-type}_int_{network-role}_v6_ip_{index}:
4306 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
4308 *Example: string parameters for IPv4 and IPv6 Address Assignments
4309 to an internal network*
4311 In this example, the {network-role} has been defined as oam\_int to
4312 represent an oam network internal to the vnf. The role oam\_int was
4313 picked to differentiate from an external oam network with a
4314 {network-role} of oam. The {vm-type} has been defined as db for
4317 .. code-block:: yaml
4322 description: Neutron UUID for an OAM internal network
4326 description: Fixed IPv4 assignment for db VM on the oam_int network
4330 description: Fixed IPv4 assignment for db VM 1 on the oam_int network
4334 description: Fixed IPv6 assignment for db VM 0 on the oam_int network
4338 description: Fixed IPv6 assignment for db VM 1 on the oam_int network
4342 type: OS::Neutron::Port
4344 network: { get_param: int_oam_int_net_id }
4345 fixed_ips: [ { “ip_address”: {get_param: db_oam_int_ip_0}}, {“ip_address”: {get_param: db_oam_int_v6_ip_0 ]}}]
4348 type: OS::Neutron::Port
4350 network: { get_param: int_oam_int_net_id }
4352 - “ip_address”: {get_param: db_oam_int_ip_1}}]
4353 - “ip_address”: {get_param: db_oam_int_v6_ip_1}}]
4355 Property: allowed\_address\_pairs, Map Property: ip\_address
4356 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4358 The property allowed\_address\_pairs in the resource OS::Neutron::Port
4359 allows the user to specify a mac\_address and/or ip\_address that will
4360 pass through a port regardless of subnet. This enables the use of
4361 protocols such as VRRP, which floats an IP address between two instances
4362 to enable fast data plane failover. The map property ip\_address
4363 specifies the IP address.
4365 The allowed\_address\_pairs is an optional property. It is not required.
4367 An ONAP Heat Orchestration Template allows the assignment of one IPv4
4368 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
4369 and {network-role}/int\_{network-role} combination.
4371 An ONAP Heat Orchestration Template allows the assignment of one IPv6
4372 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
4373 and {network-role}/int\_{network-role} combination.
4375 Note that the management of these IP addresses (i.e. transferring
4376 ownership between active and standby VMs) is the responsibility of the
4379 Note that these parameters are **not** intended to represent Neutron
4380 “Floating IP” resources, for which OpenStack manages a pool of public IP
4381 addresses that are mapped to specific VM ports. In that case, the
4382 individual VMs are not even aware of the public IPs, and all assignment
4383 of public IPs to VMs is via OpenStack commands. ONAP does not support
4384 Neutron-style Floating IPs.
4389 R-61282 The VNF Heat Orchestration Template **MUST**
4390 adhere to the following naming convention for the property
4391 allowed\_address\_pairs and Map Property ip\_address parameter,
4392 when the parameter is referencing an “external” network:
4394 - {vm-type}\_{network-role}\_floating\_ip for an IPv4 address
4396 - {vm-type}\_{network-role}\_floating\_v6\_ip for an IPv6 address
4398 The parameter must be declared as type: string
4400 The parameter must not be enumerated in the Heat environment file.
4402 *Example Parameter Definition*
4404 .. code-block:: yaml
4408 {vm-type}_{network-role}_floating_ip:
4410 description: VIP for {vm-type} VMs on the {network-role} network
4412 {vm-type}_{network-role}_floating_v6_ip:
4414 description: VIP for {vm-type} VMs on the {network-role} network
4418 In this example, the {network-role} has been defined as oam to represent
4419 an oam network and the {vm-type} has been defined as db for database.
4421 .. code-block:: yaml
4426 description: Neutron UUID for the oam network
4429 type: comma_delimited_list
4430 description: Fixed IPs for db VMs on the oam network
4434 description: VIP IP for db VMs on the oam network
4438 type: OS::Neutron::Port
4440 network: { get_param: oam_net_id }
4441 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,0] }}]
4442 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
4445 type: OS::Neutron::Port
4447 network: { get_param: oam_net_id }
4448 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,1] }}]
4449 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
4454 R-16805 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention
4455 for the property allowed\_address\_pairs and Map Property ip\_address
4456 parameter when the parameter is referencing an “internal” network.
4458 - {vm-type}\_int\_{network-role}\_floating\_ip for an IPv4 address
4460 - {vm-type}\_int\_{network-role}\_floating\_v6\_ip for an IPv6 address
4462 The parameter must be declared as type: string
4464 The parameter must be enumerated in the Heat environment file.
4466 *Example Parameter Definition*
4468 .. code-block:: yaml
4472 {vm-type}_int_{network-role}_floating_ip:
4474 description: VIP for {vm-type} VMs on the int_{network-role} network
4476 {vm-type}_int_{network-role}_floating_v6_ip:
4478 description: VIP for {vm-type} VMs on the int_{network-role} network
4480 Multiple allowed\_address\_pairs for a {vm-type} / {network-role} combination
4481 __________________________________________________________________
4483 The parameter {vm-type}\_{network-role}\_floating\_ip provides only one
4484 allowed address pair IPv4 address per {vm-type} and {network-role} pair.
4486 The parameter {vm-type}\_{network-role}\_floating\_v6\_ip provides only
4487 one allowed address pair IPv6 address per {vm-type} and {network-role}
4490 If there is a need for multiple allowed address pair IPs for a given
4491 {vm-type} and {network-role} combination within a VNF, then the
4492 parameter names defined for the property fixed\_ips and Map Property
4493 ip\_address should be used with the allowed\_address\_pairs property.
4494 The examples below illustrate this.
4496 *Example: A VNF has four load balancers. Each pair has a unique VIP.*
4498 In this example, there are two administrative VM pairs. Each pair has
4499 one VIP. The {network-role} has been defined as oam to represent an oam
4500 network and the {vm-type} has been defined as admin for an
4503 Pair 1: Resources admin\_0\_port\_0 and admin\_1\_port\_0 share a unique
4504 VIP, [admin\_oam\_ips,2]
4506 Pair 2: Resources admin\_2\_port\_0 and admin\_3\_port\_0 share a unique
4507 VIP, [admin\_oam\_ips,5]
4509 .. code-block:: yaml
4514 description: Neutron UUID for the oam network
4516 type: comma_delimited_list
4517 description: Fixed IP assignments for admin VMs on the oam network
4522 type: OS::Neutron::Port
4524 network: { get_param: oam_net_id }
4525 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,0] }}]
4526 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
4529 type: OS::Neutron::Port
4531 network: { get_param: oam_net_id }
4532 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,1] }}]
4533 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
4536 type: OS::Neutron::Port
4538 network: { get_param: oam_net_id }
4539 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,3] }}]
4540 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
4543 type: OS::Neutron::Port
4545 network: { get_param: oam_net_id }
4546 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,4] }}]
4547 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
4549 *Example: A VNF has two load balancers. The pair of load balancers share
4552 In this example, there is one load balancer pairs. The pair has two
4553 VIPs. The {network-role} has been defined as oam to represent an oam
4554 network and the {vm-type} has been defined as lb for a load balancer VM.
4556 .. code-block:: yaml
4560 type: OS::Neutron::Port
4562 network: { get_param: oam_net_id }
4563 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,0] }}]
4564 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
4567 type: OS::Neutron::Port
4569 network: { get_param: oam_net_id }
4570 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,1] }}]
4571 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
4573 As a general rule, provide the fixed IPs for the VMs indexed first in
4574 the CDL and then the VIPs as shown in the examples above.
4576 ONAP SDN-C Assignment of allowed\_address\_pair IP Addresses
4577 __________________________________________________________________
4579 The following items must be taken into consideration when designing Heat
4580 Orchestration Templates that expect ONAP’s SDN-C to assign
4581 allowed\_address\_pair IP addresses via automation.
4583 The VMs must be of the same {vm-type}.
4585 The VMs must be created in the same module (base or incremental).
4587 Resource Property “name”
4588 ~~~~~~~~~~~~~~~~~~~~~~~~
4590 The parameter naming convention of the property name for the resource
4591 OS::Nova::Server has been defined in
4592 `Resource: OS::Nova::Server – Metadata Parameters`_.
4594 This section provides the requirements how the property name for non
4595 OS::Nova::Server resources must be defined when the property is used.
4596 Not all resources require the property name (e.g., it is optional) and
4597 some resources do not support the property.
4599 R-85734 The VNF Heat Orchestration Template **MUST** use the intrinsic function str\_replace
4600 in conjunction with the ONAP supplied metadata parameter
4601 vnf\_name to generate a unique value,
4602 when the property name for a non OS::Nova::Server resources is defined
4603 in a Heat Orchestration Template.
4605 This prevents the enumeration of a
4606 unique value for the property name in a per instance environment file.
4610 - In most cases, only the use of the metadata value vnf\_name is
4611 required to create a unique property name
4613 - the Heat Orchestration Template pseudo parameter 'OS::stack\_name’
4614 may also be used in the str\_replace construct to generate a unique
4615 name when the vnf\_name does not provide uniqueness
4617 *Example: Property* name *for resource* OS::Neutron::SecurityGroup
4619 .. code-block:: yaml
4623 type: OS::Neutron::SecurityGroup
4625 description: vDNS security group
4628 template: VNF_NAME_sec_grp_DNS
4630 VNF_NAME: {get_param: vnf_name}
4634 *Example: Property name for resource* OS::Cinder::Volume
4636 .. code-block:: yaml
4640 type: OS::Cinder::Volume
4642 description: Cinder Volume
4645 template: VNF_NAME_STACK_NAME_dns_volume
4647 VNF_NAME: {get_param: vnf_name}
4648 STACK_NAME: { get_param: 'OS::stack_name' }
4651 Contrail Issue with Values for the Property Name
4652 ++++++++++++++++++++++++++++++++++++++++++++++++
4654 The Contrail GUI has a limitation displaying special characters. The
4655 issue is documented in
4656 https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is
4657 recommended that special characters be avoided. However, if special
4658 characters must be used, note that for the following resources:
4672 the only special characters supported are:
4674 - “ ! $ ‘ ( ) = ~ ^ \| @ \` { } [ ] > , . \_
4676 ONAP Output Parameter Names
4677 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
4679 ONAP defines three types of Output Parameters as detailed in
4680 `Output Parameters`_.
4682 ONAP Base Module Output Parameters:
4683 +++++++++++++++++++++++++++++++++++
4685 ONAP Base Module Output Parameters do not have an explicit naming
4686 convention. The parameter name must contain {vm-type} and {network-role}
4689 ONAP Volume Template Output Parameters:
4690 +++++++++++++++++++++++++++++++++++++++
4692 ONAP Base Module Output Parameters do not have an explicit naming
4693 convention. The parameter name must contain {vm-type} when appropriate.
4695 Predefined Output Parameters
4696 ++++++++++++++++++++++++++++
4698 ONAP currently defines one predefined output parameter the OAM
4699 Management IP Addresses.
4701 OAM Management IP Addresses
4702 ___________________________
4704 A VNF may have a management interface for application controllers to
4705 interact with and configure the VNF. Typically, this will be via a
4706 specific VM that performs a VNF administration function. The IP address
4707 of this interface must be captured and inventoried by ONAP. The IP
4708 address might be a VIP if the VNF contains an HA pair of management VMs,
4709 or may be a single IP address assigned to one VM.
4711 The Heat template may define either (or both) of the following Output
4712 parameters to identify the management IP address.
4714 - oam\_management\_v4\_address
4716 - oam\_management\_v6\_address
4720 - The use of this output parameters are optional.
4722 - The Management IP Address should be defined only once per VNF, so it
4723 must only appear in one Module template
4725 - If a fixed IP for the admin VM is passed as an input parameter, it
4726 may be echoed in the output parameters. In this case, a IPv4 and/or
4727 IPv6 parameter must be defined in the parameter section of the YAML
4728 Heat template. The parameter maybe named oam\_management\_v4\_address
4729 and/or oam\_management\_v6\_address or may be named differently.
4731 - If the IP for the admin VM is obtained via DHCP, it may be obtained
4732 from the resource attributes. In this case,
4733 oam\_management\_v4\_address and/or oam\_management\_v6\_address must
4734 not be defined in the parameter section of the YAML Heat template.
4736 *Example: SDN-C Assigned IP Address echoed as*
4737 oam\_management\_v4\_address
4739 .. code-block:: yaml
4744 description: Fixed IPv4 assignment for admin VM 0 on the OAM network
4748 admin_oam_net_0_port:
4749 type: OS::Neutron::Port
4753 template: VNF_NAME_admin_oam_net_0_port
4755 VNF_NAME: {get_param: vnf_name}
4756 network: { get_param: oam_net_id }
4757 fixed_ips: [{ "ip_address": { get_param: admin_oam_ip_0 }}]
4758 security_groups: [{ get_param: security_group }]
4761 type: OS::Nova::Server
4763 name: { get_param: admin_names }
4764 image: { get_param: admin_image_name }
4765 flavor: { get_param: admin_flavor_name }
4766 availability_zone: { get_param: availability_zone_0 }
4768 - port: { get_resource: admin_oam_net_0_port }
4770 vnf_id: { get_param: vnf_id }
4771 vf_module_id: { get_param: vf_module_id }
4772 vnf_name: {get_param: vnf_name }
4774 oam_management_v4_address:
4775 value: {get_param: admin_oam_ip_0 }
4777 *Example: Cloud Assigned IP Address output as*
4778 oam\_management\_v4\_address
4780 .. code-block:: yaml
4785 admin_oam_net_0_port:
4786 type: OS::Neutron::Port
4790 template: VNF_NAME_admin_oam_net_0_port
4792 VNF_NAME: {get_param: vnf_name}
4793 network: { get_param: oam_net_id }
4794 security_groups: [{ get_param: security_group }]
4797 type: OS::Nova::Server
4799 name: { get_param: admin_names }
4800 image: { get_param: admin_image_name }
4801 flavor: { get_param: admin_flavor_name }
4802 availability_zone: { get_param: availability_zone_0 }
4804 - port: { get_resource: admin_oam_net_0_port }
4806 vnf_id: { get_param: vnf_id }
4807 vf_module_id: { get_param: vf_module_id }
4808 vnf_name: {get_param: vnf_name }
4811 oam_management_v4_address:
4812 value: {get_attr: [admin_server, networks, {get_param: oam_net_id}, 0] }
4814 Contrail Resource Parameters
4815 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4817 ONAP requires the parameter names of certain Contrail Resources to
4818 follow specific naming conventions. This section provides these
4821 Contrail Network Parameters
4822 +++++++++++++++++++++++++++
4824 Contrail based resources may require references to a Contrail network
4825 using the network FQDN.
4830 When the parameter associated with the Contrail Network is referencing
4831 an “external” network, the parameter must adhere to the following naming
4832 convention in the Heat Orchestration Template
4834 - {network-role}\_net\_fqdn
4836 The parameter must be declared as type: string
4838 The parameter must not be enumerated in the Heat environment file.
4840 *Example: Parameter declaration*
4842 .. code-block:: yaml
4845 {network-role}_net_fqdn:
4847 description: Contrail FQDN for the {network-role} network
4849 *Example: Contrail Resource OS::ContrailV2::VirtualMachineInterface
4850 Reference to a Network FQDN.*
4852 In this example, the {network-role} has been defined as oam to represent
4853 an oam network and the {vm-type} has been defined as fw for firewall.
4854 The Contrail resource OS::ContrailV2::VirtualMachineInterface property
4855 virtual\_network\_refs references a contrail network FQDN.
4857 .. code-block:: yaml
4860 type: OS::ContrailV2::VirtualMachineInterface
4864 template: VM_NAME_virtual_machine_interface_1
4866 VM_NAME: { get_param: fw_name_0 }
4867 virtual_machine_interface_properties:
4868 virtual_machine_interface_properties_service_interface_type: { get_param: oam_protected_interface_type }
4869 virtual_network_refs:
4870 - get_param: oam_net_fqdn
4871 security_group_refs:
4872 - get_param: fw_sec_grp_id
4874 Interface Route Table Prefixes for Contrail InterfaceRoute Table
4875 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4877 The parameter associated with the resource
4878 OS::ContrailV2::InterfaceRouteTable property
4879 interface\_route\_table\_routes, map property
4880 interface\_route\_table\_routes\_route\_prefix is an ONAP Orchestration
4883 The parameters must be named {vm-type}\_{network-role}\_route\_prefixes
4884 in the Heat Orchestration Template.
4886 The parameter must be declared as type: json
4888 The parameter supports IP addresses in the format:
4890 1. Host IP Address (e.g., 10.10.10.10)
4892 2. CIDR Notation format (e.g., 10.0.0.0/28)
4894 The parameter must not be enumerated in the Heat environment file.
4896 *Example Parameter Definition*
4898 .. code-block:: yaml
4901 {vm-type}_{network-role}_route_prefixes:
4903 description: JSON list of Contrail Interface Route Table route prefixes
4907 .. code-block:: yaml
4912 description: Unique name for this VF instance
4913 fw_int_fw_route_prefixes:
4915 description: prefix for the ServiceInstance InterfaceRouteTable
4916 int_fw_dns_trusted_interface_type:
4918 description: service_interface_type for ServiceInstance
4921 type: OS::ContrailV2::InterfaceRouteTable
4922 depends_on: [*resource name of* *OS::ContrailV2::ServiceInstance*]
4926 template: VNF_NAME_interface_route_table
4928 VNF_NAME: { get_param: vnf_name }
4929 interface_route_table_routes:
4930 interface_route_table_routes_route: { get_param: fw_int_fw_route_prefixes }
4931 service_instance_refs:
4932 - get_resource: < *resource name of* *OS::ContrailV2::ServiceInstance* >
4933 service_instance_refs_data:
4934 - service_instance_refs_data_interface_type: { get_param: int_fw_interface_type }
4936 Parameter Names in Contrail Resources
4937 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4939 Contrail Heat resource properties will use, when appropriate, the same
4940 naming convention as OpenStack Heat resources. For example, the resource
4941 OS::ContrailV2::InstanceIp has two properties that the parameter naming
4942 convention is identical to properties in OS::Neutron::Port.
4944 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4945 instance\_ip\_address*
4947 The property instance\_ip\_address uses the same parameter naming
4948 convention as the property fixed\_ips and Map Property ip\_address in
4949 OS::Neutron::Port. The resource is assigning an ONAP SDN-C Assigned IP
4950 Address. The {network-role} has been defined as oam\_protected to
4951 represent an oam protected network and the {vm-type} has been defined as
4954 .. code-block:: yaml
4956 CMD_FW_OAM_PROTECTED_RII:
4957 type: OS::ContrailV2::InstanceIp
4959 - FW_OAM_PROTECTED_RVMI
4961 virtual_machine_interface_refs:
4962 - get_resource: FW_OAM_PROTECTED_RVMI
4963 virtual_network_refs:
4964 - get_param: oam_protected_net_fqdn
4965 instance_ip_address: { get_param: [fw_oam_protected_ips, get_param: index ] }
4967 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4970 The property instance\_ip\_address uses the same parameter naming
4971 convention as the property fixed\_ips and Map Property subnet\_id in
4972 OS::Neutron::Port. The resource is assigning a Cloud Assigned IP
4973 Address. The {network-role} has been defined as “oam\_protected” to
4974 represent an oam protected network and the {vm-type} has been defined as
4977 .. code-block:: yaml
4979 CMD_FW_SGI_PROTECTED_RII:
4980 type: OS::ContrailV2::InstanceIp
4982 - FW_OAM_PROTECTED_RVMI
4984 virtual_machine_interface_refs:
4985 - get_resource: FW_OAM_PROTECTED_RVMI
4986 virtual_network_refs:
4987 - get_param: oam_protected_net_fqdn
4988 subnet_uuid: { get_param: oam_protected_subnet_id }
4990 Cinder Volume Templates
4991 ^^^^^^^^^^^^^^^^^^^^^^^^
4993 ONAP supports the independent deployment of a Cinder volume via separate
4994 Heat Orchestration Templates, the Cinder Volume module. This allows the
4995 volume to persist after VNF deletion so that they can be reused on
4996 another instance (e.g., during a failover activity).
4998 A Base Module or Incremental Module may have a corresponding volume
4999 module. Use of separate volume modules is optional. A Cinder volume may
5000 be embedded within the Base Module or Incremental Module if persistence
5003 R-47788 The VNF Heat Orchestration Template **MUST** have a 1:1 scope of a cinder volume module,
5004 when it exists, with the Base Module or Incremental Module
5006 A single volume module must create only the volumes
5007 required by a single Incremental module or Base module.
5009 The following rules apply to independent volume Heat templates:
5011 - Cinder volumes must be created in a separate Heat Orchestration
5012 Template from the Base Module or Incremental Module.
5014 - A single Cinder volume module must include all Cinder volumes
5015 needed by the Base/Incremental module.
5017 - R-79531 The VNF Heat Orchestration Template **MUST** define “outputs” in the volume
5018 template for each Cinder volume resource universally unique
5019 identifier (UUID) (i.e. ONAP Volume Template Output Parameters).
5021 - The VNF Incremental Module or Base Module must define input
5022 parameters that match each Volume output parameter (i.e., ONAP Volume
5023 Template Output Parameters).
5025 - ONAP will supply the volume template outputs automatically to the
5026 bases/incremental template input parameters.
5028 - Volume modules may utilize nested Heat templates.
5030 *Examples: Volume Template*
5032 A VNF has a Cinder volume module, named incremental\_volume.yaml, that
5033 creates an independent Cinder volume for a VM in the module
5034 incremental.yaml. The incremental\_volume.yaml defines a parameter in
5035 the output section, lb\_volume\_id\_0 which is the UUID of the cinder
5036 volume. lb\_volume\_id\_0 is defined as a parameter in incremental.yaml.
5037 ONAP captures the UUID value of lb\_volume\_id\_0 from the volume module
5038 output statement and provides the value to the incremental module.
5040 Note that the example below is not a complete Heat Orchestration
5041 Template. The {vm-type} has been defined as “lb” for load balancer
5043 incremental\_volume.yaml
5045 .. code-block:: yaml
5056 type: OS::Cinder::Volume
5060 template: VNF_NAME_volume_0
5062 VNF_NAME: { get_param: vnf_name }
5063 size: {get_param: dns_volume_size_0}
5068 value: {get_resource: dns_volume_0}
5074 .. code-block:: yaml
5085 type: OS::Nova::Server
5087 name: {get_param: dns_name_0}
5092 type: OS::Cinder::VolumeAttachment
5094 instance_uuid: { get_resource: lb_0 }
5095 volume_id: { get_param: lb_volume_id_0 }
5097 ONAP Support of Environment Files
5098 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5100 The use of an environment file in OpenStack is optional. In ONAP, it is
5103 R-86285 The VNF Heat Orchestration Template **MUST** have a
5104 corresponding environment file, even if no parameters are required to be
5107 (Note that ONAP, the open source version of ONAP, does not
5108 programmatically enforce the use of an environment file.)
5110 R-67205 The VNF Heat Orchestration Template **MUST** have a corresponding
5111 environment file for a Base Module.
5113 R-35727 The VNF Heat Orchestration Template **MUST** have a
5114 corresponding environment file for an Incremental module.
5116 R-22656 The VNF Heat Orchestration Template **MUST** have a corresponding environment file
5117 for a Cinder Volume Module.
5119 A nested heat template must not have an environment file; OpenStack does
5122 The environment file must contain parameter values for the ONAP
5123 Orchestration Constants and VNF Orchestration Constants. These
5124 parameters are identical across all instances of a VNF type, and
5125 expected to change infrequently. The ONAP Orchestration Constants are
5126 associated with OS::Nova::Server image and flavor properties (See
5127 `Property: image`_ and `Property: flavor`_). Examples of VNF
5128 Orchestration Constants are the networking parameters associated
5129 with an internal network (e.g., private IP ranges) and Cinder
5132 The environment file must not contain parameter values for parameters
5133 that are instance specific (ONAP Orchestration Parameters, VNF
5134 Orchestration Parameters). These parameters are supplied to the Heat by
5135 ONAP at orchestration time.
5137 SDC Treatment of Environment Files
5138 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5140 Parameter values enumerated in the environment file are used by SDC as
5141 the default value. However, the SDC user may use the SDC GUI to
5142 overwrite the default values in the environment file.
5144 SDC generates a new environment file for distribution to MSO based on
5145 the uploaded environment file and the user provided GUI updates. The
5146 user uploaded environment file is discarded when the new file is
5147 created. Note that if the user did not change any values via GUI
5148 updates, the SDC generated environment file will contain the same values
5149 as the uploaded file.
5151 Use of Environment Files when using OpenStack “heat stack-create” CLI
5152 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5154 When ONAP is instantiating the Heat Orchestration Template, certain
5155 parameter must not be enumerated in the environment file. This document
5156 provides the details of what parameters should not be enumerated.
5158 If the Heat Orchestration Template is to be instantiated from the
5159 OpenStack Command Line Interface (CLI) using the command “heat
5160 stack-create”, all parameters must be enumerated in the environment
5163 Heat Template Constructs
5164 ^^^^^^^^^^^^^^^^^^^^^^^^^
5166 Nested Heat Templates
5167 ~~~~~~~~~~~~~~~~~~~~~
5169 ONAP supports nested Heat templates per the OpenStack specifications.
5170 Nested templates may be suitable for larger VNFs that contain many
5171 repeated instances of the same VM type(s). A common usage pattern is to
5172 create a nested template for each {vm-type} along with its supporting
5173 resources. The VNF module may then reference these component templates
5174 either statically by repeated definition or dynamically by using the
5175 resource OS::Heat::ResourceGroup.
5177 Nested Heat Template Requirements
5178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5180 ONAP supports nested Heat Orchestration Templates. A Base Module,
5181 Incremental Module, and Cinder Volume Module may use nested heat.
5183 A Heat Orchestration Template may reference the nested heat statically
5184 by repeated definition.
5186 A Heat Orchestration Template may reference the nested heat dynamically
5187 using the resource OS::Heat::ResourceGroup.
5189 A Heat Orchestration template must have no more than three levels of
5190 nesting. ONAP supports a maximum of three levels.
5192 Nested heat templates must be referenced by file name. The use of
5193 resource\_registry in the environment file is not supported and must not
5196 R-89868 The VNF Heat Orchestration Template **MUST** have unique file names within the scope
5197 of the VNF for a nested heat yaml file.
5199 R-52530 The VNF Heat Orchestration Template **MUST NOT** use a directory hierarchy for
5200 nested templates. All templates must be in a single, flat directory
5203 A nested heat template may be used by any module within a given VNF.
5207 - Constrains must not be defined for any parameter enumerated in a
5208 nested heat template.
5210 - R-11041 The VNF Heat Orchestration Template **MUST** have the resource calling the
5211 nested yaml file pass in as properties all parameters defined
5212 in nested yaml file.
5214 - R-61183 The VNF Heat Orchestration Template **MUST NOT** change the parameter names, when OS::Nova::Server metadata parameters are past into a nested heat
5217 - With nested templates, outputs are required to expose any resource
5218 properties of the child templates to the parent template. Those would
5219 not explicitly be declared as parameters but simply referenced as
5220 get\_attribute targets against the “parent” resource.
5222 Nested Heat Template Example: Static
5223 ++++++++++++++++++++++++++++++++++++++
5227 .. code-block:: yaml
5233 dns_image_name: { get_param: dns_image_name }
5234 dns_flavor_name: { get_param: dns_flavor_name }
5235 availability_zone: { get_param: availability_zone_0 }
5236 security_group: { get_param: DNS_shared_sec_grp_id }
5237 oam_net_id: { get_param: oam_protected_net_id }
5238 dns_oam_ip: { get_param: dns_oam_ip_0 }
5239 dns_name: { get_param: dns_name_0 }
5240 vnf_name: { get_param: vnf_name }
5241 vnf_id: { get_param: vnf_id }
5242 vf_module_id: {get_param: vf_module_id}
5247 dns_image_name: { get_param: dns_image_name }
5248 dns_flavor_name: { get_param: dns_flavor_name }
5249 availability_zone: { get_param: availability_zone_1 }
5250 security_group: { get_param: DNS_shared_sec_grp_id }
5251 oam_net_id: { get_param: oam_protected_net_id }
5252 dns_oam_ip: { get_param: dns_oam_ip_1 }
5253 dns_name: { get_param: dns_name_1 }
5254 vnf_name: { get_param: vnf_name }
5255 vnf_id: { get_param: vnf_id }
5256 vf_module_id: {get_param: vf_module_id}
5260 .. code-block:: yaml
5263 type: OS::Neutron::Port
5267 template: VNF_NAME_dns_oam_port
5269 VNF_NAME: {get_param: vnf_name}
5270 network: { get_param: oam_net_id }
5271 fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}]
5272 security_groups: [{ get_param: security_group }]
5275 type: OS::Nova::Server
5277 name: { get_param: dns_names }
5278 image: { get_param: dns_image_name }
5279 flavor: { get_param: dns_flavor_name }
5280 availability_zone: { get_param: availability_zone }
5282 - port: { get_resource: dns_oam_0_port }
5284 vnf_id: { get_param: vnf_id }
5285 vf_module_id: { get_param: vf_module_id }
5286 vnf_name {get_param: vnf_name }
5288 Use of Heat ResourceGroup
5289 +++++++++++++++++++++++++
5291 The OS::Heat::ResourceGroup is a useful Heat element for creating
5292 multiple instances of a given resource or collection of resources.
5293 Typically, it is used with a nested Heat template, to create, for
5294 example, a set of identical OS::Nova::Server resources plus their
5295 related OS::Neutron::Port resources via a single resource in a master
5298 ResourceGroup may be used in ONAP to simplify the structure of a Heat
5299 template that creates multiple instances of the same VM type.
5301 However, there are important caveats to be aware of:
5303 ResourceGroup does not deal with structured parameters
5304 (comma-delimited-list and json) as one might typically expect. In
5305 particular, when using a list-based parameter, where each list element
5306 corresponds to one instance of the ResourceGroup, it is not possible to
5307 use the intrinsic “loop variable” %index% in the ResourceGroup
5310 For instance, the following is **not** valid Heat for ResourceGroup:
5312 .. code-block:: yaml
5314 type: OS::Heat::ResourceGroup
5316 type: my_nested_vm_template.yaml
5318 name: {get_param: [vm_name_list, %index%]}
5320 Although this appears to use the nth entry of the vm\_name\_list list
5321 for the nth element of the ResourceGroup, it will in fact result in a
5322 Heat exception. When parameters are provided as a list (one for each
5323 element of a ResourceGroup), you must pass the complete parameter to the
5324 nested template along with the current index as separate parameters.
5326 Below is an example of an **acceptable** Heat Syntax for a
5329 .. code-block:: yaml
5331 type: OS::Heat::ResourceGroup
5333 type: my_nested_vm_template.yaml
5335 names: {get_param: vm_name_list}
5338 You can then reference within the nested template as:
5340 { get\_param: [names, {get\_param: index} ] }
5342 ResourceGroup Property count
5343 ____________________________
5345 ONAP requires that the OS::Heat::ResourceGroup property count be defined
5346 (even if the value is one) and that the value must be enumerated in the
5347 environment file. This is required for ONAP to build the TOSCA model for
5350 .. code-block:: yaml
5352 type: OS::Heat::ResourceGroup
5354 count: { get_param: count }
5357 type: my_nested_vm_template.yaml
5359 names: {get_param: vm_name_list}
5362 Availability Zone and ResourceGroups
5363 ____________________________________
5365 The resource OS::Heat::ResourceGroup and the property availability\_zone
5366 has been an “issue” with a few VNFs since ONAP only supports
5367 availability\_zone as a string parameter and not a
5368 comma\_delimited\_list. This makes it difficult to use a ResourceGroup
5369 to create Virtual Machines in more than one availability zone.
5371 There are numerous solutions to this issue. Below are two suggested
5374 **Option 1:** create a CDL in the OS::Heat::ResourceGroup. In the
5375 resource type: OS::Heat::ResourceGroup, create a comma\_delimited\_list
5376 availability\_zones by using the intrinsic function list\_join.
5378 .. code-block:: yaml
5381 type: OS::Heat::ResourceGroup
5383 count: { get_param: node_count }
5389 avaialability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] }
5393 .. code-block:: yaml
5396 avaialability_zones:
5397 type: comma_delimited_list
5402 type: OS::Nova::Server
5404 name: { get_param: [ dns_names, get_param: index ] }
5405 image: { get_param: dns_image_name }
5406 flavor: { get_param: dns_flavor_name }
5407 availability_zone: { get_param: [ avaialability_zones, get_param: index ] }
5410 **Option 2:** Create a resource group per availability zone. A separate
5411 OS::Heat::ResourceGroup is created for each availability zone.
5416 Heat templates *should not* reference any HTTP-based resource
5417 definitions, any HTTP-based nested configurations, or any HTTP-based
5420 - During orchestration, ONAP *should not* retrieve any such resources
5421 from external/untrusted/unknown sources.
5423 - VNF images should not contain such references in user-data or other
5424 configuration/operational scripts that are specified via Heat or
5425 encoded into the VNF image itself.
5427 *Note:* HTTP-based references are acceptable if the HTTP-based reference
5428 is accessing information with the VM private/internal network.
5430 Heat Files Support (get\_file)
5431 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5433 Heat Templates may contain the inclusion of text files into Heat
5434 templates via the Heat get\_file directive. This may be used, for
5435 example, to define a common “user-data” script, or to inject files into
5436 a VM on startup via the “personality” property.
5438 Support for Heat Files is subject to the following limitations:
5440 R-76718 The VNF Heat Orchestration Template **MUST** reference the get\_files targets in
5441 Heat templates by file name, and the corresponding files should be
5442 delivered to ONAP along with the Heat templates.
5444 R-41888 The VNE Heat **MUST NOT** use URL-based file retrieval.
5446 R-62177 The VNF Heat Orchestration Template **MUST** have unique file names for the included
5447 files within the scope of the VNF.
5449 R-87848 The VNF Heat Orchestration Template **MUST** have all included files in a single, flat
5450 directory per VNF. ONAP does not support a directory hierarchy.
5452 - Included files may be used by all Modules within a given VNF.
5454 - get\_file directives may be used in both non-nested and nested
5460 When Nova Servers are created via Heat templates, they may be passed a
5461 “keypair” which provides an ssh key to the ‘root’ login on the newly
5462 created VM. This is often done so that an initial root key/password does
5463 not need to be hard-coded into the image.
5465 Key pairs are unusual in OpenStack, because they are the one resource
5466 that is owned by an OpenStack User as opposed to being owned by an
5467 OpenStack Tenant. As a result, they are usable only by the User that
5468 created the keypair. This causes a problem when a Heat template attempts
5469 to reference a keypair by name, because it assumes that the keypair was
5470 previously created by a specific ONAP user ID.
5472 When a keypair is assigned to a server, the SSH public-key is
5473 provisioned on the VMs at instantiation time. They keypair itself is not
5474 referenced further by the VM (i.e. if the keypair is updated with a new
5475 public key, it would only apply to subsequent VMs created with that
5478 Due to this behavior, the recommended usage of keypairs is in a more
5479 generic manner which does not require the pre-requisite creation of a
5480 keypair. The Heat should be structured in such a way as to:
5482 - Pass a public key as a parameter value instead of a keypair name
5484 - Create a new keypair within The VNF Heat Orchestration Template (in the base
5485 module) for use within that VNF
5487 By following this approach, the end result is the same as pre-creating
5488 the keypair using the public key – i.e., that public key will be
5489 provisioned in the new VM. However, this recommended approach also makes
5490 sure that a known public key is supplied (instead of having OpenStack
5491 generate a public/private pair to be saved and tracked outside of ONAP).
5492 It also removes any access/ownership issues over the created keypair.
5494 The public keys may be enumerated as a VNF Orchestration Constant in the
5495 environment file (since it is public, it is not a secret key), or passed
5496 at run-time as instance-specific parameters. ONAP will never
5497 automatically assign a public/private key pair.
5499 *Example (create keypair with an existing ssh public-key for {vm-type}
5500 of lb (for load balancer)):*
5502 .. code-block:: yaml
5512 type: OS::Nova::Keypair
5516 template: VNF_NAME_key_pair
5518 VNF_NAME: { get_param: vnf_name }
5519 public_key: {get_param: lb_ssh_public_key}
5520 save_private_key: false
5525 OpenStack allows a tenant to create Security groups and define rules
5526 within the security groups.
5528 Security groups, with their rules, may either be created in the Heat
5529 Orchestration Template or they can be pre-created in OpenStack and
5530 referenced within the Heat template via parameter(s). There can be a
5531 different approach for security groups assigned to ports on internal
5532 (intra-VNF) networks or external networks (inter-VNF). Furthermore,
5533 there can be a common security group across all VMs for a specific
5534 network or it can vary by VM (i.e., {vm-type}) and network type (i.e.,
5537 Anti-Affinity and Affinity Rules
5538 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5540 Anti-affinity or affinity rules are supported using normal OpenStack
5541 OS::Nova::ServerGroup resources. Separate ServerGroups are typically
5542 created for each VM type to prevent them from residing on the same host,
5543 but they can be applied to multiple VM types to extend the
5544 affinity/anti-affinity across related VM types as well.
5548 In this example, the {network-role} has been defined as oam to represent
5549 an oam network and the {vm-type} have been defined as lb for load
5550 balancer and db for database.
5552 .. code-block:: yaml
5556 type: OS::Nova::ServerGroup
5561 $vnf_name: {get_param: vnf_name}
5562 template: $vnf_name-server_group1
5567 type: OS::Nova::ServerGroup
5572 $vnf_name: {get_param: vnf_name}
5573 template: $vnf_name-server_group2
5578 type: OS::Nova::Server
5582 group: {get_resource: db_server_group}
5585 type: OS::Nova::Server
5589 group: {get_resource: db_server_group}
5592 type: OS::Nova::Server
5596 group: {get_resource: lb_server_group}
5598 Resource Data Synchronization
5599 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5601 For cases where synchronization is required in the orchestration of Heat
5602 resources, two approaches are recommended:
5604 - Standard Heat depends\_on property for resources
5606 - Assures that one resource completes before the dependent resource
5609 - Definition of completeness to OpenStack may not be sufficient
5610 (e.g., a VM is considered complete by OpenStack when it is ready
5611 to be booted, not when the application is up and running).
5613 - Use of Heat Notifications
5615 - Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle
5618 - Pre-requisite resources issue *wc\_notify* commands in user\_data.
5620 - Dependent resource define depends\_on in the
5621 OS::Heat::WaitCondition resource.
5623 *Example: “depends\_on” case*
5625 In this example, the {network-role} has been defined as oam to represent
5626 an oam network and the {vm-type} has been defined as oam to represent an
5629 .. code-block:: yaml
5633 type: OS::Nova::Server
5635 name: {get_param: [oam_ names, 0]}
5636 image: {get_param: oam_image_name}
5637 flavor: {get_param: oam_flavor_name}
5638 availability_zone: {get_param: availability_zone_0}
5640 - port: {get_resource: oam01_port_0}
5641 - port: {get_resource: oam01_port_1}
5643 scheduler_hints: {group: {get_resource: oam_servergroup}}
5644 user_data_format: RAW
5647 type: OS::Neutron::Port
5649 network: {get_resource: oam_net_name}
5650 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}]
5651 security_groups: [{get_resource: oam_security_group}]
5654 type: OS::Neutron::Port
5656 network: {get_param: oam_net_name}
5657 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}]
5658 security_groups: [{get_resource: oam_security_group}]
5660 oam_01_vol_attachment:
5661 type: OS::Cinder::VolumeAttachment
5662 depends_on: oam_server_01
5664 volume_id: {get_param: oam_vol_1}
5665 mountpoint: /dev/vdb
5666 instance_uuid: {get_resource: oam_server_01}
5671 VNF/VM parameters may include availability zone IDs for VNFs that
5672 require high availability.
5674 The Heat must comply with the following requirements to specific
5675 availability zone IDs:
5677 - The Heat template should spread Nova and Cinder resources across the
5678 availability zones as desired
5680 Post Orchestration & VNF Configuration
5681 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5683 Heat templates should contain a minimum amount of post-orchestration
5684 configuration data. For instance, *do not* embed complex user-data
5685 scripts in the template with large numbers of configuration parameters
5686 to the Heat template.
5688 - VNFs may provide configuration APIs for use after VNF creation. Such
5689 APIs will be invoked via application and/or SDN controllers.
5691 *Note:* It is important to follow this convention to the extent possible
5692 even in the short-term as of the long-term direction.
5694 VNFM Driver Development Steps
5695 -----------------------------------------------------------
5697 Refer to the ONAP documentation for VNF Provider instructions on integrating
5698 vendor-specific VNFM adaptors with VF-C. The VNF driver development steps are
5701 1. Use the VNF SDK tools to design the VNF with TOSCA models to output
5702 the VNF TOSCA package. Using the VNF SDK tools, the VNF package can be
5703 validated and tested.
5705 2. The VNF Provider supplies a vendor-specific VNFM driver in ONAP, which
5706 is a microservice providing a translation interface from VF-C to
5707 the vendor-specific VNFM. The interface definitions of vendor-specific
5708 VNFM adaptors are supplied by the VNF Providers themselves.
5710 Creating Vendor-Specific VNFM Adaptor Microservices
5711 ------------------------------------------------------------------------------------------------
5713 VNFs can be managed by vendor-specific VNFMs. To add a vendor-specific
5714 VNFM to ONAP, a vendor-specific VNFM adaptor is added to ONAP implementing
5715 the interface of the vendor-specific VNFM.
5717 A vendor-specific VNFM adaptor is a microservice with a unique name and
5718 an appointed port. When started up, the vendor-specific VNFM adaptor
5719 microservice is automatically registered to the Microservices Bus (MSB).
5720 The following RESTful example describes the scenario of registering a
5721 vendor-specific VNFM adaptor to MSB:
5723 .. code-block:: java
5725 POST /api/microservices/v1/services
5727 "serviceName": "catalog",
5729 "url": "/api/catalog/v1",
5734 "ip": "10.74.56.36",
Code Review / vnfrqts / requirements.git / blob