5.2.6. ONAP Heat VNF Modularity

ONAP supports a modular Heat Orchestration Template design pattern, referred to as VNF Modularity. With this approach, a single VNF MAY be composed from one or more Heat Orchestration Templates, each of which represents a subset of the overall VNF. These component parts are referred to as VNF Modules. During orchestration, these modules are deployed incrementally to create the complete VNF.

As stated in (R-33132), a VNF’s Heat Orchestration Template MAY be
  1. Base Module Heat Orchestration Template (also referred to as a Base Module),
  2. Incremental Module Heat Orchestration Template (referred to as an Incremental Module), or
  3. a Cinder Volume Module Heat Orchestration Template (referred to as Cinder Volume Module).

At orchestration time, the VNF’s Base Module MUST be deployed first, prior to any incremental modules.

As stated in (R-28980), (R-86926), and (R-91497), a VNF’s incremental module MAY be used for

  • initial VNF deployment only
  • scale out only
  • both deployment and scale out

As stated in (R-68122), a VNF’s incremental module MAY be deployed more than once, either during initial VNF deployment and/or scale out

As stated in (R-37028) and (R-13196), a VNF MUST be composed of one Base Module and MAY be composed of zero to many Incremental Modules.

ONAP also supports the concept of an optional, independently deployed Cinder volume via a separate Heat Orchestration Templates, referred to as a Cinder Volume Module. This allows the volume to persist after a VM (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused on another instance (e.g., during a fail over activity).

The scope of a Cinder volume module, when it exists, must be 1:1 with a Base module or Incremental Module.

A VNF module (base, incremental, cinder) MAY support nested templates.

A shared Heat Resource is a resource that MAY be used by other Heat Resources either in the Base Module or an Incremental Module.

Requirement: R-61001
updated: dublin
validation_mode: none
target: VNF
keyword: MUST

A shared Heat Orchestration Template resource is a resource that MUST be defined in the base module and will be referenced by one or more resources in one or more incremental modules.

The UUID of the shared resource (created in the base module) MUST be exposed by declaring a parameter in the outputs section of the base module.

For ONAP to provided the UUID value of the shared resource to the incremental module, the parameter name defined in the outputs section of the base module MUST be defined as a parameter in the parameters section of the incremental module.

ONAP will capture the output parameter name and value in the base module and provide the value to the corresponding parameter(s) in the incremental module(s).

When the shared resource needs to be referenced by a resource in an incremental module, the UUID of the shared resource must be exposed by declaring an ONAP Base Module Output Parameter.

Note that a Cinder volume is not a shared resource. A volume template must correspond 1:1 with a base module or incremental module.

An example of a shared resource is the resource OS::Neutron::SecurityGroup. Security groups are sets of IP filter rules that are applied to a VNF’s networking. The resource OS::Neutron::Port has a property security_groups which provides the security groups associated with port. The value of parameter(s) associated with this property must be the UUIDs of the resource(s) OS::Neutron::SecurityGroup.

Note: A Cinder volume is not considered a shared resource. A volume template must correspond 1:1 with a base template or add-on module template.

5.2.6.1. Suggested Patterns for Modular VNFs

There are numerous variations of VNF modularity. Below are two suggested usage patterns.

Option 1: Incremental Modules per VNFC type

  1. Base module contains only the shared resources.
  2. Group all VMs (e.g., VNFCs) of a given type (i.e. {vm-type}) into its own incremental module. That is, the VNF has an incremental module for each {vm-type}.
  3. For a given {vm-type} incremental module, the VNF may have
    1. One incremental module used for both initial turn up and re-used for scaling. This approach is used when the number of VMs instantiated will be the same for initial deployment and scaling.
    2. Two incremental modules, where one is used for initial turn up and one is used for scaling. This approach is used when the number of VMs instantiated will be different for initial deployment and scaling.

Option 2: Base VNF with Incremental Growth Modules

  1. Base module contains a complete initial VNF instance
  2. Incremental modules for incremental scaling units
    1. May contain VMs of multiple types in logical scaling combinations
    2. May be separated by VM type for multi-dimensional scaling

With no growth units, Option 2 is equivalent to the “One Heat Template per VNF” model.

Note that modularization of VNFs is not required. A single Heat Orchestration Template (a base module) may still define a complete VNF, which might be appropriate for smaller VNFs that do not have any scaling options.

5.2.6.2. Modularity Rules

There are some rules to follow when building modular VNF templates:

  1. All VNFs must have one Base VNF Module (template) that must be the first one deployed. The base template:
    1. Must include all shared resources (e.g., private networks, server groups, security groups)
    2. Must expose all shared resources (by UUID) as “outputs” in its associated Heat template (i.e., ONAP Base Module Output Parameters)
    3. May include initial set of VMs
    4. May be operational as a stand-alone “minimum” configuration of the VNF
  2. VNFs may have one or more incremental modules which:
    1. Defines additional resources that can be added to an existing VNF
    2. Must be complete Heat templates
      1. i.e. not snippets to be incorporated into some larger template
    3. Should define logical growth-units or sub-components of an overall VNF
    4. On creation, receives appropriate Base Module outputs as parameters
      1. Provides access to all shared resources (by UUID)
      2. VNFs may have one or more incremental modules which must not be dependent on other Add-On VNF Modules
    5. Multiple instances of an incremental Module may be added to the same VNF (e.g., incrementally grow a VNF by a fixed “add-on” growth units)
  3. Each VNF Module (base or incremental) may have (optional) an associated Cinder Volume Module (see Cinder Volumes)
    1. Volume modules must correspond 1:1 with a base module or incremental module
    2. A Cinder volume may be embedded within the base module or incremental module if persistence is not required
  4. Shared resource UUIDs are passed between the base module and incremental modules via Heat Outputs Parameters (i.e., Base Module Output Parameters)
    1. The output parameter name in the base must match the parameter name in the add-on module

5.2.6.3. VNF Modularity Examples

Example: Base Module creates SecurityGroup

A VNF has a base module, named base.yaml, that defines a OS::Neutron::SecurityGroup. The security group will be referenced by an OS::Neutron::Port resource in an incremental module, named INCREMENTAL_MODULE.yaml. The base module defines a parameter in the outputs:section named dns_sec_grp_id. dns_sec_grp_id is defined as a parameter in the incremental module. ONAP captures the UUID value of dns_sec_grp_id from the base module output statement and provides the value to the incremental module.

Note that the example below is not a complete Heat Orchestration Template. The {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as dns.

base_MODULE.yaml

parameters:
. . .
resources:
  DNS_SECURITY_GROUP:
    type: OS::Neutron::SecurityGroup
    properties:
      description: vDNS security group
      name:
      str_replace:
        template: VNF_NAME_sec_grp_DNS
        params:
          VMF_NAME: {get_param: vnf_name}
      rules: [. . . . .
      ]
. . .
outputs:
  dns_sec_grp_id:
    description: UUID of DNS Resource SecurityGroup
    value: { get_resource: DNS_SECURITY_GROUP }

INCREMENTAL_MODULE.yaml

parameters:
  dns_sec_grp_id:
    type: string
    description: security group UUID
. . .

resources:
  dns_0_oam_0_port:
    type: OS::Neutron::Port
      properties:
        name:
          str_replace:
            template: VNF_NAME_dns_oam_port
            params:
              VNF_NAME: {get_param: vnf_name}
        network: { get_param: oam_net_name }
        fixed_ips: [{ "ip_address": { get_param: dns_oam_ip_0 }}]
        security_groups: [{ get_param: dns_sec_grp_id }]

Examples: Base Module creates an internal network

A VNF has a base module, named base_module.yaml, that creates an internal network. An incremental module, named incremental_module.yaml, will create a VM that will connect to the internal network. The base module defines a parameter in the out section named int_oam_net_id. int_oam_net_id is defined as a parameter in the incremental module. ONAP captures the UUID value of int_oam_net_id from the base module output statement and provides the value to the incremental module.

Note that the example below is not a complete Heat Orchestration Template. The {network-role} has been defined as oam to represent an oam network and the {vm-type} has been defined as lb for load balancer.

base.yaml

heat_template_version: 2013-05-23

resources:
  int_oam_network:
    type: OS::Neutron::Net
    properties:
      name: { }
. . .

outputs:
  int_oam_net_id:
  value: {get_resource: int_oam_network }

incremental.yaml

heat_template_version: 2013-05-23

parameters:
  int_oam_net_id:
    type: string
    description: ID of shared private network from Base template
  lb_name_0:
    type: string
    description: name for the add-on VM instance

resources:
  lb_server_0:
    type: OS::Nova::Server
    properties:
      name: {get_param: lb_name_0}
      networks:
        - port: { get_resource: get_resource: lb_0_int_oam_port_0  }
. . .
  lb_0_int_oam_port_0:
    type: OS::Neutron::Port
      properties:
      network: { get_param: int_oam_net_id }
...