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 =========================
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:
3154 2. fixed_ips, ip_address
3155 3. fixed_ips, subnet_id or fixed_ips, subnet
3156 * Note that in many examples in this document fixed_ips, subnet_id is used.
3157 4. allowed_address_pairs, ip_address
3159 Below is a generic example. Note that for some parameters
3160 comma_delimited_list are supported in addition to String.
3162 .. code-block:: python
3169 type: OS::Neutron::Port
3171 allowed_address_pairs: [{"ip_address": String, "mac_address": String},
3172 {"ip_address": String, "mac_address": String}, ...]
3173 fixed_ips: [{"ip_address": String, "subnet_id": String, "subnet":
3174 String}, {"ip_address": String, "subnet_id": String, "subnet": String},
3178 The parameters associated with these properties may reference an
3179 external network or internal network. External networks and internal
3180 networks are defined in `Networking`_.
3182 When the OS::Neutron::Port is attaching to an external network, all
3183 property values are parameters that are retrieved via the intrinsic
3184 function 'get_param'.
3186 When the OS::Neutron::Port is attaching to an internal network, a
3187 property value maybe retrieved via the intrinsic
3188 function 'get_param', 'get_resource', or 'get_attr'.
3190 This will be described in the forth coming sections.
3195 A network (internal or external) may contain one or or more subnets.
3197 A VNF can have one or more ports connected to the same network.
3199 A port can have one or more IP addresses assigned.
3201 The IP address assignments can be IPv4 addresses and/or IPv6 addresses.
3203 The IP addresses assignments for a unique external network **MUST**
3204 be all Cloud Assigned addresses OR **MUST** be all ONAP
3205 SDN-C assigned IP addresses.
3207 If the IP addresses are Cloud Assigned, all the IPv4 Addresses **MUST**
3209 the same subnet and all the IPv6 Addresses **MUST** be from the
3212 If the IP addresses are ONAP SDN-C assigned,
3213 the IPv4 Addresses **MAY**
3215 different subnets and the IPv6 Addresses **MAY** be from different
3218 If a VNF's Port is attached to an external network the IP addresses **MAY**
3219 either be assigned by
3220 1. ONAP's SDN-Controller (SDN-C)
3221 2. Cloud Assigned by OpenStack’s DHCP Service
3223 If a VNF's Port is attached to an external network and the port's IP addresses
3224 are assigned by ONAP's SDN-Controller, the 'OS::Neutron::Port' Resource's
3225 * property 'fixed_ips' map property 'ip_address' **MUST** be used
3226 * property 'fixed_ips' map property 'subnet'/'subnet_id'
3227 **MUST NOT** be used
3229 If a VNF's Port is attached to an external network and the port's IP addresses
3230 are Cloud Assigned by OpenStack’s DHCP Service,
3231 the 'OS::Neutron::Port' Resource's
3232 * property 'fixed_ips' map property 'ip_address' **MUST NOT** be used
3233 * property fixed_ips' map property 'subnet'/'subnet_id' **MAY** be used
3235 If a VNF's Port is attached to an internal network and the port's IP addresses
3236 are assigned by the VNF's Heat Orchestration Template
3237 (i.e., enumerated in the Heat Orchestration Template's environment file),
3238 the 'OS::Neutron::Port' Resource's
3239 * property 'fixed_ips' map property 'ip_address' **MUST** be used
3240 * property 'fixed_ips' map property 'subnet'/'subnet_id'
3241 **MUST NOT** be used
3243 If a VNF's Port is attached to an internal network and the port's IP addresses
3244 are Cloud Assigned by OpenStack’s DHCP Service,
3245 the 'OS::Neutron::Port' Resource's
3246 * property 'fixed_ips' map property 'ip_address' **MUST NOT** be used
3247 * property 'fixed_ips' map property 'subnet'/'subnet_id'
3250 If a VNF's Heat Orchestration Template 'OS::Neutron::Port' Resource property
3251 'fixed_ips' map property 'ip_address' is specified, then the
3252 'fixed_ips' map property 'subnet'/'subnet_id' **MUST NOT**
3255 If a VNF's Heat Orchestration Template 'OS::Neutron::Port' Resource property
3256 'fixed_ips' map property 'subnet'/'subnet_id' is specified, then the
3257 'fixed_ips' map property 'ip_address' **MUST NOT**
3260 .. csv-table:: **Table 4 OS::Nova::Server Resource Property Parameter Naming Convention**
3261 :header: Resource,Property,Parameter Type,Parameter Name,Parameter Value Provided to Heat
3265 OS::Nova::Server, image, string, {vm-type}_image_name, Environment File
3270 The Resource 'OS::Neutron::Port' property 'network' determines what network
3271 the port is attached to.
3274 R-18008 The VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’
3275 property ‘network’ parameter **MUST** be declared as type: ‘string’.
3277 R-62983 When the VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’
3278 is attaching to an external network, the ‘network’ parameter name **MUST**
3280 - follow the naming convention ‘{network-role}_net_id’ if the Neutron
3281 network UUID value is used to reference the network
3282 - follow the naming convention ‘{network-role}_net_name’ if the OpenStack
3283 network name is used to reference the network.
3285 where ‘{network-role}’ is the network-role of the external network and
3286 a ‘get_param’ **MUST** be used as the intrinsic function.
3288 R-86182 When the VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’
3289 is attaching to an internal network, and the internal network is created in a different
3290 Heat Orchestration Template than the ‘OS::Neutron::Port’, the ‘network’
3291 parameter name **MUST**
3293 - follow the naming convention ‘int\_{network-role}_net_id’ if the Neutron
3294 network UUID value is used to reference the network
3295 - follow the naming convention ‘int\_{network-role}_net_name’ if the
3296 OpenStack network name in is used to reference the network.
3298 where ‘{network-role}’ is the network-role of the internal network and a ‘get_param’ **MUST** be used as the intrinsic function.
3300 In Requirement R-86182, the internal network is created in the VNF's
3301 Base Module (Heat Orchestration Template) and the parameter name is
3302 declared in the Base Module's outputs' section.
3303 The output parameter name will be declared as a parameter in the
3304 'parameters' section of the incremental module.
3306 R-93177 When the VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’
3307 is attaching to an internal network, and the internal network is created in the same Heat
3308 Orchestration Template than the ‘OS::Neutron::Port’, the ‘network’
3309 parameter name **MUST** obtain the UUID of the internal network by using
3310 the intrinsic function ‘get_resource’ or ‘get_attr’ and referencing the
3311 Resource ID of the internal network.
3313 R-29872 The VNF’s Heat Orchestration Template’s Resource ‘OS::Nova::Server’
3314 property ‘network’ parameter **MUST NOT** be enumerated in the Heat
3315 Orchestration Template’s Environment File.
3317 The parameter values for external networks are provided by ONAP
3318 to the VNF's Heat Orchestration Template at orchestration time.
3320 The parameter values for internal networks created in the VNF's Base Module
3321 Heat Orchestration Template
3322 are provided to the VNF's Incremental Module Heat Orchestration Template
3323 at orchestration time.
3325 *Example Parameter Definition of External Networks*
3327 .. code-block:: python
3331 {network-role}_net_id:
3333 description: Neutron UUID for the external {network-role} network
3335 {network-role}_net_name:
3337 description: Neutron name for the external {network-role} network
3340 *Example Parameter Definition of Internal Networks in an Incremental Module*
3342 .. code-block:: python
3346 int_{network-role}_net_id:
3348 description: Neutron UUID for the internal int_{network-role} network
3350 int_{network-role}_net_name:
3352 description: Neutron name for the internal int_{network-role} network
3354 Property: fixed_ips, Map Property: ip_address
3355 +++++++++++++++++++++++++++++++++++++++++++++
3357 The resource 'OS::Neutron::Port' property 'fixed_ips'
3358 map property 'ip_address'
3359 is used to assign one IPv4 or IPv6
3362 One 'OS::Neutron::Port' resource may assign one or more
3363 IPv4 and/or IPv6 addresses.
3365 R-34037 The VNF’s Heat Orchestration Template’s resource ‘OS::Neutron::Port’
3366 property ‘fixed_ips’ map property ‘ip_address’ parameter **MUST** be declared as
3367 either type ‘string’ or type ‘comma_delimited_list’.
3369 R-40971 When the VNF’s Heat Orchestration Template’s Resource
3370 ‘OS::Neutron::Port’ is attaching to an external network, and an IPv4 address is
3371 assigned using the property
3372 ‘fixed_ips’ map property ‘ip_address’ and the parameter type is defined
3373 as a string, the parameter name **MUST** follow the naming
3374 convention ‘{vm-type}_{network-role}\_ip\_{index}’, where
3376 - ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server
3377 - ‘{network-role}’ is the {network-role} of the external network
3378 - the value for {index} must start at zero (0) and increment by one
3380 R-39841 The VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’
3381 property ‘fixed_ips’ map property ‘ip_address’ parameter
3382 ‘{vm-type}_{network-role}\_ip\_{index}’ **MUST NOT** be enumerated in the
3383 VNF’s Heat Orchestration Template’s Environment File.
3385 ONAP's SDN-Controller assigns the IP Address and ONAP provides
3386 the value at orchestration to the Heat Orchestration Template.
3388 *Example External Network IPv4 Address string Parameter Definition*
3390 .. code-block:: python
3394 {vm-type}_{network-role}_ip_{index}:
3396 description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
3398 R-04697 When the VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’
3399 is attaching to an external network, and an IPv4 address is assigned using
3400 the property ‘fixed_ips’ map property ‘ip_address’ and the parameter type
3401 is defined as a comma_delimited_list, the parameter name **MUST** follow the
3402 naming convention ‘{vm-type}_{network-role}_ips’, where
3404 - ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server
3405 - ‘{network-role}’ is the {network-role} of the external network
3407 R-98905 The VNF’s Heat Orchestration Template’s Resource ‘OS::Neutron::Port’
3408 property ‘fixed_ips’ map property ‘ip_address’ parameter
3409 ‘{vm-type}_{network-role}_ips’ **MUST NOT** be enumerated in the VNF’s
3410 Heat Orchestration Template’s Environment File.
3412 ONAP's SDN-Controller assigns the IP Address and ONAP provides
3413 the value at orchestration to the Heat Orchestration Template.
3415 *Example External Network IPv4 Address comma_delimited_list
3416 Parameter Definition*
3418 .. code-block:: python
3422 {vm-type}_{network-role}_ips:
3423 type: comma_delimited_list
3424 description: Fixed IPv4 assignments for {vm-type} VMs on the {network-role} network
3426 R-71577 When the VNF’s Heat Orchestration Template’s Resource
3427 ‘OS::Neutron::Port’ is attaching to an external network, and an IPv6 address
3428 is assigned using the property ‘fixed_ips’ map property ‘ip_address’ and
3429 the parameter type is defined as a string, the parameter name **MUST** follow
3430 the naming convention ‘{vm-type}_{network-role}\_v6\_ip\_{index}’, where
3432 - ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server
3433 - ‘{network-role}’ is the {network-role} of the external network
3434 - the value for {index} must start at zero (0) and increment by one
3437 R-87123 The VNF’s Heat Orchestration Template’s Resource
3438 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’
3439 parameter ‘{vm-type}_{network-role}\_v6\_ip\_{index}’ **MUST NOT** be enumerated
3440 in the VNF’s Heat Orchestration Template’s Environment File.
3442 ONAP's SDN-Controller assigns the IP Address and ONAP provides
3443 the value at orchestration to the Heat Orchestration Template.
3445 *Example External Network IPv6 Address string Parameter Definition*
3447 .. code-block:: python
3451 {vm-type}_{network-role}_v6_ip_{index}:
3453 description: Fixed IPv6 assignment for {vm-type} VM {index} on the {network-role} network
3455 R-23503 When the VNF’s Heat Orchestration Template’s Resource
3456 ‘OS::Neutron::Port’ is attaching to an external network, and an IPv6
3457 address is assigned using the property ‘fixed_ips’ map property ‘ip_address’
3458 and the parameter type is defined as a comma_delimited_list, the parameter
3459 name **MUST** follow the naming convention ‘{vm-type}_{network-role}_v6_ips’, where
3461 - ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server
3462 - ‘{network-role}’ is the {network-role} of the external network
3464 R-93030 The VNF’s Heat Orchestration Template’s Resource
3465 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’
3466 parameter ‘{vm-type}_{network-role}_v6_ips’ **MUST NOT** be enumerated in the
3467 VNF’s Heat Orchestration Template’s Environment File.
3469 ONAP's SDN-Controller assigns the IP Address and ECOMP provides
3470 the value at orchestration to the Heat Orchestration Template.
3472 *Example External Network IPv6 Address comma_delimited_list Parameter
3475 .. code-block:: python
3479 {vm-type}_{network-role}_v6_ips:
3480 type: comma_delimited_list
3481 description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
3483 R-78380 When the VNF’s Heat Orchestration Template’s Resource
3484 ‘OS::Neutron::Port’ is attaching to an internal network, and an IPv4 address
3485 is assigned using the property ‘fixed_ips’ map property ‘ip_address’ and
3486 the parameter type is defined as a string, the parameter name **MUST** follow
3487 the naming convention ‘{vm-type}\_int\_{network-role}\_ip\_{index}’, where
3489 - ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server
3490 - ‘{network-role}’ is the {network-role} of the internal network
3491 - the value for {index} must start at zero (0) and increment by one
3493 R-28795 The VNF’s Heat Orchestration Template’s Resource
3494 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’
3495 parameter ‘{vm-type}\_int\_{network-role}\_ip\_{index}’ **MUST** be enumerated
3496 in the VNF’s Heat Orchestration Template’s Environment File.
3498 The IP address is local to the VNF's internal network and is (re)used
3499 in every VNF spin up, thus the constant value is declared in the VNF's
3500 Heat Orchestration Template's Environment File.
3502 *Example Internal Network IPv4 Address string Parameter Definition*
3504 .. code-block:: python
3508 {vm-type}_int_{network-role}_ip_{index}:
3510 description: Fixed IPv4 assignment for {vm-type} VM {index} on the int_{network-role} network
3512 R-85235 When the VNF’s Heat Orchestration Template’s Resource
3513 ‘OS::Neutron::Port’ is attaching to an internal network, and an IPv4
3514 address is assigned using the property ‘fixed_ips’ map property ‘ip_address’
3515 and the parameter type is defined as a comma_delimited_list, the parameter
3516 name **MUST** follow the naming convention ‘{vm-type}\_int\_{network-role}_ips’, where
3518 - ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server
3519 - ‘{network-role}’ is the {network-role} of the internal network
3521 R-90206 The VNF’s Heat Orchestration Template’s Resource
3522 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’
3523 parameter ‘{vm-type}\_int\_{network-role}_int_ips’ **MUST** be enumerated in
3524 the VNF’s Heat Orchestration Template’s Environment File.
3526 The IP address is local to the VNF's internal network and is (re)used
3527 in every VNF spin up, thus the constant value is declared in the VNF's
3528 Heat Orchestration Template's Environment File.
3530 .. code-block:: python
3534 {vm-type}_int_{network-role}_ips:
3535 type: comma_delimited_list
3536 description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
3538 R-27818 When the VNF’s Heat Orchestration Template’s Resource
3539 ‘OS::Neutron::Port’ is attaching to an internal network, and an IPv6 address
3540 is assigned using the property ‘fixed_ips’ map property ‘ip_address’ and
3541 the parameter type is defined as a string, the parameter name **MUST** follow
3542 the naming convention ‘{vm-type}\_int\_{network-role}\_v6\_ip\_{index}’, where
3544 - ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server
3545 - ‘{network-role}’ is the {network-role} of the internal network
3546 - the value for {index} must start at zero (0) and increment by one
3548 R-97201 The VNF’s Heat Orchestration Template’s Resource
3549 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’
3550 parameter ‘{vm-type}\_int\_{network-role}\_v6\_ip\_{index}’ **MUST** be enumerated
3551 in the VNF’s Heat Orchestration Template’s Environment File.
3553 The IP address is local to the VNF's internal network and is (re)used
3554 in every VNF spin up, thus the constant value is declared in the VNF's
3555 Heat Orchestration Template's Environment File.
3557 *Example Internal Network IPv6 Address string Parameter Definition*
3559 .. code-block:: python
3563 {vm-type}_int_{network-role}_v6_ip_{index}:
3565 description: Fixed IPv6 assignment for {vm-type} VM {index} on the int_{network-role} network
3567 R-29765 When the VNF’s Heat Orchestration Template’s Resource
3568 ‘OS::Neutron::Port’ is attaching to an internal network, and an IPv6
3569 address is assigned using the property ‘fixed_ips’ map property ‘ip_address’
3570 and the parameter type is defined as a comma_delimited_list, the parameter
3571 name **MUST** follow the naming convention ‘{vm-type}\_int\_{network-role}_v6_ips’, where
3573 - ‘{vm-type}’ is the {vm-type} associated with the OS::Nova::Server
3574 - ‘{network-role}’ is the {network-role} of the internal network
3576 *Example Internal Network IPv6 Address comma_delimited_list Parameter
3579 .. code-block:: python
3583 {vm-type}_int_{network-role}_v6_ips:
3584 type: comma_delimited_list
3585 description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
3587 R-98569 The VNF’s Heat Orchestration Template’s Resource
3588 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’
3589 parameter ‘{vm-type}\_int\_{network-role}_v6_ips’ **MUST** be enumerated in
3590 the VNF’s Heat Orchestration Template’s Environment File.
3592 The IP address is local to the VNF's internal network and is (re)used
3593 in every VNF spin up, thus the constant value is declared in the VNF's
3594 Heat Orchestration Template's Environment File.
3596 R-62590 The VNF’s Heat Orchestration Template’s Resource
3597 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’
3598 parameter associated with an external network, i.e.,
3600 - {vm-type}_{network-role}\_ip\_{index}
3601 - {vm-type}_{network-role}\_ip\_v6\_{index}
3602 - {vm-type}_{network-role}_ips
3603 - {vm-type}_{network-role}_v6_ips
3605 **MUST NOT** be enumerated in the Heat Orchestration Template’s Environment File.
3606 ONAP provides the IP address assignments at orchestration time.
3608 R-93496 The VNF’s Heat Orchestration Template’s Resource
3609 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property ‘ip_address’
3610 parameter associated with an internal network, i.e.,
3612 - {vm-type}\_int\_{network-role}\_ip\_{index}
3613 - {vm-type}\_int\_{network-role}\_ip\_v6\_{index}
3614 - {vm-type}\_int\_{network-role}_ips
3615 - {vm-type}\_int\_{network-role}_v6_ips
3617 **MUST** be enumerated in the Heat Orchestration Template’s Environment
3618 File and IP addresses **MUST** be assigned.
3623 .. csv-table:: **Table # OS::Neutron::Port Property fixed_ips map property ip_address Parameter Naming Convention**
3624 :header: Resource,Property,Map Property,Network Type,IP Address,Parameter Type,Parameter Name, Environment File
3628 OS::Neutron::Port, fixed_ips, ip_address, external, IPv4, string, {vm-type}\_{network-role}\_ip\_{index}, NO
3629 OS::Neutron::Port, fixed_ips, ip_address, external, IPv4, comma\_delimited\_list, {vm-type}\_{network-role}\_ips, NO
3630 OS::Neutron::Port, fixed_ips, ip_address, external, IPv6, string, {vm-type}\_{network-role}\_v6\_ip\_{index}, NO
3631 OS::Neutron::Port, fixed_ips, ip_address, external, IPv6, comma\_delimited\_list, {vm-type}\_{network-role}\_v6\_ips, NO
3632 OS::Neutron::Port, fixed_ips, ip_address, internal, IPv4, string, {vm-type}\_int\_{network-role}\_ip\_{index}, YES
3633 OS::Neutron::Port, fixed_ips, ip_address, internal, IPv4, comma\_delimited\_list, {vm-type}\_int\_{network-role}\_ips, YES
3634 OS::Neutron::Port, fixed_ips, ip_address, internal, IPv6, string, {vm-type}\_int\_{network-role}\_v6\_ip\_{index}, YES
3635 OS::Neutron::Port, fixed_ips, ip_address, internal, IPv6, comma\_delimited\_list, {vm-type}\_int\_{network-role}\_v6\_ips, YES
3641 *Example: comma_delimited_list parameters for IPv4 and IPv6 Address
3642 Assignments to an external network*
3644 In this example, the '{network-role}' has been defined as 'oam' to represent
3645 an oam network and the '{vm-type}' has been defined as 'db' for database.
3647 .. code-block:: python
3652 description: Neutron UUID for a oam network
3654 type: comma_delimited_list
3655 description: Fixed IPv4 assignments for db VMs on the oam network
3657 type: comma_delimited_list
3658 description: Fixed IPv6 assignments for db VMs on the oam network
3661 type: OS::Neutron::Port
3663 network: { get_param: oam_net_id }
3664 fixed_ips: [ { “ip_address”: {get_param: [ db_oam_ips, 0 ]}}, {
3665 “ip_address”: {get_param: [ db_oam_v6_ips, 0 ]}}]
3667 type: OS::Neutron::Port
3669 network: { get_param: oam_net_id }
3671 - “ip_address”: {get_param: [ db_oam_ips, 1 ]}
3672 - “ip_address”: {get_param: [ db_oam_v6_ips, 1 ]}
3674 *Example: string parameters for IPv4 and IPv6 Address Assignments to an
3677 In this example, the '{network-role}' has been defined as 'oam' to
3678 represent an oam network and the '{vm-type}' has been defined as 'db' for
3681 .. code-block:: python
3686 description: Neutron UUID for an OAM network
3689 description: Fixed IPv4 assignment for db VM 0 on the OAM network
3692 description: Fixed IPv4 assignment for db VM 1 on the OAM network
3695 description: Fixed IPv6 assignment for db VM 0 on the OAM network
3698 description: Fixed IPv6 assignment for db VM 1 on the OAM network
3701 type: OS::Neutron::Port
3703 network: { get_param: oam_net_id }
3704 fixed_ips: [ { “ip_address”: {get_param: db_oam_ip_0}}, { “ip_address”: {get_param: db_oam_v6_ip_0 ]}}]
3706 type: OS::Neutron::Port
3708 network: { get_param: oam_net_id }
3710 - “ip_address”: {get_param: db_oam_ip_1}}]
3711 - “ip_address”: {get_param: db_oam_v6_ip_1}}]
3714 *Example: comma_delimited_list parameters for IPv4 and IPv6 Address
3715 Assignments to an internal network*
3717 In this example, the '{network-role}' has been defined as 'ctrl' to
3718 represent an ctrl network internal to the vnf.
3719 The '{vm-type}' has been defined as 'db' for
3722 .. code-block:: python
3727 description: Neutron UUID for the ctrl internal network
3729 type: comma_delimited_list
3730 description: Fixed IPv4 assignments for db VMs on the ctrl internal
3733 type: comma_delimited_list
3734 description: Fixed IPv6 assignments for db VMs on the ctrl internal
3737 db_0_int_ctrl_port_0:
3738 type: OS::Neutron::Port
3740 network: { get_param: int_ctrl_net_id }
3741 fixed_ips: [ { “ip_address”: {get_param: [ db_int_ctrl_ips, 0 ]}}, {
3742 “ip_address”: {get_param: [ db_int_ctrl_v6_ips, 0 ]}}]
3743 db_1_int_ctrl_port_0:
3744 type: OS::Neutron::Port
3746 network: { get_param: int_ctrl_net_id }
3748 - “ip_address”: {get_param: [ db_int_ctrl_ips, 1 ]}
3749 - “ip_address”: {get_param: [ db_int_ctrl_v6_ips, 1 ]}
3752 *Example: string parameters for IPv4 and IPv6 Address Assignments to an
3755 In this example, the int\_{network-role} has been defined as
3756 int_ctrl to represent a control network internal to the vnf.
3757 The {vm-type} has been defined as db for database.
3759 .. code-block:: python
3764 description: Neutron UUID for an OAM internal network
3767 description: Fixed IPv4 assignment for db VM on the oam_int network
3770 description: Fixed IPv4 assignment for db VM 1 on the oam_int network
3771 db_int_ctrl_v6_ip_0:
3773 description: Fixed IPv6 assignment for db VM 0 on the oam_int network
3774 db_int_ctrl_v6_ip_1:
3776 description: Fixed IPv6 assignment for db VM 1 on the oam_int network
3778 db_0_int_ctrl_port_0:
3779 type: OS::Neutron::Port
3781 network: { get_param: int_oam_int_net_id }
3782 fixed_ips: [ { “ip_address”: {get_param: db_oam_int_ip_0}}, {
3783 “ip_address”: {get_param: db_oam_int_v6_ip_0 ]}}]
3784 db_1_int_ctrl_port_0:
3785 type: OS::Neutron::Port
3787 network: { get_param: int_oam_int_net_id }
3789 - “ip_address”: {get_param: db_oam_int_ip_1}}]
3790 - “ip_address”: {get_param: db_oam_int_v6_ip_1}}]
3793 Property: fixed\_ips, Map Property: subnet\_id
3794 ++++++++++++++++++++++++++++++++++++++++++++++
3796 The resource 'OS::Neutron::Port' property 'fixed_ips' map
3797 property 'subnet'/'subnet_id' is used when a
3798 port is requesting an IP assignment via
3799 OpenStack’s DHCP Service (i.e., Cloud Assigned).
3801 The IP address assignment will be made from the specified subnet.
3803 Specifying the subnet is not required; it is optional.
3805 If the network (external or internal) that the port is attaching
3806 to only contains one subnet, specifying the subnet is
3807 superfluous. The IP address will be assigned from the one existing
3810 If the network (external or internal) that the port is attaching
3811 to contains two or more subnets, specifying the subnet in the
3812 'fixed_ips' map property 'subnet'/'subnet_id' determines which
3813 subnet the IP address will be assigned from.
3815 If the network (external or internal) that the port is attaching
3816 to contains two or more subnets, and the subnet is not is not
3817 specified, OpenStack will randomly(?) determine which subnet
3818 the IP address will be assigned from.
3820 The property fixed_ips is used to assign IPs to a port. The Map Property
3821 subnet_id specifies the subnet the IP is assigned from.
3823 R-38236 The VNF’s Heat Orchestration Template’s resource
3824 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property
3825 ‘subnet’/’subnet_id’ parameter **MUST** be declared type ‘string’.
3827 R-62802 When the VNF’s Heat Orchestration Template’s resource
3828 ‘OS::Neutron::Port’ is attaching to an external network, and an IPv4
3829 address is being Cloud Assigned by OpenStack’s DHCP Service and the
3830 external network IPv4 subnet is to be specified using the property
3831 ‘fixed_ips’ map property ‘subnet’/’subnet_id’, the parameter **MUST**
3832 follow the naming convention ‘{network-role}_subnet_id’, where
3833 ‘{network-role}’ is the network role of the network.
3835 R-83677 The VNF’s Heat Orchestration Template’s Resource
3836 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property
3837 subnet’/’subnet_id’ parameter ‘{network-role}_subnet_id’
3838 **MUST NOT** be enumerated in the VNF’s Heat Orchestration Template’s
3841 ONAP's SDN-Controller provides the network's subnet's UUID
3842 value at orchestration to the Heat Orchestration Template.
3844 *Example Parameter Definition*
3846 .. code-block:: python
3850 {network-role}_subnet_id:
3852 description: Neutron IPv4 subnet UUID for the {network-role} network
3854 R-15287 When the VNF’s Heat Orchestration Template’s resource
3855 ‘OS::Neutron::Port’ is attaching to an external network, and an IPv6
3856 address is being Cloud Assigned by OpenStack’s DHCP Service and the
3857 external network IPv6 subnet is to be specified using the property
3858 ‘fixed_ips’ map property ‘subnet’/’subnet_id’, the parameter **MUST**
3859 follow the naming convention ‘{network-role}_subnet_v6_id’, where
3860 ‘{network-role}’ is the network role of the network.
3862 R-80829 The VNF’s Heat Orchestration Template’s Resource
3863 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property
3864 subnet’/’subnet_id’ parameter ‘{network-role}_subnet_v6_id’
3865 **MUST NOT** be enumerated in the VNF’s Heat Orchestration Template’s
3868 ONAP's SDN-Controller provides the network's subnet's UUID
3869 value at orchestration to the Heat Orchestration Template.
3871 *Example Parameter Definition*
3873 .. code-block:: python
3877 {network-role}_v6_subnet_id:
3879 description: Neutron IPv6 subnet UUID for the {network-role} network
3882 *Example: One Cloud Assigned IPv4 Address (DHCP) assigned to a network
3883 that has two or more IPv4 subnets*
3885 In this example, the '{network-role}' has been defined as 'oam' to represent
3886 an oam network and the '{vm-type}' has been defined as 'lb' for load
3887 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
3888 to assign IP addresses.
3890 .. code-block:: python
3895 description: Neutron UUID for the oam network
3898 description: Neutron IPv4 subnet UUID for the oam network
3901 type: OS::Neutron::Port
3903 network: { get_param: oam_net_id }
3905 - subnet_id: { get_param: oam_subnet_id }
3907 *Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6
3908 address assigned to a network that has at least one IPv4 subnet and one
3911 In this example, the '{network-role}' has been defined as 'oam' to represent
3912 an oam network and the '{vm-type}' has been defined as 'lb' for load
3915 .. code-block:: python
3920 description: Neutron UUID for the oam network
3923 description: Neutron IPv4 subnet UUID for the oam network
3926 description: Neutron IPv6 subnet UUID for the oam network
3929 type: OS::Neutron::Port
3931 network: { get_param: oam_net_id }
3933 - subnet_id: { get_param: oam_subnet_id }
3934 - subnet_id: { get_param: oam_v6_subnet_id }
3938 - the VNF’s Heat Orchestration Template’s resource ‘OS::Neutron::Port’
3939 in an Incremental Module is attaching to an internal network
3940 that is created in the Base Module, AND
3941 - an IPv4 address is being Cloud Assigned by OpenStack’s DHCP Service AND
3942 - the internal network IPv4 subnet is to be specified using the
3943 property ‘fixed_ips’ map property ‘subnet’/’subnet_id’,
3945 the parameter **MUST** follow the naming convention
3946 ‘int\_{network-role}_subnet_id’, where ‘{network-role}’ is the
3947 network role of the internal network
3949 - Note that the parameter **MUST** be defined as an ‘output’ parameter in
3952 R-69634 The VNF’s Heat Orchestration Template’s Resource
3953 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property
3954 subnet’/’subnet_id’ parameter ‘int\_{network-role}_subnet_id’
3955 **MUST NOT** be enumerated in the VNF’s Heat Orchestration Template’s
3958 The assumption is that internal networks are created in the base module.
3959 The Neutron subnet network ID will be passed as an output parameter
3960 (e.g., ECOMP Base Module Output Parameter) to the incremental modules.
3961 In the incremental modules, the output parameter name will be defined as
3964 *Example Parameter Definition*
3966 .. code-block:: python
3970 int_{network-role}_subnet_id:
3972 description: Neutron IPv4 subnet UUID for the int_{network-role} network
3976 - the VNF’s Heat Orchestration Template’s resource
3977 ‘OS::Neutron::Port’ in an Incremental Module is attaching to an
3978 internal network that is created in the Base Module, AND
3979 - an IPv6 address is being Cloud Assigned by OpenStack’s DHCP Service AND
3980 - the internal network IPv6 subnet is to be specified using the property
3981 ‘fixed_ips’ map property ‘subnet’/’subnet_id’,
3983 the parameter **MUST** follow the naming convention
3984 ‘int\_{network-role}_v6_subnet_id’, where ‘{network-role}’
3985 is the network role of the internal network
3987 - Note that the parameter **MUST** be defined as an ‘output’ parameter in
3990 R-22288 The VNF’s Heat Orchestration Template’s Resource
3991 ‘OS::Neutron::Port’ property ‘fixed_ips’ map property
3992 ‘subnet’/’subnet_id’ parameter ‘int\_{network-role}_v6_subnet_id’
3993 **MUST NOT** be enumerated in the VNF’s Heat Orchestration Template’s
3996 *Example Parameter Definition*
3998 .. code-block:: python
4002 int_{network-role}_v6_subnet_id:
4004 description: Neutron subnet UUID for the int_{network-role} network
4007 Property: allowed\_address\_pairs, Map Property: ip\_address
4008 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4010 The property allowed\_address\_pairs in the resource OS::Neutron::Port
4011 allows the user to specify a mac\_address and/or ip\_address that will
4012 pass through a port regardless of subnet. This enables the use of
4013 protocols such as VRRP, which floats an IP address between two instances
4014 to enable fast data plane failover. The map property ip\_address
4015 specifies the IP address.
4017 The allowed\_address\_pairs is an optional property. It is not required.
4019 An ONAP Heat Orchestration Template allows the assignment of one IPv4
4020 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
4021 and {network-role}/int\_{network-role} combination.
4023 An ONAP Heat Orchestration Template allows the assignment of one IPv6
4024 address allowed\_address\_pairs and/or one IPv6 address to a {vm-type}
4025 and {network-role}/int\_{network-role} combination.
4027 Note that the management of these IP addresses (i.e. transferring
4028 ownership between active and standby VMs) is the responsibility of the
4031 Note that these parameters are **not** intended to represent Neutron
4032 “Floating IP” resources, for which OpenStack manages a pool of public IP
4033 addresses that are mapped to specific VM ports. In that case, the
4034 individual VMs are not even aware of the public IPs, and all assignment
4035 of public IPs to VMs is via OpenStack commands. ONAP does not support
4036 Neutron-style Floating IPs.
4041 R-61282 The VNF Heat Orchestration Template **MUST**
4042 adhere to the following naming convention for the property
4043 allowed\_address\_pairs and Map Property ip\_address parameter,
4044 when the parameter is referencing an “external” network:
4046 - {vm-type}\_{network-role}\_floating\_ip for an IPv4 address
4048 - {vm-type}\_{network-role}\_floating\_v6\_ip for an IPv6 address
4050 The parameter must be declared as type: string
4052 The parameter must not be enumerated in the Heat environment file.
4054 *Example Parameter Definition*
4056 .. code-block:: yaml
4060 {vm-type}_{network-role}_floating_ip:
4062 description: VIP for {vm-type} VMs on the {network-role} network
4064 {vm-type}_{network-role}_floating_v6_ip:
4066 description: VIP for {vm-type} VMs on the {network-role} network
4070 In this example, the {network-role} has been defined as oam to represent
4071 an oam network and the {vm-type} has been defined as db for database.
4073 .. code-block:: yaml
4078 description: Neutron UUID for the oam network
4081 type: comma_delimited_list
4082 description: Fixed IPs for db VMs on the oam network
4086 description: VIP IP for db VMs on the oam network
4090 type: OS::Neutron::Port
4092 network: { get_param: oam_net_id }
4093 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,0] }}]
4094 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
4097 type: OS::Neutron::Port
4099 network: { get_param: oam_net_id }
4100 fixed_ips: [ { “ip_address”: {get_param: [db_oam_ips,1] }}]
4101 allowed_address_pairs: [ { “ip_address”: {get_param: db_oam_floating_ip}}]
4106 R-16805 The VNF Heat Orchestration Template **MUST** adhere to the following naming convention
4107 for the property allowed\_address\_pairs and Map Property ip\_address
4108 parameter when the parameter is referencing an “internal” network.
4110 - {vm-type}\_int\_{network-role}\_floating\_ip for an IPv4 address
4112 - {vm-type}\_int\_{network-role}\_floating\_v6\_ip for an IPv6 address
4114 The parameter must be declared as type: string
4116 The parameter must be enumerated in the Heat environment file.
4118 *Example Parameter Definition*
4120 .. code-block:: yaml
4124 {vm-type}_int_{network-role}_floating_ip:
4126 description: VIP for {vm-type} VMs on the int_{network-role} network
4128 {vm-type}_int_{network-role}_floating_v6_ip:
4130 description: VIP for {vm-type} VMs on the int_{network-role} network
4132 Multiple allowed\_address\_pairs for a {vm-type} / {network-role} combination
4133 __________________________________________________________________
4135 The parameter {vm-type}\_{network-role}\_floating\_ip provides only one
4136 allowed address pair IPv4 address per {vm-type} and {network-role} pair.
4138 The parameter {vm-type}\_{network-role}\_floating\_v6\_ip provides only
4139 one allowed address pair IPv6 address per {vm-type} and {network-role}
4142 If there is a need for multiple allowed address pair IPs for a given
4143 {vm-type} and {network-role} combination within a VNF, then the
4144 parameter names defined for the property fixed\_ips and Map Property
4145 ip\_address should be used with the allowed\_address\_pairs property.
4146 The examples below illustrate this.
4148 *Example: A VNF has four load balancers. Each pair has a unique VIP.*
4150 In this example, there are two administrative VM pairs. Each pair has
4151 one VIP. The {network-role} has been defined as oam to represent an oam
4152 network and the {vm-type} has been defined as admin for an
4155 Pair 1: Resources admin\_0\_port\_0 and admin\_1\_port\_0 share a unique
4156 VIP, [admin\_oam\_ips,2]
4158 Pair 2: Resources admin\_2\_port\_0 and admin\_3\_port\_0 share a unique
4159 VIP, [admin\_oam\_ips,5]
4161 .. code-block:: yaml
4166 description: Neutron UUID for the oam network
4168 type: comma_delimited_list
4169 description: Fixed IP assignments for admin VMs on the oam network
4174 type: OS::Neutron::Port
4176 network: { get_param: oam_net_id }
4177 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,0] }}]
4178 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
4181 type: OS::Neutron::Port
4183 network: { get_param: oam_net_id }
4184 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,1] }}]
4185 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,2] }}]
4188 type: OS::Neutron::Port
4190 network: { get_param: oam_net_id }
4191 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,3] }}]
4192 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
4195 type: OS::Neutron::Port
4197 network: { get_param: oam_net_id }
4198 fixed_ips: [ { “ip_address”: {get_param: [admin_oam_ips,4] }}]
4199 allowed_address_pairs: [{ “ip_address”: {get_param: [admin_oam_ips,5] }}]
4201 *Example: A VNF has two load balancers. The pair of load balancers share
4204 In this example, there is one load balancer pairs. The pair has two
4205 VIPs. The {network-role} has been defined as oam to represent an oam
4206 network and the {vm-type} has been defined as lb for a load balancer VM.
4208 .. code-block:: yaml
4212 type: OS::Neutron::Port
4214 network: { get_param: oam_net_id }
4215 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,0] }}]
4216 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
4219 type: OS::Neutron::Port
4221 network: { get_param: oam_net_id }
4222 fixed_ips: [ { “ip_address”: {get_param: [lb_oam_ips,1] }}]
4223 allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2]}, {get_param: [lb_oam_ips,3] }}]
4225 As a general rule, provide the fixed IPs for the VMs indexed first in
4226 the CDL and then the VIPs as shown in the examples above.
4228 ONAP SDN-C Assignment of allowed\_address\_pair IP Addresses
4229 __________________________________________________________________
4231 The following items must be taken into consideration when designing Heat
4232 Orchestration Templates that expect ONAP’s SDN-C to assign
4233 allowed\_address\_pair IP addresses via automation.
4235 The VMs must be of the same {vm-type}.
4237 The VMs must be created in the same module (base or incremental).
4239 Resource Property “name”
4240 ~~~~~~~~~~~~~~~~~~~~~~~~
4242 The parameter naming convention of the property name for the resource
4243 OS::Nova::Server has been defined in
4244 `Resource: OS::Nova::Server – Metadata Parameters`_.
4246 This section provides the requirements how the property name for non
4247 OS::Nova::Server resources must be defined when the property is used.
4248 Not all resources require the property name (e.g., it is optional) and
4249 some resources do not support the property.
4251 R-85734 The VNF Heat Orchestration Template **MUST** use the intrinsic function str\_replace
4252 in conjunction with the ONAP supplied metadata parameter
4253 vnf\_name to generate a unique value,
4254 when the property name for a non OS::Nova::Server resources is defined
4255 in a Heat Orchestration Template.
4257 This prevents the enumeration of a
4258 unique value for the property name in a per instance environment file.
4262 - In most cases, only the use of the metadata value vnf\_name is
4263 required to create a unique property name
4265 - the Heat Orchestration Template pseudo parameter 'OS::stack\_name’
4266 may also be used in the str\_replace construct to generate a unique
4267 name when the vnf\_name does not provide uniqueness
4269 *Example: Property* name *for resource* OS::Neutron::SecurityGroup
4271 .. code-block:: yaml
4275 type: OS::Neutron::SecurityGroup
4277 description: vDNS security group
4280 template: VNF_NAME_sec_grp_DNS
4282 VNF_NAME: {get_param: vnf_name}
4286 *Example: Property name for resource* OS::Cinder::Volume
4288 .. code-block:: yaml
4292 type: OS::Cinder::Volume
4294 description: Cinder Volume
4297 template: VNF_NAME_STACK_NAME_dns_volume
4299 VNF_NAME: {get_param: vnf_name}
4300 STACK_NAME: { get_param: 'OS::stack_name' }
4303 Contrail Issue with Values for the Property Name
4304 ++++++++++++++++++++++++++++++++++++++++++++++++
4306 The Contrail GUI has a limitation displaying special characters. The
4307 issue is documented in
4308 https://bugs.launchpad.net/juniperopenstack/+bug/1590710. It is
4309 recommended that special characters be avoided. However, if special
4310 characters must be used, note that for the following resources:
4324 the only special characters supported are:
4326 - “ ! $ ‘ ( ) = ~ ^ \| @ \` { } [ ] > , . \_
4328 ONAP Output Parameter Names
4329 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
4331 ONAP defines three types of Output Parameters as detailed in
4332 `Output Parameters`_.
4334 ONAP Base Module Output Parameters:
4335 +++++++++++++++++++++++++++++++++++
4337 ONAP Base Module Output Parameters do not have an explicit naming
4338 convention. The parameter name must contain {vm-type} and {network-role}
4341 ONAP Volume Template Output Parameters:
4342 +++++++++++++++++++++++++++++++++++++++
4344 ONAP Base Module Output Parameters do not have an explicit naming
4345 convention. The parameter name must contain {vm-type} when appropriate.
4347 Predefined Output Parameters
4348 ++++++++++++++++++++++++++++
4350 ONAP currently defines one predefined output parameter the OAM
4351 Management IP Addresses.
4353 OAM Management IP Addresses
4354 ___________________________
4356 A VNF may have a management interface for application controllers to
4357 interact with and configure the VNF. Typically, this will be via a
4358 specific VM that performs a VNF administration function. The IP address
4359 of this interface must be captured and inventoried by ONAP. The IP
4360 address might be a VIP if the VNF contains an HA pair of management VMs,
4361 or may be a single IP address assigned to one VM.
4363 The Heat template may define either (or both) of the following Output
4364 parameters to identify the management IP address.
4366 - oam\_management\_v4\_address
4368 - oam\_management\_v6\_address
4372 - The use of this output parameters are optional.
4374 - The Management IP Address should be defined only once per VNF, so it
4375 must only appear in one Module template
4377 - If a fixed IP for the admin VM is passed as an input parameter, it
4378 may be echoed in the output parameters. In this case, a IPv4 and/or
4379 IPv6 parameter must be defined in the parameter section of the YAML
4380 Heat template. The parameter maybe named oam\_management\_v4\_address
4381 and/or oam\_management\_v6\_address or may be named differently.
4383 - If the IP for the admin VM is obtained via DHCP, it may be obtained
4384 from the resource attributes. In this case,
4385 oam\_management\_v4\_address and/or oam\_management\_v6\_address must
4386 not be defined in the parameter section of the YAML Heat template.
4388 *Example: SDN-C Assigned IP Address echoed as*
4389 oam\_management\_v4\_address
4391 .. code-block:: yaml
4396 description: Fixed IPv4 assignment for admin VM 0 on the OAM network
4400 admin_oam_net_0_port:
4401 type: OS::Neutron::Port
4405 template: VNF_NAME_admin_oam_net_0_port
4407 VNF_NAME: {get_param: vnf_name}
4408 network: { get_param: oam_net_id }
4409 fixed_ips: [{ "ip_address": { get_param: admin_oam_ip_0 }}]
4410 security_groups: [{ get_param: security_group }]
4413 type: OS::Nova::Server
4415 name: { get_param: admin_names }
4416 image: { get_param: admin_image_name }
4417 flavor: { get_param: admin_flavor_name }
4418 availability_zone: { get_param: availability_zone_0 }
4420 - port: { get_resource: admin_oam_net_0_port }
4422 vnf_id: { get_param: vnf_id }
4423 vf_module_id: { get_param: vf_module_id }
4424 vnf_name: {get_param: vnf_name }
4426 oam_management_v4_address:
4427 value: {get_param: admin_oam_ip_0 }
4429 *Example: Cloud Assigned IP Address output as*
4430 oam\_management\_v4\_address
4432 .. code-block:: yaml
4437 admin_oam_net_0_port:
4438 type: OS::Neutron::Port
4442 template: VNF_NAME_admin_oam_net_0_port
4444 VNF_NAME: {get_param: vnf_name}
4445 network: { get_param: oam_net_id }
4446 security_groups: [{ get_param: security_group }]
4449 type: OS::Nova::Server
4451 name: { get_param: admin_names }
4452 image: { get_param: admin_image_name }
4453 flavor: { get_param: admin_flavor_name }
4454 availability_zone: { get_param: availability_zone_0 }
4456 - port: { get_resource: admin_oam_net_0_port }
4458 vnf_id: { get_param: vnf_id }
4459 vf_module_id: { get_param: vf_module_id }
4460 vnf_name: {get_param: vnf_name }
4463 oam_management_v4_address:
4464 value: {get_attr: [admin_server, networks, {get_param: oam_net_id}, 0] }
4466 Contrail Resource Parameters
4467 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4469 ONAP requires the parameter names of certain Contrail Resources to
4470 follow specific naming conventions. This section provides these
4473 Contrail Network Parameters
4474 +++++++++++++++++++++++++++
4476 Contrail based resources may require references to a Contrail network
4477 using the network FQDN.
4482 When the parameter associated with the Contrail Network is referencing
4483 an “external” network, the parameter must adhere to the following naming
4484 convention in the Heat Orchestration Template
4486 - {network-role}\_net\_fqdn
4488 The parameter must be declared as type: string
4490 The parameter must not be enumerated in the Heat environment file.
4492 *Example: Parameter declaration*
4494 .. code-block:: yaml
4497 {network-role}_net_fqdn:
4499 description: Contrail FQDN for the {network-role} network
4501 *Example: Contrail Resource OS::ContrailV2::VirtualMachineInterface
4502 Reference to a Network FQDN.*
4504 In this example, the {network-role} has been defined as oam to represent
4505 an oam network and the {vm-type} has been defined as fw for firewall.
4506 The Contrail resource OS::ContrailV2::VirtualMachineInterface property
4507 virtual\_network\_refs references a contrail network FQDN.
4509 .. code-block:: yaml
4512 type: OS::ContrailV2::VirtualMachineInterface
4516 template: VM_NAME_virtual_machine_interface_1
4518 VM_NAME: { get_param: fw_name_0 }
4519 virtual_machine_interface_properties:
4520 virtual_machine_interface_properties_service_interface_type: { get_param: oam_protected_interface_type }
4521 virtual_network_refs:
4522 - get_param: oam_net_fqdn
4523 security_group_refs:
4524 - get_param: fw_sec_grp_id
4526 Interface Route Table Prefixes for Contrail InterfaceRoute Table
4527 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
4529 The parameter associated with the resource
4530 OS::ContrailV2::InterfaceRouteTable property
4531 interface\_route\_table\_routes, map property
4532 interface\_route\_table\_routes\_route\_prefix is an ONAP Orchestration
4535 The parameters must be named {vm-type}\_{network-role}\_route\_prefixes
4536 in the Heat Orchestration Template.
4538 The parameter must be declared as type: json
4540 The parameter supports IP addresses in the format:
4542 1. Host IP Address (e.g., 10.10.10.10)
4544 2. CIDR Notation format (e.g., 10.0.0.0/28)
4546 The parameter must not be enumerated in the Heat environment file.
4548 *Example Parameter Definition*
4550 .. code-block:: yaml
4553 {vm-type}_{network-role}_route_prefixes:
4555 description: JSON list of Contrail Interface Route Table route prefixes
4559 .. code-block:: yaml
4564 description: Unique name for this VF instance
4565 fw_int_fw_route_prefixes:
4567 description: prefix for the ServiceInstance InterfaceRouteTable
4568 int_fw_dns_trusted_interface_type:
4570 description: service_interface_type for ServiceInstance
4573 type: OS::ContrailV2::InterfaceRouteTable
4574 depends_on: [*resource name of* *OS::ContrailV2::ServiceInstance*]
4578 template: VNF_NAME_interface_route_table
4580 VNF_NAME: { get_param: vnf_name }
4581 interface_route_table_routes:
4582 interface_route_table_routes_route: { get_param: fw_int_fw_route_prefixes }
4583 service_instance_refs:
4584 - get_resource: < *resource name of* *OS::ContrailV2::ServiceInstance* >
4585 service_instance_refs_data:
4586 - service_instance_refs_data_interface_type: { get_param: int_fw_interface_type }
4588 Parameter Names in Contrail Resources
4589 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4591 Contrail Heat resource properties will use, when appropriate, the same
4592 naming convention as OpenStack Heat resources. For example, the resource
4593 OS::ContrailV2::InstanceIp has two properties that the parameter naming
4594 convention is identical to properties in OS::Neutron::Port.
4596 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4597 instance\_ip\_address*
4599 The property instance\_ip\_address uses the same parameter naming
4600 convention as the property fixed\_ips and Map Property ip\_address in
4601 OS::Neutron::Port. The resource is assigning an ONAP SDN-C Assigned IP
4602 Address. The {network-role} has been defined as oam\_protected to
4603 represent an oam protected network and the {vm-type} has been defined as
4606 .. code-block:: yaml
4608 CMD_FW_OAM_PROTECTED_RII:
4609 type: OS::ContrailV2::InstanceIp
4611 - FW_OAM_PROTECTED_RVMI
4613 virtual_machine_interface_refs:
4614 - get_resource: FW_OAM_PROTECTED_RVMI
4615 virtual_network_refs:
4616 - get_param: oam_protected_net_fqdn
4617 instance_ip_address: { get_param: [fw_oam_protected_ips, get_param: index ] }
4619 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
4622 The property instance\_ip\_address uses the same parameter naming
4623 convention as the property fixed\_ips and Map Property subnet\_id in
4624 OS::Neutron::Port. The resource is assigning a Cloud Assigned IP
4625 Address. The {network-role} has been defined as “oam\_protected” to
4626 represent an oam protected network and the {vm-type} has been defined as
4629 .. code-block:: yaml
4631 CMD_FW_SGI_PROTECTED_RII:
4632 type: OS::ContrailV2::InstanceIp
4634 - FW_OAM_PROTECTED_RVMI
4636 virtual_machine_interface_refs:
4637 - get_resource: FW_OAM_PROTECTED_RVMI
4638 virtual_network_refs:
4639 - get_param: oam_protected_net_fqdn
4640 subnet_uuid: { get_param: oam_protected_subnet_id }
4642 Cinder Volume Templates
4643 ^^^^^^^^^^^^^^^^^^^^^^^^
4645 ONAP supports the independent deployment of a Cinder volume via separate
4646 Heat Orchestration Templates, the Cinder Volume module. This allows the
4647 volume to persist after VNF deletion so that they can be reused on
4648 another instance (e.g., during a failover activity).
4650 A Base Module or Incremental Module may have a corresponding volume
4651 module. Use of separate volume modules is optional. A Cinder volume may
4652 be embedded within the Base Module or Incremental Module if persistence
4655 R-47788 The VNF Heat Orchestration Template **MUST** have a 1:1 scope of a cinder volume module,
4656 when it exists, with the Base Module or Incremental Module
4658 A single volume module must create only the volumes
4659 required by a single Incremental module or Base module.
4661 The following rules apply to independent volume Heat templates:
4663 - Cinder volumes must be created in a separate Heat Orchestration
4664 Template from the Base Module or Incremental Module.
4666 - A single Cinder volume module must include all Cinder volumes
4667 needed by the Base/Incremental module.
4669 - R-79531 The VNF Heat Orchestration Template **MUST** define “outputs” in the volume
4670 template for each Cinder volume resource universally unique
4671 identifier (UUID) (i.e. ONAP Volume Template Output Parameters).
4673 - The VNF Incremental Module or Base Module must define input
4674 parameters that match each Volume output parameter (i.e., ONAP Volume
4675 Template Output Parameters).
4677 - ONAP will supply the volume template outputs automatically to the
4678 bases/incremental template input parameters.
4680 - Volume modules may utilize nested Heat templates.
4682 *Examples: Volume Template*
4684 A VNF has a Cinder volume module, named incremental\_volume.yaml, that
4685 creates an independent Cinder volume for a VM in the module
4686 incremental.yaml. The incremental\_volume.yaml defines a parameter in
4687 the output section, lb\_volume\_id\_0 which is the UUID of the cinder
4688 volume. lb\_volume\_id\_0 is defined as a parameter in incremental.yaml.
4689 ONAP captures the UUID value of lb\_volume\_id\_0 from the volume module
4690 output statement and provides the value to the incremental module.
4692 Note that the example below is not a complete Heat Orchestration
4693 Template. The {vm-type} has been defined as “lb” for load balancer
4695 incremental\_volume.yaml
4697 .. code-block:: yaml
4708 type: OS::Cinder::Volume
4712 template: VNF_NAME_volume_0
4714 VNF_NAME: { get_param: vnf_name }
4715 size: {get_param: dns_volume_size_0}
4720 value: {get_resource: dns_volume_0}
4726 .. code-block:: yaml
4737 type: OS::Nova::Server
4739 name: {get_param: dns_name_0}
4744 type: OS::Cinder::VolumeAttachment
4746 instance_uuid: { get_resource: lb_0 }
4747 volume_id: { get_param: lb_volume_id_0 }
4749 ONAP Support of Environment Files
4750 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
4752 The use of an environment file in OpenStack is optional. In ONAP, it is
4755 R-86285 The VNF Heat Orchestration Template **MUST** have a
4756 corresponding environment file, even if no parameters are required to be
4759 (Note that ONAP, the open source version of ONAP, does not
4760 programmatically enforce the use of an environment file.)
4762 R-67205 The VNF Heat Orchestration Template **MUST** have a corresponding
4763 environment file for a Base Module.
4765 R-35727 The VNF Heat Orchestration Template **MUST** have a
4766 corresponding environment file for an Incremental module.
4768 R-22656 The VNF Heat Orchestration Template **MUST** have a corresponding environment file
4769 for a Cinder Volume Module.
4771 A nested heat template must not have an environment file; OpenStack does
4774 The environment file must contain parameter values for the ONAP
4775 Orchestration Constants and VNF Orchestration Constants. These
4776 parameters are identical across all instances of a VNF type, and
4777 expected to change infrequently. The ONAP Orchestration Constants are
4778 associated with OS::Nova::Server image and flavor properties (See
4779 `Property: image`_ and `Property: flavor`_). Examples of VNF
4780 Orchestration Constants are the networking parameters associated
4781 with an internal network (e.g., private IP ranges) and Cinder
4784 The environment file must not contain parameter values for parameters
4785 that are instance specific (ONAP Orchestration Parameters, VNF
4786 Orchestration Parameters). These parameters are supplied to the Heat by
4787 ONAP at orchestration time.
4789 SDC Treatment of Environment Files
4790 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4792 Parameter values enumerated in the environment file are used by SDC as
4793 the default value. However, the SDC user may use the SDC GUI to
4794 overwrite the default values in the environment file.
4796 SDC generates a new environment file for distribution to MSO based on
4797 the uploaded environment file and the user provided GUI updates. The
4798 user uploaded environment file is discarded when the new file is
4799 created. Note that if the user did not change any values via GUI
4800 updates, the SDC generated environment file will contain the same values
4801 as the uploaded file.
4803 Use of Environment Files when using OpenStack “heat stack-create” CLI
4804 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4806 When ONAP is instantiating the Heat Orchestration Template, certain
4807 parameter must not be enumerated in the environment file. This document
4808 provides the details of what parameters should not be enumerated.
4810 If the Heat Orchestration Template is to be instantiated from the
4811 OpenStack Command Line Interface (CLI) using the command “heat
4812 stack-create”, all parameters must be enumerated in the environment
4815 Heat Template Constructs
4816 ^^^^^^^^^^^^^^^^^^^^^^^^^
4818 Nested Heat Templates
4819 ~~~~~~~~~~~~~~~~~~~~~
4821 ONAP supports nested Heat templates per the OpenStack specifications.
4822 Nested templates may be suitable for larger VNFs that contain many
4823 repeated instances of the same VM type(s). A common usage pattern is to
4824 create a nested template for each {vm-type} along with its supporting
4825 resources. The VNF module may then reference these component templates
4826 either statically by repeated definition or dynamically by using the
4827 resource OS::Heat::ResourceGroup.
4829 Nested Heat Template Requirements
4830 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4832 ONAP supports nested Heat Orchestration Templates. A Base Module,
4833 Incremental Module, and Cinder Volume Module may use nested heat.
4835 A Heat Orchestration Template may reference the nested heat statically
4836 by repeated definition.
4838 A Heat Orchestration Template may reference the nested heat dynamically
4839 using the resource OS::Heat::ResourceGroup.
4841 A Heat Orchestration template must have no more than three levels of
4842 nesting. ONAP supports a maximum of three levels.
4844 Nested heat templates must be referenced by file name. The use of
4845 resource\_registry in the environment file is not supported and must not
4848 R-89868 The VNF Heat Orchestration Template **MUST** have unique file names within the scope
4849 of the VNF for a nested heat yaml file.
4851 R-52530 The VNF Heat Orchestration Template **MUST NOT** use a directory hierarchy for
4852 nested templates. All templates must be in a single, flat directory
4855 A nested heat template may be used by any module within a given VNF.
4859 - Constrains must not be defined for any parameter enumerated in a
4860 nested heat template.
4862 - R-11041 The VNF Heat Orchestration Template **MUST** have the resource calling the
4863 nested yaml file pass in as properties all parameters defined
4864 in nested yaml file.
4866 - 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
4869 - With nested templates, outputs are required to expose any resource
4870 properties of the child templates to the parent template. Those would
4871 not explicitly be declared as parameters but simply referenced as
4872 get\_attribute targets against the “parent” resource.
4874 Nested Heat Template Example: Static
4875 ++++++++++++++++++++++++++++++++++++++
4879 .. code-block:: yaml
4885 dns_image_name: { get_param: dns_image_name }
4886 dns_flavor_name: { get_param: dns_flavor_name }
4887 availability_zone: { get_param: availability_zone_0 }
4888 security_group: { get_param: DNS_shared_sec_grp_id }
4889 oam_net_id: { get_param: oam_protected_net_id }
4890 dns_oam_ip: { get_param: dns_oam_ip_0 }
4891 dns_name: { get_param: dns_name_0 }
4892 vnf_name: { get_param: vnf_name }
4893 vnf_id: { get_param: vnf_id }
4894 vf_module_id: {get_param: vf_module_id}
4899 dns_image_name: { get_param: dns_image_name }
4900 dns_flavor_name: { get_param: dns_flavor_name }
4901 availability_zone: { get_param: availability_zone_1 }
4902 security_group: { get_param: DNS_shared_sec_grp_id }
4903 oam_net_id: { get_param: oam_protected_net_id }
4904 dns_oam_ip: { get_param: dns_oam_ip_1 }
4905 dns_name: { get_param: dns_name_1 }
4906 vnf_name: { get_param: vnf_name }
4907 vnf_id: { get_param: vnf_id }
4908 vf_module_id: {get_param: vf_module_id}
4912 .. code-block:: yaml
4915 type: OS::Neutron::Port
4919 template: VNF_NAME_dns_oam_port
4921 VNF_NAME: {get_param: vnf_name}
4922 network: { get_param: oam_net_id }
4923 fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}]
4924 security_groups: [{ get_param: security_group }]
4927 type: OS::Nova::Server
4929 name: { get_param: dns_names }
4930 image: { get_param: dns_image_name }
4931 flavor: { get_param: dns_flavor_name }
4932 availability_zone: { get_param: availability_zone }
4934 - port: { get_resource: dns_oam_0_port }
4936 vnf_id: { get_param: vnf_id }
4937 vf_module_id: { get_param: vf_module_id }
4938 vnf_name {get_param: vnf_name }
4940 Use of Heat ResourceGroup
4941 +++++++++++++++++++++++++
4943 The OS::Heat::ResourceGroup is a useful Heat element for creating
4944 multiple instances of a given resource or collection of resources.
4945 Typically, it is used with a nested Heat template, to create, for
4946 example, a set of identical OS::Nova::Server resources plus their
4947 related OS::Neutron::Port resources via a single resource in a master
4950 ResourceGroup may be used in ONAP to simplify the structure of a Heat
4951 template that creates multiple instances of the same VM type.
4953 However, there are important caveats to be aware of:
4955 ResourceGroup does not deal with structured parameters
4956 (comma-delimited-list and json) as one might typically expect. In
4957 particular, when using a list-based parameter, where each list element
4958 corresponds to one instance of the ResourceGroup, it is not possible to
4959 use the intrinsic “loop variable” %index% in the ResourceGroup
4962 For instance, the following is **not** valid Heat for ResourceGroup:
4964 .. code-block:: yaml
4966 type: OS::Heat::ResourceGroup
4968 type: my_nested_vm_template.yaml
4970 name: {get_param: [vm_name_list, %index%]}
4972 Although this appears to use the nth entry of the vm\_name\_list list
4973 for the nth element of the ResourceGroup, it will in fact result in a
4974 Heat exception. When parameters are provided as a list (one for each
4975 element of a ResourceGroup), you must pass the complete parameter to the
4976 nested template along with the current index as separate parameters.
4978 Below is an example of an **acceptable** Heat Syntax for a
4981 .. code-block:: yaml
4983 type: OS::Heat::ResourceGroup
4985 type: my_nested_vm_template.yaml
4987 names: {get_param: vm_name_list}
4990 You can then reference within the nested template as:
4992 { get\_param: [names, {get\_param: index} ] }
4994 ResourceGroup Property count
4995 ____________________________
4997 ONAP requires that the OS::Heat::ResourceGroup property count be defined
4998 (even if the value is one) and that the value must be enumerated in the
4999 environment file. This is required for ONAP to build the TOSCA model for
5002 .. code-block:: yaml
5004 type: OS::Heat::ResourceGroup
5006 count: { get_param: count }
5009 type: my_nested_vm_template.yaml
5011 names: {get_param: vm_name_list}
5014 Availability Zone and ResourceGroups
5015 ____________________________________
5017 The resource OS::Heat::ResourceGroup and the property availability\_zone
5018 has been an “issue” with a few VNFs since ONAP only supports
5019 availability\_zone as a string parameter and not a
5020 comma\_delimited\_list. This makes it difficult to use a ResourceGroup
5021 to create Virtual Machines in more than one availability zone.
5023 There are numerous solutions to this issue. Below are two suggested
5026 **Option 1:** create a CDL in the OS::Heat::ResourceGroup. In the
5027 resource type: OS::Heat::ResourceGroup, create a comma\_delimited\_list
5028 availability\_zones by using the intrinsic function list\_join.
5030 .. code-block:: yaml
5033 type: OS::Heat::ResourceGroup
5035 count: { get_param: node_count }
5041 avaialability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] }
5045 .. code-block:: yaml
5048 avaialability_zones:
5049 type: comma_delimited_list
5054 type: OS::Nova::Server
5056 name: { get_param: [ dns_names, get_param: index ] }
5057 image: { get_param: dns_image_name }
5058 flavor: { get_param: dns_flavor_name }
5059 availability_zone: { get_param: [ avaialability_zones, get_param: index ] }
5062 **Option 2:** Create a resource group per availability zone. A separate
5063 OS::Heat::ResourceGroup is created for each availability zone.
5068 Heat templates *should not* reference any HTTP-based resource
5069 definitions, any HTTP-based nested configurations, or any HTTP-based
5072 - During orchestration, ONAP *should not* retrieve any such resources
5073 from external/untrusted/unknown sources.
5075 - VNF images should not contain such references in user-data or other
5076 configuration/operational scripts that are specified via Heat or
5077 encoded into the VNF image itself.
5079 *Note:* HTTP-based references are acceptable if the HTTP-based reference
5080 is accessing information with the VM private/internal network.
5082 Heat Files Support (get\_file)
5083 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5085 Heat Templates may contain the inclusion of text files into Heat
5086 templates via the Heat get\_file directive. This may be used, for
5087 example, to define a common “user-data” script, or to inject files into
5088 a VM on startup via the “personality” property.
5090 Support for Heat Files is subject to the following limitations:
5092 R-76718 The VNF Heat Orchestration Template **MUST** reference the get\_files targets in
5093 Heat templates by file name, and the corresponding files should be
5094 delivered to ONAP along with the Heat templates.
5096 R-41888 The VNE Heat **MUST NOT** use URL-based file retrieval.
5098 R-62177 The VNF Heat Orchestration Template **MUST** have unique file names for the included
5099 files within the scope of the VNF.
5101 R-87848 The VNF Heat Orchestration Template **MUST** have all included files in a single, flat
5102 directory per VNF. ONAP does not support a directory hierarchy.
5104 - Included files may be used by all Modules within a given VNF.
5106 - get\_file directives may be used in both non-nested and nested
5112 When Nova Servers are created via Heat templates, they may be passed a
5113 “keypair” which provides an ssh key to the ‘root’ login on the newly
5114 created VM. This is often done so that an initial root key/password does
5115 not need to be hard-coded into the image.
5117 Key pairs are unusual in OpenStack, because they are the one resource
5118 that is owned by an OpenStack User as opposed to being owned by an
5119 OpenStack Tenant. As a result, they are usable only by the User that
5120 created the keypair. This causes a problem when a Heat template attempts
5121 to reference a keypair by name, because it assumes that the keypair was
5122 previously created by a specific ONAP user ID.
5124 When a keypair is assigned to a server, the SSH public-key is
5125 provisioned on the VMs at instantiation time. They keypair itself is not
5126 referenced further by the VM (i.e. if the keypair is updated with a new
5127 public key, it would only apply to subsequent VMs created with that
5130 Due to this behavior, the recommended usage of keypairs is in a more
5131 generic manner which does not require the pre-requisite creation of a
5132 keypair. The Heat should be structured in such a way as to:
5134 - Pass a public key as a parameter value instead of a keypair name
5136 - Create a new keypair within The VNF Heat Orchestration Template (in the base
5137 module) for use within that VNF
5139 By following this approach, the end result is the same as pre-creating
5140 the keypair using the public key – i.e., that public key will be
5141 provisioned in the new VM. However, this recommended approach also makes
5142 sure that a known public key is supplied (instead of having OpenStack
5143 generate a public/private pair to be saved and tracked outside of ONAP).
5144 It also removes any access/ownership issues over the created keypair.
5146 The public keys may be enumerated as a VNF Orchestration Constant in the
5147 environment file (since it is public, it is not a secret key), or passed
5148 at run-time as instance-specific parameters. ONAP will never
5149 automatically assign a public/private key pair.
5151 *Example (create keypair with an existing ssh public-key for {vm-type}
5152 of lb (for load balancer)):*
5154 .. code-block:: yaml
5164 type: OS::Nova::Keypair
5168 template: VNF_NAME_key_pair
5170 VNF_NAME: { get_param: vnf_name }
5171 public_key: {get_param: lb_ssh_public_key}
5172 save_private_key: false
5177 OpenStack allows a tenant to create Security groups and define rules
5178 within the security groups.
5180 Security groups, with their rules, may either be created in the Heat
5181 Orchestration Template or they can be pre-created in OpenStack and
5182 referenced within the Heat template via parameter(s). There can be a
5183 different approach for security groups assigned to ports on internal
5184 (intra-VNF) networks or external networks (inter-VNF). Furthermore,
5185 there can be a common security group across all VMs for a specific
5186 network or it can vary by VM (i.e., {vm-type}) and network type (i.e.,
5189 Anti-Affinity and Affinity Rules
5190 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5192 Anti-affinity or affinity rules are supported using normal OpenStack
5193 OS::Nova::ServerGroup resources. Separate ServerGroups are typically
5194 created for each VM type to prevent them from residing on the same host,
5195 but they can be applied to multiple VM types to extend the
5196 affinity/anti-affinity across related VM types as well.
5200 In this example, the {network-role} has been defined as oam to represent
5201 an oam network and the {vm-type} have been defined as lb for load
5202 balancer and db for database.
5204 .. code-block:: yaml
5208 type: OS::Nova::ServerGroup
5213 $vnf_name: {get_param: vnf_name}
5214 template: $vnf_name-server_group1
5219 type: OS::Nova::ServerGroup
5224 $vnf_name: {get_param: vnf_name}
5225 template: $vnf_name-server_group2
5230 type: OS::Nova::Server
5234 group: {get_resource: db_server_group}
5237 type: OS::Nova::Server
5241 group: {get_resource: db_server_group}
5244 type: OS::Nova::Server
5248 group: {get_resource: lb_server_group}
5250 Resource Data Synchronization
5251 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5253 For cases where synchronization is required in the orchestration of Heat
5254 resources, two approaches are recommended:
5256 - Standard Heat depends\_on property for resources
5258 - Assures that one resource completes before the dependent resource
5261 - Definition of completeness to OpenStack may not be sufficient
5262 (e.g., a VM is considered complete by OpenStack when it is ready
5263 to be booted, not when the application is up and running).
5265 - Use of Heat Notifications
5267 - Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle
5270 - Pre-requisite resources issue *wc\_notify* commands in user\_data.
5272 - Dependent resource define depends\_on in the
5273 OS::Heat::WaitCondition resource.
5275 *Example: “depends\_on” case*
5277 In this example, the {network-role} has been defined as oam to represent
5278 an oam network and the {vm-type} has been defined as oam to represent an
5281 .. code-block:: yaml
5285 type: OS::Nova::Server
5287 name: {get_param: [oam_ names, 0]}
5288 image: {get_param: oam_image_name}
5289 flavor: {get_param: oam_flavor_name}
5290 availability_zone: {get_param: availability_zone_0}
5292 - port: {get_resource: oam01_port_0}
5293 - port: {get_resource: oam01_port_1}
5295 scheduler_hints: {group: {get_resource: oam_servergroup}}
5296 user_data_format: RAW
5299 type: OS::Neutron::Port
5301 network: {get_resource: oam_net_name}
5302 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}]
5303 security_groups: [{get_resource: oam_security_group}]
5306 type: OS::Neutron::Port
5308 network: {get_param: oam_net_name}
5309 fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}]
5310 security_groups: [{get_resource: oam_security_group}]
5312 oam_01_vol_attachment:
5313 type: OS::Cinder::VolumeAttachment
5314 depends_on: oam_server_01
5316 volume_id: {get_param: oam_vol_1}
5317 mountpoint: /dev/vdb
5318 instance_uuid: {get_resource: oam_server_01}
5323 VNF/VM parameters may include availability zone IDs for VNFs that
5324 require high availability.
5326 The Heat must comply with the following requirements to specific
5327 availability zone IDs:
5329 - The Heat template should spread Nova and Cinder resources across the
5330 availability zones as desired
5332 Post Orchestration & VNF Configuration
5333 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
5335 Heat templates should contain a minimum amount of post-orchestration
5336 configuration data. For instance, *do not* embed complex user-data
5337 scripts in the template with large numbers of configuration parameters
5338 to the Heat template.
5340 - VNFs may provide configuration APIs for use after VNF creation. Such
5341 APIs will be invoked via application and/or SDN controllers.
5343 *Note:* It is important to follow this convention to the extent possible
5344 even in the short-term as of the long-term direction.
5346 VNFM Driver Development Steps
5347 -----------------------------------------------------------
5349 Refer to the ONAP documentation for VNF Provider instructions on integrating
5350 vendor-specific VNFM adaptors with VF-C. The VNF driver development steps are
5353 1. Use the VNF SDK tools to design the VNF with TOSCA models to output
5354 the VNF TOSCA package. Using the VNF SDK tools, the VNF package can be
5355 validated and tested.
5357 2. The VNF Provider supplies a vendor-specific VNFM driver in ONAP, which
5358 is a microservice providing a translation interface from VF-C to
5359 the vendor-specific VNFM. The interface definitions of vendor-specific
5360 VNFM adaptors are supplied by the VNF Providers themselves.
5362 Creating Vendor-Specific VNFM Adaptor Microservices
5363 ------------------------------------------------------------------------------------------------
5365 VNFs can be managed by vendor-specific VNFMs. To add a vendor-specific
5366 VNFM to ONAP, a vendor-specific VNFM adaptor is added to ONAP implementing
5367 the interface of the vendor-specific VNFM.
5369 A vendor-specific VNFM adaptor is a microservice with a unique name and
5370 an appointed port. When started up, the vendor-specific VNFM adaptor
5371 microservice is automatically registered to the Microservices Bus (MSB).
5372 The following RESTful example describes the scenario of registering a
5373 vendor-specific VNFM adaptor to MSB:
5375 .. code-block:: java
5377 POST /api/microservices/v1/services
5379 "serviceName": "catalog",
5381 "url": "/api/catalog/v1",
5386 "ip": "10.74.56.36",
Code Review / vnfrqts / requirements.git / blob