docs/Chapter4/Modularity.rst

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