docs/Chapter5/Heat/ONAP Heat Orchestration Templates Overview.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 Orchestration Templates Overview:
   6
   7 ONAP Heat Orchestration Templates Overview
   8 -----------------------------------------------
   9
  10 ONAP supports a modular Heat Orchestration Template design pattern,
  11 referred to as *VNF Modularity.*
  12
  13 .. _heat_onap_vnf_modularity_overview:
  14
  15 ONAP VNF Modularity Overview
  16 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  17
  18
  19 .. req::
  20     :id: R-69663
  21     :target: VNF
  22     :keyword: MAY
  23
  24     A VNF **MAY** be composed from one or more Heat Orchestration
  25     Templates, each of which represents a subset of the overall VNF.
  26
  27 The Heat Orchestration Templates can be thought of a components or modules of
  28 the VNF and are referred to as *VNF Modules*. During orchestration,
  29 these modules are
  30 deployed incrementally to create the complete VNF.
  31
  32
  33 .. req::
  34     :id: R-33132
  35     :target: VNF
  36     :keyword: MAY
  37     :updated: casablanca
  38
  39     A VNF's Heat Orchestration Template **MAY** be
  40      1.) Base Module Heat Orchestration Template (also referred to as a
  41          Base Module),
  42      2.) Incremental Module Heat Orchestration Template (referred to as
  43          an Incremental Module), or
  44      3.) a Cinder Volume Module Heat Orchestration Template (referred to as
  45          Cinder Volume  Module).
  46
  47 .. req::
  48     :id: R-37028
  49     :target: VNF
  50     :keyword: MUST
  51     :updated: casablanca
  52     :validation_mode: static
  53
  54     A VNF **MUST** be composed of one Base Module
  55
  56 .. req::
  57     :id: R-13196
  58     :target: VNF
  59     :keyword: MAY
  60
  61     A VNF **MAY** be composed of zero to many Incremental Modules.
  62
  63 .. req::
  64     :id: R-28980
  65     :target: VNF
  66     :keyword: MAY
  67
  68     A VNF's incremental module **MAY** be used for initial VNF deployment only.
  69
  70 .. req::
  71     :id: R-86926
  72     :target: VNF
  73     :keyword: MAY
  74
  75     A VNF's incremental module **MAY** be used for scale out only.
  76
  77 A VNF's Incremental Module that is used for scale out is deployed sometime
  78 after initial VNF deployment to add capacity.
  79
  80
  81 .. req::
  82     :id: R-91497
  83     :target: VNF
  84     :keyword: MAY
  85
  86     A VNF's incremental module **MAY** be used for both deployment and
  87     scale out.
  88
  89 .. req::
  90     :id: R-68122
  91     :target: VNF
  92     :keyword: MAY
  93
  94     A VNF's incremental module **MAY** be deployed more than once,
  95     either during initial VNF deployment and/or scale out.
  96
  97 .. req::
  98     :id: R-46119
  99     :target: VNF
 100     :keyword: MAY
 101
 102     A VNF's Heat Orchestration Template's Resource ``OS::Heat::CinderVolume``
 103     **MAY** be defined in a Base Module.
 104
 105 .. req::
 106     :id: R-90748
 107     :target: VNF
 108     :keyword: MAY
 109
 110     A VNF's Heat Orchestration Template's Resource ``OS::Heat::CinderVolume``
 111     **MAY** be defined in an Incremental Module.
 112
 113 .. req::
 114     :id: R-03251
 115     :target: VNF
 116     :keyword: MAY
 117
 118     A VNF's Heat Orchestration Template's Resource ``OS::Heat::CinderVolume``
 119     **MAY** be defined in a Cinder Volume Module.
 120
 121 ONAP also supports the concept of an optional, independently deployed Cinder
 122 volume via a separate Heat Orchestration Templates, referred to as a Cinder
 123 Volume Module. This allows the volume to persist after a Virtual Machine
 124 (VM) (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused
 125 on another instance (e.g., during a fail over activity).
 126
 127 .. req::
 128     :id: R-11200
 129     :target: VNF
 130     :keyword: MUST
 131     :validation_mode: static
 132     :updated: casablanca
 133
 134     A VNF's Cinder Volume Module, when it exists, **MUST** be 1:1
 135     with a Base module or Incremental module.
 136
 137 It is strongly recommended that Cinder Volumes be created in a Cinder Volume
 138 Module.
 139
 140 .. req::
 141     :id: R-38474
 142     :target: VNF
 143     :keyword: MUST
 144     :validation_mode: static
 145     :updated: casablanca
 146
 147     A VNF's Base Module **MUST** have a corresponding Environment File.
 148
 149 .. req::
 150     :id: R-81725
 151     :target: VNF
 152     :keyword: MUST
 153     :validation_mode: static
 154     :updated: casablanca
 155
 156     A VNF's Incremental Module **MUST** have a corresponding Environment File
 157
 158 .. req::
 159     :id: R-53433
 160     :target: VNF
 161     :keyword: MUST
 162     :validation_mode: static
 163     :updated: casablanca
 164
 165     A VNF's Cinder Volume Module **MUST** have a corresponding environment file
 166
 167 These concepts will be described in more detail throughout the document.
 168 This overview is provided to set the stage and help clarify the concepts
 169 that will be introduced.
 170
 171 Nested Heat Orchestration Templates Overview
 172 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 173
 174 ONAP supports nested Heat Orchestration Templates per OpenStack
 175 specifications.
 176
 177
 178 .. req::
 179     :id: R-36582
 180     :target: VNF
 181     :keyword: MAY
 182
 183     A VNF's Base Module **MAY** utilize nested heat.
 184
 185 .. req::
 186     :id: R-56721
 187     :target: VNF
 188     :keyword: MAY
 189
 190     A VNF's Incremental Module **MAY** utilize nested heat.
 191
 192 .. req::
 193     :id: R-30395
 194     :target: VNF
 195     :keyword: MAY
 196
 197     A VNF's Cinder Volume Module **MAY** utilize nested heat.
 198
 199 Nested templates may be suitable for larger VNFs that contain many
 200 repeated instances of the same VM type(s). A common usage pattern is to
 201 create a nested template for each VM type along with its supporting
 202 resources. The Heat Orchestration Template may then reference these
 203 nested templates either statically (by repeated definition) or
 204 dynamically (via OS::Heat::ResourceGroup).
 205
 206 See :ref:`Nested Heat Templates` for additional details.
 207
 208 ONAP Heat Orchestration Template Filenames
 209 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 210
 211 In order to enable ONAP to understand the relationship between Heat
 212 files, the following Heat file naming convention must be utilized.
 213
 214 In the examples below, <text> represents any alphanumeric string that
 215 must not contain any special characters and must not contain the word
 216 "base".
 217
 218
 219 .. req::
 220     :id: R-87485
 221     :target: VNF
 222     :keyword: MUST
 223     :validation_mode: static
 224
 225     A VNF's Heat Orchestration Template's file extension **MUST**
 226     be in the lower case format ``.yaml`` or ``.yml``.
 227
 228 .. req::
 229     :id: R-56438
 230     :target: VNF
 231     :keyword: MUST
 232     :validation_mode: static
 233
 234     A VNF's Heat Orchestration Template's Nested YAML file extension **MUST**
 235     be in the lower case format ``.yaml`` or ``.yml``.
 236
 237 .. req::
 238     :id: R-74304
 239     :target: VNF
 240     :keyword: MUST
 241     :validation_mode: static
 242
 243     A VNF's Heat Orchestration Template's Environment file extension **MUST**
 244     be in the lower case format ``.env``.
 245
 246 .. req::
 247     :id: R-99646
 248     :target: VNF
 249     :keyword: MUST
 250     :validation_mode: static
 251
 252     A VNF's YAML files (i.e, Heat Orchestration Template files and
 253     Nested files) **MUST** have a unique name in the scope of the VNF.
 254
 255 Base Modules
 256 ~~~~~~~~~~~~
 257
 258
 259 .. req::
 260     :id: R-81339
 261     :target: VNF
 262     :keyword: MUST
 263     :validation_mode: static
 264     :updated: casablanca
 265
 266     A VNF Heat Orchestration Template's Base Module file name **MUST** include
 267     case insensitive 'base' in the filename and
 268     **MUST** match one of the following four
 269     formats:
 270
 271      1.) ``base_<text>.y[a]ml``
 272
 273      2.) ``<text>_base.y[a]ml``
 274
 275      3.) ``base.y[a]ml``
 276
 277      4.) ``<text>_base_<text>``.y[a]ml
 278
 279     where ``<text>`` **MUST** contain only alphanumeric characters and
 280     underscores '_' and **MUST NOT** contain the case insensitive word ``base``.
 281
 282 .. req::
 283     :id: R-91342
 284     :target: VNF
 285     :keyword: MUST
 286     :validation_mode: static
 287
 288     A VNF Heat Orchestration Template's Base Module's Environment File
 289     **MUST** be named identical to the VNF Heat Orchestration Template's
 290     Base Module with ``.y[a]ml`` replaced with ``.env``.
 291
 292 Incremental Modules
 293 ~~~~~~~~~~~~~~~~~~~
 294
 295
 296 .. req::
 297     :id: R-87247
 298     :target: VNF
 299     :keyword: MUST
 300     :validation_mode: static
 301     :updated: casablanca
 302
 303     VNF Heat Orchestration Template's Incremental Module file name
 304     **MUST** contain only alphanumeric characters and underscores
 305     '_' and **MUST NOT** contain the case insensitive word ``base``.
 306
 307 .. req::
 308     :id: R-94509
 309     :target: VNF
 310     :keyword: MUST
 311     :validation_mode: static
 312
 313     A VNF Heat Orchestration Template's Incremental Module's Environment File
 314     **MUST** be named identical to the VNF Heat Orchestration Template's
 315     Incremental Module with ``.y[a]ml`` replaced with ``.env``.
 316
 317 To clearly identify the incremental module, it is recommended to use the
 318 following naming options for modules:
 319
 320  -  ``module_<text>.y[a]ml``
 321
 322  -  ``<text>_module.y[a]ml``
 323
 324  -  ``module.y[a]ml``
 325
 326  -  ``<text>_module_<text>.y[a]ml``
 327
 328 Cinder Volume Modules
 329 ~~~~~~~~~~~~~~~~~~~~~
 330
 331
 332 .. req::
 333     :id: R-82732
 334     :target: VNF
 335     :keyword: MUST
 336     :validation_mode: static
 337     :updated: casablanca
 338
 339     A VNF Heat Orchestration Template's Cinder Volume Module **MUST**
 340     be named identical to the base or incremental module it is supporting with
 341     ``_volume`` appended.
 342
 343
 344 .. req::
 345     :id: R-589037
 346     :keyword: MUST
 347     :validation_mode: static
 348     :introduced: dublin
 349
 350     A VNF Heat Orchestration Template's Cinder Volume Module resources section
 351     **MUST** only be defined using one of the following:
 352
 353     * one of more ``OS::Cinder::Volume`` resources
 354     * one or more ``OS::Heat::ResourceGroup`` resources that call a nested YAML
 355       file that contains only ``OS::Cinder::Volume`` resources
 356     * a resource that calls a nested YAML file (static nesting) that contains
 357       only ``OS::Cinder::Volume`` resources
 358
 359 .. req::
 360     :id: R-31141
 361     :target: VNF
 362     :keyword: MUST
 363     :validation_mode: static
 364     :updated: casablanca
 365
 366     VNF Heat Orchestration Template's Cinder Volume Module's Environment File
 367     **MUST** be named identical to the VNF Heat Orchestration Template's
 368     Cinder Volume Module with ``.y[a]ml`` replaced with ``.env``.
 369
 370 Nested Heat file
 371 ~~~~~~~~~~~~~~~~
 372
 373
 374 .. req::
 375     :id: R-76057
 376     :target: VNF
 377     :keyword: MUST
 378     :validation_mode: static
 379     :updated: casablanca
 380
 381     VNF Heat Orchestration Template's Nested YAML file name **MUST** contain
 382     only alphanumeric characters and underscores '_' and
 383     **MUST NOT** contain the case insensitive word ``base``.
 384
 385 .. req::
 386     :id: R-70276
 387     :target: VNF
 388     :keyword: MUST NOT
 389     :validation_mode: static
 390
 391     A VNF HEAT's Orchestration Nested Template's YAML file name **MUST NOT**
 392     be in the format ``{vm-type}.y[a]ml`` where ``{vm-type}`` is defined
 393     in the Heat Orchestration Template.
 394
 395 Examples include
 396
 397  -  ``<text>.y[a]ml``
 398
 399  -  ``nest_<text>.y[a]ml``
 400
 401  -  ``<text>_nest.y[a]ml``
 402
 403  -  ``nest.y[a]ml``
 404
 405  -  ``<text>_nest_<text>.y[a]ml``
 406
 407 VNF Heat Orchestration Template's Nested YAML file does not have a
 408 corresponding environment files, per OpenStack specifications.
 409
 410 .. _Output Parameters:
 411
 412 Output Parameters
 413 ^^^^^^^^^^^^^^^^^^^^^^
 414
 415 The output parameters are parameters defined in the output section of a
 416 Heat Orchestration Template. The ONAP output parameters are subdivided
 417 into three categories:
 418
 419 1. ONAP Base Module Output Parameters
 420
 421 2. ONAP Volume Module Output Parameters
 422
 423 3. ONAP Predefined Output Parameters.
 424
 425 ONAP Base Module Output Parameters
 426 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 427
 428 ONAP Base Module Output Parameters are declared in the ``outputs:`` section
 429 of the VNF's Heat Orchestration Template's Base Module. A Base Module Output
 430 Parameter is available as an input parameter (i.e., declared in
 431 the ``parameters:`` section) to all Incremental Modules in the VNF.
 432
 433 A Base Module Output Parameter may be used as an input parameter in any
 434 incremental module in the VNF.  Note that the parameter is not available to
 435 other VNFs.
 436
 437
 438 .. req::
 439     :id: R-52753
 440     :target: VNF
 441     :keyword: MUST
 442     :validation_mode: static
 443
 444     VNF's Heat Orchestration Template's Base Module's output parameter's
 445     name and type **MUST** match the VNF's Heat Orchestration Template's
 446     incremental Module's name and type.
 447
 448 .. req::
 449     :id: R-22608
 450     :target: VNF
 451     :keyword: SHOULD NOT
 452     :validation_mode: static
 453
 454     When a VNF's Heat Orchestration Template's Base Module's output
 455     parameter is declared as an input parameter in an Incremental Module,
 456     the parameter attribute ``constraints:`` **SHOULD NOT** be declared.
 457
 458 Additional details on ONAP Base Module Output Parameters are provided in
 459 :ref:`ONAP Output Parameter Names` and ONAP VNF Modularity.
 460
 461 ONAP Volume Module Output Parameters
 462 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 463
 464
 465 .. req::
 466     :id: R-89913
 467     :target: VNF
 468     :keyword: MUST
 469     :validation_mode: static
 470     :updated: casablanca
 471
 472     A VNF's Heat Orchestration Template's Cinder Volume Module Output
 473     Parameter(s)
 474     **MUST** include the
 475     UUID(s) of the Cinder Volumes created in template.
 476
 477 A VNF's Heat Orchestration Template's Cinder Volume Module Output Parameter(s)
 478 are only available for the module (base or incremental) that the volume
 479 template is associated with.
 480
 481
 482 .. req::
 483     :id: R-07443
 484     :target: VNF
 485     :keyword: MUST
 486     :validation_mode: static
 487     :updated: casablanca
 488
 489     A VNF's Heat Orchestration Templates' Cinder Volume Module Output
 490     Parameter's name and type **MUST** match the input parameter name and type
 491     in the corresponding Base Module or Incremental Module.
 492
 493 .. req::
 494     :id: R-20547
 495     :target: VNF
 496     :keyword: SHOULD NOT
 497     :validation_mode: static
 498
 499     When an ONAP Volume Module Output Parameter is declared as an input
 500     parameter in a base or an incremental module Heat Orchestration
 501     Template, parameter constraints **SHOULD NOT** be declared.
 502
 503 Additional details on ONAP Base Module Output Parameters are provided in
 504 :ref:`ONAP Output Parameter Names` and :ref:`ONAP Heat Cinder Volumes`.
 505
 506 ONAP Predefined Output Parameters
 507 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 508
 509 ONAP will look for a small set of pre-defined Heat output parameters to
 510 capture resource attributes for inventory in ONAP. These output parameters
 511 are optional and currently only two parameters are supported. These output
 512 parameters are optional and are specified in
 513 :ref:`OAM Management IP Addresses`.
 514
 515 Support of heat stack update
 516 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 517
 518 ONAP does not support the use of heat stack-update command for scaling
 519 (growth/de-growth).
 520
 521
 522 .. req::
 523     :id: R-39349
 524     :target: VNF
 525     :keyword: MUST NOT
 526     :validation_mode: static
 527
 528     A VNF Heat Orchestration Template **MUST NOT** be designed to utilize the
 529     OpenStack ``heat stack-update`` command for scaling (growth/de-growth).
 530
 531 .. req::
 532     :id: R-43413
 533     :target: VNF
 534     :keyword: MUST
 535     :validation_mode: none
 536
 537     A VNF **MUST** utilize a modular Heat Orchestration Template design to
 538     support scaling (growth/de-growth).
 539
 540 It is important to note that ONAP only supports heat stack-update for
 541 image upgrades.
 542
 543 Scope of a Heat Orchestration Template
 544 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 545
 546
 547 .. req::
 548     :id: R-59482
 549     :target: VNF
 550     :keyword: MUST NOT
 551     :validation_mode: none
 552
 553     A VNF's Heat Orchestration Template **MUST NOT** be VNF instance
 554     specific or cloud site specific.
 555
 556 ONAP provides the instance specific parameter values to the Heat
 557 Orchestration Template at orchestration time.
 558
 559
 560 .. req::
 561     :id: R-01896
 562     :target: VNF
 563     :keyword: MUST
 564     :validation_mode: static
 565
 566     A VNF's Heat Orchestration Template's parameter values that are constant
 567     across all deployments **MUST** be declared in a Heat Orchestration
 568     Template Environment File.
 569
 570 ONAP VNF On-Boarding
 571 ^^^^^^^^^^^^^^^^^^^^
 572
 573 .. req::
 574     :id: R-511776
 575     :keyword: MUST
 576     :validation_mode: static
 577
 578     When a VNF's Heat Orchestration Template is ready
 579     to be on-boarded to ONAP,
 580     all files composing the VNF Heat Orchestration Template
 581     **MUST** be placed in a flat (i.e., non-hierarchical) directory and
 582     archived using ZIP.  The resulting ZIP file is uploaded into ONAP.
 583
 584 The VNF's Heat Orchestration Template's ZIP file must include
 585 the base module YAML file (R-37028) and corresponding environment file
 586 (R-38474).
 587
 588 The VNF's Heat Orchestration Template's ZIP file **MAY** include
 589
 590 * One or more incremental module YAML files (R-13196) and corresponding
 591   environment files (R-81725).
 592 * One or more volume module YAML files (R-03251) and corresponding
 593   environment files (R-53433).
 594 * One or more nested YAML files (R-36582, R-56721, R-30395).
 595 * One or more files that are retrieved via the intrinsic function
 596   ``get_file``.  The ``get_file`` function returns the content of a file
 597   into a Heat Orchestration Template. It is generally used as a file
 598   inclusion mechanism for files containing scripts or configuration files.
 599   (See Section 9.3)
 600
 601 .. req::
 602     :id: R-348813
 603     :keyword: MUST
 604     :validation_mode: static
 605
 606     The VNF's Heat Orchestration Template's ZIP file **MUST NOT** include
 607     a binary image file.
 608