docs/Chapter5/Heat/ONAP Heat VNF Modularity.rst

   1 .. 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.
   4
   5 .. _ONAP Heat VNF Modularity:
   6
   7 ONAP Heat VNF Modularity
   8 ---------------------------
   9
  10 ONAP supports a modular Heat Orchestration Template design pattern,
  11 referred to as *VNF Modularity.* With this approach, a single VNF **MAY** be
  12 composed from one or more Heat Orchestration Templates, each of which
  13 represents a subset of the overall VNF. These component parts are
  14 referred to as *VNF Modules*. During orchestration, these modules
  15 are deployed incrementally to create the complete VNF.
  16
  17 As stated in :need:`R-33132`, a VNF's Heat Orchestration Template **MAY** be
  18      1. Base Module Heat Orchestration Template (also referred to as a
  19         Base Module),
  20      2. Incremental Module Heat Orchestration Template (referred to as
  21         an Incremental Module), or
  22      3. a Cinder Volume Module Heat Orchestration Template (referred to as
  23         Cinder Volume  Module).
  24
  25 As stated in :need:`R-20974`, at orchestration time, the VNF's Base
  26 Module **MUST** be deployed first, prior to any incremental modules.
  27
  28 As stated in :need:`R-28980`, :need:`R-86926`, and :need:`R-91497`, a
  29 VNF's incremental module **MAY** be used for
  30
  31   * initial VNF deployment only
  32   * scale out only
  33   * both deployment and scale out
  34
  35 As stated in :need:`R-68122`, a VNF's incremental module **MAY** be deployed
  36 more than once, either during initial VNF deployment and/or scale out
  37
  38 As stated in :need:`R-37028` and :need:`R-13196`, a VNF **MUST** be composed
  39 of one Base Module and *MAY** be composed of zero to many Incremental
  40 Modules.
  41
  42 As stated in :need:`R-20974`, at orchestration time, the VNF's Base Module
  43 **MUST** be deployed first, prior to any incremental modules.
  44
  45 ONAP also supports the concept of an optional, independently deployed
  46 Cinder volume via a separate Heat Orchestration Templates, referred to
  47 as a Cinder Volume Module. This allows the volume to persist after a VM
  48 (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused on
  49 another instance (e.g., during a fail over activity).
  50
  51 The scope of a Cinder volume module, when it exists, must be 1:1 with a
  52 Base module or Incremental Module.
  53
  54 A VNF module (base, incremental, cinder) **MAY** support nested templates.
  55
  56 A shared Heat Resource is a resource that **MAY** be used by
  57 other Heat Resources either in the Base Module or an
  58 Incremental Module.
  59
  60 .. req::
  61     :id: R-61001
  62     :target: VNF
  63     :keyword: MUST
  64     :validation_mode: static
  65     :updated: casablanca
  66
  67
  68     A shared Heat Orchestration Template resource is a resource that **MUST**
  69     be defined in the base module and will be referenced by one or
  70     more resources in one more more incremental modules.
  71
  72     The UUID of the shared resource (created in the base module) **MUST** be
  73     exposed by declaring a parameter in the
  74     ``outputs`` section of the base module.
  75
  76     For ECOMP to provided the UUID value of the shared resource to the
  77     incremental module, the parameter name defined in the ``outputs``
  78     section of the base module **MUST** be defined as a parameter
  79     in the ``parameters`` section of the incremental module.
  80
  81     ECOMP will capture the output parameter name and value in the base module
  82     and provide the value to the corresponding parameter(s) in the
  83     incremental module(s).
  84
  85 When the shared resource needs to be referenced by a resource in an
  86 incremental module, the UUID of the shared resource must be exposed by
  87 declaring an ONAP Base Module Output Parameter.
  88
  89 Note that a Cinder volume is not a shared resource. A volume template
  90 must correspond 1:1 with a base module or incremental module.
  91
  92 An example of a shared resource is the resource
  93 OS::Neutron::SecurityGroup. Security groups are sets of IP filter rules
  94 that are applied to a VNF’s networking. The resource OS::Neutron::Port
  95 has a property security_groups which provides the security groups
  96 associated with port. The value of parameter(s) associated with this
  97 property must be the UUIDs of the resource(s)
  98 OS::Neutron::SecurityGroup.
  99
 100 *Note:* A Cinder volume is not considered a shared resource. A volume
 101 template must correspond 1:1 with a base template or add-on module
 102 template.
 103
 104 Suggested Patterns for Modular VNFs
 105 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 106
 107 There are numerous variations of VNF modularity. Below are two suggested
 108 usage patterns.
 109
 110 **Option 1: Incremental Modules per VNFC type**
 111
 112 a. Base module contains only the shared resources.
 113
 114 b. Group all VMs (e.g., VNFCs) of a given type (i.e. {vm-type}) into its
 115    own incremental module. That is, the VNF has an incremental module
 116    for each {vm-type}.
 117
 118 c. For a given {vm-type} incremental module, the VNF may have
 119
 120    i.  One incremental module used for both initial turn up and re-used
 121        for scaling. This approach is used when the number of VMs
 122        instantiated will be the same for initial deployment and scaling.
 123
 124    ii. Two incremental modules, where one is used for initial turn up
 125        and one is used for scaling. This approach is used when the
 126        number of VMs instantiated will be different for initial
 127        deployment and scaling.
 128
 129 **Option 2: Base VNF with Incremental Growth Modules**
 130
 131 a. Base module contains a complete initial VNF instance
 132
 133 b. Incremental modules for incremental scaling units
 134
 135    i.  May contain VMs of multiple types in logical scaling combinations
 136
 137    ii. May be separated by VM type for multi-dimensional scaling
 138
 139 With no growth units, Option 2 is equivalent to the "One Heat Template
 140 per VNF" model.
 141
 142 Note that modularization of VNFs is not required. A single Heat
 143 Orchestration Template (a base module) may still define a complete VNF,
 144 which might be appropriate for smaller VNFs that do not have any scaling
 145 options.
 146
 147 Modularity Rules
 148 ^^^^^^^^^^^^^^^^^^^
 149
 150 There are some rules to follow when building modular VNF templates:
 151
 152 1. All VNFs must have one Base VNF Module (template) that must be the
 153    first one deployed. The base template:
 154
 155    a. Must include all shared resources (e.g., private networks, server
 156       groups, security groups)
 157
 158    b. Must expose all shared resources (by UUID) as "outputs" in its
 159       associated Heat template (i.e., ONAP Base Module Output
 160       Parameters)
 161
 162    c. May include initial set of VMs
 163
 164    d. May be operational as a stand-alone "minimum" configuration of the
 165       VNF
 166
 167 2. VNFs may have one or more incremental modules which:
 168
 169    a. Defines additional resources that can be added to an existing VNF
 170
 171    b. Must be complete Heat templates
 172
 173       i. i.e. not snippets to be incorporated into some larger template
 174
 175    c. Should define logical growth-units or sub-components of an overall
 176       VNF
 177
 178    d. On creation, receives appropriate Base Module outputs as
 179       parameters
 180
 181       i.  Provides access to all shared resources (by UUID)
 182
 183       ii. *VNFs may have one or more incremental modules which must not be
 184           dependent on other Add-On VNF Modules*
 185
 186    e. Multiple instances of an incremental Module may be added to the
 187       same VNF (e.g., incrementally grow a VNF by a fixed "add-on"
 188       growth units)
 189
 190 3. Each VNF Module (base or incremental) may have (optional) an
 191    associated Cinder Volume Module (see Cinder Volumes)
 192
 193    a. Volume modules must correspond 1:1 with a base module or
 194       incremental module
 195
 196    b. A Cinder volume may be embedded within the base module or
 197       incremental module if persistence is not required
 198
 199 4. Shared resource UUIDs are passed between the base module and
 200    incremental modules via Heat Outputs Parameters (i.e., Base Module
 201    Output Parameters)
 202
 203    a. The output parameter name in the base must match the parameter
 204       name in the add-on module
 205
 206 VNF Modularity Examples
 207 ^^^^^^^^^^^^^^^^^^^^^^^^^
 208
 209 *Example: Base Module creates SecurityGroup*
 210
 211 A VNF has a base module, named base.yaml, that defines a
 212 OS::Neutron::SecurityGroup. The security group will be referenced by an
 213 OS::Neutron::Port resource in an incremental module, named
 214 INCREMENTAL_MODULE.yaml. The base module defines a parameter in the
 215 outputs:section named dns_sec_grp_id. dns_sec_grp_id is defined as a
 216 parameter in the incremental module. ONAP captures the UUID value of
 217 dns_sec_grp_id from the base module output statement and provides the
 218 value to the incremental module.
 219
 220 Note that the example below is not a complete Heat Orchestration
 221 Template. The {network-role} has been defined as oam to represent an oam
 222 network and the {vm-type} has been defined as dns.
 223
 224 base_MODULE.yaml
 225
 226 .. code-block:: yaml
 227
 228   parameters:
 229   . . .
 230   resources:
 231     DNS_SECURITY_GROUP:
 232       type: OS::Neutron::SecurityGroup
 233       properties:
 234         description: vDNS security group
 235         name:
 236         str_replace:
 237           template: VNF_NAME_sec_grp_DNS
 238           params:
 239             VMF_NAME: {get_param: vnf_name}
 240         rules: [. . . . .
 241         ]
 242   . . .
 243   outputs:
 244     dns_sec_grp_id:
 245       description: UUID of DNS Resource SecurityGroup
 246       value: { get_resource: DNS_SECURITY_GROUP }
 247
 248 INCREMENTAL_MODULE.yaml
 249
 250 .. code-block:: yaml
 251
 252   parameters:
 253     dns_sec_grp_id:
 254       type: string
 255       description: security group UUID
 256   . . .
 257
 258   resources:
 259     dns_0_oam_0_port:
 260       type: OS::Neutron::Port
 261         properties:
 262           name:
 263             str_replace:
 264               template: VNF_NAME_dns_oam_port
 265               params:
 266                 VNF_NAME: {get_param: vnf_name}
 267           network: { get_param: oam_net_name }
 268           fixed_ips: [{ "ip_address": { get_param: dns_oam_ip_0 }}]
 269           security_groups: [{ get_param: dns_sec_grp_id }]
 270
 271 *Examples: Base Module creates an internal network*
 272
 273 A VNF has a base module, named base_module.yaml, that creates an
 274 internal network. An incremental module, named incremental_module.yaml,
 275 will create a VM that will connect to the internal network. The base
 276 module defines a parameter in the out section named int_oam_net_id.
 277 int_oam_net_id is defined as a parameter in the incremental module.
 278 ONAP captures the UUID value of int_oam_net_id from the base module
 279 output statement and provides the value to the incremental module.
 280
 281 Note that the example below is not a complete Heat Orchestration
 282 Template. The {network-role} has been defined as oam to represent an oam
 283 network and the {vm-type} has been defined as lb for load balancer.
 284
 285 base.yaml
 286
 287 .. code-block:: yaml
 288
 289   heat_template_version: 2013-05-23
 290
 291   resources:
 292     int_oam_network:
 293       type: OS::Neutron::Network
 294       properties:
 295         name: {… }
 296   . . .
 297
 298   outputs:
 299     int_oam_net_id:
 300     value: {get_resource: int_oam_network }
 301
 302 incremental.yaml
 303
 304 .. code-block:: yaml
 305
 306   heat_template_version: 2013-05-23
 307
 308   parameters:
 309     int_oam_net_id:
 310       type: string
 311       description: ID of shared private network from Base template
 312     lb_name_0:
 313       type: string
 314       description: name for the add-on VM instance
 315
 316   resources:
 317     lb_server_0:
 318       type: OS::Nova::Server
 319       properties:
 320         name: {get_param: lb_name_0}
 321         networks:
 322           - port: { get_resource: get_resource: lb_0_int_oam_port_0  }
 323   . . .
 324     lb_0_int_oam_port_0:
 325       type: OS::Neutron::Port
 326         properties:
 327         network: { get_param: int_oam_net_id }
 328   ...
 329