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