diff options
Diffstat (limited to 'docs/Chapter4/Modularity.rst')
| -rw-r--r-- | docs/Chapter4/Modularity.rst | 352 |
1 files changed, 352 insertions, 0 deletions
diff --git a/docs/Chapter4/Modularity.rst b/docs/Chapter4/Modularity.rst new file mode 100644 index 0000000..12024bd --- /dev/null +++ b/docs/Chapter4/Modularity.rst @@ -0,0 +1,352 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 International License. +.. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2017 AT&T Intellectual Property. All rights reserved. + + +VNF Modularity +-------------- + +ONAP Heat Orchestration Templates: Overview +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ONAP supports a modular Heat Orchestration Template design pattern, +referred to as *VNF Modularity.* + +ONAP VNF Modularity Overview +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +With VNF Modularity, 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. + +A modular Heat Orchestration Template can be either one of the following +types: + +1. Base Module + +2. Incremental Module + +3. Cinder Volume Module + +* R-37028 The VNF **MUST** be composed of one “base” module. +* R-41215 The VNF **MAY** have zero to many “incremental” modules. +* R-20974 The VNF **MUST** deploy the base module first, prior to + the 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 +Virtual Machine (VM) (i.e., OS::Nova::Server) is deleted, allowing the +volume to be reused on another instance (e.g., during a failover +activity). + +* R-11200 The VNF **MUST** keep the scope of a Cinder volume module, + when it exists, to be 1:1 with the VNF Base Module or Incremental Module. + +* R-38474 The VNF **MUST** have a corresponding environment file for + a Base Module. +* R-81725 The VNF **MUST** have a corresponding environment file for + an Incremental Module. +* R-53433 The VNF **MUST** have a corresponding environment file for + a Cinder Volume Module. + +These concepts will be described in more detail throughout the document. +This overview is provided to set the stage and help clarify the concepts +that will be introduced. + + +ONAP 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. + +A modular Heat Orchestration Template can be either one of the following +types: + +1. Base Module + +2. Incremental Module + +3. Cinder Volume Module + +A VNF must be composed of one “base” module and may be composed of zero +to many “incremental” modules. The base module must be deployed first, +prior to the 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 failover activity). + +The scope of a Cinder volume module, when it exists, must be 1:1 with a +Base module or Incremental Module. + +A Base Module must have a corresponding environment file. + +An Incremental Module must have a corresponding environment file. + +A Cinder Volume Module must have a corresponding environment file. + +A VNF module (base, incremental, cinder) may support nested templates. + +A shared Heat Orchestration Template resource must be defined in the +base module. A shared resource is a resource that that will be +referenced by another resource that is defined in the Base Module and/or +one or more incremental modules. + +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. + +Suggested Patterns for Modular VNFs +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are numerous variations of VNF modularity. Below are two suggested +usage patterns. + +**Option 1: Modules per VNFC type** + +a. Base module contains only the shared resources. + +b. 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}. + +c. For a given {vm-type} incremental module, the VNF may have + + i. 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. + + ii. 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** + +a. Base module contains a complete initial VNF instance + +b. Incremental modules for incremental scaling units + + i. May contain VMs of multiple types in logical scaling combinations + + ii. 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. + +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: + + a. Must include all shared resources (e.g., private networks, server + groups, security groups) + + b. Must expose all shared resources (by UUID) as “outputs” in its + associated Heat template (i.e., ONAP Base Module Output + Parameters) + + c. May include initial set of VMs + + d. May be operational as a stand-alone “minimum” configuration of the + VNF + +2. VNFs may have one or more incremental modules which: + + a. Defines additional resources that can be added to an existing VNF + + b. Must be complete Heat templates + + i. i.e. not snippets to be incorporated into some larger template + + c. Should define logical growth-units or sub-components of an overall + VNF + + d. On creation, receives appropriate Base Module outputs as + parameters + + i. Provides access to all shared resources (by UUID) + + ii. must not be dependent on other Add-On VNF Modules + + e. 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 Volume Templates) + + a. Volume modules must correspond 1:1 with a base module or + incremental module + + b. 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) + + a. The output parameter name in the base must match the parameter + name in the add-on module + +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 out +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 + +.. code-block:: 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 + +.. code-block:: yaml + + parameters: + dns_sec_grp_id: + type: string + description: security group UUID + . . . + + resources: + dns_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 + +.. code-block:: yaml + + heat_template_version: 2013-05-23 + + resources: + int_oam_network: + type: OS::Neutron::Network + properties: + name: {… } + . . . + outputs: + int_oam_net_id: + value: {get_resource: int_oam_network } + + +incremental.yaml + +.. code-block:: 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: + type: OS::Nova::Server + properties: + name: {get_param: lb_name_0} + networks: + - port: { get_resource: lb_port } + . . . + + lb_port: + type: OS::Neutron::Port + properties: + network_id: { get_param: int_oam_net_id } + ... |