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