docs/Chapter5/Heat/ONAP Heat Template Constructs.rst

   1 .. Licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2017 AT&T Intellectual Property.  All rights reserved.
   4
   5 .. _ONAP Heat Heat Template Constructs:
   6
   7 ONAP Heat Heat Template Constructs
   8 --------------------------------------
   9
  10 .. _Nested Heat Templates:
  11
  12 Nested Heat Templates
  13 ^^^^^^^^^^^^^^^^^^^^^^^^^
  14
  15 ONAP supports nested Heat templates per the OpenStack specifications.
  16 Nested templates may be suitable for larger VNFs that contain many
  17 repeated instances of the same VM type(s). A common usage pattern is to
  18 create a nested template for each {vm-type} along with its supporting
  19 resources. The VNF module may then reference these component templates
  20 either statically by repeated definition or dynamically by using the
  21 resource OS::Heat::ResourceGroup.
  22
  23 Nested Heat Template Requirements
  24 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  25
  26 ONAP supports nested Heat Orchestration Templates. A Base Module,
  27 Incremental Module, and Cinder Volume Module may use nested heat.
  28
  29
  30 .. req::
  31     :id: R-00228
  32     :target: VNF
  33     :keyword: MAY
  34
  35     A VNF's Heat Orchestration Template **MAY**
  36     reference the nested heat statically by repeated definition.
  37
  38 .. req::
  39     :id: R-01101
  40     :target: VNF
  41     :keyword: MAY
  42
  43     A VNF's Heat Orchestration Template **MAY**
  44     reference the nested heat dynamically using the resource
  45     'OS::Heat::ResourceGroup'.
  46
  47 .. req::
  48     :id: R-60011
  49     :target: VNF
  50     :keyword: MUST
  51
  52     A VNF's Heat Orchestration Template **MUST** have no more than
  53     two levels of nesting.
  54
  55 As stated in :need:`R-67231` a VNF's Heat Orchestration template's
  56 Environment File's **MUST NOT** contain the "resource_registry:" section.
  57
  58 Two levels of nesting is defined as follows:  A base module, incremental
  59 module, or cinder volume module references a nested heat file either
  60 statically or by using the resource 'OS::Heat::ResourceGroup'.
  61 This file is the first level of nesting.
  62 If first level file then references a nested file, that file is
  63 the second level of nesting.
  64
  65
  66 .. req::
  67     :id: R-89868
  68     :target: VNF
  69     :keyword: MUST
  70
  71     The VNF Heat Orchestration Template **MUST** have unique
  72     file names within the scope of the VNF for a nested heat yaml file.
  73
  74 .. req::
  75     :id: R-52530
  76     :target: VNF
  77     :keyword: MUST
  78
  79     A VNF's Heat Orchestration Template's Nested YAML file
  80     **MUST** be in the same directory hierarchy as the VNF's Heat
  81     Orchestration Templates.
  82
  83 .. req::
  84     :id: R-90022
  85     :target: VNF
  86     :keyword: MAY
  87
  88     A VNF's Nested YAML file **MAY** be invoked more than
  89     once by a VNF's Heat Orchestration Template.
  90
  91 .. req::
  92     :id: R-04344
  93     :target: VNF
  94     :keyword: MAY
  95
  96     A VNF's Nested YAML file **MAY** be invoked by more than one of
  97     a VNF's Heat Orchestration Templates (when the VNF is composed of two
  98     or more Heat Orchestration Templates).
  99
 100 .. req::
 101     :id: R-11041
 102     :target: VNF
 103     :keyword: MUST
 104
 105     All parameters defined in a VNFs Nested YAML file
 106     **MUST** be passed in as properties of the resource calling
 107     the nested yaml file.
 108
 109 Note that:
 110
 111 -  As stated in requirement :need:`R-00011`, a VNF's Heat Orchestration
 112    Template's Nested YAML file's parameter's **MUST NOT** have
 113    a parameter constraint defined.
 114
 115 -  As stated in Requirement :need:`R-44491`, if a VNF's Heat Orchestration
 116    Template's OS::Nova::Server Resource metadata map value parameter
 117    'vnf\_id' is passed into a Nested YAML
 118    file, the parameter name 'vnf\_id' **MUST NOT** change.
 119
 120 -  As stated in Requirement :need:`R-86237`, if a VNF's Heat Orchestration
 121    Template's OS::Nova::Server Resource metadata map value parameter
 122    'vf\_module\_id' is passed into a Nested YAML
 123    file, the parameter name 'vf\_module\_id' **MUST NOT** change.
 124
 125 -  As stated in Requirement :need:`R-16576`, if a VNF's Heat Orchestration
 126    Template's OS::Nova::Server Resource metadata map value parameter
 127    'vnf\_name' is passed into a Nested YAML
 128    file, the parameter name 'vnf\_name' **MUST NOT** change.
 129
 130 -  As stated in Requirement :need:`R-49177`, if a VNF's Heat Orchestration
 131    Template's OS::Nova::Server Resource metadata map value parameter
 132    'vf\_module\_name' is passed into a Nested YAML
 133    file, the parameter name 'vf\_module\_name' **MUST NOT** change.
 134
 135 -  As stated in Requirement :need:`R-70757`, if a VNF's Heat Orchestration
 136    Template's OS::Nova::Server Resource metadata map value parameter
 137    'vm\_role' is passed into a Nested YAML
 138    file, the parameter name 'vm\_role' **MUST NOT** change.
 139
 140 -  As stated in Requirement :need:`R-22441`, if a VNF's Heat Orchestration
 141    Template's OS::Nova::Server Resource metadata map value parameter
 142    'vf\_module\_index' is passed into a Nested YAML
 143    file, the parameter name 'vf\_module\_index' **MUST NOT** change.
 144
 145 -  As stated in Requirement :need:`R-75202`, if a VNF's Heat Orchestration
 146    Template's OS::Nova::Server Resource metadata map value parameter
 147    'workload\_context' is passed into a Nested YAML
 148    file, the parameter name 'workload\_context' **MUST NOT** change.
 149
 150 -  As stated in Requirement :need:`R-62954`, if a VNF's Heat Orchestration
 151    Template's OS::Nova::Server Resource metadata map value parameter
 152    'environment\_context' is passed into a Nested YAML
 153    file, the parameter name 'environment\_context' **MUST NOT** change.
 154
 155 -  With nested templates, outputs are required to expose any resource
 156    properties of the child templates to the parent template. Those would
 157    not explicitly be declared as parameters but simply referenced as
 158    get\_attribute targets against the "parent" resource.
 159
 160 -  A parameter declared in the outputs: section of a nested template can
 161    be accessed from the parent template as an attribute (i.e., via
 162    get\_attr) of the "pseudo resource" whose type is in the nested
 163    template. In the case of a OS::Heat::ResourceGroup, an output will be
 164    an attribute of the OS::Heat::ResourceGroup itself, and will be an
 165    array from the perspective of the parent template.
 166
 167 .. req::
 168     :id: R-17528
 169     :target: VNF
 170     :keyword: MUST
 171
 172     A VNF's Heat Orchestration Template's first level Nested YAML file
 173     **MUST NOT** contain more than one ``OS::Nova::Server`` resource.
 174     A VNF's Heat Orchestration Template's second level Nested YAML file
 175     **MUST NOT** contain an ``OS::Nova::Server`` resource.
 176
 177 Nested Heat Template Example: Static
 178 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 179
 180 incremental.yaml
 181
 182 .. code-block:: yaml
 183
 184  Resources:
 185    dns_server_0:
 186      type: nested.yaml
 187      properties:
 188        dns_image_name: { get_param: dns_image_name }
 189        dns_flavor_name: { get_param: dns_flavor_name }
 190        availability_zone: { get_param: availability_zone_0 }
 191        security_group: { get_param: DNS_shared_sec_grp_id }
 192        oam_net_id: { get_param: oam_protected_net_id }
 193        dns_oam_ip: { get_param: dns_oam_ip_0 }
 194        dns_name: { get_param: dns_name_0 }
 195        vnf_name: { get_param: vnf_name }
 196        vnf_id: { get_param: vnf_id }
 197        vf_module_id: {get_param: vf_module_id}
 198
 199  dns_server_1:
 200    type: nested.yaml
 201    properties:
 202      dns_image_name: { get_param: dns_image_name }
 203      dns_flavor_name: { get_param: dns_flavor_name }
 204      availability_zone: { get_param: availability_zone_1 }
 205      security_group: { get_param: DNS_shared_sec_grp_id }
 206      oam_net_id: { get_param: oam_protected_net_id }
 207      dns_oam_ip: { get_param: dns_oam_ip_1 }
 208      dns_name: { get_param: dns_name_1 }
 209      vnf_name: { get_param: vnf_name }
 210      vnf_id: { get_param: vnf_id }
 211      vf_module_id: {get_param: vf_module_id}
 212
 213 nested.yaml
 214
 215 .. code-block:: yaml
 216
 217  dns_oam_0_port:
 218    type: OS::Neutron::Port
 219    properties:
 220      name:
 221        str_replace:
 222          template: VNF_NAME_dns_oam_port
 223          params:
 224            VNF_NAME: {get_param: vnf_name}
 225      network: { get_param: oam_net_id }
 226      fixed_ips: [{ "ip_address": { get_param: dns_oam_ip }}]
 227      security_groups: [{ get_param: security_group }]
 228
 229  dns_servers:
 230    type: OS::Nova::Server
 231    properties:
 232      name: { get_param: dns_names }
 233      image: { get_param: dns_image_name }
 234      flavor: { get_param: dns_flavor_name }
 235      availability_zone: { get_param: availability_zone }
 236      networks:
 237        - port: { get_resource: dns_oam_0_port }
 238      metadata:
 239        vnf_id: { get_param: vnf_id }
 240        vf_module_id: { get_param: vf_module_id }
 241        vnf_name {get_param: vnf_name }
 242
 243 Use of Heat ResourceGroup
 244 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 245
 246 The OS::Heat::ResourceGroup is a useful Heat element for creating
 247 multiple instances of a given resource or collection of resources.
 248 Typically, it is used with a nested Heat template, to create, for
 249 example, a set of identical OS::Nova::Server resources plus their
 250 related OS::Neutron::Port resources via a single resource in a master
 251 template.
 252
 253 OS::Heat::ResourceGroup may be used to simplify the structure of a Heat
 254 template that creates multiple instances of the same VM type.
 255
 256 However, there are important caveats to be aware of:
 257
 258 OS::Heat::ResourceGroup does not deal with structured parameters
 259 (comma-delimited-list and json) as one might typically expect. In
 260 particular, when using a list-based parameter, where each list element
 261 corresponds to one instance of the ResourceGroup, it is not possible to
 262 use the intrinsic "loop variable" %index% in the OS::Heat::ResourceGroup
 263 definition.
 264
 265 For instance, the following is **not** valid Heat for
 266 OS::Heat::ResourceGroup:
 267
 268 .. code-block:: yaml
 269
 270  type: OS::Heat::ResourceGroup
 271    resource_def:
 272      type: my_nested_vm_template.yaml
 273      properties:
 274        name: {get_param: [vm_name_list, "%index%"]}
 275
 276 Although this appears to use the nth entry of the vm_name_list list for
 277 the nth element of the OS::Heat::ResourceGroup, it will in fact result
 278 in a Heat exception. When parameters are provided as a list (one for
 279 each element of a OS::Heat::ResourceGroup), you must pass the complete
 280 parameter to the nested template along with the current index as
 281 separate parameters.
 282
 283 Below is an example of an **acceptable** Heat Syntax for a
 284 ResourceGroup:
 285
 286 .. code-block:: yaml
 287
 288  type: OS::Heat::ResourceGroup
 289    resource_def:
 290      type: my_nested_vm_template.yaml
 291      properties:
 292        names: {get_param: vm_name_list}
 293        index: "%index%"
 294
 295 You can then reference within the nested template as:
 296
 297 { get\_param: [names, {get\_param: index} ] }
 298
 299 OS::Heat::ResourceGroup Property count
 300 ++++++++++++++++++++++++++++++++++++++++
 301
 302
 303 .. req::
 304     :id: R-50011
 305     :target: VNF
 306     :keyword: MUST
 307
 308     A VNF's Heat Orchestration Template's 'OS::Heat::ResourceGroup'
 309     property 'count' **MUST** be enumerated in the VNF's
 310     Heat Orchestration Template's Environment File and **MUST** be
 311     assigned a value.
 312
 313 This is required for ONAP to build the TOSCA model for the VNF.
 314
 315 .. code-block:: yaml
 316
 317  type: OS::Heat::ResourceGroup
 318  properties:
 319    count: { get_param: count }
 320    index_var: index
 321    resource_def:
 322      type: my_nested_vm_template.yaml
 323      properties:
 324        names: {get_param: vm_name_list}
 325        index: index
 326
 327 Availability Zone and ResourceGroups
 328 ++++++++++++++++++++++++++++++++++++++++
 329
 330 The resource OS::Heat::ResourceGroup and the property availability\_zone
 331 has been an "issue" with a few VNFs since ONAP only supports
 332 availability\_zone as a string parameter and not a
 333 comma\_delimited\_list. This makes it difficult to use a
 334 OS::Heat::ResourceGroup to create Virtual Machines in more
 335 than one availability zone.
 336
 337 There are numerous solutions to this issue. Below are two suggested
 338 usage patterns.
 339
 340 **Option 1:** create a CDL in the OS::Heat::ResourceGroup. In the
 341 resource type: OS::Heat::ResourceGroup, create a comma\_delimited\_list
 342 availability\_zones by using the intrinsic function list\_join.
 343
 344 .. code-block:: yaml
 345
 346  <resource name>:
 347   type: OS::Heat::ResourceGroup
 348   properties:
 349     count: { get_param: node_count }
 350     index_var: index
 351     resource_def:
 352       type: nested.yaml
 353       properties:
 354         index: index
 355         avaialability_zones: { list_join: [',', [ { get_param: availability_zone_0 }, { get_param: availability_zone_1 } ] ] }
 356
 357 In the nested heat
 358
 359 .. code-block:: yaml
 360
 361  parameters:
 362    avaialability_zones:
 363      type: comma_delimited_list
 364      description:
 365
 366  resources:
 367    servers:
 368      type: OS::Nova::Server
 369      properties:
 370        name: { get_param: [ dns_names, get_param: index ] }
 371        image: { get_param: dns_image_name }
 372        flavor: { get_param: dns_flavor_name }
 373        availability_zone: { get_param: [ avaialability_zones, get_param: index ] }
 374
 375 **Option 2:** Create a CDL by passing the availability zone parameter
 376 into a nested heat template. An example is provided below.
 377
 378 base.yaml
 379
 380 .. code-block:: yaml
 381
 382   availability_zone_list:
 383      type: az_list_generate.yaml
 384      properties:
 385        availability_zone_0: { get_param: availability_zone_0 }
 386        availability_zone_1: { get_param: availability_zone_1 }
 387
 388     create_virtual_machines:
 389       type: OS::Heat::ResourceGroup
 390       properties:
 391         count: { get_param: count }
 392         index_var: $INDEX
 393         resource_def:
 394           type: nest_file.yaml
 395           properties:
 396             index: $INDEX
 397             availability_zone_0 : { get_attr: [availability_zone_list, general_zones ] }
 398             . . .
 399
 400 az_list_generate.yaml
 401
 402 .. code-block:: yaml
 403
 404   parameters:
 405     availability_zone_0:
 406       type: string
 407       description: availability zone 0
 408
 409     availability_zone_1:
 410       type: string
 411       description: availability zone 1
 412
 413   outputs:
 414
 415     general_zones:
 416       value: [
 417         { get_param: availability_zone_0 },
 418         { get_param: availability_zone_1 },
 419         { get_param: availability_zone_0 },
 420         { get_param: availability_zone_1 },
 421         { get_param: availability_zone_0 },
 422         { get_param: availability_zone_1 },
 423   ]
 424
 425
 426 Nested Heat Template Example: OS::Heat::ResourceGroup
 427 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 428
 429 In this example, ocgapp\_volume.yml creates volumes using a
 430 OS::Heat::ResourceGroup that uses nested heat by calling
 431 ocgapp_nested_volume.yml. ocgapp\_volume.yml has an outputs: parameter
 432 ocgapp\_volume\_ids which is declared a input parameter of type: json in
 433 ocgapp\_volume.yml.
 434
 435
 436 This is an example of requirement :need:`R-07443`, where
 437 a VNF's Heat Orchestration Templates' Cinder Volume Module Output
 438 Parameter's name and type **MUST** match the input parameter name and type
 439 in the corresponding Base Module or Incremental Module unless the Output
 440 Parameter is of the type 'comma\_delimited\_list', then the corresponding
 441 input parameter **MUST** be declared as type 'json'.
 442
 443 ocgapp\_volume.yml
 444
 445 .. code-block:: yaml
 446
 447   heat_template_version: 2014-10-16
 448
 449   description: Template for the volumes
 450
 451   parameters:
 452     vnf_name:
 453       type: string
 454       label: OCG VNF Name
 455       description: OCG VNF Name
 456     ocgapp_volume_size_0:
 457       type: number
 458       label: Cinder volume 1 size
 459       description: the size of the Cinder volume
 460       constraints:
 461       - range: { min: 100, max: 400 }
 462     ocgapp_volume_type_0:
 463       type: string
 464       label: app vm 1 volume type
 465       description: the name of the target volume backend for the first OCG APP
 466     volume_count:
 467       type: number
 468       label: volume count
 469       description: number of volumes needed
 470
 471   resources:
 472     ocgapp_volume_resource_group:
 473       type: OS::Heat::ResourceGroup
 474       properties:
 475         count: {get_param: volume_count}
 476         index_var: index
 477         resource_def:
 478           type: ocgapp_nested_volume.yml
 479           properties:
 480             index: index
 481             size: {get_param: ocgapp_volume_size_0}
 482             volume_type: {get_param: ocgapp_volume_type_0}
 483             vnf_name: {get_param: vnf_name}
 484
 485   outputs:
 486     ocgapp_volume_ids:
 487     description: ocgapp volume ids
 488     value: {get_attr: [ocgapp_volume_resource_group, ocgapp_volume_id_0]}
 489
 490 ocgapp_nested_volume.yml
 491
 492 .. code-block:: yaml
 493
 494  heat_template_version: 2014-10-16
 495
 496  description: nested heat
 497
 498  parameters:
 499    index:
 500      type: number
 501      label: Volume Index
 502      description: number of volumes to spin up
 503    size:
 504      type: number
 505      label: Volume Size
 506      description: size of the cinder volumes
 507    volume_type:
 508      type: string
 509      label: Volume Type
 510      description: type of cinder volumes
 511    vnf_name:
 512      type: string
 513      label: VNF Name
 514      description: vnf name
 515
 516  resources:
 517    ocgapp_volume_0:
 518      type: OS::Cinder::Volume
 519      properties:
 520        size: {get_param: size}
 521        volume_type: {get_param: volume_type}
 522        name:
 523          str_replace:
 524            template: VF_NAME_STACK_NAME_INDEX
 525            params:
 526              VF_NAME: { get_param: vnf_name }
 527              STACK_NAME: { get_param: 'OS::stack_name' }
 528              INDEX: {get_param: index}
 529
 530  outputs:
 531    ocgapp_volume_id_0:
 532    description: the ocgapp volume uuid
 533    value: {get_resource: ocgapp_volume_0}
 534
 535 The heat template below is a partial heat template,
 536
 537 ocgapp.yml
 538
 539 .. code-block:: yaml
 540
 541   heat_template_version: 2014-10-16
 542
 543   #file version 1.0
 544   description: OCG Apps template
 545
 546   parameters:
 547     ocgapp_volume_ids:
 548       type: json
 549       description: Unique IDs for volumes
 550
 551   resources:
 552     ocgapp_server_0:
 553       type: OS::Nova::Server
 554       properties:
 555     . . . .
 556     ocgapp_server_1:
 557       type: OS::Nova::Server
 558       properties:
 559     . . . .
 560     ocgapp_volume_attachment_0:
 561       type: OS::Cinder::VolumeAttachment
 562       properties:
 563         volume_id: {get_param: [ocgapp_volume_ids, 0]}
 564         instance_uuid: {get_resource: ocgapp_server_0}
 565     ocgapp_volume_attachment_1:
 566       type: OS::Cinder::VolumeAttachment
 567       properties:
 568         volume_id: {get_param: [ocgapp_volume_ids, 1]}
 569         instance_uuid: {get_resource: ocgapp_server_1}
 570
 571 External References
 572 ^^^^^^^^^^^^^^^^^^^^^^
 573
 574 Heat templates *should not* reference any HTTP-based resource
 575 definitions, any HTTP-based nested configurations, or any HTTP-based
 576 environment files.
 577
 578 -  During orchestration, ONAP *should not* retrieve any such resources
 579    from external/untrusted/unknown sources.
 580
 581 -  VNF images should not contain such references in user-data or other
 582    configuration/operational scripts that are specified via Heat or
 583    encoded into the VNF image itself.
 584
 585 *Note:* HTTP-based references are acceptable if the HTTP-based reference
 586 is accessing information with the VM private/internal network.
 587
 588 Note that Namespaces in XML (defined at
 589 http://www.w3.org/TR/2009/REC-xml-names-20091208/) are allowed if the
 590 Heat Orchestration Template is describing and storing software
 591 configuration information. An XML namespace is identified by a URI
 592 reference. A Uniform Resource Identifier (URI) is a string of characters
 593 which identifies an Internet Resource. The most common URI is the
 594 Uniform Resource Locator (URL) which identifies an Internet domain
 595 address. Another, not so common type of URI is the Universal Resource
 596 Name (URN). The namespace URI is not used by XML the parser to look up
 597 information. The purpose of using an URI is to give the namespace a
 598 unique name.
 599
 600 Heat Files Support (get\_file)
 601 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 602
 603 Heat Templates may contain the inclusion of text files into Heat
 604 templates via the Heat get\_file directive. This may be used, for
 605 example, to define a common "user-data" script, or to inject files into
 606 a VM on startup via the "personality" property.
 607
 608 Support for Heat Files is subject to the following limitations:
 609
 610
 611 .. req::
 612     :id: R-76718
 613     :target: VNF
 614     :keyword: MUST
 615
 616     If a VNF's Heat Orchestration Template uses the intrinsic function
 617     'get\_file', the 'get\_file' target **MUST** be referenced in
 618     the Heat Orchestration Template by file name.
 619
 620 The 'get\_file' target files are on-boarded to SDC in the same package
 621 that contains the VNF's complete Heat Orchestration Template.
 622
 623
 624 .. req::
 625     :id: R-41888
 626     :target: VNF
 627     :keyword: MUST NOT
 628
 629     A VNF's Heat Orchestration Template intrinsic function
 630     'get\_file' **MUST NOT** utilize URL-based file retrieval.
 631
 632 .. req::
 633     :id: R-62177
 634     :target: VNF
 635     :keyword: MUST
 636
 637     When using the intrinsic function get_file, the included files
 638     **MUST** have unique file names within the scope of the VNF.
 639
 640 .. req::
 641     :id: R-87848
 642     :target: VNF
 643     :keyword: MUST
 644
 645     A VNF's Heat Orchestration Template's 'get\_file' target files
 646     **MUST** be in the same directory hierarchy as the VNF's Heat
 647     Orchestration Templates.
 648
 649 ONAP does not support a hierarchical structure.  A VNF's YAML files
 650 must be in a single, flat directory.
 651
 652
 653 .. req::
 654     :id: R-05050
 655     :target: VNF
 656     :keyword: MAY
 657
 658     A VNF's Heat Orchestration Templates intrinsic function
 659     'get\_file' <content key> **MAY** be used:
 660
 661         * more than once in a VNF's Heat Orchestration Template
 662         * in two or more of a VNF's Heat Orchestration Templates
 663         * in a VNF's Heat Orchestration Templates nested YAML file
 664
 665 Key Pairs
 666 ^^^^^^^^^^
 667
 668 When Nova Servers are created via Heat templates, they may be passed a
 669 "keypair" which provides an ssh key to the 'root' login on the newly
 670 created VM. This is often done so that an initial root key/password does
 671 not need to be hard-coded into the image.
 672
 673 Key pairs are unusual in OpenStack, because they are the one resource
 674 that is owned by an OpenStack User as opposed to being owned by an
 675 OpenStack Tenant. As a result, they are usable only by the User that
 676 created the keypair. This causes a problem when a Heat template attempts
 677 to reference a keypair by name, because it assumes that the keypair was
 678 previously created by a specific ONAP user ID.
 679
 680 When a keypair is assigned to a server, the SSH public-key is
 681 provisioned on the VMs at instantiation time. They keypair itself is not
 682 referenced further by the VM (i.e. if the keypair is updated with a new
 683 public key, it would only apply to subsequent VMs created with that
 684 keypair).
 685
 686 Due to this behavior, the recommended usage of keypairs is in a more
 687 generic manner which does not require the pre-requisite creation of a
 688 keypair. The Heat should be structured in such a way as to:
 689
 690 -  Pass a public key as a parameter value instead of a keypair name
 691
 692 -  Create a new keypair within The VNF Heat Orchestration Template (in the
 693    base module) based on an existing public key for use within that VNF
 694
 695 By following this approach, the end result is the same as pre-creating
 696 the keypair using the public key – i.e., that public key will be
 697 provisioned in the new VM. However, this recommended approach also makes
 698 sure that a known public key is supplied (instead of having OpenStack
 699 generate a public/private pair to be saved and tracked outside of ONAP).
 700 It also removes any access/ownership issues over the created keypair.
 701
 702 The public keys may be enumerated as a VNF Orchestration Constant in the
 703 environment file (since it is public, it is not a secret key), or passed
 704 at run-time as instance-specific parameters. ONAP will never
 705 automatically assign a public/private key pair.
 706
 707 *Example (create keypair with an existing ssh public-key for {vm-type}
 708 of lb (for load balancer)):*
 709
 710 .. code-block:: yaml
 711
 712  parameters:
 713     vnf_name:
 714        type: string
 715     lb_ssh_public_key:
 716        type: string
 717
 718  resources:
 719     my_keypair:
 720        type: OS::Nova::Keypair
 721        properties:
 722           name:
 723              str_replace:
 724                 template: VNF_NAME_key_pair
 725                 params:
 726                 VNF_NAME: { get_param: vnf_name }
 727           public_key: {get_param: lb_ssh_public_key}
 728           save_private_key: false
 729
 730 Security Groups
 731 ^^^^^^^^^^^^^^^^^
 732
 733 OpenStack allows a tenant to create Security groups and define rules
 734 within the security groups.
 735
 736 Security groups, with their rules, may either be created in the Heat
 737 Orchestration Template or they can be pre-created in OpenStack and
 738 referenced within the Heat template via parameter(s). There can be a
 739 different approach for security groups assigned to ports on internal
 740 (intra-VNF) networks or external networks (inter-VNF). Furthermore,
 741 there can be a common security group across all VMs for a specific
 742 network or it can vary by VM (i.e., {vm-type}) and network type (i.e.,
 743 {network-role}).
 744
 745 Anti-Affinity and Affinity Rules
 746 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 747
 748 Anti-affinity or affinity rules are supported using normal OpenStack
 749 OS::Nova::ServerGroup resources. Separate ServerGroups are typically
 750 created for each VM type to prevent them from residing on the same host,
 751 but they can be applied to multiple VM types to extend the
 752 affinity/anti-affinity across related VM types as well.
 753
 754 *Example:*
 755
 756 In this example, the {network-role} has been defined as oam to represent
 757 an oam network and the {vm-type} have been defined as lb for load
 758 balancer and db for database.
 759
 760 .. code-block:: yaml
 761
 762  resources:
 763  db_server_group:
 764     type: OS::Nova::ServerGroup
 765     properties:
 766        name:
 767           str_replace:
 768              params:
 769                 $vnf_name: {get_param: vnf_name}
 770              template: $vnf_name-server_group1
 771        policies:
 772           - anti-affinity
 773
 774  lb_server_group:
 775     type: OS::Nova::ServerGroup
 776     properties:
 777        name:
 778           str_replace:
 779              params:
 780                 $vnf_name: {get_param: vnf_name}
 781              template: $vnf_name-server_group2
 782        policies:
 783           - affinity
 784
 785  db_0:
 786     type: OS::Nova::Server
 787     properties:
 788     ...
 789     scheduler_hints:
 790        group: {get_resource: db_server_group}
 791
 792  db_1:
 793     type: OS::Nova::Server
 794     properties:
 795     ...
 796     scheduler_hints:
 797        group: {get_resource: db_server_group}
 798
 799  lb_0:
 800     type: OS::Nova::Server
 801     properties:
 802     ...
 803     scheduler_hints:
 804        group: {get_resource: lb_server_group}
 805
 806 Resource Data Synchronization
 807 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 808
 809 For cases where synchronization is required in the orchestration of Heat
 810 resources, two approaches are recommended:
 811
 812 -  Standard Heat depends\_on property for resources
 813
 814    -  Assures that one resource completes before the dependent resource
 815       is orchestrated.
 816
 817    -  Definition of completeness to OpenStack may not be sufficient
 818       (e.g., a VM is considered complete by OpenStack when it is ready
 819       to be booted, not when the application is up and running).
 820
 821 -  Use of Heat Notifications
 822
 823    -  Create OS::Heat::WaitCondition and OS::Heat::WaitConditionHandle
 824       resources.
 825
 826    -  Pre-requisite resources issue *wc\_notify* commands in user\_data.
 827
 828    -  Dependent resource define depends\_on in the
 829       OS::Heat::WaitCondition resource.
 830
 831 *Example: "depends\_on" case*
 832
 833 In this example, the {network-role} has been defined as oam to represent
 834 an oam network and the {vm-type} has been defined as oam to represent an
 835 oam server.
 836
 837 .. code-block:: yaml
 838
 839  resources:
 840    oam_server_01:
 841      type: OS::Nova::Server
 842      properties:
 843        name: {get_param: [oam_ names, 0]}
 844        image: {get_param: oam_image_name}
 845        flavor: {get_param: oam_flavor_name}
 846        availability_zone: {get_param: availability_zone_0}
 847        networks:
 848          - port: {get_resource: oam01_port_0}
 849          - port: {get_resource: oam01_port_1}
 850        user_data:
 851        scheduler_hints: {group: {get_resource: oam_servergroup}}
 852        user_data_format: RAW
 853
 854  oam_01_port_0:
 855    type: OS::Neutron::Port
 856    properties:
 857      network: {get_resource: oam_net_name}
 858      fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 1]}}]
 859      security_groups: [{get_resource: oam_security_group}]
 860
 861  oam_01_port_1:
 862    type: OS::Neutron::Port
 863    properties:
 864      network: {get_param: oam_net_name}
 865      fixed_ips: [{"ip_address": {get_param: [oam_oam_net_ips, 2]}}]
 866      security_groups: [{get_resource: oam_security_group}]
 867
 868  oam_01_vol_attachment:
 869    type: OS::Cinder::VolumeAttachment
 870    depends_on: oam_server_01
 871    properties:
 872      volume_id: {get_param: oam_vol_1}
 873      mountpoint: /dev/vdb
 874      instance_uuid: {get_resource: oam_server_01}
 875
 876