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