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
  38     A VNF's Heat Orchestration Template **MAY** be
  39      1.) Base Module Heat Orchestration Template (also referred to as a
  40          Base Module),
  41      2.) Incremental Module Heat Orchestration Template (referred to as
  42          an Incremental Module), or
  43      3.) a Cinder Volume Module Heat Orchestration Template (referred to as
  44          Cinder Volume  Module).
  45
  46 .. req::
  47     :id: R-37028
  48     :target: VNF
  49     :keyword: MUST
  50
  51     A VNF **MUST** be composed of one Base Module
  52
  53 .. req::
  54     :id: R-13196
  55     :target: VNF
  56     :keyword: MAY
  57
  58     A VNF **MAY** be composed of zero to many Incremental Modules.
  59
  60 .. req::
  61     :id: R-20974
  62     :target: VNF
  63     :keyword: MUST
  64
  65     At orchestration time, the VNF's Base Module **MUST**
  66     be deployed first, prior to any incremental modules.
  67
  68 .. req::
  69     :id: R-28980
  70     :target: VNF
  71     :keyword: MAY
  72
  73     A VNF's incremental module **MAY** be used for initial VNF deployment only.
  74
  75 .. req::
  76     :id: R-86926
  77     :target: VNF
  78     :keyword: MAY
  79
  80     A VNF's incremental module **MAY** be used for scale out only.
  81
  82 A VNF's Incremental Module that is used for scale out is deployed sometime
  83 after initial VNF deployment to add capacity.
  84
  85
  86 .. req::
  87     :id: R-91497
  88     :target: VNF
  89     :keyword: MAY
  90
  91     A VNF's incremental module **MAY** be used for both deployment and
  92     scale out.
  93
  94 .. req::
  95     :id: R-68122
  96     :target: VNF
  97     :keyword: MAY
  98
  99     A VNF's incremental module **MAY** be deployed more than once,
 100     either during initial VNF deployment and/or scale out.
 101
 102 .. req::
 103     :id: R-46119
 104     :target: VNF
 105     :keyword: MAY
 106
 107     A VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
 108     **MAY** be defined in a Base Module.
 109
 110 .. req::
 111     :id: R-90748
 112     :target: VNF
 113     :keyword: MAY
 114
 115     A VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
 116     **MAY** be defined in an Incremental Module.
 117
 118 .. req::
 119     :id: R-03251
 120     :target: VNF
 121     :keyword: MAY
 122
 123     A VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
 124     **MAY** be defined in a Cinder Volume Module.
 125
 126 ONAP also supports the concept of an optional, independently deployed Cinder
 127 volume via a separate Heat Orchestration Templates, referred to as a Cinder
 128 Volume Module. This allows the volume to persist after a Virtual Machine
 129 (VM) (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused
 130 on another instance (e.g., during a failover activity).
 131
 132 .. req::
 133     :id: R-11200
 134     :target: VNF
 135     :keyword: MUST
 136     :validation_mode: static
 137
 138     A VNF's Cinder Volume Module, when it exists, **MUST** be 1:1
 139     with a Base module or Incremental module.
 140
 141 It is strongly recommended that Cinder Volumes be created in a Cinder Volume
 142 Module.
 143
 144 .. req::
 145     :id: R-38474
 146     :target: VNF
 147     :keyword: MUST
 148     :validation_mode: static
 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
 158     A VNF's Incremental Module **MUST** have a corresponding Environment File
 159
 160 .. req::
 161     :id: R-53433
 162     :target: VNF
 163     :keyword: MUST
 164     :validation_mode: static
 165
 166     A VNF's Cinder Volume Module **MUST** have a corresponding environment file
 167
 168 These concepts will be described in more detail throughout the document.
 169 This overview is provided to set the stage and help clarify the concepts
 170 that will be introduced.
 171
 172 Nested Heat Orchestration Templates Overview
 173 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 174
 175 ONAP supports nested Heat Orchestration Templates per OpenStack
 176 specifications.
 177
 178
 179 .. req::
 180     :id: R-36582
 181     :target: VNF
 182     :keyword: MAY
 183
 184     A VNF's Base Module **MAY** utilize nested heat.
 185
 186 .. req::
 187     :id: R-56721
 188     :target: VNF
 189     :keyword: MAY
 190
 191     A VNF's Incremental Module **MAY** utilize nested heat.
 192
 193 .. req::
 194     :id: R-30395
 195     :target: VNF
 196     :keyword: MAY
 197
 198     A VNF's Cinder Volume Module **MAY** utilize nested heat.
 199
 200 Nested templates may be suitable for larger VNFs that contain many
 201 repeated instances of the same VM type(s). A common usage pattern is to
 202 create a nested template for each VM type along with its supporting
 203 resources. The Heat Orchestration Template may then reference these
 204 nested templates either statically (by repeated definition) or
 205 dynamically (via OS::Heat::ResourceGroup).
 206
 207 See :ref:`Nested Heat Templates` for additional details.
 208
 209 ONAP Heat Orchestration Template Filenames
 210 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 211
 212 In order to enable ONAP to understand the relationship between Heat
 213 files, the following Heat file naming convention must be utilized.
 214
 215 In the examples below, <text> represents any alphanumeric string that
 216 must not contain any special characters and must not contain the word
 217 "base".
 218
 219
 220 .. req::
 221     :id: R-87485
 222     :target: VNF
 223     :keyword: MUST
 224     :validation_mode: static
 225
 226     A VNF's Heat Orchestration Template's file extension **MUST**
 227     be in the lower case format ``.yaml`` or ``.yml``.
 228
 229 .. req::
 230     :id: R-56438
 231     :target: VNF
 232     :keyword: MUST
 233     :validation_mode: static
 234
 235     A VNF's Heat Orchestration Template's Nested YAML file extension **MUST**
 236     be in the lower case format ``.yaml`` or ``.yml``.
 237
 238 .. req::
 239     :id: R-74304
 240     :target: VNF
 241     :keyword: MUST
 242     :validation_mode: static
 243
 244     A VNF's Heat Orchestration Template's Environment file extension **MUST**
 245     be in the lower case format ``.env``.
 246
 247 .. req::
 248     :id: R-99646
 249     :target: VNF
 250     :keyword: MUST
 251     :validation_mode: static
 252
 253     A VNF's YAML files (i.e, Heat Orchestration Template files and
 254     Nested files) **MUST** have a unique name in the scope of the VNF.
 255
 256 Base Modules
 257 ~~~~~~~~~~~~
 258
 259
 260 .. req::
 261     :id: R-81339
 262     :target: VNF
 263     :keyword: MUST
 264     :validation_mode: static
 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
 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
 337     A VNF Heat Orchestration Template's Cinder Volume Module **MUST**
 338     be named identical to the base or incremental module it is supporting with
 339     ``_volume`` appended.
 340
 341 .. req::
 342     :id: R-31141
 343     :target: VNF
 344     :keyword: MUST
 345     :validation_mode: static
 346
 347     VNF Heat Orchestration Template's Cinder Volume Module's Environment File
 348     **MUST** be named identical to the VNF Heat Orchestration Template's
 349     Cinder Volume Module with ``.y[a]ml`` replaced with ``.env``.
 350
 351 Nested Heat file
 352 ~~~~~~~~~~~~~~~~
 353
 354
 355 .. req::
 356     :id: R-76057
 357     :target: VNF
 358     :keyword: MUST
 359     :validation_mode: static
 360
 361     VNF Heat Orchestration Template's Nested YAML file name **MUST** contain
 362     only alphanumeric characters and underscores '_' and
 363     **MUST NOT** contain the case insensitive word ``base``.
 364
 365 .. req::
 366     :id: R-70276
 367     :target: VNF
 368     :keyword: MUST NOT
 369     :validation_mode: static
 370
 371     A VNF HEAT's Orchestration Nested Template's YAML file name **MUST NOT**
 372     be in the format ``{vm-type}.y[a]ml`` where ``{vm-type}`` is defined
 373     in the Heat Orchestration Template.
 374
 375 Examples include
 376
 377  -  ``<text>.y[a]ml``
 378
 379  -  ``nest_<text>.y[a]ml``
 380
 381  -  ``<text>_nest.y[a]ml``
 382
 383  -  ``nest.y[a]ml``
 384
 385  -  ``<text>_nest_<text>.y[a]ml``
 386
 387 VNF Heat Orchestration Template's Nested YAML file does not have a
 388 corresponding environment files, per OpenStack specifications.
 389
 390 .. _Output Parameters:
 391
 392 Output Parameters
 393 ^^^^^^^^^^^^^^^^^^^^^^
 394
 395 The output parameters are parameters defined in the output section of a
 396 Heat Orchestration Template. The ONAP output parameters are subdivided
 397 into three categories:
 398
 399 1. ONAP Base Module Output Parameters
 400
 401 2. ONAP Volume Module Output Parameters
 402
 403 3. ONAP Predefined Output Parameters.
 404
 405 ONAP Base Module Output Parameters
 406 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 407
 408 ONAP Base Module Output Parameters are declared in the ``outputs:`` section
 409 of the VNF's Heat Orchestration Template's Base Module. A Base Module Output
 410 Parameter is available as an input parameter (i.e., declared in
 411 the ``parameters:`` section) to all Incremental Modules in the VNF.
 412
 413 A Base Module Output Parameter may be used as an input parameter in any
 414 incremental module in the VNF.  Note that the parameter is not available to
 415 other VNFs.
 416
 417
 418 .. req::
 419     :id: R-52753
 420     :target: VNF
 421     :keyword: MUST
 422     :validation_mode: static
 423
 424     VNF's Heat Orchestration Template's Base Module's output parameter's
 425     name and type **MUST** match the VNF's Heat Orchestration Template's
 426     incremental Module's name and type unless the output parameter is of
 427     type ``comma_delimited_list``, then the corresponding input parameter
 428     **MUST** be declared as type ``json``.
 429
 430 If the Output parameter has a comma_delimited_list value (e.g., a collection
 431 of UUIDs from a Resource Group), then the corresponding input parameter must
 432 be declared as type ``json`` and not a ``comma_delimited_list``,
 433 which is actually a string value with embedded commas.
 434
 435
 436 .. req::
 437     :id: R-22608
 438     :target: VNF
 439     :keyword: MUST NOT
 440     :validation_mode: static
 441
 442     When a VNF's Heat Orchestration Template's Base Module's output
 443     parameter is declared as an input parameter in an Incremental Module,
 444     the parameter attribute ``constraints:`` **MUST NOT** be declared.
 445
 446 Additional details on ONAP Base Module Output Parameters are provided in
 447 :ref:`ONAP Output Parameter Names` and ONAP VNF Modularity.
 448
 449 ONAP Volume Module Output Parameters
 450 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 451
 452
 453 .. req::
 454     :id: R-89913
 455     :target: VNF
 456     :keyword: MUST
 457     :validation_mode: static
 458
 459     A VNF's Heat Orchestration Template's Cinder Volume Module Output
 460     Parameter(s)
 461     **MUST** include the
 462     UUID(s) of the Cinder Volumes created in template,
 463     while others **MAY** be included.
 464
 465 A VNF's Heat Orchestration Template's Cinder Volume Module Output Parameter(s)
 466 are only available for the module (base or incremental) that the volume
 467 template is associated with.
 468
 469
 470 .. req::
 471     :id: R-07443
 472     :target: VNF
 473     :keyword: MUST
 474     :validation_mode: static
 475
 476     A VNF's Heat Orchestration Templates' Cinder Volume Module Output
 477     Parameter's name and type **MUST** match the input parameter name and type
 478     in the corresponding Base Module or Incremental Module unless the Output
 479     Parameter is of the type ``comma_delimited_list``, then the corresponding
 480     input parameter **MUST** be declared as type ``json``.
 481
 482 If the Output parameter has a comma_delimited_list value (e.g., a collection
 483 of UUIDs from a Resource Group), then the corresponding input parameter must
 484 be declared as type json and not a comma_delimited_list, which is actually
 485 a string value with embedded commas.
 486
 487
 488 .. req::
 489     :id: R-20547
 490     :target: VNF
 491     :keyword: MUST NOT
 492     :validation_mode: static
 493
 494     When an ONAP Volume Module Output Parameter is declared as an input
 495     parameter in a base or an incremental module Heat Orchestration
 496     Template, parameter constraints **MUST NOT** be declared.
 497
 498 Additional details on ONAP Base Module Output Parameters are provided in
 499 :ref:`ONAP Output Parameter Names` and :ref:`ONAP Heat Cinder Volumes`.
 500
 501 ONAP Predefined Output Parameters
 502 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 503
 504 ONAP will look for a small set of pre-defined Heat output parameters to
 505 capture resource attributes for inventory in ONAP. These output parameters
 506 are optional and currently only two parameters are supported. These output
 507 parameters are optional and are specified in
 508 :ref:`OAM Management IP Addresses`.
 509
 510 Support of heat stack update
 511 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 512
 513 ONAP does not support the use of heat stack-update command for scaling
 514 (growth/de-growth).
 515
 516
 517 .. req::
 518     :id: R-39349
 519     :target: VNF
 520     :keyword: MUST NOT
 521     :validation_mode: static
 522
 523     A VNF Heat Orchestration Template **MUST NOT** be designed to utilize the
 524     OpenStack ``heat stack-update`` command for scaling (growth/de-growth).
 525
 526 .. req::
 527     :id: R-43413
 528     :target: VNF
 529     :keyword: MUST
 530     :validation_mode: static
 531
 532     A VNF **MUST** utilize a modular Heat Orchestration Template design to
 533     support scaling (growth/de-growth).
 534
 535 It is important to note that ONAP only supports heat stack-update for
 536 image upgrades.
 537
 538 Scope of a Heat Orchestration Template
 539 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 540
 541
 542 .. req::
 543     :id: R-59482
 544     :target: VNF
 545     :keyword: MUST NOT
 546     :validation_mode: static
 547
 548     A VNF's Heat Orchestration Template **MUST NOT** be VNF instance
 549     specific or cloud site specific.
 550
 551 ONAP provides the instance specific parameter values to the Heat
 552 Orchestration Template at orchestration time.
 553
 554
 555 .. req::
 556     :id: R-01896
 557     :target: VNF
 558     :keyword: MUST
 559     :validation_mode: static
 560
 561     A VNF's Heat Orchestration Template's parameter values that are constant
 562     across all deployments **MUST** be declared in a Heat Orchestration
 563     Template Environment File.