docs/Chapter5/Heat.rst

   1 .. Modifications Copyright © 2017-2018 AT&T Intellectual Property.
   2
   3 .. Licensed under the Creative Commons License, Attribution 4.0 Intl.
   4    (the "License"); you may not use this documentation except in compliance
   5    with the License. You may obtain a copy of the License at
   6
   7 .. https://creativecommons.org/licenses/by/4.0/
   8
   9 .. Unless required by applicable law or agreed to in writing, software
  10    distributed under the License is distributed on an "AS IS" BASIS,
  11    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  12    See the License for the specific language governing permissions and
  13    limitations under the License.
  14
  15
  16 Heat
  17 ----
  18
  19 General Guidelines
  20 ^^^^^^^^^^^^^^^^^^
  21 This section contains general Heat Orchestration Template guidelines
  22 and requirements.
  23
  24 Heat Template Compliance
  25 ~~~~~~~~~~~~~~~~~~~~~~~~
  26
  27 The Heat Orchestration Template requirements with RFC 2119
  28 keywords **MUST** and **MUST NOT** can be validated against a set of Heat
  29 Templates via the VNF Validation Program (VVP).
  30
  31 **NOTE**: Not all requirements are currently testable via VVP.
  32
  33 The VVP *validation scripts* project contains python validation
  34 scripts that will parse Heat Orchestration Templates in a given directory
  35 to ensure that they comply with ONAP Heat Orchestration Template requirements.
  36
  37 For instructions on how to use the VVP validation scripts,
  38 please see the validation scripts
  39 `README <https://github.com/onap/vvp-validation-scripts>`__
  40
  41 YAML Format
  42 ~~~~~~~~~~~
  43
  44
  45 .. req::
  46     :id: R-95303
  47     :target: VNF
  48     :keyword: MUST
  49
  50     A VNF's Heat Orchestration Template **MUST** be defined using valid YAML.
  51
  52 YAML (YAML Ain't
  53 Markup Language) is a human friendly data serialization standard for all
  54 programming languages. See http://www.yaml.org/.
  55
  56 Heat Orchestration Template Format
  57 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  58
  59 As stated above, Heat Orchestration templates must be defined in YAML.
  60
  61 YAML rules include:
  62
  63  - Tabs are not allowed, use spaces ONLY
  64
  65  - You must indent your properties and lists with 1 or more spaces
  66
  67  - All Resource IDs and resource property parameters are
  68    case-sensitive. (e.g., "ThIs", is not the same as "thiS")
  69
  70 Heat Orchestration Template Structure
  71 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  72
  73 Heat Orchestration template structure follows the following format,
  74 as defined by OpenStack at
  75 https://docs.openstack.org/developer/heat/template_guide/hot_spec.html
  76
  77 .. code-block:: yaml
  78
  79   heat_template_version: <date>
  80
  81   description:
  82     # a description of the template
  83
  84   parameter_groups:
  85     # a declaration of input parameter groups and order
  86
  87   parameters:
  88     # declaration of input parameters
  89
  90   resources:
  91     # declaration of template resources
  92
  93   outputs:
  94     # declaration of output parameters
  95
  96   conditions:
  97     # declaration of conditions
  98
  99 heat_template_version
 100 +++++++++++++++++++++
 101
 102
 103 .. req::
 104     :id: R-27078
 105     :target: VNF
 106     :keyword: MUST
 107
 108     A VNF's Heat Orchestration template **MUST** contain
 109     the section "heat_template_version:".
 110
 111 The section "heat_template_version:" must be set to a date
 112 that is supported by the OpenStack environment.
 113
 114 description
 115 +++++++++++
 116
 117
 118 .. req::
 119     :id: R-39402
 120     :target: VNF
 121     :keyword: MUST
 122
 123     A VNF's Heat Orchestration Template **MUST**
 124     contain the section "description:".
 125
 126 parameter_groups
 127 ++++++++++++++++
 128
 129 A VNF Heat Orchestration template may
 130 contain the section "parameter_groups:".
 131
 132 parameters
 133 ++++++++++
 134
 135
 136 .. req::
 137     :id: R-35414
 138     :target: VNF
 139     :keyword: MUST
 140
 141     A VNF Heat Orchestration's template **MUST**
 142     contain the section "parameters:".
 143
 144
 145 .. code-block:: yaml
 146
 147   parameters:
 148
 149     <param name>:
 150
 151       type: <string | number | json | comma_delimited_list | boolean>
 152
 153       label: <human-readable name of the parameter>
 154
 155       description: <description of the parameter>
 156
 157       default: <default value for parameter>
 158
 159       hidden: <true | false>
 160
 161       constraints:
 162
 163         <parameter constraints>
 164
 165       immutable: <true | false>
 166
 167 This section allows for
 168 specifying input parameters that have to be provided when instantiating
 169 the template. Each parameter is specified in a separate nested block
 170 with the name of the parameters defined in the first line and additional
 171 attributes (e.g., type, label) defined as nested elements.
 172
 173
 174 .. req::
 175     :id: R-90279
 176     :target: VNF
 177     :keyword: MUST
 178
 179     A VNF's Heat Orchestration template's parameter **MUST**
 180     be used in a resource with the exception of the parameters
 181     for the OS::Nova::Server resource property availability_zone.
 182
 183 .. req::
 184     :id: R-91273
 185     :target: VNF
 186     :keyword: MAY NOT
 187
 188     A VNF Heat Orchestration's template's parameter for
 189     the OS::Nova::Server resource property availability_zone
 190     **MAY NOT** be used in any OS::Nova::Resource.
 191
 192 That is, the parameter associated with the property 'availability_zone'
 193 maybe declared but not used in a resource.
 194
 195 <param name>
 196 ____________
 197
 198 The name of the parameter.
 199
 200
 201 .. req::
 202     :id: R-25877
 203     :target: VNF
 204     :keyword: MUST
 205
 206     A VNF's Heat Orchestration Template's parameter
 207     name (i.e., <param name>) **MUST** contain only
 208     alphanumeric characters and underscores ('_').
 209
 210 type
 211 ____
 212
 213
 214 .. req::
 215     :id: R-36772
 216     :target: VNF
 217     :keyword: MUST
 218
 219     A VNF's Heat Orchestration Template's parameter
 220     **MUST** include the attribute "type:".
 221
 222 .. req::
 223     :id: R-11441
 224     :target: VNF
 225     :keyword: MUST
 226
 227     A VNF's Heat Orchestration Template's parameter
 228     type **MUST** be one of the following values: "string",
 229     "number", "json", "comma_delimited_list" or "boolean".
 230
 231 label
 232 _____
 233
 234
 235 .. req::
 236     :id: R-32094
 237     :target: VNF
 238     :keyword: MAY
 239
 240     A VNF's Heat Orchestration Template parameter
 241     declaration **MAY** contain the attribute "label:".
 242
 243 description
 244 ___________
 245
 246
 247 .. req::
 248     :id: R-44001
 249     :target: VNF
 250     :keyword: MUST
 251
 252     A VNF's Heat Orchestration Template parameter
 253     declaration **MUST** contain the attribute "description".
 254
 255 Note that the parameter attribute "description:" is an OpenStack
 256 optional attribute that provides a description of the parameter.
 257 ONAP implementation requires this attribute.
 258
 259 default
 260 _______
 261
 262
 263 .. req::
 264     :id: R-90526
 265     :target: VNF
 266     :keyword: MUST
 267
 268     A VNF Heat Orchestration Template parameter
 269     declaration **MUST** not contain the default attribute.
 270
 271 .. req::
 272     :id: R-26124
 273     :target: VNF
 274     :keyword: MUST
 275
 276     If a VNF Heat Orchestration Template parameter
 277     requires a default value, it **MUST** be enumerated in the environment file.
 278
 279 Note that the parameter attribute "default:" is an OpenStack
 280 optional attribute that declares the default value of the
 281 parameter. ONAP implementation prohibits the use of this attribute.
 282
 283 hidden
 284 ______
 285
 286
 287 .. req::
 288     :id: R-32557
 289     :target: VNF
 290     :keyword: MAY
 291
 292     A VNF's Heat Orchestration Template parameter
 293     declaration **MAY** contain the attribute "hidden:".
 294
 295 The parameter attribute "hidden:" is an OpenStack optional
 296 attribute that defines whether the parameters should be
 297 hidden when a user requests information about a stack
 298 created from the template. This attribute can be used
 299 to hide passwords specified as parameters.
 300
 301 constraints
 302 ___________
 303
 304 The parameter attribute "constraints:" is an OpenStack optional
 305 attribute that defines a list of constraints to apply to the parameter.
 306
 307
 308 .. req::
 309     :id: R-88863
 310     :target: VNF
 311     :keyword: MUST
 312
 313     A VNF's Heat Orchestration Template's parameter defined as
 314     type "number" **MUST** have a parameter constraint of "range" or
 315     "allowed_values" defined.
 316
 317 .. req::
 318     :id: R-40518
 319     :target: VNF
 320     :keyword: MAY
 321
 322     A VNF's Heat Orchestration Template's parameter defined as
 323     type "string" **MAY** have a parameter constraint defined.
 324
 325 .. req::
 326     :id: R-96227
 327     :target: VNF
 328     :keyword: MAY
 329
 330     A VNF's Heat Orchestration Template's parameter defined as
 331     type "json" **MAY** have a parameter constraint defined.
 332
 333 .. req::
 334     :id: R-79817
 335     :target: VNF
 336     :keyword: MAY
 337
 338     A VNF's Heat Orchestration Template's parameter defined as
 339     type "comma_delimited_list" **MAY** have a parameter constraint defined.
 340
 341 .. req::
 342     :id: R-06613
 343     :target: VNF
 344     :keyword: MAY
 345
 346     A VNF's Heat Orchestration Template's parameter defined as
 347     type "boolean" **MAY** have a parameter constraint defined.
 348
 349 .. req::
 350     :id: R-00011
 351     :target: VNF
 352     :keyword: MUST NOT
 353
 354     A VNF's Heat Orchestration Template's Nested YAML files
 355     parameter's **MUST NOT** have a parameter constraint defined.
 356
 357 The constraints block of a parameter definition defines additional
 358 validation constraints that apply to the value of the parameter.
 359 The parameter values provided in the VNF Heat Orchestration Template
 360 are validated against the constraints at instantiation time.
 361 The stack creation fails if the parameter value doesn't comply to
 362 the constraints.
 363
 364 The constraints are defined as a list with the following syntax
 365
 366 .. code-block:: yaml
 367
 368   constraints:
 369
 370     <constraint type>: <constraint definition>
 371
 372     description: <constraint description>
 373
 374 ..
 375
 376 **<constraint type>** Provides the type of constraint to apply.
 377 The list of OpenStack supported constraints can be found at
 378 https://docs.openstack.org/heat/latest/template_guide/hot_spec.html .
 379
 380 **<constraint definition>** provides the actual constraint.
 381 The syntax and constraint is dependent of the <constraint type> used.
 382
 383 **description** is an optional attribute that provides a description of the
 384 constraint. The text is presented to the user when the value the user
 385 defines violates the constraint. If omitted, a default validation
 386 message is presented to the user.
 387
 388 Below is a brief overview of the "range" and "allowed values" constraints.
 389 For complete details on constraints, see
 390 https://docs.openstack.org/heat/latest/template_guide/hot_spec.html#parameter-constraints
 391
 392 **range**
 393
 394 range: The range constraint applies to parameters of type: number.
 395 It defines a lower and upper limit for the numeric value of the
 396 parameter. The syntax of the range constraint is
 397
 398 .. code-block:: yaml
 399
 400     range: { min: <lower limit>, max: <upper limit> }
 401
 402 ..
 403
 404 It is possible to define a range constraint with only a lower
 405 limit or an upper limit.
 406
 407 **allowed_values**
 408
 409 allowed_values: The allowed_values constraint applies to parameters of
 410 type \"string\" or type \"number\". It specifies a set of possible
 411 values for a parameter. At deployment time, the user-provided value
 412 for the respective parameter must match one of the elements of the
 413 list. The syntax of the allowed_values constraint is
 414
 415 .. code-block:: yaml
 416
 417     allowed_values: [ <value>, <value>, ... ]
 418
 419     Alternatively, the following YAML list notation can be used
 420
 421     allowed_values:
 422
 423     - <value>
 424
 425     - <value>
 426
 427     - ...
 428
 429 . .
 430
 431 immutable
 432 _________
 433
 434
 435 .. req::
 436     :id: R-22589
 437     :target: VNF
 438     :keyword: MAY
 439
 440     A VNF's Heat Orchestration Template parameter declaration
 441     **MAY** contain the attribute "immutable:".
 442
 443 The parameter attribute \"immutable:\" is an OpenStack optional
 444 attribute that defines whether the parameter is updatable. A Heat
 445 Orchestration Template stack update fails if immutable is set to
 446 true and the parameter value is changed.  This attribute
 447 \"immutable:\" defaults to false.
 448
 449 resources
 450 +++++++++
 451
 452
 453 .. req::
 454     :id: R-23664
 455     :target: VNF
 456     :keyword: MUST
 457
 458     A VNF's Heat Orchestration template **MUST** contain
 459     the section "resources:".
 460
 461 .. req::
 462     :id: R-90152
 463     :target: VNF
 464     :keyword: MUST
 465
 466     A VNF's Heat Orchestration Template's "resources:"
 467     section **MUST** contain the declaration of at least one resource.
 468
 469 .. req::
 470     :id: R-40551
 471     :target: VNF
 472     :keyword: MAY
 473
 474     A VNF's Heat Orchestration Template's Nested YAML files
 475     **MAY** contain the section "resources:".
 476
 477 Each resource is defined as a
 478 separate block in the resources section with the following syntax.
 479
 480 .. code-block:: yaml
 481
 482   resources:
 483
 484     <resource ID>:
 485
 486       type: <resource type>
 487
 488       properties:
 489
 490         <property name>: <property value>
 491
 492       metadata:
 493
 494         <resource specific metadata>
 495
 496       depends_on: <resource ID or list of ID>
 497
 498       update_policy: <update policy>
 499
 500       deletion_policy: <deletion policy>
 501
 502       external_id: <external resource ID>
 503
 504       condition: <condition name or expression or boolean>
 505
 506
 507
 508 resource ID
 509 ___________
 510
 511
 512 .. req::
 513     :id: R-75141
 514     :target: VNF
 515     :keyword: MUST
 516
 517     A VNF's Heat Orchestration Template's resource name
 518     (i.e., <resource ID>) **MUST** only contain alphanumeric
 519     characters and underscores ('_').
 520
 521 .. req::
 522     :id: R-16447
 523     :target: VNF
 524     :keyword: MUST
 525
 526     A VNF's <resource ID> **MUST** be unique across all
 527     Heat Orchestration Templates and all HEAT Orchestration Template
 528     Nested YAML files that are used to create the VNF.
 529
 530 Note that a VNF can be composed of one or more Heat Orchestration Templates.
 531
 532 Note that OpenStack requires the <resource ID> to be unique to the
 533 Heat Orchestration Template and not unique across all Heat
 534 Orchestration Templates the compose the VNF.
 535
 536 type
 537 ____
 538
 539 The resource attribute \"type:\" is an OpenStack required
 540 attribute that defines the resource type, such as
 541 OS::Nova::Server or OS::Neutron::Port.
 542
 543 The resource attribute \"type:\" may specify a VNF HEAT
 544 Orchestration Template Nested YAML file.
 545
 546
 547 .. req::
 548     :id: R-53952
 549     :target: VNF
 550     :keyword: MUST NOT
 551
 552     A VNF's Heat Orchestration Template's Resource
 553     **MUST NOT** reference a HTTP-based resource definitions.
 554
 555 .. req::
 556     :id: R-71699
 557     :target: VNF
 558     :keyword: MUST NOT
 559
 560     A VNF's Heat Orchestration Template's Resource
 561     **MUST NOT** reference a HTTP-based Nested YAML file.
 562
 563 properties
 564 __________
 565
 566 The resource attribute \"properties:\" is an OpenStack optional
 567 attribute that provides a list of resource-specific properties.
 568 The property value can be provided in place, or via a function
 569 (e.g., `Intrinsic functions <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-intrinsic-functions>`__).
 570
 571
 572 .. req::
 573     :id: R-10834
 574     :target: VNF
 575     :keyword: MUST
 576     :test: no test found
 577     :test_case: no test found
 578     :test_file: no test found
 579
 580     If a VNF Heat Orchestration Template resource attribute
 581     "property:" uses a nested "get_param", one level of nesting is
 582     supported and the nested "get_param" **MUST** reference an index.
 583
 584 metadata
 585 ________
 586
 587 The resource attribute \"metadata:\" is an OpenStack optional attribute.
 588
 589
 590 .. req::
 591     :id: R-97199
 592     :target: VNF
 593     :keyword: MUST
 594
 595     A VNF's Heat Orchestration Template's OS::Nova::Server
 596     resource **MUST** contain the attribute "metadata".
 597
 598 Section 5.4 contains the OS::Nova::Server mandatory and optional metadata.
 599
 600 depends_on
 601 __________
 602
 603 The resource attribute \"depends_on:\" is an OpenStack optional
 604 attribute.
 605 See `OpenStack documentation <https://docs.openstack.org/developer/heat/template_guide/hot_spec.html#hot-spec-resources-dependencies>`__
 606 for additional details.
 607
 608
 609 .. req::
 610     :id: R-46968
 611     :target: VNF
 612     :keyword: MAY
 613
 614     VNF's Heat Orchestration Template's Resource **MAY**
 615     declare the attribute "depends_on:".
 616
 617 update_policy
 618 _____________
 619
 620
 621 .. req::
 622     :id: R-63137
 623     :target: VNF
 624     :keyword: MAY
 625
 626     VNF's Heat Orchestration Template's Resource **MAY**
 627     declare the attribute "update_policy:".
 628
 629 deletion_policy
 630 _______________
 631
 632
 633 .. req::
 634     :id: R-43740
 635     :target: VNF
 636     :keyword: MAY
 637
 638     A VNF's Heat Orchestration Template's Resource
 639     **MAY** declare the attribute "deletion_policy:".
 640
 641 If specified, the \"deletion_policy:\" attribute for resources
 642 allows values 'Delete', 'Retain', and 'Snapshot'.
 643 Starting with heat_template_version 2016-10-14, lowercase
 644 equivalents are also allowed.
 645
 646 The default policy is to delete the physical resource when
 647 deleting a resource from the stack.
 648
 649 external_id
 650 ___________
 651
 652
 653 .. req::
 654     :id: R-78569
 655     :target: VNF
 656     :keyword: MAY
 657
 658     A VNF's Heat Orchestration Template's Resouce **MAY**
 659     declare the attribute "external_id:".
 660
 661 This attribute allows for specifying the resource_id for an
 662 existing external (to the stack) resource. External resources
 663 cannot depend on other resources, but we allow other resources to
 664 depend on external resource. This attribute is optional.
 665 Note: when this is specified, properties will not be used for
 666 building the resource and the resource is not managed by Heat.
 667 This is not possible to update that attribute. Also,
 668 resource won't be deleted by heat when stack is deleted.
 669
 670
 671 condition
 672 _________
 673
 674 The resource attribute \"condition:\" is an OpenStack optional attribute.
 675
 676 Support for the resource condition attribute was added
 677 in the Newton release of OpenStack.
 678
 679 outputs
 680 +++++++
 681
 682
 683 .. req::
 684     :id: R-36982
 685     :target: VNF
 686     :keyword: MAY
 687
 688     A VNF's Heat Orchestration template **MAY**
 689     contain the "outputs:" section.
 690
 691 This section allows for specifying output parameters
 692 available to users once the template has been instantiated. If the
 693 section is specified, it will need to adhere to specific requirements.
 694 See `Output Parameters`_ and
 695 `ONAP Output Parameter Names`_ for additional details.
 696
 697 Environment File Format
 698 ~~~~~~~~~~~~~~~~~~~~~~~
 699
 700 The environment file is a yaml text file.
 701 (https://docs.openstack.org/developer/heat/template_guide/environment.html)
 702
 703
 704 .. req::
 705     :id: R-86285
 706     :target: VNF
 707     :keyword: MUST
 708
 709     The VNF Heat Orchestration Template **MUST** have a corresponding
 710     environment file, even if no parameters are required to be enumerated.
 711
 712 The use of an environment file in OpenStack is optional.
 713 In ONAP, it is mandatory.
 714
 715
 716 .. req::
 717     :id: R-03324
 718     :target: VNF
 719     :keyword: MUST
 720
 721     The VNF Heat Orchestration Template **MUST** contain the
 722     "parameters" section in the environment file.
 723
 724 .. req::
 725     :id: R-68198
 726     :target: VNF
 727     :keyword: MAY
 728
 729     A VNF's Heat Orchestration template's Environment File's
 730     "parameters:" section **MAY** enumerate parameters.
 731
 732 ONAP implementation requires the parameters section in the
 733 environmental file to be declared. The parameters section
 734 contains a list of key/value pairs.
 735
 736
 737 .. req::
 738     :id: R-59930
 739     :target: VNF
 740     :keyword: MAY
 741
 742     A VNF's Heat Orchestration template's Environment
 743     File's **MAY** contain the "parameter_defaults:" section.
 744
 745 The "parameter_defaults:" section contains default parameters
 746 that are passed to all template resources.
 747
 748
 749 .. req::
 750     :id: R-46096
 751     :target: VNF
 752     :keyword: MAY
 753
 754     A VNF's Heat Orchestration template's Environment File's
 755     **MAY** contain the "encrypted_parameters:" section.
 756
 757 The "encrypted_parameters:" section contains a list of encrypted parameters.
 758
 759
 760 .. req::
 761     :id: R-24893
 762     :target: VNF
 763     :keyword: MAY
 764
 765     A VNF's Heat Orchestration template's Environment File's
 766     **MAY** contain the "event_sinks:" section.
 767
 768 The "event_sinks:" section contains the list of endpoints that would
 769 receive stack events.
 770
 771
 772 .. req::
 773     :id: R-42685
 774     :target: VNF
 775     :keyword: MAY
 776
 777     A VNF's Heat Orchestration template's Environment File's
 778     **MAY** contain the "parameter_merge_strategies:" section.
 779
 780 The "parameter_merge_strategies:" section provides the merge strategies
 781 for merging parameters and parameter defaults from the environment file.
 782
 783
 784 .. req::
 785     :id: R-67231
 786     :target: VNF
 787     :keyword: MUST NOT
 788
 789     A VNF's Heat Orchestration template's Environment File's **MUST NOT**
 790     contain the "resource_registry:" section.
 791
 792 ONAP implementation does not support the Environment File
 793 resource_registry section. The resource_registry section
 794 allows for the definition of custom resources.
 795
 796 SDC Treatment of Environment Files
 797 ++++++++++++++++++++++++++++++++++
 798
 799 Parameter values enumerated in the environment file are used by SDC as
 800 the default value. However, the SDC user may use the SDC GUI to
 801 overwrite the default values in the environment file.
 802
 803 SDC generates a new environment file for distribution to MSO based on
 804 the uploaded environment file and the user provided GUI updates. The
 805 user uploaded environment file is discarded when the new file is
 806 created.
 807
 808 ONAP has requirements for what parameters must be enumerated in the
 809 environment file and what parameter must not be enumerated in the
 810 environment file. See `Output Parameters`_ and
 811 `ONAP Resource ID and Parameter Naming Convention`_ for more details.
 812
 813 ONAP Heat Orchestration Templates: Overview
 814 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 815
 816 ONAP supports a modular Heat Orchestration Template design pattern,
 817 referred to as *VNF Modularity.*
 818
 819 ONAP VNF Modularity Overview
 820 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 821
 822
 823 .. req::
 824     :id: R-69663
 825     :target: VNF
 826     :keyword: MAY
 827
 828     A VNF **MAY** be composed from one or more Heat Orchestration
 829     Templates, each of which represents a subset of the overall VNF.
 830
 831 The Heat Orchestration Templates can be thought of a components or
 832 modules of the VNF and are referred to as "\ *VNF Modules*\ ".
 833 During orchestration, these modules are
 834 deployed incrementally to create the complete VNF.
 835
 836
 837 .. req::
 838     :id: R-33132
 839     :target: VNF
 840     :keyword: MAY
 841
 842     A VNF's Heat Orchestration Template **MAY** be
 843
 844        * a Base Module Heat Orchestration Template
 845          (also referred to as a Base Module)
 846
 847        * an Incremental Module Heat Orchestration Template
 848          (referred to as an Incremental Module)
 849
 850        * a Cinder Volume Module Heat Orchestration Template
 851          (referred to as Cinder Volume Module).
 852
 853 .. req::
 854     :id: R-37028
 855     :target: VNF
 856     :keyword: MUST
 857
 858     The VNF **MUST** be composed of one "base" module.
 859
 860 .. req::
 861     :id: R-13196
 862     :target: VNF
 863     :keyword: MAY
 864
 865     A VNF **MAY** be composed of zero to many Incremental Modules.
 866
 867 .. req::
 868     :id: R-20974
 869     :target: VNF
 870     :keyword: MUST
 871
 872     The VNF **MUST** deploy the base module first, prior to
 873     the incremental modules.
 874
 875 .. req::
 876     :id: R-28980
 877     :target: VNF
 878     :keyword: MAY
 879
 880     A VNF's incremental module **MAY** be used for initial VNF
 881     deployment only.
 882
 883 .. req::
 884     :id: R-86926
 885     :target: VNF
 886     :keyword: MAY
 887
 888     A VNF's incremental module **MAY** be used for scale out only.
 889
 890 A VNF's Incremental Module that is used for scale out is deployed
 891 sometime after initial VNF deployment to add capacity.
 892
 893
 894 .. req::
 895     :id: R-91497
 896     :target: VNF
 897     :keyword: MAY
 898
 899     A VNF's incremental module **MAY** be used for both deployment
 900     and scale out.
 901
 902 .. req::
 903     :id: R-68122
 904     :target: VNF
 905     :keyword: MAY
 906
 907     A VNF's incremental module **MAY** be deployed more than once,
 908     either during initial VNF deployment and/or scale out.
 909
 910 .. req::
 911     :id: R-46119
 912     :target: VNF
 913     :keyword: MAY
 914
 915     A VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
 916     **MAY** be defined in a Base Module.
 917
 918 .. req::
 919     :id: R-90748
 920     :target: VNF
 921     :keyword: MAY
 922
 923     A VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
 924     **MAY** be defined in an Incremental Module.
 925
 926 .. req::
 927     :id: R-03251
 928     :target: VNF
 929     :keyword: MAY
 930
 931     A VNF's Heat Orchestration Template's Resource OS::Heat::CinderVolume
 932     **MAY** be defined in a Cinder Volume Module.
 933
 934 ONAP also supports the concept of an optional, independently deployed Cinder
 935 volume via a separate Heat Orchestration Templates, referred to as a Cinder
 936 Volume Module. This allows the volume to persist after a Virtual Machine
 937 (VM) (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused
 938 on another instance (e.g., during a failover activity).
 939
 940 .. req::
 941     :id: R-11200
 942     :target: VNF
 943     :keyword: MUST
 944
 945     The VNF **MUST** keep the scope of a Cinder volume module,
 946     when it exists, to be 1:1 with the VNF Base Module or Incremental Module.
 947
 948 It is strongly recommended that Cinder Volumes be created in a Cinder Volume
 949 Module.
 950
 951 .. req::
 952     :id: R-38474
 953     :target: VNF
 954     :keyword: MUST
 955
 956     The VNF **MUST** have a corresponding environment file for a Base Module.
 957
 958 .. req::
 959     :id: R-81725
 960     :target: VNF
 961     :keyword: MUST
 962
 963     The VNF **MUST** have a corresponding environment file for an Incremental Module.
 964
 965 .. req::
 966     :id: R-53433
 967     :target: VNF
 968     :keyword: MUST
 969
 970     The VNF **MUST** have a corresponding environment file for a Cinder Volume Module.
 971
 972 These concepts will be described in more detail throughout the document.
 973 This overview is provided to set the stage and help clarify the concepts
 974 that will be introduced.
 975
 976 Nested Heat Orchestration Templates Overview
 977 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 978
 979 ONAP supports nested Heat Orchestration Templates per OpenStack
 980 specifications.
 981
 982
 983 .. req::
 984     :id: R-36582
 985     :target: VNF
 986     :keyword: MAY
 987
 988     A VNF's Base Module **MAY** utilize nested heat.
 989
 990 .. req::
 991     :id: R-56721
 992     :target: VNF
 993     :keyword: MAY
 994
 995     A VNF's Incremental Module **MAY** utilize nested heat.
 996
 997 .. req::
 998     :id: R-30395
 999     :target: VNF
1000     :keyword: MAY
1001
1002     A VNF's Cinder Volume Module **MAY** utilize nested heat.
1003
1004 Nested templates may be suitable for larger VNFs that contain many
1005 repeated instances of the same VM type(s). A common usage pattern is to
1006 create a nested template for each VM type along with its supporting
1007 resources. The Heat Orchestration Template may then reference these
1008 nested templates either statically (by repeated definition) or
1009 dynamically (via OS::Heat::ResourceGroup).
1010
1011 See `Nested Heat Templates`_ for additional details.
1012
1013 ONAP Heat Orchestration Template Filenames
1014 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1015
1016 In order to enable ONAP to understand the relationship between Heat
1017 files, the following Heat file naming convention must be utilized.
1018
1019 In the examples below, <text> represents any alphanumeric string that
1020 must not contain any special characters and must not contain the word
1021 "base".
1022
1023
1024 .. req::
1025     :id: R-87485
1026     :target: VNF
1027     :keyword: MUST
1028
1029     A VNF's Heat Orchestration Template's file extension **MUST**
1030     be in the lower case format '.yaml' or '.yml'.
1031
1032 .. req::
1033     :id: R-56438
1034     :target: VNF
1035     :keyword: MUST
1036
1037     A VNF's Heat Orchestration Template's Nested YAML file extension
1038     **MUST** be in the lower case format '.yaml' or '.yml'.
1039
1040 .. req::
1041     :id: R-74304
1042     :target: VNF
1043     :keyword: MUST
1044
1045     A VNF's Heat Orchestration Template's Environment file extension
1046     **MUST** be in the lower case format '.env'.
1047
1048 .. req::
1049     :id: R-99646
1050     :target: VNF
1051     :keyword: MUST
1052     :test: no test found
1053     :test_case: no test found
1054     :test_file: no test found
1055
1056     A VNF's YAML files (i.e, Heat Orchestration Template files and
1057     Nested files) **MUST** have a unique name in the scope of the VNF.
1058
1059 Base Modules
1060 ++++++++++++
1061
1062
1063 .. req::
1064     :id: R-81339
1065     :target: VNF
1066     :keyword: MUST
1067
1068     A VNF Heat Orchestration Template's Base Module file name **MUST**
1069     include 'base' in the filename and **MUST** match one of the following four
1070     formats:
1071
1072        * 'base_<text>.y[a]ml'
1073        * '<text>_base.y[a]ml'
1074        * 'base.y[a]ml'
1075        * '<text>_base_<text>'.y[a]ml
1076
1077     where 'base' is case insensitive and where '<text>'
1078     **MUST** contain only alphanumeric characters
1079     and underscores '_' and **MUST NOT** contain the case
1080     insensitive word 'base'.
1081
1082 .. req::
1083     :id: R-91342
1084     :target: VNF
1085     :keyword: MUST
1086
1087     A VNF Heat Orchestration Template's Base Module's Environment File
1088     **MUST** be named identical to the VNF Heat Orchestration Template's Base
1089     Module with '.y[a]ml' replaced with '.env'.
1090
1091 Incremental Modules
1092 +++++++++++++++++++
1093
1094
1095 .. req::
1096     :id: R-87247
1097     :target: VNF
1098     :keyword: MUST
1099
1100     A VNF Heat Orchestration Template's Incremental Module file name
1101     **MUST** contain only alphanumeric characters and underscores '_' and
1102     **MUST NOT** contain the case insensitive word 'base'.
1103
1104 .. req::
1105     :id: R-94509
1106     :target: VNF
1107     :keyword: MUST
1108
1109     A VNF Heat Orchestration Template's Incremental Module's Environment
1110     File **MUST** be named identical to the VNF Heat Orchestration Template's
1111     Incremental Module with '.y[a]ml' replaced with '.env'.
1112
1113 To clearly identify the incremental module, it is recommended to use the
1114 following naming options for modules:
1115
1116  -  module_<text>.y[a]ml
1117
1118  -  <text>_module.y[a]ml
1119
1120  -  module.y[a]ml
1121
1122  -  <text>_module_<text>.y[a]ml
1123
1124 Cinder Volume Modules
1125 +++++++++++++++++++++
1126
1127
1128 .. req::
1129     :id: R-82732
1130     :target: VNF
1131     :keyword: MUST
1132
1133     A VNF Heat Orchestration Template's Cinder Volume Module **MUST** be
1134     named identical to the base or incremental module it is supporting with
1135     '_volume appended'
1136
1137 .. req::
1138     :id: R-31141
1139     :target: VNF
1140     :keyword: MUST
1141
1142     A VNF Heat Orchestration Template's Cinder Volume Module's Environment
1143     File **MUST** be named identical to the VNF Heat Orchestration Template's
1144     Cinder Volume Module with .y[a]ml replaced with '.env'.
1145
1146 Nested Heat file
1147 ++++++++++++++++
1148
1149
1150 .. req::
1151     :id: R-76057
1152     :target: VNF
1153     :keyword: MUST
1154
1155     A VNF Heat Orchestration Template's Nested YAML file name **MUST**
1156     contain only alphanumeric characters and underscores '_' and **MUST NOT**
1157     contain the case insensitive word 'base'.
1158
1159 .. req::
1160     :id: R-70276
1161     :target: VNF
1162     :keyword: MUST NOT
1163     :test: no test found
1164     :test_case: no test found
1165     :test_file: no test found
1166
1167     A VNF HEAT's Orchestration Nested Template's YAML file
1168     name **MUST NOT** be in the format '{vm-type}.y[a]ml' where
1169     '{vm-type}' is defined in the Heat Orchestration Template.
1170
1171 Examples include
1172
1173  -  <text>.y[a]ml
1174
1175  -  nest_<text>.y[a]ml
1176
1177  -  <text>_nest.y[a]ml
1178
1179  -  nest.y[a]ml
1180
1181  -  <text>_nest_<text>.y[a]ml
1182
1183 VNF Heat Orchestration Template's Nested YAML file does not have a
1184 corresponding environment files, per OpenStack specifications.
1185
1186 Output Parameters
1187 ~~~~~~~~~~~~~~~~~
1188
1189 The output parameters are parameters defined in the output section of a
1190 Heat Orchestration Template. The ONAP output parameters are subdivided
1191 into three categories:
1192
1193 1. ONAP Base Module Output Parameters
1194
1195 2. ONAP Volume Module Output Parameters
1196
1197 3. ONAP Predefined Output Parameters.
1198
1199 ONAP Base Module Output Parameters
1200 ++++++++++++++++++++++++++++++++++++
1201
1202 ONAP Base Module Output Parameters are declared in the 'outputs:'' section of
1203 the VNF's Heat Orchestration Template's Base Module. A Base Module Output
1204 Parameter is available as an input parameter (i.e., declared in the
1205 'parameters:'' section) to all Incremental Modules in the VNF.
1206
1207 A Base Module Output Parameter may be used as an input parameter in any
1208 incremental module in the VNF.  Note that the parameter is not
1209 available to other VNFs.
1210
1211
1212 .. req::
1213     :id: R-52753
1214     :target: VNF
1215     :keyword: MUST
1216
1217     VNF's Heat Orchestration Template's Base Module's output parameter's
1218     name and type **MUST** match the VNF's Heat Orchestration Template's
1219     incremental Module's name and type unless the output parameter is of type
1220     'comma_delimited_list', then the corresponding input parameter **MUST**
1221     be declared as type 'json'.
1222
1223 If the Output parameter has a comma_delimited_list value (e.g., a collection
1224 of UUIDs from a Resource Group), then the corresponding input parameter
1225 must be declared as type json and not a comma_delimited_list, which is
1226 actually a string value with embedded commas.
1227
1228
1229 .. req::
1230     :id: R-22608
1231     :target: VNF
1232     :keyword: MUST NOT
1233
1234     When a VNF's Heat Orchestration Template's Base Module's output
1235     parameter is declared as an input parameter in an Incremental Module,
1236     the parameter attribute 'constraints:' **MUST NOT** be declared.
1237
1238 Additional details on ONAP Base Module Output Parameters are provided in
1239 `ONAP Output Parameter Names`_ and ONAP VNF Modularity.
1240
1241 ONAP Volume Module Output Parameters
1242 ++++++++++++++++++++++++++++++++++++
1243
1244
1245 .. req::
1246     :id: R-89913
1247     :target: VNF
1248     :keyword: MUST
1249
1250     A VNF's Heat Orchestration Template's Cinder Volume Module Output
1251     Parameter(s) **MUST** include the UUID(s) of the Cinder Volumes created in
1252     template, while other Output Parameters **MAY** be included.
1253
1254 A VNF's Heat Orchestration Template's Cinder Volume Module Output Parameter(s)
1255 are only available for the module (base or incremental) that the volume
1256 template is associated with.
1257
1258
1259 .. req::
1260     :id: R-07443
1261     :target: VNF
1262     :keyword: MUST
1263
1264     A VNF's Heat Orchestration Templates' Cinder Volume Module Output
1265     Parameter's name and type **MUST** match the input parameter name and type
1266     in the corresponding Base Module or Incremental Module unless the Output
1267     Parameter is of the type 'comma\_delimited\_list', then the corresponding input
1268     parameter **MUST** be declared as type 'json'.
1269
1270 If the Output parameter has a comma_delimited_list value (e.g., a collection
1271 of UUIDs from a Resource Group), then the corresponding input parameter must
1272 be declared as type json and not a comma\_delimited\_list, which is actually a
1273 string value with embedded commas.
1274
1275
1276 .. req::
1277     :id: R-20547
1278     :target: VNF
1279     :keyword: MUST NOT
1280
1281     When an ONAP Volume Module Output Parameter is declared as an input
1282     parameter in a base or an incremental module Heat Orchestration Template,
1283     parameter constraints **MUST NOT** be declared.
1284
1285 Additional details on ONAP Base Module Output Parameters are provided in
1286 `ONAP Output Parameter Names`_ and `Cinder Volumes`_.
1287
1288 ONAP Predefined Output Parameters
1289 +++++++++++++++++++++++++++++++++++
1290
1291 ONAP will look for a small set of pre-defined Heat output parameters to
1292 capture resource attributes for inventory in ONAP. These output parameters
1293 are optional and currently only two parameters are supported. These output
1294 parameters are optional and are specified in `OAM Management IP Addresses`_.
1295
1296 Support of heat stack update
1297 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1298
1299 ONAP does not support the use of heat stack-update command for scaling
1300 (growth/de-growth).
1301
1302
1303 .. req::
1304     :id: R-39349
1305     :target: VNF
1306     :keyword: MUST NOT
1307
1308     A VNF Heat Orchestration Template **MUST NOT** be designed to
1309     utilize the OpenStack 'heat stack-update' command for scaling
1310     (growth/de-growth).
1311
1312 .. req::
1313     :id: R-43413
1314     :target: VNF
1315     :keyword: MUST
1316
1317     A VNF **MUST** utilize a modular Heat Orchestration Template
1318     design to support scaling (growth/de-growth).
1319
1320 Scope of a Heat Orchestration Template
1321 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1322
1323
1324 .. req::
1325     :id: R-59482
1326     :target: VNF
1327     :keyword: MUST NOT
1328
1329     A VNF's Heat Orchestration Template **MUST NOT** be VNF instance
1330     specific or Cloud site specific.
1331
1332 ONAP provides the instance specific parameter values to the Heat
1333 Orchestration Template at orchestration time.
1334
1335
1336 .. req::
1337     :id: R-01896
1338     :target: VNF
1339     :keyword: MUST
1340
1341     A VNF's Heat Orchestration Template's parameter values that are
1342     constant across all deployments **MUST** be declared in a Heat Orchestration
1343     Template Environment File.
1344
1345 Networking
1346 ^^^^^^^^^^
1347
1348 ONAP defines two types of networks: External Networks and Internal Networks.
1349
1350 External Networks
1351 ~~~~~~~~~~~~~~~~~
1352
1353 ONAP defines an external network in relation to the VNF and not with regard
1354 to the Network Cloud site. External networks may also be referred to as
1355 "inter-VNF" networks.  An external network must connect VMs in a VNF to
1356 VMs in another VNF or an external gateway or external router.
1357
1358 An External Network may be a Neutron Network or a Contrail Network.
1359
1360
1361 .. req::
1362     :id: R-16968
1363     :target: VNF
1364     :keyword: MUST NOT
1365
1366     A VNF's Heat Orchestration Templates **MUST NOT** include heat
1367     resources to create external networks.
1368
1369 External networks must be orchestrated separately, independent of the VNF.
1370 This allows the network to be shared by multiple VNFs and managed
1371 independently of VNFs.
1372
1373
1374 .. req::
1375     :id: R-00606
1376     :target: VNF
1377     :keyword: MAY
1378
1379     A VNF **MAY** be connected to zero, one or more than one external
1380     networks.
1381
1382 .. req::
1383     :id: R-57424
1384     :target: VNF
1385     :keyword: MUST
1386
1387     A VNF's port connected to an external network **MUST**
1388     use the port for the purpose of reaching VMs in another VNF
1389     and/or an external gateway and/or external router. A VNF's port
1390     connected to an external network **MAY** use the port for
1391     the purpose of reaching VMs in the same VNF.
1392
1393 .. req::
1394     :id: R-29865
1395     :target: VNF
1396     :keyword: MUST
1397
1398     When a VNF connects to an external network, a network role,
1399     referred to as the '{network-role}' **MUST** be assigned to the
1400     external network for use in the VNF's Heat Orchestration Template.
1401
1402 .. req::
1403     :id: R-69014
1404     :target: VNF
1405     :keyword: MUST
1406
1407     When a VNF connects to an external network, a network role, referred
1408     to as the '{network-role}' **MUST** be assigned to the external network
1409     for use in the VNF's Heat Orchestration Template.
1410
1411 .. req::
1412     :id: R-05201
1413     :target: VNF
1414     :keyword: MUST
1415
1416     When a VNF connects to two or more external networks, each external
1417     network **MUST** be assigned a unique '{network-role}' in the context of
1418     the VNF for use in the VNF's Heat Orchestration Template.
1419
1420 .. req::
1421     :id: R-83015
1422     :target: VNF
1423     :keyword: MUST
1424
1425     A VNF's '{network-role}' assigned to an external network **MUST**
1426     be different than the '{network-role}' assigned to the VNF's internal
1427     networks, if internal networks exist.
1428
1429 .. req::
1430     :id: R-99794
1431     :target: VNF
1432     :keyword: MUST
1433     :test: no test found
1434     :test_case: no test found
1435     :test_file: no test found
1436
1437     An external network **MUST** have one subnet. An external network
1438     **MAY** have more than one subnet.
1439
1440 Note that this document refers to **'{network-role}'** which in reality
1441 is the **'{network-role-tag}'**.  The value of the
1442 '{network-role}' / '{network-role-tag}'
1443 is determined by the designer of the VNF's Heat Orchestration Template and
1444 there is no requirement for '{network-role}' / '{network-role-tag}'
1445 uniqueness across Heat Orchestration Templates for
1446 different VNFs.
1447
1448 When an external network is created by ONAP, the network is assigned a
1449 '{network-role}'.  The '{network-role}' of the network is not required to
1450 match the '{network-role}' of the VNF Heat Orchestration Template.
1451
1452 For example, the VNF Heat Orchestration Template can assign a '{network-role}'
1453 of 'oam' to a network which attaches to an external network with a
1454 '{network-role}' of 'oam_protected_1' .
1455
1456 When the Heat Orchestration Template is on-boarded into ONAP
1457   * each '{network-role}' value in the Heat Orchestration Template
1458     is mapped to the '{network-role-tag}' in the ONAP
1459     data structure.
1460   * each OS::Neutron::Port is associated with the external network it is
1461     connecting to, thus creating the VNF Heat Orchestration Template
1462     '{network-role}' / '{network-role-tag}' to external network '{network-role}'
1463     mapping.
1464
1465 ONAP enforces a naming convention for parameters associated with
1466 external networks. `ONAP Resource ID and Parameter Naming Convention`_
1467 provides additional details.
1468
1469 Internal Networks
1470 ~~~~~~~~~~~~~~~~~
1471
1472 ONAP defines an internal network in relation to the VNF and not with
1473 regard to the Network Cloud site. Internal networks may also be referred
1474 to as "intra-VNF" networks or "private" networks. An internal network
1475 only connects VMs in a single VNF; it must not connect to other VNFs
1476 or an external gateway or router
1477
1478
1479 .. req::
1480     :id: R-87096
1481     :target: VNF
1482     :keyword: MAY
1483
1484     A VNF **MAY** contain zero, one or more than one internal networks.
1485
1486 .. req::
1487     :id: R-35666
1488     :target: VNF
1489     :keyword: MUST
1490
1491     If a VNF has an internal network, the VNF Heat Orchestration
1492     Template **MUST** include the heat resources to create the internal network.
1493
1494 .. req::
1495     :id: R-86972
1496     :target: VNF
1497     :keyword: SHOULD
1498
1499     A VNF **SHOULD** create the internal network in the VNF's Heat
1500     Orchestration Template Base Module.
1501
1502 An Internal Network may be created using Neutron Heat Resources and/or
1503 Contrail Heat Resources.
1504
1505
1506 .. req::
1507     :id: R-52425
1508     :target: VNF
1509     :keyword: MUST
1510
1511     A VNF's port connected to an internal network **MUST** connect
1512     the port to VMs in the same VNF.
1513
1514 .. req::
1515     :id: R-46461
1516     :target: VNF
1517     :keyword: MUST NOT
1518
1519     A VNF's port connected to an internal network **MUST NOT** connect
1520     the port to VMs in another VNF and/or an external gateway and/or
1521     external router.
1522
1523 .. req::
1524     :id: R-68936
1525     :target: VNF
1526     :keyword: MUST
1527
1528     When a VNF creates an internal network, a network role, referred to
1529     as the '{network-role}' **MUST** be assigned to the internal network for
1530     use in the VNF's Heat Orchestration Template.
1531
1532 .. req::
1533     :id: R-32025
1534     :target: VNF
1535     :keyword: MUST
1536
1537     When a VNF creates two or more internal networks, each internal
1538     network **MUST** be assigned a unique '{network-role}' in the context of
1539     the VNF for use in the VNF's Heat Orchestration Template.
1540
1541 .. req::
1542     :id: R-69874
1543     :target: VNF
1544     :keyword: MUST
1545
1546     A VNF's '{network-role}' assigned to an internal network **MUST**
1547     be different than the '{network-role}' assigned to the VNF's external
1548     networks.
1549
1550 .. req::
1551     :id: R-16241
1552     :target: VNF
1553     :keyword: MUST
1554     :test: no test found
1555     :test_case: no test found
1556     :test_file: no test found
1557
1558     A VNF's internal network **MUST** have one subnet.
1559     A VNF's internal network **MAY** have more than one subnet.
1560
1561 .. req::
1562     :id: R-34726
1563     :target: VNF
1564     :keyword: MUST
1565
1566     If a VNF's port is connected to an internal network and the port
1567     is created in the same Heat Orchestration Template as the internal network,
1568     then the port resource **MUST** use a 'get_resource' to obtain
1569     the network UUID.
1570
1571 .. req::
1572     :id: R-22688
1573     :target: VNF
1574     :keyword: MUST
1575
1576     If a VNF's port is connected to an internal network and the
1577     port is created in an Incremental Module and the internal
1578     network is created in the Base Module then the UUID of the
1579     internal network **MUST** be exposed
1580     as a parameter in the 'outputs:' section of the Base Module and the port
1581     resource **MUST** use a 'get_param' to obtain the network UUID.
1582
1583 ONAP does not programmatically enforce a naming convention for
1584 parameters for internal network. However, a naming convention is
1585 provided that must be followed.
1586 `ONAP Resource ID and Parameter Naming Convention`_
1587 provides additional details.
1588
1589 ONAP Resource ID and Parameter Naming Convention
1590 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1591
1592 This section provides the ONAP naming requirements for
1593
1594 1. Resource IDs
1595
1596 2. Resource Property Parameters
1597
1598 {vm-type}
1599 ~~~~~~~~~
1600
1601
1602 .. req::
1603     :id: R-01455
1604     :target: VNF
1605     :keyword: MUST
1606
1607     When a VNF's Heat Orchestration Template creates a
1608     Virtual Machine  (i.e., 'OS::Nova::Server'), each 'class' of VMs
1609     **MUST** be assigned a VNF unique '{vm-type}'; where 'class'
1610     defines VMs that **MUST** have the following identical characteristics:
1611
1612       1.) OS::Nova::Server property flavor value
1613
1614       2.) OS::Nova::Server property image value
1615
1616       3.) Cinder Volume attachments
1617         - Each VM in the 'class' **MUST** have the identical Cinder Volume
1618           configuration
1619
1620       4.) Network attachments and IP address requirements
1621         - Each VM in the 'class' **MUST** have the the identical number
1622           of ports connecting to the identical networks and requiring the
1623           identical IP address configuration.
1624
1625 .. req::
1626     :id: R-82481
1627     :target: VNF
1628     :keyword: MUST
1629
1630     A VNF's Heat Orchestration Template's Resource property
1631     parameter that is associated with a unique Virtual Machine
1632     type **MUST** include '{vm-type}'  as part of the parameter
1633     name with two exceptions:
1634
1635       1.) The Resource OS::Nova::Server property availability_zone parameter
1636       **MUST NOT** be prefixed with a common '{vm-type} identifier,
1637
1638       2.) The Resource OS::Nova::Server eight mandatory and optional metadata
1639       parameters (vnf_name, vnf_id, vf_module_id, vf_module_name, vm_role,
1640       vf_module_index, environment_context, workload_context) **MUST NOT**
1641       be prefixed with a common '{vm-type}' identifier.
1642
1643 .. req::
1644     :id: R-66729
1645     :target: VNF
1646     :keyword: MUST
1647
1648     A VNF's Heat Orchestration Template's Resource that is
1649     associated with a unique Virtual Machine type **MUST** include
1650     '{vm-type}' as part of the resource ID.
1651
1652 .. req::
1653     :id: R-98407
1654     :target: VNF
1655     :keyword: MUST NOT
1656
1657     A VNF's Heat Orchestration Template's '{vm-type}' **MUST** contain
1658     only alphanumeric characters and/or underscores '_' and
1659     **MUST NOT** contain any of the following strings: '_int' or 'int\_'
1660     or '\_int\_'.
1661
1662 .. req::
1663     :id: R-48067
1664     :target: VNF
1665     :keyword: MUST NOT
1666
1667     A VNF's Heat Orchestration Template's {vm-type} **MUST NOT** be a
1668     substring of {network-role}.
1669
1670 It may cause the VNF Validation Program validation-scripts project
1671 to produce erroneous error messages.
1672
1673
1674 .. req::
1675     :id: R-32394
1676     :target: VNF
1677     :keyword: MUST
1678
1679     A VNF's Heat Orchestration Template's use of '{vm-type}'
1680     in all Resource property parameter names **MUST** be the same case.
1681
1682 .. req::
1683     :id: R-46839
1684     :target: VNF
1685     :keyword: MUST
1686
1687     A VNF's Heat Orchestration Template's use of
1688     '{vm-type}' in all Resource IDs **MUST** be the same case.
1689
1690 .. req::
1691     :id: R-36687
1692     :target: VNF
1693     :keyword: SHOULD
1694
1695     A VNF's Heat Orchestration Template's '{vm-type}' case in
1696     Resource property parameter names **SHOULD** match the case of
1697     '{vm-type}' in Resource IDs and vice versa.
1698
1699 {network-role}
1700 ~~~~~~~~~~~~~~
1701
1702 The assignment of a {network-role} is discussed in `Networking`_.
1703
1704
1705 .. req::
1706     :id: R-21330
1707     :target: VNF
1708     :keyword: MUST
1709
1710     A VNF's Heat Orchestration Template's Resource property
1711     parameter that is associated with external network **MUST**
1712     include the '{network-role}' as part of the parameter name.
1713
1714 .. req::
1715     :id: R-11168
1716     :target: VNF
1717     :keyword: MUST
1718
1719     A VNF's Heat Orchestration Template's Resource ID that is
1720     associated with an external network **MUST** include the
1721     '{network-role}' as part of the resource ID.
1722
1723 .. req::
1724     :id: R-84322
1725     :target: VNF
1726     :keyword: MUST
1727
1728     A VNF's Heat Orchestration Template's Resource property
1729     parameter that is associated with an internal network
1730     **MUST** include 'int\_{network-role}' as part of the parameter
1731     name, where 'int\_' is a hard coded string.
1732
1733 .. req::
1734     :id: R-96983
1735     :target: VNF
1736     :keyword: MUST
1737
1738     A VNF's Heat Orchestration Template's Resource ID that is
1739     associated with an internal network **MUST** include
1740     'int\_{network-role}' as part of the Resource ID, where
1741     'int\_' is a hard coded string.
1742
1743 .. req::
1744     :id: R-26506
1745     :target: VNF
1746     :keyword: MUST
1747
1748     A VNF's Heat Orchestration Template's '{network-role}'
1749     **MUST** contain only alphanumeric characters and/or
1750     underscores '_' and **MUST NOT** contain any of the following
1751     strings: '_int' or 'int\_' or '\_int\_'.
1752
1753 .. req::
1754     :id: R-00977
1755     :target: VNF
1756     :keyword: MUST NOT
1757
1758     A VNF's Heat Orchestration Template's '{network-role}'
1759     **MUST NOT** be a substring of '{vm-type}'.
1760
1761 For example, if a VNF has a '{vm-type}' of 'oam' and a
1762 '{network-role}' of 'oam\_protected' would be a violation of the requirement.
1763
1764
1765 .. req::
1766     :id: R-58424
1767     :target: VNF
1768     :keyword: MUST
1769
1770     A VNF's Heat Orchestration Template's use of '{network-role}'
1771     in all Resource property parameter names **MUST** be the same case.
1772
1773 .. req::
1774     :id: R-21511
1775     :target: VNF
1776     :keyword: MUST
1777
1778     A VNF's Heat Orchestration Template's use of '{network-role}'
1779     in all Resource IDs **MUST** be the same case.
1780
1781 .. req::
1782     :id: R-86588
1783     :target: VNF
1784     :keyword: SHOULD
1785
1786     A VNF's Heat Orchestration Template's '{network-role}' case
1787     in Resource property parameter names **SHOULD** match the case
1788     of '{network-role}' in Resource IDs and vice versa.
1789
1790 Resource IDs
1791 ~~~~~~~~~~~~
1792
1793 Requirement R-75141 states a VNF's Heat Orchestration Template's
1794 resource name (i.e., <resource ID>) MUST only contain alphanumeric
1795 characters and underscores ('_').*
1796
1797 Requirement R-16447 states a VNF's <resource ID> MUST be unique
1798 across all Heat Orchestration Templates and all HEAT Orchestration
1799 Template Nested YAML files that are used to create the VNF.
1800
1801 As stated previously, OpenStack requires the <resource ID> to be unique
1802 to the Heat Orchestration Template and not unique across all Heat
1803 Orchestration Templates the compose the VNF.
1804
1805 Heat Orchestration Template resources are described in `resources`_
1806
1807
1808 .. req::
1809     :id: R-54517
1810     :target: VNF
1811     :keyword: MUST
1812
1813     When a VNF's Heat Orchestration Template's resource is associated
1814     with a single '{vm-type}', the Resource ID **MUST** contain the '{vm-type}'.
1815
1816 .. req::
1817     :id: R-96482
1818     :target: VNF
1819     :keyword: MUST
1820
1821     When a VNF's Heat Orchestration Template's resource is associated
1822     with a single external network, the Resource ID **MUST** contain the text
1823     '{network-role}'.
1824
1825 .. req::
1826     :id: R-98138
1827     :target: VNF
1828     :keyword: MUST
1829
1830     When a VNF's Heat Orchestration Template's resource is associated
1831     with a single internal network, the Resource ID **MUST** contain the text
1832     'int\_{network-role}'.
1833
1834 .. req::
1835     :id: R-82115
1836     :target: VNF
1837     :keyword: MUST
1838
1839     When a VNF's Heat Orchestration Template's resource is associated
1840     with a single '{vm-type}' and a single external network, the Resource
1841     ID text **MUST** contain both the '{vm-type}' and the '{network-role}'
1842
1843       - the '{vm-type}' **MUST** appear before the '{network-role}' and **MUST**
1844         be separated by an underscore '_'
1845
1846           - e.g.,'{vm-type}\_{network-role}', '{vm-type}\_{index}\_{network-role}'
1847
1848       - note that an '{index}' value **MAY** separate the '{vm-type}' and the
1849         '{network-role}' and when this occurs underscores **MUST** separate the
1850         three values.
1851
1852 .. req::
1853     :id: R-82551
1854     :target: VNF
1855     :keyword: MUST
1856
1857     When a VNF's Heat Orchestration Template's resource is associated
1858     with a single '{vm-type}' and a single internal network, the Resource ID
1859     **MUST** contain both the '{vm-type}' and the 'int\_{network-role}' and
1860
1861       - the '{vm-type}' **MUST** appear before the 'int\_{network-role}' and
1862       **MUST** be separated by an underscore '_'
1863
1864         - e.g.,'{vm-type}\_int\_{network-role}', '{vm-type}_{index}\_int\_{network-role}'
1865
1866       - note that an '{index}' value **MAY** separate the '{vm-type}' and the
1867         'int\_{network-role}' and when this occurs underscores **MUST** separate
1868         the three values.
1869
1870 .. req::
1871     :id: R-67793
1872     :target: VNF
1873     :keyword: MUST NOT
1874
1875     When a VNF's Heat Orchestration Template's resource is associated
1876     with more than one '{vm-type}' and/or more than one internal and/or
1877     external network, the Resource ID **MUST NOT** contain the '{vm-type}'
1878     and/or '{network-role}'/'int\_{network-role}'. It also should contain the
1879     term 'shared' and/or contain text that identifies the VNF
1880
1881 .. req::
1882     :id: R-27970
1883     :target: VNF
1884     :keyword: MAY
1885
1886     When a VNF's Heat Orchestration Template's resource is associated
1887     with more than one '{vm-type}' and/or more than one internal and/or
1888     external network, the Resource ID **MAY** contain the term 'shared'
1889     and/or **MAY** contain text that identifies the VNF.
1890
1891 .. req::
1892     :id: R-11690
1893     :target: VNF
1894     :keyword: MUST
1895
1896     When a VNF's Heat Orchestration Template's Resource ID contains
1897     an {index} value (e.g. multiple VMs of same {vm-type}), the '{index}'
1898     **MUST** start at zero and increment by one.
1899
1900 OpenStack Heat Resources Resource ID Naming Convention
1901 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
1902
1903 Some OpenStack Heat Resources Resource IDs
1904 have mandatory or suggested naming conventions.  They are provided
1905 in the following sections.
1906
1907 OS::Cinder::Volume
1908 __________________
1909
1910
1911 .. req::
1912     :id: R-87004
1913     :target: VNF
1914     :keyword: SHOULD
1915     :test: no test found
1916     :test_case: no test found
1917     :test_file: no test found
1918
1919     A VNF's Heat Orchestration Template's Resource
1920     OS::Cinder::Volume Resource ID **SHOULD** use the naming convention
1921
1922        * {vm-type}_volume_{index}
1923
1924     where
1925
1926        * {vm-type} is the vm-type
1927        * {index} starts at zero and increments by one
1928
1929 OS::Cinder::VolumeAttachment
1930 ____________________________
1931
1932
1933 .. req::
1934     :id: R-86497
1935     :target: VNF
1936     :keyword: SHOULD
1937     :test: no test found
1938     :test_case: no test found
1939     :test_file: no test found
1940
1941     A VNF's Heat Orchestration Template's Resource
1942     OS::Cinder::VolumeAttachment Resource ID **SHOULD** use the naming convention
1943
1944        * {vm-type}_volume_attachment_{index}
1945
1946     where
1947
1948        * {vm-type} is the vm-type
1949        * {index} starts at zero and increments by one
1950
1951 OS::Heat::CloudConfig
1952 _____________________
1953
1954
1955 .. req::
1956     :id: R-04747
1957     :target: VNF
1958     :keyword: MUST
1959     :test: no test found
1960     :test_case: no test found
1961     :test_file: no test found
1962
1963     A VNF's Heat Orchestration Template's Resource
1964     'OS::Heat::CloudConfig' Resource ID **MUST** contain the '{vm-type}'.
1965
1966 .. req::
1967     :id: R-20319
1968     :target: VNF
1969     :keyword: MAY
1970     :test: no test found
1971     :test_case: no test found
1972     :test_file: no test found
1973
1974     A VNF's Heat Orchestration Template's Resource 'OS::Heat::CloudConfig'
1975     Resource ID **MAY** use the naming convention
1976
1977        * {vm-type}_RCC
1978
1979     where
1980
1981        * {vm-type} is the vm-type
1982        * 'RCC' signifies that it is the Resource Cloud Config
1983
1984 OS::Heat::MultipartMime
1985 _______________________
1986
1987
1988 .. req::
1989     :id: R-30804
1990     :target: VNF
1991     :keyword: MUST
1992     :test: no test found
1993     :test_case: no test found
1994     :test_file: no test found
1995
1996     A VNF's Heat Orchestration Template's Resource
1997     'OS::Heat::MultipartMime' Resource ID **MUST** contain the '{vm-type}'.
1998
1999 .. req::
2000     :id: R-18202
2001     :target: VNF
2002     :keyword: MAY
2003     :test: no test found
2004     :test_case: no test found
2005     :test_file: no test found
2006
2007     A VNF's Heat Orchestration Template's Resource
2008     'OS::Heat::MultipartMime' Resource ID **MAY** use the naming convention
2009
2010        * {vm-type}_RMM
2011
2012     where
2013
2014        * {vm-type} is the vm-type
2015        * 'RMM' signifies that it is the Resource Multipart Mime
2016
2017 OS::Heat::ResourceGroup
2018 _______________________
2019
2020 There is only a mandatory naming convention for a 'OS::Heat::ResourceGroup'
2021 that is is creating sub-interfaces.
2022
2023
2024 .. req::
2025     :id: R-64197
2026     :target: VNF
2027     :keyword: MUST
2028     :test: no test found
2029     :test_case: no test found
2030     :test_file: no test found
2031
2032     A VNF's Heat Orchestration Template's Resource
2033     OS::Heat::ResourceGroup Resource ID that creates sub-interfaces **MUST**
2034     use the naming convention
2035
2036        * {vm-type}_{vm-type_index}_subint_{network-role}_port_{port-index}_subinterfaces
2037
2038     where
2039
2040        * {vm-type} is the vm-type
2041        * {vm-type_index} is the instance of the {vm-type}
2042        * {network-role} is the network-role of the networks
2043          that the sub-interfaces attach to
2044        * {port-index} is the instance of the the port on the vm-type
2045          attached to the network of {network-role}
2046
2047 OS::Heat::SoftwareConfig
2048 ________________________
2049
2050
2051 .. req::
2052     :id: R-08975
2053     :target: VNF
2054     :keyword: MUST
2055     :test: no test found
2056     :test_case: no test found
2057     :test_file: no test found
2058
2059     A VNF's Heat Orchestration Template's Resource
2060     'OS::Heat::SoftwareConfig' Resource ID **MUST** contain the '{vm-type}'.
2061
2062 .. req::
2063     :id: R-03656
2064     :target: VNF
2065     :keyword: MAY
2066     :test: no test found
2067     :test_case: no test found
2068     :test_file: no test found
2069
2070     A VNF's Heat Orchestration Template's Resource
2071     'OS::Heat::SoftwareConfig' Resource ID **MAY** use the naming convention
2072
2073        * {vm-type}_RSC
2074
2075     where
2076
2077        * {vm-type} is the vm-type
2078        * 'RSC' signifies that it is the Resource Software Config
2079
2080 OS::Neutron::Net
2081 ________________
2082
2083
2084 .. req::
2085     :id: R-25720
2086     :target: VNF
2087     :keyword: MUST
2088     :test: no test found
2089     :test_case: no test found
2090     :test_file: no test found
2091
2092     A VNF's Heat Orchestration Template's Resource
2093     OS::Neutron::Net Resource ID **MUST** use the naming convention
2094
2095        * int_{network-role}_network
2096
2097 VNF Heat Orchestration Templates can only create internal networks.
2098 There is no {index} after {network-role} because {network-role}
2099 **MUST** be unique in the scope of the VNF's
2100 Heat Orchestration Template.
2101
2102 OS::Neutron::Port
2103 _________________
2104
2105
2106 .. req::
2107     :id: R-20453
2108     :target: VNF
2109     :keyword: MUST
2110     :test: no test found
2111     :test_case: no test found
2112     :test_file: no test found
2113
2114     A VNF's Heat Orchestration Template's Resource
2115     OS::Neutron::Port that is attaching to an external network Resource ID
2116     **MUST** use the naming convention
2117
2118        * {vm-type}_{vm-type_index}_{network-role}_port_{port-index}
2119
2120     where
2121
2122        * {vm-type} is the vm-type
2123        * {vm-type_index} is the instance of the {vm-type}
2124        * {network-role} is the network-role of the network
2125          that the port is attached to
2126        * {port-index} is the instance of the the port on the vm-type
2127          attached to the network of {network-role}
2128
2129 .. req::
2130     :id: R-26351
2131     :target: VNF
2132     :keyword: MUST
2133     :test: no test found
2134     :test_case: no test found
2135     :test_file: no test found
2136
2137     A VNF's Heat Orchestration Template's Resource
2138     OS::Neutron::Port that is attaching to an internal network Resource ID
2139     **MUST** use the naming convention
2140
2141        * {vm-type}_{vm-type_index}_int_{network-role}_port_{port-index}
2142
2143     where
2144
2145        * {vm-type} is the vm-type
2146        * {vm-type_index} is the instance of the {vm-type}
2147        * {network-role} is the network-role of the network
2148          that the port is attached to
2149        * {port-index} is the instance of the the port on the vm-type
2150          attached to the network of {network-role}
2151
2152 .. req::
2153     :id: R-27469
2154     :target: VNF
2155     :keyword: MUST
2156     :test: no test found
2157     :test_case: no test found
2158     :test_file: no test found
2159
2160     A VNF's Heat Orchestration Template's Resource
2161     OS::Neutron::Port that is creating a *Reserve Port* with an IPv4 address
2162     Resource ID **MUST** use the naming convention
2163
2164        * reserve_port_{vm-type}_{network-role}_floating_ip_{index}
2165
2166     where
2167
2168        * {vm-type} is the vm-type
2169        * {network-role} is the network-role of the network
2170          that the port is attached to
2171        * {index} is the instance of the IPv4 *Reserve Port*
2172          for the vm-type attached to the network of {network-role}
2173
2174 .. req::
2175     :id: R-68520
2176     :target: VNF
2177     :keyword: MUST
2178     :test: no test found
2179     :test_case: no test found
2180     :test_file: no test found
2181
2182     A VNF's Heat Orchestration Template's Resource OS::Neutron::Port
2183     that is creating a *Reserve Port* with an IPv6 address Resource ID
2184     **MUST** use the naming convention
2185
2186        * reserve_port_{vm-type}_{network-role}_floating_v6_ip_{index}
2187
2188     where
2189
2190        * {vm-type} is the vm-type
2191        * {network-role} is the network-role of the network
2192          that the port is attached to
2193        * {index} is the instance of the IPv6 *Reserve Port*
2194          for the vm-type attached to the network of {network-role}
2195
2196 OS::Neutron::SecurityGroup
2197 __________________________
2198
2199
2200 .. req::
2201     :id: R-08775
2202     :target: VNF
2203     :keyword: SHOULD
2204     :test: no test found
2205     :test_case: no test found
2206     :test_file: no test found
2207
2208     A VNF's Heat Orchestration Template's Resource
2209     OS::Neutron::SecurityGroup that is applicable to one {vm-type} and
2210     more than one network (internal and/or external) Resource ID
2211     **SHOULD** use the naming convention
2212
2213        * {vm-type}_security_group
2214
2215     where
2216
2217        * {vm-type} is the vm-type
2218
2219 .. req::
2220     :id: R-03595
2221     :target: VNF
2222     :keyword: SHOULD
2223     :test: no test found
2224     :test_case: no test found
2225     :test_file: no test found
2226
2227     A VNF's Heat Orchestration Template's Resource
2228     OS::Neutron::SecurityGroup that is applicable to more than
2229     one {vm-type} and one external network Resource ID **SHOULD**
2230     use the naming convention
2231
2232        * {network-role}_security_group
2233
2234     where
2235
2236        * {network-role} is the network-role
2237
2238 .. req::
2239     :id: R-73213
2240     :target: VNF
2241     :keyword: SHOULD
2242     :test: no test found
2243     :test_case: no test found
2244     :test_file: no test found
2245
2246     A VNF's Heat Orchestration Template's Resource
2247     OS::Neutron::SecurityGroup that is applicable to more than
2248     one {vm-type} and one internal network Resource ID **SHOULD**
2249     use the naming convention
2250
2251        * int_{network-role}_security_group
2252
2253     where
2254
2255        * {network-role} is the network-role
2256
2257 .. req::
2258     :id: R-17334
2259     :target: VNF
2260     :keyword: SHOULD
2261     :test: no test found
2262     :test_case: no test found
2263     :test_file: no test found
2264
2265     A VNF's Heat Orchestration Template's Resource
2266     OS::Neutron::SecurityGroup that is applicable to one {vm-type}
2267     and one external network Resource ID **SHOULD** use the naming convention
2268
2269        * {vm-type}_{network-role}_security_group
2270
2271     where
2272
2273        * {vm-type} is the vm-type
2274        * {network-role} is the network-role
2275
2276 .. req::
2277     :id: R-14198
2278     :target: VNF
2279     :keyword: SHOULD
2280     :test: no test found
2281     :test_case: no test found
2282     :test_file: no test found
2283
2284     A VNF's Heat Orchestration Template's Resource
2285     OS::Neutron::SecurityGroup that is applicable to one {vm-type}
2286     and one internal network Resource ID **SHOULD** use the naming convention
2287
2288        * {vm-type}_int_{network-role}_security_group
2289
2290     where
2291
2292        * {vm-type} is the vm-type
2293        * {network-role} is the network-role
2294
2295 .. req::
2296     :id: R-30005
2297     :target: VNF
2298     :keyword: MAY
2299     :test: no test found
2300     :test_case: no test found
2301     :test_file: no test found
2302
2303     A VNF's Heat Orchestration Template's Resource
2304     OS::Neutron::SecurityGroup that is applicable to more than one
2305     {vm-type} and more than one network (internal and/or external)
2306     Resource ID **MAY** use the naming convention
2307
2308        * shared_security_group
2309
2310     or
2311
2312        * {vnf-type}_security_group
2313
2314     where
2315
2316        * {vnf-type} describes the VNF
2317
2318 OS::Neutron::Subnet
2319 ___________________
2320
2321
2322 .. req::
2323     :id: R-59434
2324     :target: VNF
2325     :keyword: SHOULD
2326     :test: no test found
2327     :test_case: no test found
2328     :test_file: no test found
2329
2330     A VNF's Heat Orchestration Template's Resource
2331     OS::Neutron::Subnet Resource ID **SHOULD** use the naming convention
2332
2333        * int_{network-role}_subnet_{index}
2334
2335     where
2336
2337        * {network-role} is the network-role
2338        * {index} is the {index} of the subnet of the network
2339
2340 OS::Nova::Keypair
2341 _________________
2342
2343
2344 .. req::
2345     :id: R-24997
2346     :target: VNF
2347     :keyword: SHOULD
2348     :test: no test found
2349     :test_case: no test found
2350     :test_file: no test found
2351
2352     A VNF's Heat Orchestration Template's Resource
2353     OS::Nova::Keypair applies to one {vm-type} Resource ID **SHOULD**
2354     use the naming convention
2355
2356        * {vm-type}_keypair_{index}
2357
2358     where
2359
2360        * {network-role} is the network-role
2361        * {index} is the {index} of the keypair
2362
2363 .. req::
2364     :id: R-65516
2365     :target: VNF
2366     :keyword: SHOULD
2367     :test: no test found
2368     :test_case: no test found
2369     :test_file: no test found
2370
2371     A VNF's Heat Orchestration Template's Resource OS::Nova::Keypair
2372     applies to all Virtual Machines in the the VNF, the Resource ID **SHOULD**
2373     use the naming convention
2374
2375        * {vnf-type}_keypair
2376
2377     where
2378
2379        * {vnf-type} describes the VNF
2380
2381 OS::Nova::Server
2382 ________________
2383
2384
2385 .. req::
2386     :id: R-29751
2387     :target: VNF
2388     :keyword: MUST
2389     :test: no test found
2390     :test_case: no test found
2391     :test_file: no test found
2392
2393     A VNF's Heat Orchestration Template's Resource OS::Nova::Server
2394     Resource ID **MUST** use the naming convention
2395
2396        * {vm-type}_server_{index}
2397
2398     where
2399
2400        * {vm-type} is the vm-type
2401        * {index} is the index
2402
2403 OS::Nova::ServerGroup
2404 _____________________
2405
2406
2407 .. req::
2408     :id: R-15189
2409     :target: VNF
2410     :keyword: MAY
2411     :test: no test found
2412     :test_case: no test found
2413     :test_file: no test found
2414
2415     A VNF's Heat Orchestration Template's Resource OS::Nova::ServerGroup
2416     Resource ID **MAY** use the naming convention
2417
2418        * {vm-type}_RSG
2419
2420     or
2421
2422        * {vm-type}_Server_Grp
2423
2424     or
2425
2426        * {vm-type}_ServerGroup
2427
2428     or
2429
2430        * {vm-type}_servergroup
2431
2432 Contrail Heat Resources Resource ID Naming Convention
2433 +++++++++++++++++++++++++++++++++++++++++++++++++++++
2434
2435 Some Contrail Heat Resources Resource IDs
2436 have mandatory or suggested naming conventions. They are provided
2437 in the following sections.
2438
2439
2440 OS::ContrailV2::InstanceIp
2441 __________________________
2442
2443
2444 .. req::
2445     :id: R-53310
2446     :target: VNF
2447     :keyword: MUST
2448     :test: no test found
2449     :test_case: no test found
2450     :test_file: no test found
2451
2452     A VNF's Heat Orchestration Template's Resource
2453     'OS::ContrailV2::InstanceIp' that is configuring an IPv4 Address
2454     on a port attached to an external network Resource ID **MUST**
2455     use the naming convention
2456
2457        *  {vm-type}_{vm-type_index}_{network-role}_vmi_{vmi_index}_IP_{index}
2458
2459     where
2460
2461        * {vm-type} is the vm-type
2462        * {vm-type_index} is the instance of the {vm-type}
2463        * {network-role} is the network-role of the network
2464          that the port is attached to
2465        * {vmi_index} is the instance of the the virtual machine interface
2466          (e.g., port)  on the vm-type
2467          attached to the network of {network-role}
2468        * 'IP' signifies that an IPv4 address is being configured
2469        * {index} is the index of the IPv4 address
2470
2471 .. req::
2472     :id: R-46128
2473     :target: VNF
2474     :keyword: MUST
2475     :test: no test found
2476     :test_case: no test found
2477     :test_file: no test found
2478
2479     A VNF's Heat Orchestration Template's Resource
2480     'OS::ContrailV2::InstanceIp' that is configuring an
2481     IPv6 Address on a port attached to an external network
2482     Resource ID **MUST** use the naming convention
2483
2484        *  {vm-type}_{vm-type_index}_{network-role}_vmi_{vmi_index}_v6_IP_{index}
2485
2486     where
2487
2488        * {vm-type} is the vm-type
2489        * {vm-type_index} is the instance of the {vm-type}
2490        * {network-role} is the network-role of the network
2491          that the port is attached to
2492        * {vmi_index} is the instance of the the virtual machine interface
2493          (e.g., port)  on the vm-type
2494          attached to the network of {network-role}
2495        * 'v6_IP' signifies that an IPv6 address is being configured
2496        * {index} is the index of the IPv6 address
2497
2498 .. req::
2499     :id: R-62187
2500     :target: VNF
2501     :keyword: MUST
2502     :test: no test found
2503     :test_case: no test found
2504     :test_file: no test found
2505
2506     A VNF's Heat Orchestration Template's Resource
2507     'OS::ContrailV2::InstanceIp' that is configuring an
2508     IPv4 Address on a port attached to an internal network
2509     Resource ID **MUST** use the naming convention
2510
2511        *  {vm-type}_{vm-type_index}_int_{network-role}_vmi_{vmi_index}_IP_{index}
2512
2513     where
2514
2515        * {vm-type} is the vm-type
2516        * {vm-type_index} is the instance of the {vm-type}
2517        * {network-role} is the network-role of the network
2518          that the port is attached to
2519        * {vmi_index} is the instance of the the virtual machine interface
2520          (e.g., port)  on the vm-type
2521          attached to the network of {network-role}
2522        * 'IP' signifies that an IPv4 address is being configured
2523        * {index} is the index of the IPv4 address
2524
2525 .. req::
2526     :id: R-87563
2527     :target: VNF
2528     :keyword: MUST
2529     :test: no test found
2530     :test_case: no test found
2531     :test_file: no test found
2532
2533     A VNF's Heat Orchestration Template's Resource
2534     'OS::ContrailV2::InstanceIp' that is configuring an
2535     IPv6 Address on a port attached to an internal network
2536     Resource ID **MUST** use the naming convention
2537
2538        *  {vm-type}_{vm-type_index}_int_{network-role}_vmi_{vmi_index}_v6_IP_{index}
2539
2540     where
2541
2542        * {vm-type} is the vm-type
2543        * {vm-type_index} is the instance of the {vm-type}
2544        * {network-role} is the network-role of the network
2545          that the port is attached to
2546        * {vmi_index} is the instance of the the virtual machine interface
2547          (e.g., port)  on the vm-type
2548          attached to the network of {network-role}
2549        * 'v6_IP' signifies that an IPv6 address is being configured
2550        * {index} is the index of the IPv6 address
2551
2552 .. req::
2553     :id: R-20947
2554     :target: VNF
2555     :keyword: MUST
2556     :test: no test found
2557     :test_case: no test found
2558     :test_file: no test found
2559
2560     A VNF's Heat Orchestration Template's Resource
2561     'OS::ContrailV2::InstanceIp' that is configuring an IPv4 Address
2562     on a sub-interface port attached to a sub-interface network
2563     Resource ID **MUST** use the naming convention
2564
2565        *  {vm-type}_{vm-type_index}_subint_{network-role}_vmi_{vmi_index}_IP_{index}
2566
2567     where
2568
2569        * {vm-type} is the vm-type
2570        * {vm-type_index} is the instance of the {vm-type}
2571        * {network-role} is the network-role of the network
2572          that the port is attached to
2573        * {vmi_index} is the instance of the the virtual machine interface
2574          (e.g., port)  on the vm-type
2575          attached to the network of {network-role}
2576        * 'IP' signifies that an IPv4 address is being configured
2577        * {index} is the index of the IPv4 address
2578
2579 .. req::
2580     :id: R-88540
2581     :target: VNF
2582     :keyword: MUST
2583     :test: no test found
2584     :test_case: no test found
2585     :test_file: no test found
2586
2587     A VNF's Heat Orchestration Template's Resource
2588     'OS::ContrailV2::InstanceIp' that is configuring an IPv6 Address
2589     on a sub-interface port attached to a sub-interface network
2590     Resource ID **MUST** use the naming convention
2591
2592        *  {vm-type}_{vm-type_index}_subint_{network-role}_vmi_{vmi_index}_v6_IP_{index}
2593
2594     where
2595
2596        * {vm-type} is the vm-type
2597        * {vm-type_index} is the instance of the {vm-type}
2598        * {network-role} is the network-role of the network
2599          that the port is attached to
2600        * {vmi_index} is the instance of the the virtual machine interface
2601          (e.g., port)  on the vm-type
2602          attached to the network of {network-role}
2603        * 'v6_IP' signifies that an IPv6 address is being configured
2604        * {index} is the index of the IPv6 address
2605
2606 OS::ContrailV2::InterfaceRouteTable
2607 ___________________________________
2608
2609
2610 .. req::
2611     :id: R-81214
2612     :target: VNF
2613     :keyword: MUST
2614     :test: no test found
2615     :test_case: no test found
2616     :test_file: no test found
2617
2618     A VNF's Heat Orchestration Template's Resource
2619     'OS::ContrailV2::InterfaceRouteTable' Resource ID **MUST**
2620     contain the '{network-role}'.
2621
2622 .. req::
2623     :id: R-28189
2624     :target: VNF
2625     :keyword: MAY
2626     :test: no test found
2627     :test_case: no test found
2628     :test_file: no test found
2629
2630     A VNF's Heat Orchestration Template's Resource
2631     'OS::ContrailV2::InterfaceRouteTable' Resource ID **MAY**
2632     use the naming convention
2633
2634        * {network-role}_RIRT
2635
2636     where
2637
2638        * {network-role} is the network-role
2639        * 'RIRT' signifies that it is the Resource Interface Route Table
2640
2641 OS::ContrailV2::NetworkIpam
2642 ___________________________
2643
2644
2645 .. req::
2646     :id: R-30753
2647     :target: VNF
2648     :keyword: MUST
2649     :test: no test found
2650     :test_case: no test found
2651     :test_file: no test found
2652
2653     A VNF's Heat Orchestration Template's Resource
2654     'OS::ContrailV2::NetworkIpam' Resource ID **MUST**
2655     contain the '{network-role}'.
2656
2657 .. req::
2658     :id: R-81979
2659     :target: VNF
2660     :keyword: MAY
2661     :test: no test found
2662     :test_case: no test found
2663     :test_file: no test found
2664
2665     A VNF's Heat Orchestration Template's Resource
2666     'OS::ContrailV2::NetworkIpam' Resource ID **MAY**
2667     use the naming convention
2668
2669        * {network-role}_RNI
2670
2671     where
2672
2673        * {network-role} is the network-role
2674        * 'RNI' signifies that it is the Resource Network IPAM
2675
2676 OS::ContrailV2::PortTuple
2677 _________________________
2678
2679
2680 .. req::
2681     :id: R-20065
2682     :target: VNF
2683     :keyword: MUST
2684     :test: no test found
2685     :test_case: no test found
2686     :test_file: no test found
2687
2688     A VNF's Heat Orchestration Template's Resource
2689     'OS::ContrailV2::PortTuple' Resource ID **MUST**
2690     contain the '{vm-type}'.
2691
2692 .. req::
2693     :id: R-84457
2694     :target: VNF
2695     :keyword: MAY
2696     :test: no test found
2697     :test_case: no test found
2698     :test_file: no test found
2699
2700     A VNF's Heat Orchestration Template's Resource
2701     'OS::ContrailV2::PortTuple' Resource ID **MAY**
2702     use the naming convention
2703
2704        * {vm-type}_RPT
2705
2706     where
2707
2708        * {vm-type} is the vm-type
2709        * 'RPT' signifies that it is the Resource Port Tuple
2710
2711 OS::ContrailV2::ServiceHealthCheck
2712 __________________________________
2713
2714
2715 .. req::
2716     :id: R-76014
2717     :target: VNF
2718     :keyword: MUST
2719     :test: no test found
2720     :test_case: no test found
2721     :test_file: no test found
2722
2723     A VNF's Heat Orchestration Template's Resource
2724     'OS::ContrailV2::ServiceHealthCheck' Resource ID **MUST**
2725     contain the '{vm-type}'.
2726
2727 .. req::
2728     :id: R-65618
2729     :target: VNF
2730     :keyword: MAY
2731     :test: no test found
2732     :test_case: no test found
2733     :test_file: no test found
2734
2735     A VNF's Heat Orchestration Template's Resource
2736     'OS::ContrailV2::ServiceHealthCheck' Resource ID
2737     **MAY** use the naming convention
2738
2739        * {vm-type}_RSHC_{LEFT|RIGHT}
2740
2741     where
2742
2743        * {vm-type} is the vm-type
2744        * 'RSHC' signifies that it is the Resource Service Health Check
2745        * 'LEFT' is used if the Service Health Check is on the left interface
2746        * 'RIGHT' is used if the Service Health Check is on the right interface
2747
2748 OS::ContrailV2::ServiceTemplate
2749 _______________________________
2750
2751
2752 .. req::
2753     :id: R-16437
2754     :target: VNF
2755     :keyword: MUST
2756     :test: no test found
2757     :test_case: no test found
2758     :test_file: no test found
2759
2760     A VNF's Heat Orchestration Template's Resource
2761     'OS::ContrailV2::ServiceTemplate' Resource ID **MUST**
2762     contain the '{vm-type}'.
2763
2764 .. req::
2765     :id: R-14447
2766     :target: VNF
2767     :keyword: MAY
2768     :test: no test found
2769     :test_case: no test found
2770     :test_file: no test found
2771
2772     A VNF's Heat Orchestration Template's Resource
2773     'OS::ContrailV2::ServiceTemplate' Resource ID **MAY**
2774     use the naming convention
2775
2776        * {vm-type}_RST_{index}
2777
2778     where
2779
2780        * {vm-type} is the vm-type
2781        * 'RST' signifies that it is the Resource Service Template
2782        * '{index}' is is the index
2783
2784 OS::ContrailV2::VirtualMachineInterface
2785 _______________________________________
2786
2787
2788 .. req::
2789     :id: R-96253
2790     :target: VNF
2791     :keyword: MUST
2792     :test: no test found
2793     :test_case: no test found
2794     :test_file: no test found
2795
2796     A VNF's Heat Orchestration Template's Resource
2797     OS::ContrailV2::VirtualMachineInterface that is attaching
2798     to an external network Resource ID **MUST**
2799     use the naming convention
2800
2801        * {vm-type}_{vm-type_index}_{network-role}_vmi_{vmi_index}
2802
2803     where
2804
2805        * {vm-type} is the vm-type
2806        * {vm-type_index} is the instance of the {vm-type}
2807        * {network-role} is the network-role of the network
2808          that the port (i.e. virtual machine interface) is attached to
2809        * {vmi_index} is the instance of the the vmi on the vm-type
2810          attached to the network of {network-role}
2811
2812 .. req::
2813     :id: R-50468
2814     :target: VNF
2815     :keyword: MUST
2816     :test: no test found
2817     :test_case: no test found
2818     :test_file: no test found
2819
2820     A VNF's Heat Orchestration Template's Resource
2821     OS::ContrailV2::VirtualMachineInterface that is attaching
2822     to an internal network Resource ID **MUST** use the naming convention
2823
2824        * {vm-type}_{vm-type_index}_int_{network-role}_vmi_{vmi_index}
2825
2826     where
2827
2828        * {vm-type} is the vm-type
2829        * {vm-type_index} is the instance of the {vm-type}
2830        * {network-role} is the network-role of the network
2831          that the port (i.e. virtual machine interface) is attached to
2832        * {vmi_index} is the instance of the the vmi on the vm-type
2833          attached to the network of {network-role}
2834
2835 .. req::
2836     :id: R-54458
2837     :target: VNF
2838     :keyword: MUST
2839     :test: no test found
2840     :test_case: no test found
2841     :test_file: no test found
2842
2843     A VNF's Heat Orchestration Template's Resource
2844     OS::ContrailV2::VirtualMachineInterface that is attaching to
2845     a sub-interface network Resource ID **MUST** use the naming convention
2846
2847        * {vm-type}_{vm-type_index}_subint_{network-role}_vmi_{vmi_index}
2848
2849     where
2850
2851        * {vm-type} is the vm-type
2852        * {vm-type_index} is the instance of the {vm-type}
2853        * {network-role} is the network-role of the network
2854          that the port (i.e. virtual machine interface) is attached to
2855        * {vmi_index} is the instance of the the vmi on the vm-type
2856          attached to the network of {network-role}
2857
2858 OS::ContrailV2::VirtualNetwork
2859 ______________________________
2860
2861
2862 .. req::
2863     :id: R-99110
2864     :target: VNF
2865     :keyword: MUST
2866     :test: no test found
2867     :test_case: no test found
2868     :test_file: no test found
2869
2870     A VNF's Heat Orchestration Template's Resource
2871     OS::ContrailV2::VirtualNetwork Resource ID **MUST**
2872     use the naming convention
2873
2874        * 'int_{network-role}_network'
2875
2876     or
2877
2878        * 'int_{network-role}_RVN' where RVN represents Resource Virtual Network
2879
2880 VNF Heat Orchestration Templates can only create internal networks.
2881 There is no {index} after {network-role} because {network-role}
2882 **MUST** be unique in the scope of the VNF's
2883 Heat Orchestration Template.
2884
2885 Note that the first option is preferred.
2886
2887 Resource: OS::Nova::Server - Parameters
2888 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
2889
2890 The resource OS::Nova::Server manages the running virtual machine (VM)
2891 instance within an OpenStack cloud. (See
2892 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::Server.)
2893
2894 The following four properties of the OS::Nova::Server must follow
2895 the ONAP parameter naming convention. The four properties are:
2896
2897 1. image
2898
2899 2. flavor
2900
2901 3. name
2902
2903 4. availability\_zone
2904
2905 Requirement R-01455 defines how the '{vm-type}' is defined.
2906
2907 Requirement R-82481 defines how the '{vm-type}' is used.
2908
2909 The table below provides a summary. The sections that follow provides
2910 the detailed requirements.
2911
2912 .. csv-table:: **Table 4 OS::Nova::Server Resource Property Parameter Naming Convention**
2913    :header: Property Name,Parameter Type,Parameter Name,Parameter Value Provided to Heat
2914    :align: center
2915    :widths: auto
2916
2917    OS::Nova::Server, image, string, {vm-type}\_image\_name, Environment File
2918    OS::Nova::Server, flavor, string, {vm-type}\_flavor\_name, Environment File
2919    OS::Nova::Server, name, string, {vm-type}\_name\_{index}, ONAP
2920    OS::Nova::Server, name, CDL, {vm-type}\_names, ONAP
2921    OS::Nova::Server, availability\_zone, string, availability\_zone\_{index}, ONAP
2922
2923 Property: image
2924 +++++++++++++++
2925
2926
2927 .. req::
2928     :id: R-71152
2929     :target: VNF
2930     :keyword: MUST
2931
2932     The VNF's Heat Orchestration Template's Resource
2933     'OS::Nova::Server' property 'image' parameter **MUST** be declared as
2934     type: 'string'.
2935
2936 .. req::
2937     :id: R-58670
2938     :target: VNF
2939     :keyword: MUST
2940
2941     The VNF's Heat Orchestration Template's Resource
2942     'OS::Nova::Server' property 'image' parameter name **MUST** follow the
2943     naming convention '{vm-type}_image_name'.
2944
2945 .. req::
2946     :id: R-91125
2947     :target: VNF
2948     :keyword: MUST
2949
2950     The VNF's Heat Orchestration Template's Resource
2951     'OS::Nova::Server' property 'image' parameter **MUST** be enumerated in
2952     the Heat Orchestration Template's Environment File and a value **MUST** be
2953     assigned.
2954
2955 .. req::
2956     :id: R-57282
2957     :target: VNF
2958     :keyword: MUST
2959
2960     Each VNF's Heat Orchestration Template's '{vm-type}'
2961     **MUST** have a unique parameter name for the 'OS::Nova::Server'
2962     property 'image' even if more than one {vm-type} shares the same image.
2963
2964 *Example Parameter Definition*
2965
2966 .. code-block:: yaml
2967
2968  parameters:
2969      {vm-type}_image_name:
2970          type: string
2971          description: {vm-type} server image
2972
2973 Property: flavor
2974 ++++++++++++++++
2975
2976
2977 .. req::
2978     :id: R-50436
2979     :target: VNF
2980     :keyword: MUST
2981
2982     The VNF's Heat Orchestration Template's Resource
2983     'OS::Nova::Server' property 'flavor' parameter **MUST** be declared as
2984     type: 'string'.
2985
2986 .. req::
2987     :id: R-45188
2988     :target: VNF
2989     :keyword: MUST
2990
2991     The VNF's Heat Orchestration Template's Resource
2992     'OS::Nova::Server' property 'flavor' parameter name **MUST** follow the
2993     naming convention '{vm-type}_flavor_name'.
2994
2995 .. req::
2996     :id: R-69431
2997     :target: VNF
2998     :keyword: MUST
2999
3000     The VNF's Heat Orchestration Template's Resource
3001     'OS::Nova::Server' property 'flavor' parameter **MUST** be enumerated in the
3002     Heat Orchestration Template's Environment File and a value **MUST** be
3003     assigned.
3004
3005 .. req::
3006     :id: R-40499
3007     :target: VNF
3008     :keyword: MUST
3009
3010     Each VNF's Heat Orchestration Template's '{vm-type}' **MUST**
3011     have a unique parameter name for the 'OS::Nova::Server' property
3012     'flavor' even if more than one {vm-type} shares the same flavor.
3013
3014 *Example Parameter Definition*
3015
3016 .. code-block:: yaml
3017
3018  parameters:
3019      {vm-type}_flavor_name:
3020          type: string
3021          description: {vm-type} flavor
3022
3023 Property: Name
3024 ++++++++++++++
3025
3026
3027 .. req::
3028     :id: R-51430
3029     :target: VNF
3030     :keyword: MUST
3031
3032     The VNF's Heat Orchestration Template's Resource
3033     'OS::Nova::Server' property 'name' parameter **MUST** be declared as
3034     either type 'string' or type 'comma\_delimited\_list".
3035
3036 .. req::
3037     :id: R-54171
3038     :target: VNF
3039     :keyword: MUST
3040
3041     When the VNF's Heat Orchestration Template's Resource
3042     'OS::Nova::Server' property 'name' parameter is defined as a 'string',
3043     the parameter name **MUST** follow the naming convention
3044     '{vm-type}\_name\_{index}', where {index} is a numeric value that starts
3045     at zero and increments by one.
3046
3047 .. req::
3048     :id: R-40899
3049     :target: VNF
3050     :keyword: MUST
3051
3052     When the VNF's Heat Orchestration Template's Resource
3053     'OS::Nova::Server' property 'name' parameter is defined as a 'string',
3054     a parameter **MUST** be declared for each 'OS::Nova::Server' resource
3055     associated with the '{vm-type}'.
3056
3057 .. req::
3058     :id: R-87817
3059     :target: VNF
3060     :keyword: MUST
3061
3062     When the VNF's Heat Orchestration Template's Resource
3063     'OS::Nova::Server' property 'name' parameter is defined as a
3064     'comma_delimited_list', the parameter name **MUST** follow the naming
3065     convention '{vm-type}_names'.
3066
3067 .. req::
3068     :id: R-85800
3069     :target: VNF
3070     :keyword: MUST
3071
3072     When the VNF's Heat Orchestration Template's Resource
3073     'OS::Nova::Server' property 'name' parameter is defined as a
3074     'comma_delimited_list', a parameter **MUST** be delcared once for all
3075     'OS::Nova::Server' resources associated with the '{vm-type}'.
3076
3077 .. req::
3078     :id: R-22838
3079     :target: VNF
3080     :keyword: MUST NOT
3081
3082     The VNF's Heat Orchestration Template's Resource
3083     'OS::Nova::Server' property 'name' parameter **MUST NOT** be enumerated
3084     in the Heat Orchestration Template's Environment File.
3085
3086 If a VNF's Heat Orchestration Template's contains more than three
3087 OS::Nova::Server resources of a given {vm-type}, the comma\_delimited\_list
3088 form of the parameter name (i.e., '{vm-type}\_names') should be used to
3089 minimize the number of unique parameters defined in the template.
3090
3091
3092 *Example: Parameter Definition*
3093
3094 .. code-block:: yaml
3095
3096   parameters:
3097
3098   {vm-type}_names:
3099     type: comma_delimited_list
3100     description: VM Names for {vm-type} VMs
3101
3102   {vm-type}_name_{index}:
3103     type: string
3104     description: VM Name for {vm-type} VM {index}
3105
3106 *Example: comma\_delimited\_list*
3107
3108 In this example, the {vm-type} has been defined as "lb" for load balancer.
3109
3110 .. code-block:: yaml
3111
3112   parameters:
3113
3114     lb_names:
3115       type: comma_delimited_list
3116       description: VM Names for lb VMs
3117
3118   resources:
3119     lb_server_0:
3120       type: OS::Nova::Server
3121       properties:
3122         name: { get_param: [lb_names, 0] }
3123         ...
3124
3125     lb_server_1:
3126       type: OS::Nova::Server
3127       properties:
3128         name: { get_param: [lb_names, 1] }
3129         ...
3130
3131 *Example: fixed-index*
3132
3133 In this example, the {vm-type} has been defined as "lb" for load balancer.
3134
3135 .. code-block:: yaml
3136
3137   parameters:
3138
3139     lb_name_0:
3140       type: string
3141       description: VM Name for lb VM 0
3142
3143     lb_name_1:
3144       type: string
3145       description: VM Name for lb VM 1
3146
3147   resources:
3148
3149     lb_server_0:
3150       type: OS::Nova::Server
3151       properties:
3152         name: { get_param: lb_name_0 }
3153         ...
3154
3155     lb_server_1:
3156       type: OS::Nova::Server
3157       properties:
3158         name: { get_param: lb_name_1 }
3159         ...
3160
3161 Contrail Issue with Values for OS::Nova::Server Property Name
3162 _____________________________________________________________
3163
3164
3165 .. req::
3166     :id: R-44271
3167     :target: VNF
3168     :keyword: SHOULD NOT
3169
3170     The VNF's Heat Orchestration Template's Resource
3171     'OS::Nova::Server' property 'name' parameter value **SHOULD NOT**
3172     contain special characters since the Contrail GUI has a limitation
3173     displaying special characters.
3174
3175 However, if special characters must be used, the only special characters
3176 supported are:
3177
3178 --- \" ! $ ' (\ \ ) = ~ ^ | @ ` { } [ ] > , . _
3179
3180
3181 Property: availability\_zone
3182 ++++++++++++++++++++++++++++
3183
3184
3185 .. req::
3186     :id: R-98450
3187     :target: VNF
3188     :keyword: MUST
3189
3190     The VNF's Heat Orchestration Template's Resource
3191     'OS::Nova::Server' property 'availability\_zone' parameter name
3192     **MUST** follow the naming convention 'availability\_zone\_{index}'
3193     where the '{index}' **MUST** start at zero and increment by one.
3194
3195 .. req::
3196     :id: R-23311
3197     :target: VNF
3198     :keyword: MUST
3199
3200     The VNF's Heat Orchestration Template's Resource
3201     'OS::Nova::Server' property 'availability_zone' parameter **MUST**
3202     be declared as type: 'string'.
3203
3204 The parameter must not be declared as type 'comma\_delimited\_list',
3205 ONAP does not support it.
3206
3207
3208 .. req::
3209     :id: R-59568
3210     :target: VNF
3211     :keyword: MUST NOT
3212
3213     The VNF's Heat Orchestration Template's Resource
3214     'OS::Nova::Server' property 'availability_zone' parameter **MUST NOT**
3215     be enumerated in the Heat Orchestration Template's Environment File.
3216
3217 Example Parameter Definition
3218
3219 .. code-block:: yaml
3220
3221   parameters:
3222     availability_zone_{index}:
3223       type: string
3224       description: availability zone {index} name
3225
3226 Requirement R-90279 states that a VNF Heat Orchestration's template's
3227 parameter MUST be used in a resource with the exception of the parameters
3228 for the OS::Nova::Server resource property availability_zone.
3229
3230
3231 .. req::
3232     :id: R-01359
3233     :target: VNF
3234     :keyword: MAY
3235
3236     A VNF's Heat Orchstration Template that contains an
3237     'OS::Nova:Server' Resource **MAY** define a parameter for the property
3238     'availability_zone' that is not utilized in any 'OS::Nova::Server'
3239     resources in the Heat Orchestration Template.
3240
3241 Example
3242 +++++++
3243
3244 The example below depicts part of a Heat Orchestration Template that
3245 uses the four OS::Nova::Server properties discussed in this section.
3246
3247 In the Heat Orchestration Template below, four Virtual
3248 Machines (OS::Nova::Server) are created: two dns servers with
3249 {vm-type} set to "dns" and two oam servers with {vm-type} set to "oam".
3250 Note that the parameter associated with the property name is a
3251 comma_delimited_list for dns and a string for oam.
3252
3253 .. code-block:: yaml
3254
3255   parameters:
3256
3257     dns_image_name:
3258       type: string
3259       description: dns server image
3260
3261     dns_flavor_name:
3262       type: string
3263       description: dns server flavor
3264
3265     dns_names:
3266       type: comma_delimited_list
3267       description: dns server names
3268
3269     oam_image_name:
3270       type: string
3271       description: oam server image
3272
3273     oam_flavor_name:
3274       type: string
3275       description: oam server flavor
3276
3277     oam_name_0:
3278       type: string
3279       description: oam server name 0
3280
3281     oam_name_1:
3282       type: string
3283       description: oam server name 1
3284
3285     availability_zone_0:
3286       type: string
3287       description: availability zone ID or Name
3288
3289     availability_zone_1:
3290       type: string
3291       description: availability zone ID or Name
3292
3293   resources:
3294
3295     dns_server_0:
3296       type: OS::Nova::Server
3297       properties:
3298         name: { get_param: [ dns_names, 0 ] }
3299         image: { get_param: dns_image_name }
3300         flavor: { get_param: dns_flavor_name }
3301         availability_zone: { get_param: availability_zone_0 }
3302
3303   . . .
3304
3305       dns_server_1:
3306         type: OS::Nova::Server
3307         properties:
3308           name: { get_param: [ dns_names, 1 ] }
3309           image: { get_param: dns_image_name }
3310           flavor: { get_param: dns_flavor_name }
3311           availability_zone: { get_param: availability_zone_1 }
3312
3313   . . .
3314
3315       oam_server_0:
3316         type: OS::Nova::Server
3317         properties:
3318           name: { get_param: oam_name_0 }
3319           image: { get_param: oam_image_name }
3320           flavor: { get_param: oam_flavor_name }
3321           availability_zone: { get_param: availability_zone_0 }
3322
3323   . . .
3324
3325       oam_server_1:
3326         type: OS::Nova::Server
3327         properties:
3328           name: { get_param: oam_name_1 }
3329           image: { get_param: oam_image_name }
3330           flavor: { get_param: oam_flavor_name }
3331           availability_zone: { get_param: availability_zone_1 }
3332
3333   . . .
3334
3335 Boot Options
3336 ++++++++++++
3337
3338
3339 .. req::
3340     :id: R-99798
3341     :target: VNF
3342     :keyword: MAY
3343
3344     A VNF's Heat Orchestration Template's Virtual Machine
3345     (i.e., OS::Nova::Server Resource) **MAY** boot from an image or **MAY**
3346     boot from a Cinder Volume.
3347
3348 .. req::
3349     :id: R-83706
3350     :target: VNF
3351     :keyword: MUST
3352
3353     When a VNF's Heat Orchestration Template's Virtual Machine
3354     (i.e., 'OS::Nova::Server' Resource) boots from an image, the
3355     'OS::Nova::Server' resource property 'image' **MUST** be used.
3356
3357 The requirements associated with
3358 the 'image' property are detailed in `Property: image`_
3359
3360
3361 .. req::
3362     :id: R-69588
3363     :target: VNF
3364     :keyword: MUST
3365
3366     When a VNF's Heat Orchestration Template's Virtual Machine
3367     (i.e., 'OS::Nova::Server' Resource) boots from Cinder Volume, the
3368     'OS::Nova::Server' resource property 'block_device_mapping' or
3369     'block_device_mapping_v2' **MUST** be used.
3370
3371 There are currently no heat guidelines
3372 associated with these two properties:
3373 'block_device_mapping' and 'block_device_mapping_v2'.
3374
3375 Resource: OS::Nova::Server – Metadata Parameters
3376 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
3377
3378 The OS::Nova::Server Resource property metadata is an optional
3379 OpenStack property.
3380 The table below summarizes the mandatory and optional metadata
3381 supported by ONAP.
3382
3383 The sections that follow provides the requirements associated with each
3384 metadata parameter.
3385
3386 .. csv-table:: **Table 5 OS::Nova::Server Mandatory and Optional Metadata**
3387    :header: Metadata Parameter Name, Parameter Type, Required, Parameter Value Provided to Heat
3388    :align: center
3389    :widths: auto
3390
3391    vnf_id, string, **MUST**, ONAP
3392    vf_module_id, string, **MUST**, ONAP
3393    vnf_name, string, **MUST**, ONAP
3394    vf_module_name, string, **SHOULD**, ONAP
3395    vm_role, string, **MAY**, YAML or Environment File
3396    vf_module_index, string, **MAY**, ONAP
3397    workload_context, string, **SHOULD**, ONAP
3398    environment_context, string, **SHOULD**, ONAP
3399
3400 vnf\_id
3401 +++++++
3402
3403 The OS::Nova::Server Resource metadata map value parameter 'vnf_id'
3404 is an ONAP generated UUID that identifies the VNF.  The value
3405 is provided by ONAP to the VNF's Heat Orchestration
3406 Template at orchestration time.
3407
3408
3409 .. req::
3410     :id: R-37437
3411     :target: VNF
3412     :keyword: MUST
3413
3414     A VNF's Heat Orchestration Template's OS::Nova::Server
3415     Resource **MUST** contain the metadata map value parameter 'vnf_id'.
3416
3417 .. req::
3418     :id: R-07507
3419     :target: VNF
3420     :keyword: MUST
3421
3422     A VNF's Heat Orchestration Template's OS::Nova::Server
3423     Resource metadata map value parameter 'vnf_id' **MUST** be declared
3424     as type: 'string'.
3425
3426 .. req::
3427     :id: R-55218
3428     :target: VNF
3429     :keyword: MUST NOT
3430
3431     A VNF's Heat Orchestration Template's OS::Nova::Server
3432     Resource metadata map value parameter 'vnf_id' **MUST NOT** have
3433     parameter contraints defined.
3434
3435 .. req::
3436     :id: R-20856
3437     :target: VNF
3438     :keyword: MUST NOT
3439
3440     A VNF's Heat Orchestration Template's OS::Nova::Server
3441     Resource metadata map value parameter 'vnf_id' **MUST NOT** be
3442     enumerated in the Heat Orchestration Template's environment file.
3443
3444 .. req::
3445     :id: R-44491
3446     :target: VNF
3447     :keyword: MUST NOT
3448
3449     If a VNF's Heat Orchestration Template's OS::Nova::Server
3450     Resource metadata map value parameter 'vnf_id' is passed into a
3451     Nested YAML file, the parameter name 'vnf_id' **MUST NOT** change.
3452
3453 *Example 'vnf_id' Parameter Definition*
3454
3455 .. code-block:: yaml
3456
3457   parameters:
3458
3459     vnf_id:
3460       type: string
3461       description: Unique ID for this VNF instance
3462
3463 vf\_module\_id
3464 ++++++++++++++
3465
3466 The OS::Nova::Server Resource metadata map value parameter 'vf\_module\_id'
3467 is an ONAP generated UUID that identifies the VF Module (e.g., Heat
3468 Orchestration Template).  The value
3469 is provided by ONAP to the VNF's Heat Orchestration
3470 Template at orchestration time.
3471
3472
3473 .. req::
3474     :id: R-71493
3475     :target: VNF
3476     :keyword: MUST
3477
3478     A VNF's Heat Orchestration Template's OS::Nova::Server
3479     Resource **MUST** contain the metadata map value parameter
3480     'vf\_module\_id'.
3481
3482 .. req::
3483     :id: R-82134
3484     :target: VNF
3485     :keyword: MUST
3486
3487     A VNF's Heat Orchestration Template's OS::Nova::Server
3488     Resource metadata map value parameter 'vf\_module\_id' **MUST**
3489     be declared as type: 'string'.
3490
3491 .. req::
3492     :id: R-98374
3493     :target: VNF
3494     :keyword: MUST NOT
3495
3496     A VNF's Heat Orchestration Template's OS::Nova::Server
3497     Resource metadata map value parameter 'vf\_module\_id' **MUST NOT**
3498     have parameter contraints defined.
3499
3500 .. req::
3501     :id: R-72871
3502     :target: VNF
3503     :keyword: MUST NOT
3504
3505     A VNF's Heat Orchestration Template's OS::Nova::Server
3506     Resource metadata map value parameter 'vf\_module\_id' **MUST NOT**
3507     be enumerated in the Heat Orchestration Template's environment file.
3508
3509 .. req::
3510     :id: R-86237
3511     :target: VNF
3512     :keyword: MUST NOT
3513
3514     If a VNF's Heat Orchestration Template's OS::Nova::Server
3515     Resource metadata map value parameter 'vf_module_id' is passed
3516     into a Nested YAML file, the parameter name 'vf\_module\_id'
3517     **MUST NOT** change.
3518
3519 *Example 'vf\_module\_id' Parameter Definition*
3520
3521 .. code-block:: yaml
3522
3523   parameters:
3524
3525     vnf_module_id:
3526       type: string
3527       description: Unique ID for this VNF module instance
3528
3529
3530 vnf\_name
3531 +++++++++
3532
3533 The OS::Nova::Server Resource metadata map value parameter 'vnf_name'
3534 is the ONAP generated alphanumeric name of the deployed VNF instance.
3535 The value
3536 is provided by ONAP to the VNF's Heat Orchestration
3537 Template at orchestration time.
3538 The parameter must be declared as type: string
3539
3540
3541 .. req::
3542     :id: R-72483
3543     :target: VNF
3544     :keyword: MUST
3545
3546     A VNF's Heat Orchestration Template's OS::Nova::Server
3547     Resource **MUST** contain the metadata map value parameter
3548     'vnf_name'.
3549
3550 .. req::
3551     :id: R-62428
3552     :target: VNF
3553     :keyword: MUST
3554
3555     A VNF's Heat Orchestration Template's OS::Nova::Server
3556     Resource metadata map value parameter 'vnf_name' **MUST** be
3557     declared as type: 'string'.
3558
3559 .. req::
3560     :id: R-44318
3561     :target: VNF
3562     :keyword: MUST NOT
3563
3564     A VNF's Heat Orchestration Template's OS::Nova::Server
3565     Resource metadata map value parameter 'vnf\_name' **MUST NOT** have
3566     parameter contraints defined.
3567
3568 .. req::
3569     :id: R-36542
3570     :target: VNF
3571     :keyword: MUST NOT
3572
3573     A VNF's Heat Orchestration Template's OS::Nova::Server
3574     Resource metadata map value parameter 'vnf\_name' **MUST NOT** be
3575     enumerated in the Heat Orchestration Template's environment file.
3576
3577 .. req::
3578     :id: R-16576
3579     :target: VNF
3580     :keyword: MUST NOT
3581
3582     If a VNF's Heat Orchestration Template's OS::Nova::Server
3583     Resource metadata map value parameter 'vnf_name' is passed into a
3584     Nested YAML file, the parameter name 'vnf_name' **MUST NOT** change.
3585
3586 *Example 'vnf\_name' Parameter Definition*
3587
3588 .. code-block:: yaml
3589
3590   parameters:
3591
3592     vnf_name:
3593       type: string
3594       description: Unique name for this VNF instance
3595
3596 vf\_module\_name
3597 ++++++++++++++++
3598
3599 The OS::Nova::Server Resource metadata map value parameter 'vf_module_name'
3600 is the deployment name of the heat stack created (e.g., <STACK_NAME>) from the
3601 VNF's Heat Orchestration template
3602 in the command 'Heat stack-create'
3603 (e.g., 'Heat stack-create [-f <FILE>] [-e <FILE>] <STACK_NAME>').
3604 The 'vf_module_name' (e.g., <STACK_NAME> is specified as
3605 part of the orchestration process.
3606
3607
3608 .. req::
3609     :id: R-68023
3610     :target: VNF
3611     :keyword: SHOULD
3612
3613     A VNF's Heat Orchestration Template's OS::Nova::Server
3614     Resource **SHOULD** contain the metadata map value parameter
3615     'vf\_module\_name'.
3616
3617 .. req::
3618     :id: R-39067
3619     :target: VNF
3620     :keyword: MUST
3621
3622     A VNF's Heat Orchestration Template's OS::Nova::Server
3623     Resource metadata map value parameter 'vf\_module\_name' **MUST**
3624     be declared as type: 'string'.
3625
3626 .. req::
3627     :id: R-15480
3628     :target: VNF
3629     :keyword: MUST NOT
3630
3631     A VNF's Heat Orchestration Template's OS::Nova::Server
3632     Resource metadata map value parameter 'vf\_module\_name'
3633     **MUST NOT** have parameter contraints defined.
3634
3635 .. req::
3636     :id: R-80374
3637     :target: VNF
3638     :keyword: MUST NOT
3639
3640     A VNF's Heat Orchestration Template's OS::Nova::Server
3641     Resource metadata map value parameter 'vf\_module\_name'
3642     **MUST NOT** be enumerated in the Heat Orchestration Template's
3643     environment file.
3644
3645 .. req::
3646     :id: R-49177
3647     :target: VNF
3648     :keyword: MUST
3649
3650     If a VNF's Heat Orchestration Template's OS::Nova::Server
3651     Resource metadata map value parameter 'vf\_module\_name' is passed
3652     into a Nested YAML file, the parameter name 'vf\_module\_name'
3653     **MUST NOT** change.
3654
3655 *Example 'vf_module_name' Parameter Definition*
3656
3657 .. code-block:: yaml
3658
3659   parameters:
3660
3661     vf_module_name:
3662       type: string
3663       description: Unique name for this VNF Module instance
3664
3665 vm\_role
3666 ++++++++
3667
3668 The OS::Nova::Server Resource metadata map value parameter 'vm-role'
3669 is a metadata tag that describes the role of the Virtual Machine.
3670 The 'vm\_role' is stored in ONAP's A&AI module and is
3671 available for use by other ONAP components and/or north bound systems.
3672
3673
3674 .. req::
3675     :id: R-85328
3676     :target: VNF
3677     :keyword: MAY
3678
3679     A VNF's Heat Orchestration Template's OS::Nova::Server
3680     Resource **MAY** contain the metadata map value parameter 'vm_role'.
3681
3682 .. req::
3683     :id: R-95430
3684     :target: VNF
3685     :keyword: MUST
3686
3687     A VNF's Heat Orchestration Template's OS::Nova::Server
3688     Resource metadata map value parameter 'vm_role' **MUST** be
3689     declared as type: 'string'.
3690
3691 .. req::
3692     :id: R-67597
3693     :target: VNF
3694     :keyword: MUST NOT
3695
3696     A VNF's Heat Orchestration Template's OS::Nova::Server
3697     Resource metadata map value parameter 'vm_role' **MUST NOT** have
3698     parameter contraints defined.
3699
3700
3701 .. req::
3702     :id: R-46823
3703     :target: VNF
3704     :keyword: MUST
3705
3706     A VNF's Heat Orchestration Template's OS::Nova::Server
3707     Resource metadata map value parameter 'vnf_name' **MUST** be
3708     either
3709
3710      - enumerated in the VNF's Heat Orchestration
3711        Template's environment file.
3712
3713      - hard coded in the VNF's Heat Orchestration
3714        Template's OS::Nova::Resource metadata property.
3715
3716 Defining the 'vm_role' as the '{vm-type}' is a recommended convention
3717
3718
3719 .. req::
3720     :id: R-86476
3721     :target: VNF
3722     :keyword: MUST
3723
3724     If a VNF's Heat Orchestration Template's OS::Nova::Server
3725     Resource metadata map value parameter 'vm_role' value **MUST** only
3726     contain alphanumeric characters and underscores '_'.
3727
3728 .. req::
3729     :id: R-70757
3730     :target: VNF
3731     :keyword: MUST NOT
3732
3733     If a VNF's Heat Orchestration Template's OS::Nova::Server
3734     Resource metadata map value parameter 'vm_role' is passed into a
3735     Nested YAML file, the parameter name 'vm_role' **MUST NOT** change.
3736
3737 *Example 'vm\_role' Parameter Definition*
3738
3739 .. code-block:: yaml
3740
3741   parameters:
3742
3743     vm_role:
3744       type: string
3745       description: Unique role for this VM
3746
3747 *Example: 'vm-role' Definition: Hard Coded in
3748 OS::Nova::Resource metadata property*
3749
3750 .. code-block:: yaml
3751
3752   resources:
3753
3754     dns_server_0
3755       type: OS::Nova::Server
3756       properties:
3757         . . . .
3758         metadata:
3759           vm_role: dns
3760
3761 *Example 'vm-role' Definition: Defined in Environment file
3762 and retrieved via 'get_param'*
3763
3764 .. code-block:: yaml
3765
3766   resources:
3767
3768     dns_server_0:
3769       type: OS::Nova::Server
3770       properties:
3771         . . . .
3772         metadata:
3773           vm_role: { get_param: vm_role }
3774
3775 Example vnf_id, vf_module_id, vnf_name, vf_module_name, vm_role
3776 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
3777
3778 The example below depicts part of a Heat Orchestration Template
3779 that uses the five of the OS::Nova::Server metadata parameter
3780 discussed in this section. The {vm-type} has been defined as lb
3781 for load balancer.
3782
3783 .. code-block:: yaml
3784
3785   parameters:
3786     lb_name_0
3787       type: string
3788       description: VM Name for lb VM 0
3789     vnf_name:
3790       type: string
3791       description: Unique name for this VNF instance
3792     vnf_id:
3793       type: string
3794       description: Unique ID for this VNF instance
3795     vf_module_name:
3796       type: string
3797       description: Unique name for this VNF Module instance
3798     vf_module_id:
3799       type: string
3800       description: Unique ID for this VNF Module instance
3801     vm_role:
3802       type: string
3803       description: Unique role for this VM
3804   resources:
3805     lb_server_0:
3806       type: OS::Nova::Server
3807       properties:
3808         name: { get_param: lb_name_0 }
3809         ...
3810         metadata:
3811           vnf_name: { get_param: vnf_name }
3812           vnf_id: { get_param: vnf_id }
3813           vf_module_name: { get_param: vf_module_name }
3814           vf_module_id: { get_param: vf_module_id }
3815           vm_role: lb
3816
3817 vf\_module\_index
3818 +++++++++++++++++
3819
3820
3821 .. req::
3822     :id: R-50816
3823     :target: VNF
3824     :keyword: MAY
3825
3826     A VNF's Heat Orchestration Template's OS::Nova::Server
3827     Resource **MAY** contain the metadata map value parameter
3828     'vf\_module\_index'.
3829
3830 .. req::
3831     :id: R-54340
3832     :target: VNF
3833     :keyword: MUST
3834
3835     A VNF's Heat Orchestration Template's OS::Nova::Server
3836     Resource metadata map value parameter 'vf\_module\_index' **MUST** be
3837     declared as type: 'number'.
3838
3839 .. req::
3840     :id: R-09811
3841     :target: VNF
3842     :keyword: MUST NOT
3843
3844     A VNF's Heat Orchestration Template's OS::Nova::Server
3845     Resource metadata map value parameter 'vf\_module\_index' **MUST NOT**
3846     have parameter contraints defined.
3847
3848 .. req::
3849     :id: R-37039
3850     :target: VNF
3851     :keyword: MUST NOT
3852
3853     A VNF's Heat Orchestration Template's OS::Nova::Server
3854     Resource metadata map value parameter 'vf\_module\_index' **MUST NOT**
3855     be enumerated in the Heat Orchestration Template's environment file.
3856
3857 .. req::
3858     :id: R-22441
3859     :target: VNF
3860     :keyword: MUST NOT
3861
3862     If a VNF's Heat Orchestration Template's OS::Nova::Server
3863     Resource metadata map value parameter 'vf\_module\_index' is passed
3864     into a Nested YAML file, the parameter name 'vf\_module\_index'
3865     **MUST NOT** change.
3866
3867 .. req::
3868     :id: R-55306
3869     :target: VNF
3870     :keyword: MUST NOT
3871
3872     If a VNF's Heat Orchestration Template's OS::Nova::Server
3873     Resource metadata map value parameter 'vf\_module\_index' **MUST NOT** be
3874     used in a VNF's Volume Template; it is not supported.
3875
3876 The vf\_module_index parameter indicates which instance of the module is being
3877 deployed into the VNF.
3878 This parameter may be used in cases where multiple instances of the same
3879 incremental module may be instantiated for scaling purposes. The index
3880 can be used in the Heat Orchestration Template for indexing into a
3881 pseudo-constant array parameter when unique values are required for each
3882 module instance, e.g., for fixed private IP addresses on VM types.
3883
3884 The vf\_module\_index will start at 0 for the first instance of a module
3885 type. Subsequent instances of the same module type will receive the
3886 lowest unused index. This means that indexes will be reused if a module
3887 is deleted and re-added. As an example, if three copies of a module are
3888 deployed with vf\_module\_index values of 0, 1, and 2 then subsequently
3889 the second one is deleted (index 1), and then re-added, index 1 will be
3890 reused.
3891
3892 *Example*
3893
3894 In this example, the {vm-type} has been defined as oam\_vm to represent
3895 an OAM VM. An incremental heat module is used to deploy the OAM VM. The
3896 OAM VM attaches to an internal control network which has a
3897 {network-role} of ctrl. A maximum of four OAM VMs can be deployed. The
3898 environment file contains the four IP addresses that each successive OAM
3899 VM will be assigned. The vf\_module\_index is used as the index to
3900 determine the IP assignment.
3901
3902 Environment File
3903
3904 .. code-block:: yaml
3905
3906   parameters:
3907     oam_vm_int_ctrl_ips: 10.10.10.1,10.10.10.2,10.10.10.3,10.10.10.4
3908
3909 YAML File
3910
3911 .. code-block:: yaml
3912
3913  parameters:
3914    vf_module_index:
3915      type: number
3916      description: Unique index for this VNF Module instance
3917    oam_vm_name_0:
3918      type: string
3919      description: VM Name for lb VM 0
3920    int_ctrl_net_id:
3921      type: string
3922      description: Neutron UUID for the internal control network
3923    oam_vm_int_ctrl_ips:
3924      type: comma_delimited_list
3925      description: Fixed IP assignments for oam VMs on the internal control
3926      network
3927  resources:
3928    oam_vm_server_0:
3929      type: OS::Nova::Server
3930      properties:
3931        name: { get_param: oam_vm_name_0 }
3932        networks:
3933          port: { get_resource: oam_vm_0_int_ctrl_port_0 }
3934
3935        . . .
3936
3937        metadata:
3938          vf_module_index: { get_param: vf_module_index }
3939    oam_vm_0_int_ctrl_port_0:
3940      type: OS::Neutron::Port
3941      properties:
3942        network: { get_param: int_ctrl_net_id }
3943        fixed_ips: [ { "ip_address": {get_param: [ oam_vm_int_ctrl_ips, { get_param, vf_module_index}]}}]
3944
3945 workload\_context
3946 ++++++++++++++++++
3947
3948
3949 .. req::
3950     :id: R-47061
3951     :target: VNF
3952     :keyword: SHOULD
3953
3954     A VNF's Heat Orchestration Template's OS::Nova::Server
3955     Resource **SHOULD** contain the metadata map value parameter
3956     'workload_context'.
3957
3958 .. req::
3959     :id: R-74978
3960     :target: VNF
3961     :keyword: MUST
3962
3963     A VNF's Heat Orchestration Template's OS::Nova::Server
3964     Resource metadata map value parameter 'workload_context' **MUST** be
3965     declared as type: 'string'.
3966
3967 .. req::
3968     :id: R-34055
3969     :target: VNF
3970     :keyword: MUST NOT
3971
3972     A VNF's Heat Orchestration Template's OS::Nova::Server
3973     Resource metadata map value parameter 'workload_context' **MUST NOT**
3974     have parameter contraints defined.
3975
3976 .. req::
3977     :id: R-02691
3978     :target: VNF
3979     :keyword: MUST NOT
3980
3981     A VNF's Heat Orchestration Template's OS::Nova::Server
3982     Resource metadata map value parameter 'workload_context' **MUST NOT**
3983     be enumerated in the Heat Orchestration Template's environment file.
3984
3985 .. req::
3986     :id: R-75202
3987     :target: VNF
3988     :keyword: MUST NOT
3989
3990     If a VNF's Heat Orchestration Template's OS::Nova::Server
3991     Resource metadata map value parameter 'workload_context' is passed
3992     into a Nested YAML file, the parameter name 'workload_context'
3993     **MUST NOT** change.
3994
3995 The 'workload\_context' parameter value will be chosen by the Service Model
3996 Distribution context client in VID and will be supplied to the
3997 Heat Orchestration Template by ONAP at orchestration time.
3998
3999 *Example Parameter Definition*
4000
4001 .. code-block:: yaml
4002
4003   parameters:
4004     workload_context:
4005       type: string
4006       description: Workload Context for this VNF instance
4007
4008
4009 *Example OS::Nova::Server with metadata*
4010
4011 .. code-block:: yaml
4012
4013   resources:
4014     . . .
4015
4016     {vm-type}_server_{index}:
4017        type: OS::Nova::Server
4018        properties:
4019          name:
4020          flavor:
4021          image:
4022         ...
4023        metadata:
4024           vnf_name: { get_param: vnf_name }
4025           vnf_id: { get_param: vnf_id }
4026           vf_module_name: { get_param: vf_module_name }
4027           vf_module_id: { get_param: vf_module_id }
4028           workload_context: {get_param: workload_context}
4029
4030 environment\_context
4031 ++++++++++++++++++++++
4032
4033
4034 .. req::
4035     :id: R-88536
4036     :target: VNF
4037     :keyword: SHOULD
4038
4039     A VNF's Heat Orchestration Template's OS::Nova::Server
4040     Resource **SHOULD** contain the metadata map value parameter
4041     'environment_context'.
4042
4043 .. req::
4044     :id: R-20308
4045     :target: VNF
4046     :keyword: MUST
4047
4048     A VNF's Heat Orchestration Template's OS::Nova::Server
4049     Resource metadata map value parameter 'environment_context' **MUST**
4050     be declared as type: 'string'.
4051
4052 .. req::
4053     :id: R-56183
4054     :target: VNF
4055     :keyword: MUST NOT
4056
4057     A VNF's Heat Orchestration Template's OS::Nova::Server
4058     Resource metadata map value parameter 'environment_context' **MUST NOT**
4059     have parameter contraints defined.
4060
4061 .. req::
4062     :id: R-13194
4063     :target: VNF
4064     :keyword: MUST NOT
4065
4066     A VNF's Heat Orchestration Template's OS::Nova::Server
4067     Resource metadata map value parameter 'environment_context' **MUST NOT**
4068     be enumerated in the Heat Orchestration Template's environment file.
4069
4070 .. req::
4071     :id: R-62954
4072     :target: VNF
4073     :keyword: MUST NOT
4074
4075     If a VNF's Heat Orchestration Template's OS::Nova::Server
4076     Resource metadata map value parameter 'environment_context' is
4077     passed into a Nested YAML file, the parameter name
4078     'environment_context' **MUST NOT** change.
4079
4080 The 'environment\_context' parameter value will be defined by the
4081 service designer as part of the service model during the SDC
4082 on-boarding process and will be supplied to the Heat Orchestration
4083 Template by ONAP at orchestration time.
4084
4085
4086 *Example Parameter Definition*
4087
4088 .. code-block:: yaml
4089
4090   parameters:
4091     environment_context:
4092       type: string
4093       description: Environment Context for this VNF instance
4094
4095
4096 *Example OS::Nova::Server with metadata*
4097
4098 .. code-block:: yaml
4099
4100   resources:
4101     . . .
4102
4103     {vm-type}_server_{index}:
4104        type: OS::Nova::Server
4105        properties:
4106          name:
4107          flavor:
4108          image:
4109         ...
4110        metadata:
4111           vnf_name: { get_param: vnf_name }
4112           vnf_id: { get_param: vnf_id }
4113           vf_module_name: { get_param: vf_module_name }
4114           vf_module_id: { get_param: vf_module_id }
4115           workload_context: {get_param: workload_context}
4116           environment_context: {get_param: environment_context }
4117
4118
4119 Resource: OS::Neutron::Port - Parameters
4120 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
4121
4122 The resource OS::Neutron::Port is for managing Neutron ports (See
4123 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Port.)
4124
4125 Introduction
4126 ++++++++++++
4127
4128 Four properties of the resource OS::Neutron::Port that must follow the
4129 ONAP parameter naming convention. The four properties are:
4130
4131 1. network
4132 2. fixed_ips, ip_address
4133 3. fixed_ips, subnet_id or fixed_ips, subnet
4134
4135  * Note that in many examples in this document fixed_ips, subnet_id is used.
4136
4137 4. allowed_address_pairs, ip_address
4138
4139 Below is a generic example. Note that for some parameters
4140 comma_delimited_list are supported in addition to String.
4141
4142 .. code-block:: yaml
4143
4144   resources:
4145
4146   ...
4147
4148   <resource ID>:
4149     type: OS::Neutron::Port
4150     properties:
4151       allowed_address_pairs: [{"ip_address": String, "mac_address": String},
4152       {"ip_address": String, "mac_address": String}, ...]
4153       fixed_ips: [{"ip_address": String, "subnet_id": String, "subnet":
4154       String}, {"ip_address": String, "subnet_id": String, "subnet": String},
4155       ...]
4156       network: String
4157
4158 The values associated with these properties may reference an external
4159 network or internal network. External networks and internal
4160 networks are defined in `Networking`_.
4161
4162 When the OS::Neutron::Port is attaching to an external network, all
4163 property values are parameters that are retrieved via the intrinsic
4164 function 'get_param'.
4165
4166 When the OS::Neutron::Port is attaching to an internal network, a
4167 property value maybe retrieved via the intrinsic
4168 function 'get_param', 'get_resource', or 'get_attr'.
4169
4170 This will be described in the forth coming sections.
4171
4172 Items to Note
4173 _____________
4174
4175
4176 .. req::
4177     :id: R-93272
4178     :target: VNF
4179     :keyword: MAY
4180     :test: no test found
4181     :test_case: no test found
4182     :test_file: no test found
4183
4184     A VNF **MAY** have one or more ports connected to a unique
4185     external network. All VNF ports connected to the unique external
4186     network **MUST** have Cloud Assigned IP Addresses
4187     or **MUST** have ONAP SDN-C assigned IP addresses.
4188
4189 .. req::
4190     :id: R-13841
4191     :target: VNF
4192     :keyword: MAY
4193     :test: no test found
4194     :test_case: no test found
4195     :test_file: no test found
4196
4197     A VNF **MAY** have one or more ports connected to a unique
4198     internal network. All VNF ports connected to the unique internal
4199     network **MUST** have Cloud Assigned IP Addresses
4200     or **MUST** have statically assigned IP addresses.
4201
4202 .. req::
4203     :id: R-07577
4204     :target: VNF
4205     :keyword: MUST
4206     :test: no test found
4207     :test_case: no test found
4208     :test_file: no test found
4209
4210     If the VNF's ports connected to a unique network (internal or external)
4211     and the port's IP addresses are Cloud Assigned IP Addresses,
4212     all the IPv4 Addresses **MUST** be from
4213     the same subnet and all the IPv6 Addresses **MUST** be from the
4214     same subnet.
4215
4216 .. req::
4217     :id: R-45602
4218     :target: VNF
4219     :keyword: MUST NOT
4220     :test: no test found
4221     :test_case: no test found
4222     :test_file: no test found
4223
4224     If a VNF's Port is attached to a network (internal or external)
4225     and the port's IP addresses are Cloud Assigned by OpenStack's DHCP
4226     Service, the 'OS::Neutron::Port' Resource's
4227
4228        * property 'fixed_ips' map property 'ip_address' **MUST NOT** be used
4229        * property 'fixed_ips' map property 'subnet'/'subnet_id' **MAY** be used
4230
4231 .. req::
4232     :id: R-63956
4233     :target: VNF
4234     :keyword: MAY
4235     :test: no test found
4236     :test_case: no test found
4237     :test_file: no test found
4238
4239     If the VNF's ports connected to a unique external network
4240     and the port's IP addresses are ONAP SDN-C assigned IP Addresses,
4241     the IPv4 Addresses **MAY** be from different subnets and the IPv6
4242     Addresses **MAY** be from different subnets.
4243
4244 .. req::
4245     :id: R-48880
4246     :target: VNF
4247     :keyword: MUST
4248     :test: no test found
4249     :test_case: no test found
4250     :test_file: no test found
4251
4252     If a VNF's Port is attached to an external network and the port's
4253     IP addresses are assigned by ONAP's SDN-Controller,
4254     the 'OS::Neutron::Port' Resource's
4255
4256        * property 'fixed_ips' map property 'ip_address' **MUST** be used
4257        * property 'fixed_ips' map property 'subnet'/'subnet_id' **MUST NOT** be used
4258
4259 .. req::
4260     :id: R-18001
4261     :target: VNF
4262     :keyword: MAY
4263     :test: no test found
4264     :test_case: no test found
4265     :test_file: no test found
4266
4267     If the VNF's ports connected to a unique internal network
4268     and the port's IP addresses are statically assigned IP Addresses,
4269     the IPv4 Addresses **MAY** be from different subnets and the
4270     IPv6 Addresses **MAY** be from different subnets.
4271
4272 .. req::
4273     :id: R-70964
4274     :target: VNF
4275     :keyword: MUST NOT
4276     :test: no test found
4277     :test_case: no test found
4278     :test_file: no test found
4279
4280     If a VNF's Port is attached to an internal network and the port's
4281     IP addresses are statically assigned by the VNF's Heat Orchestration\
4282     Template (i.e., enumerated in the Heat Orchestration Template's
4283     environment file), the 'OS::Neutron::Port' Resource's
4284
4285        * property 'fixed_ips' map property 'ip_address' **MUST** be used
4286        * property 'fixed_ips' map property 'subnet'/'subnet_id'
4287          **MUST NOT** be used
4288
4289 Property: network
4290 +++++++++++++++++
4291
4292 The Resource 'OS::Neutron::Port' property 'network' determines what network
4293 the port is attached to.
4294
4295
4296 .. req::
4297     :id: R-18008
4298     :target: VNF
4299     :keyword: MUST
4300
4301     The VNF's Heat Orchestration Template's Resource 'OS::Neutron::Port'
4302     property 'network' parameter **MUST** be declared as type: 'string'.
4303
4304 .. req::
4305     :id: R-62983
4306     :target: VNF
4307     :keyword: MUST
4308
4309     When the VNF's Heat Orchestration Template's Resource 'OS::Neutron::Port'
4310     is attaching to an external network, the 'network' parameter name **MUST**
4311
4312     - follow the naming convention '{network-role}_net_id' if the Neutron
4313       network UUID value is used to reference the network
4314     - follow the naming convention '{network-role}_net_name' if the OpenStack
4315       network name is used to reference the network.
4316
4317     where '{network-role}' is the network-role of the external network and
4318     a 'get_param' **MUST** be used as the intrinsic function.
4319
4320 .. req::
4321     :id: R-86182
4322     :target: VNF
4323     :keyword: MUST
4324
4325     When the VNF's Heat Orchestration Template's Resource 'OS::Neutron::Port'
4326     is attaching to an internal network, and the internal network is created in a different
4327     Heat Orchestration Template than the 'OS::Neutron::Port', the 'network'
4328     parameter name **MUST**
4329
4330     - follow the naming convention 'int\_{network-role}_net_id' if the Neutron
4331       network UUID value is used to reference the network
4332     - follow the naming convention 'int\_{network-role}_net_name' if the
4333       OpenStack network name in is used to reference the network.
4334
4335     where '{network-role}' is the network-role of the internal network and a 'get_param' **MUST** be used as the intrinsic function.
4336
4337 In Requirement R-86182, the internal network is created in the VNF's
4338 Base Module (Heat Orchestration Template) and the parameter name is
4339 declared in the Base Module's outputs' section.
4340 The output parameter name will be declared as a parameter in the
4341 'parameters' section of the incremental module.
4342
4343
4344 .. req::
4345     :id: R-93177
4346     :target: VNF
4347     :keyword: MUST
4348
4349     When the VNF's Heat Orchestration Template's
4350     Resource 'OS::Neutron::Port' is attaching to an internal
4351     network, and the internal network is created in the same Heat
4352     Orchestration Template than the 'OS::Neutron::Port', the 'network'
4353     parameter name **MUST** obtain the UUID of the internal network
4354     by using the intrinsic function 'get_resource' or 'get_attr'
4355     and referencing the Resource ID of the internal network.
4356
4357 .. req::
4358     :id: R-29872
4359     :target: VNF
4360     :keyword: MUST NOT
4361
4362     The VNF's Heat Orchestration Template's Resource 'OS::Nova::Server'
4363     property 'network' parameter **MUST NOT** be enumerated in the Heat
4364     Orchestration Template's Environment File.
4365
4366 The parameter values for external networks are provided by ONAP
4367 to the VNF's Heat Orchestration Template at orchestration time.
4368
4369 The parameter values for internal networks created in the VNF's Base Module
4370 Heat Orchestration Template
4371 are provided to the VNF's Incremental Module Heat Orchestration Template
4372 at orchestration time.
4373
4374 *Example Parameter Definition of External Networks*
4375
4376 .. code-block:: yaml
4377
4378   parameters:
4379
4380     {network-role}_net_id:
4381       type: string
4382       description: Neutron UUID for the external {network-role} network
4383
4384     {network-role}_net_name:
4385       type: string
4386       description: Neutron name for the external {network-role} network
4387
4388
4389 *Example Parameter Definition of Internal Networks in an Incremental Module*
4390
4391 .. code-block:: yaml
4392
4393   parameters:
4394
4395     int_{network-role}_net_id:
4396       type: string
4397       description: Neutron UUID for the internal int_{network-role} network
4398
4399     int_{network-role}_net_name:
4400       type: string
4401       description: Neutron name for the internal int_{network-role} network
4402
4403 Property: fixed_ips, Map Property: ip_address
4404 +++++++++++++++++++++++++++++++++++++++++++++
4405
4406 The resource 'OS::Neutron::Port' property 'fixed_ips'
4407 map property 'ip_address'
4408 is used to assign one IPv4 or IPv6
4409 addresses to port.
4410
4411 One 'OS::Neutron::Port' resource may assign one or more
4412 IPv4 and/or IPv6 addresses.
4413
4414
4415 .. req::
4416     :id: R-34037
4417     :target: VNF
4418     :keyword: MUST
4419
4420     The VNF's Heat Orchestration Template's resource 'OS::Neutron::Port'
4421     property 'fixed_ips' map property 'ip_address' parameter **MUST**
4422     be declared as either type 'string' or type 'comma_delimited_list'.
4423
4424 .. req::
4425     :id: R-40971
4426     :target: VNF
4427     :keyword: MUST
4428
4429     When the VNF's Heat Orchestration Template's Resource
4430     'OS::Neutron::Port' is attaching to an external network, and an IPv4
4431     address is assigned using the property 'fixed_ips' map property
4432     'ip_address' and the parameter type is defined
4433     as a string, the parameter name **MUST** follow the naming
4434     convention
4435       - '{vm-type}_{network-role}\_ip\_{index}'
4436
4437     where
4438
4439       - '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
4440       - '{network-role}' is the {network-role} of the external network
4441       - the value for {index} must start at zero (0) and increment by one
4442
4443 .. req::
4444     :id: R-39841
4445     :target: VNF
4446     :keyword: MUST NOT
4447
4448     The VNF's Heat Orchestration Template's Resource 'OS::Neutron::Port'
4449     property 'fixed_ips' map property 'ip_address' parameter
4450     '{vm-type}_{network-role}\_ip\_{index}' **MUST NOT** be enumerated in the
4451     VNF's Heat Orchestration Template's Environment File.
4452
4453 ONAP's SDN-Controller assigns the IP Address and ONAP provides
4454 the value at orchestration to the Heat Orchestration Template.
4455
4456 *Example External Network IPv4 Address string Parameter Definition*
4457
4458 .. code-block:: yaml
4459
4460   parameters:
4461
4462     {vm-type}_{network-role}_ip_{index}:
4463       type: string
4464       description: Fixed IPv4 assignment for {vm-type} VM {index} on the{network-role} network
4465
4466
4467 .. req::
4468     :id: R-04697
4469     :target: VNF
4470     :keyword: MUST
4471
4472     When the VNF's Heat Orchestration Template's Resource 'OS::Neutron::Port'
4473     is attaching to an external network, and an IPv4 address is assigned using
4474     the property 'fixed_ips' map property 'ip_address' and the parameter type
4475     is defined as a comma_delimited_list, the parameter name **MUST** follow the
4476     naming convention
4477
4478       * '{vm-type}_{network-role}_ips',
4479
4480     where
4481
4482       * '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
4483       * '{network-role}' is the {network-role} of the external network
4484
4485 .. req::
4486     :id: R-98905
4487     :target: VNF
4488     :keyword: MUST NOT
4489
4490     The VNF's Heat Orchestration Template's Resource 'OS::Neutron::Port'
4491     property 'fixed_ips' map property 'ip_address' parameter
4492     '{vm-type}_{network-role}_ips' **MUST NOT** be enumerated in the VNF's
4493     Heat Orchestration Template's Environment File.
4494
4495 ONAP's SDN-Controller assigns the IP Address and ONAP provides
4496 the value at orchestration to the Heat Orchestration Template.
4497
4498 *Example External Network IPv4 Address comma_delimited_list
4499 Parameter Definition*
4500
4501 .. code-block:: yaml
4502
4503   parameters:
4504
4505     {vm-type}_{network-role}_ips:
4506       type: comma_delimited_list
4507       description: Fixed IPv4 assignments for {vm-type} VMs on the {network-role} network
4508
4509
4510 .. req::
4511     :id: R-71577
4512     :target: VNF
4513     :keyword: MUST
4514
4515     When the VNF's Heat Orchestration Template's Resource
4516     'OS::Neutron::Port' is attaching to an external network, and an IPv6 address
4517     is assigned using the property 'fixed_ips' map property 'ip_address' and
4518     the parameter type is defined as a string, the parameter name **MUST** follow
4519     the naming convention
4520
4521       * '{vm-type}_{network-role}\_v6\_ip\_{index}'
4522
4523     where
4524
4525       * '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
4526       * '{network-role}' is the {network-role} of the external network
4527       * the value for {index} must start at zero (0) and increment by one
4528
4529 .. req::
4530     :id: R-87123
4531     :target: VNF
4532     :keyword: MUST NOT
4533
4534     The VNF's Heat Orchestration Template's Resource
4535     'OS::Neutron::Port' property 'fixed_ips' map property 'ip_address'
4536     parameter '{vm-type}_{network-role}\_v6\_ip\_{index}'
4537     **MUST NOT** be enumerated in the VNF's Heat Orchestration
4538     Template's Environment File.
4539
4540 ONAP's SDN-Controller assigns the IP Address and ONAP provides
4541 the value at orchestration to the Heat Orchestration Template.
4542
4543 *Example External Network IPv6 Address string Parameter Definition*
4544
4545 .. code-block:: yaml
4546
4547   parameters:
4548
4549     {vm-type}_{network-role}_v6_ip_{index}:
4550       type: string
4551       description: Fixed IPv6 assignment for {vm-type} VM {index} on the {network-role} network
4552
4553
4554 .. req::
4555     :id: R-23503
4556     :target: VNF
4557     :keyword: MUST
4558
4559     When the VNF's Heat Orchestration Template's Resource
4560     'OS::Neutron::Port' is attaching to an external network, and an IPv6
4561     address is assigned using the property 'fixed_ips' map property 'ip_address'
4562     and the parameter type is defined as a comma_delimited_list, the parameter
4563     name **MUST** follow the naming convention
4564
4565       * '{vm-type}_{network-role}_v6_ips'
4566
4567     where
4568
4569       * '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
4570       * '{network-role}' is the {network-role} of the external network
4571
4572 .. req::
4573     :id: R-93030
4574     :target: VNF
4575     :keyword: MUST NOT
4576
4577     The VNF's Heat Orchestration Template's Resource
4578     'OS::Neutron::Port' property 'fixed_ips' map property 'ip_address'
4579     parameter '{vm-type}_{network-role}_v6_ips' **MUST NOT** be enumerated in the
4580     VNF's Heat Orchestration Template's Environment File.
4581
4582 ONAP's SDN-Controller assigns the IP Address and ONAP provides
4583 the value at orchestration to the Heat Orchestration Template.
4584
4585 *Example External Network IPv6 Address comma_delimited_list Parameter
4586 Definition*
4587
4588 .. code-block:: yaml
4589
4590   parameters:
4591
4592     {vm-type}_{network-role}_v6_ips:
4593       type: comma_delimited_list
4594       description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
4595
4596
4597 .. req::
4598     :id: R-78380
4599     :target: VNF
4600     :keyword: MUST
4601
4602     When the VNF's Heat Orchestration Template's Resource
4603     'OS::Neutron::Port' is attaching to an internal network, and an IPv4 address
4604     is assigned using the property 'fixed_ips' map property 'ip_address' and
4605     the parameter type is defined as a string, the parameter name **MUST** follow
4606     the naming convention
4607
4608        * '{vm-type}\_int\_{network-role}\_ip\_{index}'
4609
4610     where
4611
4612        * '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
4613        * '{network-role}' is the {network-role} of the internal network
4614        * the value for {index} must start at zero (0) and increment by one
4615
4616 .. req::
4617     :id: R-28795
4618     :target: VNF
4619     :keyword: MUST
4620
4621     The VNF's Heat Orchestration Template's Resource
4622     'OS::Neutron::Port' property 'fixed_ips' map property 'ip_address'
4623     parameter '{vm-type}\_int\_{network-role}\_ip\_{index}' **MUST** be enumerated
4624     in the VNF's Heat Orchestration Template's Environment File.
4625
4626 The IP address is local to the VNF's internal network and is (re)used
4627 in every VNF spin up, thus the constant value is declared in the VNF's
4628 Heat Orchestration Template's Environment File.
4629
4630 *Example Internal Network IPv4 Address string Parameter Definition*
4631
4632 .. code-block:: yaml
4633
4634   parameters:
4635
4636     {vm-type}_int_{network-role}_ip_{index}:
4637       type: string
4638       description: Fixed IPv4 assignment for {vm-type} VM {index} on the int_{network-role} network
4639
4640
4641 .. req::
4642     :id: R-85235
4643     :target: VNF
4644     :keyword: MUST
4645
4646     When the VNF's Heat Orchestration Template's Resource
4647     'OS::Neutron::Port' is attaching to an internal network, and an IPv4
4648     address is assigned using the property 'fixed_ips' map property 'ip_address'
4649     and the parameter type is defined as a comma_delimited_list, the parameter
4650     name **MUST** follow the naming convention
4651
4652        * '{vm-type}\_int\_{network-role}_ips'
4653
4654     where
4655
4656        * '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
4657        * '{network-role}' is the {network-role} of the internal network
4658
4659 .. req::
4660     :id: R-90206
4661     :target: VNF
4662     :keyword: MUST
4663
4664     The VNF's Heat Orchestration Template's Resource
4665     'OS::Neutron::Port' property 'fixed_ips' map property 'ip_address'
4666     parameter '{vm-type}\_int\_{network-role}_int_ips' **MUST** be enumerated in
4667     the VNF's Heat Orchestration Template's Environment File.
4668
4669 The IP address is local to the VNF's internal network and is (re)used
4670 in every VNF spin up, thus the constant value is declared in the VNF's
4671 Heat Orchestration Template's Environment File.
4672
4673 .. code-block:: yaml
4674
4675   parameters:
4676
4677     {vm-type}_int_{network-role}_ips:
4678       type: comma_delimited_list
4679       description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
4680
4681
4682 .. req::
4683     :id: R-27818
4684     :target: VNF
4685     :keyword: MUST
4686
4687     When the VNF's Heat Orchestration Template's Resource
4688     'OS::Neutron::Port' is attaching to an internal network, and an IPv6 address
4689     is assigned using the property 'fixed_ips' map property 'ip_address' and
4690     the parameter type is defined as a string, the parameter name **MUST** follow
4691     the naming convention
4692
4693        * '{vm-type}\_int\_{network-role}\_v6\_ip\_{index}'
4694
4695     where
4696
4697        * '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
4698        * '{network-role}' is the {network-role} of the internal network
4699        * the value for {index} must start at zero (0) and increment by one
4700
4701 .. req::
4702     :id: R-97201
4703     :target: VNF
4704     :keyword: MUST
4705
4706     The VNF's Heat Orchestration Template's Resource
4707     'OS::Neutron::Port' property 'fixed_ips' map property 'ip_address'
4708     parameter '{vm-type}\_int\_{network-role}\_v6\_ip\_{index}'
4709     **MUST** be enumerated in the VNF's Heat Orchestration
4710     Template's Environment File.
4711
4712 The IP address is local to the VNF's internal network and is (re)used
4713 in every VNF spin up, thus the constant value is declared in the VNF's
4714 Heat Orchestration Template's Environment File.
4715
4716 *Example Internal Network IPv6 Address string Parameter Definition*
4717
4718 .. code-block:: yaml
4719
4720   parameters:
4721
4722     {vm-type}_int_{network-role}_v6_ip_{index}:
4723       type: string
4724       description: Fixed IPv6 assignment for {vm-type} VM {index} on the int_{network-role} network
4725
4726
4727 .. req::
4728     :id: R-29765
4729     :target: VNF
4730     :keyword: MUST
4731
4732     When the VNF's Heat Orchestration Template's Resource
4733     'OS::Neutron::Port' is attaching to an internal network, and an IPv6
4734     address is assigned using the property 'fixed_ips' map property 'ip_address'
4735     and the parameter type is defined as a comma_delimited_list, the parameter
4736     name **MUST** follow the naming convention
4737
4738        * '{vm-type}\_int\_{network-role}_v6_ips'
4739
4740     where
4741
4742        * '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
4743        * '{network-role}' is the {network-role} of the internal network
4744
4745 *Example Internal Network IPv6 Address comma_delimited_list Parameter
4746 Definition*
4747
4748 .. code-block:: yaml
4749
4750   parameters:
4751
4752     {vm-type}_int_{network-role}_v6_ips:
4753       type: comma_delimited_list
4754       description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
4755
4756
4757 .. req::
4758     :id: R-98569
4759     :target: VNF
4760     :keyword: MUST
4761
4762     The VNF's Heat Orchestration Template's Resource
4763     'OS::Neutron::Port' property 'fixed_ips' map property 'ip_address'
4764     parameter '{vm-type}\_int\_{network-role}_v6_ips' **MUST** be enumerated in
4765     the VNF's Heat Orchestration Template's Environment File.
4766
4767 The IP address is local to the VNF's internal network and is (re)used
4768 in every VNF spin up, thus the constant value is declared in the VNF's
4769 Heat Orchestration Template's Environment File.
4770
4771
4772 .. req::
4773     :id: R-62590
4774     :target: VNF
4775     :keyword: MUST NOT
4776
4777     The VNF's Heat Orchestration Template's Resource
4778     'OS::Neutron::Port' property 'fixed_ips' map property 'ip_address'
4779     parameter associated with an external network, i.e.,
4780
4781     - {vm-type}_{network-role}\_ip\_{index}
4782     - {vm-type}_{network-role}\_ip\_v6\_{index}
4783     - {vm-type}_{network-role}_ips
4784     - {vm-type}_{network-role}_v6_ips
4785
4786     **MUST NOT** be enumerated in the Heat Orchestration Template's Environment File.
4787     ONAP provides the IP address assignments at orchestration time.
4788
4789 .. req::
4790     :id: R-93496
4791     :target: VNF
4792     :keyword: MUST
4793
4794     The VNF's Heat Orchestration Template's Resource
4795     'OS::Neutron::Port' property 'fixed_ips' map property 'ip_address'
4796     parameter associated with an internal network, i.e.,
4797
4798     - {vm-type}\_int\_{network-role}\_ip\_{index}
4799     - {vm-type}\_int\_{network-role}\_ip\_v6\_{index}
4800     - {vm-type}\_int\_{network-role}_ips
4801     - {vm-type}\_int\_{network-role}_v6_ips
4802
4803     **MUST** be enumerated in the Heat Orchestration Template's Environment
4804     File and IP addresses **MUST** be assigned.
4805
4806 Summary Table
4807 _____________
4808
4809 .. csv-table:: **Table # OS::Neutron::Port Property fixed_ips map property ip_address Parameter Naming Convention**
4810    :header: Resource,Property,Map Property,Network Type,IP Address,Parameter Type,Parameter Name, Environment File
4811    :align: center
4812    :widths: auto
4813
4814    OS::Neutron::Port, fixed_ips, ip_address, external, IPv4, string, {vm-type}\_{network-role}\_ip\_{index}, NO
4815    OS::Neutron::Port, fixed_ips, ip_address, external, IPv4, comma\_delimited\_list, {vm-type}\_{network-role}\_ips, NO
4816    OS::Neutron::Port, fixed_ips, ip_address, external, IPv6, string, {vm-type}\_{network-role}\_v6\_ip\_{index}, NO
4817    OS::Neutron::Port, fixed_ips, ip_address, external, IPv6, comma\_delimited\_list, {vm-type}\_{network-role}\_v6\_ips, NO
4818    OS::Neutron::Port, fixed_ips, ip_address, internal, IPv4, string, {vm-type}\_int\_{network-role}\_ip\_{index}, YES
4819    OS::Neutron::Port, fixed_ips, ip_address, internal, IPv4, comma\_delimited\_list, {vm-type}\_int\_{network-role}\_ips, YES
4820    OS::Neutron::Port, fixed_ips, ip_address, internal, IPv6, string, {vm-type}\_int\_{network-role}\_v6\_ip\_{index}, YES
4821    OS::Neutron::Port, fixed_ips, ip_address, internal, IPv6, comma\_delimited\_list, {vm-type}\_int\_{network-role}\_v6\_ips, YES
4822
4823
4824 Examples
4825 ________
4826
4827 *Example: comma_delimited_list parameters for IPv4 and IPv6 Address
4828 Assignments to an external network*
4829
4830 In this example, the '{network-role}' has been defined as 'oam' to represent
4831 an oam network and the '{vm-type}' has been defined as 'db' for database.
4832
4833 .. code-block:: yaml
4834
4835   parameters:
4836     oam_net_id:
4837       type: string
4838       description: Neutron UUID for a oam network
4839     db_oam_ips:
4840       type: comma_delimited_list
4841       description: Fixed IPv4 assignments for db VMs on the oam network
4842     db_oam_v6_ips:
4843       type: comma_delimited_list
4844       description: Fixed IPv6 assignments for db VMs on the oam network
4845   resources:
4846     db_0_oam_port_0:
4847       type: OS::Neutron::Port
4848       properties:
4849         network: { get_param: oam_net_id }
4850         fixed_ips: [ { "ip_address": {get_param: [ db_oam_ips, 0 ]}}, {
4851         "ip_address": {get_param: [ db_oam_v6_ips, 0 ]}}]
4852     db_1_oam_port_0:
4853       type: OS::Neutron::Port
4854       properties:
4855         network: { get_param: oam_net_id }
4856         fixed_ips:
4857           - "ip_address": {get_param: [ db_oam_ips, 1 ]}
4858           - "ip_address": {get_param: [ db_oam_v6_ips, 1 ]}
4859
4860 *Example: string parameters for IPv4 and IPv6 Address Assignments to an
4861 external network*
4862
4863 In this example, the '{network-role}' has been defined as 'oam' to
4864 represent an oam network and the '{vm-type}' has been defined as 'db' for
4865 database.
4866
4867 .. code-block:: yaml
4868
4869   parameters:
4870     oam_net_id:
4871       type: string
4872       description: Neutron UUID for an OAM network
4873     db_oam_ip_0:
4874       type: string
4875       description: Fixed IPv4 assignment for db VM 0 on the OAM network
4876     db_oam_ip_1:
4877       type: string
4878       description: Fixed IPv4 assignment for db VM 1 on the OAM network
4879     db_oam_v6_ip_0:
4880       type: string
4881       description: Fixed IPv6 assignment for db VM 0 on the OAM network
4882     db_oam_v6_ip_1:
4883       type: string
4884       description: Fixed IPv6 assignment for db VM 1 on the OAM network
4885   resources:
4886     db_0_oam_port_0:
4887       type: OS::Neutron::Port
4888       properties:
4889         network: { get_param: oam_net_id }
4890         fixed_ips: [ { "ip_address": {get_param: db_oam_ip_0}}, { "ip_address": {get_param: db_oam_v6_ip_0 }}]
4891     db_1_oam_port_0:
4892       type: OS::Neutron::Port
4893       properties:
4894         network: { get_param: oam_net_id }
4895         fixed_ips:
4896           - "ip_address": {get_param: db_oam_ip_1}
4897           - "ip_address": {get_param: db_oam_v6_ip_1}
4898
4899
4900 *Example: comma_delimited_list parameters for IPv4 and IPv6 Address
4901 Assignments to an internal network*
4902
4903 In this example, the '{network-role}' has been defined as 'ctrl' to
4904 represent an ctrl network internal to the vnf.
4905 The '{vm-type}' has been defined as 'db' for
4906 database.
4907
4908 .. code-block:: yaml
4909
4910   parameters:
4911     int_ctrl_net_id:
4912       type: string
4913       description: Neutron UUID for the ctrl internal network
4914     db_int_ctrl_ips:
4915       type: comma_delimited_list
4916       description: Fixed IPv4 assignments for db VMs on the ctrl internal
4917       network
4918     db_int_ctrl_v6_ips:
4919       type: comma_delimited_list
4920       description: Fixed IPv6 assignments for db VMs on the ctrl internal
4921       network
4922   resources:
4923     db_0_int_ctrl_port_0:
4924       type: OS::Neutron::Port
4925       properties:
4926         network: { get_param: int_ctrl_net_id }
4927         fixed_ips: [ { "ip_address": {get_param: [ db_int_ctrl_ips, 0 ]}}, {
4928         "ip_address": {get_param: [ db_int_ctrl_v6_ips, 0 ]}}]
4929     db_1_int_ctrl_port_0:
4930       type: OS::Neutron::Port
4931       properties:
4932         network: { get_param: int_ctrl_net_id }
4933         fixed_ips:
4934         - "ip_address": {get_param: [ db_int_ctrl_ips, 1 ]}
4935         - "ip_address": {get_param: [ db_int_ctrl_v6_ips, 1 ]}
4936
4937
4938 *Example: string parameters for IPv4 and IPv6 Address Assignments to an
4939 internal network*
4940
4941 In this example, the int\_{network-role} has been defined as
4942 int_ctrl to represent a control network internal to the vnf.
4943 The {vm-type} has been defined as db for database.
4944
4945 .. code-block:: yaml
4946
4947   parameters:
4948     int_ctrl_net_id:
4949       type: string
4950       description: Neutron UUID for an OAM internal network
4951     db_int_ctrl_ip_0:
4952       type: string
4953       description: Fixed IPv4 assignment for db VM on the oam_int network
4954     db_int_ctrl_ip_1:
4955       type: string
4956       description: Fixed IPv4 assignment for db VM 1 on the oam_int network
4957     db_int_ctrl_v6_ip_0:
4958       type: string
4959       description: Fixed IPv6 assignment for db VM 0 on the oam_int network
4960     db_int_ctrl_v6_ip_1:
4961       type: string
4962       description: Fixed IPv6 assignment for db VM 1 on the oam_int network
4963   resources:
4964     db_0_int_ctrl_port_0:
4965       type: OS::Neutron::Port
4966       properties:
4967         network: { get_param: int_oam_int_net_id }
4968         fixed_ips: [ { "ip_address": {get_param: db_oam_int_ip_0}}, {
4969         "ip_address": {get_param: db_oam_int_v6_ip_0 }}]
4970     db_1_int_ctrl_port_0:
4971       type: OS::Neutron::Port
4972       properties:
4973         network: { get_param: int_oam_int_net_id }
4974         fixed_ips:
4975           - "ip_address": {get_param: db_oam_int_ip_1}
4976           - "ip_address": {get_param: db_oam_int_v6_ip_1}
4977
4978
4979 Property: fixed\_ips, Map Property: subnet\_id
4980 ++++++++++++++++++++++++++++++++++++++++++++++
4981
4982 The resource 'OS::Neutron::Port' property 'fixed_ips' map
4983 property 'subnet'/'subnet_id' is used when a
4984 port is requesting an IP assignment via
4985 OpenStack's DHCP Service (i.e., Cloud Assigned).
4986
4987 The IP address assignment will be made from the specified subnet.
4988
4989 Specifying the subnet is not required; it is optional.
4990
4991 If the network (external or internal) that the port is attaching
4992 to only contains one subnet, specifying the subnet is
4993 superfluous.  The IP address will be assigned from the one existing
4994 subnet.
4995
4996 If the network (external or internal) that the port is attaching
4997 to contains two or more subnets, specifying the subnet in the
4998 'fixed_ips' map property 'subnet'/'subnet_id' determines which
4999 subnet the IP address will be assigned from.
5000
5001 If the network (external or internal) that the port is attaching
5002 to contains two or more subnets, and the subnet is not is not
5003 specified, OpenStack will randomly(?) determine which subnet
5004 the IP address will be assigned from.
5005
5006 The property fixed_ips is used to assign IPs to a port. The Map Property
5007 subnet_id specifies the subnet the IP is assigned from.
5008
5009
5010 .. req::
5011     :id: R-38236
5012     :target: VNF
5013     :keyword: MUST
5014
5015     The VNF's Heat Orchestration Template's resource
5016     'OS::Neutron::Port' property 'fixed_ips' map property
5017     'subnet'/'subnet_id' parameter **MUST** be declared type 'string'.
5018
5019 .. req::
5020     :id: R-62802
5021     :target: VNF
5022     :keyword: MUST
5023
5024     When the VNF's Heat Orchestration Template's resource
5025     'OS::Neutron::Port' is attaching to an external network, and an IPv4
5026     address is being Cloud Assigned by OpenStack's DHCP Service and the
5027     external network IPv4 subnet is to be specified using the property
5028     'fixed_ips' map property 'subnet'/'subnet_id', the parameter **MUST**
5029     follow the naming convention
5030
5031        * '{network-role}_subnet_id'
5032
5033     where
5034
5035        * '{network-role}' is the network role of the network.
5036
5037 .. req::
5038     :id: R-83677
5039     :target: VNF
5040     :keyword: MUST NOT
5041
5042     The VNF's Heat Orchestration Template's Resource
5043     'OS::Neutron::Port' property 'fixed_ips' map property
5044     subnet'/'subnet_id' parameter '{network-role}_subnet_id'
5045     **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's
5046     Environment File.
5047
5048 ONAP's SDN-Controller provides the network's subnet's UUID
5049 value at orchestration to the Heat Orchestration Template.
5050
5051 *Example Parameter Definition*
5052
5053 .. code-block:: yaml
5054
5055   parameters:
5056
5057     {network-role}_subnet_id:
5058       type: string
5059       description: Neutron IPv4 subnet UUID for the {network-role} network
5060
5061
5062 .. req::
5063     :id: R-15287
5064     :target: VNF
5065     :keyword: MUST
5066
5067     When the VNF's Heat Orchestration Template's resource
5068     'OS::Neutron::Port' is attaching to an external network, and an IPv6
5069     address is being Cloud Assigned by OpenStack's DHCP Service and the
5070     external network IPv6 subnet is to be specified using the property
5071     'fixed_ips' map property 'subnet'/'subnet_id', the parameter **MUST**
5072     follow the naming convention
5073
5074        * '{network-role}_subnet_v6_id'
5075
5076     where
5077
5078        * '{network-role}' is the network role of the network.
5079
5080 .. req::
5081     :id: R-80829
5082     :target: VNF
5083     :keyword: MUST NOT
5084
5085     The VNF's Heat Orchestration Template's Resource
5086     'OS::Neutron::Port' property 'fixed_ips' map property
5087     subnet'/'subnet_id' parameter '{network-role}_subnet_v6_id'
5088     **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's
5089     Environment File.
5090
5091 ONAP's SDN-Controller provides the network's subnet's UUID
5092 value at orchestration to the Heat Orchestration Template.
5093
5094 *Example Parameter Definition*
5095
5096 .. code-block:: yaml
5097
5098   parameters:
5099
5100     {network-role}_v6_subnet_id:
5101       type: string
5102       description: Neutron IPv6 subnet UUID for the {network-role} network
5103
5104
5105 *Example: One Cloud Assigned IPv4 Address (DHCP) assigned to a network
5106 that has two or more IPv4 subnets*
5107
5108 In this example, the '{network-role}' has been defined as 'oam' to represent
5109 an oam network and the '{vm-type}' has been defined as 'lb' for load
5110 balancer. The Cloud Assigned IP Address uses the OpenStack DHCP service
5111 to assign IP addresses.
5112
5113 .. code-block:: yaml
5114
5115   parameters:
5116     oam_net_id:
5117       type: string
5118       description: Neutron UUID for the oam network
5119     oam_subnet_id:
5120       type: string
5121       description: Neutron IPv4 subnet UUID for the oam network
5122   resources:
5123     lb_0_oam_port_0:
5124       type: OS::Neutron::Port
5125         parameters:
5126           network: { get_param: oam_net_id }
5127           fixed_ips:
5128             - subnet_id: { get_param: oam_subnet_id }
5129
5130 *Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6
5131 address assigned to a network that has at least one IPv4 subnet and one
5132 IPv6 subnet*
5133
5134 In this example, the '{network-role}' has been defined as 'oam' to represent
5135 an oam network and the '{vm-type}' has been defined as 'lb' for load
5136 balancer.
5137
5138 .. code-block:: yaml
5139
5140   parameters:
5141     oam_net_id:
5142       type: string
5143       description: Neutron UUID for the oam network
5144     oam_subnet_id:
5145       type: string
5146       description: Neutron IPv4 subnet UUID for the oam network
5147     oam_v6_subnet_id:
5148       type: string
5149       description: Neutron IPv6 subnet UUID for the oam network
5150   resources:
5151     lb_0_oam_port_0:
5152       type: OS::Neutron::Port
5153       properties:
5154         network: { get_param: oam_net_id }
5155         fixed_ips:
5156           - subnet_id: { get_param: oam_subnet_id }
5157           - subnet_id: { get_param: oam_v6_subnet_id }
5158
5159
5160 .. req::
5161     :id: R-84123
5162     :target: VNF
5163     :keyword: MUST
5164
5165     When
5166
5167     - the VNF's Heat Orchestration Template's resource 'OS::Neutron::Port'
5168       in an Incremental Module is attaching to an internal network
5169       that is created in the Base Module, AND
5170     - an IPv4 address is being Cloud Assigned by OpenStack's DHCP Service AND
5171     - the internal network IPv4 subnet is to be specified using the
5172       property 'fixed_ips' map property 'subnet'/'subnet_id',
5173
5174     the parameter **MUST** follow the naming convention
5175        * 'int\_{network-role}_subnet_id'
5176     where
5177        * '{network-role}' is the network role of the internal network
5178
5179     - Note that the parameter **MUST** be defined as an 'output' parameter in
5180       the base module.
5181
5182 .. req::
5183     :id: R-69634
5184     :target: VNF
5185     :keyword: MUST NOT
5186
5187     The VNF's Heat Orchestration Template's Resource
5188     'OS::Neutron::Port' property 'fixed_ips' map property
5189     subnet'/'subnet_id' parameter 'int\_{network-role}_subnet_id'
5190     **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's
5191     Environment File.
5192
5193 The assumption is that internal networks are created in the base module.
5194 The Neutron subnet network ID will be passed as an output parameter
5195 (e.g., ONAP Base Module Output Parameter) to the incremental modules.
5196 In the incremental modules, the output parameter name will be defined as
5197 input parameter.
5198
5199 *Example Parameter Definition*
5200
5201 .. code-block:: yaml
5202
5203   parameters:
5204
5205     int_{network-role}_subnet_id:
5206       type: string
5207       description: Neutron IPv4 subnet UUID for the int_{network-role} network
5208
5209
5210 .. req::
5211     :id: R-76160
5212     :target: VNF
5213     :keyword: MUST
5214
5215     When
5216
5217     - the VNF's Heat Orchestration Template's resource
5218       'OS::Neutron::Port' in an Incremental Module is attaching to an
5219       internal network that is created in the Base Module, AND
5220     - an IPv6 address is being Cloud Assigned by OpenStack's DHCP Service AND
5221     - the internal network IPv6 subnet is to be specified using the property
5222       'fixed_ips' map property 'subnet'/'subnet_id',
5223
5224     the parameter **MUST** follow the naming convention
5225        * 'int\_{network-role}_v6_subnet_id'
5226     where
5227        * '{network-role}' is the network role of the internal network
5228
5229     - Note that the parameter **MUST** be defined as an 'output' parameter in
5230       the base module.
5231
5232 .. req::
5233     :id: R-22288
5234     :target: VNF
5235     :keyword: MUST NOT
5236
5237     The VNF's Heat Orchestration Template's Resource
5238     'OS::Neutron::Port' property 'fixed_ips' map property
5239     'subnet'/'subnet_id' parameter 'int\_{network-role}_v6_subnet_id'
5240     **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's
5241     Environment File.
5242
5243 *Example Parameter Definition*
5244
5245 .. code-block:: yaml
5246
5247   parameters:
5248
5249     int_{network-role}_v6_subnet_id:
5250       type: string
5251       description: Neutron subnet UUID for the int_{network-role} network
5252
5253
5254 Property: allowed\_address\_pairs, Map Property: ip\_address
5255 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
5256
5257 The property 'allowed_address_pairs' in the resource 'OS::Neutron::Port'
5258 allows the user to specify a mac_address and/or ip_address that will
5259 pass through a port regardless of subnet. This enables the use of
5260 protocols, such as VRRP, which allow for a Virtual IP (VIP) address
5261 to be shared among two or more ports, with one designated as the master
5262 and the others as backups. In case the master fails,
5263 the Virtual IP address is mapped to a backup's IP address and
5264 the backup becomes the master.
5265
5266 Note that the management of the VIP IP addresses (i.e. transferring
5267 ownership between active and standby VMs) is the responsibility of
5268 the VNF application.
5269
5270
5271 .. req::
5272     :id: R-62300
5273     :target: VNF
5274     :keyword: MUST
5275
5276     If a VNF has two or more ports that require a Virtual IP Address (VIP),
5277     a VNF's Heat Orchestration Template's Resource 'OS::Neutron::Port' property
5278     'allowed_address_pairs' map property 'ip_address' parameter **MUST** be used.
5279
5280 The 'allowed_address_pairs' is an optional property. It is not required.
5281
5282 ONAP automation supports the assignment of VIP addresses
5283 for external networks. ONAP support the assignment of one IPv4 VIP address
5284 and/or one IPv6 VIP address to a set of ports associated with a
5285 '{vm-type}' and '{network-role}'.
5286
5287 If a VNF requires more than one IPv4 VIP address
5288 and/or more than one IPv6 VIP address to a set of ports associated with a
5289 '{vm-type}' and '{network-role}', there are "manual" work-around
5290 procedures that can be utilized.
5291
5292 VIP Assignment, External Networks, Supported by Automation
5293 __________________________________________________________
5294
5295
5296
5297 .. req::
5298     :id: R-91810
5299     :target: VNF
5300     :keyword: MUST NOT
5301     :test: no test found
5302     :test_case: no test found
5303     :test_file: no test found
5304
5305     If a VNF requires ONAP to assign a Virtual IP (VIP) Address to
5306     ports connected an external network, the port
5307     **MUST NOT** have more than one IPv4 VIP address.
5308
5309 .. req::
5310     :id: R-41956
5311     :target: VNF
5312     :keyword: MUST NOT
5313     :test: no test found
5314     :test_case: no test found
5315     :test_file: no test found
5316
5317     If a VNF requires ONAP to assign a Virtual IP (VIP) Address to
5318     ports connected an external network, the port
5319     **MUST NOT** have more than one IPv6 VIP address.
5320
5321 .. req::
5322     :id: R-10754
5323     :target: VNF
5324     :keyword: MUST
5325     :test: no test found
5326     :test_case: no test found
5327     :test_file: no test found
5328
5329     If a VNF has two or more ports that
5330     attach to an external network that require a Virtual IP Address (VIP),
5331     and the VNF requires ONAP automation to assign the IP address,
5332     all the Virtual Machines using the VIP address **MUST**
5333     be instantiated in the same Base Module Heat Orchestration Template
5334     or in the same Incremental Module Heat Orchestration Template.
5335
5336 .. req::
5337     :id: R-98748
5338     :target: VNF
5339     :keyword: MUST
5340     :test: no test found
5341     :test_case: no test found
5342     :test_file: no test found
5343
5344     The VNF's Heat Orchestration Template's Resource
5345     'OS::Neutron::Port' property 'allowed_address_pairs'
5346     map property 'ip_address' parameter
5347     **MUST** be declared as type 'string'.
5348
5349 .. req::
5350     :id: R-41492
5351     :target: VNF
5352     :keyword: MUST
5353     :test: no test found
5354     :test_case: no test found
5355     :test_file: no test found
5356
5357     When the VNF's Heat Orchestration Template's Resource
5358     'OS::Neutron::Port' is attaching to an external network,
5359     and an IPv4 Virtual IP (VIP) address is assigned via ONAP automation
5360     using the property 'allowed_address_pairs' map property 'ip_address' and
5361     the parameter name **MUST** follow the naming convention
5362
5363        * '{vm-type}_{network-role}_floating_ip'
5364
5365     where
5366
5367        * '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
5368        * '{network-role}' is the {network-role} of the external network
5369
5370     And the parameter **MUST** be declared as type 'string'.
5371
5372 .. req::
5373     :id: R-83412
5374     :target: VNF
5375     :keyword: MUST NOT
5376     :test: no test found
5377     :test_case: no test found
5378     :test_file: no test found
5379
5380     The VNF's Heat Orchestration Template's Resource
5381     'OS::Neutron::Port' property 'allowed_address_pairs'
5382     map property 'ip_address' parameter
5383     '{vm-type}_{network-role}_floating_ip'
5384     **MUST NOT** be enumerated in the
5385     VNF's Heat Orchestration Template's Environment File.
5386
5387 *Example Parameter Definition*
5388
5389 .. code-block:: yaml
5390
5391   parameters:
5392
5393     {vm-type}_{network-role}_floating_ip:
5394       type: string
5395       description: IPv4 VIP for {vm-type} VMs on the {network-role} network
5396
5397
5398
5399
5400 .. req::
5401     :id: R-35735
5402     :target: VNF
5403     :keyword: MUST
5404     :test: no test found
5405     :test_case: no test found
5406     :test_file: no test found
5407
5408     When the VNF's Heat Orchestration Template's Resource
5409     'OS::Neutron::Port' is attaching to an external network,
5410     and an IPv6 Virtual IP (VIP) address is assigned via ONAP automation
5411     using the property 'allowed_address_pairs' map property 'ip_address',
5412     the parameter name **MUST** follow the naming convention
5413
5414        * '{vm-type}_{network-role}_v6_floating_ip'
5415
5416     where
5417
5418        * '{vm-type}' is the {vm-type} associated with the OS::Nova::Server
5419        * '{network-role}' is the {network-role} of the external network
5420
5421     And the parameter **MUST** be declared as type 'string'.
5422
5423 .. req::
5424     :id: R-83418
5425     :target: VNF
5426     :keyword: MUST NOT
5427     :test: no test found
5428     :test_case: no test found
5429     :test_file: no test found
5430
5431     The VNF's Heat Orchestration Template's Resource
5432     'OS::Neutron::Port' property 'allowed_address_pairs'
5433     map property 'ip_address' parameter
5434     '{vm-type}_{network-role}_floating_v6_ip'
5435     **MUST NOT** be enumerated in the
5436     VNF's Heat Orchestration Template's Environment File.
5437
5438 *Example Parameter Definition*
5439
5440 .. code-block:: yaml
5441
5442   parameters:
5443
5444     {vm-type}_{network-role}_floating_v6_ip:
5445       type: string
5446       description: VIP for {vm-type} VMs on the {network-role} network
5447
5448 Note that these parameters are **not** intended to represent an OpenStack
5449 "Floating IP", for which OpenStack manages a pool of public IP
5450 addresses that are mapped to specific VM ports. In that case, the
5451 individual VMs are not even aware of the public IPs, and all assignment
5452 of public IPs to VMs is via OpenStack commands. ONAP does not support
5453 Neutron-style Floating IPs.  That is, ONAP does not support the
5454 resources 'OS::Neutron::FloatingIP'
5455 and 'OS::Neutron::FloatingIPAssociation'.
5456
5457
5458 .. req::
5459     :id: R-05257
5460     :target: VNF
5461     :keyword: MUST NOT
5462     :test: no test found
5463     :test_case: no test found
5464     :test_file: no test found
5465
5466     A VNF's Heat Orchestration Template's **MUST NOT**
5467     contain the Resource 'OS::Neutron::FloatingIP'.
5468
5469 .. req::
5470     :id: R-76449
5471     :target: VNF
5472     :keyword: MUST NOT
5473     :test: no test found
5474     :test_case: no test found
5475     :test_file: no test found
5476
5477     A VNF's Heat Orchestration Template's **MUST NOT**
5478     contain the Resource 'OS::Neutron::FloatingIPAssociation'.
5479
5480 The Floating IP functions as a NAT.  They are allocated within
5481 Openstack, and always "terminate" within the Openstack infrastructure.
5482 When Openstack receives packets on a Floating IP, the packets will
5483 be forwarded to the
5484 Port that has been mapped to the Floating IP, using the private address of the
5485 port.  The VM never sees or knows about the Openstack Floating IP.
5486 The process to use is:
5487
5488   - User allocates a floating IP from the Openstack pool.
5489   - User 'attaches' that floating IP to one of the VM ports.
5490
5491 If there is a high-availability VNF that wants to "float" the IP to a
5492 different VM, it requires a Neutron command to request Openstack to 'attach'
5493 the floating IP to a different VM port.
5494 The pool of such addresses is managed by Openstack infrastructure.
5495 Users cannot create new ones, they can only choose from those in the pool.
5496 The pool is typically global (i.e. any user/tenant can grab them).
5497
5498 Allowed address pairs are for more typical Linux-level "virtual IPs".
5499 They are additional IP addresses that are advertised by some port on the VM,
5500 in addition to the primary private IP address.  Typically in a
5501 high-availability VNF, an additional IP is assigned and will float between
5502 VMs (e.g., via some health-check app that will plumb the IP on one or other
5503 VM).  In order for this to work, the actual packets must be addressed to that
5504 IP address (and the allowed_ip_address list will let it pass through
5505 to the VM).  This generally requires provider network access
5506 (i.e. direct access to a data center network for the VMs), such that these
5507 IPs can pass through all of the virtual routers.
5508 Contrail also provides the enhanced networking that allows routing of such
5509 additional IPs.
5510
5511 Floating IPs are not used in ONAP due to the NAT-ting nature of the IPs,
5512 the inability to reserve such IPs for specific use, the need to manage them
5513 via Openstack commands (i.e. a HA VNF would require direct access to
5514 Openstack to 'float' such an IP from one VM to another).
5515
5516 *Example:*
5517
5518 In this example, the {network-role} has been defined as oam to represent
5519 an oam network and the {vm-type} has been defined as db for database.
5520
5521 .. code-block:: yaml
5522
5523   parameters:
5524     oam_net_id:
5525       type: string
5526       description: Neutron UUID for the oam network
5527     db_oam_ips:
5528       type: comma_delimited_list
5529       description: Fixed IPs for db VMs on the oam network
5530     db_oam_floating_ip:
5531       type: string
5532       description: VIP IP for db VMs on the oam network
5533   resources:
5534     db_0_oam_port_0:
5535       type: OS::Neutron::Port
5536       properties:
5537         network: { get_param: oam_net_id }
5538         fixed_ips: [ { "ip_address": {get_param: [db_oam_ips,0] }}]
5539         allowed_address_pairs: [ { "ip_address": {get_param:
5540         db_oam_floating_ip}}]
5541     db_1_oam_port_0:
5542       type: OS::Neutron::Port
5543         properties:
5544           network: { get_param: oam_net_id }
5545           fixed_ips: [ { "ip_address": {get_param: [db_oam_ips,1] }}]
5546           allowed_address_pairs: [ { "ip_address": {get_param:
5547           db_oam_floating_ip}}]
5548
5549
5550 VIP Assignment, External Networks, Additional Options
5551 _____________________________________________________
5552
5553 The parameter {'vm-type}_{network-role}_floating_ip' allows for only one
5554 allowed address pair IPv4 address per '{vm-type}' and '{network-role}'
5555 combination.
5556
5557 The parameter '{vm-type}_{network-role}_floating_v6_ip' allows for only one
5558 allowed address pair IPv6 address per '{vm-type}' and '{network-role}'
5559 combination.
5560
5561 If there is a need for multiple allowed address pair IPs for a given
5562 {vm-type} and {network-role} combination within a VNF, there are two
5563 options.
5564
5565 **Option One**
5566
5567 If there is a need for multiple allowed address pair IPs for a given
5568 '{vm-type}' and '{network-role}' combination within a VNF, then the
5569 parameter names defined for the Property 'fixed_ips' Map Property
5570 'ip_address' should be used or the Property 'allowed_address_pairs'
5571 Map Property 'ip_address'. The
5572 parameter names are provided in the table below.
5573
5574 .. csv-table:: **Table 5 OS::Neutron::Port Property allowed_address_pairs map property ip_address Parameter Naming Convention**
5575    :header: IP Address,Parameter Type,Parameter Name
5576    :align: center
5577    :widths: auto
5578
5579    IPv4, string, {vm-type}_{network-role}_ip_{index}
5580    IPv4, comma_delimited_list, {vm-type}_{network-role}_ips
5581    IPv6, string, {vm-type}_{network-role}_v6_ip_{index}
5582    IPv6, comma_delimited_list, {vm-type}_{network-role}_v6_ips
5583
5584 The examples below illustrate this concept.
5585
5586 *Example: A VNF has four load balancers. Each pair has a unique VIP.*
5587
5588 In this example, there are two administrative VM pairs. Each pair has
5589 one VIP. The {network-role} has been defined as oam to represent an oam
5590 network and the {vm-type} has been defined as admin for an
5591 administrative VM.
5592
5593 Pair 1: Resources admin_0_port_0 and admin_1_port_0 share a unique VIP,
5594 [admin_oam_ips,2]
5595
5596 Pair 2: Resources admin_2_port_0 and admin_3_port_0 share a unique VIP,
5597 [admin_oam_ips,5]
5598
5599 .. code-block:: yaml
5600
5601   parameters:
5602     oam_net_id:
5603       type: string
5604       description: Neutron UUID for the oam network
5605     admin_oam_ips:
5606       type: comma_delimited_list
5607       description: Fixed IP assignments for admin VMs on the oam network
5608
5609   resources:
5610     admin_0_oam_port_0:
5611       type: OS::Neutron::Port
5612       properties:
5613         network: { get_param: oam_net_id }
5614         fixed_ips: [ { "ip_address": {get_param: [admin_oam_ips,0] }}]
5615         allowed_address_pairs: [{ "ip_address": {get_param: [admin_oam_ips,2]
5616         }}]
5617     admin_1_oam_port_0:
5618       type: OS::Neutron::Port
5619       properties:
5620         network: { get_param: oam_net_id }
5621         fixed_ips: [ { "ip_address": {get_param: [admin_oam_ips,1] }}]
5622         allowed_address_pairs: [{ "ip_address": {get_param: [admin_oam_ips,2]
5623       }}]
5624     admin_2_oam_port_0:
5625       type: OS::Neutron::Port
5626       properties:
5627         network: { get_param: oam_net_id }
5628         fixed_ips: [ { "ip_address": {get_param: [admin_oam_ips,3] }}]
5629         allowed_address_pairs: [{ "ip_address": {get_param: [admin_oam_ips,5]
5630         }}]
5631     admin_3_oam_port_0:
5632       type: OS::Neutron::Port
5633       properties:
5634         network: { get_param: oam_net_id }
5635         fixed_ips: [ { "ip_address": {get_param: [admin_oam_ips,4] }}]
5636         allowed_address_pairs: [{ "ip_address": {get_param: [admin_oam_ips,5]
5637         }}]
5638
5639 *Example: A VNF has two load balancers. The pair of load balancers share
5640 two VIPs.*
5641
5642 In this example, there is one load balancer pairs. The pair has two
5643 VIPs. The {network-role} has been defined as oam to represent an oam
5644 network and the {vm-type} has been defined as lb for a load balancer VM.
5645
5646 .. code-block:: yaml
5647
5648   resources:
5649     lb_0_oam_port_0:
5650       type: OS::Neutron::Port
5651       properties:
5652         network: { get_param: oam_net_id }
5653         fixed_ips: [ { "ip_address": {get_param: [lb_oam_ips,0] }}]
5654         allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2] },
5655         {get_param: [lb_oam_ips,3] }}]
5656     lb_1_oam_port_0:
5657       type: OS::Neutron::Port
5658       properties:
5659         network: { get_param: oam_net_id }
5660         fixed_ips: [ { "ip_address": {get_param: [lb_oam_ips,1] }}]
5661         allowed_address_pairs: [{ "ip_address": {get_param: [lb_oam_ips,2] },
5662         {get_param: [lb_oam_ips,3] }}]
5663
5664 As a general rule, provide the fixed IPs for the VMs indexed first in
5665 the CDL and then the VIPs as shown in the examples above.
5666
5667 **Option Two**
5668
5669 If there is a need for multiple allowed address pair IPs for a given
5670 '{vm-type}' and '{network-role}' combination within a VNF, then the
5671 parameter names defined for the table below can be used.
5672
5673 **Resource OS::Neutron::Port**
5674
5675 Table 6: Multiple allowed_address_pairs Option 2A
5676
5677 .. csv-table:: **Table 6 OS::Neutron::Port Property allowed_address_pairs map property ip_address Parameter Naming Convention**
5678    :header: IP Address,Parameter Type,Parameter Name
5679    :align: center
5680    :widths: auto
5681
5682    IPv4, string, {vm-type}_{network-role}_vip_{index}
5683    IPv4, comma_delimited_list, {vm-type}_{network-role}_vips
5684    IPv6, string, {vm-type}_{network-role}_v6_vip_{index}
5685    IPv6, comma_delimited_list, {vm-type}_{network-role}_v6_vips
5686
5687
5688 If there is a need for multiple allowed address pair IPs for a given
5689 '{vm-type}' and '{network-role}' combination within a VNF and the need to
5690 differentiate the VIPs for different traffic types (e.g., 911 VIP,
5691 fail-over VIP), then the parameter names defined for the table below can
5692 be used.
5693
5694 **Resource OS::Neutron::Port**
5695
5696 Table 7: Multiple allowed_address_pairs Option 2B
5697
5698 .. csv-table:: **Table 7 OS::Neutron::Port Property allowed_address_pairs map property ip_address Parameter Naming Convention**
5699    :header: IP Address,Parameter Type,Parameter Name
5700    :align: center
5701    :widths: auto
5702
5703    IPv4, string, {vm-type}_{network-role}_{vip_type}_vip
5704    IPv4, comma_delimited_list, {vm-type}_{network-role}_{vip_type}_vips
5705    IPv6, string, {vm-type}_{network-role}_{vip_type}_v6_vip
5706    IPv6, comma_delimited_list, {vm-type}_{network-role}_{vip_type}_v6_vips
5707
5708 Internal Networks
5709 _________________
5710
5711 ONAP defines an internal network in relation to
5712 the VNF and not with regard to the Network Cloud site. Internal
5713 networks may also be referred to as "intra-VNF" networks or "private"
5714 networks. An internal network only connects VMs in a single VNF. It
5715 must not connect to other VNFs or an external (to the cloud) gateway or an
5716 external (to the cloud) router.
5717
5718 ONAP internal networks should be created in the base module.
5719
5720 As previously mentioned,
5721 ports that connect to an internal network are assigned IP addresses
5722 via one of two methods
5723
5724  * Method 1: Cloud assigned by OpenStack's DHCP Service
5725  * Method 2: Statically assigned.  That is, predetermined by the VNF designer
5726    and are specified in the VNF's Heat Orchestration Template's
5727    Environment File
5728
5729 If Cloud assigned IP addressing is being used, output statements
5730 are created in the base module.
5731
5732 If static assigned IP addressing is being used, the  IP addresses
5733 are defined in the environment file.
5734
5735
5736   * {vm-type}_int_{network-role}_floating_ip
5737   * {vm-type}_int_{network-role}_floating_v6_ip
5738
5739   * {vm-type}_int_{network-role}_vip_{index}
5740   * {vm-type}_int_{network-role}_vips
5741   * {vm-type}_int_{network-role}_v6_vip_{index}
5742   * {vm-type}_int_{network-role}_v6_vips
5743
5744
5745   * {vm-type}_int_{network-role}_{vip_type}_vip
5746   * {vm-type}_int_{network-role}_{vip_type}_vips
5747   * {vm-type}_int_{network-role}_{vip_type}_v6_vip
5748   * {vm-type}_int_{network-role}_{vip_type}_v6_vips
5749
5750
5751
5752 *Example Parameter Definition*
5753
5754 .. code-block:: yaml
5755
5756   parameters:
5757     {vm-type}_int_{network-role}_floating_ip:
5758       type: string
5759       description: VIP for {vm-type} VMs on the int_{network-role} network
5760
5761     {vm-type}_int_{network-role}_floating_v6_ip:
5762       type: string
5763       description: VIP for {vm-type} VMs on the int_{network-role} network
5764
5765
5766
5767
5768 allowed_address_pair IP Addresses Required in more than one module
5769 __________________________________________________________________
5770
5771 If the IP address {vm-type}_{network-role}_floating_ip and/or
5772 {vm-type}_{network-role}_floating_v6_ip must be used in more than module in the
5773 VNF, the parameter values must be defined as output values in the base
5774 module with output names: {vm-type}_{network-role}_shared_vip or
5775 {vm-type}_{network-role}_v6_shared_vip
5776
5777 .. code-block:: yaml
5778
5779   outputs:
5780     {vm-type}_{network-role}_shared_vip:
5781       description:
5782       value: { get_param: {vm-type}_{network-role}_floating_ip }
5783
5784     {vm-type}_{network-role}_v6_shared_vip:
5785       description:
5786       value: { get_param: {vm-type}_{network-role}_v6_floating_ip }
5787
5788 The output parameters must be defined as input parameter in the
5789 incremental modules that require the IP addresses. When defining the
5790 allowed_address_pairs: in the OS::Neutron::Port, it should be as
5791 follows:
5792
5793 .. code-block:: yaml
5794
5795   allowed_address_pairs: [ { "ip_address": {get_param:
5796   {vm-type}_{network-role}_shared_vip }}, { "ip_address": {get_param:
5797   {vm-type}_{network-role}_v6_shared_vip }}]
5798
5799 Reserve Port Concept
5800 ____________________
5801
5802 A "Reserve Port" is an OS::Neutron::Port that fixed_ips, ip_address
5803 property is assigned one or more IP addresses that are used as Virtual
5804 IP (VIP) Addresses (i.e., allowed_address_pairs) on other ports.
5805
5806 A "Reserve Port" is never attached to a Virtual Machine
5807 (OS::Nova::Server). The reserve port ensures that the intended
5808 allowed_address_pair IP address is not inadvertently assigned as a
5809 fixed_ips to a OS::Neutron::Port that is attached OS::Nova::Server and
5810 thus causing routing issues.
5811
5812 A VNF may have one or more "Reserve Ports". A reserve port maybe created
5813 in the base module or an incremental module. If created in the base
5814 module, parameters may be defined in the outputs: section of the base
5815 template so the IP Address assigned to the reserve port maybe assigned
5816 to the allowed_address_pair property of an OS::Neutron::Port in one or
5817 more incremental modules.
5818
5819 The parameter name of the IP address used in the "Reserve Port" depends
5820 on the allowed_address_pair "option" utilized by the VNF.
5821
5822 When creating a Reserve Port, if only one allowed_address_pair is configured
5823 on a port, then the parameter name depends upon the IP addresses type
5824 (IPv4 or IPv6) and network type (internal or external).
5825 The valid parameter names are:
5826
5827   * {vm-type}_{network-role}_floating_ip
5828   * {vm-type}_{network-role}_floating_v6_ip
5829   * {vm-type}_int_{network-role}_floating_ip
5830   * {vm-type}_int_{network-role}_floating_v6_ip
5831
5832 When creating a Reserve Port, if more than one (e.g., multiple)
5833 allowed_address_pair is configured on a port, then the parameter name depends
5834 upon the IP addresses type (IPv4 or IPv6) and network type
5835 (internal or external) and the option being used.  The valid parameter
5836 names are:
5837
5838   * {vm-type}_{network-role}_ip_{index}
5839   * {vm-type}_{network-role}_ips
5840   * {vm-type}_{network-role}_v6_ip_{index}
5841   * {vm-type}_{network-role}_v6_ips
5842   * {vm-type}_{network-role}_vip_{index}
5843   * {vm-type}_{network-role}_vips
5844   * {vm-type}_{network-role}_v6_vip_{index}
5845   * {vm-type}_{network-role}_v6_vips
5846   * {vm-type}_{network-role}_{vip-type}_vip
5847   * {vm-type}_{network-role}_v6_{vip-type}_vip
5848   * {vm-type}_{network-role}_{vip-type}_vips
5849   * {vm-type}_{network-role}_v6_{vip-type}_vips
5850
5851 *Example IPv4 Reserve Port Definition: one allowed_address_pair
5852 configured on a port*
5853
5854 .. code-block:: yaml
5855
5856   Reserve_Port_{vm-type}_{network-role}_floating_ip_{index}:
5857     type: OS::Neutron::Port
5858     properties:
5859       network: { get_param: {network-role}_net_id }
5860       fixed_ips:
5861         - ip_address : { get_param: {vm-type}_{network-role}_floating_ip }
5862
5863 *Example IPv6 Reserve Port Definition: one allowed_address_pair
5864 configured on a port*
5865
5866 .. code-block:: yaml
5867
5868   Reserve_Port_{vm-type}_{network-role}_floating_v6_ip_{index}:
5869     type: OS::Neutron::Port
5870     properties:
5871       network: { get_param: {network-role}_net_id }
5872       fixed_ips:
5873         - ip_address : { get_param: {vm-type}_{network-role}_floating_v6_ip }
5874
5875
5876 Resource Property "name"
5877 ~~~~~~~~~~~~~~~~~~~~~~~~
5878
5879 The parameter naming convention of the property name for the resource
5880 OS::Nova::Server has been defined in
5881 `Resource:  OS::Nova::Server – Metadata Parameters`_.
5882
5883 This section provides the requirements how the property name for non
5884 OS::Nova::Server resources must be defined when the property is used.
5885 Not all resources require the property name (e.g., it is optional) and
5886 some resources do not support the property.
5887
5888
5889 .. req::
5890     :id: R-85734
5891     :target: VNF
5892     :keyword: MUST
5893
5894     If a VNF's Heat Orchestration Template contains the property 'name'
5895     for a non 'OS::Nova::Server' resource, the intrinsic function
5896     'str_replace' **MUST** be used in conjunction with the ONAP
5897     supplied metadata parameter 'vnf_name' to generate a unique value.
5898
5899 This prevents the enumeration of a
5900 unique value for the property name in a per instance environment file.
5901
5902
5903 .. req::
5904     :id: R-99812
5905     :target: VNF
5906     :keyword: MUST NOT
5907     :test: no test found
5908     :test_case: no test found
5909     :test_file: no test found
5910
5911     A value for VNF's Heat Orchestration Template's property 'name'
5912     for a non 'OS::Nova::Server' resource **MUST NOT** be declared
5913     in the VNF's Heat Orchestration Template's Environment File.
5914
5915 In most cases the use of the metadata value 'vnf_name' is required to create a
5916 unique property name.  If this will not provide a unique value,
5917 additional options include:
5918
5919  - Using the Heat Orchestration Template pseudo parameter
5920    'OS::stack_name' in the str_replace construct
5921  - Resources created in a nested heat file invoked by an
5922    'OS::Heat::ResourceGroup' can use the 'index' to construct a unique name
5923
5924
5925 .. req::
5926     :id: R-32408
5927     :target: VNF
5928     :keyword: MUST
5929     :test: no test found
5930     :test_case: no test found
5931     :test_file: no test found
5932
5933     If a VNF's Heat Orchestration Template property 'name'
5934     for a non 'OS::Nova::Server' resource uses the intrinsic function
5935     'str_replace' in conjunction with the ONAP
5936     supplied metadata parameter 'vnf_name' and does not create
5937     a unique value, additional data **MUST** be used in the
5938     'str_replace' to create a unique value, such as 'OS::stack_name'
5939     and/or the 'OS::Heat::ResourceGroup' 'index'.
5940
5941 *Example: Property 'name' for resource 'OS::Neutron::SecurityGroup'*
5942
5943 .. code-block:: yaml
5944
5945   resources:
5946     DNS_SECURITY_GROUP:
5947       type: OS::Neutron::SecurityGroup
5948       properties:
5949         description: vDNS security group
5950         name:
5951           str_replace:
5952             template: VNF_NAME_sec_grp_DNS
5953             params:
5954               VNF_NAME: {get_param: vnf_name}
5955         rules: [. . . . .]
5956
5957 *Example: Property 'name' for resource 'OS::Cinder::Volume'*
5958
5959 .. code-block:: yaml
5960
5961   resources:
5962     dns_volume_0:
5963       type: OS::Cinder::Volume
5964       properties:
5965         description: Cinder Volume
5966         name:
5967           str_replace:
5968             template: VNF_NAME_STACK_NAME_dns_volume
5969             params:
5970               VNF_NAME: {get_param: vnf_name}
5971               STACK_NAME: { get_param: 'OS::stack_name' }
5972   . . . .
5973
5974 *Example: Property 'name' for resource 'OS::Cinder::Volume' invoked by a
5975 'OS::Heat::ResourceGroup'*
5976
5977 .. code-block:: yaml
5978
5979   resources:
5980     dns_volume_0:
5981       type: OS::Cinder::Volume
5982       properties:
5983         description: Cinder Volume
5984         name:
5985           str_replace:
5986               template: VNF_NAME_STACK_NAME_dns_volume_INDEX
5987               params:
5988                   VNF_NAME: { get_param: vnf_name }
5989                   STACK_NAME: { get_param: 'OS::stack_name' }
5990                   INDEX: { get_param: index }
5991   . . . .
5992
5993 Contrail Issue with Values for the Property Name
5994 ++++++++++++++++++++++++++++++++++++++++++++++++
5995
5996
5997 .. req::
5998     :id: R-84517
5999     :target: VNF
6000     :keyword: SHOULD
6001     :test: no test found
6002     :test_case: no test found
6003     :test_file: no test found
6004
6005     The Contrail GUI has a limitation displaying special characters.
6006     The issue is documented in
6007     https://bugs.launchpad.net/juniperopenstack/+bug/1590710.
6008     It is recommended that special **SHOULD** characters be avoided.
6009     However, if special characters must be used, note that for
6010     the following resources:
6011
6012        * Virtual Machine
6013        * Virtual Network
6014        * Port
6015        * Security Group
6016        * Policies
6017        * IPAM Creation
6018
6019     the only special characters supported
6020     are - \" ! $\ \ ' ( ) = ~ ^ | @ ` { } [ ] > , . _"
6021
6022 ONAP Output Parameter Names
6023 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
6024
6025 ONAP defines three types of Output Parameters as detailed in
6026 `Output Parameters`_.
6027
6028 ONAP Base Module Output Parameters:
6029 +++++++++++++++++++++++++++++++++++
6030
6031 ONAP Base Module Output Parameters do not have an explicit naming
6032 convention.
6033
6034
6035 .. req::
6036     :id: R-97726
6037     :target: VNF
6038     :keyword: MUST
6039     :test: no test found
6040     :test_case: no test found
6041     :test_file: no test found
6042
6043     A VNF's Heat Orchestration Template's Base Module Output
6044     Parameter names **MUST** contain {vm-type} and/or {network-role}
6045     when appropriate.
6046
6047 ONAP Volume Template Output Parameters:
6048 +++++++++++++++++++++++++++++++++++++++
6049
6050
6051 .. req::
6052     :id: R-88524
6053     :target: VNF
6054     :keyword: MUST
6055     :test: no test found
6056     :test_case: no test found
6057     :test_file: no test found
6058
6059     A VNF's Heat Orchestration Template's Volume Template
6060     Output Parameter names **MUST** contain {vm-type} when appropriate.
6061
6062 Predefined Output Parameters
6063 ++++++++++++++++++++++++++++
6064
6065 ONAP currently defines one predefined output parameter the OAM
6066 Management IP Addresses.
6067
6068 OAM Management IP Addresses
6069 ___________________________
6070
6071 A VNF may have a management interface for application controllers to
6072 interact with and configure the VNF. Typically, this will be via a
6073 specific VM that performs a VNF administration function. The IP address
6074 of this interface must be captured and inventoried by ONAP. The IP
6075 address might be a VIP if the VNF contains an HA pair of management VMs,
6076 or may be a single IP address assigned to one VM.
6077
6078
6079 .. req::
6080     :id: R-47874
6081     :target: VNF
6082     :keyword: MAY
6083     :test: no test found
6084     :test_case: no test found
6085     :test_file: no test found
6086
6087     A VNF **MAY** have
6088
6089      * Only an IPv4 OAM Management IP Address
6090      * Only an IPv6 OAM Management IP Address
6091      * Both a IPv4 and IPv6 OAM Management IP Addresses
6092
6093 .. req::
6094     :id: R-18683
6095     :target: VNF
6096     :keyword: MUST
6097     :test: no test found
6098     :test_case: no test found
6099     :test_file: no test found
6100
6101     If a VNF has one IPv4 OAM Management IP Address and the
6102     IP Address needs to be inventoried in ONAP's A&AI
6103     database, an output parameter **MUST** be declared in only one of the
6104     VNF's Heat Orchestration Templates and the parameter **MUST** be named
6105     'oam_management_v4_address'.
6106
6107 .. req::
6108     :id: R-94669
6109     :target: VNF
6110     :keyword: MUST
6111     :test: no test found
6112     :test_case: no test found
6113     :test_file: no test found
6114
6115     If a VNF has one IPv6 OAM Management IP Address and the
6116     IP Address needs to be inventoried in ONAP's AAI
6117     database, an output parameter **MUST** be declared in only one of the
6118     VNF's Heat Orchestration Templates and the parameter **MUST** be named
6119     'oam_management_v6_address'.
6120
6121 The OAM Management IP Address maybe assigned either via
6122   *  ONAP SDN-C
6123   *  DHCP
6124
6125
6126 .. req::
6127     :id: R-56287
6128     :target: VNF
6129     :keyword: MUST
6130     :test: no test found
6131     :test_case: no test found
6132     :test_file: no test found
6133
6134     If the VNF's OAM Management IP Address is assigned by ONAP SDN-C and
6135     assigned in the VNF's Heat Orchestration Template's via a heat resource
6136     'OS::Neutron::Port' property 'fixed_ips' map property
6137     'ip_adress' parameter (e.g., '{vm-type}_{network-role}_ip_{index}',
6138     '{vm-type}_{network-role}_v6_ip_{index}')
6139     and the OAM IP Address is required to be inventoried in ONAP AAI,
6140     then the parameter **MUST** be echoed in an output statement.
6141
6142 .. code-block:: yaml
6143
6144    outputs:
6145        oam_management_v4_address:
6146          value: {get_param: {vm-type}_{network-role}_ip_{index} }
6147        oam_management_v6_address:
6148          value: {get_param: {vm-type}_{network-role}_v6_ip_{index} }
6149
6150 *Example: ONAP SDN-C Assigned IP Address echoed as
6151 oam_management_v4_address*
6152
6153 .. code-block:: yaml
6154
6155   parameters:
6156     admin_oam_ip_0:
6157       type: string
6158       description: Fixed IPv4 assignment for admin VM 0 on the OAM network
6159   . . .
6160   resources:
6161     admin_0_oam_port_0:
6162       type: OS::Neutron::Port
6163       properties:
6164         name:
6165           str_replace:
6166             template: VNF_NAME_admin_oam_port_0
6167             params:
6168               VNF_NAME: {get_param: vnf_name}
6169         network: { get_param: oam_net_id }
6170         fixed_ips: [{ "ip_address": { get_param: admin_oam_ip_0 }}]
6171         security_groups: [{ get_param: security_group }]
6172     admin_server_0:
6173       type: OS::Nova::Server
6174       properties:
6175         name: { get_param: admin_names }
6176         image: { get_param: admin_image_name }
6177         flavor: { get_param: admin_flavor_name }
6178         availability_zone: { get_param: availability_zone_0 }
6179       networks:
6180         - port: { get_resource: admin_0_oam_net_port_0 }
6181       metadata:
6182         vnf_id: { get_param: vnf_id }
6183         vf_module_id: { get_param: vf_module_id }
6184         vnf_name: {get_param: vnf_name }
6185   outputs:
6186       oam_management_v4_address:
6187         value: {get_param: admin_oam_ip_0 }
6188
6189
6190 .. req::
6191     :id: R-48987
6192     :target: VNF
6193     :keyword: MUST
6194     :test: no test found
6195     :test_case: no test found
6196     :test_file: no test found
6197
6198     If the VNF's OAM Management IP Address is Cloud assigned and
6199     and the OAM IP Address is required to be inventoried in ONAP AAI,
6200     then the parameter **MUST** be obtained by the resource 'OS::Neutron::Port'
6201     attribute 'ip_address'.
6202
6203 .. code-block:: yaml
6204
6205    outputs:
6206        oam_management_v4_address:
6207          value: {get_attr: [ {OS::Neutron Port Resource ID}, fixed_ips, 0, ip_address] }
6208
6209 *Example: Cloud Assigned IP Address output as oam_management_v4_address*
6210
6211 .. code-block:: yaml
6212
6213   parameters:
6214   . . .
6215   resources:
6216     admin_0_oam_port_0:
6217       type: OS::Neutron::Port
6218       properties:
6219         name:
6220           str_replace:
6221             template: VNF_NAME_admin_oam_0_port
6222             params:
6223               VNF_NAME: {get_param: vnf_name}
6224         network: { get_param: oam_net_id }
6225         security_groups: [{ get_param: security_group }]
6226     admin_server_0:
6227       type: OS::Nova::Server
6228       properties:
6229         name: { get_param: admin_name_0 }
6230         image: { get_param: admin_image_name }
6231         flavor: { get_param: admin_flavor_name }
6232         availability_zone: { get_param: availability_zone_0 }
6233         networks:
6234           - port: { get_resource: admin_0_oam_port_0 }
6235         metadata:
6236           vnf_id: { get_param: vnf_id }
6237           vf_module_id: { get_param: vf_module_id }
6238           vnf_name: {get_param: vnf_name }
6239   outputs:
6240     oam_management_v4_address:
6241       value: {get_attr: [admin_0_oam_port_0, fixed_ips, 0, ip_address] }
6242
6243 Contrail Resource Parameters
6244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6245
6246 ONAP requires the parameter names of certain Contrail Resources to
6247 follow specific naming conventions. This section provides these
6248 requirements.
6249
6250 Contrail Network Parameters
6251 +++++++++++++++++++++++++++
6252
6253 Contrail based resources may require references to a Contrail network
6254 using the network FQDN.
6255
6256 External Networks
6257 _________________
6258
6259
6260 .. req::
6261     :id: R-02164
6262     :target: VNF
6263     :keyword: MUST
6264     :test: no test found
6265     :test_case: no test found
6266     :test_file: no test found
6267
6268     When a VNF's Heat Orchestration Template's Contrail resource
6269     has a property that
6270     references an external network that requires the network's
6271     Fully Qualified Domain Name (FQDN), the property parameter
6272
6273        * **MUST** follow the format '{network-role}_net_fqdn'
6274        * **MUST** be declared as type 'string'
6275        * **MUST NOT** be enumerated in the NF's Heat Orchestration Template's
6276          Environment File
6277
6278 .. req::
6279     :id: R-73228
6280     :target: VNF
6281     :keyword: MUST
6282     :test: no test found
6283     :test_case: no test found
6284     :test_file: no test found
6285
6286     A VNF's Heat Orchestration Template's parameter
6287     '{network-role}_net_fqdn'
6288     **MUST** be declared as type 'string'.
6289
6290 .. req::
6291     :id: R-92193
6292     :target: VNF
6293     :keyword: MUST NOT
6294     :test: no test found
6295     :test_case: no test found
6296     :test_file: no test found
6297
6298     A VNF's Heat Orchestration Template's parameter
6299     '{network-role}_net_fqdn'
6300     **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's
6301     Environment File.
6302
6303 *Example: Parameter declaration*
6304
6305 .. code-block:: yaml
6306
6307   parameters:
6308     {network-role}_net_fqdn:
6309       type: string
6310       description: Contrail FQDN for the {network-role} network
6311
6312 *Example: Contrail Resource OS::ContrailV2::VirtualMachineInterface
6313 Reference to a Network FQDN.*
6314
6315 In this example, the {network-role} has been defined as oam to represent
6316 an oam network and the {vm-type} has been defined as fw for firewall.
6317 The Contrail resource OS::ContrailV2::VirtualMachineInterface property
6318 virtual_network_refs references a contrail network FQDN.
6319
6320 .. code-block:: yaml
6321
6322   fw_0_oam_vmi_0:
6323     type: OS::ContrailV2::VirtualMachineInterface
6324     properties:
6325       name:
6326         str_replace:
6327           template: VM_NAME_virtual_machine_interface_1
6328           params:
6329             VM_NAME: { get_param: fw_name_0 }
6330       virtual_machine_interface_properties:
6331         virtual_machine_interface_properties_service_interface_type: {
6332         get_param: oam_protected_interface_type }
6333       virtual_network_refs:
6334         - get_param: oam_net_fqdn
6335       security_group_refs:
6336         - get_param: fw_sec_grp_id
6337
6338
6339 Interface Route Table Prefixes for Contrail InterfaceRoute Table
6340 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6341
6342
6343 .. req::
6344     :id: R-28222
6345     :target: VNF
6346     :keyword: MUST
6347     :test: no test found
6348     :test_case: no test found
6349     :test_file: no test found
6350
6351     If a VNF's Heat Orchestration Template
6352     'OS::ContrailV2::InterfaceRouteTable' resource
6353     'interface_route_table_routes' property
6354     'interface_route_table_routes_route' map property parameter name
6355     **MUST** follow the format
6356
6357        * {vm-type}_{network-role}_route_prefixes
6358
6359 .. req::
6360     :id: R-19756
6361     :target: VNF
6362     :keyword: MUST
6363     :test: no test found
6364     :test_case: no test found
6365     :test_file: no test found
6366
6367     If a VNF's Heat Orchestration Template
6368     'OS::ContrailV2::InterfaceRouteTable' resource
6369     'interface_route_table_routes' property
6370     'interface_route_table_routes_route' map property parameter
6371     '{vm-type}_{network-role}_route_prefixes'
6372     **MUST** be defined as type 'json'.
6373
6374 .. req::
6375     :id: R-76682
6376     :target: VNF
6377     :keyword: MUST NOT
6378     :test: no test found
6379     :test_case: no test found
6380     :test_file: no test found
6381
6382     If a VNF's Heat Orchestration Template
6383     'OS::ContrailV2::InterfaceRouteTable' resource
6384     'interface_route_table_routes' property
6385     'interface_route_table_routes_route' map property parameter
6386     '{vm-type}_{network-role}_route_prefixes'
6387     **MUST NOT** be enumerated in the VNF's Heat Orchestration Template's
6388     Environment File.
6389
6390 The parameter '{vm-type}_{network-role}_route_prefixes'
6391 supports IP addresses in the format:
6392
6393 1. Host IP Address (e.g., 10.10.10.10)
6394
6395 2. CIDR Notation format (e.g., 10.0.0.0/28)
6396
6397
6398 *Example Parameter Definition*
6399
6400 .. code-block:: yaml
6401
6402   parameters:
6403     {vm-type}_{network-role}_route_prefixes:
6404       type: json
6405       description: JSON list of Contrail Interface Route Table route prefixes
6406
6407 *Example:*
6408
6409 .. code-block:: yaml
6410
6411   parameters:
6412     vnf_name:
6413       type: string
6414       description: Unique name for this VF instance
6415     fw_oam_route_prefixes:
6416       type: json
6417       description: prefix for the ServiceInstance InterfaceRouteTable
6418     int_fw_dns_trusted_interface_type:
6419       type: string
6420       description: service_interface_type for ServiceInstance
6421
6422   resources:
6423     <resource name>:
6424       type: OS::ContrailV2::InterfaceRouteTable
6425       depends_on: [resource name of OS::ContrailV2::ServiceInstance]
6426       properties:
6427         name:
6428           str_replace:
6429             template: VNF_NAME_interface_route_table
6430             params:
6431               VNF_NAME: { get_param: vnf_name }
6432         interface_route_table_routes:
6433           interface_route_table_routes_route: { get_param: fw_oam_route_prefixes }
6434         service_instance_refs:
6435           - get_resource: <resource name of OS::ContrailV2::ServiceInstance>
6436         service_instance_refs_data:
6437           - service_instance_refs_data_interface_type: { get_param: oam_interface_type }
6438
6439 Resource OS::ContrailV2::InstanceIp
6440 +++++++++++++++++++++++++++++++++++
6441
6442 The Contrail resource OS::ContrailV2::InstanceIp has two properties
6443 that parameters **MUST** follow an explicit naming convention.  The
6444 properties are 'instance_ip_address' and 'subnet_uuid'.
6445
6446 *Example OS::ContrailV2::InstanceIp Resource*
6447
6448 .. code-block:: yaml
6449
6450   <resource ID>:
6451     type: OS::ContrailV2::InstanceIp
6452     properties:
6453       name: { get_param: name }
6454       fq_name: { get_param: fq_name }
6455       display_name: { get_param: display_name }
6456       secondary_ip_tracking_ip:
6457         {
6458           secondary_ip_tracking_ip_ip_prefix: { get_param: secondary_ip_tracking_ip_ip_prefix },
6459           secondary_ip_tracking_ip_ip_prefix_len: { get_param: secondary_ip_tracking_ip_ip_prefix_len },
6460         }
6461       instance_ip_address: { get_param: instance_ip_address }
6462       instance_ip_mode: { get_param: instance_ip_mode }
6463       subnet_uuid: { get_param: subnet_uuid }
6464       instance_ip_family: { get_param: instance_ip_family }
6465       annotations:
6466         {
6467           annotations_key_value_pair:
6468             [{
6469               annotations_key_value_pair_key: { get_param: annotations_key_value_pair_key },
6470               annotations_key_value_pair_value: { get_param: annotations_key_value_pair_value },
6471             }],
6472         }
6473       instance_ip_local_ip: { get_param: instance_ip_local_ip }
6474       instance_ip_secondary: { get_param: instance_ip_secondary }
6475       physical_router_refs: [{ get_param: physical_router_refs }]
6476       virtual_machine_interface_refs: [{ get_param: virtual_machine_interface_refs }]
6477       virtual_network_refs: [{ get_param: virtual_network_refs }]
6478
6479 Resource OS::ContrailV2::InstanceIp Property instance_ip_address
6480 ________________________________________________________________
6481
6482 A VNF's Heat Orchestration Templates resource 'OS::ContrailV2::InstanceIp'
6483 property 'instance_ip_address' parameter
6484 **MUST** follow the same requirements
6485 that apply to the resource 'OS::Neutron' property 'fixed_ips' map
6486 property 'ip_address' parameter.
6487
6488 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
6489 instance_ip_address*
6490
6491 The property instance_ip_address uses the same parameter naming
6492 convention as the property fixed_ips and Map Property ip_address in
6493 OS::Neutron::Port. The resource is assigning an ONAP SDN-C Assigned IP
6494 Address. The {network-role} has been defined as oam_protected to
6495 represent an oam protected network and the {vm-type} has been defined as
6496 fw for firewall.
6497
6498 .. code-block:: yaml
6499
6500   fw_0_oam_protected_vmi_0_IP_0:
6501     type: OS::ContrailV2::InstanceIp
6502     depends_on:
6503       - fw_0_oam_protected_vmi_0
6504     properties:
6505       virtual_machine_interface_refs:
6506         - get_resource: fw_0_oam_protected_vmi_0
6507       virtual_network_refs:
6508         - get_param: oam_protected_net_fqdn
6509       instance_ip_address: { get_param: [fw_oam_protected_ips, get_param: index ] }
6510
6511 Resource OS::ContrailV2::InstanceIp Property subnet_uuid
6512 ________________________________________________________________
6513
6514 A VNF's Heat Orchestration Templates resource 'OS::ContrailV2::InstanceIp'
6515 property 'subnet_uuid' parameter
6516 **MUST** follow the same requirements
6517 that apply to the resource 'OS::Neutron' property 'fixed_ips' map
6518 property 'subnet'/'subnet_id' parameter.
6519
6520 *Example: Contrail Resource OS::ContrailV2::InstanceIp, Property
6521 subnet_uuid*
6522
6523 The property instance_ip_address uses the same parameter naming
6524 convention as the property fixed_ips and Map Property subnet_id in
6525 OS::Neutron::Port. The resource is assigning a Cloud Assigned IP
6526 Address. The {network-role} has been defined as "oam_protected" to
6527 represent an oam protected network and the {vm-type} has been defined as
6528 "fw" for firewall.
6529
6530 .. code-block:: yaml
6531
6532   fw_0_oam_protected_vmi_0_IP_0:
6533     type: OS::ContrailV2::InstanceIp
6534     depends_on:
6535     - fw_0_oam_protected_vmi_0
6536     properties:
6537       virtual_machine_interface_refs:
6538         - get_resource: fw_0_oam_protected_vmi_0
6539       virtual_network_refs:
6540         - get_param: oam_protected_net_fqdn
6541       subnet_uuid: { get_param: oam_protected_subnet_id }
6542
6543 OS::ContrailV2::VirtualMachineInterface Property virtual_machine_interface_allowed_address_pairs
6544 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6545
6546
6547 A VNF's Heat Orchestration Templates resource
6548 'OS::ContrailV2::VirtualMachineInterface' map property,
6549 virtual_machine_interface_allowed_address_pairs,
6550 virtual_machine_interface_allowed_address_pairs_allowed_address_pair,
6551 virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip,
6552 virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix
6553 parameter **MUST** follow the same requirements that apply to the
6554 resource 'OS::Neutron::Port' property
6555 'allowed_address_pairs', map property 'ip_address' parameter.
6556
6557 *Example OS::ContrailV2::VirtualMachineInterface*
6558
6559 .. code-block:: yaml
6560
6561   <resource ID>:
6562     type: OS::ContrailV2::VirtualMachineInterface
6563     properties:
6564       name: { get_param: name }
6565       fq_name: { get_param: fq_name }
6566       ecmp_hashing_include_fields:
6567         {
6568           ecmp_hashing_include_fields_hashing_configured: { get_param: ecmp_hashing_include_fields_hashing_configured },
6569           ecmp_hashing_include_fields_source_ip: { get_param: ecmp_hashing_include_fields_source_ip },
6570           ecmp_hashing_include_fields_destination_ip: { get_param: ecmp_hashing_include_fields_destination_ip },
6571           ecmp_hashing_include_fields_ip_protocol: { get_param: ecmp_hashing_include_fields_ip_protocol },
6572           ecmp_hashing_include_fields_source_port: { get_param: ecmp_hashing_include_fields_source_port },
6573           ecmp_hashing_include_fields_destination_port: { get_param: ecmp_hashing_include_fields_destination_port },
6574         }
6575       virtual_machine_interface_host_routes:
6576         {
6577           virtual_machine_interface_host_routes_route:
6578             [{
6579               virtual_machine_interface_host_routes_route_prefix: { get_param: virtual_machine_interface_host_routes_route_prefix },
6580               virtual_machine_interface_host_routes_route_next_hop: { get_param: virtual_machine_interface_host_routes_route_next_hop },
6581               virtual_machine_interface_host_routes_route_next_hop_type: { get_param: virtual_machine_interface_host_routes_route_next_hop_type },
6582               virtual_machine_interface_host_routes_route_community_attributes:
6583                 {
6584                   virtual_machine_interface_host_routes_route_community_attributes_community_attribute: [{ get_param: virtual_machine_interface_host_routes_route_community_attributes_community_attribute }],
6585                 },
6586             }],
6587         }
6588       virtual_machine_interface_mac_addresses:
6589         {
6590           virtual_machine_interface_mac_addresses_mac_address: [{ get_param: virtual_machine_interface_mac_addresses_mac_address }],
6591         }
6592       virtual_machine_interface_dhcp_option_list:
6593         {
6594           virtual_machine_interface_dhcp_option_list_dhcp_option:
6595             [{
6596               virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_name: { get_param: virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_name },
6597               virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_value: { get_param: virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_value },
6598               virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_value_bytes: { get_param: virtual_machine_interface_dhcp_option_list_dhcp_option_dhcp_option_value_bytes },
6599             }],
6600         }
6601       virtual_machine_interface_bindings:
6602         {
6603           virtual_machine_interface_bindings_key_value_pair:
6604             [{
6605               virtual_machine_interface_bindings_key_value_pair_key: { get_param: virtual_machine_interface_bindings_key_value_pair_key },
6606               virtual_machine_interface_bindings_key_value_pair_value: { get_param: virtual_machine_interface_bindings_key_value_pair_value },
6607             }],
6608         }
6609       virtual_machine_interface_disable_policy: { get_param: virtual_machine_interface_disable_policy }
6610       virtual_machine_interface_allowed_address_pairs:
6611         {
6612           virtual_machine_interface_allowed_address_pairs_allowed_address_pair:
6613             [{
6614               virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip:
6615                 {
6616                   virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix: { get_param: virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix },
6617                   virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix_len: { get_param: virtual_machine_interface_allowed_address_pairs_allowed_address_pair_ip_ip_prefix_len },
6618                 },
6619               virtual_machine_interface_allowed_address_pairs_allowed_address_pair_mac: { get_param: virtual_machine_interface_allowed_address_pairs_allowed_address_pair_mac },
6620               virtual_machine_interface_allowed_address_pairs_allowed_address_pair_address_mode: { get_param: virtual_machine_interface_allowed_address_pairs_allowed_address_pair_address_mode },
6621             }],
6622         }
6623       annotations:
6624         {
6625           annotations_key_value_pair:
6626             [{
6627               annotations_key_value_pair_key: { get_param: annotations_key_value_pair_key },
6628               annotations_key_value_pair_value: { get_param: annotations_key_value_pair_value },
6629             }],
6630         }
6631       virtual_machine_interface_fat_flow_protocols:
6632         {
6633           virtual_machine_interface_fat_flow_protocols_fat_flow_protocol:
6634             [{
6635               virtual_machine_interface_fat_flow_protocols_fat_flow_protocol_protocol: { get_param: virtual_machine_interface_fat_flow_protocols_fat_flow_protocol_protocol },
6636               virtual_machine_interface_fat_flow_protocols_fat_flow_protocol_port: { get_param: virtual_machine_interface_fat_flow_protocols_fat_flow_protocol_port },
6637             }],
6638         }
6639       virtual_machine_interface_device_owner: { get_param: virtual_machine_interface_device_owner }
6640       port_security_enabled: { get_param: port_security_enabled }
6641       virtual_machine_interface_properties:
6642         {
6643           virtual_machine_interface_properties_service_interface_type: { get_param: virtual_machine_interface_properties_service_interface_type },
6644           virtual_machine_interface_properties_interface_mirror:
6645             {
6646               virtual_machine_interface_properties_interface_mirror_traffic_direction: { get_param: virtual_machine_interface_properties_interface_mirror_traffic_direction },
6647               virtual_machine_interface_properties_interface_mirror_mirror_to:
6648                 {
6649                   virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_name: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_name },
6650                   virtual_machine_interface_properties_interface_mirror_mirror_to_encapsulation: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_encapsulation },
6651                   virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_ip_address: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_ip_address },
6652                   virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_mac_address: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_analyzer_mac_address },
6653                   virtual_machine_interface_properties_interface_mirror_mirror_to_routing_instance: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_routing_instance },
6654                   virtual_machine_interface_properties_interface_mirror_mirror_to_udp_port: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_udp_port },
6655                   virtual_machine_interface_properties_interface_mirror_mirror_to_juniper_header: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_juniper_header },
6656                   virtual_machine_interface_properties_interface_mirror_mirror_to_nh_mode: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_nh_mode },
6657                   virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header:
6658                     {
6659                       virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vtep_dst_ip_address: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vtep_dst_ip_address },
6660                       virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vtep_dst_mac_address: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vtep_dst_mac_address },
6661                       virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vni: { get_param: virtual_machine_interface_properties_interface_mirror_mirror_to_static_nh_header_vni },
6662                     },
6663                 },
6664             },
6665           virtual_machine_interface_properties_local_preference: { get_param: virtual_machine_interface_properties_local_preference },
6666           virtual_machine_interface_properties_sub_interface_vlan_tag: { get_param: virtual_machine_interface_properties_sub_interface_vlan_tag },
6667         }
6668       display_name: { get_param: display_name }
6669       service_health_check_refs: [{ get_param: service_health_check_refs }]
6670       routing_instance_refs: [{ get_param: routing_instance_refs }]
6671       routing_instance_refs_data:
6672         [{
6673           routing_instance_refs_data_direction: { get_param: routing_instance_refs_data_direction },
6674           routing_instance_refs_data_vlan_tag: { get_param: routing_instance_refs_data_vlan_tag },
6675           routing_instance_refs_data_src_mac: { get_param: routing_instance_refs_data_src_mac },
6676           routing_instance_refs_data_dst_mac: { get_param: routing_instance_refs_data_dst_mac },
6677           routing_instance_refs_data_mpls_label: { get_param: routing_instance_refs_data_mpls_label },
6678           routing_instance_refs_data_service_chain_address: { get_param: routing_instance_refs_data_service_chain_address },
6679           routing_instance_refs_data_ipv6_service_chain_address: { get_param: routing_instance_refs_data_ipv6_service_chain_address },
6680           routing_instance_refs_data_protocol: { get_param: routing_instance_refs_data_protocol },
6681         }]
6682       security_group_refs: [{ get_param: security_group_refs }]
6683       physical_interface_refs: [{ get_param: physical_interface_refs }]
6684       port_tuple_refs: [{ get_param: port_tuple_refs }]
6685       interface_route_table_refs: [{ get_param: interface_route_table_refs }]
6686       virtual_machine_interface_refs: [{ get_param: virtual_machine_interface_refs }]
6687       virtual_network_refs: [{ get_param: virtual_network_refs }]
6688       virtual_machine_refs: [{ get_param: virtual_machine_refs }]
6689       qos_config_refs: [{ get_param: qos_config_refs }]
6690       virtual_machine: { get_param: virtual_machine }
6691       project: { get_param: project }
6692
6693
6694
6695 Suggested Naming Convention for Common Parameters
6696 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6697
6698 Many VNFs use the parameters in the table below are used in user_data.
6699 The table below provides a suggested naming convention for these common
6700 parameters.
6701
6702 Netmask
6703 +++++++
6704
6705 .. csv-table:: **Table 8: Suggested Naming Convention for Common Parameters:  Netmask**
6706    :header: Parameter Name,Parameter Type,Notes
6707    :align: center
6708    :widths: auto
6709
6710    {network-role}_subnet_<index>_netmask, string,
6711    int_<network-role>_subnet_<index>_netmask, string,
6712    {network-role}_v6_subnet_<index>_netmask , string,
6713    int_{network-role}_v6_subnet_<index>_netmask, string,
6714
6715 CIDR
6716 ++++
6717
6718 .. csv-table:: **Table 9: Suggested Naming Convention for Common Parameters:  CIDR**
6719    :header: Parameter Name,Parameter Type,Notes
6720    :align: center
6721    :widths: auto
6722
6723    <network-role>_subnet_<index>_cidr, string,
6724    int_<network-role>_subnet_<index>_cidr, string,
6725    <network-role>_v6_subnet_<index>_cidr, string,
6726    int_<network-role>_v6_subnet_<index>_cidr, string,
6727
6728 Default Gateway
6729 +++++++++++++++
6730
6731 .. csv-table:: **Table 10: Suggested Naming Convention for Common Parameters:  Default Gateway**
6732    :header: Parameter Name,Parameter Type,Notes
6733    :align: center
6734    :widths: auto
6735
6736    {network-role}_subnet_<index>_default_gateway, string,
6737    {network-role}_v6_subnet_<index>_default_gateway, string,
6738
6739 DCAE Collector IP Address
6740 +++++++++++++++++++++++++
6741
6742 .. csv-table:: **Table 11: Suggested Naming Convention for Common Parameters:  DCAE Collector Address**
6743    :header: Parameter Name,Parameter Type,Notes
6744    :align: center
6745    :widths: auto
6746
6747    dcae_collector_ip_<index>, string,
6748    dcae_collector_v6_ip_<index>, string,
6749
6750 NTP Server IP Address
6751 +++++++++++++++++++++
6752
6753 .. csv-table:: **Table 12: Suggested Naming Convention for Common Parameters:  NTP Server IP Address**
6754    :header: Parameter Name,Parameter Type,Notes
6755    :align: center
6756    :widths: auto
6757
6758    ntp_ip_<index>, string,
6759    ntp_v6_ip_<index>, string,
6760
6761 DNS
6762 ++++++++
6763
6764 .. csv-table:: **Table 13: Suggested Naming Convention for Common Parameters:  DCAE Collector Address**
6765    :header: Parameter Name,Parameter Type,Notes
6766    :align: center
6767    :widths: auto
6768
6769    dns_{network-role}_ip_<index>, string,
6770    dns_{network-role}_v6_ip_<index>, string,
6771
6772 Security Group
6773 ++++++++++++++
6774
6775 .. csv-table:: **Table 14: Suggested Naming Convention for Common Parameters:  Security Group**
6776    :header: Parameter Name,Parameter Type,Notes
6777    :align: center
6778    :widths: auto
6779
6780    {vm-type}_security_group, string, Security Group applicable to one {vm-type} and more than one network (internal and/or external)
6781    {network-role}_security_group, string, Security Group applicable to more than one {vm-type} and one external network
6782    int_{network-role}_security_group, string, Security Group applicable to more than one {vm-type} and one internal network
6783    {vm-type}_{network-role}_security_group, string, Security Group applicable to one {vm-type} and one external network
6784    {vm-type}_int_{network-role}_security_group, string, Security Group applicable to one {vm-type} and one internal network
6785    shared_security_group, string, Security Group applicable to more than one {vm-type} and more than one network (internal and/or external)
6786
6787 ONAP VNF Modularity
6788 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
6789
6790 ONAP supports a modular Heat Orchestration Template design pattern,
6791 referred to as *VNF Modularity.* With this approach, a single VNF **MAY** be
6792 composed from one or more Heat Orchestration Templates, each of which
6793 represents a subset of the overall VNF. These component parts are
6794 referred to as *VNF Modules*. During orchestration, these modules
6795 are deployed incrementally to create the complete VNF.
6796
6797 As stated in R-33132, a VNF's Heat Orchestration Template **MAY** be
6798      1.) Base Module Heat Orchestration Template (also referred to as a
6799       Base Module),
6800      2.) Incremental Module Heat Orchestration Template (referred to as
6801       an Incremental Module), or
6802      3.) a Cinder Volume Module Heat Orchestration Template (referred to as
6803       Cinder Volume  Module).
6804
6805 As stated in R-20974, at orchestration time, the VNF's Base Module **MUST**
6806 be deployed first, prior to any incremental modules.
6807
6808 As stated in R-28980, R-86926, and R-91497, a
6809 VNF's incremental module **MAY** be used for
6810
6811   * initial VNF deployment only
6812   * scale out only
6813   * both deployment and scale out
6814
6815 As stated in R-68122, a VNF's incremental module **MAY** be deployed
6816 more than once, either during initial VNF deployment and/or scale out
6817
6818 As stated in R-37028 and R-13196, a VNF **MUST** be composed
6819 of one Base Module and *MAY** be composed of zero to many Incremental
6820 Modules.
6821
6822 ONAP also supports the concept of an optional, independently deployed
6823 Cinder volume via a separate Heat Orchestration Templates, referred to
6824 as a Cinder Volume Module. This allows the volume to persist after a VM
6825 (i.e., OS::Nova::Server) is deleted, allowing the volume to be reused on
6826 another instance (e.g., during a fail over activity).
6827
6828 The scope of a Cinder volume module, when it exists, must be 1:1 with a
6829 Base module or Incremental Module.
6830
6831 A VNF module (base, incremental, cinder) **MAY** support nested templates.
6832
6833 A shared Heat Resource is a resource that **MAY** be used by
6834 other Heat Resources either in the Base Module or an
6835 Incremental Module.
6836
6837
6838
6839 .. req::
6840     :id: R-61001
6841     :target: VNF
6842     :keyword: MUST
6843
6844     A shared Heat Orchestration Template resource must be defined
6845     in the base module. A shared resource is a resource that that will
6846     be referenced by another resource that is defined in the Base Module
6847     and/or one or more incremental modules. When the shared resource needs
6848     to be referenced by a resource in an incremental module, the UUID of
6849     the shared resource **MUST** be exposed by declaring an ONAP Base
6850     Module Output Parameter.
6851
6852 When the shared resource needs to be referenced by a resource in an
6853 incremental module, the UUID of the shared resource must be exposed by
6854 declaring an ONAP Base Module Output Parameter.
6855
6856 An example of a shared resource is the resource
6857 OS::Neutron::SecurityGroup. Security groups are sets of IP filter rules
6858 that are applied to a VNF’s networking. The resource OS::Neutron::Port
6859 has a property security_groups which provides the security groups
6860 associated with port. The value of parameter(s) associated with this
6861 property must be the UUIDs of the resource(s)
6862 OS::Neutron::SecurityGroup.
6863
6864 *Note:* A Cinder volume is not considered a shared resource. A volume
6865 template must correspond 1:1 with a base template or add-on module
6866 template.
6867
6868 Suggested Patterns for Modular VNFs
6869 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
6870
6871 There are numerous variations of VNF modularity. Below are two suggested
6872 usage patterns.
6873
6874 **Option 1: Incremental Modules per VNFC type**
6875
6876 a. Base module contains only the shared resources.
6877
6878 b. Group all VMs (e.g., VNFCs) of a given type (i.e. {vm-type}) into its
6879    own incremental module. That is, the VNF has an incremental module
6880    for each {vm-type}.
6881
6882 c. For a given {vm-type} incremental module, the VNF may have
6883
6884    i.  One incremental module used for both initial turn up and re-used
6885        for scaling. This approach is used when the number of VMs
6886        instantiated will be the same for initial deployment and scaling.
6887
6888    ii. Two incremental modules, where one is used for initial turn up
6889        and one is used for scaling. This approach is used when the
6890        number of VMs instantiated will be different for initial
6891        deployment and scaling.
6892
6893 **Option 2: Base VNF with Incremental Growth Modules**
6894
6895 a. Base module contains a complete initial VNF instance
6896
6897 b. Incremental modules for incremental scaling units
6898
6899    i.  May contain VMs of multiple types in logical scaling combinations
6900
6901    ii. May be separated by VM type for multi-dimensional scaling
6902
6903 With no growth units, Option 2 is equivalent to the "One Heat Template
6904 per VNF" model.
6905
6906 Note that modularization of VNFs is not required. A single Heat
6907 Orchestration Template (a base module) may still define a complete VNF,
6908 which might be appropriate for smaller VNFs that do not have any scaling
6909 options.
6910
6911 Modularity Rules
6912 ~~~~~~~~~~~~~~~~~~~~~
6913
6914 There are some rules to follow when building modular VNF templates:
6915
6916 1. All VNFs must have one Base VNF Module (template) that must be the
6917    first one deployed. The base template:
6918
6919    a. Must include all shared resources (e.g., private networks, server
6920       groups, security groups)
6921
6922    b. Must expose all shared resources (by UUID) as "outputs" in its
6923       associated Heat template (i.e., ONAP Base Module Output
6924       Parameters)
6925
6926    c. May include initial set of VMs
6927
6928    d. May be operational as a stand-alone "minimum" configuration of the
6929       VNF
6930
6931 2. VNFs may have one or more incremental modules which:
6932
6933    a. Defines additional resources that can be added to an existing VNF
6934
6935    b. Must be complete Heat templates
6936
6937       i. i.e. not snippets to be incorporated into some larger template
6938
6939    c. Should define logical growth-units or sub-components of an overall
6940       VNF
6941
6942    d. On creation, receives appropriate Base Module outputs as
6943       parameters
6944
6945       i.  Provides access to all shared resources (by UUID)
6946
6947       ii. *VNFs may have one or more incremental modules which must not be
6948           dependent on other Add-On VNF Modules*
6949
6950    e. Multiple instances of an incremental Module may be added to the
6951       same VNF (e.g., incrementally grow a VNF by a fixed "add-on"
6952       growth units)
6953
6954 3. Each VNF Module (base or incremental) may have (optional) an
6955    associated Cinder Volume Module (see Cinder Volumes)
6956
6957    a. Volume modules must correspond 1:1 with a base module or
6958       incremental module
6959
6960    b. A Cinder volume may be embedded within the base module or
6961       incremental module if persistence is not required
6962
6963 4. Shared resource UUIDs are passed between the base module and
6964    incremental modules via Heat Outputs Parameters (i.e., Base Module
6965    Output Parameters)
6966
6967    a. The output parameter name in the base must match the parameter
6968       name in the add-on module
6969
6970 VNF Modularity Examples
6971 ~~~~~~~~~~~~~~~~~~~~~~~~~
6972
6973 *Example: Base Module creates SecurityGroup*
6974
6975 A VNF has a base module, named base.yaml, that defines a
6976 OS::Neutron::SecurityGroup. The security group will be referenced by an
6977 OS::Neutron::Port resource in an incremental module, named
6978 INCREMENTAL_MODULE.yaml. The base module defines a parameter in the
6979 outputs:section named dns_sec_grp_id. dns_sec_grp_id is defined as a
6980 parameter in the incremental module. ONAP captures the UUID value of
6981 dns_sec_grp_id from the base module output statement and provides the
6982 value to the incremental module.
6983
6984 Note that the example below is not a complete Heat Orchestration
6985 Template. The {network-role} has been defined as oam to represent an oam
6986 network and the {vm-type} has been defined as dns.
6987
6988 base_MODULE.yaml
6989
6990 .. code-block:: yaml
6991
6992   parameters:
6993   . . .
6994   resources:
6995     DNS_SECURITY_GROUP:
6996       type: OS::Neutron::SecurityGroup
6997       properties:
6998         description: vDNS security group
6999         name:
7000         str_replace:
7001           template: VNF_NAME_sec_grp_DNS
7002           params:
7003             VMF_NAME: {get_param: vnf_name}
7004         rules: [. . . . .
7005         ]
7006   . . .
7007   outputs:
7008     dns_sec_grp_id:
7009       description: UUID of DNS Resource SecurityGroup
7010       value: { get_resource: DNS_SECURITY_GROUP }
7011
7012 INCREMENTAL_MODULE.yaml
7013
7014 .. code-block:: yaml
7015
7016   parameters:
7017     dns_sec_grp_id:
7018       type: string
7019       description: security group UUID
7020   . . .
7021
7022   resources:
7023     dns_0_oam_0_port:
7024       type: OS::Neutron::Port
7025         properties:
7026           name:
7027             str_replace:
7028               template: VNF_NAME_dns_oam_port
7029               params:
7030                 VNF_NAME: {get_param: vnf_name}
7031           network: { get_param: oam_net_name }
7032           fixed_ips: [{ "ip_address": { get_param: dns_oam_ip_0 }}]
7033           security_groups: [{ get_param: dns_sec_grp_id }]
7034
7035 *Examples: Base Module creates an internal network*
7036
7037 A VNF has a base module, named base_module.yaml, that creates an
7038 internal network. An incremental module, named incremental_module.yaml,
7039 will create a VM that will connect to the internal network. The base
7040 module defines a parameter in the out section named int_oam_net_id.
7041 int_oam_net_id is defined as a parameter in the incremental module.
7042 ONAP captures the UUID value of int_oam_net_id from the base module
7043 output statement and provides the value to the incremental module.
7044
7045 Note that the example below is not a complete Heat Orchestration
7046 Template. The {network-role} has been defined as oam to represent an oam
7047 network and the {vm-type} has been defined as lb for load balancer.
7048
7049 base.yaml
7050
7051 .. code-block:: yaml
7052
7053   heat_template_version: 2013-05-23
7054
7055   resources:
7056     int_oam_network:
7057       type: OS::Neutron::Network
7058       properties:
7059         name: {… }
7060   . . .
7061
7062   outputs:
7063     int_oam_net_id:
7064     value: {get_resource: int_oam_network }
7065
7066 incremental.yaml
7067
7068 .. code-block:: yaml
7069
7070   heat_template_version: 2013-05-23
7071
7072   parameters:
7073     int_oam_net_id:
7074       type: string
7075       description: ID of shared private network from Base template
7076     lb_name_0:
7077       type: string
7078       description: name for the add-on VM instance
7079
7080   resources:
7081     lb_server_0:
7082       type: OS::Nova::Server
7083       properties:
7084         name: {get_param: lb_name_0}
7085         networks:
7086           - port: { get_resource: get_resource: lb_0_int_oam_port_0  }
7087   . . .
7088     lb_0_int_oam_port_0:
7089       type: OS::Neutron::Port
7090         properties:
7091         network: { get_param: int_oam_net_id }
7092   ...
7093
7094
7095 Cinder Volumes
7096 ^^^^^^^^^^^^^^^^^^^^^^^^
7097
7098 Cinder Volumes are created with the heat resource OS::Cinder::Volume.
7099
7100 As stated in R-46119, R-90748, R-03251, a VNF's Heat Orchestration
7101 Template's Resource OS::Heat::CinderVolume **MAY** be defined in a
7102 Base Module, Incremental Module, or Cinder Volume Module.
7103
7104 ONAP supports the independent deployment of a Cinder volume via separate
7105 Heat Orchestration Templates, the Cinder Volume module. This allows the
7106 volume to persist after VNF deletion so that they can be reused on
7107 another instance (e.g., during a failover activity).
7108
7109 A Base Module or Incremental Module may have a corresponding volume
7110 module. Use of separate volume modules is optional. A Cinder volume may
7111 be embedded within the Base Module or Incremental Module if persistence
7112 is not required.
7113
7114 If a VNF Base Module or Incremental Module has an independent volume
7115 module, the scope of volume templates must be 1:1 with Base module or
7116 Incremental module. A single volume module must create only the volumes
7117 required by a single Incremental module or Base module.
7118
7119 As stated in R-11200, a VNF's Cinder Volume Module, when it exists,
7120 **MUST** be 1:1 with a Base module or Incremental module.  That is,
7121 A single volume module must create only the volumes required by a
7122 single Incremental module or Base module.
7123
7124 As stated in R-30395, a VNF's Cinder Volume Module **MAY** utilize
7125 nested heat.
7126
7127 As stated in R-89913, a VNF's Heat Orchestration Template's Cinder Volume
7128 Module Output Parameter(s) **MUST** include the
7129 UUID(s) of the Cinder Volumes created in template,
7130 while others **MAY** be included.
7131
7132 As stated in R-07443, a VNF's Heat Orchestration Templates' Cinder Volume
7133 Module Output Parameter's name and type **MUST** match the input parameter
7134 name and type in the corresponding Base Module or Incremental Module unless
7135 the Output Parameter is of the type 'comma_delimited_list',
7136 then the corresponding input parameter **MUST** be declared as type 'json'.
7137
7138 A single volume module must create only the volumes
7139 required by a single Incremental module or Base module.
7140
7141 The following rules apply to independent volume Heat templates:
7142
7143
7144 .. req::
7145     :id: R-79531
7146     :target: VNF
7147     :keyword: MUST
7148
7149     The VNF Heat Orchestration Template **MUST** define
7150     "outputs" in the volume template for each Cinder volume
7151     resource universally unique identifier (UUID) (i.e. ONAP
7152     Volume Template Output Parameters).
7153
7154 -  The VNF Incremental Module or Base Module must define input
7155    parameters that match each Volume output parameter (i.e., ONAP Volume
7156    Template Output Parameters).
7157
7158    -  ONAP will supply the volume template outputs automatically to the
7159       bases/incremental template input parameters.
7160
7161 -  Volume modules may utilize nested Heat templates.
7162
7163 Optional Property availability_zone
7164 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7165
7166
7167 .. req::
7168     :id: R-25190
7169     :target: VNF
7170     :keyword: SHOULD NOT
7171
7172     A VNF's Heat Orchestration Template's Resource 'OS::Cinder::Volume'
7173     **SHOULD NOT** declare the property 'availability_zone'.
7174
7175 If the property is used, the value **MUST**
7176 be enumerated in the environment file and must be set to nova', which
7177 is the default. There are no requirements on the parameter naming
7178 convention with the exception that the naming convention **MUST NOT** be the
7179 same as the 'OS::Nova::Server' property 'availability_zone' (i.e.,
7180 'availability_zone_{index}').
7181
7182 Optional Property volume_type
7183 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7184
7185 OpenStack supports multiple volume types. If the OS::Cinder::Volume optional
7186 property volume_type is not specified, the OpenStack default volume type is
7187 used. If a specific volume type is required, the property is used and
7188 the value **MUST** be enumerated in the environment file. There are no
7189 requirements on the parameter naming convention
7190
7191 Cinder Volume Examples
7192 ~~~~~~~~~~~~~~~~~~~~~~~~~
7193
7194 *Examples: Volume Template*
7195
7196 A VNF has a Cinder volume module, named incremental\_volume.yaml, that
7197 creates an independent Cinder volume for a VM in the module
7198 incremental.yaml. The incremental\_volume.yaml defines a parameter in
7199 the output section, lb\_volume\_id\_0 which is the UUID of the cinder
7200 volume. lb\_volume\_id\_0 is defined as a parameter in incremental.yaml.
7201 ONAP captures the UUID value of lb\_volume\_id\_0 from the volume module
7202 output statement and provides the value to the incremental module.
7203
7204 Note that the example below is not a complete Heat Orchestration
7205 Template. The {vm-type} has been defined as "lb" for load balancer
7206
7207 incremental\_volume.yaml
7208
7209 .. code-block:: yaml
7210
7211  parameters:
7212     vnf_name:
7213        type: string
7214     lb_volume_size_0:
7215        type: number
7216     ...
7217
7218  resources:
7219     dns_volume_0:
7220        type: OS::Cinder::Volume
7221        properties:
7222           name:
7223              str_replace:
7224                 template: VNF_NAME_volume_0
7225                 params:
7226                    VNF_NAME: { get_param: vnf_name }
7227           size: {get_param: dns_volume_size_0}
7228     ...
7229
7230  outputs:
7231     lb_volume_id_0:
7232        value: {get_resource: dns_volume_0}
7233     ...
7234
7235
7236 incremental.yaml
7237
7238 .. code-block:: yaml
7239
7240  parameters:
7241     lb_name_0:
7242        type: string
7243     lb_volume_id_0:
7244        type: string
7245     ...
7246
7247  resources:
7248     lb_0:
7249        type: OS::Nova::Server
7250        properties:
7251           name: {get_param: dns_name_0}
7252           networks:
7253           ...
7254
7255     lb_0_volume_attach:
7256        type: OS::Cinder::VolumeAttachment
7257        properties:
7258           instance_uuid: { get_resource: lb_0 }
7259           volume_id: { get_param: lb_volume_id_0 }
7260
7261 ONAP Support of Environment Files
7262 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
7263
7264 The use of an environment file in OpenStack is optional.  In ONAP, it is
7265 mandatory. A Heat Orchestration Template uploaded to ONAP must have a
7266 corresponding environment file, even if no parameters are required to
7267 be enumerated.
7268
7269 (Note that ONAP does not programmatically enforce the use of
7270 an environment file.)
7271
7272
7273 .. req::
7274     :id: R-67205
7275     :target: VNF
7276     :keyword: MUST
7277
7278     The VNF Heat Orchestration Template **MUST** have a corresponding
7279     environment file for a Base Module.
7280
7281 .. req::
7282     :id: R-35727
7283     :target: VNF
7284     :keyword: MUST
7285
7286     The VNF Heat Orchestration Template **MUST** have a
7287     corresponding environment file for an Incremental module.
7288
7289 .. req::
7290     :id: R-22656
7291     :target: VNF
7292     :keyword: MUST
7293
7294     The VNF Heat Orchestration Template **MUST** have a
7295     corresponding environment file for a Cinder Volume Module.
7296
7297 A nested heat template must not have an environment file; OpenStack does
7298 not support it.
7299
7300 The environment file must contain parameter values for the ONAP
7301 Orchestration Constants and VNF Orchestration Constants. These
7302 parameters are identical across all instances of a VNF type, and
7303 expected to change infrequently. The ONAP Orchestration Constants are
7304 associated with OS::Nova::Server image and flavor properties (See
7305 `Property: image`_ and `Property: flavor`_). Examples of VNF
7306 Orchestration Constants are the networking parameters associated
7307 with an internal network (e.g., private IP ranges) and Cinder
7308 volume sizes.
7309
7310 The environment file must not contain parameter values for parameters
7311 that are instance specific (ONAP Orchestration Parameters, VNF
7312 Orchestration Parameters). These parameters are supplied to the Heat by
7313 ONAP at orchestration time.
7314
7315 SDC Treatment of Environment Files
7316 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7317
7318 Parameter values enumerated in the environment file are used by SDC as
7319 the default value. However, the SDC user may use the SDC GUI to
7320 overwrite the default values in the environment file.
7321
7322 SDC generates a new environment file for distribution to SO based on
7323 the uploaded environment file and the user provided GUI updates. The
7324 user uploaded environment file is discarded when the new file is
7325 created. Note that if the user did not change any values via GUI
7326 updates, the SDC generated environment file will contain the same values
7327 as the uploaded file.
7328
7329 Use of Environment Files when using OpenStack "heat stack-create" CLI
7330 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7331
7332 When ONAP is instantiating the Heat Orchestration Template, certain
7333 parameter must not be enumerated in the environment file. This document
7334 provides the details of what parameters should not be enumerated.
7335
7336 If the Heat Orchestration Template is to be instantiated from the
7337 OpenStack Command Line Interface (CLI) using the command "heat
7338 stack-create", all parameters must be enumerated in the environment
7339 file.
7340
7341 Heat Template Constructs
7342 ^^^^^^^^^^^^^^^^^^^^^^^^^
7343
7344 Nested Heat Templates
7345 ~~~~~~~~~~~~~~~~~~~~~
7346
7347 ONAP supports nested Heat templates per the OpenStack specifications.
7348 Nested templates may be suitable for larger VNFs that contain many
7349 repeated instances of the same VM type(s). A common usage pattern is to
7350 create a nested template for each {vm-type} along with its supporting
7351 resources. The VNF module may then reference these component templates
7352 either statically by repeated definition or dynamically by using the
7353 resource OS::Heat::ResourceGroup.
7354
7355 Nested Heat Template Requirements
7356 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7357
7358 ONAP supports nested Heat Orchestration Templates. A Base Module,
7359 Incremental Module, and Cinder Volume Module may use nested heat.
7360
7361
7362 .. req::
7363     :id: R-00228
7364     :target: VNF
7365     :keyword: MAY
7366
7367     A VNF's Heat Orchestration Template **MAY**
7368     reference the nested heat statically by repeated definition.
7369
7370 .. req::
7371     :id: R-01101
7372     :target: VNF
7373     :keyword: MAY
7374
7375     A VNF's Heat Orchestration Template **MAY**
7376     reference the nested heat dynamically using the resource
7377     'OS::Heat::ResourceGroup'.
7378
7379 .. req::
7380     :id: R-60011
7381     :target: VNF
7382     :keyword: MUST
7383
7384     A VNF's Heat Orchestration Template **MUST** have no more than
7385     two levels of nesting.
7386
7387 As stated in R-67231 a VNF's Heat Orchestration template's
7388 Environment File's **MUST NOT** contain the "resource_registry:" section.
7389
7390 Two levels of nesting is defined as follows:  A base module, incremental
7391 module, or cinder volume module references a nested heat file either
7392 statically or by using the resource 'OS::Heat::ResourceGroup'.
7393 This file is the first level of nesting.
7394 If first level file then references a nested file, that file is
7395 the second level of nesting.
7396
7397
7398 .. req::
7399     :id: R-89868
7400     :target: VNF
7401     :keyword: MUST
7402
7403     The VNF Heat Orchestration Template **MUST** have unique
7404     file names within the scope of the VNF for a nested heat yaml file.
7405
7406 .. req::
7407     :id: R-52530
7408     :target: VNF
7409     :keyword: MUST
7410
7411     A VNF's Heat Orchestration Template's Nested YAML file
7412     **MUST** be in the same directory hierarchy as the VNF's Heat
7413     Orchestration Templates.
7414
7415 .. req::
7416     :id: R-90022
7417     :target: VNF
7418     :keyword: MAY
7419
7420     A VNF's Nested YAML file **MAY** be invoked more than
7421     once by a VNF's Heat Orchestration Template.
7422
7423 .. req::
7424     :id: R-04344
7425     :target: VNF
7426     :keyword: MAY
7427
7428     A VNF's Nested YAML file **MAY** be invoked by more than one of
7429     a VNF's Heat Orchestration Templates (when the VNF is composed of two
7430     or more Heat Orchestration Templates).
7431
7432 .. req::
7433     :id: R-11041
7434     :target: VNF
7435     :keyword: MUST
7436
7437     All parameters defined in a VNFs Nested YAML file
7438     **MUST** be passed in as properties of the resource calling
7439     the nested yaml file.
7440
7441 Note that:
7442
7443 -  As stated in requirement R-00011, a VNF's Heat Orchestration
7444    Template's Nested YAML file's parameter's **MUST NOT** have
7445    a parameter constraint defined.
7446
7447 -  As stated in Requirement R-44491, if a VNF's Heat Orchestration
7448    Template's OS::Nova::Server Resource metadata map value parameter
7449    'vnf\_id' is passed into a Nested YAML
7450    file, the parameter name 'vnf\_id' **MUST NOT** change.
7451
7452 -  As stated in Requirement R-86237, if a VNF's Heat Orchestration
7453    Template's OS::Nova::Server Resource metadata map value parameter
7454    'vf\_module\_id' is passed into a Nested YAML
7455    file, the parameter name 'vf\_module\_id' **MUST NOT** change.
7456
7457 -  As stated in Requirement R-16576, if a VNF's Heat Orchestration
7458    Template's OS::Nova::Server Resource metadata map value parameter
7459    'vnf\_name' is passed into a Nested YAML
7460    file, the parameter name 'vnf\_name' **MUST NOT** change.
7461
7462 -  As stated in Requirement R-49177, if a VNF's Heat Orchestration
7463    Template's OS::Nova::Server Resource metadata map value parameter
7464    'vf\_module\_name' is passed into a Nested YAML
7465    file, the parameter name 'vf\_module\_name' **MUST NOT** change.
7466
7467 -  As stated in Requirement R-70757, if a VNF's Heat Orchestration
7468    Template's OS::Nova::Server Resource metadata map value parameter
7469    'vm\_role' is passed into a Nested YAML
7470    file, the parameter name 'vm\_role' **MUST NOT** change.
7471
7472 -  As stated in Requirement R-22441, if a VNF's Heat Orchestration
7473    Template's OS::Nova::Server Resource metadata map value parameter
7474    'vf\_module\_index' is passed into a Nested YAML
7475    file, the parameter name 'vf\_module\_index' **MUST NOT** change.
7476
7477 -  As stated in Requirement R-75202, if a VNF's Heat Orchestration
7478    Template's OS::Nova::Server Resource metadata map value parameter
7479    'workload\_context' is passed into a Nested YAML
7480    file, the parameter name 'workload\_context' **MUST NOT** change.
7481
7482 -  As stated in Requirement R-62954, if a VNF's Heat Orchestration
7483    Template's OS::Nova::Server Resource metadata map value parameter
7484    'environment\_context' is passed into a Nested YAML
7485    file, the parameter name 'environment\_context' **MUST NOT** change.
7486
7487 -  With nested templates, outputs are required to expose any resource
7488    properties of the child templates to the parent template. Those would
7489    not explicitly be declared as parameters but simply referenced as
7490    get\_attribute targets against the "parent" resource.
7491
7492 -  A parameter declared in the outputs: section of a nested template can
7493    be accessed from the parent template as an attribute (i.e., via
7494    get\_attr) of the "pseudo resource" whose type is in the nested
7495    template. In the case of a OS::Heat::ResourceGroup, an output will be
7496    an attribute of the OS::Heat::ResourceGroup itself, and will be an
7497    array from the perspective of the parent template.
7498
7499 .. req::
7500     :id: R-17528
7501     :target: VNF
7502     :keyword: MUST
7503
7504     A VNF's Heat Orchestration Template's first level Nested YAML file
7505     **MUST NOT** contain more than one ``OS::Nova::Server`` resource.
7506     A VNF's Heat Orchestration Template's second level Nested YAML file
7507     **MUST NOT** contain an ``OS::Nova::Server`` resource.
7508
7509 Nested Heat Template Example: Static
7510 ++++++++++++++++++++++++++++++++++++++
7511
7512 incremental.yaml
7513
7514 .. code-block:: yaml
7515
7516  Resources:
7517    dns_server_0:
7518      type: nested.yaml
7519      properties:
7520        dns_image_name: { get_param: dns_image_name }
7521        dns_flavor_name: { get_param: dns_flavor_name }
7522        availability_zone: { get_param: availability_zone_0 }
7523        security_group: { get_param: DNS_shared_sec_grp_id }
7524        oam_net_id: { get_param: oam_protected_net_id }
7525        dns_oam_ip: { get_param: dns_oam_ip_0 }
7526        dns_name: { get_param: dns_name_0 }
7527        vnf_name: { get_param: vnf_name }
7528        vnf_id: { get_param: vnf_id }
7529        vf_module_id: {get_param: vf_module_id}
7530
7531  dns_server_1:
7532    type: nested.yaml
7533    properties:
7534      dns_image_name: { get_param: dns_image_name }
7535      dns_flavor_name: { get_param: dns_flavor_name }
7536      availability_zone: { get_param: availability_zone_1 }
7537      security_group: { get_param: DNS_shared_sec_grp_id }
7538      oam_net_id: { get_param: oam_protected_net_id }
7539      dns_oam_ip: { get_param: dns_oam_ip_1 }
7540      dns_name: { get_param: dns_name_1 }
7541      vnf_name: { get_param: vnf_name }
7542      vnf_id: { get_param: vnf_id }
7543      vf_module_id: {get_param: vf_module_id}
7544
7545 nested.yaml
7546
7547 .. code-block:: yaml
7548
7549  dns_oam_0_port:
7550    type: OS::Neutron::Port
7551    properties:
7552      name:
7553        str_replace:
7554          template: VNF_NAME_dns_oam_port
7555          params:
7556            VNF_NAME: {get_param: vnf_name}
7557      network: { get_param: oam_net_id }
7558      fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}]
7559      security_groups: [{ get_param: security_group }]
7560
7561  dns_servers:
7562    type: OS::Nova::Server
7563    properties:
7564      name: { get_param: dns_names }
7565      image: { get_param: dns_image_name }
7566      flavor: { get_param: dns_flavor_name }
7567      availability_zone: { get_param: availability_zone }
7568      networks:
7569        - port: { get_resource: dns_oam_0_port }
7570      metadata:
7571        vnf_id: { get_param: vnf_id }
7572        vf_module_id: { get_param: vf_module_id }
7573        vnf_name {get_param: vnf_name }
7574
7575 Use of Heat ResourceGroup
7576 +++++++++++++++++++++++++
7577
7578 The OS::Heat::ResourceGroup is a useful Heat element for creating
7579 multiple instances of a given resource or collection of resources.
7580 Typically, it is used with a nested Heat template, to create, for
7581 example, a set of identical OS::Nova::Server resources plus their
7582 related OS::Neutron::Port resources via a single resource in a master
7583 template.
7584
7585 OS::Heat::ResourceGroup may be used to simplify the structure of a Heat
7586 template that creates multiple instances of the same VM type.
7587
7588 However, there are important caveats to be aware of:
7589
7590 OS::Heat::ResourceGroup does not deal with structured parameters
7591 (comma-delimited-list and json) as one might typically expect. In
7592 particular, when using a list-based parameter, where each list element
7593 corresponds to one instance of the ResourceGroup, it is not possible to
7594 use the intrinsic "loop variable" %index% in the OS::Heat::ResourceGroup
7595 definition.
7596
7597 For instance, the following is **not** valid Heat for
7598 OS::Heat::ResourceGroup:
7599
7600 .. code-block:: yaml
7601
7602  type: OS::Heat::ResourceGroup
7603    resource_def:
7604      type: my_nested_vm_template.yaml
7605      properties:
7606        name: {get_param: [vm_name_list, "%index%"]}
7607
7608 Although this appears to use the nth entry of the vm_name_list list for
7609 the nth element of the OS::Heat::ResourceGroup, it will in fact result
7610 in a Heat exception. When parameters are provided as a list (one for
7611 each element of a OS::Heat::ResourceGroup), you must pass the complete
7612 parameter to the nested template along with the current index as
7613 separate parameters.
7614
7615 Below is an example of an **acceptable** Heat Syntax for a
7616 ResourceGroup:
7617
7618 .. code-block:: yaml
7619
7620  type: OS::Heat::ResourceGroup
7621    resource_def:
7622      type: my_nested_vm_template.yaml
7623      properties:
7624        names: {get_param: vm_name_list}
7625        index: "%index%"
7626
7627 You can then reference within the nested template as:
7628
7629 { get\_param: [names, {get\_param: index} ] }
7630
7631 OS::Heat::ResourceGroup Property count
7632 ________________________________________
7633
7634
7635 .. req::
7636     :id: R-50011
7637     :target: VNF
7638     :keyword: MUST
7639
7640     A VNF's Heat Orchestration Template's 'OS::Heat::ResourceGroup'
7641     property 'count' **MUST** be enumerated in the VNF's
7642     Heat Orchestration Template's Environment File and **MUST** be
7643     assigned a value.
7644
7645 This is required for ONAP to build the TOSCA model for the VNF.
7646
7647 .. code-block:: yaml
7648
7649  type: OS::Heat::ResourceGroup
7650  properties:
7651    count: { get_param: count }
7652    index_var: index
7653    resource_def:
7654      type: my_nested_vm_template.yaml
7655      properties:
7656        names: {get_param: vm_name_list}
7657        index: index
7658
7659 Availability Zone and ResourceGroups
7660 ____________________________________
7661
7662 The resource OS::Heat::ResourceGroup and the property availability\_zone
7663 has been an "issue" with a few VNFs since ONAP only supports
7664 availability\_zone as a string parameter and not a
7665 comma\_delimited\_list. This makes it difficult to use a
7666 OS::Heat::ResourceGroup to create Virtual Machines in more
7667 than one availability zone.
7668
7669 There are numerous solutions to this issue. Below are two suggested
7670 usage patterns.
7671
7672 **Option 1:** create a CDL in the OS::Heat::ResourceGroup. In the
7673 resource type: OS::Heat::ResourceGroup, create a comma\_delimited\_list
7674 availability\_zones by using the intrinsic function list\_join.
7675
7676 .. code-block:: yaml
7677
7678  <resource name>:
7679   type: OS::Heat::ResourceGroup
7680   properties:
7681     count: { get_param: node_count }
7682     index_var: index
7683     resource_def:
7684       type: nested.yaml
7685       properties:
7686         index: index
7687         avaialability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] }
7688
7689 In the nested heat
7690
7691 .. code-block:: yaml
7692
7693  parameters:
7694    avaialability_zones:
7695      type: comma_delimited_list
7696      description:
7697
7698  resources:
7699    servers:
7700      type: OS::Nova::Server
7701      properties:
7702        name: { get_param: [ dns_names, get_param: index ] }
7703        image: { get_param: dns_image_name }
7704        flavor: { get_param: dns_flavor_name }
7705        availability_zone: { get_param: [ avaialability_zones, get_param: index ] }
7706
7707 **Option 2:** Create a CDL by passing the availability zone parameter
7708 into a nested heat template. An example is provided below.
7709
7710 base.yaml
7711
7712 .. code-block:: yaml
7713
7714   availability_zone_list:
7715      type: az_list_generate.yaml
7716      properties:
7717        availability_zone_0: { get_param: availability_zone_0 }
7718        availability_zone_1: { get_param: availability_zone_1 }
7719
7720     create_virtual_machines:
7721       type: OS::Heat::ResourceGroup
7722       properties:
7723         count: { get_param: count }
7724         index_var: $INDEX
7725         resource_def:
7726           type: nest_file.yaml
7727           properties:
7728             index: $INDEX
7729             availability_zone_0 : { get_attr: [availability_zone_list, general_zones ] }
7730             . . .
7731
7732 az_list_generate.yaml
7733
7734 .. code-block:: yaml
7735
7736   parameters:
7737     availability_zone_0:
7738       type: string
7739       description: availability zone 0
7740
7741     availability_zone_1:
7742       type: string
7743       description: availability zone 1
7744
7745   outputs:
7746
7747     general_zones:
7748       value: [
7749         { get_param: availability_zone_0 },
7750         { get_param: availability_zone_1 },
7751         { get_param: availability_zone_0 },
7752         { get_param: availability_zone_1 },
7753         { get_param: availability_zone_0 },
7754         { get_param: availability_zone_1 },
7755   ]
7756
7757
7758 Nested Heat Template Example: OS::Heat::ResourceGroup
7759 _________________________________________________________
7760
7761 In this example, ocgapp\_volume.yml creates volumes using a
7762 OS::Heat::ResourceGroup that uses nested heat by calling
7763 ocgapp_nested_volume.yml. ocgapp\_volume.yml has an outputs: parameter
7764 ocgapp\_volume\_ids which is declared a input parameter of type: json in
7765 ocgapp\_volume.yml.
7766
7767
7768 This is an example of requirement R-07443, where
7769 a VNF's Heat Orchestration Templates' Cinder Volume Module Output
7770 Parameter's name and type **MUST** match the input parameter name and type
7771 in the corresponding Base Module or Incremental Module unless the Output
7772 Parameter is of the type 'comma\_delimited\_list', then the corresponding
7773 input parameter **MUST** be declared as type 'json'.
7774
7775 ocgapp\_volume.yml
7776
7777 .. code-block:: yaml
7778
7779   heat_template_version: 2014-10-16
7780
7781   description: Template for the volumes
7782
7783   parameters:
7784     vnf_name:
7785       type: string
7786       label: OCG VNF Name
7787       description: OCG VNF Name
7788     ocgapp_volume_size_0:
7789       type: number
7790       label: Cinder volume 1 size
7791       description: the size of the Cinder volume
7792       constraints:
7793       - range: { min: 100, max: 400 }
7794     ocgapp_volume_type_0:
7795       type: string
7796       label: app vm 1 volume type
7797       description: the name of the target volume backend for the first OCG APP
7798     volume_count:
7799       type: number
7800       label: volume count
7801       description: number of volumes needed
7802
7803   resources:
7804     ocgapp_volume_resource_group:
7805       type: OS::Heat::ResourceGroup
7806       properties:
7807         count: {get_param: volume_count}
7808         index_var: index
7809         resource_def:
7810           type: ocgapp_nested_volume.yml
7811           properties:
7812             index: index
7813             size: {get_param: ocgapp_volume_size_0}
7814             volume_type: {get_param: ocgapp_volume_type_0}
7815             vnf_name: {get_param: vnf_name}
7816
7817   outputs:
7818     ocgapp_volume_ids:
7819     description: ocgapp volume ids
7820     value: {get_attr: [ocgapp_volume_resource_group, ocgapp_volume_id_0]}
7821
7822 ocgapp_nested_volume.yml
7823
7824 .. code-block:: yaml
7825
7826  heat_template_version: 2014-10-16
7827
7828  description: nested heat
7829
7830  parameters:
7831    index:
7832      type: number
7833      label: Volume Index
7834      description: number of volumes to spin up
7835    size:
7836      type: number
7837      label: Volume Size
7838      description: size of the cinder volumes
7839    volume_type:
7840      type: string
7841      label: Volume Type
7842      description: type of cinder volumes
7843    vnf_name:
7844      type: string
7845      label: VNF Name
7846      description: vnf name
7847
7848  resources:
7849    ocgapp_volume_0:
7850      type: OS::Cinder::Volume
7851      properties:
7852        size: {get_param: size}
7853        volume_type: {get_param: volume_type}
7854        name:
7855          str_replace:
7856            template: VF_NAME_STACK_NAME_INDEX
7857            params:
7858              VF_NAME: { get_param: vnf_name }
7859              STACK_NAME: { get_param: 'OS::stack_name' }
7860              INDEX: {get_param: index}
7861
7862  outputs:
7863    ocgapp_volume_id_0:
7864    description: the ocgapp volume uuid
7865    value: {get_resource: ocgapp_volume_0}
7866
7867 The heat template below is a partial heat template,
7868
7869 ocgapp.yml
7870
7871 .. code-block:: yaml
7872
7873   heat_template_version: 2014-10-16
7874
7875   #file version 1.0
7876   description: OCG Apps template
7877
7878   parameters:
7879     ocgapp_volume_ids:
7880       type: json
7881       description: Unique IDs for volumes
7882
7883   resources:
7884     ocgapp_server_0:
7885       type: OS::Nova::Server
7886       properties:
7887     . . . .
7888     ocgapp_server_1:
7889       type: OS::Nova::Server
7890       properties:
7891     . . . .
7892     ocgapp_volume_attachment_0:
7893       type: OS::Cinder::VolumeAttachment
7894       properties:
7895         volume_id: {get_param: [ocgapp_volume_ids, 0]}
7896         instance_uuid: {get_resource: ocgapp_server_0}
7897     ocgapp_volume_attachment_1:
7898       type: OS::Cinder::VolumeAttachment
7899       properties:
7900         volume_id: {get_param: [ocgapp_volume_ids, 1]}
7901         instance_uuid: {get_resource: ocgapp_server_1}
7902
7903 External References
7904 ~~~~~~~~~~~~~~~~~~~
7905
7906 Heat templates *should not* reference any HTTP-based resource
7907 definitions, any HTTP-based nested configurations, or any HTTP-based
7908 environment files.
7909
7910 -  During orchestration, ONAP *should not* retrieve any such resources
7911    from external/untrusted/unknown sources.
7912
7913 -  VNF images should not contain such references in user-data or other
7914    configuration/operational scripts that are specified via Heat or
7915    encoded into the VNF image itself.
7916
7917 *Note:* HTTP-based references are acceptable if the HTTP-based reference
7918 is accessing information with the VM private/internal network.
7919
7920 Note that Namespaces in XML (defined at
7921 http://www.w3.org/TR/2009/REC-xml-names-20091208/) are allowed if the
7922 Heat Orchestration Template is describing and storing software
7923 configuration information. An XML namespace is identified by a URI
7924 reference. A Uniform Resource Identifier (URI) is a string of characters
7925 which identifies an Internet Resource. The most common URI is the
7926 Uniform Resource Locator (URL) which identifies an Internet domain
7927 address. Another, not so common type of URI is the Universal Resource
7928 Name (URN). The namespace URI is not used by XML the parser to look up
7929 information. The purpose of using an URI is to give the namespace a
7930 unique name.
7931
7932 Heat Files Support (get\_file)
7933 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7934
7935 Heat Templates may contain the inclusion of text files into Heat
7936 templates via the Heat get\_file directive. This may be used, for
7937 example, to define a common "user-data" script, or to inject files into
7938 a VM on startup via the "personality" property.
7939
7940 Support for Heat Files is subject to the following limitations:
7941
7942
7943 .. req::
7944     :id: R-76718
7945     :target: VNF
7946     :keyword: MUST
7947
7948     If a VNF's Heat Orchestration Template uses the intrinsic function
7949     'get\_file', the 'get\_file' target **MUST** be referenced in
7950     the Heat Orchestration Template by file name.
7951
7952 The 'get\_file' target files are on-boarded to SDC in the same package
7953 that contains the VNF's complete Heat Orchestration Template.
7954
7955
7956 .. req::
7957     :id: R-41888
7958     :target: VNF
7959     :keyword: MUST NOT
7960
7961     A VNF's Heat Orchestration Template intrinsic function
7962     'get\_file' **MUST NOT** utilize URL-based file retrieval.
7963
7964 .. req::
7965     :id: R-62177
7966     :target: VNF
7967     :keyword: MUST
7968
7969     When using the intrinsic function get_file, the included files
7970     **MUST** have unique file names within the scope of the VNF.
7971
7972 .. req::
7973     :id: R-87848
7974     :target: VNF
7975     :keyword: MUST
7976
7977     A VNF's Heat Orchestration Template's 'get\_file' target files
7978     **MUST** be in the same directory hierarchy as the VNF's Heat
7979     Orchestration Templates.
7980
7981 ONAP does not support a hierarchical structure.  A VNF's YAML files
7982 must be in a single, flat directory.
7983
7984
7985 .. req::
7986     :id: R-05050
7987     :target: VNF
7988     :keyword: MAY
7989
7990     A VNF's Heat Orchestration Templates intrinsic function
7991     'get\_file' <content key> **MAY** be used:
7992
7993         * more than once in a VNF's Heat Orchestration Template
7994         * in two or more of a VNF's Heat Orchestration Templates
7995         * in a VNF's Heat Orchestration Templates nested YAML file
7996
7997 Key Pairs
7998 ~~~~~~~~~
7999
8000 When Nova Servers are created via Heat templates, they may be passed a
8001 "keypair" which provides an ssh key to the 'root' login on the newly
8002 created VM. This is often done so that an initial root key/password does
8003 not need to be hard-coded into the image.
8004
8005 Key pairs are unusual in OpenStack, because they are the one resource
8006 that is owned by an OpenStack User as opposed to being owned by an
8007 OpenStack Tenant. As a result, they are usable only by the User that
8008 created the keypair. This causes a problem when a Heat template attempts
8009 to reference a keypair by name, because it assumes that the keypair was
8010 previously created by a specific ONAP user ID.
8011
8012 When a keypair is assigned to a server, the SSH public-key is
8013 provisioned on the VMs at instantiation time. They keypair itself is not
8014 referenced further by the VM (i.e. if the keypair is updated with a new
8015 public key, it would only apply to subsequent VMs created with that
8016 keypair).
8017
8018 Due to this behavior, the recommended usage of keypairs is in a more
8019 generic manner which does not require the pre-requisite creation of a
8020 keypair. The Heat should be structured in such a way as to:
8021
8022 -  Pass a public key as a parameter value instead of a keypair name
8023
8024 -  Create a new keypair within The VNF Heat Orchestration Template (in the
8025    base module) based on an existing public key for use within that VNF
8026
8027 By following this approach, the end result is the same as pre-creating
8028 the keypair using the public key – i.e., that public key will be
8029 provisioned in the new VM. However, this recommended approach also makes
8030 sure that a known public key is supplied (instead of having OpenStack
8031 generate a public/private pair to be saved and tracked outside of ONAP).
8032 It also removes any access/ownership issues over the created keypair.
8033
8034 The public keys may be enumerated as a VNF Orchestration Constant in the
8035 environment file (since it is public, it is not a secret key), or passed
8036 at run-time as instance-specific parameters. ONAP will never
8037 automatically assign a public/private key pair.
8038
8039 *Example (create keypair with an existing ssh public-key for {vm-type}
8040 of lb (for load balancer)):*
8041
8042 .. code-block:: yaml
8043
8044  parameters:
8045     vnf_name:
8046        type: string
8047     lb_ssh_public_key:
8048        type: string
8049
8050  resources:
8051     my_keypair:
8052        type: OS::Nova::Keypair
8053        properties:
8054           name:
8055              str_replace:
8056                 template: VNF_NAME_key_pair
8057                 params:
8058                 VNF_NAME: { get_param: vnf_name }
8059           public_key: {get_param: lb_ssh_public_key}
8060           save_private_key: false
8061
8062 Security Groups
8063 ~~~~~~~~~~~~~~~
8064
8065 OpenStack allows a tenant to create Security groups and define rules
8066 within the security groups.
8067
8068 Security groups, with their rules, may either be created in the Heat
8069 Orchestration Template or they can be pre-created in OpenStack and
8070 referenced within the Heat template via parameter(s). There can be a
8071 different approach for security groups assigned to ports on internal
8072 (intra-VNF) networks or external networks (inter-VNF). Furthermore,
8073 there can be a common security group across all VMs for a specific
8074 network or it can vary by VM (i.e., {vm-type}) and network type (i.e.,
8075 {network-role}).
8076
8077 Anti-Affinity and Affinity Rules
8078 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8079
8080 Anti-affinity or affinity rules are supported using normal OpenStack
8081 OS::Nova::ServerGroup resources. Separate ServerGroups are typically
8082 created for each VM type to prevent them from residing on the same host,
8083 but they can be applied to multiple VM types to extend the
8084 affinity/anti-affinity across related VM types as well.
8085
8086 *Example:*
8087
8088 In this example, the {network-role} has been defined as oam to represent
8089 an oam network and the {vm-type} have been defined as lb for load
8090 balancer and db for database.
8091
8092 .. code-block:: yaml
8093
8094  resources:
8095  db_server_group:
8096     type: OS::Nova::ServerGroup
8097     properties:
8098        name:
8099           str_replace:
8100              params:
8101                 $vnf_name: {get_param: vnf_name}
8102              template: $vnf_name-server_group1
8103        policies:
8104           - anti-affinity
8105
8106  lb_server_group:
8107     type: OS::Nova::ServerGroup
8108     properties:
8109        name:
8110           str_replace:
8111              params:
8112                 $vnf_name: {get_param: vnf_name}
8113              template: $vnf_name-server_group2
8114        policies:
8115           - affinity
8116
8117  db_0:
8118     type: OS::Nova::Server
8119     properties:
8120     ...
8121     scheduler_hints:
8122        group: {get_resource: db_server_group}
8123
8124  db_1:
8125     type: OS::Nova::Server
8126     properties:
8127     ...
8128     scheduler_hints:
8129        group: {get_resource: db_server_group}
8130
8131  lb_0:
8132     type: OS::Nova::Server
8133     properties:
8134     ...
8135     scheduler_hints:
8136        group: {get_resource: lb_server_group}
8137
8138 Resource Data Synchronization
8139 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
8140
8141 For cases where synchronization is required in the orchestration of Heat
8142 resources, two approaches are recommended:
8143
8144 -  Standard Heat depends\_on property for resources
8145
8146    -  Assures that one resource completes before the dependent resource
8147       is orchestrated.
8148
8149    -  Definition of completeness to OpenStack may not be sufficient
8150       (e.g., a VM is considered complete by OpenStack when it is ready
8151       to be booted, not when the application is up and running).
8152
8153 -  Use of Heat Notifications
8154
8155    -  Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle
8156       resources.
8157
8158    -  Pre-requisite resources issue *wc\_notify* commands in user\_data.
8159
8160    -  Dependent resource define depends\_on in the
8161       OS::Heat::WaitCondition resource.
8162
8163 *Example: "depends\_on" case*
8164
8165 In this example, the {network-role} has been defined as oam to represent
8166 an oam network and the {vm-type} has been defined as oam to represent an
8167 oam server.
8168
8169 .. code-block:: yaml
8170
8171  resources:
8172    oam_server_01:
8173      type: OS::Nova::Server
8174      properties:
8175        name: {get_param: [oam_ names, 0]}
8176        image: {get_param: oam_image_name}
8177        flavor: {get_param: oam_flavor_name}
8178        availability_zone: {get_param: availability_zone_0}
8179        networks:
8180          - port: {get_resource: oam01_port_0}
8181          - port: {get_resource: oam01_port_1}
8182        user_data:
8183        scheduler_hints: {group: {get_resource: oam_servergroup}}
8184        user_data_format: RAW
8185
8186  oam_01_port_0:
8187    type: OS::Neutron::Port
8188    properties:
8189      network: {get_resource: oam_net_name}
8190      fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}]
8191      security_groups: [{get_resource: oam_security_group}]
8192
8193  oam_01_port_1:
8194    type: OS::Neutron::Port
8195    properties:
8196      network: {get_param: oam_net_name}
8197      fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}]
8198      security_groups: [{get_resource: oam_security_group}]
8199
8200  oam_01_vol_attachment:
8201    type: OS::Cinder::VolumeAttachment
8202    depends_on: oam_server_01
8203    properties:
8204      volume_id: {get_param: oam_vol_1}
8205      mountpoint: /dev/vdb
8206      instance_uuid: {get_resource: oam_server_01}
8207
8208 High Availability
8209 ^^^^^^^^^^^^^^^^^
8210
8211 VNF/VM parameters may include availability zone IDs for VNFs that
8212 require high availability.
8213
8214 The Heat must comply with the following requirements to specific
8215 availability zone IDs:
8216
8217 -  The Heat template should spread Nova resources across the
8218    availability zones as desired
8219
8220 Post Orchestration & VNF Configuration
8221 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
8222
8223 Heat templates should contain a minimum amount of post-orchestration
8224 configuration data. For instance, *do not* embed complex user-data
8225 scripts in the template with large numbers of configuration parameters
8226 to the Heat template.
8227
8228 -  VNFs may provide configuration APIs for use after VNF creation. Such
8229    APIs will be invoked via application and/or SDN controllers.
8230
8231 *Note:* It is important to follow this convention to the extent possible
8232 even in the short-term as of the long-term direction.
8233
8234