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 OS::Nova::Server Resource property metadata is an optional
2622 The table below summarizes the mandatory and optional metadata
2625 The sections that follow provides the requirements associated with each
2628 .. csv-table:: **Table 5 OS::Nova::Server Mandatory and Optional Metadata**
2629 :header: Metadata Parameter Name, Parameter Type, Required, Parameter Value Provided to Heat
2633 vnf_id, string, **MUST**, ONAP
2634 vf_module_id, string, **MUST**, ONAP
2635 vnf_name, string, **MUST**, ONAP
2636 vf_module_name, string, **SHOULD**, ONAP
2637 vm_role, string, **MAY**, YAML or Environment File
2638 vf_module_index, string, **MAY**, ONAP
2639 workload_context, string, **SHOULD**, ONAP
2640 environment_context, string, **SHOULD**, ONAP
2645 The OS::Nova::Server Resource metadata map value parameter 'vnf_id'
2646 is an ONAP generated UUID that identifies the VNF. The value
2647 is provided by ONAP to the VNF's Heat Orchestration
2648 Template at orchestration time.
2650 R-37437 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2651 Resource **MUST** contain the metadata map value parameter ‘vnf_id’.
2653 R-07507 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2654 Resource metadata map value parameter ‘vnf_id’ **MUST** be declared
2657 R-55218 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2658 Resource metadata map value parameter ‘vnf_id’ **MUST NOT** have
2659 parameter contraints defined.
2661 R-20856 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2662 Resource metadata map value parameter ‘vnf_id’ **MUST NOT** be
2663 enumerated in the Heat Orchestration Template’s environment file.
2665 R-44491 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
2666 Resource metadata map value parameter ‘vnf_id’ is passed into a
2667 Nested YAML file, the parameter name ‘vnf_id’ **MUST NOT** change.
2670 *Example 'vnf_id' Parameter Definition*
2672 .. code-block:: python
2678 description: Unique ID for this VNF instance
2683 The OS::Nova::Server Resource metadata map value parameter 'vf\_module\_id'
2684 is an ONAP generated UUID that identifies the VF Module (e.g., Heat
2685 Orchestration Template). The value
2686 is provided by ONAP to the VNF's Heat Orchestration
2687 Template at orchestration time.
2689 R-71493 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2690 Resource **MUST** contain the metadata map value parameter
2693 R-82134 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2694 Resource metadata map value parameter ‘vf\_module\_id’ **MUST**
2695 be declared as type: ‘string’.
2697 R-98374 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2698 Resource metadata map value parameter ‘vf\_module\_id’ **MUST NOT**
2699 have parameter contraints defined.
2701 R-72871 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2702 Resource metadata map value parameter ‘vf\_module\_id’ **MUST NOT**
2703 be enumerated in the Heat Orchestration Template’s environment file.
2705 R-86237 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
2706 Resource metadata map value parameter ‘vf_module_id’ is passed
2707 into a Nested YAML file, the parameter name ‘vf\_module\_id’
2708 **MUST NOT** change.
2710 *Example 'vf\_module\_id' Parameter Definition*
2712 .. code-block:: python
2718 description: Unique ID for this VNF module instance
2724 The OS::Nova::Server Resource metadata map value parameter 'vnf_name'
2725 is the ONAP generated alphanumeric name of the deployed VNF instance.
2727 is provided by ONAP to the VNF's Heat Orchestration
2728 Template at orchestration time.
2729 The parameter must be declared as type: string
2731 R-72483 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2732 Resource **MUST** contain the metadata map value parameter
2735 R-62428 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2736 Resource metadata map value parameter ‘vnf_name’ **MUST** be
2737 declared as type: ‘string’.
2739 R-44318 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2740 Resource metadata map value parameter ‘vnf_name’ **MUST NOT** have
2741 parameter contraints defined.
2743 R-36542 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2744 Resource metadata map value parameter ‘vnf_name’ **MUST NOT** be
2745 enumerated in the Heat Orchestration Template’s environment file.
2747 R-16576 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
2748 Resource metadata map value parameter ‘vnf_name’ is passed into a
2749 Nested YAML file, the parameter name ‘vnf_name’ **MUST NOT** change.
2751 *Example 'vnf_name' Parameter Definition*
2753 .. code-block:: python
2759 description: Unique name for this VNF instance
2764 The OS::Nova::Server Resource metadata map value parameter 'vf_module_name'
2765 is the deployment name of the heat stack created (e.g., <STACK_NAME>) from the
2766 VNF's Heat Orchestration template
2767 in the command 'Heat stack-create'
2768 (e.g., 'Heat stack-create [-f <FILE>] [-e <FILE>] <STACK_NAME>').
2769 The 'vf_module_name' (e.g., <STACK_NAME> is specified as
2770 part of the orchestration process.
2772 R-68023 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2773 Resource **SHOULD** contain the metadata map value parameter
2776 R-39067 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2777 Resource metadata map value parameter ‘vf\_module\_name’ **MUST**
2778 be declared as type: ‘string’.
2780 R-15480 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2781 Resource metadata map value parameter ‘vf\_module\_name’
2782 **MUST NOT** have parameter contraints defined.
2784 R-80374 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2785 Resource metadata map value parameter ‘vf\_module\_name’
2786 **MUST NOT** be enumerated in the Heat Orchestration Template’s
2789 R-49177 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
2790 Resource metadata map value parameter ‘vf\_module\_name’ is passed
2791 into a Nested YAML file, the parameter name ‘vf\_module\_name’
2792 **MUST NOT** change.
2794 *Example 'vf_module_name' Parameter Definition*
2796 .. code-block:: python
2802 description: Unique name for this VNF Module instance
2807 The OS::Nova::Server Resource metadata map value parameter 'vm-role'
2808 is a metadata tag that describes the role of the Virtual Machine.
2809 The 'vm_role' is stored in ONAP's A&AI module and is
2810 available for use by other ONAP components and/or north bound systems.
2812 R-85328 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2813 Resource **MAY** contain the metadata map value parameter ‘vm_role’.
2815 R-95430 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2816 Resource metadata map value parameter ‘vm_role’ **MUST** be
2817 declared as type: ‘string’.
2819 R-67597 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2820 Resource metadata map value parameter ‘vm_role’ **MUST NOT** have
2821 parameter contraints defined.
2823 R-46823 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2824 Resource metadata map value parameter ‘vnf_name’ **MUST** be
2827 - enumerated in the VNF’s Heat Orchestration
2828 Template’s environment file.
2830 - hard coded in the VNF’s Heat Orchestration
2831 Template’s OS::Nova::Resource metadata property.
2833 Defining the 'vm_role' as the '{vm-type}' is a recommended convention
2835 R-86476 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
2836 Resource metadata map value parameter ‘vm_role’ value **MUST only**
2837 contain alphanumeric characters and underscores ‘_’.
2839 R-70757 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
2840 Resource metadata map value parameter ‘vm_role’ is passed into a
2841 Nested YAML file, the parameter name ‘vm_role’ **MUST NOT** change.
2844 *Example 'vm_role' Parameter Definition*
2846 .. code-block:: python
2852 description: Unique role for this VM
2854 *Example: 'vm-role' Definition: Hard Coded in
2855 OS::Nova::Resource metadata property*
2857 .. code-block:: python
2862 type: OS::Nova::Server
2868 *Example 'vm-role' Definition: Defined in Environment file
2869 and retrieved via 'get_param'*
2871 .. code-block:: python
2876 type: OS::Nova::Server
2880 vm_role: { get_param: vm_role }
2882 Example vnf_id, vf_module_id, vnf_name, vf_module_name, vm_role
2883 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
2885 The example below depicts part of a Heat Orchestration Template
2886 that uses the five of the OS::Nova::Server metadata parameter
2887 discussed in this section. The {vm-type} has been defined as lb
2890 .. code-block:: python
2895 description: VM Name for lb VM 0
2898 description: Unique name for this VNF instance
2901 description: Unique ID for this VNF instance
2904 description: Unique name for this VNF Module instance
2907 description: Unique ID for this VNF Module instance
2910 description: Unique role for this VM
2913 type: OS::Nova::Server
2915 name: { get_param: lb_name_0 }
2918 vnf_name: { get_param: vnf_name }
2919 vnf_id: { get_param: vnf_id }
2920 vf_module_name: { get_param: vf_module_name }
2921 vf_module_id: { get_param: vf_module_id }
2927 R-50816 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2928 Resource **MAY** contain the metadata map value parameter
2929 ‘vf\_module\_index’.
2931 R-54340 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2932 Resource metadata map value parameter ‘vf\_module\_index’ **MUST** be
2933 declared as type: ‘number’.
2935 R-09811 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2936 Resource metadata map value parameter ‘vf\_module\_index’ **MUST NOT**
2937 have parameter contraints defined.
2939 R-37039 A VNF’s Heat Orchestration Template’s OS::Nova::Server
2940 Resource metadata map value parameter ‘vf\_module\_index’ **MUST NOT**
2941 be enumerated in the Heat Orchestration Template’s environment file.
2943 R-22441 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
2944 Resource metadata map value parameter ‘vf\_module\_index’ is passed
2945 into a Nested YAML file, the parameter name ‘vf\_module\_index’
2946 **MUST NOT** change.
2948 R-55306 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
2949 Resource metadata map value parameter ‘vf\_module\_index’ **MUST NOT** be
2950 used in a VNF’s Volume Template; it is not supported.
2952 The vf_module_index parameter indicates which instance of the module is being
2953 deployed into the VNF.
2954 This parameter may be used in cases where multiple instances of the same
2955 incremental module may be instantiated for scaling purposes. The index
2956 can be used in the Heat Orchestration Template for indexing into a
2957 pseudo-constant array parameter when unique values are required for each
2958 module instance, e.g., for fixed private IP addresses on VM types.
2960 The vf_module_index will start at 0 for the first instance of a module
2961 type. Subsequent instances of the same module type will receive the
2962 lowest unused index. This means that indexes will be reused if a module
2963 is deleted and re-added. As an example, if three copies of a module are
2964 deployed with vf_module_index values of 0, 1, and 2 then subsequently
2965 the second one is deleted (index 1), and then re-added, index 1 will be
2970 In this example, the {vm-type} has been defined as oam_vm to represent
2971 an OAM VM. An incremental heat module is used to deploy the OAM VM. The
2972 OAM VM attaches to an internal control network which has a
2973 {network-role} of ctrl. A maximum of four OAM VMs can be deployed. The
2974 environment file contains the four IP addresses that each successive OAM
2975 VM will be assigned. The vf_module_index is used as the index to
2976 determine the IP assignment.
2980 .. code-block:: python
2983 oam_vm_int_ctrl_ips: 10.10.10.1,10.10.10.2,10.10.10.3,10.10.10.4
2987 .. code-block:: python
2992 description: Unique index for this VNF Module instance
2995 description: VM Name for lb VM 0
2998 description: Neutron UUID for the internal control network
2999 oam_vm_int_ctrl_ips:
3000 type: comma_delimited_list
3001 description: Fixed IP assignments for oam VMs on the internal control
3005 type: OS::Nova::Server
3007 name: { get_param: oam_vm_name_0 }
3009 - port: { get_resource: oam_vm_0_int_ctrl_port_0 }
3012 vf_module_index: { get_param: vf_module_index }
3013 oam_vm_0_int_ctrl_port_0:
3014 type: OS::Neutron::Port
3016 network: { get_param: int_ctrl_net_id }
3017 fixed_ips: [ { “ip_address”: {get_param: [ oam_vm_int_ctrl_ips, { get_param, vf_module_index]}}}]
3022 R-47061 A VNF’s Heat Orchestration Template’s OS::Nova::Server
3023 Resource **SHOULD** contain the metadata map value parameter
3026 R-74978 A VNF’s Heat Orchestration Template’s OS::Nova::Server
3027 Resource metadata map value parameter ‘workload_context’ **MUST** be
3028 declared as type: ‘string’.
3030 R-34055 A VNF’s Heat Orchestration Template’s OS::Nova::Server
3031 Resource metadata map value parameter ‘workload_context’ **MUST NOT**
3032 have parameter contraints defined.
3034 R-02691 A VNF’s Heat Orchestration Template’s OS::Nova::Server
3035 Resource metadata map value parameter ‘workload_context’ **MUST NOT**
3036 be enumerated in the Heat Orchestration Template’s environment file.
3038 R-75202 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
3039 Resource metadata map value parameter ‘workload_context’ is passed
3040 into a Nested YAML file, the parameter name ‘workload_context’
3041 **MUST NOT** change.
3043 The 'workload_context' parameter value will be chosen by the Service Model
3044 Distribution context client in VID and will be supplied to the
3045 Heat Orchestration Template by ONAP at orchestration time.
3047 *Example Parameter Definition*
3049 .. code-block:: python
3054 description: Workload Context for this VNF instance
3057 *Example OS::Nova::Server with metadata*
3059 .. code-block:: python
3064 {vm-type}_server_{index}:
3065 type: OS::Nova::Server
3072 vnf_name: { get_param: vnf_name }
3073 vnf_id: { get_param: vnf_id }
3074 vf_module_name: { get_param: vf_module_name }
3075 vf_module_id: { get_param: vf_module_id }
3076 workload_context: {get_param: workload_context}
3081 R-88536 A VNF’s Heat Orchestration Template’s OS::Nova::Server
3082 Resource **SHOULD** contain the metadata map value parameter
3083 ‘environment_context’.
3085 R-20308 A VNF’s Heat Orchestration Template’s OS::Nova::Server
3086 Resource metadata map value parameter ‘environment_context’ **MUST**
3087 be declared as type: ‘string’.
3089 R-56183 A VNF’s Heat Orchestration Template’s OS::Nova::Server
3090 Resource metadata map value parameter ‘environment_context’ **MUST NOT**
3091 have parameter contraints defined.
3093 R-13194 A VNF’s Heat Orchestration Template’s OS::Nova::Server
3094 Resource metadata map value parameter ‘environment_context’ **MUST NOT**
3095 be enumerated in the Heat Orchestration Template’s environment file.
3097 R-62954 If a VNF’s Heat Orchestration Template’s OS::Nova::Server
3098 Resource metadata map value parameter ‘environment_context’ is
3099 passed into a Nested YAML file, the parameter name
3100 ‘environment_context’ **MUST NOT** change.
3102 The 'environment_context' parameter value will be defined by the
3103 service designer as part of the service model during the SDC
3104 on-boarding process and will be supplied to the Heat Orchestration
3105 Template by ONAP at orchestration time.
3108 *Example Parameter Definition*
3110 .. code-block:: python
3113 environment_context:
3115 description: Environment Context for this VNF instance
3118 *Example OS::Nova::Server with metadata*
3120 .. code-block:: python
3125 {vm-type}_server_{index}:
3126 type: OS::Nova::Server
3133 vnf_name: { get_param: vnf_name }
3134 vnf_id: { get_param: vnf_id }
3135 vf_module_name: { get_param: vf_module_name }
3136 vf_module_id: { get_param: vf_module_id }
3137 workload_context: {get_param: workload_context}
3138 environment_context: {get_param: environment_context }
3141 Resource: OS::Neutron::Port - Parameters
3142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3144 The resource OS::Neutron::Port is for managing Neutron ports (See
3145 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Port.)
3150 Four properties of the resource OS::Neutron::Port that must follow the
3151 ONAP parameter naming convention. The four properties are:
3155 2. fixed\_ips, ip\_address
3157 3. fixed\_ips, subnet\_id
3159 4. allowed\_address\_pairs, ip\_address
3161 The parameters associated with these properties may reference an
3162 external network or internal network. External networks and internal
3163 networks are defined in `Networking`_.
3168 When the parameter references an external network
3170 - R-72050 The VNF Heat Orchestration Template **MUST** contain {network-role} in the parameter name
3172 - the parameter must not be enumerated in the Heat environment file
3174 - the parameter is classified as an ONAP Orchestration Parameter
3176 +----------------------+---------------------------+--------------------------+
3177 | Property Name | ONAP Parameter Name | Parameter Type |
3178 +======================+===========================+==========================+
3179 | network | {network-role}\_net\_id | string |
3180 | +---------------------------+--------------------------+
3181 | | {network-role}\_net\_name | string |
3182 +----------------------+---------------------------+--------------------------+
3183 | fixed\_ips, | {vm-type}\_{network-role}\| string |
3184 | ip\_address | _ip\_{index} | |
3185 | +---------------------------+--------------------------+
3186 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
3188 | +---------------------------+--------------------------+
3189 | | {vm-type}\_{network-role}\| string |
3190 | | _v6\_ip\_{index} | |
3191 | +---------------------------+--------------------------+
3192 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
3194 +----------------------+---------------------------+--------------------------+
3195 | fixed\_ips, subnet | {network-role}\ | string |
3197 | +---------------------------+--------------------------+
3198 | | {network-role}\ | string |
3199 | | _v6\_subnet\_id | |
3200 +----------------------+---------------------------+--------------------------+
3201 | allowed\_address | {vm-type}\_{network-role}\| string |
3202 | \_pairs, ip\_address | _floating\_ip | |
3203 | +---------------------------+--------------------------+
3204 | | {vm-type}\_{network-role}\| string |
3205 | | _floating\_v6\_ip | |
3206 | +---------------------------+--------------------------+
3207 | | {vm-type}\_{network-role}\| string |
3208 | | _ip\_{index} | |
3209 | +---------------------------+--------------------------+
3210 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
3212 | +---------------------------+--------------------------+
3213 | | {vm-type}\_{network-role}\| string |
3214 | | _v6\_ip\_{index} | |
3215 | +---------------------------+--------------------------+
3216 | | {vm-type}\_{network-role}\| comma\_delimited\_list |
3218 +----------------------+---------------------------+--------------------------+
3220 Table 5: OS::Neutron::Port Resource Property Parameters (External
3226 When the parameter references an internal network
3228 - R-57576 The VNF Heat Orchestration Template **MUST** contain int\_{network-role}
3229 in the parameter name.
3231 - the parameter may be enumerated in the environment file.
3233 +-------------------------+--------------------------------+-----------------+
3234 | Property | Parameter Name for | Parameter Type |
3235 | | Internal Networks | |
3236 +=========================+================================+=================+
3237 | network | int\_{network-role}\ | string |
3239 | +--------------------------------+-----------------+
3240 | | int\_{network-role}\ | string |
3242 +-------------------------+--------------------------------+-----------------+
3243 | fixed\_ips, ip\_address | {vm-type}\_int\_{network-role}\| string |
3244 | | _ip\_{index} | |
3245 | +--------------------------------+-----------------+
3246 | | {vm-type}\_int\_{network-role}\| comma\ |
3247 | | _ips | _delimited\_list|
3248 | +--------------------------------+-----------------+
3249 | | {vm-type}\_int\_{network-role}\| string |
3250 | | _v6\_ip\_{index} | |
3251 | +--------------------------------+-----------------+
3252 | | {vm-type}\_int\_{network-role}\| comma\ |
3253 | | _v6\_ips | _delimited\_list|
3254 +-------------------------+--------------------------------+-----------------+
3255 | fixed\_ips, subnet | int\_{network-role}\ | string |
3257 | +--------------------------------+-----------------+
3258 | | int\_{network-role}\ | string |
3259 | | _v6\_subnet\_id | |
3260 +-------------------------+--------------------------------+-----------------+
3261 | allowed\_address\_pairs,| {vm-type}\_int\_{network-role}\| string |
3262 | ip\_address | _floating\_ip | |
3263 | +--------------------------------+-----------------+
3264 | | {vm-type}\_int\_{network-role}\| string |
3265 | | _floating\_v6\_ip | |
3266 | +--------------------------------+-----------------+
3267 | | {vm-type}\_int\_{network-role}\| string |
3268 | | _ip\_{index} | |
3269 | +--------------------------------+-----------------+
3270 | | {vm-type}\_int\_{network-role}\| comma\ |
3271 | | _ips | _delimited\_list|
3272 | +--------------------------------+-----------------+
3273 | | {vm-type}\_int\_{network-role}\| string |
3274 | | _v6\_ip\_{index} | |
3275 | +--------------------------------+-----------------+
3276 | | {vm-type}\_int\_{network-role}\| comma\ |
3277 | | _v6\_ips | _delimited\_list|
3278 +-------------------------+--------------------------------+-----------------+
3280 Table 6: Port Resource Property Parameters (Internal Networks)
3285 The property networks in the resource OS::Neutron::Port must be
3286 referenced by Neutron Network ID, a UUID value, or by the network name
3287 defined in OpenStack.
3292 R-93272 The VNF Heat Orchestration Template **MUST** adhere to the following parameter naming
3293 convention in the Heat Orchestration Template, when the parameter
3294 associated with the property network is referencing an “external” network:
3296 - {network-role}\_net\_id for the Neutron network ID
3298 - {network-role}\_net\_name for the network name in OpenStack
3300 The parameter must be declared as type: string
3302 The parameter must not be enumerated in the Heat environment file.
3304 *Example Parameter Definition*
3306 .. code-block:: yaml
3309 {network-role}_net_id:
3311 description: Neutron UUID for the {network-role} network
3312 {network-role}_net_name:
3314 description: Neutron name for the {network-role} network
3316 *Example: One Cloud Assigned IP Address (DHCP) assigned to a network
3317 that has only one subnet*
3319 In this example, the {network-role} has been defined as oam to represent
3320 an oam network and the {vm-type} has been defined as lb for load
3321 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3322 to assign IP addresses.
3324 .. code-block:: yaml
3329 description: Neutron UUID for the oam network
3333 type: OS::Neutron::Port
3334 network: { get_param: oam_net_id }
3339 R-65373 The VNF Heat Orchestration Template **MUST** adhere to the following parameter naming
3340 convention, when the parameter associated with the property network is
3341 referencing an “internal” network:
3343 - int\_{network-role}\_net\_id for the Neutron network ID
3345 - int\_{network-role}\_net\_name for the network name in OpenStack
3347 The parameter must be declared as type: string
3349 The assumption is that internal networks are created in the base module.
3350 The Neutron Network ID will be passed as an output parameter (e.g., ONAP
3351 Base Module Output Parameter) to the incremental modules. In the
3352 incremental modules, it will be defined as input parameter.
3354 *Example Parameter Definition*
3356 .. code-block:: yaml
3359 int_{network-role}_net_id:
3361 description: Neutron UUID for the {network-role} network
3362 int_{network-role}_net_name:
3364 description: Neutron name for the {network-role} network
3366 Property: fixed\_ips, Map Property: subnet\_id
3367 ++++++++++++++++++++++++++++++++++++++++++++++
3369 The property fixed\_ips is used to assign IPs to a port. The Map
3370 Property subnet\_id specifies the subnet the IP is assigned from.
3372 The property fixed\_ips and Map Property subnet\_id must be used if a
3373 Cloud (i.e., DHCP) IP address assignment is being requested and the
3374 Cloud IP address assignment is targeted at a specific subnet when two or
3377 The property fixed\_ips and Map Property subnet\_id should not be used
3378 if all IP assignments are fixed, or if the Cloud IP address assignment
3379 does not target a specific subnet or there is only one subnet.
3381 Note that DHCP assignment of IP addresses is also referred to as cloud
3382 assigned IP addresses.
3384 Subnet of an External Networks
3385 ______________________________
3387 R-47716 The VNF Heat Orchestration Template **MUST** adhere to the following parameter naming
3388 convention for the property fixed\_ips and Map Property subnet\_id
3389 parameter, when the parameter is referencing a subnet of an
3392 - {network-role}\_subnet\_id if the subnet is an IPv4 subnet
3394 - {network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
3396 The parameter must be declared as type: string
3398 The parameter must not be enumerated in the Heat environment file.
3400 *Example Parameter Definition*
3402 .. code-block:: yaml
3405 {network-role}_subnet_id:
3407 description: Neutron subnet UUID for the {network-role} network
3409 {network-role}_v6_subnet_id:
3411 description: Neutron subnet UUID for the {network-role} network
3413 *Example: One Cloud Assigned IPv4 Address (DHCP) assigned to a network
3414 that has two or more subnets subnet:*
3416 In this example, the {network-role} has been defined as oam to represent
3417 an oam network and the {vm-type} has been defined as lb for load
3418 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3419 to assign IP addresses.
3421 .. code-block:: yaml
3426 description: Neutron UUID for the oam network
3430 description: Neutron subnet UUID for the oam network
3434 type: OS::Neutron::Port
3435 network: { get_param: oam_net_id }
3437 - subnet_id: { get_param: oam_subnet_id }
3439 *Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6
3440 address assigned to a network that has at least one IPv4 subnet and one
3443 In this example, the {network-role} has been defined as oam to represent
3444 an oam network and the {vm-type} has been defined as lb for load
3447 .. code-block:: yaml
3452 description: Neutron UUID for the oam network
3456 description: Neutron subnet UUID for the oam network
3460 description: Neutron subnet UUID for the oam network
3464 type: OS::Neutron::Port
3466 network: { get_param: oam_net_id }
3468 - subnet_id: { get_param: oam_subnet_id }
3469 - subnet_id: { get_param: oam_v6_subnet_id }
3474 R-20106 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention for
3475 the property fixed\_ips and Map Property subnet\_id parameter,
3476 when the parameter is referencing the subnet of an “internal” network:
3478 - int\_{network-role}\_subnet\_id if the subnet is an IPv4 subnet
3480 - int\_{network-role}\_v6\_subnet\_id if the subnet is an IPv6 subnet
3482 The parameter must be declared as type: string
3484 The assumption is that internal networks are created in the base module.
3485 The Neutron subnet network ID will be passed as an output parameter
3486 (e.g., ONAP Base Module Output Parameter) to the incremental modules. In
3487 the incremental modules, it will be defined as input parameter.
3489 *Example Parameter Definition*
3491 .. code-block:: yaml
3494 int_{network-role}_subnet_id:
3496 description: Neutron subnet UUID for the {network-role} network
3498 int_{network-role}_v6_subnet_id:
3500 description: Neutron subnet UUID for the {network-role} network
3502 Property: fixed\_ips, Map Property: ip\_address
3503 +++++++++++++++++++++++++++++++++++++++++++++++
3505 The property fixed\_ips is used to assign IPs to a port. The Map
3506 Property ip\_address specifies the IP address to be assigned to the
3509 The property fixed\_ips and Map Property ip\_address must be used when
3510 statically assigning one or more IP addresses to a port. This is also
3511 referred to as ONAP SDN-C IP address assignment. ONAP’s SDN-C provides
3512 the IP address assignment.
3514 An IP address is assigned to a port on a VM (referenced by {vm-type})
3515 that is connected to an external network (referenced by {network-role})
3516 or internal network (referenced by int\_{network-role}).
3518 R-41177 The VNF Heat Orchestration Template **MUST** include {vm-type} and {network-role}
3519 in the parameter name, when a SDN-C IP assignment is made to a
3520 port connected to an external network.
3522 When a SDN-C IP assignment is made to a port connected to an internal
3523 network, the parameter name must contain {vm-type} and
3524 int\_{network-role}.
3526 IP Address Assignments on External Networks
3527 ___________________________________________
3529 When the property fixed\_ips and Map Property ip\_address is used to
3530 assign IP addresses to an external network, the parameter name is
3531 dependent on the parameter type (comma\_delimited\_list or string) and
3532 IP address type (IPv4 or IPv6).
3534 R-84898 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention,
3535 when the parameter for property fixed\_ips and Map Property ip\_address
3536 is declared type: comma\_delimited\_list:
3538 - {vm-type}\_{network-role}\_ips for IPv4 address
3540 - {vm-type}\_{network-role}\_v6\_ips for IPv6 address
3542 Each element in the IP list should be assigned to successive instances
3543 of {vm-type} on {network-role}.
3545 The parameter must not be enumerated in the Heat environment file.
3547 *Example Parameter Definition*
3549 .. code-block:: yaml
3553 {vm-type}_{network-role}_ips:
3554 type: comma_delimited_list
3555 description: Fixed IPv4 assignments for {vm-type} VMs on the {Network-role} network
3557 {vm-type}_{network-role}_v6_ips:
3558 type: comma_delimited_list
3559 description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
3561 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
3562 Assignments to an external network*
3564 In this example, the {network-role} has been defined as oam to represent
3565 an oam network and the {vm-type} has been defined as db for database.
3567 .. code-block:: yaml
3572 description: Neutron UUID for a oam network
3575 type: comma_delimited_list
3576 description: Fixed IPv4 assignments for db VMs on the oam network
3579 type: comma_delimited_list
3580 description: Fixed IPv6 assignments for db VMs on the oam network
3584 type: OS::Neutron::Port
3585 network: { get_param: oam_net_id }
3586 fixed_ips: [ { “ip_address”: {get_param: [ db_oam_ips, 0 ]}}, {“ip_address”: {get_param: [ db_oam_v6_ips, 0 ]}}]
3589 type: OS::Neutron::Port
3591 network: { get_param: oam_net_id }
3593 - “ip_address”: {get_param: [ db_oam_ips, 1 ]}
3594 - “ip_address”: {get_param: [ db_oam_v6_ips, 1 ]}
3596 R-34960 The VNF Heat Orchestration Template **MUST** adhere to the following
3598 when the parameter for property fixed\_ips and Map Property ip\_address
3599 is declared type: string:
3601 - {vm-type}\_{network-role}\_ip\_{index} for an IPv4 address
3603 - {vm-type}\_{network-role}\_v6\_ip\_{index} for an IPv6 address
3605 The value for {index} must start at zero (0) and increment by one.
3607 The parameter must not be enumerated in the Heat environment file.
3609 *Example Parameter Definition*
3611 .. code-block:: yaml
3614 {vm-type}_{network-role}_ip_{index}:
3616 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
3618 {vm-type}_{network-role}_v6_ip_{index}:
3620 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
3622 *Example: string parameters for IPv4 and IPv6 Address Assignments
3623 to an external network*
3625 In this example, the {network-role} has been defined as “oam” to
3626 represent an oam network and the {vm-type} has been defined as “db” for
3629 .. code-block:: yaml
3634 description: Neutron UUID for an OAM network
3638 description: Fixed IPv4 assignment for db VM 0 on the OAM network
3642 description: Fixed IPv4 assignment for db VM 1 on the OAM network
3646 description: Fixed IPv6 assignment for db VM 0 on the OAM network
3650 description: Fixed IPv6 assignment for db VM 1 on the OAM network
3654 type: OS::Neutron::Port
3656 network: { get_param: oam_net_id }
3657 fixed_ips: [ { “ip_address”: {get_param: db_oam_ip_0}}, {“ip_address”: {get_param: db_oam_v6_ip_0 ]}}]
3660 type: OS::Neutron::Port
3662 network: { get_param: oam_net_id }
3664 - “ip_address”: {get_param: db_oam_ip_1}}]
3665 - “ip_address”: {get_param: db_oam_v6_ip_1}}]
3667 IP Address Assignment on Internal Networks
3668 __________________________________________
3670 When the property fixed\_ips and Map Property ip\_address is used to
3671 assign IP addresses to an internal network, the parameter name is
3672 dependent on the parameter type (comma\_delimited\_list or string) and
3673 IP address type (IPv4 or IPv6).
3675 R-62584 The VNF Heat Orchestration Template **MUST** adhere to
3676 the following naming convention,
3677 when the parameter for property fixed\_ips and Map Property ip\_address
3678 is declared type: comma\_delimited\_list:
3680 - {vm-type}\_int\_{network-role}\_ips for IPv4 address
3682 - {vm-type}\_int\_{network-role}\_v6\_ips for IPv6 address
3684 Each element in the IP list should be assigned to successive instances
3685 of {vm-type} on {network-role}.
3687 The parameter must be enumerated in the Heat environment file. Since an
3688 internal network is local to the VNF, IP addresses can be re-used at
3691 *Example Parameter Definition*
3693 .. code-block:: yaml
3697 {vm-type}_int_{network-role}_ips:
3698 type: comma_delimited_list
3699 description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
3701 {vm-type}_int_{network-role}_v6_ips:
3702 type: comma_delimited_list
3703 description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
3705 *Example: comma\_delimited\_list parameters for IPv4 and IPv6 Address
3706 Assignments to an internal network*
3708 In this example, the {network-role} has been defined as oam\_int to
3709 represent an oam network internal to the vnf. The role oam\_int was
3710 picked to differentiate from an external oam network with a
3711 {network-role} of oam. The {vm-type} has been defined as db for
3714 .. code-block:: yaml
3719 description: Neutron UUID for the oam internal network
3722 type: comma_delimited_list
3723 description: Fixed IPv4 assignments for db VMs on the oam internal network
3725 db_int_oam_int_v6_ips:
3726 type: comma_delimited_list
3727 description: Fixed IPv6 assignments for db VMs on the oam internal network
3731 type: OS::Neutron::Port
3733 network: { get_param: int_oam_int_net_id }
3734 fixed_ips: [ { “ip_address”: {get_param: [ db_int_oam_int_ips, 0]}}, { “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 0 ]}}]
3737 type: OS::Neutron::Port
3739 network: { get_param: int_oam_int_net_id }
3741 - “ip_address”: {get_param: [ db_int_oam_int_ips, 1 ]}
3742 - “ip_address”: {get_param: [ db_int_oam_int_v6_ips, 1 ]}
3744 R-29256 The VNF Heat Orchestration Template **MUST** must adhere to the following
3746 when the parameter for property fixed\_ips and Map Property ip\_address
3747 is declared type: string:
3749 - {vm-type}\_int\_{network-role}\_ip\_{index} for an IPv4 address
3751 - {vm-type}\_int\_{network-role}\_v6\_ip\_{index} for an IPv6 address
3753 The value for {index} must start at zero (0) and increment by one.
3755 The parameter must be enumerated in the Heat environment file. Since an
3756 internal network is local to the VNF, IP addresses can be re-used at
3759 *Example Parameter Definition*
3761 .. code-block:: yaml
3765 {vm-type}_int_{network-role}_ip_{index}:
3767 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
3769 {vm-type}_int_{network-role}_v6_ip_{index}:
3771 description: Fixed IPv6 assignment for {vm-type} VM {index} on the{network-role} network
3773 *Example: string parameters for IPv4 and IPv6 Address Assignments
3774 to an internal network*
3776 In this example, the {network-role} has been defined as oam\_int to
3777 represent an oam network internal to the vnf. The role oam\_int was
3778 picked to differentiate from an external oam network with a
3779 {network-role} of oam. The {vm-type} has been defined as db for
3782 .. code-block:: yaml
3787 description: Neutron UUID for an OAM internal network
3791 description: Fixed IPv4 assignment for db VM on the oam_int network
3795 description: Fixed IPv4 assignment for db VM 1 on the oam_int network
3799 description: Fixed IPv6 assignment for db VM 0 on the oam_int network
3803 description: Fixed IPv6 assignment for db VM 1 on the oam_int network
3807 type: OS::Neutron::Port
3809 network: { get_param: int_oam_int_net_id }
3810 fixed_ips: [ { “ip_address”: {get_param: db_oam_int_ip_0}}, {“ip_address”: {get_param: db_oam_int_v6_ip_0 ]}}]
3813 type: OS::Neutron::Port
3815 network: { get_param: int_oam_int_net_id }
3817 - “ip_address”: {get_param: db_oam_int_ip_1}}]
3818 - “ip_address”: {get_param: db_oam_int_v6_ip_1}}]
3820 Property: allowed\_address\_pairs, Map Property: ip\_address
3821 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3823 The property allowed\_address\_pairs in the resource OS::Neutron::Port
3824 allows the user to specify a mac\_address and/or ip\_address that will
3825 pass through a port regardless of subnet. This enables the use of
3826 protocols such as VRRP, which floats an IP address between two instances
3827 to enable fast data plane failover. The map property ip\_address
3828 specifies the IP address.
3830 The allowed\_address\_pairs is an optional property. It is not required.
3832 An ONAP Heat Orchestration Template allows the assignment of one IPv4
3833 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
3834 and {network-role}/int\_{network-role} combination.
3836 An ONAP Heat Orchestration Template allows the assignment of one IPv6
3837 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
3838 and {network-role}/int\_{network-role} combination.
3840 Note that the management of these IP addresses (i.e. transferring
3841 ownership between active and standby VMs) is the responsibility of the
3844 Note that these parameters are **not** intended to represent Neutron
3845 “Floating IP” resources, for which OpenStack manages a pool of public IP
3846 addresses that are mapped to specific VM ports. In that case, the
3847 individual VMs are not even aware of the public IPs, and all assignment
3848 of public IPs to VMs is via OpenStack commands. ONAP does not support
3849 Neutron-style Floating IPs.
3854 R-61282 The VNF Heat Orchestration Template **MUST**
3855 adhere to the following naming convention for the property
3856 allowed\_address\_pairs and Map Property ip\_address parameter,
3857 when the parameter is referencing an “external” network:
3859 - {vm-type}\_{network-role}\_floating\_ip for an IPv4 address
3861 - {vm-type}\_{network-role}\_floating\_v6\_ip for an IPv6 address
3863 The parameter must be declared as type: string
3865 The parameter must not be enumerated in the Heat environment file.
3867 *Example Parameter Definition*
3869 .. code-block:: yaml
3873 {vm-type}_{network-role}_floating_ip:
3875 description: VIP for {vm-type} VMs on the {network-role} network
3877 {vm-type}_{network-role}_floating_v6_ip:
3879 description: VIP for {vm-type} VMs on the {network-role} network
3883 In this example, the {network-role} has been defined as oam to represent
3884 an oam network and the {vm-type} has been defined as db for database.
3886 .. code-block:: yaml
3891 description: Neutron UUID for the oam network
3894 type: comma_delimited_list
3895 description: Fixed IPs for db VMs on the oam network
3899 description: VIP IP for db VMs on the oam network
3903 type: OS::Neutron::Port
3905 network: { get_param: oam_net_id }
3906 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,0] }}]
3907 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
3910 type: OS::Neutron::Port
3912 network: { get_param: oam_net_id }
3913 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,1] }}]
3914 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
3919 R-16805 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention
3920 for the property allowed\_address\_pairs and Map Property ip\_address
3921 parameter when the parameter is referencing an “internal” network.
3923 - {vm-type}\_int\_{network-role}\_floating\_ip for an IPv4 address
3925 - {vm-type}\_int\_{network-role}\_floating\_v6\_ip for an IPv6 address
3927 The parameter must be declared as type: string
3929 The parameter must be enumerated in the Heat environment file.
3931 *Example Parameter Definition*
3933 .. code-block:: yaml
3937 {vm-type}_int_{network-role}_floating_ip:
3939 description: VIP for {vm-type} VMs on the int_{network-role} network
3941 {vm-type}_int_{network-role}_floating_v6_ip:
3943 description: VIP for {vm-type} VMs on the int_{network-role} network
3945 Multiple allowed\_address\_pairs for a {vm-type} / {network-role} combination
3946 __________________________________________________________________
3948 The parameter {vm-type}\_{network-role}\_floating\_ip provides only one
3949 allowed address pair IPv4 address per {vm-type} and {network-role} pair.
3951 The parameter {vm-type}\_{network-role}\_floating\_v6\_ip provides only
3952 one allowed address pair IPv6 address per {vm-type} and {network-role}
3955 If there is a need for multiple allowed address pair IPs for a given
3956 {vm-type} and {network-role} combination within a VNF, then the
3957 parameter names defined for the property fixed\_ips and Map Property
3958 ip\_address should be used with the allowed\_address\_pairs property.
3959 The examples below illustrate this.
3961 *Example: A VNF has four load balancers. Each pair has a unique VIP.*
3963 In this example, there are two administrative VM pairs. Each pair has
3964 one VIP. The {network-role} has been defined as oam to represent an oam
3965 network and the {vm-type} has been defined as admin for an
3968 Pair 1: Resources admin\_0\_port\_0 and admin\_1\_port\_0 share a unique
3969 VIP, [admin\_oam\_ips,2]
3971 Pair 2: Resources admin\_2\_port\_0 and admin\_3\_port\_0 share a unique
3972 VIP, [admin\_oam\_ips,5]
3974 .. code-block:: yaml
3979 description: Neutron UUID for the oam network
3981 type: comma_delimited_list
3982 description: Fixed IP assignments for admin VMs on the oam network
3987 type: OS::Neutron::Port
3989 network: { get_param: oam_net_id }
3990 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,0] }}]
3991 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
3994 type: OS::Neutron::Port
3996 network: { get_param: oam_net_id }
3997 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,1] }}]
3998 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
4001 type: OS::Neutron::Port
4003 network: { get_param: oam_net_id }
4004 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,3] }}]
4005 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
4008 type: OS::Neutron::Port
4010 network: { get_param: oam_net_id }
4011 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,4] }}]
4012 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
4014 *Example: A VNF has two load balancers. The pair of load balancers share
4017 In this example, there is one load balancer pairs. The pair has two
4018 VIPs. The {network-role} has been defined as oam to represent an oam
4019 network and the {vm-type} has been defined as lb for a load balancer VM.
4021 .. code-block:: yaml
4025 type: OS::Neutron::Port
4027 network: { get_param: oam_net_id }
4028 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,0] }}]
4029 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
4032 type: OS::Neutron::Port
4034 network: { get_param: oam_net_id }
4035 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,1] }}]
4036 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
4038 As a general rule, provide the fixed IPs for the VMs indexed first in
4039 the CDL and then the VIPs as shown in the examples above.
4041 ONAP SDN-C Assignment of allowed\_address\_pair IP Addresses
4042 __________________________________________________________________
4044 The following items must be taken into consideration when designing Heat
4045 Orchestration Templates that expect ONAP’s SDN-C to assign
4046 allowed\_address\_pair IP addresses via automation.
4048 The VMs must be of the same {vm-type}.
4050 The VMs must be created in the same module (base or incremental).
4052 Resource Property “name”
4053 ~~~~~~~~~~~~~~~~~~~~~~~~
4055 The parameter naming convention of the property name for the resource
4056 OS::Nova::Server has been defined in
4057 `Resource: OS::Nova::Server – Metadata Parameters`_.
4059 This section provides the requirements how the property name for non
4060 OS::Nova::Server resources must be defined when the property is used.
4061 Not all resources require the property name (e.g., it is optional) and
4062 some resources do not support the property.
4064 R-85734 The VNF Heat Orchestration Template **MUST** use the intrinsic function str\_replace
4065 in conjunction with the ONAP supplied metadata parameter
4066 vnf\_name to generate a unique value,
4067 when the property name for a non OS::Nova::Server resources is defined
4068 in a Heat Orchestration Template.
4070 This prevents the enumeration of a
4071 unique value for the property name in a per instance environment file.
4075 - In most cases, only the use of the metadata value vnf\_name is
4076 required to create a unique property name
4078 - the Heat Orchestration Template pseudo parameter 'OS::stack\_name’
4079 may also be used in the str\_replace construct to generate a unique
4080 name when the vnf\_name does not provide uniqueness
4082 *Example: Property* name *for resource* OS::Neutron::SecurityGroup
4084 .. code-block:: yaml
4088 type: OS::Neutron::SecurityGroup
4090 description: vDNS security group
4093 template: VNF_NAME_sec_grp_DNS
4095 VNF_NAME: {get_param: vnf_name}
4099 *Example: Property name for resource* OS::Cinder::Volume
4101 .. code-block:: yaml
4105 type: OS::Cinder::Volume
4107 description: Cinder Volume
4110 template: VNF_NAME_STACK_NAME_dns_volume
4112 VNF_NAME: {get_param: vnf_name}
4113 STACK_NAME: { get_param: 'OS::stack_name' }
4116 Contrail Issue with Values for the Property Name
4117 ++++++++++++++++++++++++++++++++++++++++++++++++
4119 The Contrail GUI has a limitation displaying special characters. The
4120 issue is documented in
4121 https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is
4122 recommended that special characters be avoided. However, if special
4123 characters must be used, note that for the following resources:
4137 the only special characters supported are:
4139 - “ ! $ ‘ ( ) = ~ ^ \| @ \` { } [ ] > , . \_
4141 ONAP Output Parameter Names
4142 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
4144 ONAP defines three types of Output Parameters as detailed in
4145 `Output Parameters`_.
4147 ONAP Base Module Output Parameters:
4148 +++++++++++++++++++++++++++++++++++
4150 ONAP Base Module Output Parameters do not have an explicit naming
4151 convention. The parameter name must contain {vm-type} and {network-role}
4154 ONAP Volume Template Output Parameters:
4155 +++++++++++++++++++++++++++++++++++++++
4157 ONAP Base Module Output Parameters do not have an explicit naming
4158 convention. The parameter name must contain {vm-type} when appropriate.
4160 Predefined Output Parameters
4161 ++++++++++++++++++++++++++++
4163 ONAP currently defines one predefined output parameter the OAM
4164 Management IP Addresses.
4166 OAM Management IP Addresses
4167 ___________________________
4169 A VNF may have a management interface for application controllers to
4170 interact with and configure the VNF. Typically, this will be via a
4171 specific VM that performs a VNF administration function. The IP address
4172 of this interface must be captured and inventoried by ONAP. The IP
4173 address might be a VIP if the VNF contains an HA pair of management VMs,
4174 or may be a single IP address assigned to one VM.
4176 The Heat template may define either (or both) of the following Output
4177 parameters to identify the management IP address.
4179 - oam\_management\_v4\_address
4181 - oam\_management\_v6\_address
4185 - The use of this output parameters are optional.
4187 - The Management IP Address should be defined only once per VNF, so it
4188 must only appear in one Module template
4190 - If a fixed IP for the admin VM is passed as an input parameter, it
4191 may be echoed in the output parameters. In this case, a IPv4 and/or
4192 IPv6 parameter must be defined in the parameter section of the YAML
4193 Heat template. The parameter maybe named oam\_management\_v4\_address
4194 and/or oam\_management\_v6\_address or may be named differently.
4196 - If the IP for the admin VM is obtained via DHCP, it may be obtained
4197 from the resource attributes. In this case,
4198 oam\_management\_v4\_address and/or oam\_management\_v6\_address must
4199 not be defined in the parameter section of the YAML Heat template.
4201 *Example: SDN-C Assigned IP Address echoed as*
4202 oam\_management\_v4\_address
4204 .. code-block:: yaml
4209 description: Fixed IPv4 assignment for admin VM 0 on the OAM network
4213 admin_oam_net_0_port:
4214 type: OS::Neutron::Port
4218 template: VNF_NAME_admin_oam_net_0_port
4220 VNF_NAME: {get_param: vnf_name}
4221 network: { get_param: oam_net_id }
4222 fixed_ips: [{ "ip_address": { get_param: admin_oam_ip_0 }}]
4223 security_groups: [{ get_param: security_group }]
4226 type: OS::Nova::Server
4228 name: { get_param: admin_names }
4229 image: { get_param: admin_image_name }
4230 flavor: { get_param: admin_flavor_name }
4231 availability_zone: { get_param: availability_zone_0 }
4233 - port: { get_resource: admin_oam_net_0_port }
4235 vnf_id: { get_param: vnf_id }
4236 vf_module_id: { get_param: vf_module_id }
4237 vnf_name: {get_param: vnf_name }
4239 oam_management_v4_address:
4240 value: {get_param: admin_oam_ip_0 }
4242 *Example: Cloud Assigned IP Address output as*
4243 oam\_management\_v4\_address
4245 .. code-block:: yaml
4250 admin_oam_net_0_port:
4251 type: OS::Neutron::Port
4255 template: VNF_NAME_admin_oam_net_0_port
4257 VNF_NAME: {get_param: vnf_name}
4258 network: { get_param: oam_net_id }
4259 security_groups: [{ get_param: security_group }]
4262 type: OS::Nova::Server
4264 name: { get_param: admin_names }
4265 image: { get_param: admin_image_name }
4266 flavor: { get_param: admin_flavor_name }
4267 availability_zone: { get_param: availability_zone_0 }
4269 - port: { get_resource: admin_oam_net_0_port }
4271 vnf_id: { get_param: vnf_id }
4272 vf_module_id: { get_param: vf_module_id }
4273 vnf_name: {get_param: vnf_name }
4276 oam_management_v4_address:
4277 value: {get_attr: [admin_server, networks, {get_param: oam_net_id}, 0] }
4279 Contrail Resource Parameters
4280 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4282 ONAP requires the parameter names of certain Contrail Resources to
4283 follow specific naming conventions. This section provides these
4286 Contrail Network Parameters
4287 +++++++++++++++++++++++++++
4289 Contrail based resources may require references to a Contrail network
4290 using the network FQDN.
4295 When the parameter associated with the Contrail Network is referencing
4296 an “external” network, the parameter must adhere to the following naming
4297 convention in the Heat Orchestration Template
4299 - {network-role}\_net\_fqdn
4301 The parameter must be declared as type: string
4303 The parameter must not be enumerated in the Heat environment file.
4305 *Example: Parameter declaration*
4307 .. code-block:: yaml
4310 {network-role}_net_fqdn:
4312 description: Contrail FQDN for the {network-role} network
4314 *Example: Contrail Resource OS::ContrailV2::VirtualMachineInterface
4315 Reference to a Network FQDN.*
4317 In this example, the {network-role} has been defined as oam to represent
4318 an oam network and the {vm-type} has been defined as fw for firewall.
4319 The Contrail resource OS::ContrailV2::VirtualMachineInterface property
4320 virtual\_network\_refs references a contrail network FQDN.
4322 .. code-block:: yaml
4325 type: OS::ContrailV2::VirtualMachineInterface
4329 template: VM_NAME_virtual_machine_interface_1
4331 VM_NAME: { get_param: fw_name_0 }
4332 virtual_machine_interface_properties:
4333 virtual_machine_interface_properties_service_interface_type: { get_param: oam_protected_interface_type }
4334 virtual_network_refs:
4335 - get_param: oam_net_fqdn
4336 security_group_refs:
4337 - get_param: fw_sec_grp_id
4339 Interface Route Table Prefixes for Contrail InterfaceRoute Table
4340 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4342 The parameter associated with the resource
4343 OS::ContrailV2::InterfaceRouteTable property
4344 interface\_route\_table\_routes, map property
4345 interface\_route\_table\_routes\_route\_prefix is an ONAP Orchestration
4348 The parameters must be named {vm-type}\_{network-role}\_route\_prefixes
4349 in the Heat Orchestration Template.
4351 The parameter must be declared as type: json
4353 The parameter supports IP addresses in the format:
4355 1. Host IP Address (e.g., 10.10.10.10)
4357 2. CIDR Notation format (e.g., 10.0.0.0/28)
4359 The parameter must not be enumerated in the Heat environment file.
4361 *Example Parameter Definition*
4363 .. code-block:: yaml
4366 {vm-type}_{network-role}_route_prefixes:
4368 description: JSON list of Contrail Interface Route Table route prefixes
4372 .. code-block:: yaml
4377 description: Unique name for this VF instance
4378 fw_int_fw_route_prefixes:
4380 description: prefix for the ServiceInstance InterfaceRouteTable
4381 int_fw_dns_trusted_interface_type:
4383 description: service_interface_type for ServiceInstance
4386 type: OS::ContrailV2::InterfaceRouteTable
4387 depends_on: [*resource name of* *OS::ContrailV2::ServiceInstance*]
4391 template: VNF_NAME_interface_route_table
4393 VNF_NAME: { get_param: vnf_name }
4394 interface_route_table_routes:
4395 interface_route_table_routes_route: { get_param: fw_int_fw_route_prefixes }
4396 service_instance_refs:
4397 - get_resource: < *resource name of* *OS::ContrailV2::ServiceInstance* >
4398 service_instance_refs_data:
4399 - service_instance_refs_data_interface_type: { get_param: int_fw_interface_type }
4401 Parameter Names in Contrail Resources
4402 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4404 Contrail Heat resource properties will use, when appropriate, the same
4405 naming convention as OpenStack Heat resources. For example, the resource
4406 OS::ContrailV2::InstanceIp has two properties that the parameter naming
4407 convention is identical to properties in OS::Neutron::Port.
4409 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4410 instance\_ip\_address*
4412 The property instance\_ip\_address uses the same parameter naming
4413 convention as the property fixed\_ips and Map Property ip\_address in
4414 OS::Neutron::Port. The resource is assigning an ONAP SDN-C Assigned IP
4415 Address. The {network-role} has been defined as oam\_protected to
4416 represent an oam protected network and the {vm-type} has been defined as
4419 .. code-block:: yaml
4421 CMD_FW_OAM_PROTECTED_RII:
4422 type: OS::ContrailV2::InstanceIp
4424 - FW_OAM_PROTECTED_RVMI
4426 virtual_machine_interface_refs:
4427 - get_resource: FW_OAM_PROTECTED_RVMI
4428 virtual_network_refs:
4429 - get_param: oam_protected_net_fqdn
4430 instance_ip_address: { get_param: [fw_oam_protected_ips, get_param: index ] }
4432 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4435 The property instance\_ip\_address uses the same parameter naming
4436 convention as the property fixed\_ips and Map Property subnet\_id in
4437 OS::Neutron::Port. The resource is assigning a Cloud Assigned IP
4438 Address. The {network-role} has been defined as “oam\_protected” to
4439 represent an oam protected network and the {vm-type} has been defined as
4442 .. code-block:: yaml
4444 CMD_FW_SGI_PROTECTED_RII:
4445 type: OS::ContrailV2::InstanceIp
4447 - FW_OAM_PROTECTED_RVMI
4449 virtual_machine_interface_refs:
4450 - get_resource: FW_OAM_PROTECTED_RVMI
4451 virtual_network_refs:
4452 - get_param: oam_protected_net_fqdn
4453 subnet_uuid: { get_param: oam_protected_subnet_id }
4455 Cinder Volume Templates
4456 ^^^^^^^^^^^^^^^^^^^^^^^^
4458 ONAP supports the independent deployment of a Cinder volume via separate
4459 Heat Orchestration Templates, the Cinder Volume module. This allows the
4460 volume to persist after VNF deletion so that they can be reused on
4461 another instance (e.g., during a failover activity).
4463 A Base Module or Incremental Module may have a corresponding volume
4464 module. Use of separate volume modules is optional. A Cinder volume may
4465 be embedded within the Base Module or Incremental Module if persistence
4468 R-47788 The VNF Heat Orchestration Template **MUST** have a 1:1 scope of a cinder volume module,
4469 when it exists, with the Base Module or Incremental Module
4471 A single volume module must create only the volumes
4472 required by a single Incremental module or Base module.
4474 The following rules apply to independent volume Heat templates:
4476 - Cinder volumes must be created in a separate Heat Orchestration
4477 Template from the Base Module or Incremental Module.
4479 - A single Cinder volume module must include all Cinder volumes
4480 needed by the Base/Incremental module.
4482 - R-79531 The VNF Heat Orchestration Template **MUST** define “outputs” in the volume
4483 template for each Cinder volume resource universally unique
4484 identifier (UUID) (i.e. ONAP Volume Template Output Parameters).
4486 - The VNF Incremental Module or Base Module must define input
4487 parameters that match each Volume output parameter (i.e., ONAP Volume
4488 Template Output Parameters).
4490 - ONAP will supply the volume template outputs automatically to the
4491 bases/incremental template input parameters.
4493 - Volume modules may utilize nested Heat templates.
4495 *Examples: Volume Template*
4497 A VNF has a Cinder volume module, named incremental\_volume.yaml, that
4498 creates an independent Cinder volume for a VM in the module
4499 incremental.yaml. The incremental\_volume.yaml defines a parameter in
4500 the output section, lb\_volume\_id\_0 which is the UUID of the cinder
4501 volume. lb\_volume\_id\_0 is defined as a parameter in incremental.yaml.
4502 ONAP captures the UUID value of lb\_volume\_id\_0 from the volume module
4503 output statement and provides the value to the incremental module.
4505 Note that the example below is not a complete Heat Orchestration
4506 Template. The {vm-type} has been defined as “lb” for load balancer
4508 incremental\_volume.yaml
4510 .. code-block:: yaml
4521 type: OS::Cinder::Volume
4525 template: VNF_NAME_volume_0
4527 VNF_NAME: { get_param: vnf_name }
4528 size: {get_param: dns_volume_size_0}
4533 value: {get_resource: dns_volume_0}
4539 .. code-block:: yaml
4550 type: OS::Nova::Server
4552 name: {get_param: dns_name_0}
4557 type: OS::Cinder::VolumeAttachment
4559 instance_uuid: { get_resource: lb_0 }
4560 volume_id: { get_param: lb_volume_id_0 }
4562 ONAP Support of Environment Files
4563 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4565 The use of an environment file in OpenStack is optional. In ONAP, it is
4568 R-86285 The VNF Heat Orchestration Template **MUST** have a
4569 corresponding environment file, even if no parameters are required to be
4572 (Note that ONAP, the open source version of ONAP, does not
4573 programmatically enforce the use of an environment file.)
4575 R-67205 The VNF Heat Orchestration Template **MUST** have a corresponding
4576 environment file for a Base Module.
4578 R-35727 The VNF Heat Orchestration Template **MUST** have a
4579 corresponding environment file for an Incremental module.
4581 R-22656 The VNF Heat Orchestration Template **MUST** have a corresponding environment file
4582 for a Cinder Volume Module.
4584 A nested heat template must not have an environment file; OpenStack does
4587 The environment file must contain parameter values for the ONAP
4588 Orchestration Constants and VNF Orchestration Constants. These
4589 parameters are identical across all instances of a VNF type, and
4590 expected to change infrequently. The ONAP Orchestration Constants are
4591 associated with OS::Nova::Server image and flavor properties (See
4592 `Property: image`_ and `Property: flavor`_). Examples of VNF
4593 Orchestration Constants are the networking parameters associated
4594 with an internal network (e.g., private IP ranges) and Cinder
4597 The environment file must not contain parameter values for parameters
4598 that are instance specific (ONAP Orchestration Parameters, VNF
4599 Orchestration Parameters). These parameters are supplied to the Heat by
4600 ONAP at orchestration time.
4602 SDC Treatment of Environment Files
4603 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4605 Parameter values enumerated in the environment file are used by SDC as
4606 the default value. However, the SDC user may use the SDC GUI to
4607 overwrite the default values in the environment file.
4609 SDC generates a new environment file for distribution to MSO based on
4610 the uploaded environment file and the user provided GUI updates. The
4611 user uploaded environment file is discarded when the new file is
4612 created. Note that if the user did not change any values via GUI
4613 updates, the SDC generated environment file will contain the same values
4614 as the uploaded file.
4616 Use of Environment Files when using OpenStack “heat stack-create” CLI
4617 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4619 When ONAP is instantiating the Heat Orchestration Template, certain
4620 parameter must not be enumerated in the environment file. This document
4621 provides the details of what parameters should not be enumerated.
4623 If the Heat Orchestration Template is to be instantiated from the
4624 OpenStack Command Line Interface (CLI) using the command “heat
4625 stack-create”, all parameters must be enumerated in the environment
4628 Heat Template Constructs
4629 ^^^^^^^^^^^^^^^^^^^^^^^^^
4631 Nested Heat Templates
4632 ~~~~~~~~~~~~~~~~~~~~~
4634 ONAP supports nested Heat templates per the OpenStack specifications.
4635 Nested templates may be suitable for larger VNFs that contain many
4636 repeated instances of the same VM type(s). A common usage pattern is to
4637 create a nested template for each {vm-type} along with its supporting
4638 resources. The VNF module may then reference these component templates
4639 either statically by repeated definition or dynamically by using the
4640 resource OS::Heat::ResourceGroup.
4642 Nested Heat Template Requirements
4643 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4645 ONAP supports nested Heat Orchestration Templates. A Base Module,
4646 Incremental Module, and Cinder Volume Module may use nested heat.
4648 A Heat Orchestration Template may reference the nested heat statically
4649 by repeated definition.
4651 A Heat Orchestration Template may reference the nested heat dynamically
4652 using the resource OS::Heat::ResourceGroup.
4654 A Heat Orchestration template must have no more than three levels of
4655 nesting. ONAP supports a maximum of three levels.
4657 Nested heat templates must be referenced by file name. The use of
4658 resource\_registry in the environment file is not supported and must not
4661 R-89868 The VNF Heat Orchestration Template **MUST** have unique file names within the scope
4662 of the VNF for a nested heat yaml file.
4664 R-52530 The VNF Heat Orchestration Template **MUST NOT** use a directory hierarchy for
4665 nested templates. All templates must be in a single, flat directory
4668 A nested heat template may be used by any module within a given VNF.
4672 - Constrains must not be defined for any parameter enumerated in a
4673 nested heat template.
4675 - R-11041 The VNF Heat Orchestration Template **MUST** have the resource calling the
4676 nested yaml file pass in as properties all parameters defined
4677 in nested yaml file.
4679 - 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
4682 - With nested templates, outputs are required to expose any resource
4683 properties of the child templates to the parent template. Those would
4684 not explicitly be declared as parameters but simply referenced as
4685 get\_attribute targets against the “parent” resource.
4687 Nested Heat Template Example: Static
4688 ++++++++++++++++++++++++++++++++++++++
4692 .. code-block:: yaml
4698 dns_image_name: { get_param: dns_image_name }
4699 dns_flavor_name: { get_param: dns_flavor_name }
4700 availability_zone: { get_param: availability_zone_0 }
4701 security_group: { get_param: DNS_shared_sec_grp_id }
4702 oam_net_id: { get_param: oam_protected_net_id }
4703 dns_oam_ip: { get_param: dns_oam_ip_0 }
4704 dns_name: { get_param: dns_name_0 }
4705 vnf_name: { get_param: vnf_name }
4706 vnf_id: { get_param: vnf_id }
4707 vf_module_id: {get_param: vf_module_id}
4712 dns_image_name: { get_param: dns_image_name }
4713 dns_flavor_name: { get_param: dns_flavor_name }
4714 availability_zone: { get_param: availability_zone_1 }
4715 security_group: { get_param: DNS_shared_sec_grp_id }
4716 oam_net_id: { get_param: oam_protected_net_id }
4717 dns_oam_ip: { get_param: dns_oam_ip_1 }
4718 dns_name: { get_param: dns_name_1 }
4719 vnf_name: { get_param: vnf_name }
4720 vnf_id: { get_param: vnf_id }
4721 vf_module_id: {get_param: vf_module_id}
4725 .. code-block:: yaml
4728 type: OS::Neutron::Port
4732 template: VNF_NAME_dns_oam_port
4734 VNF_NAME: {get_param: vnf_name}
4735 network: { get_param: oam_net_id }
4736 fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}]
4737 security_groups: [{ get_param: security_group }]
4740 type: OS::Nova::Server
4742 name: { get_param: dns_names }
4743 image: { get_param: dns_image_name }
4744 flavor: { get_param: dns_flavor_name }
4745 availability_zone: { get_param: availability_zone }
4747 - port: { get_resource: dns_oam_0_port }
4749 vnf_id: { get_param: vnf_id }
4750 vf_module_id: { get_param: vf_module_id }
4751 vnf_name {get_param: vnf_name }
4753 Use of Heat ResourceGroup
4754 +++++++++++++++++++++++++
4756 The OS::Heat::ResourceGroup is a useful Heat element for creating
4757 multiple instances of a given resource or collection of resources.
4758 Typically, it is used with a nested Heat template, to create, for
4759 example, a set of identical OS::Nova::Server resources plus their
4760 related OS::Neutron::Port resources via a single resource in a master
4763 ResourceGroup may be used in ONAP to simplify the structure of a Heat
4764 template that creates multiple instances of the same VM type.
4766 However, there are important caveats to be aware of:
4768 ResourceGroup does not deal with structured parameters
4769 (comma-delimited-list and json) as one might typically expect. In
4770 particular, when using a list-based parameter, where each list element
4771 corresponds to one instance of the ResourceGroup, it is not possible to
4772 use the intrinsic “loop variable” %index% in the ResourceGroup
4775 For instance, the following is **not** valid Heat for ResourceGroup:
4777 .. code-block:: yaml
4779 type: OS::Heat::ResourceGroup
4781 type: my_nested_vm_template.yaml
4783 name: {get_param: [vm_name_list, %index%]}
4785 Although this appears to use the nth entry of the vm\_name\_list list
4786 for the nth element of the ResourceGroup, it will in fact result in a
4787 Heat exception. When parameters are provided as a list (one for each
4788 element of a ResourceGroup), you must pass the complete parameter to the
4789 nested template along with the current index as separate parameters.
4791 Below is an example of an **acceptable** Heat Syntax for a
4794 .. code-block:: yaml
4796 type: OS::Heat::ResourceGroup
4798 type: my_nested_vm_template.yaml
4800 names: {get_param: vm_name_list}
4803 You can then reference within the nested template as:
4805 { get\_param: [names, {get\_param: index} ] }
4807 ResourceGroup Property count
4808 ____________________________
4810 ONAP requires that the OS::Heat::ResourceGroup property count be defined
4811 (even if the value is one) and that the value must be enumerated in the
4812 environment file. This is required for ONAP to build the TOSCA model for
4815 .. code-block:: yaml
4817 type: OS::Heat::ResourceGroup
4819 count: { get_param: count }
4822 type: my_nested_vm_template.yaml
4824 names: {get_param: vm_name_list}
4827 Availability Zone and ResourceGroups
4828 ____________________________________
4830 The resource OS::Heat::ResourceGroup and the property availability\_zone
4831 has been an “issue” with a few VNFs since ONAP only supports
4832 availability\_zone as a string parameter and not a
4833 comma\_delimited\_list. This makes it difficult to use a ResourceGroup
4834 to create Virtual Machines in more than one availability zone.
4836 There are numerous solutions to this issue. Below are two suggested
4839 **Option 1:** create a CDL in the OS::Heat::ResourceGroup. In the
4840 resource type: OS::Heat::ResourceGroup, create a comma\_delimited\_list
4841 availability\_zones by using the intrinsic function list\_join.
4843 .. code-block:: yaml
4846 type: OS::Heat::ResourceGroup
4848 count: { get_param: node_count }
4854 avaialability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] }
4858 .. code-block:: yaml
4861 avaialability_zones:
4862 type: comma_delimited_list
4867 type: OS::Nova::Server
4869 name: { get_param: [ dns_names, get_param: index ] }
4870 image: { get_param: dns_image_name }
4871 flavor: { get_param: dns_flavor_name }
4872 availability_zone: { get_param: [ avaialability_zones, get_param: index ] }
4875 **Option 2:** Create a resource group per availability zone. A separate
4876 OS::Heat::ResourceGroup is created for each availability zone.
4881 Heat templates *should not* reference any HTTP-based resource
4882 definitions, any HTTP-based nested configurations, or any HTTP-based
4885 - During orchestration, ONAP *should not* retrieve any such resources
4886 from external/untrusted/unknown sources.
4888 - VNF images should not contain such references in user-data or other
4889 configuration/operational scripts that are specified via Heat or
4890 encoded into the VNF image itself.
4892 *Note:* HTTP-based references are acceptable if the HTTP-based reference
4893 is accessing information with the VM private/internal network.
4895 Heat Files Support (get\_file)
4896 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4898 Heat Templates may contain the inclusion of text files into Heat
4899 templates via the Heat get\_file directive. This may be used, for
4900 example, to define a common “user-data” script, or to inject files into
4901 a VM on startup via the “personality” property.
4903 Support for Heat Files is subject to the following limitations:
4905 R-76718 The VNF Heat Orchestration Template **MUST** reference the get\_files targets in
4906 Heat templates by file name, and the corresponding files should be
4907 delivered to ONAP along with the Heat templates.
4909 R-41888 The VNE Heat **MUST NOT** use URL-based file retrieval.
4911 R-62177 The VNF Heat Orchestration Template **MUST** have unique file names for the included
4912 files within the scope of the VNF.
4914 R-87848 The VNF Heat Orchestration Template **MUST** have all included files in a single, flat
4915 directory per VNF. ONAP does not support a directory hierarchy.
4917 - Included files may be used by all Modules within a given VNF.
4919 - get\_file directives may be used in both non-nested and nested
4925 When Nova Servers are created via Heat templates, they may be passed a
4926 “keypair” which provides an ssh key to the ‘root’ login on the newly
4927 created VM. This is often done so that an initial root key/password does
4928 not need to be hard-coded into the image.
4930 Key pairs are unusual in OpenStack, because they are the one resource
4931 that is owned by an OpenStack User as opposed to being owned by an
4932 OpenStack Tenant. As a result, they are usable only by the User that
4933 created the keypair. This causes a problem when a Heat template attempts
4934 to reference a keypair by name, because it assumes that the keypair was
4935 previously created by a specific ONAP user ID.
4937 When a keypair is assigned to a server, the SSH public-key is
4938 provisioned on the VMs at instantiation time. They keypair itself is not
4939 referenced further by the VM (i.e. if the keypair is updated with a new
4940 public key, it would only apply to subsequent VMs created with that
4943 Due to this behavior, the recommended usage of keypairs is in a more
4944 generic manner which does not require the pre-requisite creation of a
4945 keypair. The Heat should be structured in such a way as to:
4947 - Pass a public key as a parameter value instead of a keypair name
4949 - Create a new keypair within The VNF Heat Orchestration Template (in the base
4950 module) for use within that VNF
4952 By following this approach, the end result is the same as pre-creating
4953 the keypair using the public key – i.e., that public key will be
4954 provisioned in the new VM. However, this recommended approach also makes
4955 sure that a known public key is supplied (instead of having OpenStack
4956 generate a public/private pair to be saved and tracked outside of ONAP).
4957 It also removes any access/ownership issues over the created keypair.
4959 The public keys may be enumerated as a VNF Orchestration Constant in the
4960 environment file (since it is public, it is not a secret key), or passed
4961 at run-time as instance-specific parameters. ONAP will never
4962 automatically assign a public/private key pair.
4964 *Example (create keypair with an existing ssh public-key for {vm-type}
4965 of lb (for load balancer)):*
4967 .. code-block:: yaml
4977 type: OS::Nova::Keypair
4981 template: VNF_NAME_key_pair
4983 VNF_NAME: { get_param: vnf_name }
4984 public_key: {get_param: lb_ssh_public_key}
4985 save_private_key: false
4990 OpenStack allows a tenant to create Security groups and define rules
4991 within the security groups.
4993 Security groups, with their rules, may either be created in the Heat
4994 Orchestration Template or they can be pre-created in OpenStack and
4995 referenced within the Heat template via parameter(s). There can be a
4996 different approach for security groups assigned to ports on internal
4997 (intra-VNF) networks or external networks (inter-VNF). Furthermore,
4998 there can be a common security group across all VMs for a specific
4999 network or it can vary by VM (i.e., {vm-type}) and network type (i.e.,
5002 Anti-Affinity and Affinity Rules
5003 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5005 Anti-affinity or affinity rules are supported using normal OpenStack
5006 OS::Nova::ServerGroup resources. Separate ServerGroups are typically
5007 created for each VM type to prevent them from residing on the same host,
5008 but they can be applied to multiple VM types to extend the
5009 affinity/anti-affinity across related VM types as well.
5013 In this example, the {network-role} has been defined as oam to represent
5014 an oam network and the {vm-type} have been defined as lb for load
5015 balancer and db for database.
5017 .. code-block:: yaml
5021 type: OS::Nova::ServerGroup
5026 $vnf_name: {get_param: vnf_name}
5027 template: $vnf_name-server_group1
5032 type: OS::Nova::ServerGroup
5037 $vnf_name: {get_param: vnf_name}
5038 template: $vnf_name-server_group2
5043 type: OS::Nova::Server
5047 group: {get_resource: db_server_group}
5050 type: OS::Nova::Server
5054 group: {get_resource: db_server_group}
5057 type: OS::Nova::Server
5061 group: {get_resource: lb_server_group}
5063 Resource Data Synchronization
5064 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5066 For cases where synchronization is required in the orchestration of Heat
5067 resources, two approaches are recommended:
5069 - Standard Heat depends\_on property for resources
5071 - Assures that one resource completes before the dependent resource
5074 - Definition of completeness to OpenStack may not be sufficient
5075 (e.g., a VM is considered complete by OpenStack when it is ready
5076 to be booted, not when the application is up and running).
5078 - Use of Heat Notifications
5080 - Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle
5083 - Pre-requisite resources issue *wc\_notify* commands in user\_data.
5085 - Dependent resource define depends\_on in the
5086 OS::Heat::WaitCondition resource.
5088 *Example: “depends\_on” case*
5090 In this example, the {network-role} has been defined as oam to represent
5091 an oam network and the {vm-type} has been defined as oam to represent an
5094 .. code-block:: yaml
5098 type: OS::Nova::Server
5100 name: {get_param: [oam_ names, 0]}
5101 image: {get_param: oam_image_name}
5102 flavor: {get_param: oam_flavor_name}
5103 availability_zone: {get_param: availability_zone_0}
5105 - port: {get_resource: oam01_port_0}
5106 - port: {get_resource: oam01_port_1}
5108 scheduler_hints: {group: {get_resource: oam_servergroup}}
5109 user_data_format: RAW
5112 type: OS::Neutron::Port
5114 network: {get_resource: oam_net_name}
5115 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}]
5116 security_groups: [{get_resource: oam_security_group}]
5119 type: OS::Neutron::Port
5121 network: {get_param: oam_net_name}
5122 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}]
5123 security_groups: [{get_resource: oam_security_group}]
5125 oam_01_vol_attachment:
5126 type: OS::Cinder::VolumeAttachment
5127 depends_on: oam_server_01
5129 volume_id: {get_param: oam_vol_1}
5130 mountpoint: /dev/vdb
5131 instance_uuid: {get_resource: oam_server_01}
5136 VNF/VM parameters may include availability zone IDs for VNFs that
5137 require high availability.
5139 The Heat must comply with the following requirements to specific
5140 availability zone IDs:
5142 - The Heat template should spread Nova and Cinder resources across the
5143 availability zones as desired
5145 Post Orchestration & VNF Configuration
5146 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5148 Heat templates should contain a minimum amount of post-orchestration
5149 configuration data. For instance, *do not* embed complex user-data
5150 scripts in the template with large numbers of configuration parameters
5151 to the Heat template.
5153 - VNFs may provide configuration APIs for use after VNF creation. Such
5154 APIs will be invoked via application and/or SDN controllers.
5156 *Note:* It is important to follow this convention to the extent possible
5157 even in the short-term as of the long-term direction.
5159 VNFM Driver Development Steps
5160 -----------------------------------------------------------
5162 Refer to the ONAP documentation for VNF Provider instructions on integrating
5163 vendor-specific VNFM adaptors with VF-C. The VNF driver development steps are
5166 1. Use the VNF SDK tools to design the VNF with TOSCA models to output
5167 the VNF TOSCA package. Using the VNF SDK tools, the VNF package can be
5168 validated and tested.
5170 2. The VNF Provider supplies a vendor-specific VNFM driver in ONAP, which
5171 is a microservice providing a translation interface from VF-C to
5172 the vendor-specific VNFM. The interface definitions of vendor-specific
5173 VNFM adaptors are supplied by the VNF Providers themselves.
5175 Creating Vendor-Specific VNFM Adaptor Microservices
5176 ------------------------------------------------------------------------------------------------
5178 VNFs can be managed by vendor-specific VNFMs. To add a vendor-specific
5179 VNFM to ONAP, a vendor-specific VNFM adaptor is added to ONAP implementing
5180 the interface of the vendor-specific VNFM.
5182 A vendor-specific VNFM adaptor is a microservice with a unique name and
5183 an appointed port. When started up, the vendor-specific VNFM adaptor
5184 microservice is automatically registered to the Microservices Bus (MSB).
5185 The following RESTful example describes the scenario of registering a
5186 vendor-specific VNFM adaptor to MSB:
5188 .. code-block:: java
5190 POST /api/microservices/v1/services
5192 "serviceName": "catalog",
5194 "url": "/api/catalog/v1",
5199 "ip": "10.74.56.36",
Code Review / vnfrqts / requirements.git / blob