1 **5. VNF Modeling Requirements**
2 =====================================
13 The Heat templates supported by OpenECOMP must follow the requirements
14 enumerated in this section.
19 In order to enable OpenECOMP to understand the relationship between Heat
20 files, the following Heat file naming convention must be followed.
22 - The file name for the base module Heat template must include “base”
25 - Examples: *base\_xyz.yml* or *base\_xyz.yaml*; *xyz\_base.yml* or
28 - There is no explicit naming convention for the add-on modules.
30 - Examples: *module1.yml* or *module1.yaml*
32 - All Cinder volume templates must be named the same as the
33 corresponding Heat template with “\_volume” appended to the file
36 - Examples: *base\_xyz\_volume.yml* or *base\_xyz\_volume.yaml*;
37 *xyz\_base\_volume.yml* or *xyz\_base\_volume.yaml*;
38 *module1\_volume.yml* or *module1\_volume.yaml* (referencing the
39 above base module Heat template name)
41 - The file name of the environment files must fully match the
42 corresponding Heat template filename and have *.env* or *.ENV*
45 - Examples: *base\_xyz.env* or *base\_xyz.ENV*; *xyz\_base.env* or
46 *xyz\_base.ENV*; *base\_xyz\_volume.env* or
47 *base\_xyz\_volume.ENV*; *module1.env* or *module1.ENV;
48 module1\_volume.env* or *module1\_volume.ENV* (referencing the
49 above base module Heat template name)
51 - A YAML file must have a corresponding ENV file, even if the ENV file
52 enumerates no parameters. It is an OpenECOMP requirement.
57 A Heat template (a YAML file and its corresponding environment file)
58 must be formatted in valid YAML. For a description of YAML, refer to the
59 following OpenStack wiki.
61 https://wiki.openstack.org/wiki/Heat/YAMLTemplates
63 A Heat template must follow a specific format. The OpenStack Heat
64 Orchestration Template (HOT) specification explains in detail all
65 elements of the HOT template format.
67 http://docs.openstack.org/developer/heat/template_guide/hot_spec.html
69 Parameter Categories & Specification
70 ------------------------------------
75 OpenECOMP requires the Heat template parameters to follow certain
76 requirements in order for it to be orchestrated or deployed. OpenECOMP
77 classifies parameters into eight broad categories.
79 - **OpenECOMP Metadata**: OpenECOMP mandatory and optional metadata
80 parameters in the resource *OS::Nova::Server*.
82 - OpenECOMP dictates the naming convention of these Metadata
83 parameters and must be adhered to (See Section 4.4).
85 - Metadata parameters must not be enumerated in the environment
88 - The OpenECOMP Metadata are generated and/or assigned by OpenECOMP
89 and supplied to the Heat by OpenECOMP at orchestration time.
91 - **OpenECOMP Orchestration Parameters**: The data associated with
92 these parameters are VNF instance specific.
94 - OpenECOMP enforces the naming convention of these parameters and
95 must be adhered to (See Section 4).
97 - These parameters must not be enumerated in the environment file.
99 - The OpenECOMP Orchestration Parameters are generated and/or
100 assigned by OpenECOMP and supplied to the Heat by OpenECOMP at
103 - **VNF Orchestration Parameters**: The data associated with these
104 parameters are VNF instance specific.
106 - While OpenECOMP does not enforce a naming convention, the
107 parameter names should include {vm-type} and {network-role} when
108 appropriate. (See Section 4)
110 - These parameters must not be enumerated in the environment file.
112 - The VNF Orchestration Parameters Heat are generated and/or
113 assigned by OpenECOMP and supplied to the Heat by OpenECOMP at
116 - **OpenECOMP Orchestration Constants**: The data associated with these
117 parameters must be constant across all VNF instances.
119 - OpenECOMP enforces the naming convention of these parameters and
120 must be adhered to (See Section 4).
122 - These parameters must be enumerated in the environment file.
124 - **VNF Orchestration Constants**: The data associated with these
125 parameters must be constant across all VNF instances.
127 - While OpenECOMP does not enforce a naming convention, the
128 parameter names should include {vm-type} and {network-role} when
129 appropriate. (See Section 4)
131 - These parameters must be enumerated in the environment file.
133 - **OpenECOMP Base Template Output Parameters** (also referred to as
134 Base Template Output Parameters): The output section of the base
135 template allows for specifying output parameters available to add-on
136 modules once the base template has been instantiated. The parameter
137 defined in the output section of the base must be identical to the
138 parameter defined in the add-on module(s) where the parameter is
141 - **OpenECOMP Volume Template Output Parameters** (also referred to as
142 Volume Template Output Parameters): The output section of the volume
143 template allows for specifying output parameters available to the
144 corresponding Heat template (base or add-on) once the volume template
145 has been instantiated. The parameter defined in the output section of
146 the volume must be identical to the parameter defined in the base or
149 - **OpenECOMP Predefined Output Parameters** (also referred to as
150 Predefined Output Parameters): OpenECOMP will look for a small set of
151 pre-defined Heat output parameters to capture resource attributes for
152 inventory in OpenECOMP. These parameters are specified in Section
155 The table below summarizes the Parameter Types. If the user is
156 orchestrating a manual spin up of Heat (e.g. OpenStack command line),
157 the parameter values that OpenECOMP supplies must be enumerated in the
158 environment file. However, when the Heat is to be loaded into OpenECOMP
159 for orchestration, the parameters that OpenECOMP supplies must be
160 deleted or marked with a comment (i.e., a “#” placed at the beginning of
163 +-----------------------------------------------+---------------------+---------------------------------------------------------------------------------+
164 | Parameter Type | Naming Convention | Parameter Value Source |
165 +===============================================+=====================+=================================================================================+
166 | OpenECOMP Metadata | Explicit | OpenECOMP |
167 +-----------------------------------------------+---------------------+---------------------------------------------------------------------------------+
168 | OpenECOMP Orchestration Parameters | Explicit | OpenECOMP |
169 +-----------------------------------------------+---------------------+---------------------------------------------------------------------------------+
170 | VNF Orchestration Parameters | Recommended | OpenECOMP |
171 +-----------------------------------------------+---------------------+---------------------------------------------------------------------------------+
172 | OpenECOMP Orchestration Constants | Explicit | Environment File |
173 +-----------------------------------------------+---------------------+---------------------------------------------------------------------------------+
174 | VNF Orchestration Constants | Recommended | Environment File |
175 +-----------------------------------------------+---------------------+---------------------------------------------------------------------------------+
176 | OpenECOMP Base Template Output Parameters | Recommended | Heat Output Statement for base, OpenECOMP supplied to add-on modules |
177 +-----------------------------------------------+---------------------+---------------------------------------------------------------------------------+
178 | OpenECOMP Volume Template Output Parameters | Recommended | Heat Output Statement for volume, OpeneECOMP supplies to corresponding module |
179 +-----------------------------------------------+---------------------+---------------------------------------------------------------------------------+
180 | OpenECOMP Predefined Output Parameters | Explicit | Heat Output Statement |
181 +-----------------------------------------------+---------------------+---------------------------------------------------------------------------------+
183 Table 1 Parameter Types
185 Parameter Specifications
186 ~~~~~~~~~~~~~~~~~~~~~~~~
188 OpenECOMP METADATA Parameters
189 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
191 OpenECOMP defines four “metadata” parameters: vnf\_id, vf\_module\_id,
192 vnf\_name, vf\_module\_name. These parameters must not define any
193 constraints in the Heat template, including length restrictions, ranges,
194 default value and/or allowed patterns.
196 OpenECOMP Base Template & Volume Template Output Parameters
197 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
199 The base template and volume template output parameters are defined as
200 input parameters in subsequent modules. When defined as input
201 parameters, these parameters must not define any constraints in the Heat
202 template, including length restrictions, ranges, default value and/or
203 allowed patterns. The parameter name defined in the output statement of
204 the Heat must be identical to the parameter name defined in the Heat
205 that is to receive the value.
207 OpenECOMP Predefined Output Parameters
208 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
210 These parameters must not define any constraints in the Heat template,
211 including length restrictions, ranges, default value and/or allowed
214 OpenECOMP Orchestration Parameters, VNF Orchestration Parameters, OpenECOMP Orchestration Constants, VNF Orchestration Constants
215 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
217 OpenECOMP Orchestration Parameters, VNF Orchestration Parameters,
218 OpenECOMP Orchestration Constants, VNF Orchestration Constants must
219 adhere to the following:
221 - All parameters should be clearly documented in the template,
222 including expected values.
224 - All parameters should be clearly specified, including constraints and
227 - Numeric parameter constraints should include range and/or allowed
230 - When the parameter type is a string and the parameter name contains
231 an index, the index must be zero based. That is, the index starts at
234 - When the parameter type is a Comma Delimited List (CDL), the
235 reference index must start at zero.
237 - Default values must only be supplied in a Heat environment file to
238 keep the template itself as clean as possible.
240 - Special characters must not be used in parameter names, as currently
241 only alphanumeric characters and “\_” underscores are allowed.
243 Use of Heat Environments
244 ------------------------
246 A YAML file must have a corresponding environment file (also referred to
247 as ENV file), even if the environment file defines no parameters. It is
248 an OpenECOMP requirement.
250 The environment file must contain parameter values for the OpenECOMP
251 Orchestration Constants and VNF Orchestration Constants. These
252 parameters are identical across all instances of a VNF type, and
253 expected to change infrequently. The OpenECOMP Orchestration Constants
254 are associated with OS::Nova::Server image and flavor properties (See
255 Section 4.3). Examples of VNF Orchestration Constants are the networking
256 parameters associated with an internal network (e.g. private IP ranges)
257 and Cinder volume sizes.
259 The environment file must not contain parameter values for parameters
260 that are instance specific (OpenECOMP Orchestration Parameters, VNF
261 Orchestration Parameters). These parameters are supplied to the Heat by
262 OpenECOMP at orchestration time. The parameters are generated and/or
263 assigned by OpenECOMP at orchestration time
265 Independent Volume Templates
266 ----------------------------
268 OpenECOMP supports independent deployment of a Cinder volume via
269 separate Heat templates. This allows the volume to persist after VNF
270 deletion so that they can be reused on another instance (e.g. during a
273 A VNF Incremental Module or Base Module may have an independent volume
274 module. Use of separate volume modules is optional. A Cinder volume may
275 be embedded within the Incremental or Base Module if persistence is not
278 If a VNF Incremental Module or Base Module has an independent volume
279 module, the scope of volume templates must be 1:1 with Incremental
280 module or Base module. A single volume module must create only the
281 volumes required by a single Incremental module or Base module.
283 The following rules apply to independent volume Heat templates:
285 - Cinder volumes must be created in a separate Heat template from the
286 Incremental and Base Modules.
288 - A single volume module must include all Cinder volumes needed by
289 the Incremental/Base module.
291 - The volume template must define “outputs” for each Cinder volume
292 resource universally unique identifier (UUID) (i.e. OpenECOMP
293 Volume Template Output Parameters).
295 - The VNF Incremental Module or Base Module must define input
296 parameters that match each Volume output parameter (i.e., OpenECOMP
297 Volume Template Output Parameters).
299 - OpenECOMP will supply the volume template outputs automatically to
300 the bases/incremental template input parameters.
302 - Volume modules may utilize nested Heat templates.
304 **Example (volume template):**
306 In this example, the {vm-type} has been left as a variable.
307 {vm-type} is described in section 4.1. If the VM was a load
308 balancer, the {vm-type} could be defined as “lb”
310 .. code-block:: python
315 {vm-type}\_volume\_size\_0:
320 {vm-type}\_volume\_0:
321 type: OS::Cinder::Volume
325 template: VNF\_NAME\_volume\_0
327 VNF\_NAME: { get\_param: vnf\_name }
328 size: {get\_param: {vm-type}\_volume\_size\_0}
331 *(+ additional volume definitions)*
333 .. code-block:: python
336 {vm-type}\_volume\_id\_0:
337 value: {get\_resource: {vm-type}\_volume\_0}
340 *(+ additional volume outputs)*
342 *Example (VNF module template):*
344 .. code-block:: python
349 {vm-type}\_volume\_id\_0:
355 type: OS::Nova::Server
357 name: {get\_param: {vm-type}\_name\_0}
361 {vm-type}\_0\_volume\_attach:
362 type: OS::Cinder::VolumeAttachment
364 instance\_uuid: { get\_resource: {vm-type}\_0 }
365 volume\_id: { get\_param: {vm-type}\_volume\_id\_0 }
367 Nested Heat Templates
368 ---------------------
370 OpenECOMP supports nested Heat templates per the OpenStack
371 specifications. Nested templates may be suitable for larger VNFs that
372 contain many repeated instances of the same VM type(s). A common usage
373 pattern is to create a nested template for each VM type along with its
374 supporting resources. The master VNF template (or VNF Module template)
375 may then reference these component templates either statically (by
376 repeated definition) or dynamically (via *OS::Heat::ResourceGroup*).
378 Nested template support in OpenECOMP is subject to the following
381 - Heat templates for OpenECOMP must only have one level of nesting.
382 OpenECOMP only supports one level of nesting.
384 - Nested templates must be referenced by file name in the master
387 - i.e. use of *resource\_registry* in the .env file is *not*
390 - Nested templates must have unique file names within the scope of the
393 - OpenECOMP does not support a directory hierarchy for nested
394 templates. All templates must be in a single, flat directory (per
397 - A nested template may be shared by all Modules (i.e., Heat templates)
406 VNF templates must not include any resources for external networks
407 connected to the VNF. In this context, “external” is in relation to the
408 VNF itself (not with regard to the Network Cloud site). External
409 networks may also be referred to as “inter-VNF” networks.
411 - External networks must be orchestrated separately, so they can be
412 shared by multiple VNFs and managed independently. When the external
413 network is created, it must be assigned a unique {network-role} (See
416 - External networks must be passed into the VNF template as parameters,
417 including the network-id (i.e. the neutron network UUID) and optional
420 - VNF templates must pass the appropriate external network IDs into
421 nested VM templates when nested Heat is used.
423 - VNFs may use DHCP assigned IP addresses or assign fixed IPs when
424 attaching VMs to an external network.
426 - OpenECOMP enforces a naming convention for parameters associated with
429 - Parameter values associated with an external network will be
430 generated and/or assigned by OpenECOMP at orchestration time.
432 - Parameter values associated with an external network must not be
433 enumerated in the environment file.
438 Orchestration activities related to internal networks must be included
439 in VNF templates. In this context, “internal” is in relation to the VNF
440 itself (not in relation to the Network Cloud site). Internal networks
441 may also be referred to as “intra-VNF” networks or “private” networks.
443 - Internal networks must not attach to any external gateways and/or
444 routers. Internal networks are for intra-VM communication only.
446 - In the modular approach, internal networks must be created in the
447 Base Module template, with their resource IDs exposed as outputs
448 (i.e., OpenECOMP Base Template Output Parameters) for use by all
449 add-on module templates. When the external network is created, it
450 must be assigned a unique {network-role} (See section 4.2).
452 - VNFs may use DHCP assigned IP addresses or assign fixed IPs when
453 attaching VMs to an internal network.
455 - OpenECOMP does not enforce a naming convention for parameters for
456 internal network, however, a naming convention is provided that
459 - Parameter values associated with an internal network must either be
460 passed as output parameter from the base template (i.e., OpenECOMP
461 Base Template Output Parameters) into the add-on modules or be
462 enumerated in the environment file.
464 IP Address Assignment
465 ---------------------
467 - VMs connect to external networks using either fixed (e.g. statically
468 assigned) IP addresses or DHCP assigned IP addresses.
470 - VMs connect to internal networks using either fixed (e.g. statically
471 assigned) IP addresses or DHCP assigned IP addresses.
473 - Neutron Floating IPs must not be used. OpenECOMP does not support
474 Neutron Floating IPs.
476 - OpenECOMP supports the OS::Neutron::Port property
477 “allowed\_address\_pairs.” See Section 4.4.3.
479 Parameter Naming Convention
480 ---------------------------
485 A common *{vm-type}* identifier must be used throughout the Heat
486 template in naming parameters, for each VM type in the VNF with the
487 following exceptions:
489 - The four OpenECOMP Metadata parameters must not be prefixed with a
490 common {vm-type} identifier. They are *vnf\_name*, *vnf\_id*,
491 *vf\_module\_id*, *vf\_module\_name*.
493 - Parameters only referring to a network or subnetwork must not be
494 prefixed with a common {vm-type} identifier.
496 - The parameter referring to the OS::Nova::Server property
497 availability\_zone must not be prefixed with a common {vm-type}
500 - {vm-type} must be unique to the VNF. It does not have to be globally
501 unique across all VNFs that OpenECOMP supports.
506 VNF templates must not include any resources for external networks
507 connected to the VNF. In this context, “external” is in relation to the
508 VNF itself (not with regard to the Network Cloud site). External
509 networks may also be referred to as “inter-VNF” networks.
511 External networks must be orchestrated separately, so they can be shared
512 by multiple VNFs and managed independently. When the external network is
513 created, it must be assigned a unique {network-role}.
515 “External” networks must be passed into the VNF template as parameters.
516 Examples include the network-id (i.e. the neutron network UUID) and
517 optional subnet ID. See section 4.4.3.
519 Any parameter that is associated with an external network must include
520 the {network-role} as part of the parameter name.
522 Internal network parameters must also define a {network-role}. Any
523 parameter that is associated with an internal network must include
524 int\_{network-role} as part of the parameter name.
526 Resource: OS::Nova::Server - Parameters
527 ---------------------------------------
529 The following OS::Nova::Server Resource Property Parameter Names must
530 follow the OpenECOMP parameter Naming Convention. All the parameters
531 associated with OS::Nova::Server are classified as OpenECOMP
532 Orchestration Parameters.
534 +----------------------+-----------------------------------------+------------------+
536 +======================+=========================================+==================+
537 | Property | OpenECOMP Parameter Naming Convention | Parameter Type |
538 +----------------------+-----------------------------------------+------------------+
539 | image | {*vm-type*}\_image\_name | string |
540 +----------------------+-----------------------------------------+------------------+
541 | flavor | {*vm-type*}\_flavor\_name | string |
542 +----------------------+-----------------------------------------+------------------+
543 | name | {*vm-type*}\_name\_{*index*} | string |
544 +----------------------+-----------------------------------------+------------------+
545 | | {vm-type}\_names | CDL |
546 +----------------------+-----------------------------------------+------------------+
547 | availability\_zone | availability\_zone\_{index} | string |
548 +----------------------+-----------------------------------------+------------------+
550 Table 2 Resource Property Parameter Names
555 Image is an OpenECOMP Orchestration Constant parameter. The image must
556 be referenced by the Network Cloud Service Provider (NCSP) image name,
557 with the parameter enumerated in the Heat environment file.
559 The parameters must be named *“{vm-type}\_image\_name”* in the VNF.
561 Each VM type (e.g., {vm-type}) should have a separate parameter for
562 images, even if several share the same image. This provides maximum
563 clarity and flexibility.
568 Flavor is an OpenECOMP Orchestration Constant parameter. The flavors
569 must be referenced by the Network Cloud Service Provider (NCSP) flavor
570 name, with the parameter enumerated in the Heat environment file.
572 The parameters must be named *“{vm-type}\_flavor\_name”* for each
573 *{vm-type}* in the VNF.
575 Each VM type should have separate parameters for flavors, even if more
576 than one VM shares the same flavor. This provides maximum clarity and
582 Name is an OpenEOMP Orchestration parameter; the value is provided to
583 the Heat template by OpenECOMP.
585 VM names (hostnames) for assignment to VM instances must be passed to
586 Heat templates either as
588 - an array (comma delimited list) for each VM type
590 - a set of fixed-index parameters for each VM type instance.
592 Each element in the VM Name list should be assigned to successive
593 instances of that VM type.
595 The parameter names must reflect the VM Type (i.e., include the
596 {vm-type} in the parameter name.) The parameter name format must be one
599 - If the parameter type is a comma delimited list: {**vm-type**}\_names
601 - If the parameter type is a string with a fixed index:
602 {**vm-type**}\_name\_{**index**}
604 If a VNF contains more than three instances of a given {vm-type}, the
605 CDL form of the parameter name (i.e., *{vm-type}*\ \_names} should be
606 used to minimize the number of unique parameters defined in the Heat.
610 .. code-block:: python
614 type: comma\_delimited\_list
615 description: VM Names for {vm-type} VMs
616 {vm-type}\_name\_{index}:
618 description: VM Name for {vm-type} VM {index}
622 In this example, the {vm-type} has been defined as “lb” for load
625 .. code-block:: python
629 type: comma\_delimited\_list
630 description: VM Names for lb VMs
633 type: OS::Nova::Server
635 name: { get\_param: [lb\_names, 0] }
639 type: OS::Nova::Server
641 name: { get\_param: [lb\_names, 1] }
644 **Example (fixed-index):**
646 In this example, the {vm-type} has been defined as “lb” for load
649 .. code-block:: python
654 description: VM Name for lb VM 0
657 description: VM Name for lb VM 1
661 type: OS::Nova::Server
663 name: { get\_param: lb\_name\_0 }
667 type: OS::Nova::Server
669 name: { get\_param: lb\_name\_1 }
672 Property: availability\_zone
673 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
675 Availability\_zone is an OpenECOMP Orchestration parameter; the value is
676 provided to the Heat template by OpenECOMP.
678 Availability zones must be passed as individual numbered parameters (not
679 as arrays) so that VNFs with multi-availability zone requirements can
680 clearly specify that in its parameter definitions.
682 The availability zone parameter must be defined as
683 “availability\_zone\_{index}”, with the {index} starting at zero.
687 In this example, the {vm-type} has been defined as “lb” for load
690 .. code-block:: python
694 type: comma\_delimited\_list
695 description: VM Names for lb VMs
696 availability\_zone\_0:
698 description: First availability zone ID or Name
702 type: OS::Nova::Server
704 name: { get\_param: [lb\_names, 0] }
705 availability\_zone: { get\_param: availability\_zone\_0 }
708 Resource: OS::Nova::Server - Metadata
709 -------------------------------------
711 This section describes the OpenECOMP Metadata parameters.
713 OpenECOMP Heat templates must include the following three parameters
714 that are used as metadata under the resource OS::Nova:Server: vnf\_id,
715 vf\_module\_id, vnf\_name
717 OpenECOMP Heat templates may include the following parameter that is
718 used as metadata under the resource OS::Nova:Server: vf\_module\_name.
720 These parameters are all classified as OpenECOMP Metadata.
722 +---------------------------+------------------+----------------------+
723 | Metadata Parameter Name | Parameter Type | Mandatory/Optional |
724 +===========================+==================+======================+
725 | vnf\_id | string | mandatory |
726 +---------------------------+------------------+----------------------+
727 | vf\_module\_id | string | mandatory |
728 +---------------------------+------------------+----------------------+
729 | vnf\_name | string | mandatory |
730 +---------------------------+------------------+----------------------+
731 | vf\_module\_name | string | optional |
732 +---------------------------+------------------+----------------------+
734 Table 3 OpenECOMP Metadata
736 Required Metadata Elements
737 ~~~~~~~~~~~~~~~~~~~~~~~~~~
739 The vnf\_id, vf\_module\_id, and vnf\_name metadata elements are
740 required (must) for *OS::Nova::Server* resources. The metadata
741 parameters will be used by OpenECOMP to associate the servers with the
746 - *“vnf\_id”* parameter value will be supplied by OpenECOMP.
747 OpenECOMP generates the UUID that is the vnf\_id and supplies it
748 to the Heat at orchestration time.
752 - “\ *vf\_module\_id”* parameter value will be supplied by
753 OpenECOMP. OpenECOMP generates the UUID that is the vf\_module\_id
754 and supplies it to the Heat at orchestration time.
758 - “\ *vnf\_name”* parameter value will be generated and/or assigned
759 by OpenECOMP and supplied to the Heat by OpenECOMP at
762 Optional Metadata Elements
763 ~~~~~~~~~~~~~~~~~~~~~~~~~~
765 The following metadata element is optional for *OS::Nova::Server*
770 - The vf\_module\_name is the name of the name of the Heat stack
771 (e.g., <STACK\_NAME>) in the command “Heat stack-create” (e.g.
772 Heat stack-create [-f <FILE>] [-e <FILE>] <STACK\_NAME>). The
773 <STACK\_NAME> needs to be specified as part of the orchestration
776 - *“vf\_module\_name”* parameter value, when used, will be supplied
777 by OpenECOMP to the Heat at orchestration time. The parameter will
778 be generated and/or assigned by OpenECOMP and supplied to the Heat
779 by OpenECOMP at orchestration time.
783 In this example, the {vm-type} has been defined as “lb” for load
786 .. code-block:: python
791 description: Unique name for this VNF instance
794 description: Unique ID for this VNF instance
797 description: Unique name for this VNF Module instance
800 description: Unique ID for this VNF Module instance
804 type: OS::Nova::ServerGroup
808 template: VNF\_NAME\_lb\_ServerGroup
810 VNF\_NAME: { get\_param: VNF\_name }
811 policies: [ ‘anti-affinity’ ]
814 type: OS::Nova::Server
816 name: { get\_param: lb\_name\_0 }
818 group: { get\_resource: lb\_server\_group }
820 vnf\_name: { get\_param: vnf\_name }
821 vnf\_id: { get\_param: vnf\_id }
822 vf\_module\_name: { get\_param: vf\_module\_name }
823 vf\_module\_id: { get\_param: vf\_module\_id }
826 Resource: OS::Neutron::Port - Parameters
827 ----------------------------------------
829 The following four OS::Neutron::Port Resource Property Parameters must
830 adhere to the OpenECOMP parameter naming convention.
838 - allowed\_address\_pairs
840 These four parameters reference a network, which maybe an external
841 network or an internal network. Thus the parameter will include
842 {network-role} in its name.
844 When the parameter references an external network, the parameter is an
845 OpenECOMP Orchestration Parameter. The parameter value must be supplied
846 by OpenECOMP. The parameters must adhere to the OpenECOMP parameter
849 +---------------------------+-----------------------------------------------+------------------+
850 | OS::Neutron::Port |
851 +===========================+===============================================+==================+
852 | Property | Parameter Name for External Networks | Parameter Type |
853 +---------------------------+-----------------------------------------------+------------------+
854 | Network | {network-role}\_net\_id | string |
855 +---------------------------+-----------------------------------------------+------------------+
856 | | {network-role}\_net\_name | string |
857 +---------------------------+-----------------------------------------------+------------------+
858 | Subnet | {network-role}\_subnet\_id | string |
859 +---------------------------+-----------------------------------------------+------------------+
860 | | {network-role}\_v6\_subnet\_id | string |
861 +---------------------------+-----------------------------------------------+------------------+
862 | fixed\_ips | {vm-type}\_{network-role}\_ip\_{index} | string |
863 +---------------------------+-----------------------------------------------+------------------+
864 | | {vm-type}\_{network-role}\_ips | CDL |
865 +---------------------------+-----------------------------------------------+------------------+
866 | | {vm-type}\_{network-role}\_v6\_ip\_{index} | string |
867 +---------------------------+-----------------------------------------------+------------------+
868 | | {vm-type}\_{network-role}\_v6\_ips | CDL |
869 +---------------------------+-----------------------------------------------+------------------+
870 | allowed\_address\_pairs | {vm-type}\_{network-role}\_floating\_ip | string |
871 +---------------------------+-----------------------------------------------+------------------+
872 | | {vm-type}\_{network-role}\_floating\_v6\_ip | string |
873 +---------------------------+-----------------------------------------------+------------------+
874 | | {vm-type}\_{network-role}\_ip\_{index} | string |
875 +---------------------------+-----------------------------------------------+------------------+
876 | | {vm-type}\_{network-role}\_ips | CDL |
877 +---------------------------+-----------------------------------------------+------------------+
878 | | {vm-type}\_{network-role}\_v6\_ip\_{index} | string |
879 +---------------------------+-----------------------------------------------+------------------+
880 | | {vm-type}\_{network-role}\_v6\_ips | CDL |
881 +---------------------------+-----------------------------------------------+------------------+
883 Table 4 Port Resource Property Parameters (External Networks)
885 When the parameter references an internal network, the parameter is a
886 VNF Orchestration Parameters. The parameter value(s) must be supplied
887 either via an output statement(s) in the base module (i.e., OpenECOMP
888 Base Template Output Parameters) or be enumerated in the environment
889 file. The parameters must adhere to the following parameter naming
892 +---------------------------+----------------------------------------------------+------------------+
893 | OS::Neutron::Port |
894 +===========================+====================================================+==================+
895 | Property | Parameter Name for Internal Networks | Parameter Type |
896 +---------------------------+----------------------------------------------------+------------------+
897 | Network | int\_{network-role}\_net\_id | string |
898 +---------------------------+----------------------------------------------------+------------------+
899 | | int\_{network-role}\_net\_name | string |
900 +---------------------------+----------------------------------------------------+------------------+
901 | Subnet | int\_{network-role}\_subnet\_id | string |
902 +---------------------------+----------------------------------------------------+------------------+
903 | | Int\_{network-role}\_v6\_subnet\_id | string |
904 +---------------------------+----------------------------------------------------+------------------+
905 | fixed\_ips | {vm-type}\_int\_{network-role}\_ip\_{index} | string |
906 +---------------------------+----------------------------------------------------+------------------+
907 | | {vm-type}\_int\_{network-role}\_ips | CDL |
908 +---------------------------+----------------------------------------------------+------------------+
909 | | {vm-type}\_int\_{network-role}\_v6\_ip\_{index} | string |
910 +---------------------------+----------------------------------------------------+------------------+
911 | | {vm-type}\_int\_{network-role}\_v6\_ips | CDL |
912 +---------------------------+----------------------------------------------------+------------------+
913 | allowed\_address\_pairs | {vm-type}\_int\_{network-role}\_floating\_ip | string |
914 +---------------------------+----------------------------------------------------+------------------+
915 | | {vm-type}\_int\_{network-role}\_floating\_v6\_ip | string |
916 +---------------------------+----------------------------------------------------+------------------+
917 | | {vm-type}\_int\_{network-role}\_ip\_{index} | string |
918 +---------------------------+----------------------------------------------------+------------------+
919 | | {vm-type}\_int\_{network-role}\_ips | CDL |
920 +---------------------------+----------------------------------------------------+------------------+
921 | | {vm-type}\_int\_{network-role}\_v6\_ip\_{index} | string |
922 +---------------------------+----------------------------------------------------+------------------+
923 | | {vm-type}\_int\_{network-role}\_v6\_ips | CDL |
924 +---------------------------+----------------------------------------------------+------------------+
926 Table 5 Port Resource Property Parameters (Internal Networks)
928 Property: network & subnet
929 ~~~~~~~~~~~~~~~~~~~~~~~~~~
931 The property “networks” in the resource OS::Neutron::Port must be
932 referenced by Neutron Network ID, a UUID value, or by the network name
933 defined in OpenStack.
935 When the parameter is referencing an “external” network, the parameter
936 must adhere to the following naming convention
938 - *“{*\ network-role}\_net\_id”, for the Neutron network ID
940 - “{network-role}\_net\_name”, for the network name in OpenStack
942 When the parameter is referencing an “internal” network, the parameter
943 must adhere to the following naming convention.
945 - “\ *int\_{network-role}\_net\_id*\ ”, for the Neutron network ID
947 - “\ *int\_{network-role}\_net\_name*\ ”, for the network name in
950 The property “subnet\_id” must be used if a DHCP IP address assignment
951 is being requested and the DHCP IP address assignment is targeted at a
954 The property “subnet\_id” should not be used if all IP assignments are
955 fixed, or if the DHCP assignment does not target a specific subnet
957 When the parameter is referencing an “external” network subnet, the
958 “subnet\_id” parameter must adhere to the following naming convention.
960 - “\ *{network-role}\_subnet\_id*\ ” if the subnet is an IPv4 subnet
962 - “\ *{network-role}\_v6\_subnet\_id”* if the subnet is an IPv6 subnet
964 When the parameter is referencing an “internal” network subnet, the
965 “subnet\_id” parameter must adhere to the following naming convention.
967 - “\ *int\_{network-role}\_subnet\_id*\ ” if the subnet is an IPv4
970 - “\ *int\_{network-role}\_v6\_subnet\_id*\ ” if the subnet is an IPv6
975 .. code-block:: python
978 {network-role}\_net\_id:
980 description: Neutron UUID for the {network-role} network
981 {network-role}\_net\_name:
983 description: Neutron name for the {network-role} network
984 {network-role}\_subnet\_id:
986 description: Neutron subnet UUID for the {network-role} network
987 {network-role}\_v6\_subnet\_id:
989 description: Neutron subnet UUID for the {network-role} network
993 In this example, the {network-role} has been defined as “oam” to
994 represent an oam network and the {vm-type} has been defined as “lb” for
997 .. code-block:: python
1002 description: Neutron UUID for the oam network
1006 type: OS::Neutron::Port
1007 network: { get\_param: oam\_net\_id }
1009 Property: fixed\_ips
1010 ~~~~~~~~~~~~~~~~~~~~
1012 The property “fixed\_ips” in the resource OS::Neutron::Port must be used
1013 when statically assigning IP addresses.
1015 An IP address is assigned to a port on a type of VM (i.e., {vm-type})
1016 that is connected to a type of network (i.e., {network-role}). These two
1017 tags are components of the parameter name.
1019 When the “fixed\_ips” parameter is referencing an “external” network,
1020 the parameter must adhere to the naming convention below. The parameter
1021 may be a comma delimited list or a string.
1023 There must be a different parameter name for IPv4 IP addresses and IPv6
1026 - **Comma-delimited list:** Each element in the IP list should be
1027 assigned to successive instances of that VM type on that network.
1029 - *Format for IPv4 addresses:* {vm-type}\_{network-role}\_ips
1031 - *Format for IPv6 addresses:* {vm-type}\_{network-role}\_v6\_ips
1033 - **A set of fixed-index parameters:** In this case, the parameter
1034 should have “\ *type: string*\ ” and must be repeated for every IP
1035 expected for each {vm-type} + {network-role} pair.
1037 - *Format for IPv4 addresses:*
1038 {vm-type}\_{network-role}\_ip\_{index}
1040 - *Format for IPv6 addresses:*
1041 {vm-type}\_{network-role}\_v6\_ip\_{index}
1043 When the “fixed\_ips” parameter is referencing an “internal” network,
1044 the parameter must adhere to the naming convention below. The parameter
1045 may be a comma delimited list or a string.
1047 There must be a different parameter name for IPv4 IP addresses and IPv6
1050 - **Comma-delimited list:** Each element in the IP list should be
1051 assigned to successive instances of that VM type on that network.
1053 - *Format for IPv4 addresses:* {vm-type}\_int\_{network-role}\_ips
1055 - *Format for IPv6 addresses:*
1056 {vm-type}\_int\_{network-role}\_v6\_ips
1058 - **A set of fixed-index parameters:** In this case, the parameter
1059 should have “\ *type: string*\ ” and must be repeated for every IP
1060 expected for each {vm-type} and {network-role}pair.
1062 - *Format for IPv4 addresses:*
1063 {vm-type}\_int\_{network-role}\_ip\_{index}
1065 - *Format for IPv6 addresses:*
1066 {vm-type}\_int\_{network-role}\_v6\_ip\_{index}
1068 If a VNF contains more than three IP addresses for a given {vm-type} and
1069 {network-role} combination, the CDL form of the parameter name should be
1070 used to minimize the number of unique parameters defined in the Heat.
1072 *Example (external network)*
1074 .. code-block:: python
1077 {vm-type}\_{network-role}\_ips:
1078 type: comma\_delimited\_list
1079 description: Fixed IPv4 assignments for {vm-type} VMs on the
1080 {network-role} network
1081 {vm-type}\_{network-role}\_v6\_ips:
1082 type: comma\_delimited\_list
1083 description: Fixed IPv6 assignments for {vm-type} VMs on the
1084 {network-role} network
1085 {vm-type}\_{network-role}\_ip\_{index}:
1087 description: Fixed IPv4 assignment for {vm-type} VM {index} on the
1088 {network-role} network
1089 {vm-type}\_{network-role}\_v6\_ip\_{index}:
1091 description: Fixed IPv6 assignment for {vm-type} VM {index} on the
1092 {network-role} network
1094 *Example (CDL parameter for IPv4 Address Assignments to an external
1097 In this example, the {network-role} has been defined as “oam” to
1098 represent an oam network and the {vm-type} has been defined as “db” for
1101 .. code-block:: python
1106 description: Neutron UUID for a oam network
1108 type: comma\_delimited\_list
1109 description: Fixed IP assignments for db VMs on the oam network
1113 type: OS::Neutron::Port
1114 network: { get\_param: oam\_net\_id }
1115 fixed\_ips: [ { “ip\_address”: {get\_param: [ db\_oam\_ips, 0]
1118 type: OS::Neutron::Port
1119 network: { get\_param: oam\_net\_id }
1120 fixed\_ips: [ { “ip\_address”: {get\_param: [ db\_oam\_ips, 1]
1123 *Example (string parameters for IPv4 Address Assignments to an external
1126 In this example, the {network-role} has been defined as “oam” to
1127 represent an oam network and the {vm-type} has been defined as “db” for
1130 .. code-block:: python
1135 description: Neutron UUID for an OAM network
1138 description: First fixed IP assignment for db VMs on the OAM network
1141 description: Second fixed IP assignment for db VMs on the OAM network
1145 type: OS::Neutron::Port
1146 network: { get\_param: oam\_net\_id }
1147 fixed\_ips: [ { “ip\_address”: {get\_param: db\_oam\_ip\_0}}]
1149 type: OS::Neutron::Port
1150 network: { get\_param: oam\_net\_id }
1151 fixed\_ips: [ { “ip\_address”: {get\_param: db\_oam\_ip\_1}}]
1153 Property: allowed\_address\_pairs
1154 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1156 The property “allowed\_address\_pairs” in the resource OS::Neutron::Port
1157 allows the user to specify mac\_address/ip\_address (CIDR) pairs that
1158 pass through a port regardless of subnet. This enables the use of
1159 protocols such as VRRP, which floats an IP address between two instances
1160 to enable fast data plane failover. An “allowed\_address\_pairs” is
1161 unique to a {vm-type} and {network-role} combination. The management of
1162 these IP addresses (i.e. transferring ownership between active and
1163 standby VMs) is the responsibility of the application itself.
1165 Note that these parameters are *not* intended to represent Neutron
1166 “Floating IP” resources, for which OpenStack manages a pool of public IP
1167 addresses that are mapped to specific VM ports. In that case, the
1168 individual VMs are not even aware of the public IPs, and all assignment
1169 of public IPs to VMs is via OpenStack commands. OpenECOMP does not
1170 support Neutron-style Floating IPs.
1172 Both IPv4 and IPv6 “allowed\_address\_pairs” addresses are supported.
1174 If property “allowed\_address\_pairs” is used with an external network,
1175 the parameter name must adhere to the following convention:
1177 - *Format for IPv4 addresses: {vm-type}\_{network-role}\_floating\_ip*
1179 - *Format for IPv6 addresses:
1180 {vm-type}\_{network-role}\_floating\_v6\_ip*
1184 .. code-block:: python
1187 {vm-type}\_{network-role}\_floating\_ip:
1189 description: VIP for {vm-type} VMs on the {network-role} network
1190 {vm-type}\_{network-role}\_floating\_v6\_ip:
1192 description: VIP for {vm-type} VMs on the {network-role} network
1196 In this example, the {network-role} has been defined as “oam” to
1197 represent an oam network and the {vm-type} has been defined as “db” for
1200 .. code-block:: python
1204 type: comma\_delimited\_list
1205 description: Fixed IPs for db VMs on the oam network
1206 db\_oam\_floating\_ip:
1208 description: Floating IP for db VMs on the oam network
1211 type: OS::Neutron::Port
1212 network: { get\_param: oam\_net\_id }
1213 fixed\_ips: [ { “ip\_address”: {get\_param: [db\_oam\_ips,0] }}]
1214 allowed\_address\_pairs: [
1215 { “ip\_address”: {get\_param: db\_oam\_floating\_ip}}]
1217 type: OS::Neutron::Port
1218 network: { get\_param: oam\_net\_id }
1219 fixed\_ips: [ { “ip\_address”: {get\_param: [db\_oam\_ips,1] }}]
1220 allowed\_address\_pairs: [
1221 { “ip\_address”: {get\_param: db\_oam\_floating\_ip}}]
1223 If property “allowed\_address\_pairs” is used with an internal network,
1224 the parameter name should adhere to the following convention:
1226 - *Format for IPv4 addresses:
1227 {vm-type}\_int\_{network-role}\_floating\_ip*
1229 - *Format for IPv6 addresses:
1230 {vm-type}\_int\_{network-role}\_floating\_v6\_ip*
1232 Using the parameter *{vm-type}\_{network-role}\_floating\_ip* or
1233 *{vm-type}\_{network-role}\_floating\_v6\_ip* provides only one floating
1234 IP per Vm-type{vm-type} and {network-role} pair. If there is a need for
1235 multiple floating IPs (e.g., Virtual IPs (VIPs)) for a given {vm-type}
1236 and {network-role} combination within a VNF, then the parameter names
1237 defined for the “fixed\_ips” should be used with the
1238 “allowed\_address\_pairs” property. The examples below illustrate this.
1240 Below example reflects two load balancer pairs in a single VNF. Each
1243 *Example: A VNF has four load balancers. Each pair has a unique VIP.*
1245 *Pair 1:* lb\_0 and lb\_1 share a unique VIP
1247 *Pair 2:* lb\_2 and lb\_3 share a unique VIP
1249 In this example, the {network-role} has been defined as “oam” to
1250 represent an oam network and the {vm-type} has been defined as “lb” for
1253 .. code-block:: python
1257 type: OS::Neutron::Port
1258 network: { get\_param: oam\_net\_id }
1259 fixed\_ips: [ { “ip\_address”: {get\_param: [lb\_oam\_ips,0] }}]
1260 allowed\_address\_pairs: [{ “ip\_address”: {get\_param: [lb\_oam\_ips,2] }}]
1263 type: OS::Neutron::Port
1264 network: { get\_param: oam\_net\_id }
1265 fixed\_ips: [ { “ip\_address”: {get\_param: [lb\_oam\_ips,1] }}]
1266 allowed\_address\_pairs: [{ “ip\_address”: {get\_param: [lb\_oam\_ips,2] }}]
1269 type: OS::Neutron::Port
1270 network: { get\_param: oam\_net\_id }
1271 fixed\_ips: [ { “ip\_address”: {get\_param: [lb\_oam\_ips,3] }}]
1272 allowed\_address\_pairs: [{ “ip\_address”: {get\_param: [lb\_oam\_ips,5] }}]
1275 type: OS::Neutron::Port
1276 network: { get\_param: oam\_net\_id }
1277 fixed\_ips: [ { “ip\_address”: {get\_param: [lb\_oam\_ips,4] }}]
1278 allowed\_address\_pairs: [{ “ip\_address”: {get\_param: [lb\_oam\_ips,5] }}]
1280 Below example reflects a single app VM pair within a VNF with two VIPs:
1282 *Example: A VNF has two load balancers. The pair of load balancers share
1285 In this example, the {network-role} has been defined as “oam” to
1286 represent an oam network and the {vm-type} has been defined as “lb” for
1289 .. code-block:: python
1293 type: OS::Neutron::Port
1294 network: { get\_param: oam\_net\_id }
1295 fixed\_ips: [ { “ip\_address”: {get\_param: [lb\_oam\_ips,0] }}]
1296 allowed\_address\_pairs: [{ "ip\_address": {get\_param: [lb\_oam\_ips,2] }, {get\_param: [lb\_oam\_ips,3] }}]
1299 type: OS::Neutron::Port
1300 network: { get\_param: oam\_net\_id }
1301 fixed\_ips: [ { “ip\_address”: {get\_param: [lb\_oam\_ips,1] }}]
1302 allowed\_address\_pairs: [{ "ip\_address": {get\_param: [lb\_oam\_ips,2] }, {get\_param: [lb\_oam\_ips,3] }}]
1304 As a general rule, provide the fixed IPs for the VMs indexed first in
1305 the CDL and then the VIPs as shown in the examples above.
1307 Resource Property: name
1308 -----------------------
1310 The parameter naming standard for the resource OS::Nova::Server has been
1311 defined in Section 4.3.3. This section describes how the name property
1312 of all other resources must be defined.
1314 Heat templates must use the Heat “str\_replace” function in conjunction
1315 with the OpenECOMP supplied metadata parameter *vnf\_name* or
1316 *vnf\_module\_id* to generate a unique name for each VNF instance. This
1317 prevents the use of unique parameters values for resource “name”
1318 properties to be enumerated in a per instance environment file.
1322 - In most cases, only the use of the vnf\_name is necessary to create a
1325 - the Heat pseudo parameter 'OS::stack\_name’ can also be used in the
1326 ‘str\_replace’ construct to generate a unique name when the vnf\_name
1327 does not provide uniqueness
1329 .. code-block:: python
1331 type: OS::Cinder::Volume
1335 template: VF\_NAME\_STACK\_NAME\_oam\_volume
1337 VF\_NAME: { get\_param: vnf\_name }
1338 STACK\_NAME: { get\_param: 'OS::stack\_name' }
1340 type: OS::Neutron::SecurityGroup
1342 description: Security Group of Firewall
1345 template: VNF\_NAME\_Firewall\_SecurityGroup
1347 VNF\_NAME: { get\_param: vnf\_name }
1352 OpenECOMP defines three type of Output Parameters.
1354 Base Template Output Parameters:
1355 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1357 The base template output parameters are available for use as input
1358 parameters in all add-on modules. The add-on modules may (or may not)
1359 use these parameters.
1361 Volume Template Output Parameters:
1362 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1364 The volume template output parameters are only available only for the
1365 module (base or add on) that the volume is associated with.
1367 Predefined Output Parameters
1368 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1370 OpenECOMP currently defines one predefined output parameter.
1372 OAM Management IP Addresses
1373 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
1375 Many VNFs will have a management interface for application controllers
1376 to interact with and configure the VNF. Typically, this will be via a
1377 specific VM that performs a VNF administration function. The IP address
1378 of this interface must be captured and inventoried by OpenECOMP. This
1379 might be a VIP if the VNF contains an HA pair of management VMs, or may
1380 be a single IP address assigned to one VM.
1382 The Heat template may define either (or both) of the following Output
1383 parameters to identify the management IP address.
1385 - *oam\_management\_v4\_address*
1387 - *oam\_management\_v6\_address*
1391 - The Management IP Address should be defined only once per VNF, so it
1392 would only appear in one Module template
1394 - If a fixed IP for the admin VM is passed as an input parameter, it
1395 may be echoed in the output parameters
1397 - If the IP for the admin VM is obtained via DHCP, it may be obtained
1398 from the resource attributes
1402 .. code-block:: python
1406 type: OS::Nova::Server
1409 - network: {get\_param: oam\_net\_id }
1413 oam\_management\_v4\_address:
1414 value: {get\_attr: [admin\_server, networks, {get\_param: oam\_net\_id}, 0] }
1416 Heat Template Constructs
1417 ------------------------
1422 Heat templates *should not* reference any HTTP-based resource
1423 definitions, any HTTP-based nested configurations, or any HTTP-based
1426 - During orchestration, OpenECOMP *should not* retrieve any such
1427 resources from external/untrusted/unknown sources.
1429 - VNF images should not contain such references in user-data or other
1430 configuration/operational scripts that are specified via Heat or
1431 encoded into the VNF image itself.
1433 *Note:* HTTP-based references are acceptable if the HTTP-based reference
1434 is accessing information with the VM private/internal network.
1436 Heat Files Support (get\_file)
1437 ------------------------------
1439 Heat Templates may contain the inclusion of text files into Heat
1440 templates via the Heat “get\_file” directive. This may be used, for
1441 example, to define a common “user-data” script, or to inject files into
1442 a VM on startup via the “personality” property.
1444 Support for Heat Files is subject to the following limitations:
1446 - The ‘get\_files’ targets must be referenced in Heat templates by file
1447 name, and the corresponding files should be delivered to OpenECOMP
1448 along with the Heat templates.
1450 - URL-based file retrieval must not be used; it is not supported.
1452 - The included files must have unique file names within the scope of
1455 - OpenECOMP does not support a directory hierarchy for included files.
1457 - All files must be in a single, flat directory per VNF.
1459 - Included files may be used by all Modules within a given VNF.
1461 - get\_file directives may be used in both non-nested and nested
1464 Use of Heat ResourceGroup
1465 -------------------------
1467 The *OS::Heat::ResourceGroup* is a useful Heat element for creating
1468 multiple instances of a given resource or collection of resources.
1469 Typically it is used with a nested Heat template, to create, for
1470 example, a set of identical *OS::Nova::Server* resources plus their
1471 related *OS::Neutron::Port* resources via a single resource in a master
1474 *ResourceGroup* may be used in OpenECOMP to simplify the structure of a
1475 Heat template that creates multiple instances of the same VM type.
1476 However, there are important caveats to be aware of.
1478 *ResourceGroup* does not deal with structured parameters
1479 (comma-delimited-list and json) as one might typically expect. In
1480 particular, when using a list-based parameter, where each list element
1481 corresponds to one instance of the *ResourceGroup*, it is not possible
1482 to use the intrinsic “loop variable” %index% in the *ResourceGroup*
1485 For instance, the following is **not** valid Heat for a *ResourceGroup*:
1487 .. code-block:: python
1489 type: OS::Heat::ResourceGroup
1491 type: my\_nested\_vm\_template.yaml
1493 name: {get\_param: [vm\_name\_list, %index%]}
1495 Although this appears to use the nth entry of the *vm\_name\_list* list
1496 for the nth element of the *ResourceGroup*, it will in fact result in a
1497 Heat exception. When parameters are provided as a list (one for each
1498 element of a *ResourceGroup*), you must pass the complete parameter to
1499 the nested template along with the current index as separate parameters.
1501 Below is an example of an **acceptable** Heat Syntax for a
1504 .. code-block:: python
1506 type: OS::Heat::ResourceGroup
1508 type: my\_nested\_vm\_template.yaml
1510 names: {get\_param: vm\_name\_list}
1513 You can then reference within the nested template as:
1515 { get\_param: [names, {get\_param: index} ] }
1517 Note that this is workaround has very important limitations. Since the
1518 entire list parameter is passed to the nested template, any change to
1519 that list (e.g., adding an additional element) will cause Heat to treat
1520 the entire parameter as updated within the context of the nested
1521 template (i.e., for each *ResourceGroup* element). As a result, if
1522 *ResourceGroup* is ever used for scaling (e.g., increment the count and
1523 include an additional element to each list parameter), Heat will often
1524 rebuild every existing element in addition to adding the “deltas”. For
1525 this reason, use of *ResourceGroup* for scaling in this manner is not
1531 When Nova Servers are created via Heat templates, they may be passed a
1532 “keypair” which provides an ssh key to the ‘root’ login on the newly
1533 created VM. This is often done so that an initial root key/password does
1534 not need to be hard-coded into the image.
1536 Key pairs are unusual in OpenStack, because they are the one resource
1537 that is owned by an OpenStack User as opposed to being owned by an
1538 OpenStack Tenant. As a result, they are usable only by the User that
1539 created the keypair. This causes a problem when a Heat template attempts
1540 to reference a keypair by name, because it assumes that the keypair was
1541 previously created by a specific OpenECOMP user ID.
1543 When a keypair is assigned to a server, the SSH public-key is
1544 provisioned on the VMs at instantiation time. They keypair itself is not
1545 referenced further by the VM (i.e. if the keypair is updated with a new
1546 public key, it would only apply to subsequent VMs created with that
1549 Due to this behavior, the recommended usage of keypairs is in a more
1550 generic manner which does not require the pre-requisite creation of a
1551 keypair. The Heat should be structured in such a way as to:
1553 - Pass a public key as a parameter value instead of a keypair name
1555 - Create a new keypair within the VNF Heat templates (in the base
1556 module) for use within that VNF
1558 By following this approach, the end result is the same as pre-creating
1559 the keypair using the public key – i.e., that public key will be
1560 provisioned in the new VM. However, this recommended approach also makes
1561 sure that a known public key is supplied (instead of having OpenStack
1562 generate a public/private pair to be saved and tracked outside of
1563 OpenECOMP). It also removes any access/ownership issues over the created
1566 The public keys may be enumerated as a VNF Orchestration Constant in the
1567 environment file (since it is public, it is not a secret key), or passed
1568 at run-time as an instance-specific parameters. OpenECOMP will never
1569 automatically assign a public/private key pair.
1571 *Example (create keypair with an existing ssh public-key for {vm-type}
1572 of lb (for load balancer)):*
1574 .. code-block:: python
1583 type: OS::Nova::Keypair
1587 template: VNF\_NAME\_key\_pair
1589 VNF\_NAME: { get\_param: vnf\_name }
1590 public\_key: {get\_param: lb\_ssh\_public\_key}
1591 save\_private\_key: false
1596 OpenStack allows a tenant to create Security groups and define rules
1597 within the security groups.
1599 Security groups, with their rules, may either be created in the Heat
1600 template or they can be pre-created in OpenStack and referenced within
1601 the Heat template via parameter(s). There can be a different approach
1602 for security groups assigned to ports on internal (intra-VNF) networks
1603 or external networks (inter-VNF). Furthermore, there can be a common
1604 security group across all VMs for a specific network or it can vary by
1605 VM (i.e., {vm-type}) and network type (i.e., {network-role}).
1607 Anti-Affinity and Affinity Rules
1608 --------------------------------
1610 Anti-affinity or affinity rules are supported using normal OpenStack
1611 *“OS::Nova::ServerGroup”* resources. Separate ServerGroups are typically
1612 created for each VM type to prevent them from residing on the same host,
1613 but they can be applied to multiple VM types to extend the
1614 affinity/anti-affinity across related VM types as well.
1618 In this example, the {network-role} has been defined as “oam” to
1619 represent an oam network and the {vm-type} have been defined as “lb” for
1620 load balancer and “db” for database.
1622 .. code-block:: python
1626 type: OS::Nova::ServerGroup
1631 $vnf\_name: {get\_param: vnf\_name}
1632 template: $vnf\_name-server\_group1
1637 type: OS::Nova::ServerGroup
1642 $vnf\_name: {get\_param: vnf\_name}
1643 template: $vnf\_name-server\_group2
1648 *type: OS::Nova::Server*
1652 group: {get\_param: db\_server\_group}
1655 type: OS::Nova::Server
1659 group: {get\_param: db\_server\_group}
1662 type: OS::Nova::Server
1666 group: {get\_param: lb\_server\_group}