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 ONAP VNF Modularity Overview
  14 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  15
  16
  17 .. req::
  18     :id: R-69663
  19     :target: VNF
  20     :keyword: MAY
  21
  22     A VNF **MAY** be composed from one or more Heat Orchestration
  23     Templates, each of which represents a subset of the overall VNF.
  24
  25 The Heat Orchestration Templates can be thought of a components or modules of
  26 the VNF and are referred to as *VNF Modules*. During orchestration,
  27 these modules are
  28 deployed incrementally to create the complete VNF.
  29
  30
  31 .. req::
  32     :id: R-33132
  33     :target: VNF
  34     :keyword: MAY
  35
  36     A VNF's Heat Orchestration Template **MAY** be
  37      1.) Base Module Heat Orchestration Template (also referred to as a
  38          Base Module),
  39      2.) Incremental Module Heat Orchestration Template (referred to as
  40          an Incremental Module), or
  41      3.) a Cinder Volume Module Heat Orchestration Template (referred to as
  42          Cinder Volume  Module).
  43
  44 .. req::
  45     :id: R-37028
  46     :target: VNF
  47     :keyword: MUST
  48
  49     A VNF **MUST** be composed of one Base Module
  50
  51 .. req::
  52     :id: R-13196
  53     :target: VNF
  54     :keyword: MAY
  55
  56     A VNF **MAY** be composed of zero to many Incremental Modules.
  57
  58 .. req::
  59     :id: R-20974
  60     :target: VNF
  61     :keyword: MUST
  62
  63     At orchestration time, the VNF's Base Module **MUST**
  64     be deployed first, prior to any incremental modules.
  65
  66 .. req::
  67     :id: R-28980
  68     :target: VNF
  69     :keyword: MAY
  70
  71     A VNF's incremental module **MAY** be used for initial VNF deployment only.
  72
  73 .. req::
  74     :id: R-86926
  75     :target: VNF
  76     :keyword: MAY
  77
  78     A VNF's incremental module **MAY** be used for scale out only.
  79
  80 A VNF's Incremental Module that is used for scale out is deployed sometime
  81 after initial VNF deployment to add capacity.
  82
  83
  84 .. req::
  85     :id: R-91497
  86     :target: VNF
  87     :keyword: MAY
  88
  89     A VNF's incremental module **MAY** be used for both deployment and
  90     scale out.
  91
  92 .. req::
  93     :id: R-68122
  94     :target: VNF
  95     :keyword: MAY
  96
  97     A VNF's incremental module **MAY** be deployed more than once,
  98     either during initial VNF deployment and/or scale out.
  99
 100 .. req::
 101     :id: R-46119
 102     :target: VNF
 103     :keyword: MAY
 104
 105     A VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
 106     **MAY** be defined in a Base Module.
 107
 108 .. req::
 109     :id: R-90748
 110     :target: VNF
 111     :keyword: MAY
 112
 113     A VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
 114     **MAY** be defined in an Incremental Module.
 115
 116 .. req::
 117     :id: R-03251
 118     :target: VNF
 119     :keyword: MAY
 120
 121     A VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
 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 failover activity).
 129
 130 .. req::
 131     :id: R-11200
 132     :target: VNF
 133     :keyword: MUST
 134     :validation_mode: static
 135
 136     A VNF's Cinder Volume Module, when it exists, **MUST** be 1:1
 137     with a Base module or Incremental module.
 138
 139 It is strongly recommended that Cinder Volumes be created in a Cinder Volume
 140 Module.
 141
 142 .. req::
 143     :id: R-38474
 144     :target: VNF
 145     :keyword: MUST
 146     :validation_mode: static
 147
 148     The VNF **MUST** have a corresponding environment file for a Base Module.
 149
 150 .. req::
 151     :id: R-81725
 152     :target: VNF
 153     :keyword: MUST
 154     :validation_mode: static
 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
 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
 264     A VNF Heat Orchestration Template's Base Module file name **MUST** include
 265     case insensitive 'base' in the filename and
 266     **MUST** match one of the following four
 267     formats:
 268
 269      1.) ``base_<text>.y[a]ml``
 270
 271      2.) ``<text>_base.y[a]ml``
 272
 273      3.) ``base.y[a]ml``
 274
 275      4.) ``<text>_base_<text>``.y[a]ml
 276
 277     where ``<text>`` **MUST** contain only alphanumeric characters and
 278     underscores '_' and **MUST NOT** contain the case insensitive word ``base``.
 279
 280 .. req::
 281     :id: R-91342
 282     :target: VNF
 283     :keyword: MUST
 284     :validation_mode: static
 285
 286     A VNF Heat Orchestration Template's Base Module's Environment File
 287     **MUST** be named identical to the VNF Heat Orchestration Template's
 288     Base Module with ``.y[a]ml`` replaced with ``.env``.
 289
 290 Incremental Modules
 291 ~~~~~~~~~~~~~~~~~~~
 292
 293
 294 .. req::
 295     :id: R-87247
 296     :target: VNF
 297     :keyword: MUST
 298     :validation_mode: static
 299
 300     VNF Heat Orchestration Template's Incremental Module file name
 301     **MUST** contain only alphanumeric characters and underscores
 302     '_' and **MUST NOT** contain the case insensitive word ``base``.
 303
 304 .. req::
 305     :id: R-94509
 306     :target: VNF
 307     :keyword: MUST
 308     :validation_mode: static
 309
 310     A VNF Heat Orchestration Template's Incremental Module's Environment File
 311     **MUST** be named identical to the VNF Heat Orchestration Template's
 312     Incremental Module with ``.y[a]ml`` replaced with ``.env``.
 313
 314 To clearly identify the incremental module, it is recommended to use the
 315 following naming options for modules:
 316
 317  -  ``module_<text>.y[a]ml``
 318
 319  -  ``<text>_module.y[a]ml``
 320
 321  -  ``module.y[a]ml``
 322
 323  -  ``<text>_module_<text>.y[a]ml``
 324
 325 Cinder Volume Modules
 326 ~~~~~~~~~~~~~~~~~~~~~
 327
 328
 329 .. req::
 330     :id: R-82732
 331     :target: VNF
 332     :keyword: MUST
 333     :validation_mode: static
 334
 335     A VNF Heat Orchestration Template's Cinder Volume Module **MUST**
 336     be named identical to the base or incremental module it is supporting with
 337     ``_volume`` appended.
 338
 339 .. req::
 340     :id: R-31141
 341     :target: VNF
 342     :keyword: MUST
 343     :validation_mode: static
 344
 345     VNF Heat Orchestration Template's Cinder Volume Module's Environment File
 346     **MUST** be named identical to the VNF Heat Orchestration Template's
 347     Cinder Volume Module with ``.y[a]ml`` replaced with ``.env``.
 348
 349 Nested Heat file
 350 ~~~~~~~~~~~~~~~~
 351
 352
 353 .. req::
 354     :id: R-76057
 355     :target: VNF
 356     :keyword: MUST
 357     :validation_mode: static
 358
 359     VNF Heat Orchestration Template's Nested YAML file name **MUST** contain
 360     only alphanumeric characters and underscores '_' and
 361     **MUST NOT** contain the case insensitive word ``base``.
 362
 363 .. req::
 364     :id: R-70276
 365     :target: VNF
 366     :keyword: MUST NOT
 367     :validation_mode: static
 368
 369     A VNF HEAT's Orchestration Nested Template's YAML file name **MUST NOT**
 370     be in the format ``{vm-type}.y[a]ml`` where ``{vm-type}`` is defined
 371     in the Heat Orchestration Template.
 372
 373 Examples include
 374
 375  -  ``<text>.y[a]ml``
 376
 377  -  ``nest_<text>.y[a]ml``
 378
 379  -  ``<text>_nest.y[a]ml``
 380
 381  -  ``nest.y[a]ml``
 382
 383  -  ``<text>_nest_<text>.y[a]ml``
 384
 385 VNF Heat Orchestration Template's Nested YAML file does not have a
 386 corresponding environment files, per OpenStack specifications.
 387
 388 .. _Output Parameters:
 389
 390 Output Parameters
 391 ^^^^^^^^^^^^^^^^^^^^^^
 392
 393 The output parameters are parameters defined in the output section of a
 394 Heat Orchestration Template. The ONAP output parameters are subdivided
 395 into three categories:
 396
 397 1. ONAP Base Module Output Parameters
 398
 399 2. ONAP Volume Module Output Parameters
 400
 401 3. ONAP Predefined Output Parameters.
 402
 403 ONAP Base Module Output Parameters
 404 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 405
 406 ONAP Base Module Output Parameters are declared in the ``outputs:`` section
 407 of the VNF's Heat Orchestration Template's Base Module. A Base Module Output
 408 Parameter is available as an input parameter (i.e., declared in
 409 the ``parameters:`` section) to all Incremental Modules in the VNF.
 410
 411 A Base Module Output Parameter may be used as an input parameter in any
 412 incremental module in the VNF.  Note that the parameter is not available to
 413 other VNFs.
 414
 415
 416 .. req::
 417     :id: R-52753
 418     :target: VNF
 419     :keyword: MUST
 420     :validation_mode: static
 421
 422     VNF's Heat Orchestration Template's Base Module's output parameter's
 423     name and type **MUST** match the VNF's Heat Orchestration Template's
 424     incremental Module's name and type unless the output parameter is of
 425     type ``comma_delimited_list``, then the corresponding input parameter
 426     **MUST** be declared as type ``json``.
 427
 428 If the Output parameter has a comma_delimited_list value (e.g., a collection
 429 of UUIDs from a Resource Group), then the corresponding input parameter must
 430 be declared as type ``json`` and not a ``comma_delimited_list``,
 431 which is actually a string value with embedded commas.
 432
 433
 434 .. req::
 435     :id: R-22608
 436     :target: VNF
 437     :keyword: MUST NOT
 438     :validation_mode: static
 439
 440     When a VNF's Heat Orchestration Template's Base Module's output
 441     parameter is declared as an input parameter in an Incremental Module,
 442     the parameter attribute ``constraints:`` **MUST NOT** be declared.
 443
 444 Additional details on ONAP Base Module Output Parameters are provided in
 445 :ref:`ONAP Output Parameter Names` and ONAP VNF Modularity.
 446
 447 ONAP Volume Module Output Parameters
 448 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 449
 450
 451 .. req::
 452     :id: R-89913
 453     :target: VNF
 454     :keyword: MUST
 455     :validation_mode: static
 456
 457     A VNF's Heat Orchestration Template's Cinder Volume Module Output
 458     Parameter(s)
 459     **MUST** include the
 460     UUID(s) of the Cinder Volumes created in template,
 461     while others **MAY** be included.
 462
 463 A VNF's Heat Orchestration Template's Cinder Volume Module Output Parameter(s)
 464 are only available for the module (base or incremental) that the volume
 465 template is associated with.
 466
 467
 468 .. req::
 469     :id: R-07443
 470     :target: VNF
 471     :keyword: MUST
 472     :validation_mode: static
 473
 474     A VNF's Heat Orchestration Templates' Cinder Volume Module Output
 475     Parameter's name and type **MUST** match the input parameter name and type
 476     in the corresponding Base Module or Incremental Module unless the Output
 477     Parameter is of the type ``comma_delimited_list``, then the corresponding
 478     input parameter **MUST** be declared as type ``json``.
 479
 480 If the Output parameter has a comma_delimited_list value (e.g., a collection
 481 of UUIDs from a Resource Group), then the corresponding input parameter must
 482 be declared as type json and not a comma_delimited_list, which is actually
 483 a string value with embedded commas.
 484
 485
 486 .. req::
 487     :id: R-20547
 488     :target: VNF
 489     :keyword: MUST NOT
 490     :validation_mode: static
 491
 492     When an ONAP Volume Module Output Parameter is declared as an input
 493     parameter in a base or an incremental module Heat Orchestration
 494     Template, parameter constraints **MUST NOT** be declared.
 495
 496 Additional details on ONAP Base Module Output Parameters are provided in
 497 :ref:`ONAP Output Parameter Names` and :ref:`ONAP Heat Cinder Volumes`.
 498
 499 ONAP Predefined Output Parameters
 500 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 501
 502 ONAP will look for a small set of pre-defined Heat output parameters to
 503 capture resource attributes for inventory in ONAP. These output parameters
 504 are optional and currently only two parameters are supported. These output
 505 parameters are optional and are specified in
 506 :ref:`OAM Management IP Addresses`.
 507
 508 Support of heat stack update
 509 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 510
 511 ONAP does not support the use of heat stack-update command for scaling
 512 (growth/de-growth).
 513
 514
 515 .. req::
 516     :id: R-39349
 517     :target: VNF
 518     :keyword: MUST NOT
 519     :validation_mode: static
 520
 521     A VNF Heat Orchestration Template **MUST NOT** be designed to utilize the
 522     OpenStack ``heat stack-update`` command for scaling (growth/de-growth).
 523
 524 .. req::
 525     :id: R-43413
 526     :target: VNF
 527     :keyword: MUST
 528     :validation_mode: static
 529
 530     A VNF **MUST** utilize a modular Heat Orchestration Template design to
 531     support scaling (growth/de-growth).
 532
 533 It is important to note that ONAP only supports heat stack-update for
 534 image upgrades.
 535
 536 Scope of a Heat Orchestration Template
 537 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 538
 539
 540 .. req::
 541     :id: R-59482
 542     :target: VNF
 543     :keyword: MUST NOT
 544     :validation_mode: static
 545
 546     A VNF's Heat Orchestration Template **MUST NOT** be VNF instance
 547     specific or cloud site specific.
 548
 549 ONAP provides the instance specific parameter values to the Heat
 550 Orchestration Template at orchestration time.
 551
 552
 553 .. req::
 554     :id: R-01896
 555     :target: VNF
 556     :keyword: MUST
 557     :validation_mode: static
 558
 559     A VNF's Heat Orchestration Template's parameter values that are constant
 560     across all deployments **MUST** be declared in a Heat Orchestration
 561     Template Environment File.
 562
 563