docs/Chapter5/Heat/ONAP Heat Resource ID and Parameter Naming Convention/Nova Parameters.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
   6 Resource: OS::Nova::Server - Parameters
   7 -----------------------------------------------------------------------
   8
   9 The OS::Nova::Server resource manages the running virtual machine (VM)
  10 instance within an OpenStack cloud. (See
  11 https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Nova::Server.)
  12
  13 The following four properties of the ``OS::Nova::Server``
  14 resource must follow an
  15 ONAP specified naming convention.
  16
  17 1. ``image``
  18
  19 2. ``flavor``
  20
  21 3. ``name``
  22
  23 4. ``availability_zone``
  24
  25 Requirement R-01455 defines how the ``{vm-type]`` is defined.
  26
  27 Requirement R-82481 defines how the ``{vm-type}`` is used.
  28
  29 .. req::
  30     :id: R-304011
  31     :target: VNF
  32     :keyword: MUST
  33     :validation_mode: static
  34     :introduced: casablanca
  35
  36     A VNF's Heat Orchestration Template's ``OS::Nova::Server`` resource's
  37
  38     * Resource ID
  39     * property ``image`` parameter name
  40     * property ``flavor`` parameter name
  41     * property ``name`` parameter name
  42
  43
  44     **MUST** contain the identical ``{vm-type}``
  45     and **MUST** follow the naming conventions defined
  46     in R-58670, R-45188, R-54171, R-87817, and R-29751.
  47
  48 The table below provides a summary. The sections that follow provides
  49 the detailed requirements.
  50
  51 .. csv-table:: **Table 1 OS::Nova::Server Resource Property Parameter Naming Convention**
  52    :header: Resource,Property,Parameter Type,Parameter Name,Parameter Value Provided to Heat
  53    :align: center
  54    :widths: auto
  55
  56    OS::Nova::Server, image, string, {vm-type}_image_name, Environment File
  57    OS::Nova::Server, flavor, string, {vm-type}_flavor_name, Environment File
  58    OS::Nova::Server, name, string, {vm-type}_name_{index}, ONAP
  59    OS::Nova::Server, name, CDL, {vm-type}_names, ONAP
  60    OS::Nova::Server, availability_zone, string, availability_zone_{index}, ONAP
  61
  62 .. _Property image:
  63
  64 Property: image
  65 ^^^^^^^^^^^^^^^
  66
  67
  68 .. req::
  69     :id: R-901331
  70     :target: VNF
  71     :keyword: MUST
  72     :validation_mode: static
  73     :introduced: casablanca
  74
  75     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
  76     property ``image`` value **MUST** be be obtained via a ``get_param``.
  77
  78 .. req::
  79     :id: R-71152
  80     :target: VNF
  81     :keyword: MUST
  82     :validation_mode: static
  83     :updated: casablanca
  84
  85     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
  86     property
  87     ``image`` parameter **MUST** be declared as type: ``string``.
  88
  89 .. req::
  90     :id: R-58670
  91     :target: VNF
  92     :keyword: MUST
  93     :validation_mode: static
  94     :updated: casablanca
  95
  96     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
  97     property
  98     ``image`` parameter name **MUST** follow the naming convention
  99     ``{vm-type}_image_name``.
 100
 101 .. req::
 102     :id: R-91125
 103     :target: VNF
 104     :keyword: MUST
 105     :validation_mode: static
 106     :updated: casablanca
 107
 108     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 109     property
 110     ``image`` parameter **MUST** be enumerated in the Heat Orchestration
 111     Template's Environment File and a value **MUST** be assigned.
 112
 113 .. req::
 114     :id: R-57282
 115     :target: VNF
 116     :keyword: MUST
 117     :validation_mode: static
 118     :updated: casablanca
 119
 120     Each VNF's Heat Orchestration Template's ``{vm-type}`` **MUST**
 121     have a unique parameter name for the ``OS::Nova::Server`` property
 122     ``image`` even if more than one ``{vm-type}`` shares the same image.
 123
 124 *Example Parameter Definition*
 125
 126 .. code-block:: yaml
 127
 128  parameters:
 129      {vm-type}_image_name:
 130          type: string
 131          description: {vm-type} server image
 132
 133 .. _Property flavor:
 134
 135 Property: flavor
 136 ^^^^^^^^^^^^^^^^^^
 137
 138
 139 .. req::
 140     :id: R-481670
 141     :target: VNF
 142     :keyword: MUST
 143     :validation_mode: static
 144     :introduced: casablanca
 145
 146     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 147     property ``flavor`` value **MUST** be be obtained via a ``get_param``.
 148
 149 .. req::
 150     :id: R-50436
 151     :target: VNF
 152     :keyword: MUST
 153     :validation_mode: static
 154     :updated: casablanca
 155
 156     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 157     property
 158     ``flavor`` parameter **MUST** be declared as type: ``string``.
 159
 160 .. req::
 161     :id: R-45188
 162     :target: VNF
 163     :keyword: MUST
 164     :validation_mode: static
 165     :updated: casablanca
 166
 167     The VNF's Heat Orchestration Template's Resource 'OS::Nova::Server' property
 168     ``flavor`` parameter name **MUST** follow the naming convention
 169     ``{vm-type}_flavor_name``.
 170
 171 .. req::
 172     :id: R-69431
 173     :target: VNF
 174     :keyword: MUST
 175     :validation_mode: static
 176     :updated: casablanca
 177
 178     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 179     property
 180     ``flavor`` parameter **MUST** be enumerated in the Heat Orchestration
 181     Template's Environment File and a value **MUST** be assigned.
 182
 183 .. req::
 184     :id: R-40499
 185     :target: VNF
 186     :keyword: MUST
 187     :validation_mode: static
 188     :updated: casablanca
 189
 190     Each VNF's Heat Orchestration Template's ``{vm-type}`` **MUST**
 191     have a unique parameter name for the ``OS::Nova::Server`` property
 192     ``flavor`` even if more than one ``{vm-type}`` shares the same flavor.
 193
 194 *Example Parameter Definition*
 195
 196 .. code-block:: yaml
 197
 198  parameters:
 199      {vm-type}_flavor_name:
 200          type: string
 201          description: {vm-type} flavor
 202
 203 Property: Name
 204 ^^^^^^^^^^^^^^^^^
 205
 206
 207 .. req::
 208     :id: R-663631
 209     :target: VNF
 210     :keyword: MUST
 211     :validation_mode: static
 212     :introduced: casablanca
 213
 214     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 215     property ``name`` value **MUST** be be obtained via a ``get_param``.
 216
 217 .. req::
 218     :id: R-51430
 219     :target: VNF
 220     :keyword: MUST
 221     :validation_mode: static
 222     :updated: casablanca
 223
 224     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 225     property
 226     ``name`` parameter **MUST** be declared as either type ``string``
 227     or type ``comma_delimited_list``.
 228
 229 .. req::
 230     :id: R-54171
 231     :target: VNF
 232     :keyword: MUST
 233     :validation_mode: static
 234     :updated: casablanca
 235
 236     When the VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 237     property ``name`` parameter is defined as a ``string``,
 238     the parameter name **MUST** follow the naming convention
 239     ``{vm-type}_name_{index}``, where ``{index}`` is a numeric
 240     value that starts at
 241     zero and increments by one.
 242
 243 .. req::
 244     :id: R-40899
 245     :target: VNF
 246     :keyword: MUST
 247     :validation_mode: static
 248     :updated: casablanca
 249
 250     When the VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 251     property ``name`` parameter is defined as a ``string``, a parameter
 252     **MUST** be delcared for
 253     each ``OS::Nova::Server`` resource associated with the ``{vm-type}``.
 254
 255 .. req::
 256     :id: R-87817
 257     :target: VNF
 258     :keyword: MUST
 259     :validation_mode: static
 260     :updated: casablanca
 261
 262     When the VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 263     property ``name`` parameter is defined as a ``comma_delimited_list``,
 264     the parameter name **MUST** follow the naming convention
 265     ``{vm-type}_names``.
 266
 267 .. req::
 268     :id: R-85800
 269     :target: VNF
 270     :keyword: MUST
 271     :validation_mode: static
 272     :updated: casablanca
 273
 274     When the VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 275     property ``name`` parameter is defined as a ``comma_delimited_list``,
 276     a parameter **MUST** be delcared once for all ``OS::Nova::Server`` resources
 277     associated with the ``{vm-type}``.
 278
 279 .. req::
 280     :id: R-22838
 281     :target: VNF
 282     :keyword: MUST NOT
 283     :validation_mode: static
 284     :updated: casablanca
 285
 286     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 287     property
 288     ``name`` parameter **MUST NOT** be enumerated in the Heat Orchestration
 289     Template's Environment File.
 290
 291 If a VNF's Heat Orchestration Template's contains more than three
 292 OS::Nova::Server resources of a given ``{vm-type}``, the comma_delimited_list
 293 form of the parameter name (i.e., ``{vm-type}_names``) should be used to
 294 minimize the number of unique parameters defined in the template.
 295
 296
 297 *Example: Parameter Definition*
 298
 299 .. code-block:: yaml
 300
 301   parameters:
 302
 303   {vm-type}_names:
 304     type: comma_delimited_list
 305     description: VM Names for {vm-type} VMs
 306
 307   {vm-type}_name_{index}:
 308     type: string
 309     description: VM Name for {vm-type} VM {index}
 310
 311 *Example: comma\_delimited\_list*
 312
 313 In this example, the {vm-type} has been defined as "lb" for load balancer.
 314
 315 .. code-block:: yaml
 316
 317   parameters:
 318
 319     lb_names:
 320       type: comma_delimited_list
 321       description: VM Names for lb VMs
 322
 323   resources:
 324     lb_server_0:
 325       type: OS::Nova::Server
 326       properties:
 327         name: { get_param: [lb_names, 0] }
 328         ...
 329
 330     lb_server_1:
 331       type: OS::Nova::Server
 332       properties:
 333         name: { get_param: [lb_names, 1] }
 334         ...
 335
 336 *Example: fixed-index*
 337
 338 In this example, the {vm-type} has been defined as "lb" for load balancer.
 339
 340 .. code-block:: yaml
 341
 342   parameters:
 343
 344     lb_name_0:
 345       type: string
 346       description: VM Name for lb VM 0
 347
 348     lb_name_1:
 349       type: string
 350       description: VM Name for lb VM 1
 351
 352   resources:
 353
 354     lb_server_0:
 355       type: OS::Nova::Server
 356       properties:
 357         name: { get_param: lb_name_0 }
 358         ...
 359
 360     lb_server_1:
 361       type: OS::Nova::Server
 362       properties:
 363         name: { get_param: lb_name_1 }
 364         ...
 365
 366 Contrail Issue with Values for OS::Nova::Server Property Name
 367 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 368
 369
 370 .. req::
 371     :id: R-44271
 372     :target: VNF
 373     :keyword: SHOULD NOT
 374     :updated: casablanca
 375
 376     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 377     property
 378     ``name`` parameter value **SHOULD NOT** contain special characters
 379     since the Contrail GUI has a limitation displaying special characters.
 380
 381     However, if special characters must be used, the only special characters
 382     supported are: --- \" ! $ ' (\ \ ) = ~ ^ | @ ` { } [ ] > , . _
 383
 384
 385 Property: availability_zone
 386 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 387
 388
 389 .. req::
 390     :id: R-98450
 391     :target: VNF
 392     :keyword: MUST
 393     :validation_mode: static
 394     :updated: casablanca
 395
 396     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 397     property
 398     ``availability_zone`` parameter name **MUST** follow the naming convention
 399     ``availability_zone_{index}`` where the ``{index}``
 400     **MUST** start at zero and
 401     increment by one.
 402
 403 .. req::
 404     :id: R-23311
 405     :target: VNF
 406     :keyword: MUST
 407     :validation_mode: static
 408     :updated: casablanca
 409
 410     The VNF's Heat Orchestration Template's Resource
 411     ``OS::Nova::Server`` property
 412     ``availability_zone`` parameter **MUST** be declared as type: ``string``.
 413
 414 The parameter must not be declared as type ``comma_delimited_list``, ONAP does
 415 not support it.
 416
 417 .. req::
 418     :id: R-59568
 419     :target: VNF
 420     :keyword: MUST NOT
 421     :validation_mode: static
 422     :updated: casablanca
 423
 424     The VNF's Heat Orchestration Template's Resource ``OS::Nova::Server``
 425     property
 426     ``availability_zone`` parameter **MUST NOT** be enumerated in the Heat
 427     Orchestration
 428     Template's Environment File.
 429
 430 Example Parameter Definition
 431
 432 .. code-block:: yaml
 433
 434   parameters:
 435     availability_zone_{index}:
 436       type: string
 437       description: availability zone {index} name
 438
 439 Requirement :need:`R-90279` states that a VNF Heat Orchestration's template's
 440 parameter MUST be used in a resource with the exception of the parameters
 441 for the OS::Nova::Server resource property availability_zone.
 442
 443
 444 .. req::
 445     :id: R-01359
 446     :target: VNF
 447     :keyword: MAY
 448     :updated: casablanca
 449
 450     A VNF's Heat Orchestration Template that contains an ``OS::Nova:Server``
 451     Resource **MAY** define a parameter for the property
 452     ``availability_zone`` that is not utilized in any ``OS::Nova::Server``
 453     resources in the Heat Orchestration Template.
 454
 455 Example
 456 ^^^^^^^^^^^
 457
 458 The example below depicts part of a Heat Orchestration Template that
 459 uses the four ``OS::Nova::Server`` properties discussed in this section.
 460
 461 In the Heat Orchestration Template below, four Virtual Machines
 462 (``OS::Nova::Server``) are created: two dns servers with ``{vm-type}`` set to
 463 ``dns`` and two oam servers with ``{vm-type}`` set to ``oam``.
 464 Note that the parameter
 465 associated with the property name is a ``comma_delimited_list`` for ``dns`` and
 466 a string for ``oam``.
 467
 468 .. code-block:: yaml
 469
 470   parameters:
 471
 472     dns_image_name:
 473       type: string
 474       description: dns server image
 475
 476     dns_flavor_name:
 477       type: string
 478       description: dns server flavor
 479
 480     dns_names:
 481       type: comma_delimited_list
 482       description: dns server names
 483
 484     oam_image_name:
 485       type: string
 486       description: oam server image
 487
 488     oam_flavor_name:
 489       type: string
 490       description: oam server flavor
 491
 492     oam_name_0:
 493       type: string
 494       description: oam server name 0
 495
 496     oam_name_1:
 497       type: string
 498       description: oam server name 1
 499
 500     availability_zone_0:
 501       type: string
 502       description: availability zone ID or Name
 503
 504     availability_zone_1:
 505       type: string
 506       description: availability zone ID or Name
 507
 508   resources:
 509
 510     dns_server_0:
 511       type: OS::Nova::Server
 512       properties:
 513         name: { get_param: [ dns_names, 0 ] }
 514         image: { get_param: dns_image_name }
 515         flavor: { get_param: dns_flavor_name }
 516         availability_zone: { get_param: availability_zone_0 }
 517
 518   . . .
 519
 520       dns_server_1:
 521         type: OS::Nova::Server
 522         properties:
 523           name: { get_param: [ dns_names, 1 ] }
 524           image: { get_param: dns_image_name }
 525           flavor: { get_param: dns_flavor_name }
 526           availability_zone: { get_param: availability_zone_1 }
 527
 528   . . .
 529
 530       oam_server_0:
 531         type: OS::Nova::Server
 532         properties:
 533           name: { get_param: oam_name_0 }
 534           image: { get_param: oam_image_name }
 535           flavor: { get_param: oam_flavor_name }
 536           availability_zone: { get_param: availability_zone_0 }
 537
 538   . . .
 539
 540       oam_server_1:
 541         type: OS::Nova::Server
 542         properties:
 543           name: { get_param: oam_name_1 }
 544           image: { get_param: oam_image_name }
 545           flavor: { get_param: oam_flavor_name }
 546           availability_zone: { get_param: availability_zone_1 }
 547
 548   . . .
 549
 550 Boot Options
 551 ^^^^^^^^^^^^^^^
 552
 553
 554 .. req::
 555     :id: R-99798
 556     :target: VNF
 557     :keyword: MAY
 558     :updated: casablanca
 559
 560     A VNF's Heat Orchestration Template's Virtual Machine
 561     (i.e., ``OS::Nova::Server`` resource) **MAY** boot from an image or
 562     **MAY** boot from a Cinder Volume.
 563
 564 .. req::
 565     :id: R-83706
 566     :target: VNF
 567     :keyword: MUST
 568     :validation_mode: static
 569     :updated: casablanca
 570
 571     When a VNF's Heat Orchestration Template's Virtual Machine
 572     (i.e., ``OS::Nova::Server`` resource) boots from an image, the
 573     ``OS::Nova::Server`` resource property ``image`` **MUST** be used.
 574
 575 The requirements associated with
 576 the 'image' property are detailed in `Property: image`_
 577
 578
 579 .. req::
 580     :id: R-69588
 581     :target: VNF
 582     :keyword: MUST
 583     :validation_mode: static
 584     :updated: casablanca
 585
 586     When a VNF's Heat Orchestration Template's Virtual Machine
 587     (i.e., ``OS::Nova::Server`` Resource) boots from Cinder Volume, the
 588     ``OS::Nova::Server`` resource property
 589     ``block_device_mapping`` or ``block_device_mapping_v2``
 590     **MUST** be used.
 591
 592 There are currently no heat guidelines
 593 associated with these two properties:
 594 'block_device_mapping' and 'block_device_mapping_v2'.