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