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 with aggreed
132 changes from ETSI SOL001 draft.
134 +---------------------+------------------------------------+-----------------+
135 | **ETSI NFV Element**| **TOSCA VNFD** | **Derived from**|
137 | **[IFA011]** | **[TOSCA-Simple-Profile-NFV-v1.0]**| |
138 +=====================+====================================+=================+
139 | VNF | tosca.nodes.nfv.VNF | tosca.nodes.Root|
140 +---------------------+------------------------------------+-----------------+
141 | Cpd (Connection | tosca.nodes.nfv.Cp | tosca.nodes.Root|
142 | Point) | tosca.nodes.nfv.Cp | tosca.nodes.Root|
143 +---------------------+------------------------------------+-----------------+
144 | VduCpd (internal | tosca.nodes.nfv.VduCp | tosca.nodes.\ |
145 | connection point) | | nfv.Cp |
146 +---------------------+------------------------------------+-----------------+
147 | VnfVirtualLinkDesc | tosca.nodes.nfv.VnfVirtualLink | tosca.nodes.Root|
148 | (Virtual Link) | | |
149 +---------------------+------------------------------------+-----------------+
150 | VDU Virtual Storage | tosca.nodes.nfv.VDU.VirtualStorage | tosca.nodes.Root|
151 +---------------------+------------------------------------+-----------------+
152 | VDU Virtual Compute | tosca.nodes.nfv.VDU.Compute | tosca.nodes.Root|
153 +---------------------+------------------------------------+-----------------+
154 | Software Image | | |
155 +---------------------+------------------------------------+-----------------+
156 | Deployment Flavour | | |
157 +---------------------+------------------------------------+-----------------+
158 | Scaling Aspect | | |
159 +---------------------+------------------------------------+-----------------+
160 | Element Group | | |
161 +---------------------+------------------------------------+-----------------+
162 | Instantiation | | |
164 +---------------------+------------------------------------+-----------------+
167 +--------------------------------------------------------------------+
168 | +--------------------------------------------------------------+ |
169 | | tosca\_definitions\_version: tosca\_simple\_yaml\_1\_0 | |
171 | | description: VNFD TOSCA file demo | |
175 | | - TOSCA\_definition\_nfv\_1\_0.yaml | |
177 | | - TOSCA\_definition\_nfv\_ext\_1\_0.yaml | |
179 | | | **node\_types: | |
180 | | tosca.nodes.nfv.VNF.vOpenNAT: | |
181 | | derived\_from:** tosca.nodes.nfv.VNF | |
182 | | | **requirements: | |
183 | | **- **sriov\_plane: | |
184 | | capability:** tosca.capabilities.nfv.VirtualLinkable | |
185 | | | **node:** tosca.nodes.nfv.VnfVirtualLinkDesc | |
186 | | | **relationship:** tosca.relationships.nfv.VirtualLinksTo | |
187 | +--------------------------------------------------------------+ |
188 +====================================================================+
189 +--------------------------------------------------------------------+
194 1. SR-IOV Passthrought
196 Definitions of SRIOV\_Port are necessary if VDU supports SR-IOV. Here is
199 +------------------------------------------------+
208 | tosca\_name: SRIOV\_Port |
212 | virtual\_network\_interface\_requirements: |
216 | support\_mandatory: false |
218 | description: sriov |
226 | description: sriov port |
228 | layer\_protocol: ipv4 |
232 | - virtual\_binding: |
234 | capability: virtual\_binding |
240 | type: tosca.relationships.nfv.VirtualBindsTo |
244 | node: tosca.nodes.Root |
246 | type: tosca.nodes.nfv.VduCpd |
248 | substitution\_mappings: |
258 | node\_type: tosca.nodes.nfv.VNF.vOpenNAT |
259 +------------------------------------------------+
263 Definitions of mem\_page\_size as one property shall be added to
264 Properties and set the value to large if one VDU node supports
265 huagepages. Here is an example.
267 +----------------------------------+
276 | tosca\_name: Huge\_pages\_demo |
280 | mem\_page\_size:large |
281 +==================================+
282 +----------------------------------+
286 Likewise, we shall add definitions of numa to
287 requested\_additional\_capabilities if we wand VUD nodes to support
288 NUMA. Here is an example.
290 +-------------------------------------------------+
291 | topology\_template: |
299 | virtual\_compute: |
305 | numa\_enabled: true |
307 | virtual\_mem\_size: 2 GB |
309 | requested\_additional\_capabilities: |
313 | support\_mandatory: true |
315 | requested\_additional\_capability\_name: numa |
317 | target\_performance\_parameters: |
319 | hw:numa\_nodes: "2" |
321 | hw:numa\_cpus.0: "0,1" |
323 | hw:numa\_mem.0: "1024" |
325 | hw:numa\_cpus.1: "2,3,4,5" |
327 | hw:numa\_mem.1: "1024" |
328 +-------------------------------------------------+
332 Definitions of Hyper-Theading are necessary as one of
333 requested\_additional\_capabilities of one VUD node if that node
334 supports Hyper-Theading. Here is an example.
336 +-------------------------------------------------------------+
337 | topology\_template: |
345 | virtual\_compute: |
351 | numa\_enabled: true |
353 | virtual\_mem\_size: 2 GB |
355 | requested\_additional\_capabilities: |
357 | hyper\_threading: |
359 | support\_mandatory: true |
361 | requested\_additional\_capability\_name: hyper\_threading |
363 | target\_performance\_parameters: |
365 | hw:cpu\_sockets : "2" |
367 | hw:cpu\_threads : "2" |
369 | hw:cpu\_cores : "2" |
371 | hw:cpu\_threads\_policy: "isolate" |
372 +-------------------------------------------------------------+
376 Definitions of ovs\_dpdk are necessary as one of
377 requested\_additional\_capabilities of one VUD node if that node
378 supports dpdk. Here is an example.
380 +------------------------------------------------------+
381 | topology\_template: |
389 | virtual\_compute: |
395 | numa\_enabled: true |
397 | virtual\_mem\_size: 2 GB |
399 | requested\_additional\_capabilities: |
403 | support\_mandatory: true |
405 | requested\_additional\_capability\_name: ovs\_dpdk |
407 | target\_performance\_parameters: |
409 | sw:ovs\_dpdk: "true" |
410 +------------------------------------------------------+
412 NFV TOSCA Type Definition
413 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
415 tosca.capabilites.nfv.VirtualCompute
416 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
418 This capability is used with the properties specified in ETSI SOL001 draft.
420 tosca.nodes.nfv.VDU.Compute
421 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
423 The NFV Virtualization Deployment Unit (VDU) compute node type
424 represents a VDU entity which it describes the deployment and
425 operational behavior of a VNF component (VNFC), as defined by **[ETSI
428 +-----------------------+-------------------------------+
429 | Shorthand Name | VDU.Compute |
430 +=======================+===============================+
431 | Type Qualified Name | tosca:VDU.Compute |
432 +-----------------------+-------------------------------+
433 | Type URI | tosca.nodes.nfv.VDU.Compute |
434 +-----------------------+-------------------------------+
435 | derived\_from | tosca.nodes.Compute |
436 +-----------------------+-------------------------------+
449 +------------+--------------------+------------+------------------------------+
450 | Name | Type | Constraints| Description |
451 +============+====================+============+==============================+
452 | virtual\ | tosca.\ | | Describes virtual compute |
453 | _compute | capabilities.nfv.\ | | resources capabilities. |
454 | | VirtualCompute | | |
455 +------------+--------------------+------------+------------------------------+
456 | monitoring\| tosca.\ | None | Monitoring parameter, which |
457 | _parameter | capabilities.nfv.\ | | can be tracked for a VNFC |
458 | | Metric | | based on this VDU |
460 | | | | Examples include: |
461 | | | | memory-consumption, |
462 | | | | CPU-utilisation, |
463 | | | | bandwidth-consumption, VNFC |
464 | | | | downtime, etc. |
465 +------------+--------------------+------------+------------------------------+
466 | Virtual\ | tosca.\ | | Defines ability of |
467 | _binding | capabilities.nfv.\ | | VirtualBindable |
468 | | VirtualBindable | | |
470 | | editor note: need | | |
471 | | to create a | | |
472 | | capability type | | |
473 +------------+--------------------+------------+------------------------------+
478 +-----------------------------------------------------------------------------+
479 | tosca.nodes.nfv.VDU.Compute: |
481 | derived\_from: tosca.nodes.Compute |
499 | type: list # explicit index (boot index) not necessary, contrary to IFA011 |
507 | nfvi\_constraints: |
517 | configurable\_properties: |
523 | type: tosca.datatypes.nfv.VnfcConfigurableProperties |
529 | private\_address: |
531 | status: deprecated |
535 | status: deprecated |
539 | status: deprecated |
543 | status: deprecated |
547 | virtual\_compute: |
549 | type: tosca.capabilities.nfv.VirtualCompute |
551 | virtual\_binding: |
553 | type: tosca.capabilities.nfv.VirtualBindable |
555 | #monitoring\_parameter: |
557 | # modeled as ad hoc (named) capabilities in VDU node template |
563 | # cpu\_load: tosca.capabilities.nfv.Metric |
565 | # memory\_usage: tosca.capabilities.nfv.Metric |
567 | host: #Editor note: FFS. How this capabilities should be used in NFV Profile|
569 | type: `*tosca.capabilities.Container* <#DEFN_TYPE_CAPABILITIES_CONTAINER>`__|
571 | valid\_source\_types: |
572 | [`*tosca.nodes.SoftwareComponent* <#DEFN_TYPE_NODES_SOFTWARE_COMPONENT>`__] |
574 | occurrences: [0,UNBOUNDED] |
578 | occurrences: [0,0] |
582 | occurrences: [0,0] |
585 | #Editor note: FFS. How this capabilities should be used in NFV Profile |
587 | type: `*tosca.capabilities.Scalable* <#DEFN_TYPE_CAPABILITIES_SCALABLE>`__ |
591 | occurrences: [0,UNBOUND] |
595 | - virtual\_storage: |
597 | capability: tosca.capabilities.nfv.VirtualStorage |
599 | relationship: tosca.relationships.nfv.VDU.AttachedTo |
601 | node: tosca.nodes.nfv.VDU.VirtualStorage |
603 | occurences: [ 0, UNBOUNDED ] |
605 | - local\_storage: #For NFV Profile, this requirement is deprecated. |
607 | occurrences: [0,0] |
615 | type: tosca.artifacts.nfv.SwImage |
616 +-----------------------------------------------------------------------------+
621 Note: currently not supported.
623 +--------+---------+----------------+------------+------------------------+
624 | Name | Required| Type | Constraints| Description |
625 +========+=========+================+============+========================+
626 | SwImage| Yes | tosca.\ | | Describes the software |
627 | | | artifacts.nfv.\| | image which is directly|
628 | | | SwImage | | realizing this virtual |
630 +--------+---------+----------------+------------+------------------------+
637 tosca.nodes.nfv.VDU.VirtualStorage
638 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
640 The NFV VirtualStorage node type represents a virtual storage entity
641 which it describes the deployment and operational behavior of a virtual
642 storage resources, as defined by **[ETSI NFV IFA011].**
644 **[editor note]** open issue: should NFV profile use the current storage
645 model as described in YAML 1.1. Pending on Shitao proposal (see
646 NFVIFA(17)000110 discussion paper)
648 **[editor note]** new relationship type as suggested in Matt
649 presentation. Slide 8. With specific rules of “valid\_target\_type”
651 +---------------------------+--------------------------------------+
652 | **Shorthand Name** | VirtualStorage |
653 +===========================+======================================+
654 | **Type Qualified Name** | tosca: VirtualStorage |
655 +---------------------------+--------------------------------------+
656 | **Type URI** | tosca.nodes.nfv.VDU.VirtualStorage |
657 +---------------------------+--------------------------------------+
658 | **derived\_from** | tosca.nodes.Root |
659 +---------------------------+--------------------------------------+
661 tosca.artifacts.nfv.SwImage
662 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
664 +---------------------------+------------------------------------+
665 | **Shorthand Name** | SwImage |
666 +===========================+====================================+
667 | **Type Qualified Name** | tosca:SwImage |
668 +---------------------------+------------------------------------+
669 | **Type URI** | tosca.artifacts.nfv.SwImage |
670 +---------------------------+------------------------------------+
671 | **derived\_from** | tosca.artifacts.Deployment.Image |
672 +---------------------------+------------------------------------+
677 +-----------------+---------+----------+------------+-------------------------+
678 | Name | Required| Type | Constraints| Description |
679 +=================+=========+==========+============+=========================+
680 | name | yes | string | | Name of this software |
682 +-----------------+---------+----------+------------+-------------------------+
683 | version | yes | string | | Version of this software|
685 +-----------------+---------+----------+------------+-------------------------+
686 | checksum | yes | string | | Checksum of the software|
687 | | | | | image file |
688 +-----------------+---------+----------+------------+-------------------------+
689 | container\ | yes | string | | The container format |
690 | _format | | | | describes the container |
691 | | | | | file format in which |
692 | | | | | software image is |
693 | | | | | provided. |
694 +-----------------+---------+----------+------------+-------------------------+
695 | disk\_format | yes | string | | The disk format of a |
696 | | | | | software image is the |
697 | | | | | format of the underlying|
698 | | | | | disk image |
699 +-----------------+---------+----------+------------+-------------------------+
700 | min\_disk | yes | scalar-\ | | The minimal disk size |
701 | | | unit.size| | requirement for this |
702 | | | | | software image. |
703 +-----------------+---------+----------+------------+-------------------------+
704 | min\_ram | no | scalar-\ | | The minimal RAM |
705 | | | unit.size| | requirement for this |
706 | | | | | software image. |
707 +-----------------+---------+----------+------------+-------------------------+
708 | Size | yes | scalar-\ | | The size of this |
709 | | | unit.size| | software image |
710 +-----------------+---------+----------+------------+-------------------------+
711 | sw\_image | yes | string | | A reference to the |
712 | | | | | actual software image |
713 | | | | | within VNF Package, or |
715 +-----------------+---------+----------+------------+-------------------------+
716 | operating\ | no | string | | Identifies the operating|
717 | _system | | | | system used in the |
718 | | | | | software image. |
719 +-----------------+---------+----------+------------+-------------------------+
720 | supported\ | no | list | | Identifies the |
721 | _virtualization\| | | | virtualization |
722 | _enviroment | | | | environments (e.g. |
723 | | | | | hypervisor) compatible |
724 | | | | | with this software image|
725 +-----------------+---------+----------+------------+-------------------------+
730 +-----------------------------------------------------+
731 | tosca.artifacts.nfv.SwImage: |
733 | derived\_from: tosca.artifacts.Deployment.Image |
735 | properties or metadata: |
759 | container\_format: |
773 | type: scalar-unit.size # Number |
779 | type: scalar-unit.size # Number |
785 | type: scalar-unit.size # Number |
795 | operating\_system: |
801 | supported\_virtualisation\_environments: |
810 +-----------------------------------------------------+
812 .. |image1| image:: Image1.png
815 .. |image2| image:: Image2.png
825 This section contains general Heat Orchestration Template guidelines.
830 R-95303 A VNF's Heat Orchestration Template **MUST** be defined using valid YAML.
833 Markup Language) is a human friendly data serialization standard for all
834 programming languages. See http://www.yaml.org/.
836 Heat Orchestration Template Format
837 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
839 As stated above, Heat Orchestration templates must be defined in YAML.
843 - Tabs are not allowed, use spaces ONLY
845 - You must indent your properties and lists with 1 or more spaces
847 - All Resource IDs and resource property parameters are case-sensitive. (e.g., "ThIs", is not the same as "thiS")
849 Heat Orchestration Template Structure
850 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
852 Heat Orchestration template structure follows the following format,
853 as defined by OpenStack at
854 https://docs.openstack.org/developer/heat/template_guide/hot_spec.html
856 .. code-block:: python
858 heat_template_version: <date>
861 # a description of the template
864 # a declaration of input parameter groups and order
867 # declaration of input parameters
870 # declaration of template resources
873 # declaration of output parameters
876 # declaration of conditions
878 heat_template_version
879 +++++++++++++++++++++
881 R-27078 A VNF's Heat Orchestration template **MUST** contain
882 the section "heat_template_version:".
884 The section "heat_template_version:" must be set to a date
885 that is supported by the OpenStack environment.
890 R-39402 A VNF's Heat Orchestration Template **MUST**
891 contain the section "description:".
896 A VNF Heat Orchestration template may
897 contain the section "parameter_groups:".
902 R-35414 A VNF Heat Orchestration's template **MUST**
903 contain the section "parameters:".
906 .. code-block:: python
912 type: <string | number | json | comma_delimited_list | boolean>
914 label: <human-readable name of the parameter>
916 description: <description of the parameter>
918 default: <default value for parameter>
920 hidden: <true | false>
924 <parameter constraints>
926 immutable: <true | false>
928 This section allows for
929 specifying input parameters that have to be provided when instantiating
930 the template. Each parameter is specified in a separate nested block
931 with the name of the parameters defined in the first line and additional
932 attributes (e.g., type, label) defined as nested elements.
934 R-90279 A VNF Heat Orchestration's template's parameter **MUST**
935 be used in a resource with the exception of the parameters
936 for the OS::Nova::Server resource property availability_zone.
938 R-91273 A VNF Heat Orchestration’s template’s parameter for
939 the OS::Nova::Server resource property availability_zone
940 **MAY NOT** be used in any OS::Nova::Resource.
945 The name of the parameter.
947 R-25877 A VNF's Heat Orchestration Template's parameter
948 name (i.e., <param name>) **MUST** contain only
949 alphanumeric characters and underscores ('_').
954 R-36772 A VNF’s Heat Orchestration Template’s parameter
955 **MUST** include the attribute “type:”.
957 R-11441 A VNF’s Heat Orchestration Template’s parameter
958 type **MUST** be one of the following values: "string",
959 "number", "json", "comma_delimited_list" or "boolean".
964 R-32094 A VNF's Heat Orchestration Template parameter
965 declaration **MAY** contain the attribute "label:"
970 R-44001 A VNF's Heat Orchestration Template parameter
971 declaration **MUST** contain the attribute "description".
973 Note that the parameter attribute “description:” is an
974 OpenStack optional attribute that provides a description
975 of the parameter. ONAP implementation requires this attribute.
980 R-90526 A VNF Heat Orchestration Template parameter
981 declaration **MUST** not contain the default attribute.
983 R-26124 If a VNF Heat Orchestration Template parameter
984 requires a default value, it **MUST** be enumerated in the environment file.
986 Note that the parameter attribute “default:” is an OpenStack
987 optional attribute that declares the default value of the
988 parameter. ONAP implementation prohibits the use of this attribute.
993 R-32557 A VNF's Heat Orchestration Template parameter
994 declaration MAY contain the attribute "hidden:".
996 The parameter attribute "hidden:" is an OpenStack optional
997 attribute that defines whether the parameters should be
998 hidden when a user requests information about a stack
999 created from the template. This attribute can be used
1000 to hide passwords specified as parameters.
1005 The parameter attribute "constraints:" is an OpenStack optional
1006 attribute that defines a list of constraints to apply to the parameter.
1008 R-88863 A VNF's Heat Orchestration Template's parameter defined as
1009 type "number" **MUST** have a parameter constraint of "range" or
1010 "allowed_values" defined.
1012 R-40518 A VNF's Heat Orchestration Template’s parameter defined as
1013 type "string" **MAY** have a parameter constraint defined.
1015 R-96227 A VNF's Heat Orchestration Template’s parameter defined as
1016 type "json" **MAY** have a parameter constraint defined.
1018 R-79817 A VNF's Heat Orchestration Template’s parameter defined as
1019 type "comma_delimited_list" **MAY** have a parameter constraint defined.
1021 R-06613 A VNF's Heat Orchestration Template’s parameter defined as
1022 type "boolean" **MAY** have a parameter constraint defined.
1024 R-00011 A VNF's Heat Orchestration Template's Nested YAML files
1025 parameter's **MUST NOT** have a parameter constraint defined.
1027 The constraints block of a parameter definition defines additional
1028 validation constraints that apply to the value of the parameter.
1029 The parameter values provided in the VNF Heat Orchestration Template
1030 are validated against the constraints at instantiation time.
1031 The stack creation fails if the parameter value doesn’t comply to the constraints.
1033 The constraints are defined as a list with the following syntax
1035 .. code-block:: python
1039 <constraint type>: <constraint definition>
1041 description: <constraint description>
1045 **<constraint type>** Provides the type of constraint to apply.
1046 The list of OpenStack supported constraints can be found at
1047 https://docs.openstack.org/heat/latest/template_guide/hot_spec.html .
1049 **<constraint definition>** provides the actual constraint.
1050 The syntax and constraint is dependent of the <constraint type> used.
1052 **description** is an optional attribute that provides a description of the
1053 constraint. The text is presented to the user when the value the user
1054 defines violates the constraint. If omitted, a default validation
1055 message is presented to the user.
1057 Below is a brief overview of the "range" and "allowed values" constraints.
1058 For complete details on constraints, see
1059 https://docs.openstack.org/heat/latest/template_guide/hot_spec.html#parameter-constraints
1063 range: The range constraint applies to parameters of type: number.
1064 It defines a lower and upper limit for the numeric value of the
1065 parameter. The syntax of the range constraint is
1067 .. code-block:: python
1069 range: { min: <lower limit>, max: <upper limit> }
1073 It is possible to define a range constraint with only a lower
1074 limit or an upper limit.
1078 allowed_values: The allowed_values constraint applies to parameters of
1079 type \"string\" or type \"number\". It specifies a set of possible
1080 values for a parameter. At deployment time, the user-provided value
1081 for the respective parameter must match one of the elements of the
1082 list. The syntax of the allowed_values constraint is
1084 .. code-block:: python
1086 allowed_values: [ <value>, <value>, ... ]
1088 Alternatively, the following YAML list notation can be used
1103 R-22589 A VNF’s Heat Orchestration Template parameter declaration
1104 **MAY** contain the attribute "immutable:".
1106 The parameter attribute \"immutable:\" is an OpenStack optional
1107 attribute that defines whether the parameter is updatable. A Heat
1108 Orchestration Template stack update fails if immutable is set to
1109 true and the parameter value is changed. This attribute
1110 \"immutable:\" defaults to false.
1115 R-23664 A VNF's Heat Orchestration template **MUST** contain
1116 the section "resources:".
1118 R-90152 A VNF's Heat Orchestration Template's "resources:"
1119 section **MUST** contain the declaration of at least one resource.
1121 R-40551 A VNF's Heat Orchestration Template's Nested YAML files
1122 **MAY** contain the section "resources:".
1124 Each resource is defined as a
1125 separate block in the resources section with the following syntax.
1127 .. code-block:: python
1133 type: <resource type>
1137 <property name>: <property value>
1141 <resource specific metadata>
1143 depends_on: <resource ID or list of ID>
1145 update_policy: <update policy>
1147 deletion_policy: <deletion policy>
1149 external_id: <external resource ID>
1151 condition: <condition name or expression or boolean>
1158 R-75141 A VNF's Heat Orchestration Template's resource name
1159 (i.e., <resource ID>) **MUST** only contain alphanumeric
1160 characters and underscores ('_').
1162 R-16447 A VNF's <resource ID> **MUST** be unique across all
1163 Heat Orchestration Templates and all HEAT Orchestration Template
1164 Nested YAML files that are used to create the VNF.
1166 Note that a VNF can be composed of one or more Heat Orchestration Templates.
1168 Note that OpenStack requires the <resource ID> to be unique to the
1169 Heat Orchestration Template and not unique across all Heat
1170 Orchestration Templates the compose the VNF.
1175 The resource attribute \"type:\" is an OpenStack required
1176 attribute that defines the resource type, such as
1177 OS::Nova::Server or OS::Neutron::Port.
1179 The resource attribute \"type:\" may specify a VNF HEAT
1180 Orchestration Template Nested YAML file.
1182 R-53952 A VNF’s Heat Orchestration Template’s Resource
1183 **MUST NOT** reference a HTTP-based resource definitions.
1185 R-71699 A VNF’s Heat Orchestration Template’s Resource
1186 **MUST NOT** reference a HTTP-based Nested YAML file.
1191 The resource attribute \"properties:\" is an OpenStack optional
1192 attribute that provides a list of resource-specific properties.
1193 The property value can be provided in place, or via a function
1194 (e.g., `Intrinsic functions <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-intrinsic-functions>`__).
1196 R-10834 If a VNF Heat Orchestration Template resource attribute
1197 "property:" uses a nested "get_param", one level of nesting is
1198 supported and the nested "get_param" **MUST** reference an index
1203 The resource attribute \"metadata:\" is an OpenStack optional attribute.
1205 R-97199 A VNF's Heat Orchestration Template's OS::Nova::Server
1206 resource **MUST** contain the attribute "metadata".
1208 Section 5.4 contains the OS::Nova::Server mandatory and optional metadata.
1214 The resource attribute \"depends_on:\" is an OpenStack optional
1216 See `OpenStack documentation <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-resources-dependencies>`__
1217 for additional details.
1219 R-46968 VNF’s Heat Orchestration Template’s Resource **MAY**
1220 declare the attribute “depends_on:”.
1225 R-63137 VNF’s Heat Orchestration Template’s Resource **MAY**
1226 declare the attribute “update_policy:”.
1231 R-43740 A VNF’s Heat Orchestration Template’s Resource
1232 **MAY** declare the attribute “deletion_policy:”.
1234 If specified, the \"deletion_policy:\" attribute for resources
1235 allows values 'Delete', 'Retain', and 'Snapshot'.
1236 Starting with heat_template_version 2016-10-14, lowercase
1237 equivalents are also allowed.
1239 The default policy is to delete the physical resource when
1240 deleting a resource from the stack.
1245 R-78569 A VNF’s Heat Orchestration Template’s Resouce **MAY**
1246 declare the attribute “external_id:”.
1248 This attribute allows for specifying the resource_id for an
1249 existing external (to the stack) resource. External resources
1250 cannot depend on other resources, but we allow other resources to
1251 depend on external resource. This attribute is optional.
1252 Note: when this is specified, properties will not be used for
1253 building the resource and the resource is not managed by Heat.
1254 This is not possible to update that attribute. Also,
1255 resource won’t be deleted by heat when stack is deleted.
1261 The resource attribute \"condition:\" is an OpenStack optional attribute.
1263 Support for the resource condition attribute was added
1264 in the Newton release of OpenStack.
1269 R-36982 A VNF’s Heat Orchestration template **MAY** contain the “outputs:” section.
1271 This section allows for specifying output parameters
1272 available to users once the template has been instantiated. If the
1273 section is specified, it will need to adhere to specific requirements.
1274 See `ONAP Parameter Classifications Overview`_ and
1275 `ONAP Output Parameter Names`_ for additional details.
1277 Environment File Format
1278 ~~~~~~~~~~~~~~~~~~~~~~~
1280 The environment file is a yaml text file.
1281 (https://docs.openstack.org/developer/heat/template_guide/environment.html)
1283 R-86285 The VNF Heat Orchestration Template **MUST** have a corresponding
1284 environment file, even if no parameters are required to be enumerated.
1286 The use of an environment file in OpenStack is optional.
1287 In ONAP, it is mandatory.
1289 R-03324 The VNF Heat Orchestration Template **MUST** contain the
1290 "parameters" section in the
1293 R-68198 A VNF’s Heat Orchestration template’s Environment File’s
1294 “parameters:” section **MAY** enumerate parameters.
1296 ONAP implementation requires the parameters section in the
1297 environmental file to be declared. The parameters section
1298 contains a list of key/value pairs.
1300 R-59930 A VNF’s Heat Orchestration template’s Environment
1301 File’s **MAY** contain the “parameter_defaults:” section.
1303 The “parameter_defaults:” section contains default parameters
1304 that are passed to all template resources.
1306 R-46096 A VNF’s Heat Orchestration template’s Environment File’s
1307 **MAY** contain the “encrypted_parameters:” section.
1309 The “encrypted_parameters:” section contains a list of encrypted parameters.
1311 R-24893 A VNF’s Heat Orchestration template’s Environment File’s
1312 **MAY** contain the “event_sinks:” section.
1314 The “event_sinks:” section contains the list of endpoints that would
1315 receive stack events.
1317 R-42685 A VNF’s Heat Orchestration template’s Environment File’s
1318 **MAY** contain the “parameter_merge_strategies:” section.
1320 The “parameter_merge_strategies:” section provides the merge strategies
1321 for merging parameters and parameter defaults from the environment file.
1323 R-67231 A VNF’s Heat Orchestration template’s Environment File’s **MUST NOT**
1324 contain the “resource_registry:” section.
1326 ONAP implementation does not support the Environment File resource_registry
1327 section. The resource_registry section allows for the definition of custom resources.
1330 SDC Treatment of Environment Files
1331 ++++++++++++++++++++++++++++++++++
1333 Parameter values enumerated in the environment file are used by SDC as
1334 the default value. However, the SDC user may use the SDC GUI to
1335 overwrite the default values in the environment file.
1337 SDC generates a new environment file for distribution to MSO based on
1338 the uploaded environment file and the user provided GUI updates. The
1339 user uploaded environment file is discarded when the new file is
1342 ONAP has requirements for what parameters must be enumerated in the
1343 environment file and what parameter must not be enumerated in the
1344 environment file. See `ONAP Parameter Classifications Overview`_ and
1345 `ONAP Resource ID and Parameter Naming Convention`_ for more details.
1347 ONAP Heat Orchestration Templates: Overview
1348 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1350 ONAP supports a modular Heat Orchestration Template design pattern,
1351 referred to as *VNF Modularity.*
1353 ONAP VNF Modularity Overview
1354 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1356 R-69663 A VNF **MAY** be composed from one or more Heat Orchestration
1357 Templates, each of which represents a subset of the overall VNF.
1359 The Heat Orchestration Templates can be thought of a components or
1360 modules of the VNF and are referred to as “\ *VNF Modules*\ ”.
1361 During orchestration, these modules are
1362 deployed incrementally to create the complete VNF.
1364 R-33132 A VNF’s Heat Orchestration Template **MAY** be 1.) Base Module
1365 Heat Orchestration Template (also referred to as a Base Module), 2.)
1366 Incremental Module Heat Orchestration Template (referred to as an Incremental
1367 Module), or 3.) a Cinder Volume Module Heat Orchestration Template
1368 (referred to as Cinder Volume Module).
1370 R-37028 The VNF **MUST** be composed of one “base” module.
1372 R-13196 A VNF **MAY** be composed of zero to many Incremental Modules
1374 R-20974 The VNF **MUST** deploy the base module first, prior to
1375 the incremental modules.
1377 R-28980 A VNF’s incremental module **MAY** be used for initial VNF
1380 R-86926 A VNF’s incremental module **MAY** be used for scale out only.
1382 A VNF’s Incremental Module that is used for scale out is deployed
1383 sometime after initial VNF deployment to add capacity.
1385 R-91497 A VNF’s incremental module **MAY** be used for both deployment
1388 R-68122 A VNF’s incremental module **MAY** be deployed more than once,
1389 either during initial VNF deployment and/or scale out.
1391 R-46119 A VNF’s Heat Orchestration Template’s Resource OS::Heat::CinderVolume
1392 **MAY** be defined in a Base Module.
1394 R-90748 A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume
1395 **MAY** be defined in an Incremental Module.
1397 R-03251 A VNF’s Heat Orchestration Template’s Resource OS::Cinder::Volume
1398 **MAY** be defined in a Cinder Volume Module.
1400 ONAP also supports the concept of an optional, independently deployed Cinder
1401 volume via a separate Heat Orchestration Templates, referred to as a Cinder
1402 Volume Module. This allows the volume to persist after a Virtual Machine
1403 (VM) (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused
1404 on another instance (e.g., during a failover activity).
1406 R-11200 The VNF **MUST** keep the scope of a Cinder volume module, when it
1407 exists, to be 1:1 with the VNF Base Module or Incremental Module
1409 It is strongly recommended that Cinder Volumes be created in a Cinder Volume
1412 R-38474 The VNF **MUST** have a corresponding environment file for a
1415 R-81725 The VNF **MUST** have a corresponding environment file for an
1418 R-53433 The VNF **MUST** have a corresponding environment file for a
1419 Cinder Volume Module.
1421 These concepts will be described in more detail throughout the document.
1422 This overview is provided to set the stage and help clarify the concepts
1423 that will be introduced.
1425 Nested Heat Orchestration Templates Overview
1426 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1428 ONAP supports nested Heat Orchestration Templates per OpenStack
1431 R-36582 A VNF’s Base Module **MAY** utilize nested heat.
1433 R-56721 A VNF’s Incremental Module **MAY** utilize nested heat.
1435 R-30395 A VNF’s Cinder Volume Module **MAY** utilize nested heat.
1437 Nested templates may be suitable for larger VNFs that contain many
1438 repeated instances of the same VM type(s). A common usage pattern is to
1439 create a nested template for each VM type along with its supporting
1440 resources. The Heat Orchestration Template may then reference these
1441 nested templates either statically (by repeated definition) or
1442 dynamically (via OS::Heat::ResourceGroup).
1444 See `Nested Heat Templates`_ for additional details.
1446 ONAP Heat Orchestration Template Filenames
1447 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1449 In order to enable ONAP to understand the relationship between Heat
1450 files, the following Heat file naming convention must be utilized.
1452 In the examples below, <text> represents any alphanumeric string that
1453 must not contain any special characters and must not contain the word
1456 R-87485 A VNF’s Heat Orchestration Template’s file extension **MUST**
1457 be in the lower case format ‘.yaml’ or ‘.yml’.
1459 R-56438 A VNF’s Heat Orchestration Template’s Nested YAML file extension
1460 **MUST** be in the lower case format ‘.yaml’ or ‘.yml’.
1462 R-74304 A VNF’s Heat Orchestration Template’s Environment file extension
1463 **MUST** be in the lower case format ‘.env’.
1468 R-81339 A VNF Heat Orchestration Template’s Base Module file name **MUST**
1469 include ‘base’ in the filename and **MUST** match one of the following four
1470 formats: 1.) ‘base_<text>.y[a]ml’, 2.) ‘<text>_base.y[a]ml’, 3.)
1471 ‘base.y[a]ml’, or 4.) ‘<text>_base_<text>’.y[a]ml; where ‘base’ is case
1472 insensitive and where ‘<text>’ **MUST** contain only alphanumeric characters
1473 and underscores ‘_’ and **MUST NOT** contain the case insensitive word ‘base’.
1475 R-91342 A VNF Heat Orchestration Template’s Base Module’s Environment File
1476 **MUST** be named identical to the VNF Heat Orchestration Template’s Base
1477 Module with ‘.y[a]ml’ replaced with ‘.env’.
1482 R-87247 A VNF Heat Orchestration Template’s Incremental Module file name
1483 **MUST** contain only alphanumeric characters and underscores ‘_’ and
1484 **MUST NOT** contain the case insensitive word ‘base’.
1486 R-94509 A VNF Heat Orchestration Template’s Incremental Module’s Environment
1487 File **MUST** be named identical to the VNF Heat Orchestration Template’s
1488 Incremental Module with ‘.y[a]ml’ replaced with ‘.env’.
1490 To clearly identify the incremental module, it is recommended to use the
1491 following naming options for modules:
1493 - module_<text>.y[a]ml
1495 - <text>_module.y[a]ml
1499 - <text>_module_<text>.y[a]ml
1501 Cinder Volume Modules
1502 +++++++++++++++++++++
1504 R-82732 A VNF Heat Orchestration Template’s Cinder Volume Module **MUST** be
1505 named identical to the base or incremental module it is supporting with
1508 R-31141 A VNF Heat Orchestration Template’s Cinder Volume Module’s Environment
1509 File **MUST** be named identical to the VNF Heat Orchestration Template’s
1510 Cinder Volume Module with .y[a]ml replaced with ‘.env’.
1515 R-76057 A VNF Heat Orchestration Template’s Nested YAML file name **MUST**
1516 contain only alphanumeric characters and underscores ‘_’ and **MUST NOT**
1517 contain the case insensitive word ‘base’.
1523 - nest_<text>.y[a]ml
1525 - <text>_nest.y[a]ml
1529 - <text>_nest_<text>.y[a]ml
1531 VNF Heat Orchestration Template's Nested YAML file does not have a
1532 corresponding environment files, per OpenStack specifications.
1534 R-18224 The VNF Heat Orchestration Template **MUST** pass in as properties
1535 all parameter values
1536 associated with the nested heat file in the resource definition defined
1537 in the parent heat template.
1542 The output parameters are parameters defined in the output section of a
1543 Heat Orchestration Template. The ONAP output parameters are subdivided
1544 into three categories:
1546 1. ONAP Base Module Output Parameters
1548 2. ONAP Volume Module Output Parameters
1550 3. ONAP Predefined Output Parameters.
1552 ONAP Base Module Output Parameters
1553 ++++++++++++++++++++++++++++++++++++
1555 ONAP Base Module Output Parameters are declared in the 'outputs:'' section of
1556 the VNF's Heat Orchestration Template's Base Module. A Base Module Output
1557 Parameter is available as an input parameter (i.e., declared in the
1558 'parameters:'' section) to all Incremental Modules in the VNF.
1560 A Base Module Output Parameter may be used as an input parameter in any
1561 incremental module in the VNF. Note that the parameter is not
1562 available to other VNFs.
1564 R-52753 VNF’s Heat Orchestration Template’s Base Module’s output parameter’s
1565 name and type **MUST** match the VNF’s Heat Orchestration Template’s
1566 incremental Module’s name and type unless the output parameter is of type
1567 ‘comma_delimited_list’, then the corresponding input parameter **MUST**
1568 be declared as type ‘json’.
1570 If the Output parameter has a comma_delimited_list value (e.g., a collection
1571 of UUIDs from a Resource Group), then the corresponding input parameter
1572 must be declared as type json and not a comma_delimited_list, which is
1573 actually a string value with embedded commas.
1575 R-22608 When a VNF’s Heat Orchestration Template’s Base Module’s output
1576 parameter is declared as an input parameter in an Incremental Module,
1577 the parameter attribute ‘constraints:’ **MUST NOT** be declared.
1579 Additional details on ONAP Base Module Output Parameters are provided in
1580 `ONAP Output Parameter Names`_ and ONAP VNF Modularity.
1582 ONAP Volume Module Output Parameters
1583 ++++++++++++++++++++++++++++++++++++
1585 R-89913 A VNF’s Heat Orchestration Template’s Cinder Volume Module Output
1586 Parameter(s) **MUST** include the UUID(s) of the Cinder Volumes created in
1587 template, while other Output Parameters **MAY** be included.
1589 A VNF’s Heat Orchestration Template’s Cinder Volume Module Output Parameter(s)
1590 are only available for the module (base or incremental) that the volume
1591 template is associated with.
1593 R-07443 A VNF’s Heat Orchestration Templates’ Cinder Volume Module Output
1594 Parameter’s name and type **MUST** match the input parameter name and type
1595 in the corresponding Base Module or Incremental Module unless the Output
1596 Parameter is of the type ‘comma_delimited_list’, then the corresponding input
1597 parameter **MUST** be declared as type ‘json’.
1599 If the Output parameter has a comma_delimited_list value (e.g., a collection
1600 of UUIDs from a Resource Group), then the corresponding input parameter must
1601 be declared as type json and not a comma_delimited_list, which is actually a
1602 string value with embedded commas.
1604 R-20547 When an ONAP Volume Module Output Parameter is declared as an input
1605 parameter in a base or an incremental module Heat Orchestration Template,
1606 parameter constraints **MUST NOT** be declared.
1608 Additional details on ONAP Base Module Output Parameters are provided in
1609 `ONAP Output Parameter Names`_ and `Cinder Volume Templates`_.
1611 ONAP Predefined Output Parameters
1612 +++++++++++++++++++++++++++++++++++
1614 ONAP will look for a small set of pre-defined Heat output parameters to
1615 capture resource attributes for inventory in ONAP. These output parameters
1616 are optional and currently only two parameters are supported. These output
1617 parameters are optional and are specified in `OAM Management IP Addresses`_.
1619 Support of heat stack update
1620 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1622 ONAP does not support the use of heat stack-update command for scaling
1625 R-39349 A VNF Heat Orchestration Template **MUST NOT** be designed to
1626 utilize the OpenStack ‘heat stack-update’ command for scaling
1629 R-43413 A VNF **MUST** utilize a modular Heat Orchestration Template
1630 design to support scaling (growth/de-growth).
1632 Scope of a Heat Orchestration Template
1633 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1635 R-59482 A VNF’s Heat Orchestration Template **MUST NOT** be VNF instance
1636 specific or Cloud site specific
1638 R-56750 A VNF’s Heat Orchestration Template’s parameter values that are
1639 constant across all deployments **MUST** be declared in a Heat Orchestration
1640 Template Environment File.
1642 ONAP provides the instance specific parameter values to the Heat
1643 Orchestration Template at orchestration time.
1645 R-01896 A VNF’s Heat Orchestration Template’s parameter values that are
1646 constant across all deployments **MUST** be declared in a Heat Orchestration
1647 Template Environment File.
1652 ONAP defines two types of networks: External Networks and Internal Networks.
1657 ONAP defines an external network in relation to the VNF and not with regard
1658 to the Network Cloud site. External networks may also be referred to as
1659 “inter-VNF” networks. An external network must connect VMs in a VNF to
1660 VMs in another VNF or an external gateway or external router.
1662 An External Network may be a Neutron Network or a Contrail Network.
1664 R-16968 A VNF’s Heat Orchestration Templates **MUST NOT** include heat
1665 resources to create external networks.
1667 External networks must be orchestrated separately, independent of the VNF.
1668 This allows the network to be shared by multiple VNFs and managed
1669 independently of VNFs.
1671 R-00606 A VNF **MAY** be connected to zero, one or more than one external
1674 R-57424 A VNF’s port connected to an external network **MUST** connect the
1675 port to VMs in another VNF and/or an external gateway and/or external router.
1677 R-29865 A VNF’s port connected to an external network **MUST NOT** connect
1678 the port to VMs in the same VNF.
1680 R-69014 When a VNF connects to an external network, a network role, referred
1681 to as the ‘{network-role}’ **MUST** be assigned to the external network
1682 for use in the VNF’s Heat Orchestration Template.
1684 R-05201 When a VNF connects to two or more external networks, each external
1685 network **MUST** be assigned a unique ‘{network-role}’ in the context of
1686 the VNF for use in the VNF’s Heat Orchestration Template.
1688 R-83015 A VNF’s ‘{network-role}’ assigned to an external network **MUST**
1689 be different than the ‘{network-role}’ assigned to the VNF’s internal
1690 networks, if internal networks exist.
1692 ONAP enforces a naming convention for parameters associated with
1693 external networks. `ONAP Resource ID and Parameter Naming Convention`_
1694 provides additional details.
1699 ONAP defines an internal network in relation to the VNF and not with
1700 regard to the Network Cloud site. Internal networks may also be referred
1701 to as “intra-VNF” networks or “private” networks. An internal network
1702 only connects VMs in a single VNF; it must not connect to other VNFs
1703 or an external gateway or router
1705 R-87096 A VNF **MAY** contain zero, one or more than one internal networks.
1707 R-35666 If a VNF has an internal network, the VNF Heat Orchestration
1708 Template **MUST** include the heat resources to create the internal network.
1710 R-86972 A VNF **SHOULD** create the internal network in the VNF’s Heat
1711 Orchestration Template Base Module.
1713 An Internal Network may be created using Neutron Heat Resources and/or
1714 Contrail Heat Resources.
1716 R-52425 A VNF’s port connected to an internal network **MUST** connect
1717 the port to VMs in the same VNF.
1719 R-46461 A VNF’s port connected to an internal network **MUST NOT** connect
1720 the port to VMs in another VNF and/or an external gateway and/or
1723 R-68936 When a VNF creates an internal network, a network role, referred to
1724 as the ‘{network-role}’ **MUST** be assigned to the internal network for
1725 use in the VNF’s Heat Orchestration Template.
1727 R-32025 When a VNF creates two or more internal networks, each internal
1728 network **MUST** be assigned a unique ‘{network-role}’ in the context of
1729 the VNF for use in the VNF’s Heat Orchestration Template.
1731 R-69874 A VNF’s ‘{network-role}’ assigned to an internal network **MUST**
1732 be different than the ‘{network-role}’ assigned to the VNF’s external
1735 R-34726 If a VNF’s port is connected to an internal network and the port
1736 is created in the same Heat Orchestration Template as the internal network,
1737 then the port resource **MUST** use a ‘get_resource’ to obtain
1740 R-22688 If a VNF’s port is connected to an internal network and the
1741 port is created in an Incremental Module and the internal network is created
1742 in the Base Module then the UUID of the internal network **MUST** be exposed
1743 as a parameter in the ‘outputs:’ section of the Base Module and the port
1744 resource **MUST** use a ‘get_param’ to obtain the network UUID.
1746 ONAP does not programmatically enforce a naming convention for
1747 parameters for internal network. However, a naming convention is
1748 provided that must be followed.
1749 `ONAP Resource ID and Parameter Naming Convention`_
1750 provides additional details.
1752 ONAP Resource ID and Parameter Naming Convention
1753 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1755 This section provides the ONAP naming requirements for
1759 2. Resource Property Parameters
1764 R-01455 When a VNF's Heat Orchestration Template creates a Virtual Machine (i.e., 'OS::Nova::Server'),
1765 each 'class' of VMs **MUST** be assigned a VNF unique
1766 '{vm-type}'; where 'class' defines VMs that **MUST** have the following
1767 identical characteristics:
1769 1.) OS::Nova::Server property flavor value
1771 2.) OS::Nova::Server property image value
1773 3.) Cinder Volume attachments
1774 - Each VM in the 'class' **MUST** have the identical Cinder Volume
1777 4.) Network attachments and IP address requirements
1778 - Each VM in the 'class' **MUST** have the the identical number
1779 of ports connecting to the identical networks and requiring the
1780 identical IP address configuration.
1782 R-82481 A VNF's Heat Orchestration Template's Resource property
1784 associated with a unique Virtual Machine type **MUST**
1785 include '{vm-type}' as part of the parameter name with two
1788 1.) The Resource OS::Nova::Server property availability_zone parameter
1789 **MUST NOT** be prefixed with a common '{vm-type} identifier,
1791 2.) The Resource OS::Nova::Server eight mandatory and optional metadata
1792 parameters (vnf_name, vnf_id, vf_module_id, vf_module_name, vm_role,
1793 vf_module_index, environment_context, workload_context) **MUST NOT**
1794 be prefixed with a common '{vm-type}' identifier.
1797 R-66729 A VNF’s Heat Orchestration Template’s Resource that is
1798 associated with a unique Virtual Machine type **MUST** include
1799 ‘{vm-type}’ as part of the resource ID.
1801 R-98407 A VNF's Heat Orchestration Template's '{vm-type}' **MUST** contain
1802 only alphanumeric characters and/or underscores '_' and
1803 **MUST NOT** contain any of the following strings: '_int' or 'int\_'
1806 R-48067 A VNF's Heat Orchestration Template's {vm-type} **MUST NOT** be a
1807 substring of {network-role}.
1809 It may cause the Pre-Amsterdam VNF Validation Program (i.e.,
1810 ICE Project) process to produce erroneous error messages.
1812 R-32394 A VNF’s Heat Orchestration Template’s use of ‘{vm-type}’
1813 in all Resource property parameter names **MUST** be the same case.
1815 R-46839 A VNF’s Heat Orchestration Template’s use of
1816 ‘{vm-type}’ in all Resource IDs **MUST** be the same case.
1818 R-36687 A VNF’s Heat Orchestration Template’s ‘{vm-type}’ case in
1819 Resource property parameter names **SHOULD** match the case of
1820 ‘{vm-type}’ in Resource IDs and vice versa.
1825 The assignment of a {network-role} is discussed in `Networking`_.
1827 R-21330 A VNF’s Heat Orchestration Template’s Resource property parameter
1828 that is associated with external network **MUST** include the ‘{network-role}’’ as part of the parameter name
1830 R-11168 A VNF's Heat Orchestration Template's Resource ID that is
1831 associated with an external network **MUST** include the
1832 '{network-role}' as part of the resource ID.
1834 R-84322 A VNF's Heat Orchestration Template's Resource property
1835 parameter that is associated with an internal network
1836 **MUST** include 'int\_{network-role}' as part of the parameter
1837 name, where 'int\_' is a hard coded string.
1839 R-96983 A VNF's Heat Orchestration Template's Resource ID that is
1840 associated with an internal network **MUST** include
1841 'int\_{network-role}' as part of the Resource ID, where
1842 'int\_' is a hard coded string.
1844 R-26506 A VNF's Heat Orchestration Template's '{network-role}'
1845 **MUST** contain only alphanumeric characters and/or
1846 underscores '_' and **MUST NOT** contain any of the following
1847 strings: '_int' or 'int\_' or '\_int\_'.
1849 R-00977 A VNF’s Heat Orchestration Template’s ‘{network-role}’
1850 **MUST NOT** be a substring of ‘{vm-type}’.
1852 For example, if a VNF has a ‘{vm-type}’ of ‘oam’ and a
1853 ‘{network-role}’ of ‘oam_protected’ would be a violation of the requirement.
1855 R-58424 A VNF’s Heat Orchestration Template’s use of ‘{network-role}’
1856 in all Resource property parameter names **MUST** be the same case
1858 R-21511 A VNF’s Heat Orchestration Template’s use of ‘{network-role}’
1859 in all Resource IDs **MUST** be the same case.
1861 R-86588 A VNF’s Heat Orchestration Template’s ‘{network-role}’ case
1862 in Resource property parameter names **SHOULD** match the case
1863 of ‘{network-role}’ in Resource IDs and vice versa.
1868 Requirement R-75141 states a VNF’s Heat Orchestration Template’s
1869 resource name (i.e., <resource ID>) MUST only contain alphanumeric
1870 characters and underscores (‘_’).*
1872 Requirement R-16447 states a VNF’s <resource ID> MUST be unique
1873 across all Heat Orchestration Templates and all HEAT Orchestration
1874 Template Nested YAML files that are used to create the VNF.
1876 As stated previously, OpenStack requires the <resource ID> to be unique
1877 to the Heat Orchestration Template and not unique across all Heat
1878 Orchestration Templates the compose the VNF.
1880 Heat Orchestration Template resources are described in `resources`_
1882 R-54517 When a VNF’s Heat Orchestration Template’s resource is associated
1883 with a single ‘{vm-type}’, the Resource ID **MUST** contain the ‘{vm-type}’.
1885 R-96482 When a VNF’s Heat Orchestration Template’s resource is associated
1886 with a single external network, the Resource ID MUST contain the text
1889 R-98138 When a VNF’s Heat Orchestration Template’s resource is associated
1890 with a single internal network, the Resource ID MUST contain the text
1891 ‘int\_{network-role}’.
1893 R-82115 When a VNF's Heat Orchestration Template's resource is associated
1894 with a single '{vm-type}' and a single external network, the Resource
1895 ID text **MUST** contain both the '{vm-type}' and the '{network-role}'
1897 - the '{vm-type}' **MUST** appear before the '{network-role}' and **MUST**
1898 be separated by an underscore '_'
1900 - e.g., '{vm-type}_{network-role}', '{vm-type}_{index}_{network-role}'
1902 - note that an '{index}' value **MAY** separate the '{vm-type}' and the
1903 '{network-role}' and when this occurs underscores **MUST** separate the
1906 R-82551 When a VNF's Heat Orchestration Template's resource is associated
1907 with a single '{vm-type}' and a single internal network, the Resource ID
1908 **MUST** contain both the '{vm-type}' and the 'int\_{network-role}' and
1910 - the '{vm-type}' **MUST** appear before the 'int\_{network-role}' and
1911 **MUST** be separated by an underscore '_'
1913 - (e.g., '{vm-type}\_int\_{network-role}', '{vm-type}_{index}\_int\_{network-role}')
1915 - note that an '{index}' value **MAY** separate the '{vm-type}' and the
1916 'int\_{network-role}' and when this occurs underscores **MUST** separate
1919 R-67793 When a VNF’s Heat Orchestration Template’s resource is associated
1920 with more than one ‘{vm-type}’ and/or more than one internal and/or
1921 external network, the Resource ID **MUST NOT** contain the ‘{vm-type}’
1922 and/or ‘{network-role}’/’int\_{network-role}’. It also should contain the
1923 term ‘shared’ and/or contain text that identifies the VNF
1925 R-27970 When a VNF’s Heat Orchestration Template’s resource is associated
1926 with more than one ‘{vm-type}’ and/or more than one internal and/or
1927 external network, the Resource ID **MAY** contain the term ‘shared’
1928 and/or **MAY** contain text that identifies the VNF.
1930 R-11690 When a VNF’s Heat Orchestration Template’s Resource ID contains
1931 an {index} value (e.g. multiple VMs of same {vm-type}), the ‘{index}’
1932 **MUST** start at zero and increment by one.
1934 The table below provides example OpenStack Heat resource ID for
1935 resources only associated with one {vm-type} and/or one network.
1937 The Requirements column states if the Resource ID Format MUST be followed
1938 or SHOULD be followed. Resource ID formats that are marked MUST must be
1939 followed, no deviations are permitted. Resource ID formats that are marked
1940 SHOULD should be followed. However, deviations are permissible to meet
1941 the needs of the VNF’s Heat Orchestration Template.
1943 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
1944 | Resource Type | Resource ID Format | Requirements | Notes |
1946 +==============================+=================================================================+====================================+=========================+
1947 | OS::Cinder::Volume | {vm-type}\_volume\_{index} | **SHOULD** | |
1949 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
1950 | OS::Cinder::VolumeAttachment | {vm-type}\_volumeattachment\_{index} | **SHOULD** | |
1951 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
1952 | OS::Heat::CloudConfig | {vm-type}_RCC | **SHOULD** | |
1953 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
1954 | OS::Heat::MultipartMime | {vm-type}_RMM | **SHOULD** | |
1956 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
1957 | OS::Heat::ResourceGroup | {vm-type}_RRG | **SHOULD** | |
1959 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
1962 | | | | Resource ID for the |
1963 | | {vm-type}_{index}\_subint\_{network-role}_ | **MUST** for subinterface creation | OS::Heat::ResourceGroup |
1964 | | port\_{index}_subinterfaces | | that creates |
1965 | | | | subinterfaces |
1966 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
1967 | OS::Heat::SoftwareConfig | {vm-type}_RSC | **SHOULD** | |
1969 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
1970 | OS::Neutron::Port | {vm-type}_{vm-type-index}_{network-role}\_port\_{port-index} | **MUST** | Resource ID for port |
1971 | | | | connecting to an |
1972 | | | | external network. The |
1973 | | | | {vm-type-index} |
1975 | | | | instance of the |
1976 | | | | {vm_type}. The |
1977 | | | | {port-index} |
1979 | | | | instance of the |
1980 | | | | “port” on the |
1981 | | | | {vm-type}. There is |
1982 | | | | no index after |
1983 | | | | {network_role} since |
1984 | | | | since {network-role} |
1985 | | | | is unque to the VNF, |
1986 | | | | there should |
1987 | | | | only be one instance. |
1988 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
1989 | | {vm-type}_{index}\_int\_{network-role}\_port\_{index} | | Resource ID for port |
1990 | | | **MUST** | connecting to an |
1991 | | | | internal network. The |
1992 | | | | {index} that follows |
1993 | | | | {vm-type} is the |
1994 | | | | instance of the |
1995 | | | | {vm_type}. The |
1996 | | | | {index} that follows |
1997 | | | | “port” is the |
1998 | | | | instance of the |
1999 | | | | “port” on the |
2000 | | | | {vm-type}. There is |
2001 | | | | no index after |
2002 | | | | {network_role} since |
2003 | | | | since {network-role} |
2004 | | | | is unque to the AIC |
2005 | | | | LCP; there should |
2006 | | | | only be one instance. |
2007 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2008 | | Reserve_Port\_{vm-type}_{network-role}\_floating_ip\_{index} | | Resource ID for a |
2009 | | | **MUST** | reserve port that is |
2010 | | | | used for an |
2011 | | | | allowed_address_pair. |
2012 | | Reserve_Port\_{vm-type}_{network-role}\_floating_v6_ip\_{index} | | See Section 5.6.5.5 |
2013 | | | | for additional |
2016 | | | | There is no {index} |
2017 | | | | that follows |
2019 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2020 | OS::Neutron::SecurityGroup | {vm-type}_Sec_Grp | | Security Group |
2021 | | | **SHOULD** | applicable to one |
2022 | | | | {vm-type} and more |
2023 | | | | than one network |
2024 | | | | (internal and/or |
2026 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2027 | | {network-role}_Sec_Grp | | Security Group |
2028 | | | **SHOULD** | applicable to more |
2029 | | | | than one {vm-type} |
2030 | | | | and one external |
2032 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2033 | | int\_{network-role}_Sec_Grp | | Security Group |
2034 | | | **SHOULD** | applicable to more |
2035 | | | | than one {vm-type} |
2036 | | | | and one internal |
2038 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2039 | | {vm-type}_{network-role}_Sec_Grp | | Security Group |
2040 | | | **SHOULD** | applicable to one |
2041 | | | | {vm-type} and one |
2042 | | | | external network |
2043 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2044 | | {vm-type}\_int\_{network-role}_Sec_Grp | | Security Group |
2045 | | | **SHOULD** | applicable to one |
2046 | | | | {vm-type} and one |
2047 | | | | internal network |
2048 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2049 | | Shared_Sec_Grp | | Security Group |
2050 | | | **SHOULD** | applicable to more |
2051 | | | | than one {vm-type} |
2052 | | | | and more than one |
2053 | | | | network (internal |
2054 | | | | and/or external) |
2055 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2056 | OS::Neutron::Subnet | int\_{network-role}\_subnet\_{index} | | VNF Heat |
2057 | | | **MUST** | Orchestration |
2058 | | | | Templates can only |
2059 | | | | create internal |
2061 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2062 | OS::Neutron::Net | int\_{network-role}\_network | | VNF Heat |
2063 | | | **MUST** | Orchestration |
2064 | | | | Templates can only |
2065 | | | | create internal |
2066 | | | | networks. There is no |
2067 | | | | {index} because |
2068 | | | | {nework-role} should |
2069 | | | | be unique. |
2071 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2072 | OS::Nova::Keypair | {vm-type}\_keypair\_{index} | **SHOULD** | Key Pair applicable to |
2073 | | | | one {vm-type} |
2074 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2075 | | {vnf-type}_keypair | **SHOULD** | Key Pair applicable |
2076 | | | | to all {vm-type} in the |
2078 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2079 | OS::Nova::Server | {vm-type}\_server\_{index} | Mandatory | |
2081 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2082 | OS::Nova::ServerGroup | {vm-type}_RSG | **SHOULD** | Both formats are |
2084 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2085 | | {vm-type}_Server_Grp | **SHOULD** | |
2086 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2087 | | {vm-type}_ServerGroup | **SHOULD** | |
2088 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2089 | OS::Swift::Container | {vm-type}_RSwiftC | **SHOULD** | |
2090 +------------------------------+-----------------------------------------------------------------+------------------------------------+-------------------------+
2093 Table 2: Example OpenStack Heat Resource ID
2095 The table below provides Resource ID Formats for Contrail heat resources.
2096 - The Resource ID formats that are marked mandatory must be followed.
2097 No deviations are permitted.
2098 - The Resource ID formats that are marked optional should be followed.
2099 However, deviations in the Resource ID format that is shown is
2102 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2103 | Resource | Resource ID | Mandatory / | Notes | |
2104 | Type | Format | Optional | | |
2105 +=================+==========================================================================+=================+=================+===+
2106 | OS::ContrailV2: | {vm-type}_{index}_{network-role}\_vmi\_{index}\_IP\_{index} | **MUST** – | The {index} | |
2107 | :InstanceIp | | IPv4 address on | that follows | |
2108 | | | vmi external | {vm-type} is | |
2109 | | | network | the instance of | |
2110 | | | | the {vm_type}. | |
2111 | | | | The {index} | |
2112 | | | | that follows | |
2113 | | | | “vmi” is the | |
2114 | | | | instance of the | |
2115 | | | | “vmi” on the | |
2116 | | | | {vm-type}. | |
2117 | | | | There is no | |
2118 | | | | index after | |
2119 | | | | {network_role} | |
2120 | | | | since since | |
2121 | | | | {network-role} | |
2122 | | | | is unque. The | |
2123 | | | | {index} that | |
2124 | | | | follows the | |
2125 | | | | “IP” is the | |
2126 | | | | instance of the | |
2127 | | | | “IP” on the | |
2129 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2130 | | {vm-type}_{index}_{network-role}\_vmi\_{index}\_v6\_IP\_{index} | **MUST** – | | |
2131 | | | IPv6 address on | | |
2132 | | | vmi external | | |
2134 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2135 | | {vm-type}_{index}\_int\_{network-role}\_vmi\_{index}\_IP\_{index} | **MUST** – | | |
2136 | | | IPv4 address on | | |
2137 | | | vmi internal | | |
2139 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2140 | | {vm-type}_{index}\_int\_{network-role}\_vmi\_{index}\_v6\_IP\_{index} | **MUST** – | | |
2141 | | | IPv6 address on | | |
2142 | | | vmi internal | | |
2145 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2146 | | {vm-type}_{index}\_subint\_{network-role}\_vmi\_{index}\_IP\_{index} | **MUST** – | | |
2147 | | | IPv4 address on | | |
2148 | | | sub-interface | | |
2149 | | | vmi external | | |
2151 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2152 | | {vm-type}_{index}\_subint\_{network-role}\_vmi\_{index}\_v6\_IP\_{index} | **MUST** – | | |
2153 | | | IPv6 address on | | |
2154 | | | sub-interface | | |
2155 | | | vmi external | | |
2157 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2158 | OS::ContrailV2: | {network-role}_RIRT | **MAY** | | |
2159 | :InterfaceRoute | | | | |
2161 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2162 | OS::ContrailV2: | {network-role}_RNI | **MAY** | | |
2163 | :NetworkIpam | | | | |
2164 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2165 | OS::ContrailV2: | {vm-type}_RPT | **MAY** | | |
2166 | :PortTuple | | | | |
2167 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2168 | OS::ContrailV2: | {vm-type}\_RSHC\_{LEFT/RIGHT} | **MAY** | | |
2169 | :ServiceHealthC | | | | |
2171 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2172 | OS::ContrailV2: | {vm-type}\_RST\_{index} | **MAY** | | |
2173 | :ServiceTemplat | | | | |
2175 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2176 | OS::ContrailV2: | {vm-type}\_{index}\_{network-role}\_vmi\_{index} | **MUST** - vmi | Resource ID for | |
2177 | :VirtualMachine | | attached to an | virtual machine | |
2178 | Interface | | external | interface (vmi) | |
2179 | | | network | connecting to | |
2180 | | | | an external | |
2181 | | | | network. The | |
2182 | | | | {index} that | |
2184 | | | | {vm-type} is | |
2185 | | | | the instance of | |
2186 | | | | the {vm_type}. | |
2187 | | | | The {index} | |
2188 | | | | that follows | |
2189 | | | | “vmi” is the | |
2190 | | | | instance of the | |
2191 | | | | “vmi” on the | |
2192 | | | | {vm-type}. | |
2193 | | | | There is no | |
2194 | | | | index after | |
2195 | | | | {network_role} | |
2196 | | | | since since | |
2197 | | | | {network-role} | |
2198 | | | | is unque to the | |
2199 | | | | AIC LCP; there | |
2200 | | | | should only be | |
2201 | | | | one instance. | |
2202 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2203 | | {vm-type}_{index}\_int\_{network-role}\_vmi\_{index} | **MUST** - vmi | | |
2204 | | | attached to an | | |
2205 | | | internal | | |
2207 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2208 | | {vm-type}_{index}\_subint\_{network-role}\_vmi\_{index} | **MUST** - vmi | | |
2209 | | | attached to a | | |
2210 | | | sub-interface | | |
2212 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2213 | OS::ContrailV2: | int\_{network-role}\_RVN | **MAY** | VNF Heat | |
2214 | :VirtualNetwork | | | Orchestration | |
2215 | | | | Templates can | |
2216 | | | | only create | |
2217 | | | | internal | |
2218 | | | | networks. There | |
2219 | | | | is no {index} | |
2221 | | | | {nework-role} | |
2222 | | | | should be | |
2223 | | | | unique. Both | |
2224 | | | | formats are | |
2226 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2227 | | int\_{network-role}\_network | **MAY** | | |
2229 +-----------------+--------------------------------------------------------------------------+-----------------+-----------------+---+
2231 Table 3: Example Contrail Heat resource ID
2233 There is a use case where the template filename is used as the type: as
2234 shown in the example below. There is no suggested Resource ID naming
2235 convention for this use case.
2237 Example: Template Filename used as the type:
2239 .. code-block:: python
2241 heat_template_version: 2015-04-30
2249 Resource: OS::Nova::Server - Parameters
2250 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2252 The resource OS::Nova::Server manages the running virtual machine (VM)
2253 instance within an OpenStack cloud. (See
2254 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::Server.)
2256 Four properties of this resource must follow the ONAP parameter naming
2257 convention. The four properties are:
2265 4. availability\_zone
2267 Requirement R-01455 defines how the ‘{vm-type]’ is defined.
2269 Requirement R-82481 defines how the ‘{vm-type} is used.’
2271 The table below provides a summary. The sections that follow provides
2272 the detailed requirements.
2274 .. csv-table:: **Table 4 OS::Nova::Server Resource Property Parameter Naming Convention**
2275 :header: Property Name,Parameter Type,Parameter Name,Parameter Value Provided to Heat
2279 image, string, {vm-type}\_image\_name, Environment File
2280 flavor, string, {vm-type}\_flavor\_name, Environment File
2281 name, string, {vm-type}\_name\_{index}, ONAP
2282 name, CDL, {vm-type}_names, ONAP
2283 availability_zone, string, availability\_zone\_{index}, ONAP
2288 R-71152 The VNF’s Heat Orchestration Template’s Resource
2289 ‘OS::Nova::Server’ property ‘image’ parameter **MUST** be declared as
2292 R-58670 The VNF’s Heat Orchestration Template’s Resource
2293 ‘OS::Nova::Server’ property ‘image’ parameter name **MUST** follow the
2294 naming convention ‘{vm-type}_image_name’.
2296 R-91125 The VNF’s Heat Orchestration Template’s Resource
2297 ‘OS::Nova::Server’ property ‘image’ parameter **MUST** be enumerated in
2298 the Heat Orchestration Template’s Environment File and a value **MUST** be
2301 R-57282 Each VNF’s Heat Orchestration Template’s ‘{vm-type}’
2302 **MUST** have a unique parameter name for the ‘OS::Nova::Server’
2303 property ‘image’ even if more than one {vm-type} shares the same image.
2305 *Example Parameter Definition*
2307 .. code-block:: yaml
2310 {vm-type}_image_name:
2312 description: {vm-type} server image
2317 R-50436 The VNF’s Heat Orchestration Template’s Resource
2318 ‘OS::Nova::Server’ property ‘flavor’ parameter **MUST** be declared as
2321 R-45188 The VNF’s Heat Orchestration Template’s Resource
2322 ‘OS::Nova::Server’ property ‘flavor’ parameter name **MUST** follow the
2323 naming convention ‘{vm-type}_flavor_name’.
2325 R-69431 The VNF’s Heat Orchestration Template’s Resource
2326 ‘OS::Nova::Server’ property ‘flavor’ parameter **MUST** be enumerated in the
2327 Heat Orchestration Template’s Environment File and a value **MUST** be
2330 R-40499 Each VNF’s Heat Orchestration Template’s ‘{vm-type}’ **MUST**
2331 have a unique parameter name for the ‘OS::Nova::Server’ property
2332 ‘flavor’ even if more than one {vm-type} shares the same flavor.
2334 *Example Parameter Definition*
2336 .. code-block:: yaml
2339 {vm-type}_flavor_name:
2341 description: {vm-type} flavor
2346 R-51430 The VNF’s Heat Orchestration Template’s Resource
2347 ‘OS::Nova::Server’ property ‘name’ parameter **MUST** be declared as
2348 either type ‘string’ or type ‘comma_delimited_list”.
2350 R-54171 When the VNF’s Heat Orchestration Template’s Resource
2351 ‘OS::Nova::Server’ property ‘name’ parameter is defined as a ‘string’,
2352 the parameter name **MUST** follow the naming convention
2353 ‘{vm-type}\_name\_{index}’, where {index} is a numeric value that starts
2354 at zero and increments by one.
2356 R-40899 When the VNF’s Heat Orchestration Template’s Resource
2357 ‘OS::Nova::Server’ property ‘name’ parameter is defined as a ‘string’,
2358 a parameter **MUST** be declared for each ‘OS::Nova::Server’ resource
2359 associated with the ‘{vm-type}’.
2361 R-87817 When the VNF’s Heat Orchestration Template’s Resource
2362 ‘OS::Nova::Server’ property ‘name’ parameter is defined as a
2363 ‘comma_delimited_list’, the parameter name **MUST** follow the naming
2364 convention ‘{vm-type}_names’.
2366 R-85800 When the VNF’s Heat Orchestration Template’s Resource
2367 ‘OS::Nova::Server’ property ‘name’ parameter is defined as a
2368 ‘comma_delimited_list’, a parameter **MUST** be delcared once for all
2369 ‘OS::Nova::Server’ resources associated with the ‘{vm-type}’.
2371 R-22838 The VNF’s Heat Orchestration Template’s Resource
2372 ‘OS::Nova::Server’ property ‘name’ parameter **MUST NOT** be enumerated
2373 in the Heat Orchestration Template’s Environment File.
2375 If a VNF’s Heat Orchestration Template’s contains more than three
2376 OS::Nova::Server resources of a given {vm-type}, the comma_delimited_list
2377 form of the parameter name (i.e., ‘{vm-type}_names’) should be used to
2378 minimize the number of unique parameters defined in the template.
2381 *Example: Parameter Definition*
2383 .. code-block:: python
2388 type: comma_delimited_list
2389 description: VM Names for {vm-type} VMs
2391 {vm-type}_name_{index}:
2393 description: VM Name for {vm-type} VM {index}
2395 *Example: comma_delimited_list*
2397 In this example, the {vm-type} has been defined as “lb” for load balancer.
2399 .. code-block:: python
2404 type: comma_delimited_list
2405 description: VM Names for lb VMs
2409 type: OS::Nova::Server
2411 name: { get_param: [lb_names, 0] }
2415 type: OS::Nova::Server
2417 name: { get_param: [lb_names, 1] }
2420 *Example: fixed-index*
2422 In this example, the {vm-type} has been defined as “lb” for load balancer.
2424 .. code-block:: python
2430 description: VM Name for lb VM 0
2434 description: VM Name for lb VM 1
2439 type: OS::Nova::Server
2441 name: { get_param: lb_name_0 }
2445 type: OS::Nova::Server
2447 name: { get_param: lb_name_1 }
2450 Contrail Issue with Values for OS::Nova::Server Property Name
2451 _____________________________________________________________
2453 R-44271 The VNF's Heat Orchestration Template's Resource 'OS::Nova::Server' property
2454 'name' parameter value **SHOULD NOT** contain special characters
2455 since the Contrail GUI has a limitation displaying special characters.
2457 However, if special characters must be used, the only special characters
2460 --- \" ! $ ' (\ \ ) = ~ ^ | @ ` { } [ ] > , . _
2463 Property: availability\_zone
2464 ++++++++++++++++++++++++++++
2466 R-98450 The VNF’s Heat Orchestration Template’s Resource
2467 ‘OS::Nova::Server’ property ‘availability_zone’ parameter name
2468 **MUST** follow the naming convention ‘availability\_zone\_{index}’
2469 where the ‘{index}’ **MUST** start at zero and increment by one.
2471 R-23311 The VNF’s Heat Orchestration Template’s Resource
2472 ‘OS::Nova::Server’ property ‘availability_zone’ parameter **MUST**
2473 be declared as type: ‘string’.
2475 The parameter must not be declared as type ‘comma_delimited_list’,
2476 ONAP does not support it.
2478 R-59568 The VNF’s Heat Orchestration Template’s Resource
2479 ‘OS::Nova::Server’ property ‘availability_zone’ parameter **MUST NOT**
2480 be enumerated in the Heat Orchestration Template’s Environment File.
2482 Example Parameter Definition
2484 .. code-block:: python
2487 availability_zone_{index}:
2489 description: availability zone {index} name
2491 Requirement R-90279 states that a VNF Heat Orchestration’s template’s
2492 parameter MUST be used in a resource with the exception of the parameters
2493 for the OS::Nova::Server resource property availability_zone.
2495 R-01359 A VNF’s Heat Orchstration Template that contains an
2496 ‘OS::Nova:Server’ Resource **MAY** define a parameter for the property
2497 ‘availability_zone’ that is not utilized in any ‘OS::Nova::Server’
2498 resources in the Heat Orchestration Template.
2503 The example below depicts part of a Heat Orchestration Template that
2504 uses the four OS::Nova::Server properties discussed in this section.
2506 In the Heat Orchestration Template below, four Virtual
2507 Machines (OS::Nova::Server) are created: two dns servers with
2508 {vm-type} set to “dns” and two oam servers with {vm-type} set to “oam”.
2509 Note that the parameter associated with the property name is a
2510 comma_delimited_list for dns and a string for oam.
2512 .. code-block:: python
2518 description: dns server image
2522 description: dns server flavor
2525 type: comma_delimited_list
2526 description: dns server names
2530 description: oam server image
2534 description: oam server flavor
2538 description: oam server name 0
2542 description: oam server name 1
2544 availability_zone_0:
2546 description: availability zone ID or Name
2548 availability_zone_1:
2550 description: availability zone ID or Name
2555 type: OS::Nova::Server
2557 name: { get_param: [ dns_names, 0 ] }
2558 image: { get_param: dns_image_name }
2559 flavor: { get_param: dns_flavor_name }
2560 availability_zone: { get_param: availability_zone_0 }
2565 type: OS::Nova::Server
2567 name: { get_param: [ dns_names, 1 ] }
2568 image: { get_param: dns_image_name }
2569 flavor: { get_param: dns_flavor_name }
2570 availability_zone: { get_param: availability_zone_1 }
2575 type: OS::Nova::Server
2577 name: { get_param: oam_name_0 }
2578 image: { get_param: oam_image_name }
2579 flavor: { get_param: oam_flavor_name }
2580 availability_zone: { get_param: availability_zone_0 }
2585 type: OS::Nova::Server
2587 name: { get_param: oam_name_1 }
2588 image: { get_param: oam_image_name }
2589 flavor: { get_param: oam_flavor_name }
2590 availability_zone: { get_param: availability_zone_1 }
2597 R-99798 A VNF’s Heat Orchestration Template’s Virtual Machine
2598 (i.e., OS::Nova::Server Resource) **MAY** boot from an image or **MAY**
2599 boot from a Cinder Volume.
2601 R-83706 When a VNF’s Heat Orchestration Template’s Virtual Machine
2602 (i.e., ‘OS::Nova::Server’ Resource) boots from an image, the
2603 ‘OS::Nova::Server’ resource property ‘image’ **MUST** be used.
2605 The requirements associated with
2606 the 'image' property are detailed in `Property: image`_
2608 R-69588 When a VNF’s Heat Orchestration Template’s Virtual Machine
2609 (i.e., ‘OS::Nova::Server’ Resource) boots from Cinder Volume, the
2610 ‘OS::Nova::Server’ resource property ‘block_device_mapping’ or
2611 ‘block_device_mapping_v2’ **MUST** be used.
2613 There are currently no heat guidelines
2614 associated with these two properties:
2615 'block_device_mapping' and 'block_device_mapping_v2'.
2617 Resource: OS::Nova::Server – Metadata Parameters
2618 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2620 The resource OS::Nova::Server has an OpenStack optional property
2621 metadata. The metadata property is mandatory for ONAP Heat Orchestration
2622 Templates; it must be included.
2624 R-17020 The VNF Heat Orchestration Template **MUST** include the following three mandatory
2625 metadata parameters for an OS::Nova::Server resource:
2633 ONAP allows the following three optional metadata parameters for an
2634 OS::Nova::Server resource. They may be included
2640 Note that the metadata parameters do not and must not contain {vm-type}
2643 When Metadata parameters are past into a nested heat template, the
2644 parameter names must not change.
2646 The table below provides a summary. The sections that follow provides
2649 +-------------------+----------+-------------------+----------------+
2650 | Metadata Parameter| Parameter| Mandatory/Optional| Parameter Value|
2651 | Name | Type | | Generation |
2652 +===================+==========+===================+================+
2653 | vnf\_id | string | Mandatory | ONAP |
2654 +-------------------+----------+-------------------+----------------+
2655 | vf\_module\_id | string | Mandatory | ONAP |
2656 +-------------------+----------+-------------------+----------------+
2657 | vnf\_name | string | Mandatory | ONAP |
2658 +-------------------+----------+-------------------+----------------+
2659 | vf\_module\_name | string | Optional | ONAP |
2660 +-------------------+----------+-------------------+----------------+
2661 | vm\_role | string | Optional | YAML or |
2662 | | | | Environment |
2664 +-------------------+----------+-------------------+----------------+
2666 Table 4: ONAP Metadata
2671 The vnf\_id parameter is mandatory; it must be included in the Heat
2672 Orchestration Template.
2674 The vnf\_id parameter value will be supplied by ONAP. ONAP generates the
2675 UUID that is the vnf\_id and supplies it to the Heat Orchestration
2676 Template at orchestration time.
2678 The parameter must be declared as type: string
2680 R-55218 The VNF Heat Orchestration Template **MUST NOT** have parameter constraints defined
2681 for the OS::Nova::Server metadata parameter vnf\_id.
2683 R-20856 The VNF Heat Orchestration Template **MUST NOT** enumerate the OS::Nova::Server
2684 metadata parameter vnf\_id in environment file.
2686 *Example Parameter Definition*
2688 .. code-block:: yaml
2693 description: Unique ID for this VNF instance
2698 The vf\_module\_id parameter is mandatory; it must be included in the
2699 Heat Orchestration Template.
2701 The vf\_module\_id parameter value will be supplied by ONAP. ONAP
2702 generates the UUID that is the vf\_module\_id and supplies it to the
2703 Heat Orchestration Template at orchestration time.
2705 The parameter must be declared as type: string
2707 R-98374 The VNF Heat Orchestration Template **MUST NOT** have parameter constraints
2708 defined for the OS::Nova::Server metadata parameter vf\_module\_id.
2710 R-72871 The VNF Heat Orchestration Template **MUST NOT** enumerate the OS::Nova::Server
2711 metadata parameter vf\_module\_id in environment file.
2713 *Example Parameter Definition*
2715 .. code-block:: yaml
2720 description: Unique ID for this VNF module instance
2725 The vnf\_name parameter is mandatory; it must be included in the Heat
2726 Orchestration Template.
2728 The vnf\_name parameter value will be generated and/or assigned by ONAP
2729 and supplied to the Heat Orchestration Template by ONAP at orchestration
2732 The parameter must be declared as type: string
2734 R-44318 The VNF Heat Orchestration Template **MUST NOT** have parameter constraints defined
2735 for the OS::Nova::Server metadata parameter vnf\_name.
2737 R-36542 The VNF Heat Orchestration Template **MUST NOT** enumerate the OS::Nova::Server
2738 metadata parameter vnf\_name in the environment file.
2740 *Example Parameter Definition*
2742 .. code-block:: yaml
2747 description: Unique name for this VNF instance
2752 The vf\_module\_name parameter is optional; it may be included in the
2753 Heat Orchestration Template.
2755 The vf\_module\_name parameter is the name of the name of the Heat stack
2756 (e.g., <STACK\_NAME>) in the command “Heat stack-create” (e.g., Heat
2757 stack-create [-f <FILE>] [-e <FILE>] <STACK\_NAME>). The <STACK\_NAME>
2758 needs to be specified as part of the orchestration process.
2760 The parameter must be declared as type: string
2762 Parameter constraints must not be defined.
2764 The parameter must not be enumerated in the Heat environment file.
2766 *Example Parameter Definition*
2768 .. code-block:: yaml
2773 description: Unique name for this VNF Module instance
2778 The vm\_role parameter is optional; it may be included in the Heat
2779 Orchestration Template.
2781 Any roles tagged to the VMs via metadata will be stored in ONAP’s A&AI
2782 system and available for use by other ONAP components and/or north bound
2785 The vm\_role values must be either
2787 - hard-coded into the Heat Orchestration Template or
2789 - enumerated in the environment file.
2791 Defining the vm\_role as the {vm-type} is a recommended convention
2793 The parameter must be declared as type: string
2795 Parameter constraints must not be defined.
2797 *Example Parameter Definition*
2799 .. code-block:: yaml
2804 description: Unique role for this VM
2806 *Example Resource Definition: Hard Coded*
2808 In this example, the {vm-role} is hard coded in the Heat Orchestration
2811 .. code-block:: yaml
2815 type: OS::Nova::Server
2821 *Example Resource Definition: get\_param*
2823 In this example, the {vm-role} is enumerated in the environment file.
2825 .. code-block:: yaml
2829 type: OS::Nova::Server
2833 vm_role: { get_param: vm_role }
2838 The example below depicts part of a Heat Orchestration Template that
2839 uses the five of the OS::Nova::Server metadata parameter discussed in
2840 this section. The {vm-type} has been defined as lb for load balancer.
2842 .. code-block:: yaml
2847 description: VM Name for lb VM 0
2850 description: Unique name for this VNF instance
2853 description: Unique ID for this VNF instance
2856 description: Unique name for this VNF Module instance
2859 description: Unique ID for this VNF Module instance
2862 description: Unique role for this VM
2867 type: OS::Nova::Server
2869 name: { get_param: lb_name_0 }
2872 vnf_name: { get_param: vnf_name }
2873 vnf_id: { get_param: vnf_id }
2874 vf_module_name: { get_param: vf_module_name }
2875 vf_module_id: { get_param: vf_module_id }
2878 Resource: OS::Neutron::Port - Parameters
2879 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2881 The resource OS::Neutron::Port is for managing Neutron ports (See
2882 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Port.)
2887 Four properties of the resource OS::Neutron::Port that must follow the
2888 ONAP parameter naming convention. The four properties are:
2892 2. fixed\_ips, ip\_address
2894 3. fixed\_ips, subnet\_id
2896 4. allowed\_address\_pairs, ip\_address
2898 The parameters associated with these properties may reference an
2899 external network or internal network. External networks and internal
2900 networks are defined in `Networking`_.
2905 When the parameter references an external network
2907 - R-72050 The VNF Heat Orchestration Template **MUST** contain {network-role} in the parameter name
2909 - the parameter must not be enumerated in the Heat environment file
2911 - the parameter is classified as an ONAP Orchestration Parameter
2913 +----------------------+---------------------------+--------------------------+
2914 | Property Name | ONAP Parameter Name | Parameter Type |
2915 +======================+===========================+==========================+
2916 | network | {network-role}\_net\_id | string |
2917 | +---------------------------+--------------------------+
2918 | | {network-role}\_net\_name | string |
2919 +----------------------+---------------------------+--------------------------+
2920 | fixed\_ips, | {vm-type}\_{network-role}\| string |
2921 | ip\_address | _ip\_{index} | |
2922 | +---------------------------+--------------------------+
2923 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
2925 | +---------------------------+--------------------------+
2926 | | {vm-type}\_{network-role}\| string |
2927 | | _v6\_ip\_{index} | |
2928 | +---------------------------+--------------------------+
2929 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
2931 +----------------------+---------------------------+--------------------------+
2932 | fixed\_ips, subnet | {network-role}\ | string |
2934 | +---------------------------+--------------------------+
2935 | | {network-role}\ | string |
2936 | | _v6\_subnet\_id | |
2937 +----------------------+---------------------------+--------------------------+
2938 | allowed\_address | {vm-type}\_{network-role}\| string |
2939 | \_pairs, ip\_address | _floating\_ip | |
2940 | +---------------------------+--------------------------+
2941 | | {vm-type}\_{network-role}\| string |
2942 | | _floating\_v6\_ip | |
2943 | +---------------------------+--------------------------+
2944 | | {vm-type}\_{network-role}\| string |
2945 | | _ip\_{index} | |
2946 | +---------------------------+--------------------------+
2947 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
2949 | +---------------------------+--------------------------+
2950 | | {vm-type}\_{network-role}\| string |
2951 | | _v6\_ip\_{index} | |
2952 | +---------------------------+--------------------------+
2953 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
2955 +----------------------+---------------------------+--------------------------+
2957 Table 5: OS::Neutron::Port Resource Property Parameters (External
2963 When the parameter references an internal network
2965 - R-57576 The VNF Heat Orchestration Template **MUST** contain int\_{network-role}
2966 in the parameter name.
2968 - the parameter may be enumerated in the environment file.
2970 +-------------------------+--------------------------------+-----------------+
2971 | Property | Parameter Name for | Parameter Type |
2972 | | Internal Networks | |
2973 +=========================+================================+=================+
2974 | network | int\_{network-role}\ | string |
2976 | +--------------------------------+-----------------+
2977 | | int\_{network-role}\ | string |
2979 +-------------------------+--------------------------------+-----------------+
2980 | fixed\_ips, ip\_address | {vm-type}\_int\_{network-role}\| string |
2981 | | _ip\_{index} | |
2982 | +--------------------------------+-----------------+
2983 | | {vm-type}\_int\_{network-role}\| comma\ |
2984 | | _ips | _delimited\_list|
2985 | +--------------------------------+-----------------+
2986 | | {vm-type}\_int\_{network-role}\| string |
2987 | | _v6\_ip\_{index} | |
2988 | +--------------------------------+-----------------+
2989 | | {vm-type}\_int\_{network-role}\| comma\ |
2990 | | _v6\_ips | _delimited\_list|
2991 +-------------------------+--------------------------------+-----------------+
2992 | fixed\_ips, subnet | int\_{network-role}\ | string |
2994 | +--------------------------------+-----------------+
2995 | | int\_{network-role}\ | string |
2996 | | _v6\_subnet\_id | |
2997 +-------------------------+--------------------------------+-----------------+
2998 | allowed\_address\_pairs,| {vm-type}\_int\_{network-role}\| string |
2999 | ip\_address | _floating\_ip | |
3000 | +--------------------------------+-----------------+
3001 | | {vm-type}\_int\_{network-role}\| string |
3002 | | _floating\_v6\_ip | |
3003 | +--------------------------------+-----------------+
3004 | | {vm-type}\_int\_{network-role}\| string |
3005 | | _ip\_{index} | |
3006 | +--------------------------------+-----------------+
3007 | | {vm-type}\_int\_{network-role}\| comma\ |
3008 | | _ips | _delimited\_list|
3009 | +--------------------------------+-----------------+
3010 | | {vm-type}\_int\_{network-role}\| string |
3011 | | _v6\_ip\_{index} | |
3012 | +--------------------------------+-----------------+
3013 | | {vm-type}\_int\_{network-role}\| comma\ |
3014 | | _v6\_ips | _delimited\_list|
3015 +-------------------------+--------------------------------+-----------------+
3017 Table 6: Port Resource Property Parameters (Internal Networks)
3022 The property networks in the resource OS::Neutron::Port must be
3023 referenced by Neutron Network ID, a UUID value, or by the network name
3024 defined in OpenStack.
3029 R-93272 The VNF Heat Orchestration Template **MUST** adhere to the following parameter naming
3030 convention in the Heat Orchestration Template, when the parameter
3031 associated with the property network is referencing an “external” network:
3033 - {network-role}\_net\_id for the Neutron network ID
3035 - {network-role}\_net\_name for the network name in OpenStack
3037 The parameter must be declared as type: string
3039 The parameter must not be enumerated in the Heat environment file.
3041 *Example Parameter Definition*
3043 .. code-block:: yaml
3046 {network-role}_net_id:
3048 description: Neutron UUID for the {network-role} network
3049 {network-role}_net_name:
3051 description: Neutron name for the {network-role} network
3053 *Example: One Cloud Assigned IP Address (DHCP) assigned to a network
3054 that has only one subnet*
3056 In this example, the {network-role} has been defined as oam to represent
3057 an oam network and the {vm-type} has been defined as lb for load
3058 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3059 to assign IP addresses.
3061 .. code-block:: yaml
3066 description: Neutron UUID for the oam network
3070 type: OS::Neutron::Port
3071 network: { get_param: oam_net_id }
3076 R-65373 The VNF Heat Orchestration Template **MUST** adhere to the following parameter naming
3077 convention, when the parameter associated with the property network is
3078 referencing an “internal” network:
3080 - int\_{network-role}\_net\_id for the Neutron network ID
3082 - int\_{network-role}\_net\_name for the network name in OpenStack
3084 The parameter must be declared as type: string
3086 The assumption is that internal networks are created in the base module.
3087 The Neutron Network ID will be passed as an output parameter (e.g., ONAP
3088 Base Module Output Parameter) to the incremental modules. In the
3089 incremental modules, it will be defined as input parameter.
3091 *Example Parameter Definition*
3093 .. code-block:: yaml
3096 int_{network-role}_net_id:
3098 description: Neutron UUID for the {network-role} network
3099 int_{network-role}_net_name:
3101 description: Neutron name for the {network-role} network
3103 Property: fixed\_ips, Map Property: subnet\_id
3104 ++++++++++++++++++++++++++++++++++++++++++++++
3106 The property fixed\_ips is used to assign IPs to a port. The Map
3107 Property subnet\_id specifies the subnet the IP is assigned from.
3109 The property fixed\_ips and Map Property subnet\_id must be used if a
3110 Cloud (i.e., DHCP) IP address assignment is being requested and the
3111 Cloud IP address assignment is targeted at a specific subnet when two or
3114 The property fixed\_ips and Map Property subnet\_id should not be used
3115 if all IP assignments are fixed, or if the Cloud IP address assignment
3116 does not target a specific subnet or there is only one subnet.
3118 Note that DHCP assignment of IP addresses is also referred to as cloud
3119 assigned IP addresses.
3121 Subnet of an External Networks
3122 ______________________________
3124 R-47716 The VNF Heat Orchestration Template **MUST** adhere to the following parameter naming
3125 convention for the property fixed\_ips and Map Property subnet\_id
3126 parameter, when the parameter is referencing a subnet of an
3129 - {network-role}\_subnet\_id if the subnet is an IPv4 subnet
3131 - {network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
3133 The parameter must be declared as type: string
3135 The parameter must not be enumerated in the Heat environment file.
3137 *Example Parameter Definition*
3139 .. code-block:: yaml
3142 {network-role}_subnet_id:
3144 description: Neutron subnet UUID for the {network-role} network
3146 {network-role}_v6_subnet_id:
3148 description: Neutron subnet UUID for the {network-role} network
3150 *Example: One Cloud Assigned IPv4 Address (DHCP) assigned to a network
3151 that has two or more subnets subnet:*
3153 In this example, the {network-role} has been defined as oam to represent
3154 an oam network and the {vm-type} has been defined as lb for load
3155 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3156 to assign IP addresses.
3158 .. code-block:: yaml
3163 description: Neutron UUID for the oam network
3167 description: Neutron subnet UUID for the oam network
3171 type: OS::Neutron::Port
3172 network: { get_param: oam_net_id }
3174 - subnet_id: { get_param: oam_subnet_id }
3176 *Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6
3177 address assigned to a network that has at least one IPv4 subnet and one
3180 In this example, the {network-role} has been defined as oam to represent
3181 an oam network and the {vm-type} has been defined as lb for load
3184 .. code-block:: yaml
3189 description: Neutron UUID for the oam network
3193 description: Neutron subnet UUID for the oam network
3197 description: Neutron subnet UUID for the oam network
3201 type: OS::Neutron::Port
3203 network: { get_param: oam_net_id }
3205 - subnet_id: { get_param: oam_subnet_id }
3206 - subnet_id: { get_param: oam_v6_subnet_id }
3211 R-20106 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention for
3212 the property fixed\_ips and Map Property subnet\_id parameter,
3213 when the parameter is referencing the subnet of an “internal” network:
3215 - int\_{network-role}\_subnet\_id if the subnet is an IPv4 subnet
3217 - int\_{network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
3219 The parameter must be declared as type: string
3221 The assumption is that internal networks are created in the base module.
3222 The Neutron subnet network ID will be passed as an output parameter
3223 (e.g., ONAP Base Module Output Parameter) to the incremental modules. In
3224 the incremental modules, it will be defined as input parameter.
3226 *Example Parameter Definition*
3228 .. code-block:: yaml
3231 int_{network-role}_subnet_id:
3233 description: Neutron subnet UUID for the {network-role} network
3235 int_{network-role}_v6_subnet_id:
3237 description: Neutron subnet UUID for the {network-role} network
3239 Property: fixed\_ips, Map Property: ip\_address
3240 +++++++++++++++++++++++++++++++++++++++++++++++
3242 The property fixed\_ips is used to assign IPs to a port. The Map
3243 Property ip\_address specifies the IP address to be assigned to the
3246 The property fixed\_ips and Map Property ip\_address must be used when
3247 statically assigning one or more IP addresses to a port. This is also
3248 referred to as ONAP SDN-C IP address assignment. ONAP’s SDN-C provides
3249 the IP address assignment.
3251 An IP address is assigned to a port on a VM (referenced by {vm-type})
3252 that is connected to an external network (referenced by {network-role})
3253 or internal network (referenced by int\_{network-role}).
3255 R-41177 The VNF Heat Orchestration Template **MUST** include {vm-type} and {network-role}
3256 in the parameter name, when a SDN-C IP assignment is made to a
3257 port connected to an external network.
3259 When a SDN-C IP assignment is made to a port connected to an internal
3260 network, the parameter name must contain {vm-type} and
3261 int\_{network-role}.
3263 IP Address Assignments on External Networks
3264 ___________________________________________
3266 When the property fixed\_ips and Map Property ip\_address is used to
3267 assign IP addresses to an external network, the parameter name is
3268 dependent on the parameter type (comma\_delimited\_list or string) and
3269 IP address type (IPv4 or IPv6).
3271 R-84898 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention,
3272 when the parameter for property fixed\_ips and Map Property ip\_address
3273 is declared type: comma\_delimited\_list:
3275 - {vm-type}\_{network-role}\_ips for IPv4 address
3277 - {vm-type}\_{network-role}\_v6\_ips for IPv6 address
3279 Each element in the IP list should be assigned to successive instances
3280 of {vm-type} on {network-role}.
3282 The parameter must not be enumerated in the Heat environment file.
3284 *Example Parameter Definition*
3286 .. code-block:: yaml
3290 {vm-type}_{network-role}_ips:
3291 type: comma_delimited_list
3292 description: Fixed IPv4 assignments for {vm-type} VMs on the {Network-role} network
3294 {vm-type}_{network-role}_v6_ips:
3295 type: comma_delimited_list
3296 description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
3298 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
3299 Assignments to an external network*
3301 In this example, the {network-role} has been defined as oam to represent
3302 an oam network and the {vm-type} has been defined as db for database.
3304 .. code-block:: yaml
3309 description: Neutron UUID for a oam network
3312 type: comma_delimited_list
3313 description: Fixed IPv4 assignments for db VMs on the oam network
3316 type: comma_delimited_list
3317 description: Fixed IPv6 assignments for db VMs on the oam network
3321 type: OS::Neutron::Port
3322 network: { get_param: oam_net_id }
3323 fixed_ips: [ { “ip_address”: {get_param: [ db_oam_ips, 0 ]}}, {“ip_address”: {get_param: [ db_oam_v6_ips, 0 ]}}]
3326 type: OS::Neutron::Port
3328 network: { get_param: oam_net_id }
3330 - “ip_address”: {get_param: [ db_oam_ips, 1 ]}
3331 - “ip_address”: {get_param: [ db_oam_v6_ips, 1 ]}
3333 R-34960 The VNF Heat Orchestration Template **MUST** adhere to the following
3335 when the parameter for property fixed\_ips and Map Property ip\_address
3336 is declared type: string:
3338 - {vm-type}\_{network-role}\_ip\_{index} for an IPv4 address
3340 - {vm-type}\_{network-role}\_v6\_ip\_{index} for an IPv6 address
3342 The value for {index} must start at zero (0) and increment by one.
3344 The parameter must not be enumerated in the Heat environment file.
3346 *Example Parameter Definition*
3348 .. code-block:: yaml
3351 {vm-type}_{network-role}_ip_{index}:
3353 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
3355 {vm-type}_{network-role}_v6_ip_{index}:
3357 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
3359 *Example: string parameters for IPv4 and IPv6 Address Assignments
3360 to an external network*
3362 In this example, the {network-role} has been defined as “oam” to
3363 represent an oam network and the {vm-type} has been defined as “db” for
3366 .. code-block:: yaml
3371 description: Neutron UUID for an OAM network
3375 description: Fixed IPv4 assignment for db VM 0 on the OAM network
3379 description: Fixed IPv4 assignment for db VM 1 on the OAM network
3383 description: Fixed IPv6 assignment for db VM 0 on the OAM network
3387 description: Fixed IPv6 assignment for db VM 1 on the OAM network
3391 type: OS::Neutron::Port
3393 network: { get_param: oam_net_id }
3394 fixed_ips: [ { “ip_address”: {get_param: db_oam_ip_0}}, {“ip_address”: {get_param: db_oam_v6_ip_0 ]}}]
3397 type: OS::Neutron::Port
3399 network: { get_param: oam_net_id }
3401 - “ip_address”: {get_param: db_oam_ip_1}}]
3402 - “ip_address”: {get_param: db_oam_v6_ip_1}}]
3404 IP Address Assignment on Internal Networks
3405 __________________________________________
3407 When the property fixed\_ips and Map Property ip\_address is used to
3408 assign IP addresses to an internal network, the parameter name is
3409 dependent on the parameter type (comma\_delimited\_list or string) and
3410 IP address type (IPv4 or IPv6).
3412 R-62584 The VNF Heat Orchestration Template **MUST** adhere to
3413 the following naming convention,
3414 when the parameter for property fixed\_ips and Map Property ip\_address
3415 is declared type: comma\_delimited\_list:
3417 - {vm-type}\_int\_{network-role}\_ips for IPv4 address
3419 - {vm-type}\_int\_{network-role}\_v6\_ips for IPv6 address
3421 Each element in the IP list should be assigned to successive instances
3422 of {vm-type} on {network-role}.
3424 The parameter must be enumerated in the Heat environment file. Since an
3425 internal network is local to the VNF, IP addresses can be re-used at
3428 *Example Parameter Definition*
3430 .. code-block:: yaml
3434 {vm-type}_int_{network-role}_ips:
3435 type: comma_delimited_list
3436 description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
3438 {vm-type}_int_{network-role}_v6_ips:
3439 type: comma_delimited_list
3440 description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
3442 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
3443 Assignments to an internal network*
3445 In this example, the {network-role} has been defined as oam\_int to
3446 represent an oam network internal to the vnf. The role oam\_int was
3447 picked to differentiate from an external oam network with a
3448 {network-role} of oam. The {vm-type} has been defined as db for
3451 .. code-block:: yaml
3456 description: Neutron UUID for the oam internal network
3459 type: comma_delimited_list
3460 description: Fixed IPv4 assignments for db VMs on the oam internal network
3462 db_int_oam_int_v6_ips:
3463 type: comma_delimited_list
3464 description: Fixed IPv6 assignments for db VMs on the oam internal network
3468 type: OS::Neutron::Port
3470 network: { get_param: int_oam_int_net_id }
3471 fixed_ips: [ { “ip_address”: {get_param: [ db_int_oam_int_ips, 0]}}, { “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 0 ]}}]
3474 type: OS::Neutron::Port
3476 network: { get_param: int_oam_int_net_id }
3478 - “ip_address”: {get_param: [ db_int_oam_int_ips, 1 ]}
3479 - “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 1 ]}
3481 R-29256 The VNF Heat Orchestration Template **MUST** must adhere to the following
3483 when the parameter for property fixed\_ips and Map Property ip\_address
3484 is declared type: string:
3486 - {vm-type}\_int\_{network-role}\_ip\_{index} for an IPv4 address
3488 - {vm-type}\_int\_{network-role}\_v6\_ip\_{index} for an IPv6 address
3490 The value for {index} must start at zero (0) and increment by one.
3492 The parameter must be enumerated in the Heat environment file. Since an
3493 internal network is local to the VNF, IP addresses can be re-used at
3496 *Example Parameter Definition*
3498 .. code-block:: yaml
3502 {vm-type}_int_{network-role}_ip_{index}:
3504 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
3506 {vm-type}_int_{network-role}_v6_ip_{index}:
3508 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
3510 *Example: string parameters for IPv4 and IPv6 Address Assignments
3511 to an internal network*
3513 In this example, the {network-role} has been defined as oam\_int to
3514 represent an oam network internal to the vnf. The role oam\_int was
3515 picked to differentiate from an external oam network with a
3516 {network-role} of oam. The {vm-type} has been defined as db for
3519 .. code-block:: yaml
3524 description: Neutron UUID for an OAM internal network
3528 description: Fixed IPv4 assignment for db VM on the oam_int network
3532 description: Fixed IPv4 assignment for db VM 1 on the oam_int network
3536 description: Fixed IPv6 assignment for db VM 0 on the oam_int network
3540 description: Fixed IPv6 assignment for db VM 1 on the oam_int network
3544 type: OS::Neutron::Port
3546 network: { get_param: int_oam_int_net_id }
3547 fixed_ips: [ { “ip_address”: {get_param: db_oam_int_ip_0}}, {“ip_address”: {get_param: db_oam_int_v6_ip_0 ]}}]
3550 type: OS::Neutron::Port
3552 network: { get_param: int_oam_int_net_id }
3554 - “ip_address”: {get_param: db_oam_int_ip_1}}]
3555 - “ip_address”: {get_param: db_oam_int_v6_ip_1}}]
3557 Property: allowed\_address\_pairs, Map Property: ip\_address
3558 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3560 The property allowed\_address\_pairs in the resource OS::Neutron::Port
3561 allows the user to specify a mac\_address and/or ip\_address that will
3562 pass through a port regardless of subnet. This enables the use of
3563 protocols such as VRRP, which floats an IP address between two instances
3564 to enable fast data plane failover. The map property ip\_address
3565 specifies the IP address.
3567 The allowed\_address\_pairs is an optional property. It is not required.
3569 An ONAP Heat Orchestration Template allows the assignment of one IPv4
3570 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
3571 and {network-role}/int\_{network-role} combination.
3573 An ONAP Heat Orchestration Template allows the assignment of one IPv6
3574 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
3575 and {network-role}/int\_{network-role} combination.
3577 Note that the management of these IP addresses (i.e. transferring
3578 ownership between active and standby VMs) is the responsibility of the
3581 Note that these parameters are **not** intended to represent Neutron
3582 “Floating IP” resources, for which OpenStack manages a pool of public IP
3583 addresses that are mapped to specific VM ports. In that case, the
3584 individual VMs are not even aware of the public IPs, and all assignment
3585 of public IPs to VMs is via OpenStack commands. ONAP does not support
3586 Neutron-style Floating IPs.
3591 R-61282 The VNF Heat Orchestration Template **MUST**
3592 adhere to the following naming convention for the property
3593 allowed\_address\_pairs and Map Property ip\_address parameter,
3594 when the parameter is referencing an “external” network:
3596 - {vm-type}\_{network-role}\_floating\_ip for an IPv4 address
3598 - {vm-type}\_{network-role}\_floating\_v6\_ip for an IPv6 address
3600 The parameter must be declared as type: string
3602 The parameter must not be enumerated in the Heat environment file.
3604 *Example Parameter Definition*
3606 .. code-block:: yaml
3610 {vm-type}_{network-role}_floating_ip:
3612 description: VIP for {vm-type} VMs on the {network-role} network
3614 {vm-type}_{network-role}_floating_v6_ip:
3616 description: VIP for {vm-type} VMs on the {network-role} network
3620 In this example, the {network-role} has been defined as oam to represent
3621 an oam network and the {vm-type} has been defined as db for database.
3623 .. code-block:: yaml
3628 description: Neutron UUID for the oam network
3631 type: comma_delimited_list
3632 description: Fixed IPs for db VMs on the oam network
3636 description: VIP IP for db VMs on the oam network
3640 type: OS::Neutron::Port
3642 network: { get_param: oam_net_id }
3643 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,0] }}]
3644 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
3647 type: OS::Neutron::Port
3649 network: { get_param: oam_net_id }
3650 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,1] }}]
3651 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
3656 R-16805 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention
3657 for the property allowed\_address\_pairs and Map Property ip\_address
3658 parameter when the parameter is referencing an “internal” network.
3660 - {vm-type}\_int\_{network-role}\_floating\_ip for an IPv4 address
3662 - {vm-type}\_int\_{network-role}\_floating\_v6\_ip for an IPv6 address
3664 The parameter must be declared as type: string
3666 The parameter must be enumerated in the Heat environment file.
3668 *Example Parameter Definition*
3670 .. code-block:: yaml
3674 {vm-type}_int_{network-role}_floating_ip:
3676 description: VIP for {vm-type} VMs on the int_{network-role} network
3678 {vm-type}_int_{network-role}_floating_v6_ip:
3680 description: VIP for {vm-type} VMs on the int_{network-role} network
3682 Multiple allowed\_address\_pairs for a {vm-type} / {network-role} combination
3683 __________________________________________________________________
3685 The parameter {vm-type}\_{network-role}\_floating\_ip provides only one
3686 allowed address pair IPv4 address per {vm-type} and {network-role} pair.
3688 The parameter {vm-type}\_{network-role}\_floating\_v6\_ip provides only
3689 one allowed address pair IPv6 address per {vm-type} and {network-role}
3692 If there is a need for multiple allowed address pair IPs for a given
3693 {vm-type} and {network-role} combination within a VNF, then the
3694 parameter names defined for the property fixed\_ips and Map Property
3695 ip\_address should be used with the allowed\_address\_pairs property.
3696 The examples below illustrate this.
3698 *Example: A VNF has four load balancers. Each pair has a unique VIP.*
3700 In this example, there are two administrative VM pairs. Each pair has
3701 one VIP. The {network-role} has been defined as oam to represent an oam
3702 network and the {vm-type} has been defined as admin for an
3705 Pair 1: Resources admin\_0\_port\_0 and admin\_1\_port\_0 share a unique
3706 VIP, [admin\_oam\_ips,2]
3708 Pair 2: Resources admin\_2\_port\_0 and admin\_3\_port\_0 share a unique
3709 VIP, [admin\_oam\_ips,5]
3711 .. code-block:: yaml
3716 description: Neutron UUID for the oam network
3718 type: comma_delimited_list
3719 description: Fixed IP assignments for admin VMs on the oam network
3724 type: OS::Neutron::Port
3726 network: { get_param: oam_net_id }
3727 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,0] }}]
3728 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
3731 type: OS::Neutron::Port
3733 network: { get_param: oam_net_id }
3734 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,1] }}]
3735 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
3738 type: OS::Neutron::Port
3740 network: { get_param: oam_net_id }
3741 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,3] }}]
3742 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
3745 type: OS::Neutron::Port
3747 network: { get_param: oam_net_id }
3748 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,4] }}]
3749 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
3751 *Example: A VNF has two load balancers. The pair of load balancers share
3754 In this example, there is one load balancer pairs. The pair has two
3755 VIPs. The {network-role} has been defined as oam to represent an oam
3756 network and the {vm-type} has been defined as lb for a load balancer VM.
3758 .. code-block:: yaml
3762 type: OS::Neutron::Port
3764 network: { get_param: oam_net_id }
3765 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,0] }}]
3766 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
3769 type: OS::Neutron::Port
3771 network: { get_param: oam_net_id }
3772 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,1] }}]
3773 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
3775 As a general rule, provide the fixed IPs for the VMs indexed first in
3776 the CDL and then the VIPs as shown in the examples above.
3778 ONAP SDN-C Assignment of allowed\_address\_pair IP Addresses
3779 __________________________________________________________________
3781 The following items must be taken into consideration when designing Heat
3782 Orchestration Templates that expect ONAP’s SDN-C to assign
3783 allowed\_address\_pair IP addresses via automation.
3785 The VMs must be of the same {vm-type}.
3787 The VMs must be created in the same module (base or incremental).
3789 Resource Property “name”
3790 ~~~~~~~~~~~~~~~~~~~~~~~~
3792 The parameter naming convention of the property name for the resource
3793 OS::Nova::Server has been defined in
3794 `Resource: OS::Nova::Server – Metadata Parameters`_.
3796 This section provides the requirements how the property name for non
3797 OS::Nova::Server resources must be defined when the property is used.
3798 Not all resources require the property name (e.g., it is optional) and
3799 some resources do not support the property.
3801 R-85734 The VNF Heat Orchestration Template **MUST** use the intrinsic function str\_replace
3802 in conjunction with the ONAP supplied metadata parameter
3803 vnf\_name to generate a unique value,
3804 when the property name for a non OS::Nova::Server resources is defined
3805 in a Heat Orchestration Template.
3807 This prevents the enumeration of a
3808 unique value for the property name in a per instance environment file.
3812 - In most cases, only the use of the metadata value vnf\_name is
3813 required to create a unique property name
3815 - the Heat Orchestration Template pseudo parameter 'OS::stack\_name’
3816 may also be used in the str\_replace construct to generate a unique
3817 name when the vnf\_name does not provide uniqueness
3819 *Example: Property* name *for resource* OS::Neutron::SecurityGroup
3821 .. code-block:: yaml
3825 type: OS::Neutron::SecurityGroup
3827 description: vDNS security group
3830 template: VNF_NAME_sec_grp_DNS
3832 VNF_NAME: {get_param: vnf_name}
3836 *Example: Property name for resource* OS::Cinder::Volume
3838 .. code-block:: yaml
3842 type: OS::Cinder::Volume
3844 description: Cinder Volume
3847 template: VNF_NAME_STACK_NAME_dns_volume
3849 VNF_NAME: {get_param: vnf_name}
3850 STACK_NAME: { get_param: 'OS::stack_name' }
3853 Contrail Issue with Values for the Property Name
3854 ++++++++++++++++++++++++++++++++++++++++++++++++
3856 The Contrail GUI has a limitation displaying special characters. The
3857 issue is documented in
3858 https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is
3859 recommended that special characters be avoided. However, if special
3860 characters must be used, note that for the following resources:
3874 the only special characters supported are:
3876 - “ ! $ ‘ ( ) = ~ ^ \| @ \` { } [ ] > , . \_
3878 ONAP Output Parameter Names
3879 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
3881 ONAP defines three types of Output Parameters as detailed in
3882 `Output Parameters`_.
3884 ONAP Base Module Output Parameters:
3885 +++++++++++++++++++++++++++++++++++
3887 ONAP Base Module Output Parameters do not have an explicit naming
3888 convention. The parameter name must contain {vm-type} and {network-role}
3891 ONAP Volume Template Output Parameters:
3892 +++++++++++++++++++++++++++++++++++++++
3894 ONAP Base Module Output Parameters do not have an explicit naming
3895 convention. The parameter name must contain {vm-type} when appropriate.
3897 Predefined Output Parameters
3898 ++++++++++++++++++++++++++++
3900 ONAP currently defines one predefined output parameter the OAM
3901 Management IP Addresses.
3903 OAM Management IP Addresses
3904 ___________________________
3906 A VNF may have a management interface for application controllers to
3907 interact with and configure the VNF. Typically, this will be via a
3908 specific VM that performs a VNF administration function. The IP address
3909 of this interface must be captured and inventoried by ONAP. The IP
3910 address might be a VIP if the VNF contains an HA pair of management VMs,
3911 or may be a single IP address assigned to one VM.
3913 The Heat template may define either (or both) of the following Output
3914 parameters to identify the management IP address.
3916 - oam\_management\_v4\_address
3918 - oam\_management\_v6\_address
3922 - The use of this output parameters are optional.
3924 - The Management IP Address should be defined only once per VNF, so it
3925 must only appear in one Module template
3927 - If a fixed IP for the admin VM is passed as an input parameter, it
3928 may be echoed in the output parameters. In this case, a IPv4 and/or
3929 IPv6 parameter must be defined in the parameter section of the YAML
3930 Heat template. The parameter maybe named oam\_management\_v4\_address
3931 and/or oam\_management\_v6\_address or may be named differently.
3933 - If the IP for the admin VM is obtained via DHCP, it may be obtained
3934 from the resource attributes. In this case,
3935 oam\_management\_v4\_address and/or oam\_management\_v6\_address must
3936 not be defined in the parameter section of the YAML Heat template.
3938 *Example: SDN-C Assigned IP Address echoed as*
3939 oam\_management\_v4\_address
3941 .. code-block:: yaml
3946 description: Fixed IPv4 assignment for admin VM 0 on the OAM network
3950 admin_oam_net_0_port:
3951 type: OS::Neutron::Port
3955 template: VNF_NAME_admin_oam_net_0_port
3957 VNF_NAME: {get_param: vnf_name}
3958 network: { get_param: oam_net_id }
3959 fixed_ips: [{ "ip_address": { get_param: admin_oam_ip_0 }}]
3960 security_groups: [{ get_param: security_group }]
3963 type: OS::Nova::Server
3965 name: { get_param: admin_names }
3966 image: { get_param: admin_image_name }
3967 flavor: { get_param: admin_flavor_name }
3968 availability_zone: { get_param: availability_zone_0 }
3970 - port: { get_resource: admin_oam_net_0_port }
3972 vnf_id: { get_param: vnf_id }
3973 vf_module_id: { get_param: vf_module_id }
3974 vnf_name: {get_param: vnf_name }
3976 oam_management_v4_address:
3977 value: {get_param: admin_oam_ip_0 }
3979 *Example: Cloud Assigned IP Address output as*
3980 oam\_management\_v4\_address
3982 .. code-block:: yaml
3987 admin_oam_net_0_port:
3988 type: OS::Neutron::Port
3992 template: VNF_NAME_admin_oam_net_0_port
3994 VNF_NAME: {get_param: vnf_name}
3995 network: { get_param: oam_net_id }
3996 security_groups: [{ get_param: security_group }]
3999 type: OS::Nova::Server
4001 name: { get_param: admin_names }
4002 image: { get_param: admin_image_name }
4003 flavor: { get_param: admin_flavor_name }
4004 availability_zone: { get_param: availability_zone_0 }
4006 - port: { get_resource: admin_oam_net_0_port }
4008 vnf_id: { get_param: vnf_id }
4009 vf_module_id: { get_param: vf_module_id }
4010 vnf_name: {get_param: vnf_name }
4013 oam_management_v4_address:
4014 value: {get_attr: [admin_server, networks, {get_param: oam_net_id}, 0] }
4016 Contrail Resource Parameters
4017 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4019 ONAP requires the parameter names of certain Contrail Resources to
4020 follow specific naming conventions. This section provides these
4023 Contrail Network Parameters
4024 +++++++++++++++++++++++++++
4026 Contrail based resources may require references to a Contrail network
4027 using the network FQDN.
4032 When the parameter associated with the Contrail Network is referencing
4033 an “external” network, the parameter must adhere to the following naming
4034 convention in the Heat Orchestration Template
4036 - {network-role}\_net\_fqdn
4038 The parameter must be declared as type: string
4040 The parameter must not be enumerated in the Heat environment file.
4042 *Example: Parameter declaration*
4044 .. code-block:: yaml
4047 {network-role}_net_fqdn:
4049 description: Contrail FQDN for the {network-role} network
4051 *Example: Contrail Resource OS::ContrailV2::VirtualMachineInterface
4052 Reference to a Network FQDN.*
4054 In this example, the {network-role} has been defined as oam to represent
4055 an oam network and the {vm-type} has been defined as fw for firewall.
4056 The Contrail resource OS::ContrailV2::VirtualMachineInterface property
4057 virtual\_network\_refs references a contrail network FQDN.
4059 .. code-block:: yaml
4062 type: OS::ContrailV2::VirtualMachineInterface
4066 template: VM_NAME_virtual_machine_interface_1
4068 VM_NAME: { get_param: fw_name_0 }
4069 virtual_machine_interface_properties:
4070 virtual_machine_interface_properties_service_interface_type: { get_param: oam_protected_interface_type }
4071 virtual_network_refs:
4072 - get_param: oam_net_fqdn
4073 security_group_refs:
4074 - get_param: fw_sec_grp_id
4076 Interface Route Table Prefixes for Contrail InterfaceRoute Table
4077 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4079 The parameter associated with the resource
4080 OS::ContrailV2::InterfaceRouteTable property
4081 interface\_route\_table\_routes, map property
4082 interface\_route\_table\_routes\_route\_prefix is an ONAP Orchestration
4085 The parameters must be named {vm-type}\_{network-role}\_route\_prefixes
4086 in the Heat Orchestration Template.
4088 The parameter must be declared as type: json
4090 The parameter supports IP addresses in the format:
4092 1. Host IP Address (e.g., 10.10.10.10)
4094 2. CIDR Notation format (e.g., 10.0.0.0/28)
4096 The parameter must not be enumerated in the Heat environment file.
4098 *Example Parameter Definition*
4100 .. code-block:: yaml
4103 {vm-type}_{network-role}_route_prefixes:
4105 description: JSON list of Contrail Interface Route Table route prefixes
4109 .. code-block:: yaml
4114 description: Unique name for this VF instance
4115 fw_int_fw_route_prefixes:
4117 description: prefix for the ServiceInstance InterfaceRouteTable
4118 int_fw_dns_trusted_interface_type:
4120 description: service_interface_type for ServiceInstance
4123 type: OS::ContrailV2::InterfaceRouteTable
4124 depends_on: [*resource name of* *OS::ContrailV2::ServiceInstance*]
4128 template: VNF_NAME_interface_route_table
4130 VNF_NAME: { get_param: vnf_name }
4131 interface_route_table_routes:
4132 interface_route_table_routes_route: { get_param: fw_int_fw_route_prefixes }
4133 service_instance_refs:
4134 - get_resource: < *resource name of* *OS::ContrailV2::ServiceInstance* >
4135 service_instance_refs_data:
4136 - service_instance_refs_data_interface_type: { get_param: int_fw_interface_type }
4138 Parameter Names in Contrail Resources
4139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4141 Contrail Heat resource properties will use, when appropriate, the same
4142 naming convention as OpenStack Heat resources. For example, the resource
4143 OS::ContrailV2::InstanceIp has two properties that the parameter naming
4144 convention is identical to properties in OS::Neutron::Port.
4146 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4147 instance\_ip\_address*
4149 The property instance\_ip\_address uses the same parameter naming
4150 convention as the property fixed\_ips and Map Property ip\_address in
4151 OS::Neutron::Port. The resource is assigning an ONAP SDN-C Assigned IP
4152 Address. The {network-role} has been defined as oam\_protected to
4153 represent an oam protected network and the {vm-type} has been defined as
4156 .. code-block:: yaml
4158 CMD_FW_OAM_PROTECTED_RII:
4159 type: OS::ContrailV2::InstanceIp
4161 - FW_OAM_PROTECTED_RVMI
4163 virtual_machine_interface_refs:
4164 - get_resource: FW_OAM_PROTECTED_RVMI
4165 virtual_network_refs:
4166 - get_param: oam_protected_net_fqdn
4167 instance_ip_address: { get_param: [fw_oam_protected_ips, get_param: index ] }
4169 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4172 The property instance\_ip\_address uses the same parameter naming
4173 convention as the property fixed\_ips and Map Property subnet\_id in
4174 OS::Neutron::Port. The resource is assigning a Cloud Assigned IP
4175 Address. The {network-role} has been defined as “oam\_protected” to
4176 represent an oam protected network and the {vm-type} has been defined as
4179 .. code-block:: yaml
4181 CMD_FW_SGI_PROTECTED_RII:
4182 type: OS::ContrailV2::InstanceIp
4184 - FW_OAM_PROTECTED_RVMI
4186 virtual_machine_interface_refs:
4187 - get_resource: FW_OAM_PROTECTED_RVMI
4188 virtual_network_refs:
4189 - get_param: oam_protected_net_fqdn
4190 subnet_uuid: { get_param: oam_protected_subnet_id }
4192 Cinder Volume Templates
4193 ^^^^^^^^^^^^^^^^^^^^^^^^
4195 ONAP supports the independent deployment of a Cinder volume via separate
4196 Heat Orchestration Templates, the Cinder Volume module. This allows the
4197 volume to persist after VNF deletion so that they can be reused on
4198 another instance (e.g., during a failover activity).
4200 A Base Module or Incremental Module may have a corresponding volume
4201 module. Use of separate volume modules is optional. A Cinder volume may
4202 be embedded within the Base Module or Incremental Module if persistence
4205 R-47788 The VNF Heat Orchestration Template **MUST** have a 1:1 scope of a cinder volume module,
4206 when it exists, with the Base Module or Incremental Module
4208 A single volume module must create only the volumes
4209 required by a single Incremental module or Base module.
4211 The following rules apply to independent volume Heat templates:
4213 - Cinder volumes must be created in a separate Heat Orchestration
4214 Template from the Base Module or Incremental Module.
4216 - A single Cinder volume module must include all Cinder volumes
4217 needed by the Base/Incremental module.
4219 - R-79531 The VNF Heat Orchestration Template **MUST** define “outputs” in the volume
4220 template for each Cinder volume resource universally unique
4221 identifier (UUID) (i.e. ONAP Volume Template Output Parameters).
4223 - The VNF Incremental Module or Base Module must define input
4224 parameters that match each Volume output parameter (i.e., ONAP Volume
4225 Template Output Parameters).
4227 - ONAP will supply the volume template outputs automatically to the
4228 bases/incremental template input parameters.
4230 - Volume modules may utilize nested Heat templates.
4232 *Examples: Volume Template*
4234 A VNF has a Cinder volume module, named incremental\_volume.yaml, that
4235 creates an independent Cinder volume for a VM in the module
4236 incremental.yaml. The incremental\_volume.yaml defines a parameter in
4237 the output section, lb\_volume\_id\_0 which is the UUID of the cinder
4238 volume. lb\_volume\_id\_0 is defined as a parameter in incremental.yaml.
4239 ONAP captures the UUID value of lb\_volume\_id\_0 from the volume module
4240 output statement and provides the value to the incremental module.
4242 Note that the example below is not a complete Heat Orchestration
4243 Template. The {vm-type} has been defined as “lb” for load balancer
4245 incremental\_volume.yaml
4247 .. code-block:: yaml
4258 type: OS::Cinder::Volume
4262 template: VNF_NAME_volume_0
4264 VNF_NAME: { get_param: vnf_name }
4265 size: {get_param: dns_volume_size_0}
4270 value: {get_resource: dns_volume_0}
4276 .. code-block:: yaml
4287 type: OS::Nova::Server
4289 name: {get_param: dns_name_0}
4294 type: OS::Cinder::VolumeAttachment
4296 instance_uuid: { get_resource: lb_0 }
4297 volume_id: { get_param: lb_volume_id_0 }
4299 ONAP Support of Environment Files
4300 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4302 The use of an environment file in OpenStack is optional. In ONAP, it is
4305 R-86285 The VNF Heat Orchestration Template **MUST** have a
4306 corresponding environment file, even if no parameters are required to be
4309 (Note that ONAP, the open source version of ONAP, does not
4310 programmatically enforce the use of an environment file.)
4312 R-67205 The VNF Heat Orchestration Template **MUST** have a corresponding
4313 environment file for a Base Module.
4315 R-35727 The VNF Heat Orchestration Template **MUST** have a
4316 corresponding environment file for an Incremental module.
4318 R-22656 The VNF Heat Orchestration Template **MUST** have a corresponding environment file
4319 for a Cinder Volume Module.
4321 A nested heat template must not have an environment file; OpenStack does
4324 The environment file must contain parameter values for the ONAP
4325 Orchestration Constants and VNF Orchestration Constants. These
4326 parameters are identical across all instances of a VNF type, and
4327 expected to change infrequently. The ONAP Orchestration Constants are
4328 associated with OS::Nova::Server image and flavor properties (See
4329 `Property: image`_ and `Property: flavor`_). Examples of VNF
4330 Orchestration Constants are the networking parameters associated
4331 with an internal network (e.g., private IP ranges) and Cinder
4334 The environment file must not contain parameter values for parameters
4335 that are instance specific (ONAP Orchestration Parameters, VNF
4336 Orchestration Parameters). These parameters are supplied to the Heat by
4337 ONAP at orchestration time.
4339 SDC Treatment of Environment Files
4340 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4342 Parameter values enumerated in the environment file are used by SDC as
4343 the default value. However, the SDC user may use the SDC GUI to
4344 overwrite the default values in the environment file.
4346 SDC generates a new environment file for distribution to MSO based on
4347 the uploaded environment file and the user provided GUI updates. The
4348 user uploaded environment file is discarded when the new file is
4349 created. Note that if the user did not change any values via GUI
4350 updates, the SDC generated environment file will contain the same values
4351 as the uploaded file.
4353 Use of Environment Files when using OpenStack “heat stack-create” CLI
4354 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4356 When ONAP is instantiating the Heat Orchestration Template, certain
4357 parameter must not be enumerated in the environment file. This document
4358 provides the details of what parameters should not be enumerated.
4360 If the Heat Orchestration Template is to be instantiated from the
4361 OpenStack Command Line Interface (CLI) using the command “heat
4362 stack-create”, all parameters must be enumerated in the environment
4365 Heat Template Constructs
4366 ^^^^^^^^^^^^^^^^^^^^^^^^^
4368 Nested Heat Templates
4369 ~~~~~~~~~~~~~~~~~~~~~
4371 ONAP supports nested Heat templates per the OpenStack specifications.
4372 Nested templates may be suitable for larger VNFs that contain many
4373 repeated instances of the same VM type(s). A common usage pattern is to
4374 create a nested template for each {vm-type} along with its supporting
4375 resources. The VNF module may then reference these component templates
4376 either statically by repeated definition or dynamically by using the
4377 resource OS::Heat::ResourceGroup.
4379 Nested Heat Template Requirements
4380 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4382 ONAP supports nested Heat Orchestration Templates. A Base Module,
4383 Incremental Module, and Cinder Volume Module may use nested heat.
4385 A Heat Orchestration Template may reference the nested heat statically
4386 by repeated definition.
4388 A Heat Orchestration Template may reference the nested heat dynamically
4389 using the resource OS::Heat::ResourceGroup.
4391 A Heat Orchestration template must have no more than three levels of
4392 nesting. ONAP supports a maximum of three levels.
4394 Nested heat templates must be referenced by file name. The use of
4395 resource\_registry in the environment file is not supported and must not
4398 R-89868 The VNF Heat Orchestration Template **MUST** have unique file names within the scope
4399 of the VNF for a nested heat yaml file.
4401 R-52530 The VNF Heat Orchestration Template **MUST NOT** use a directory hierarchy for
4402 nested templates. All templates must be in a single, flat directory
4405 A nested heat template may be used by any module within a given VNF.
4409 - Constrains must not be defined for any parameter enumerated in a
4410 nested heat template.
4412 - R-11041 The VNF Heat Orchestration Template **MUST** have the resource calling the
4413 nested yaml file pass in as properties all parameters defined
4414 in nested yaml file.
4416 - 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
4419 - With nested templates, outputs are required to expose any resource
4420 properties of the child templates to the parent template. Those would
4421 not explicitly be declared as parameters but simply referenced as
4422 get\_attribute targets against the “parent” resource.
4424 Nested Heat Template Example: Static
4425 ++++++++++++++++++++++++++++++++++++++
4429 .. code-block:: yaml
4435 dns_image_name: { get_param: dns_image_name }
4436 dns_flavor_name: { get_param: dns_flavor_name }
4437 availability_zone: { get_param: availability_zone_0 }
4438 security_group: { get_param: DNS_shared_sec_grp_id }
4439 oam_net_id: { get_param: oam_protected_net_id }
4440 dns_oam_ip: { get_param: dns_oam_ip_0 }
4441 dns_name: { get_param: dns_name_0 }
4442 vnf_name: { get_param: vnf_name }
4443 vnf_id: { get_param: vnf_id }
4444 vf_module_id: {get_param: vf_module_id}
4449 dns_image_name: { get_param: dns_image_name }
4450 dns_flavor_name: { get_param: dns_flavor_name }
4451 availability_zone: { get_param: availability_zone_1 }
4452 security_group: { get_param: DNS_shared_sec_grp_id }
4453 oam_net_id: { get_param: oam_protected_net_id }
4454 dns_oam_ip: { get_param: dns_oam_ip_1 }
4455 dns_name: { get_param: dns_name_1 }
4456 vnf_name: { get_param: vnf_name }
4457 vnf_id: { get_param: vnf_id }
4458 vf_module_id: {get_param: vf_module_id}
4462 .. code-block:: yaml
4465 type: OS::Neutron::Port
4469 template: VNF_NAME_dns_oam_port
4471 VNF_NAME: {get_param: vnf_name}
4472 network: { get_param: oam_net_id }
4473 fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}]
4474 security_groups: [{ get_param: security_group }]
4477 type: OS::Nova::Server
4479 name: { get_param: dns_names }
4480 image: { get_param: dns_image_name }
4481 flavor: { get_param: dns_flavor_name }
4482 availability_zone: { get_param: availability_zone }
4484 - port: { get_resource: dns_oam_0_port }
4486 vnf_id: { get_param: vnf_id }
4487 vf_module_id: { get_param: vf_module_id }
4488 vnf_name {get_param: vnf_name }
4490 Use of Heat ResourceGroup
4491 +++++++++++++++++++++++++
4493 The OS::Heat::ResourceGroup is a useful Heat element for creating
4494 multiple instances of a given resource or collection of resources.
4495 Typically, it is used with a nested Heat template, to create, for
4496 example, a set of identical OS::Nova::Server resources plus their
4497 related OS::Neutron::Port resources via a single resource in a master
4500 ResourceGroup may be used in ONAP to simplify the structure of a Heat
4501 template that creates multiple instances of the same VM type.
4503 However, there are important caveats to be aware of:
4505 ResourceGroup does not deal with structured parameters
4506 (comma-delimited-list and json) as one might typically expect. In
4507 particular, when using a list-based parameter, where each list element
4508 corresponds to one instance of the ResourceGroup, it is not possible to
4509 use the intrinsic “loop variable” %index% in the ResourceGroup
4512 For instance, the following is **not** valid Heat for ResourceGroup:
4514 .. code-block:: yaml
4516 type: OS::Heat::ResourceGroup
4518 type: my_nested_vm_template.yaml
4520 name: {get_param: [vm_name_list, %index%]}
4522 Although this appears to use the nth entry of the vm\_name\_list list
4523 for the nth element of the ResourceGroup, it will in fact result in a
4524 Heat exception. When parameters are provided as a list (one for each
4525 element of a ResourceGroup), you must pass the complete parameter to the
4526 nested template along with the current index as separate parameters.
4528 Below is an example of an **acceptable** Heat Syntax for a
4531 .. code-block:: yaml
4533 type: OS::Heat::ResourceGroup
4535 type: my_nested_vm_template.yaml
4537 names: {get_param: vm_name_list}
4540 You can then reference within the nested template as:
4542 { get\_param: [names, {get\_param: index} ] }
4544 ResourceGroup Property count
4545 ____________________________
4547 ONAP requires that the OS::Heat::ResourceGroup property count be defined
4548 (even if the value is one) and that the value must be enumerated in the
4549 environment file. This is required for ONAP to build the TOSCA model for
4552 .. code-block:: yaml
4554 type: OS::Heat::ResourceGroup
4556 count: { get_param: count }
4559 type: my_nested_vm_template.yaml
4561 names: {get_param: vm_name_list}
4564 Availability Zone and ResourceGroups
4565 ____________________________________
4567 The resource OS::Heat::ResourceGroup and the property availability\_zone
4568 has been an “issue” with a few VNFs since ONAP only supports
4569 availability\_zone as a string parameter and not a
4570 comma\_delimited\_list. This makes it difficult to use a ResourceGroup
4571 to create Virtual Machines in more than one availability zone.
4573 There are numerous solutions to this issue. Below are two suggested
4576 **Option 1:** create a CDL in the OS::Heat::ResourceGroup. In the
4577 resource type: OS::Heat::ResourceGroup, create a comma\_delimited\_list
4578 availability\_zones by using the intrinsic function list\_join.
4580 .. code-block:: yaml
4583 type: OS::Heat::ResourceGroup
4585 count: { get_param: node_count }
4591 avaialability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] }
4595 .. code-block:: yaml
4598 avaialability_zones:
4599 type: comma_delimited_list
4604 type: OS::Nova::Server
4606 name: { get_param: [ dns_names, get_param: index ] }
4607 image: { get_param: dns_image_name }
4608 flavor: { get_param: dns_flavor_name }
4609 availability_zone: { get_param: [ avaialability_zones, get_param: index ] }
4612 **Option 2:** Create a resource group per availability zone. A separate
4613 OS::Heat::ResourceGroup is created for each availability zone.
4618 Heat templates *should not* reference any HTTP-based resource
4619 definitions, any HTTP-based nested configurations, or any HTTP-based
4622 - During orchestration, ONAP *should not* retrieve any such resources
4623 from external/untrusted/unknown sources.
4625 - VNF images should not contain such references in user-data or other
4626 configuration/operational scripts that are specified via Heat or
4627 encoded into the VNF image itself.
4629 *Note:* HTTP-based references are acceptable if the HTTP-based reference
4630 is accessing information with the VM private/internal network.
4632 Heat Files Support (get\_file)
4633 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4635 Heat Templates may contain the inclusion of text files into Heat
4636 templates via the Heat get\_file directive. This may be used, for
4637 example, to define a common “user-data” script, or to inject files into
4638 a VM on startup via the “personality” property.
4640 Support for Heat Files is subject to the following limitations:
4642 R-76718 The VNF Heat Orchestration Template **MUST** reference the get\_files targets in
4643 Heat templates by file name, and the corresponding files should be
4644 delivered to ONAP along with the Heat templates.
4646 R-41888 The VNE Heat **MUST NOT** use URL-based file retrieval.
4648 R-62177 The VNF Heat Orchestration Template **MUST** have unique file names for the included
4649 files within the scope of the VNF.
4651 R-87848 The VNF Heat Orchestration Template **MUST** have all included files in a single, flat
4652 directory per VNF. ONAP does not support a directory hierarchy.
4654 - Included files may be used by all Modules within a given VNF.
4656 - get\_file directives may be used in both non-nested and nested
4662 When Nova Servers are created via Heat templates, they may be passed a
4663 “keypair” which provides an ssh key to the ‘root’ login on the newly
4664 created VM. This is often done so that an initial root key/password does
4665 not need to be hard-coded into the image.
4667 Key pairs are unusual in OpenStack, because they are the one resource
4668 that is owned by an OpenStack User as opposed to being owned by an
4669 OpenStack Tenant. As a result, they are usable only by the User that
4670 created the keypair. This causes a problem when a Heat template attempts
4671 to reference a keypair by name, because it assumes that the keypair was
4672 previously created by a specific ONAP user ID.
4674 When a keypair is assigned to a server, the SSH public-key is
4675 provisioned on the VMs at instantiation time. They keypair itself is not
4676 referenced further by the VM (i.e. if the keypair is updated with a new
4677 public key, it would only apply to subsequent VMs created with that
4680 Due to this behavior, the recommended usage of keypairs is in a more
4681 generic manner which does not require the pre-requisite creation of a
4682 keypair. The Heat should be structured in such a way as to:
4684 - Pass a public key as a parameter value instead of a keypair name
4686 - Create a new keypair within The VNF Heat Orchestration Template (in the base
4687 module) for use within that VNF
4689 By following this approach, the end result is the same as pre-creating
4690 the keypair using the public key – i.e., that public key will be
4691 provisioned in the new VM. However, this recommended approach also makes
4692 sure that a known public key is supplied (instead of having OpenStack
4693 generate a public/private pair to be saved and tracked outside of ONAP).
4694 It also removes any access/ownership issues over the created keypair.
4696 The public keys may be enumerated as a VNF Orchestration Constant in the
4697 environment file (since it is public, it is not a secret key), or passed
4698 at run-time as instance-specific parameters. ONAP will never
4699 automatically assign a public/private key pair.
4701 *Example (create keypair with an existing ssh public-key for {vm-type}
4702 of lb (for load balancer)):*
4704 .. code-block:: yaml
4714 type: OS::Nova::Keypair
4718 template: VNF_NAME_key_pair
4720 VNF_NAME: { get_param: vnf_name }
4721 public_key: {get_param: lb_ssh_public_key}
4722 save_private_key: false
4727 OpenStack allows a tenant to create Security groups and define rules
4728 within the security groups.
4730 Security groups, with their rules, may either be created in the Heat
4731 Orchestration Template or they can be pre-created in OpenStack and
4732 referenced within the Heat template via parameter(s). There can be a
4733 different approach for security groups assigned to ports on internal
4734 (intra-VNF) networks or external networks (inter-VNF). Furthermore,
4735 there can be a common security group across all VMs for a specific
4736 network or it can vary by VM (i.e., {vm-type}) and network type (i.e.,
4739 Anti-Affinity and Affinity Rules
4740 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4742 Anti-affinity or affinity rules are supported using normal OpenStack
4743 OS::Nova::ServerGroup resources. Separate ServerGroups are typically
4744 created for each VM type to prevent them from residing on the same host,
4745 but they can be applied to multiple VM types to extend the
4746 affinity/anti-affinity across related VM types as well.
4750 In this example, the {network-role} has been defined as oam to represent
4751 an oam network and the {vm-type} have been defined as lb for load
4752 balancer and db for database.
4754 .. code-block:: yaml
4758 type: OS::Nova::ServerGroup
4763 $vnf_name: {get_param: vnf_name}
4764 template: $vnf_name-server_group1
4769 type: OS::Nova::ServerGroup
4774 $vnf_name: {get_param: vnf_name}
4775 template: $vnf_name-server_group2
4780 type: OS::Nova::Server
4784 group: {get_resource: db_server_group}
4787 type: OS::Nova::Server
4791 group: {get_resource: db_server_group}
4794 type: OS::Nova::Server
4798 group: {get_resource: lb_server_group}
4800 Resource Data Synchronization
4801 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4803 For cases where synchronization is required in the orchestration of Heat
4804 resources, two approaches are recommended:
4806 - Standard Heat depends\_on property for resources
4808 - Assures that one resource completes before the dependent resource
4811 - Definition of completeness to OpenStack may not be sufficient
4812 (e.g., a VM is considered complete by OpenStack when it is ready
4813 to be booted, not when the application is up and running).
4815 - Use of Heat Notifications
4817 - Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle
4820 - Pre-requisite resources issue *wc\_notify* commands in user\_data.
4822 - Dependent resource define depends\_on in the
4823 OS::Heat::WaitCondition resource.
4825 *Example: “depends\_on” case*
4827 In this example, the {network-role} has been defined as oam to represent
4828 an oam network and the {vm-type} has been defined as oam to represent an
4831 .. code-block:: yaml
4835 type: OS::Nova::Server
4837 name: {get_param: [oam_ names, 0]}
4838 image: {get_param: oam_image_name}
4839 flavor: {get_param: oam_flavor_name}
4840 availability_zone: {get_param: availability_zone_0}
4842 - port: {get_resource: oam01_port_0}
4843 - port: {get_resource: oam01_port_1}
4845 scheduler_hints: {group: {get_resource: oam_servergroup}}
4846 user_data_format: RAW
4849 type: OS::Neutron::Port
4851 network: {get_resource: oam_net_name}
4852 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}]
4853 security_groups: [{get_resource: oam_security_group}]
4856 type: OS::Neutron::Port
4858 network: {get_param: oam_net_name}
4859 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}]
4860 security_groups: [{get_resource: oam_security_group}]
4862 oam_01_vol_attachment:
4863 type: OS::Cinder::VolumeAttachment
4864 depends_on: oam_server_01
4866 volume_id: {get_param: oam_vol_1}
4867 mountpoint: /dev/vdb
4868 instance_uuid: {get_resource: oam_server_01}
4873 VNF/VM parameters may include availability zone IDs for VNFs that
4874 require high availability.
4876 The Heat must comply with the following requirements to specific
4877 availability zone IDs:
4879 - The Heat template should spread Nova and Cinder resources across the
4880 availability zones as desired
4882 Post Orchestration & VNF Configuration
4883 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4885 Heat templates should contain a minimum amount of post-orchestration
4886 configuration data. For instance, *do not* embed complex user-data
4887 scripts in the template with large numbers of configuration parameters
4888 to the Heat template.
4890 - VNFs may provide configuration APIs for use after VNF creation. Such
4891 APIs will be invoked via application and/or SDN controllers.
4893 *Note:* It is important to follow this convention to the extent possible
4894 even in the short-term as of the long-term direction.
4896 VNFM Driver Development Steps
4897 -----------------------------------------------------------
4899 Refer to the ONAP documentation for VNF Provider instructions on integrating
4900 vendor-specific VNFM adaptors with VF-C. The VNF driver development steps are
4903 1. Use the VNF SDK tools to design the VNF with TOSCA models to output
4904 the VNF TOSCA package. Using the VNF SDK tools, the VNF package can be
4905 validated and tested.
4907 2. The VNF Provider supplies a vendor-specific VNFM driver in ONAP, which
4908 is a microservice providing a translation interface from VF-C to
4909 the vendor-specific VNFM. The interface definitions of vendor-specific
4910 VNFM adaptors are supplied by the VNF Providers themselves.
4912 Creating Vendor-Specific VNFM Adaptor Microservices
4913 ------------------------------------------------------------------------------------------------
4915 VNFs can be managed by vendor-specific VNFMs. To add a vendor-specific
4916 VNFM to ONAP, a vendor-specific VNFM adaptor is added to ONAP implementing
4917 the interface of the vendor-specific VNFM.
4919 A vendor-specific VNFM adaptor is a microservice with a unique name and
4920 an appointed port. When started up, the vendor-specific VNFM adaptor
4921 microservice is automatically registered to the Microservices Bus (MSB).
4922 The following RESTful example describes the scenario of registering a
4923 vendor-specific VNFM adaptor to MSB:
4925 .. code-block:: java
4927 POST /api/microservices/v1/services
4929 "serviceName": "catalog",
4931 "url": "/api/catalog/v1",
4936 "ip": "10.74.56.36",
Code Review / vnfrqts / requirements.git / blob