docs/Chapter5/Heat/ONAP Heat Orchestration Template Format.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 Template Format:
   6
   7 ONAP Heat Orchestration Template Format
   8 ------------------------------------------------
   9 As stated above, Heat Orchestration templates must be defined in YAML.
  10
  11 .. req::
  12     :id: R-92635
  13     :keyword: MUST
  14     :validation_mode: static
  15     :introduced: casablanca
  16
  17     A VNF's Heat Orchestration Template **MUST** be compliant with the
  18     OpenStack Template Guide.
  19
  20 The OpenStack Template Guide is defined at
  21 https://docs.openstack.org/heat/latest/template_guide/index.html#top.
  22
  23 Heat Orchestration Template Structure
  24 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  25
  26 Heat Orchestration template structure follows the following format, as
  27 defined by OpenStack at
  28 https://docs.openstack.org/developer/heat/template_guide/hot_spec.html.
  29
  30 .. code-block:: yaml
  31
  32   heat_template_version: <date>
  33
  34   description:
  35     # a description of the template
  36
  37   parameter_groups:
  38     # a declaration of input parameter groups and order
  39
  40   parameters:
  41     # declaration of input parameters
  42
  43   resources:
  44     # declaration of template resources
  45
  46   outputs:
  47     # declaration of output parameters
  48
  49   conditions:
  50     # declaration of conditions
  51
  52
  53 heat_template_version
  54 ~~~~~~~~~~~~~~~~~~~~~~~
  55
  56
  57 .. req::
  58     :id: R-27078
  59     :keyword: MUST
  60     :target: VNF
  61     :validation_mode: static
  62
  63     A VNF's Heat Orchestration template **MUST** contain the
  64     section ``heat_template_version:``.
  65
  66 The section ``heat_template_version:`` must be set to a date that
  67 is supported by the OpenStack environment.
  68
  69 description
  70 ~~~~~~~~~~~~
  71
  72
  73 .. req::
  74     :id: R-39402
  75     :keyword: MUST
  76     :validation_mode: static
  77
  78     A VNF's Heat Orchestration Template **MUST** contain the
  79     section ``description:``.
  80
  81 parameter_groups
  82 ~~~~~~~~~~~~~~~~~~~~~~
  83
  84 A VNF Heat Orchestration template may
  85 contain the section "parameter_groups:".
  86
  87 parameters
  88 ~~~~~~~~~~~~~~~~~~~~~~
  89
  90 .. req::
  91     :id: R-35414
  92     :target: VNF
  93     :keyword: MUST
  94     :validation_mode: static
  95
  96     A VNF Heat Orchestration's template **MUST** contain the
  97     section ``parameters:``.
  98
  99
 100 .. code-block:: yaml
 101
 102   parameters:
 103
 104     <param name>:
 105
 106       type: <string | number | json | comma_delimited_list | boolean>
 107
 108       label: <human-readable name of the parameter>
 109
 110       description: <description of the parameter>
 111
 112       default: <default value for parameter>
 113
 114       hidden: <true | false>
 115
 116       constraints:
 117
 118         <parameter constraints>
 119
 120       immutable: <true | false>
 121
 122 This section allows for
 123 specifying input parameters that have to be provided when instantiating
 124 the template. Each parameter is specified in a separate nested block
 125 with the name of the parameters defined in the first line and additional
 126 attributes (e.g., type, label) defined as nested elements.
 127
 128
 129 .. req::
 130     :id: R-90279
 131     :target: VNF
 132     :keyword: MUST
 133     :validation_mode: static
 134     :updated: casablanca
 135
 136     A VNF Heat Orchestration's template's parameter **MUST** be used
 137     in a resource with the exception of the parameters for the
 138     ``OS::Nova::Server`` resource property ``availability_zone``.
 139
 140 .. req::
 141     :id: R-91273
 142     :target: VNF
 143     :keyword: MAY NOT
 144     :updated: casablanca
 145
 146     A VNF Heat Orchestration's template's parameter for the
 147     ``OS::Nova::Server`` resource property ``availability_zone``
 148     **MAY NOT** be used in any ``OS::Nova::Server``.
 149
 150 That is, the parameter associated with the property ``availability_zone``
 151 maybe declared but not used in a resource.
 152
 153 <param name>
 154 +++++++++++++
 155
 156 The name of the parameter.
 157
 158
 159 .. req::
 160     :id: R-25877
 161     :target: VNF
 162     :keyword: MUST
 163     :validation_mode: static
 164
 165     A VNF's Heat Orchestration Template's parameter name
 166     (i.e., <param name>) **MUST** contain only alphanumeric
 167     characters and underscores ('_').
 168
 169 type
 170 ++++
 171
 172
 173 .. req::
 174     :id: R-36772
 175     :target: VNF
 176     :keyword: MUST
 177     :validation_mode: static
 178
 179     A VNF's Heat Orchestration Template's parameter **MUST** include the
 180     attribute ``type:``.
 181
 182 .. req::
 183     :id: R-11441
 184     :target: VNF
 185     :keyword: MUST
 186     :validation_mode: static
 187     :updated: casablanca
 188
 189     A VNF's Heat Orchestration Template's parameter type **MUST** be one of
 190     the following values:
 191
 192     * ``string``
 193     * ``number``
 194     * ``json``
 195     * ``comma_delimited_list``
 196     * ``boolean``
 197
 198 label
 199 ++++++
 200
 201
 202 .. req::
 203     :id: R-32094
 204     :target: VNF
 205     :keyword: MAY
 206
 207     A VNF's Heat Orchestration Template parameter declaration **MAY**
 208     contain the attribute ``label:``.
 209
 210 description
 211 +++++++++++++
 212
 213
 214 .. req::
 215     :id: R-44001
 216     :target: VNF
 217     :keyword: MUST
 218     :validation_mode: static
 219
 220     A VNF's Heat Orchestration Template parameter declaration **MUST**
 221     contain the attribute ``description``.
 222
 223 Note that the parameter attribute ``description:`` is an OpenStack optional
 224 attribute that provides a description of the parameter.
 225 ONAP implementation requires this attribute.
 226
 227 default
 228 ++++++++
 229
 230
 231 .. req::
 232     :id: R-90526
 233     :target: VNF
 234     :keyword: MUST
 235     :validation_mode: static
 236
 237     A VNF Heat Orchestration Template parameter declaration **MUST NOT**
 238     contain the ``default`` attribute.
 239
 240 .. req::
 241     :id: R-26124
 242     :target: VNF
 243     :keyword: MUST
 244     :validation_mode: static
 245     :updated: casablanca
 246
 247     If a VNF Heat Orchestration Template parameter has a default value,
 248     it **MUST** be enumerated in the environment file.
 249
 250 Note that the parameter attribute ``default:`` is an OpenStack optional
 251 attribute that declares the default value of the parameter.
 252 ONAP implementation prohibits the use of this attribute.
 253
 254 hidden
 255 +++++++
 256
 257
 258 .. req::
 259     :id: R-32557
 260     :target: VNF
 261     :keyword: MAY
 262
 263     A VNF's Heat Orchestration Template parameter declaration **MAY**
 264     contain the attribute ``hidden:``.
 265
 266 The parameter attribute ``hidden:`` is an OpenStack optional attribute that
 267 defines whether the parameters should be hidden when a user requests
 268 information about a stack created from the template.
 269 This attribute can be used to hide passwords specified as parameters.
 270
 271 constraints
 272 ++++++++++++
 273
 274 The parameter attribute ``constraints:`` is an OpenStack optional attribute
 275 that defines a list of constraints to apply to the parameter.
 276
 277
 278 .. req::
 279     :id: R-88863
 280     :target: VNF
 281     :keyword: MUST
 282     :validation_mode: static
 283     :updated: casablanca
 284
 285     A VNF's Heat Orchestration Template's parameter defined
 286     in a non-nested YAML file as type
 287     ``number`` **MUST** have a parameter constraint of ``range`` or
 288     ``allowed_values`` defined.
 289
 290 .. req::
 291     :id: R-40518
 292     :target: VNF
 293     :keyword: MAY
 294     :updated: casablanca
 295
 296     A VNF's Heat Orchestration Template's parameter defined
 297     in a non-nested YAML file as type
 298     ``string`` **MAY** have a parameter constraint defined.
 299
 300 .. req::
 301     :id: R-96227
 302     :target: VNF
 303     :keyword: MAY
 304     :updated: casablanca
 305
 306     A VNF's Heat Orchestration Template's parameter defined
 307     in a non-nested YAML file as type
 308     ``json`` **MAY** have a parameter constraint defined.
 309
 310 .. req::
 311     :id: R-79817
 312     :target: VNF
 313     :keyword: MAY
 314     :updated: casablanca
 315
 316     A VNF's Heat Orchestration Template's parameter defined
 317     in a non-nested YAML file as
 318     type ``comma_delimited_list`` **MAY** have a parameter constraint defined.
 319
 320 .. req::
 321     :id: R-06613
 322     :target: VNF
 323     :keyword: MAY
 324     :updated: casablanca
 325
 326     A VNF's Heat Orchestration Template's parameter defined
 327     in a non-nested YAML file as type
 328     ``boolean`` **MAY** have a parameter constraint defined.
 329
 330 .. req::
 331     :id: R-00011
 332     :target: VNF
 333     :keyword: MUST NOT
 334     :validation_mode: static
 335     :updated: casablanca
 336
 337     A VNF's Heat Orchestration Template's parameter defined
 338     in a nested YAML file
 339     **MUST NOT** have a parameter constraint defined.
 340
 341 The constraints block of a parameter definition defines additional
 342 validation constraints that apply to the value of the parameter.
 343 The parameter values provided in the VNF Heat Orchestration Template are
 344 validated against the constraints at instantiation time.
 345 The stack creation fails if the parameter value doesn't comply to
 346 the constraints.
 347
 348 The constraints are defined as a list with the following syntax
 349
 350 .. code-block:: yaml
 351
 352   constraints:
 353
 354     <constraint type>: <constraint definition>
 355
 356     description: <constraint description>
 357
 358 ..
 359
 360 **<constraint type>** Provides the type of constraint to apply.
 361 The list of OpenStack supported constraints can be found at
 362 https://docs.openstack.org/heat/latest/template_guide/hot_spec.html .
 363
 364 **<constraint definition>** provides the actual constraint.
 365 The syntax and constraint is dependent of the <constraint type> used.
 366
 367 **description:** is an optional attribute that provides a description of
 368 the constraint. The text is presented to the user when the value the user
 369 defines violates the constraint. If omitted, a default validation message is
 370 presented to the user.
 371
 372
 373
 374 Below is a brief overview of the ``range`` and ``allowed values`` constraints.
 375 For complete details on constraints, see
 376 https://docs.openstack.org/heat/latest/template_guide/hot_spec.html#parameter-constraints
 377
 378
 379 **range**
 380
 381 ``range``: The ``range`` constraint applies to parameters of ``type: number``.
 382 It defines a lower and upper limit for the numeric value of the parameter.
 383 The syntax of the ``range`` constraint is
 384
 385 .. code-block:: yaml
 386
 387     range: { min: <lower limit>, max: <upper limit> }
 388
 389 ..
 390
 391 It is possible to define a range constraint with only a lower limit or an
 392 upper limit.
 393
 394 **allowed_values**
 395
 396 ``allowed_values``: The ``allowed_values`` constraint applies to parameters of
 397 type ``string`` or type ``number``. It specifies a set of possible values
 398 for a parameter. At deployment time, the user-provided value for the
 399 respective parameter must match one of the elements of the list.
 400 The syntax of the ``allowed_values`` constraint is
 401
 402 .. code-block:: yaml
 403
 404     allowed_values: [ <value>, <value>, ... ]
 405
 406     Alternatively, the following YAML list notation can be used
 407
 408     allowed_values:
 409
 410     - <value>
 411
 412     - <value>
 413
 414     - ...
 415
 416 immutable
 417 ++++++++++++
 418
 419
 420 .. req::
 421     :id: R-22589
 422     :target: VNF
 423     :keyword: MAY
 424
 425     A VNF's Heat Orchestration Template parameter declaration
 426     **MAY** contain the attribute ``immutable:``.
 427
 428 The parameter attribute ``immutable`` is an OpenStack optional attribute
 429 that defines whether the parameter is updatable. A Heat Orchestration Template
 430 stack update fails if ``immutable`` is set to ``true`` and the parameter
 431 value is changed.  This attribute ``immutable`` defaults to ``false``.
 432
 433 .. _resources:
 434
 435 resources
 436 ~~~~~~~~~~~~
 437
 438
 439 .. req::
 440     :id: R-23664
 441     :target: VNF
 442     :keyword: MUST
 443     :validation_mode: static
 444
 445     A VNF's Heat Orchestration template **MUST**
 446     contain the section ``resources:``.
 447
 448 .. req::
 449     :id: R-90152
 450     :target: VNF
 451     :keyword: MUST
 452     :validation_mode: static
 453
 454     A VNF's Heat Orchestration Template's
 455     ``resources:`` section **MUST** contain the declaration of at
 456     least one resource.
 457
 458 .. req::
 459     :id: R-40551
 460     :target: VNF
 461     :keyword: MAY
 462     :updated: casablanca
 463
 464     A VNF's Heat Orchestration Template's Nested YAML files **MAY**
 465     (or **MAY NOT**) contain the section ``resources:``.
 466
 467 Each resource is defined as a
 468 separate block in the resources section with the following syntax.
 469
 470 .. code-block:: yaml
 471
 472   resources:
 473
 474     <resource ID>:
 475
 476       type: <resource type>
 477
 478       properties:
 479
 480         <property name>: <property value>
 481
 482       metadata:
 483
 484         <resource specific metadata>
 485
 486       depends_on: <resource ID or list of ID>
 487
 488       update_policy: <update policy>
 489
 490       deletion_policy: <deletion policy>
 491
 492       external_id: <external resource ID>
 493
 494       condition: <condition name or expression or boolean>
 495
 496
 497 resource ID
 498 +++++++++++++
 499
 500 .. req::
 501     :id: R-75141
 502     :target: VNF
 503     :keyword: MUST
 504     :validation_mode: static
 505
 506     A VNF's Heat Orchestration Template's resource name
 507     (i.e., <resource ID>) **MUST** only contain alphanumeric
 508     characters and underscores ('_').
 509
 510 .. req::
 511     :id: R-16447
 512     :target: VNF
 513     :keyword: MUST
 514     :validation_mode: static
 515
 516     A VNF's <resource ID> **MUST** be unique across all Heat
 517     Orchestration Templates and all HEAT Orchestration Template
 518     Nested YAML files that are used to create the VNF.
 519
 520 Note that a VNF can be composed of one or more Heat Orchestration Templates.
 521
 522 Note that OpenStack requires the <resource ID> to be unique to the
 523 Heat Orchestration Template and not unique across all Heat
 524 Orchestration Templates the compose the VNF.
 525
 526 type
 527 +++++
 528
 529 The resource attribute ``type`` is an OpenStack required attribute that
 530 defines the resource type, such as ``OS::Nova::Server`` or
 531 ``OS::Neutron::Port``.
 532
 533 The resource attribute ``type`` may specify a VNF HEAT
 534 Orchestration Template Nested YAML file.
 535
 536
 537 .. req::
 538     :id: R-53952
 539     :target: VNF
 540     :keyword: MUST NOT
 541     :validation_mode: static
 542
 543     A VNF's Heat Orchestration Template's Resource
 544     **MUST NOT** reference a HTTP-based resource definitions.
 545
 546 .. req::
 547     :id: R-71699
 548     :target: VNF
 549     :keyword: MUST NOT
 550     :validation_mode: static
 551
 552     A VNF's Heat Orchestration Template's Resource
 553     **MUST NOT** reference a HTTP-based Nested YAML file.
 554
 555 properties
 556 +++++++++++++
 557
 558 The resource attribute ``properties`` is an OpenStack optional attribute that
 559 provides a list of resource-specific properties. The property value can
 560 be provided in place, or via a function
 561 (e.g., `Intrinsic functions <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-intrinsic-functions>`__).
 562
 563
 564 .. req::
 565     :id: R-10834
 566     :target: VNF
 567     :keyword: MUST
 568     :validation_mode: static
 569     :updated: casablanca
 570
 571     If a VNF's Heat Orchestration Template resource attribute
 572     ``property:`` uses a nested ``get_param``, the nested
 573     ``get_param`` **MUST** reference an index.
 574
 575 metadata
 576 ++++++++++
 577
 578 The resource attribute ``metadata`` is an OpenStack optional attribute.
 579
 580 .. req::
 581     :id: R-67386
 582     :target: VNF
 583     :keyword: MUST
 584     :validation_mode: static
 585     :introduced: casablanca
 586
 587     A VNF's Heat Orchestration Template's Resource **MAY** declare the
 588     attribute ``metadata``.
 589
 590 depends_on
 591 +++++++++++
 592
 593 The resource attribute ``depends_on`` is an OpenStack optional attribute.
 594 See `Section <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-resources-dependencies>`__ 9.7 for additional details.
 595
 596 .. req::
 597     :id: R-46968
 598     :target: VNF
 599     :keyword: MAY
 600
 601     VNF's Heat Orchestration Template's Resource **MAY** declare the
 602     attribute ``depends_on:``.
 603
 604 update_policy
 605 ++++++++++++++
 606
 607
 608 .. req::
 609     :id: R-63137
 610     :target: VNF
 611     :keyword: MAY
 612
 613     VNF's Heat Orchestration Template's Resource **MAY** declare the
 614     attribute ``update_policy:``.
 615
 616 deletion_policy
 617 +++++++++++++++++++
 618
 619
 620 .. req::
 621     :id: R-43740
 622     :target: VNF
 623     :keyword: MAY
 624     :updated: casablanca
 625
 626     VNF's Heat Orchestration Template's Resource **MAY** declare the
 627     attribute ``deletion_policy:``.
 628
 629 If specified, the ``deletion_policy`` attribute for resources allows
 630 values ``Delete``, ``Retain``, and ``Snapshot``.
 631 Starting with heat_template_version 2016-10-14,
 632 lowercase equivalents are also allowed.
 633
 634 The default policy is to delete the physical resource when
 635 deleting a resource from the stack.
 636
 637 external_id
 638 ++++++++++++
 639
 640
 641 .. req::
 642     :id: R-78569
 643     :target: VNF
 644     :keyword: MAY
 645     :updated: casablanca
 646
 647     VNF's Heat Orchestration Template's Resource **MAY** declare the
 648     attribute ``external_id:``.
 649
 650 This attribute allows for specifying the resource_id for an existing external
 651 (to the stack) resource. External resources cannot depend on other resources,
 652 but we allow other resources to depend on external resource. This attribute
 653 is optional. Note: when this is specified, properties will not be used for
 654 building the resource and the resource is not managed by Heat. This is not
 655 possible to update that attribute. Also, resource won't be deleted by
 656 heat when stack is deleted.
 657
 658
 659 condition
 660 +++++++++++
 661
 662 The resource attribute ``condition`` is an OpenStack optional attribute.
 663
 664 outputs
 665 ~~~~~~~~~
 666
 667
 668 .. req::
 669     :id: R-36982
 670     :target: VNF
 671     :keyword: MAY
 672
 673     A VNF's Heat Orchestration template **MAY** contain the ``outputs:``
 674     section.
 675
 676 This section allows for specifying output parameters
 677 available to users once the template has been instantiated. If the
 678 section is specified, it will need to adhere to specific requirements.
 679 See :ref:`Output Parameters` and
 680 :ref:`ONAP Output Parameter Names` for additional details.
 681
 682 Environment File Format
 683 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 684
 685 A VNF's Heat Orchestration Template's environment file is a yaml text file.
 686 (https://docs.openstack.org/developer/heat/template_guide/environment.html)
 687
 688
 689 .. req::
 690     :id: R-86285
 691     :target: VNF
 692     :keyword: MUST
 693     :validation_mode: static
 694     :updated: casablanca
 695
 696     A VNF's Heat Orchestration template **MUST** have a
 697     corresponding environment file.
 698
 699 The use of an environment file in OpenStack is optional. In ONAP, it is
 700 mandatory. A Heat Orchestration Template uploaded to ONAP must have a
 701 corresponding environment file, even if no parameters are enumerated in
 702 the mandatory parameter section.
 703
 704
 705 .. req::
 706     :id: R-03324
 707     :target: VNF
 708     :keyword: MUST
 709     :validation_mode: static
 710     :updated: casablanca
 711
 712     A VNF's Heat Orchestration template's Environment File **MUST**
 713     contain the ``parameters:`` section.
 714
 715 .. req::
 716     :id: R-68198
 717     :target: VNF
 718     :keyword: MAY
 719     :updated: casablanca
 720
 721     A VNF's Heat Orchestration template's Environment File's
 722     ``parameters:`` section **MAY** (or **MAY NOT**) enumerate parameters.
 723
 724 ONAP implementation requires the parameters section in the environmental
 725 file to be declared.  The parameters section contains a list of key/value
 726 pairs.
 727
 728
 729 .. req::
 730     :id: R-59930
 731     :target: VNF
 732     :keyword: MAY
 733
 734     A VNF's Heat Orchestration template's Environment File's
 735     **MAY** contain the ``parameter_defaults:`` section.
 736
 737 The ``parameter_defaults:`` section contains default parameters that are
 738 passed to all template resources.
 739
 740
 741 .. req::
 742     :id: R-46096
 743     :target: VNF
 744     :keyword: MAY
 745
 746     A VNF's Heat Orchestration template's Environment File's
 747     **MAY** contain the ``encrypted_parameters:`` section.
 748
 749 The ``encrypted_parameters:`` section contains a list of encrypted parameters.
 750
 751
 752 .. req::
 753     :id: R-24893
 754     :target: VNF
 755     :keyword: MAY
 756
 757     A VNF's Heat Orchestration template's Environment File's
 758     **MAY** contain the ``event_sinks:`` section.
 759
 760 The ``event_sinks:`` section contains the list of endpoints that would receive
 761 stack events.
 762
 763
 764 .. req::
 765     :id: R-42685
 766     :target: VNF
 767     :keyword: MAY
 768
 769     A VNF's Heat Orchestration template's Environment File's
 770     **MAY** contain the ``parameter_merge_strategies:`` section.
 771
 772 The ``parameter_merge_strategies:`` section provides the merge strategies for
 773 merging parameters and parameter defaults from the environment file.
 774
 775
 776 .. req::
 777     :id: R-67231
 778     :target: VNF
 779     :keyword: MUST NOT
 780     :validation_mode: static
 781
 782     A VNF's Heat Orchestration template's Environment File's
 783     **MUST NOT** contain the ``resource_registry:`` section.
 784
 785 ONAP implementation does not support the Environment File resource_registry
 786 section.  The resource_registry section allows for the definition of custom
 787 resources.
 788
 789 SDC Treatment of Environment Files
 790 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 791
 792 Parameter values enumerated in the environment file are used by SDC as
 793 the default value. However, the SDC user may use the SDC GUI to
 794 overwrite the default values in the environment file.
 795
 796 SDC generates a new environment file for distribution to MSO based on
 797 the uploaded environment file and the user provided GUI updates. The
 798 user uploaded environment file is discarded when the new file is
 799 created.
 800
 801 ONAP has requirements for what parameters must be enumerated in the
 802 environment file and what parameter must not be enumerated in the
 803 environment file. See :ref:`Output Parameters` and
 804 :ref:`ONAP Heat Resource ID and Parameter Naming Convention` for more details.
 805