docs/Chapter4/Modularity.rst

   1 .. Modifications Copyright © 2017-2018 AT&T Intellectual Property.
   2
   3 .. Licensed under the Creative Commons License, Attribution 4.0 Intl.
   4    (the "License"); you may not use this documentation except in compliance
   5    with the License. You may obtain a copy of the License at
   6
   7 .. https://creativecommons.org/licenses/by/4.0/
   8
   9 .. Unless required by applicable law or agreed to in writing, software
  10    distributed under the License is distributed on an "AS IS" BASIS,
  11    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    See the License for the specific language governing permissions and
  13    limitations under the License.
  14
  15
  16 VNF Modularity
  17 --------------
  18
  19 ONAP Heat Orchestration Templates: Overview
  20 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  21
  22 ONAP supports a modular Heat Orchestration Template design pattern,
  23 referred to as *VNF Modularity.*
  24
  25 ONAP VNF Modularity Overview
  26 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  27
  28 With VNF Modularity, a single VNF may be composed from one or more Heat
  29 Orchestration Templates, each of which represents a subset of the
  30 overall VNF. These component parts are referred to as "\ *VNF
  31 Modules*\ ". During orchestration, these modules are deployed
  32 incrementally to create the complete VNF.
  33
  34 A modular Heat Orchestration Template can be either one of the following
  35 types:
  36
  37 1. Base Module
  38
  39 2. Incremental Module
  40
  41 3. Cinder Volume Module
  42
  43 :need:`R-37028` - The VNF **MUST** be composed of one "base" module.
  44
  45 .. req::
  46     :id: R-41215
  47     :target: VNF
  48     :keyword: MAY
  49
  50     The VNF **MAY** have zero to many "incremental" modules.
  51
  52 :need:`R-20974` - The VNF **MUST** deploy the base module first, prior to
  53 the incremental modules.
  54
  55 ONAP also supports the concept of an optional, independently deployed
  56 Cinder volume via a separate Heat Orchestration Templates, referred to
  57 as a Cinder Volume Module. This allows the volume to persist after a
  58 Virtual Machine (VM) (i.e., OS::Nova::Server) is deleted, allowing the
  59 volume to be reused on another instance (e.g., during a failover
  60 activity).
  61
  62 :need:`R-11200` - The VNF **MUST** keep the scope of a Cinder volume module,
  63 when it exists, to be 1:1 with the VNF Base Module or Incremental Module.
  64
  65 :need:`R-38474` - The VNF **MUST** have a corresponding environment file for a
  66 Base Module.
  67
  68 :need:`R-81725` - The VNF **MUST** have a corresponding environment file for an
  69 Incremental Module.
  70
  71 :need:`R-53433` - The VNF **MUST** have a corresponding environment file for a
  72 Cinder Volume Module.
  73
  74 These concepts will be described in more detail throughout the document.
  75 This overview is provided to set the stage and help clarify the concepts
  76 that will be introduced.
  77
  78 ONAP VNF Modularity
  79 ^^^^^^^^^^^^^^^^^^^^^^
  80
  81 ONAP supports a modular Heat Orchestration Template design pattern,
  82 referred to as *VNF Modularity.* With this approach, a single VNF may be
  83 composed from one or more Heat Orchestration Templates, each of which
  84 represents a subset of the overall VNF. These component parts are
  85 referred to as "\ *VNF Modules*\ ". During orchestration, these modules
  86 are deployed incrementally to create the complete VNF.
  87
  88 A modular Heat Orchestration Template can be either one of the following
  89 types:
  90
  91 1. Base Module
  92
  93 2. Incremental Module
  94
  95 3. Cinder Volume Module
  96
  97 A VNF must be composed of one "base" module and may be composed of zero
  98 to many "incremental" modules. The base module must be deployed first,
  99 prior to the incremental modules.
 100
 101 ONAP also supports the concept of an optional, independently deployed
 102 Cinder volume via a separate Heat Orchestration Templates, referred to
 103 as a Cinder Volume Module. This allows the volume to persist after a VM
 104 (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused on
 105 another instance (e.g., during a failover activity).
 106
 107 The scope of a Cinder volume module, when it exists, must be 1:1 with a
 108 Base module or Incremental Module.
 109
 110 A Base Module must have a corresponding environment file.
 111
 112 An Incremental Module must have a corresponding environment file.
 113
 114 A Cinder Volume Module must have a corresponding environment file.
 115
 116 A VNF module (base, incremental, cinder) may support nested templates.
 117
 118 A shared Heat Orchestration Template resource must be defined in the
 119 base module. A shared resource is a resource that that will be
 120 referenced by another resource that is defined in the Base Module and/or
 121 one or more incremental modules.
 122
 123 When the shared resource needs to be referenced by a resource in an
 124 incremental module, the UUID of the shared resource must be exposed by
 125 declaring an ONAP Base Module Output Parameter.
 126
 127 Note that a Cinder volume is *not* a shared resource. A volume template
 128 must correspond 1:1 with a base module or incremental module.
 129
 130 An example of a shared resource is the resource
 131 OS::Neutron::SecurityGroup. Security groups are sets of IP filter rules
 132 that are applied to a VNF’s networking. The resource OS::Neutron::Port
 133 has a property security\_groups which provides the security groups
 134 associated with port. The value of parameter(s) associated with this
 135 property must be the UUIDs of the resource(s)
 136 OS::Neutron::SecurityGroup.
 137
 138 *Note:* A Cinder volume is *not* considered a shared resource. A volume
 139 template must correspond 1:1 with a base template or add-on module
 140 template.
 141
 142 Suggested Patterns for Modular VNFs
 143 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 144
 145 There are numerous variations of VNF modularity. Below are two suggested
 146 usage patterns.
 147
 148 **Option 1: Modules per VNFC type**
 149
 150 a. Base module contains only the shared resources.
 151
 152 b. Group all VMs (e.g., VNFCs) of a given type (i.e. {vm-type}) into its
 153    own incremental module. That is, the VNF has an incremental module
 154    for each {vm-type}.
 155
 156 c. For a given {vm-type} incremental module, the VNF may have
 157
 158    i.  One incremental module used for both initial turn up and re-used
 159        for scaling. This approach is used when the number of VMs
 160        instantiated will be the same for initial deployment and scaling.
 161
 162    ii. Two incremental modules, where one is used for initial turn up
 163        and one is used for scaling. This approach is used when the
 164        number of VMs instantiated will be different for initial
 165        deployment and scaling.
 166
 167 **Option 2: Base VNF with Incremental Growth Modules**
 168
 169 a. Base module contains a complete initial VNF instance
 170
 171 b. Incremental modules for incremental scaling units
 172
 173    i.  May contain VMs of multiple types in logical scaling combinations
 174
 175    ii. May be separated by VM type for multi-dimensional scaling
 176
 177 With no growth units, Option 2 is equivalent to the "One Heat Template
 178 per VNF" model.
 179
 180 Note that modularization of VNFs is not required. A single Heat
 181 Orchestration Template (a base module) may still define a complete VNF,
 182 which might be appropriate for smaller VNFs that do not have any scaling
 183 options.
 184
 185 Modularity Rules
 186 ^^^^^^^^^^^^^^^^^^^
 187
 188 There are some rules to follow when building modular VNF templates:
 189
 190 1. All VNFs must have one Base VNF Module (template) that must be the
 191    first one deployed. The base template:
 192
 193    a. Must include all shared resources (e.g., private networks, server
 194       groups, security groups)
 195
 196    b. Must expose all shared resources (by UUID) as "outputs" in its
 197       associated Heat template (i.e., ONAP Base Module Output
 198       Parameters)
 199
 200    c. May include initial set of VMs
 201
 202    d. May be operational as a stand-alone "minimum" configuration of the
 203       VNF
 204
 205 2. VNFs may have one or more incremental modules which:
 206
 207    a. Defines additional resources that can be added to an existing VNF
 208
 209    b. Must be complete Heat templates
 210
 211       i. i.e. not snippets to be incorporated into some larger template
 212
 213    c. Should define logical growth-units or sub-components of an overall
 214       VNF
 215
 216    d. On creation, receives appropriate Base Module outputs as
 217       parameters
 218
 219       i.  Provides access to all shared resources (by UUID)
 220
 221       ii. must not be dependent on other Add-On VNF Modules
 222
 223    e. Multiple instances of an incremental Module may be added to the
 224       same VNF (e.g., incrementally grow a VNF by a fixed "add-on"
 225       growth units)
 226
 227 3. Each VNF Module (base or incremental) may have (optional) an
 228    associated Cinder Volume Module (see Cinder Volume Templates)
 229
 230    a. Volume modules must correspond 1:1 with a base module or
 231       incremental module
 232
 233    b. A Cinder volume may be embedded within the base module or
 234       incremental module if persistence is not required
 235
 236 4. Shared resource UUIDs are passed between the base module and
 237    incremental modules via Heat Outputs Parameters (i.e., Base Module
 238    Output Parameters)
 239
 240    a. The output parameter name in the base must match the parameter
 241       name in the add-on module
 242
 243 VNF Modularity Examples
 244 ^^^^^^^^^^^^^^^^^^^^^^^
 245
 246 *Example: Base Module creates SecurityGroup*
 247
 248 A VNF has a base module, named base.yaml, that defines a
 249 OS::Neutron::SecurityGroup. The security group will be referenced by an
 250 OS::Neutron::Port resource in an incremental module, named
 251 INCREMENTAL\_MODULE.yaml. The base module defines a parameter in the out
 252 section named dns\_sec\_grp\_id. dns\_sec\_grp\_id is defined as a
 253 parameter in the incremental module. ONAP captures the UUID value of
 254 dns\_sec\_grp\_id from the base module output statement and provides the
 255 value to the incremental module.
 256
 257 Note that the example below is not a complete Heat Orchestration
 258 Template. The {network-role} has been defined as oam to represent an oam
 259 network and the {vm-type} has been defined as dns.
 260
 261 base\_MODULE.yaml
 262
 263 .. code-block:: yaml
 264
 265  parameters:
 266    . . .
 267
 268  resources:
 269    DNS_SECURITY_GROUP:
 270      type: OS::Neutron::SecurityGroup
 271      properties:
 272        description: vDNS security group
 273        name:
 274          str_replace:
 275            template: VNF_NAME_sec_grp_DNS
 276            params:
 277              VMF_NAME: {get_param: vnf_name}
 278        rules: [. . . . .
 279
 280    . . .
 281
 282  outputs:
 283    dns_sec_grp_id:
 284      description: UUID of DNS Resource SecurityGroup
 285      value: { get_resource: DNS_SECURITY_GROUP }
 286
 287
 288 INCREMENTAL\_MODULE.yaml
 289
 290 .. code-block:: yaml
 291
 292  parameters:
 293    dns_sec_grp_id:
 294      type: string
 295      description: security group UUID
 296    . . .
 297
 298  resources:
 299    dns_oam_0_port:
 300      type: OS::Neutron::Port
 301      properties:
 302        name:
 303          str_replace:
 304            template: VNF_NAME_dns_oam_port
 305            params:
 306              VNF_NAME: {get_param: vnf_name}
 307        network: { get_param: oam_net_name }
 308        fixed_ips: [{ "ip_address": { get_param: dns_oam_ip_0 }}]
 309        security_groups: [{ get_param: dns_sec_grp_id }]
 310
 311
 312 *Examples: Base Module creates an internal network*
 313
 314 A VNF has a base module, named base\_module.yaml, that creates an
 315 internal network. An incremental module, named incremental\_module.yaml,
 316 will create a VM that will connect to the internal network. The base
 317 module defines a parameter in the out section named int\_oam\_net\_id.
 318 int\_oam\_net\_id is defined as a parameter in the incremental module.
 319 ONAP captures the UUID value of int\_oam\_net\_id from the base module
 320 output statement and provides the value to the incremental module.
 321
 322 Note that the example below is not a complete Heat Orchestration
 323 Template. The {network-role} has been defined as oam to represent an oam
 324 network and the {vm-type} has been defined as lb for load balancer.
 325
 326 base.yaml
 327
 328 .. code-block:: yaml
 329
 330  heat_template_version: 2013-05-23
 331
 332  resources:
 333     int_oam_network:
 334        type: OS::Neutron::Network
 335        properties:
 336           name: {… }
 337           . . .
 338  outputs:
 339     int_oam_net_id:
 340        value: {get_resource: int_oam_network }
 341
 342
 343 incremental.yaml
 344
 345 .. code-block:: yaml
 346
 347  heat_template_version: 2013-05-23
 348
 349  parameters:
 350     int_oam_net_id:
 351        type: string
 352        description: ID of shared private network from Base template
 353     lb_name_0:
 354        type: string
 355        description: name for the add-on VM instance
 356
 357  Resources:
 358     lb_server:
 359        type: OS::Nova::Server
 360        properties:
 361           name: {get_param: lb_name_0}
 362           networks:
 363              - port: { get_resource: lb_port }
 364           . . .
 365
 366     lb_port:
 367        type: OS::Neutron::Port
 368        properties:
 369           network_id: { get_param: int_oam_net_id }
 370  ...
 371