docs/Chapter5/Heat/ONAP Heat Resource ID and Parameter Naming Convention/Neutron 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 Resource: OS::Neutron::Port - Parameters
   6 ----------------------------------------
   7
   8 The resource OS::Neutron::Port is for managing Neutron ports.
   9
  10 (See https://docs.openstack.org/developer/heat/template_guide/openstack.html#OS::Neutron::Port)
  11
  12 Introduction
  13 ^^^^^^^^^^^^^
  14
  15 Four properties of the resource ``OS::Neutron::Port`` must follow the ONAP
  16 naming convention. The four properties are:
  17
  18 1. network
  19 2. fixed_ips, ip_address
  20 3. fixed_ips, subnet
  21
  22  * Note that earlier versions of this document mentioned the property
  23    fixed_ips, subnet_id.  This property has been removed from the document
  24    since it has been deprecated.
  25    See https://github.com/openstack/heat/blob/stable/ocata/heat/engine/resources/openstack/neutron/port.py
  26
  27 4. allowed_address_pairs, ip_address
  28
  29 Below is a generic example. Note that for some parameters
  30 comma_delimited_list are supported in addition to String.
  31
  32 .. code-block:: yaml
  33
  34   resources:
  35
  36   ...
  37
  38   <resource ID>:
  39     type: OS::Neutron::Port
  40     properties:
  41       allowed_address_pairs: [{"ip_address": String, "mac_address": String}, {"ip_address": String, "mac_address": String}, ...]
  42       fixed_ips: [{"ip_address": String, "subnet": String}, {"ip_address": String, "subnet": String}, ...]
  43       network: String
  44
  45 The values associated with these properties may reference an ONAP external
  46 network or ONAP internal network. ONAP external networks and ONAP internal
  47 networks are defined in :ref:`ONAP Heat Networking`.
  48
  49 When the ``OS::Neutron::Port`` is attaching to an ONAP external network, all
  50 property values are parameters that are retrieved via the intrinsic
  51 function ``get_param``.
  52
  53 When the ``OS::Neutron::Port`` is attaching to an ONAP internal network, a
  54 property value maybe retrieved via the intrinsic
  55 function ``get_param``, ``get_resource``, or ``get_attr``.
  56
  57 This will be described in the forth coming sections.
  58
  59 Items to Note
  60 ~~~~~~~~~~~~~
  61
  62 A VNF **MAY** have one or more ports connected to a unique
  63 ONAP external network. All VNF ports connected to the unique ONAP external
  64 network **MUST** have cloud assigned IP addresses
  65 or **MUST** have ONAP SDN-C assigned IP addresses.
  66
  67 A VNF **MAY** have one or more ports connected to a unique ONAP
  68 internal network. All VNF ports connected to the unique ONAP internal
  69 network **MUST** have cloud assigned IP addresses
  70 or **MUST** have statically assigned IP addresses.
  71
  72 .. req::
  73     :id: R-45602
  74     :target: VNF
  75     :keyword: MUST NOT
  76     :validation_mode: none
  77     :updated: casablanca
  78
  79     If a VNF's Port is attached to a network (internal or external)
  80     and the port's IP addresses are cloud assigned by OpenStack's DHCP
  81     Service, the ``OS::Neutron::Port`` Resource's
  82
  83     * property ``fixed_ips`` map property ``ip_address`` **MUST NOT** be used
  84     * property ``fixed_ips`` map property ``subnet``
  85       **MAY** be used
  86
  87 .. req::
  88     :id: R-63956
  89     :target: VNF
  90     :keyword: MAY
  91     :updated: frankfurt
  92
  93     If the VNF's ports connected to a unique ONAP external network
  94     (per the ONAP definition, see Requirement R-57424 and R-16968)
  95     and the port's IP addresses are ONAP SDN-C assigned IP addresses,
  96     the IPv4 addresses **MAY** be from different subnets and the IPv6
  97     addresses **MAY** be from different subnets.
  98
  99 .. req::
 100     :id: R-48880
 101     :target: VNF
 102     :keyword: MUST
 103     :validation_mode: none
 104     :updated: frankfurt
 105
 106     If a VNF's Port is attached to an ONAP external network (per the ONAP
 107     definition, see Requirement R-57424 and R-16968) and the port's
 108     IP addresses are assigned by ONAP's SDN-Controller,
 109     the ``OS::Neutron::Port`` Resource's
 110
 111     * property ``fixed_ips`` map property ``ip_address`` **MUST** be used
 112     * property ``fixed_ips`` map property ``subnet``
 113       **MUST NOT** be used
 114
 115 .. req::
 116     :id: R-18001
 117     :target: VNF
 118     :keyword: MAY
 119     :updated: frankfurt
 120
 121     If the VNF's ports connected to a unique ONAP internal network
 122     (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666)
 123     and the port's IP addresses are statically assigned IP addresses,
 124     the IPv4 addresses **MAY** be from different subnets and the
 125     IPv6 addresses **MAY** be from different subnets.
 126
 127 .. req::
 128     :id: R-70964
 129     :target: VNF
 130     :keyword: MUST NOT
 131     :validation_mode: none
 132     :updated: frankfurt
 133
 134     If a VNF's Port is attached to an ONAP internal network
 135     (per the ONAP definition, see Requirements R-52425 and R-46461 and R-35666)
 136     and the port's
 137     IP addresses are statically assigned by the VNF's Heat Orchestration
 138     Template (i.e., enumerated in the Heat Orchestration Template's
 139     environment file), the ``OS::Neutron::Port`` Resource's
 140
 141     * property ``fixed_ips`` map property ``ip_address`` **MUST** be used
 142     * property ``fixed_ips`` map property ``subnet``
 143       **MUST NOT** be used
 144
 145 .. req::
 146     :id: R-681859
 147     :target: VNF
 148     :keyword: MUST
 149     :validation_mode: static
 150     :introduced: dublin
 151
 152     A VNF's Heat Orchestration Template's ``OS::Neutron::Port`` resource's
 153
 154     * Resource ID (defined in R-20453)
 155     * property ``network`` parameter name (defined in R-62983 and
 156       R-86182)
 157     * property ``fixed_ips``, map property ``ip_address`` parameter name
 158       (defined in R-40971, R-04697, R-71577, R-23503, R-78380, R-85235,
 159       R-27818, and R-29765)
 160     * property ``fixed_ips``, map property ``subnet`` parameter name
 161       (defined in R-62802, R-15287, R-84123, R-76160)
 162     * property ``allowed_address_pairs`` parameter name (defined in
 163       R-41492 and R-83418)
 164
 165     **MUST** contain the identical ``{network-role}``.
 166
 167 Property: network
 168 ^^^^^^^^^^^^^^^^^
 169
 170 The Resource ``OS::Neutron::Port`` property ``network`` determines what network
 171 the port is attached to.
 172
 173 .. req::
 174     :id: R-18008
 175     :target: VNF
 176     :keyword: MUST
 177     :validation_mode: static
 178     :updated: casablanca
 179
 180     The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port``
 181     property ``network`` parameter **MUST** be declared as type: ``string``.
 182
 183 .. req::
 184     :id: R-62983
 185     :target: VNF
 186     :keyword: MUST
 187     :validation_mode: static
 188     :updated: frankfurt
 189
 190     When the VNF's Heat Orchestration Template's Resource
 191     ``OS::Neutron::Port`` is attaching to an ONAP external network (per the
 192     ONAP definition, see Requirement R-57424 and R-16968), the
 193     ``network`` parameter name **MUST**
 194
 195       * follow the naming convention ``{network-role}_net_id`` if the Neutron
 196         network UUID value is used to reference the network
 197       * follow the naming convention ``{network-role}_net_name`` if the
 198         OpenStack network name is used to reference the network.
 199
 200     where ``{network-role}`` is the network-role of the ONAP external network
 201     and a ``get_param`` **MUST** be used as the intrinsic function.
 202
 203 .. req::
 204     :id: R-86182
 205     :target: VNF
 206     :keyword: MUST
 207     :validation_mode: static
 208     :updated: frankfurt
 209
 210     When the VNF's Heat Orchestration Template's Resource
 211     ``OS::Neutron::Port``
 212     is in an incremental module and
 213     is attaching to an ONAP internal network (per the
 214     ONAP definition, see Requirements R-52425 and R-46461 and R-35666),
 215     the ``network`` parameter name **MUST**
 216
 217       * follow the naming convention ``int_{network-role}_net_id`` if the
 218         network UUID value is used to reference the network
 219       * follow the naming convention ``int_{network-role}_net_name`` if the
 220         network name in is used to reference the network.
 221
 222     where ``{network-role}`` is the network-role of the ONAP internal network
 223     and a ``get_param`` **MUST** be used as the intrinsic function.
 224
 225
 226 In Requirement R-86182, the ONAP internal network is created in the VNF's
 227 Base Module (Heat Orchestration Template) and the parameter name is
 228 declared in the Base Module's ``outputs`` section.
 229 The output parameter name will be declared as a parameter in the
 230 ``parameters`` section of the incremental module (See Requirement R-22688).
 231
 232
 233 When the VNF's Heat Orchestration Template's resource
 234 ``OS::Neutron::Port`` is in the base module and
 235 is attaching to an ONAP internal network (per the
 236 ONAP definition, see Requirements R-52425 and R-46461 and R-35666),
 237 and the ONAP internal network is
 238
 239  * created in the base module,
 240    the ``network`` property value can obtain the UUID
 241    of the internal network by using the intrinsic function
 242    ``get_resource`` and referencing the Resource ID of the internal network.
 243  * created in the base module by invoking a Nested YAML file, the network
 244    property value can obtain the UUID of the internal network by using the
 245    intrinsic function get_attr and referencing the Resource ID of the internal
 246    network.
 247
 248
 249 .. req::
 250     :id: R-29872
 251     :target: VNF
 252     :keyword: MUST NOT
 253     :validation_mode: static
 254     :updated: casablanca
 255
 256     The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port``
 257     property ``network``
 258     parameter **MUST NOT** be enumerated in the Heat Orchestration
 259     Template's Environment File.
 260
 261 The parameter values for ONAP external networks are provided by ONAP
 262 to the VNF's Heat Orchestration Template at orchestration time.
 263
 264 The parameter values for ONAP internal networks created in the VNF's Base Module
 265 Heat Orchestration Template
 266 are provided to the VNF's Incremental Module Heat Orchestration Template
 267 at orchestration time.
 268
 269 *Example Parameter Definition of External Networks*
 270
 271 .. code-block:: yaml
 272
 273   parameters:
 274
 275     {network-role}_net_id:
 276       type: string
 277       description: Neutron UUID for the external {network-role} network
 278
 279     {network-role}_net_name:
 280       type: string
 281       description: Neutron name for the external {network-role} network
 282
 283
 284
 285 *Example Parameter Definition of Internal Networks in an Incremental Module*
 286
 287 .. code-block:: yaml
 288
 289   parameters:
 290
 291     int_{network-role}_net_id:
 292       type: string
 293       description: Neutron UUID for the internal int_{network-role} network
 294
 295     int_{network-role}_net_name:
 296       type: string
 297       description: Neutron name for the internal int_{network-role} network
 298
 299 Property: fixed_ips, Map Property: ip_address
 300 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 301
 302 The resource ``OS::Neutron::Port`` property ``fixed_ips``
 303 map property ``ip_address``
 304 is used to assign one IPv4 or IPv6
 305 addresses to port.
 306
 307 One ``OS::Neutron::Port`` resource may assign one or more
 308 IPv4 and/or IPv6 addresses.
 309
 310 .. req::
 311     :id: R-34037
 312     :target: VNF
 313     :keyword: MUST
 314     :validation_mode: static
 315     :updated: casablanca
 316
 317     The VNF's Heat Orchestration Template's
 318     resource ``OS::Neutron::Port`` property ``fixed_ips``
 319     map property ``ip_address`` parameter
 320     **MUST** be declared as either type ``string`` or type
 321     ``comma_delimited_list``.
 322
 323 .. req::
 324     :id: R-40971
 325     :target: VNF
 326     :keyword: MUST
 327     :validation_mode: static
 328     :updated: frankfurt
 329
 330     When the VNF's Heat Orchestration Template's Resource
 331     ``OS::Neutron::Port`` is attaching to an ONAP external network (per the
 332     ONAP definition, see Requirement R-57424 and R-16968),
 333     and an IPv4 address is assigned
 334     using the property ``fixed_ips``
 335     map property ``ip_address`` and the parameter type is defined as a string,
 336     the parameter name **MUST** follow the
 337     naming convention
 338
 339     * ``{vm-type}_{network-role}_ip_{index}``
 340
 341     where
 342
 343     * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server``
 344     * ``{network-role}`` is the {network-role} of the ONAP external network
 345     * ``{index}`` is a numeric value that **MUST** start at zero in a
 346       VNF's Heat Orchestration Template and **MUST** increment by one
 347
 348 .. req::
 349     :id: R-39841
 350     :target: VNF
 351     :keyword: MUST NOT
 352     :validation_mode: static
 353     :updated: casablanca
 354
 355     The VNF's Heat Orchestration Template's Resource
 356     ``OS::Neutron::Port`` property ``fixed_ips``
 357     map property ``ip_address`` parameter
 358     ``{vm-type}_{network-role}_ip_{index}``
 359     **MUST NOT** be enumerated in the
 360     VNF's Heat Orchestration Template's Environment File.
 361
 362 ONAP's SDN-Controller assigns the IP address and ONAP provides
 363 the value at orchestration to the Heat Orchestration Template.
 364
 365 *Example External Network IPv4 Address string Parameter Definition*
 366
 367 .. code-block:: yaml
 368
 369   parameters:
 370
 371     {vm-type}_{network-role}_ip_{index}:
 372       type: string
 373       description: Fixed IPv4 assignment for {vm-type} VM {index} on the {network-role} network
 374
 375 .. req::
 376     :id: R-04697
 377     :target: VNF
 378     :keyword: MUST
 379     :validation_mode: static
 380     :updated: frankfurt
 381
 382     When the VNF's Heat Orchestration Template's Resource
 383     ``OS::Neutron::Port`` is attaching to an ONAP external network (per the
 384     ONAP definition, see Requirement R-57424 and R-16968),
 385     and an IPv4 address is assigned
 386     using the property ``fixed_ips``
 387     map property ``ip_address`` and the parameter type is defined as a
 388     ``comma_delimited_list``,
 389     the parameter name **MUST** follow the
 390     naming convention
 391
 392       * ``{vm-type}_{network-role}_ips``
 393
 394       where
 395
 396       * ``{vm-type}`` is the {vm-type} associated with the
 397         ``OS::Nova::Server``
 398       * ``{network-role}`` is the {network-role} of the ONAP external
 399         network
 400
 401 .. req::
 402     :id: R-98905
 403     :target: VNF
 404     :keyword: MUST NOT
 405     :validation_mode: static
 406     :updated: casablanca
 407
 408     The VNF's Heat Orchestration Template's Resource
 409     ``OS::Neutron::Port`` property ``fixed_ips``
 410     map property ``ip_address`` parameter
 411     ``{vm-type}_{network-role}_ips``
 412     **MUST NOT** be enumerated in the
 413     VNF's Heat Orchestration Template's Environment File.
 414
 415 ONAP's SDN-Controller assigns the IP address and ONAP provides
 416 the value at orchestration to the Heat Orchestration Template.
 417
 418 *Example External Network IPv4 Address comma_delimited_list
 419 Parameter Definition*
 420
 421 .. code-block:: yaml
 422
 423   parameters:
 424
 425     {vm-type}_{network-role}_ips:
 426       type: comma_delimited_list
 427       description: Fixed IPv4 assignments for {vm-type} VMs on the {network-role} network
 428
 429
 430 .. req::
 431     :id: R-71577
 432     :target: VNF
 433     :keyword: MUST
 434     :validation_mode: static
 435     :updated: frankfurt
 436
 437     When the VNF's Heat Orchestration Template's Resource
 438     ``OS::Neutron::Port`` is attaching to an ONAP external network (per the
 439     ONAP definition, see Requirement R-57424 and R-16968),
 440     and an IPv6 address is assigned
 441     using the property ``fixed_ips``
 442     map property ``ip_address`` and the parameter type is defined as a string,
 443     the parameter name **MUST** follow the
 444     naming convention
 445
 446     * ``{vm-type}_{network-role}_v6_ip_{index}``
 447
 448     where
 449
 450     * ``{vm-type}`` is the {vm-type} associated with the
 451       ``OS::Nova::Server``
 452     * ``{network-role}`` is the {network-role} of the ONAP external network
 453     * ``{index}`` is a numeric value that **MUST** start at zero in a
 454       VNF's Heat Orchestration Template and **MUST** increment by one
 455
 456 .. req::
 457     :id: R-87123
 458     :target: VNF
 459     :keyword: MUST NOT
 460     :validation_mode: static
 461     :updated: casablanca
 462
 463     The VNF's Heat Orchestration Template's Resource
 464     ``OS::Neutron::Port`` property ``fixed_ips``
 465     map property ``ip_address`` parameter
 466     ``{vm-type}_{network-role}_v6_ip_{index}``
 467     **MUST NOT** be enumerated in the
 468     VNF's Heat Orchestration Template's Environment File.
 469
 470 ONAP's SDN-Controller assigns the IP address and ONAP provides
 471 the value at orchestration to the Heat Orchestration Template.
 472
 473 *Example External Network IPv6 Address string Parameter Definition*
 474
 475 .. code-block:: yaml
 476
 477   parameters:
 478
 479     {vm-type}_{network-role}_v6_ip_{index}:
 480       type: string
 481       description: Fixed IPv6 assignment for {vm-type} VM {index} on the {network-role} network
 482
 483 .. req::
 484     :id: R-23503
 485     :target: VNF
 486     :keyword: MUST
 487     :validation_mode: static
 488     :updated: frankfurt
 489
 490     When the VNF's Heat Orchestration Template's Resource
 491     ``OS::Neutron::Port`` is attaching to an ONAP external network (per the
 492     ONAP definition, see Requirement R-57424 and R-16968),
 493     and an IPv6 address is assigned
 494     using the property ``fixed_ips``
 495     map property ``ip_address`` and the parameter type is defined as a
 496     ``comma_delimited_list``,
 497     the parameter name **MUST** follow the
 498     naming convention
 499
 500       * ``{vm-type}_{network-role}_v6_ips``
 501
 502     where
 503
 504       * ``{vm-type}`` is the {vm-type} associated with the
 505         OS::Nova::Server
 506       * ``{network-role}`` is the {network-role} of the ONAP external
 507         network
 508
 509 .. req::
 510     :id: R-93030
 511     :target: VNF
 512     :keyword: MUST NOT
 513     :validation_mode: static
 514     :updated: casablanca
 515
 516     The VNF's Heat Orchestration Template's Resource
 517     ``OS::Neutron::Port`` property ``fixed_ips``
 518     map property ``ip_address`` parameter
 519     ``{vm-type}_{network-role}_v6_ips``
 520     **MUST NOT** be enumerated in the
 521     VNF's Heat Orchestration Template's Environment File.
 522
 523 ONAP's SDN-Controller assigns the IP address and ONAP provides
 524 the value at orchestration to the Heat Orchestration Template.
 525
 526 *Example External Network IPv6 Address comma_delimited_list Parameter
 527 Definition*
 528
 529 .. code-block:: yaml
 530
 531   parameters:
 532
 533     {vm-type}_{network-role}_v6_ips:
 534       type: comma_delimited_list
 535       description: Fixed IPv6 assignments for {vm-type} VMs on the {network-role} network
 536
 537
 538 .. req::
 539     :id: R-78380
 540     :target: VNF
 541     :keyword: MUST
 542     :validation_mode: static
 543     :updated: frankfurt
 544
 545     When the VNF's Heat Orchestration Template's Resource
 546     ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the
 547     ONAP definition, see Requirements R-52425 and R-46461 and R-35666),
 548     and an IPv4 address is assigned
 549     using the property ``fixed_ips``
 550     map property ``ip_address`` and the parameter type is
 551     defined as a ``string``,
 552     the parameter name **MUST** follow the
 553     naming convention
 554
 555     * ``{vm-type}_int_{network-role}_ip_{index}``
 556
 557     where
 558
 559     * ``{vm-type}`` is the {vm-type} associated with the
 560       ``OS::Nova::Server``
 561     * ``{network-role}`` is the {network-role} of the ONAP internal network
 562     * ``{index}`` is a numeric value that **MUST** start at zero in a
 563       VNF's Heat Orchestration Template and **MUST** increment by one
 564
 565 .. req::
 566     :id: R-28795
 567     :target: VNF
 568     :keyword: MUST
 569     :validation_mode: static
 570     :updated: casablanca
 571
 572     The VNF's Heat Orchestration Template's Resource
 573     ``OS::Neutron::Port`` property ``fixed_ips``
 574     map property ``ip_address`` parameter
 575     ``{vm-type}_int_{network-role}_ip_{index}``
 576     **MUST** be enumerated in the
 577     VNF's Heat Orchestration Template's Environment File.
 578
 579 The IP address is local to the VNF's internal network and is (re)used
 580 in every VNF spin up, thus the constant value is declared in the VNF's
 581 Heat Orchestration Template's Environment File.
 582
 583 *Example Internal Network IPv4 Address string Parameter Definition*
 584
 585 .. code-block:: yaml
 586
 587   parameters:
 588
 589     {vm-type}_int_{network-role}_ip_{index}:
 590       type: string
 591       description: Fixed IPv4 assignment for {vm-type} VM {index} on the int_{network-role} network
 592
 593 .. req::
 594     :id: R-85235
 595     :target: VNF
 596     :keyword: MUST
 597     :validation_mode: static
 598     :updated: frankfurt
 599
 600     When the VNF's Heat Orchestration Template's Resource
 601     ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the
 602     ONAP definition, see Requirements R-52425 and R-46461 and R-35666),
 603     and an IPv4 address is assigned
 604     using the property ``fixed_ips``
 605     map property ``ip_address`` and the parameter type is defined as a
 606     ``comma_delimited_list``,
 607     the parameter name **MUST** follow the
 608     naming convention
 609
 610       * ``{vm-type}_int_{network-role}_ips``
 611
 612     where
 613
 614       * ``{vm-type}`` is the {vm-type} associated with the
 615         ``OS::Nova::Server``
 616       * ``{network-role}`` is the {network-role} of the ONAP internal
 617         network
 618
 619 .. req::
 620     :id: R-90206
 621     :target: VNF
 622     :keyword: MUST
 623     :validation_mode: static
 624     :updated: casablanca
 625
 626     The VNF's Heat Orchestration Template's Resource
 627     ``OS::Neutron::Port`` property ``fixed_ips``
 628     map property ``ip_address`` parameter
 629     ``{vm-type}_int_{network-role}_int_ips``
 630     **MUST** be enumerated in the
 631     VNF's Heat Orchestration Template's Environment File.
 632
 633 The IP address is local to the VNF's internal network and is (re)used
 634 in every VNF spin up, thus the constant value is declared in the VNF's
 635 Heat Orchestration Template's Environment File.
 636
 637 .. code-block:: yaml
 638
 639   parameters:
 640
 641     {vm-type}_int_{network-role}_ips:
 642       type: comma_delimited_list
 643       description: Fixed IPv4 assignments for {vm-type} VMs on the int_{network-role} network
 644
 645
 646 .. req::
 647     :id: R-27818
 648     :target: VNF
 649     :keyword: MUST
 650     :validation_mode: static
 651     :updated: frankfurt
 652
 653     When the VNF's Heat Orchestration Template's Resource
 654     ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the
 655     ONAP definition, see Requirements R-52425 and R-46461 and R-35666),
 656     and an IPv6 address is assigned
 657     using the property ``fixed_ips``
 658     map property ``ip_address`` and the parameter type is defined as a
 659     ``string``,
 660     the parameter name **MUST** follow the
 661     naming convention
 662
 663     * ``{vm-type}_int_{network-role}_v6_ip_{index}``
 664
 665     where
 666
 667     * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server``
 668     * ``{network-role}`` is the {network-role} of the ONAP internal network
 669     * ``{index}`` is a numeric value that **MUST** start at zero in a
 670       VNF's Heat Orchestration Template and **MUST** increment by one
 671
 672
 673 .. req::
 674     :id: R-97201
 675     :target: VNF
 676     :keyword: MUST
 677     :validation_mode: static
 678     :updated: casablanca
 679
 680     The VNF's Heat Orchestration Template's Resource
 681     ``OS::Neutron::Port`` property ``fixed_ips``
 682     map property ``ip_address`` parameter
 683     ``{vm-type}_int_{network-role}_v6_ip_{index}``
 684     **MUST** be enumerated in the
 685     VNF's Heat Orchestration Template's Environment File.
 686
 687 The IP address is local to the VNF's internal network and is (re)used
 688 in every VNF spin up, thus the constant value is declared in the VNF's
 689 Heat Orchestration Template's Environment File.
 690
 691 *Example Internal Network IPv6 Address string Parameter Definition*
 692
 693 .. code-block:: yaml
 694
 695   parameters:
 696
 697     {vm-type}_int_{network-role}_v6_ip_{index}:
 698       type: string
 699       description: Fixed IPv6 assignment for {vm-type} VM {index} on the int_{network-role} network
 700
 701 .. req::
 702     :id: R-29765
 703     :target: VNF
 704     :keyword: MUST
 705     :validation_mode: static
 706     :updated: frankfurt
 707
 708     When the VNF's Heat Orchestration Template's Resource
 709     ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the
 710     ONAP definition, see Requirements R-52425 and R-46461 and R-35666),
 711     and an IPv6 address is assigned
 712     using the property ``fixed_ips``
 713     map property ``ip_address`` and the parameter type is defined as a
 714     ``comma_delimited_list``,
 715     the parameter name **MUST** follow the
 716     naming convention
 717
 718       * ``{vm-type}_int_{network-role}_v6_ips``
 719
 720     where
 721
 722       * ``{vm-type}`` is the {vm-type} associated with the
 723         ``OS::Nova::Server``
 724       * ``{network-role}`` is the {network-role} of the ONAP internal
 725         network
 726
 727 *Example Internal Network IPv6 Address comma_delimited_list Parameter
 728 Definition*
 729
 730 .. code-block:: yaml
 731
 732   parameters:
 733
 734     {vm-type}_int_{network-role}_v6_ips:
 735       type: comma_delimited_list
 736       description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
 737
 738
 739 .. req::
 740     :id: R-98569
 741     :target: VNF
 742     :keyword: MUST
 743     :validation_mode: static
 744     :updated: casablanca
 745
 746     The VNF's Heat Orchestration Template's Resource
 747     ``OS::Neutron::Port`` property ``fixed_ips``
 748     map property ``ip_address`` parameter
 749     ``{vm-type}_int_{network-role}_v6_ips``
 750     **MUST** be enumerated in the
 751     VNF's Heat Orchestration Template's Environment File.
 752
 753 The IP address is local to the VNF's internal network and is (re)used
 754 in every VNF spin up, thus the constant value is declared in the VNF's
 755 Heat Orchestration Template's Environment File.
 756
 757 .. code-block:: yaml
 758
 759   parameters:
 760
 761     {vm-type}_int_{network-role}_v6_ips:
 762       type: comma_delimited_list
 763       description: Fixed IPv6 assignments for {vm-type} VMs on the int_{network-role} network
 764
 765 .. req::
 766     :id: R-62590
 767     :target: VNF
 768     :keyword: MUST NOT
 769     :validation_mode: static
 770     :updated: frankfurt
 771
 772     The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port``
 773     property ``fixed_ips``
 774     map property ``ip_address``
 775     parameter associated with an ONAP external network, i.e.,
 776
 777      * ``{vm-type}_{network-role}_ip_{index}``
 778      * ``{vm-type}_{network-role}_v6_ip_{index}``
 779      * ``{vm-type}_{network-role}_ips``
 780      * ``{vm-type}_{network-role}_v6_ips``
 781
 782
 783     **MUST NOT** be enumerated in the Heat Orchestration
 784     Template's Environment File.  ONAP provides the IP address
 785     assignments at orchestration time.
 786
 787 .. req::
 788     :id: R-93496
 789     :target: VNF
 790     :keyword: MUST
 791     :validation_mode: static
 792     :updated: frankfurt
 793
 794     The VNF's Heat Orchestration Template's Resource ``OS::Neutron::Port``
 795     property ``fixed_ips``
 796     map property ``ip_address``
 797     parameter associated with an ONAP internal network, i.e.,
 798
 799      * ``{vm-type}_int_{network-role}_ip_{index}``
 800      * ``{vm-type}_int_{network-role}_v6_ip_{index}``
 801      * ``{vm-type}_int_{network-role}_ips``
 802      * ``{vm-type}_int_{network-role}_v6_ips``
 803
 804
 805     **MUST** be enumerated in the Heat Orchestration
 806     Template's Environment File and IP addresses **MUST** be
 807     assigned.
 808
 809 Summary Table
 810 ~~~~~~~~~~~~~
 811
 812 .. csv-table:: **Table 4 OS::Neutron::Port Property fixed_ips map property ip_address Parameter Naming Convention**
 813    :header: Resource,Property,Map Property,Network Type,IP Address,Parameter Type,Parameter Name, Environment File
 814    :align: center
 815    :widths: auto
 816
 817    OS::Neutron::Port, fixed_ips, ip_address, ONAP external, IPv4, string, {vm-type}_{network-role}_ip_{index}, NO
 818    OS::Neutron::Port, fixed_ips, ip_address, ONAP external, IPv4, comma_delimited_list, {vm-type}_{network-role}_ips, NO
 819    OS::Neutron::Port, fixed_ips, ip_address, ONAP external, IPv6, string, {vm-type}_{network-role}_v6_ip_{index}, NO
 820    OS::Neutron::Port, fixed_ips, ip_address, ONAP external, IPv6, comma_delimited_list, {vm-type}_{network-role}_v6_ips, NO
 821    OS::Neutron::Port, fixed_ips, ip_address, ONAP internal, IPv4, string, {vm-type}_int_{network-role}_ip_{index}, YES
 822    OS::Neutron::Port, fixed_ips, ip_address, ONAP internal, IPv4, comma_delimited_list, {vm-type}_int_{network-role}_ips, YES
 823    OS::Neutron::Port, fixed_ips, ip_address, ONAP internal, IPv6, string, {vm-type}_int_{network-role}_v6_ip_{index}, YES
 824    OS::Neutron::Port, fixed_ips, ip_address, ONAP internal, IPv6, comma_delimited_list, {vm-type}_int_{network-role}_v6_ips, YES
 825
 826
 827 Examples
 828 ~~~~~~~~
 829
 830 *Example: comma_delimited_list parameters for IPv4 and IPv6 Address
 831 Assignments to an ONAP external network*
 832
 833 In this example, the ``{network-role}`` has been defined as ``oam`` to
 834 represent an oam network and the ``{vm-type}`` has been defined as ``db``
 835 for database.
 836
 837 .. code-block:: yaml
 838
 839   parameters:
 840     oam_net_id:
 841       type: string
 842       description: Neutron UUID for a oam network
 843     db_oam_ips:
 844       type: comma_delimited_list
 845       description: Fixed IPv4 assignments for db VMs on the oam network
 846     db_oam_v6_ips:
 847       type: comma_delimited_list
 848       description: Fixed IPv6 assignments for db VMs on the oam network
 849   resources:
 850     db_0_oam_port_0:
 851       type: OS::Neutron::Port
 852       properties:
 853         network: { get_param: oam_net_id }
 854         fixed_ips: [ { "ip_address": {get_param: [ db_oam_ips, 0 ]}}, {
 855         "ip_address": {get_param: [ db_oam_v6_ips, 0 ]}}]
 856     db_1_oam_port_0:
 857       type: OS::Neutron::Port
 858       properties:
 859         network: { get_param: oam_net_id }
 860         fixed_ips:
 861           - "ip_address": {get_param: [ db_oam_ips, 1 ]}
 862           - "ip_address": {get_param: [ db_oam_v6_ips, 1 ]}
 863
 864 *Example: string parameters for IPv4 and IPv6 Address Assignments to an
 865 ONAP external network*
 866
 867 In this example, the ``{network-role}`` has been defined as ``oam`` to
 868 represent an oam network and the ``{vm-type}`` has been defined as ``db`` for
 869 database.
 870
 871 .. code-block:: yaml
 872
 873   parameters:
 874     oam_net_id:
 875       type: string
 876       description: Neutron UUID for an OAM network
 877     db_oam_ip_0:
 878       type: string
 879       description: Fixed IPv4 assignment for db VM 0 on the OAM network
 880     db_oam_ip_1:
 881       type: string
 882       description: Fixed IPv4 assignment for db VM 1 on the OAM network
 883     db_oam_v6_ip_0:
 884       type: string
 885       description: Fixed IPv6 assignment for db VM 0 on the OAM network
 886     db_oam_v6_ip_1:
 887       type: string
 888       description: Fixed IPv6 assignment for db VM 1 on the OAM network
 889   resources:
 890     db_0_oam_port_0:
 891       type: OS::Neutron::Port
 892       properties:
 893         network: { get_param: oam_net_id }
 894         fixed_ips: [ { "ip_address": {get_param: db_oam_ip_0}}, { "ip_address": {get_param: db_oam_v6_ip_0 }}]
 895     db_1_oam_port_0:
 896       type: OS::Neutron::Port
 897       properties:
 898         network: { get_param: oam_net_id }
 899         fixed_ips:
 900           - "ip_address": {get_param: db_oam_ip_1}
 901           - "ip_address": {get_param: db_oam_v6_ip_1}
 902
 903
 904 *Example*: comma_delimited_list parameters for IPv4 and IPv6 Address
 905 Assignments to an ONAP internal network*
 906
 907 In this example, the ``{network-role}`` has been defined as ``ctrl`` to
 908 represent an ctrl network internal to the vnf.
 909 The ``{vm-type}`` has been defined as ``db`` for
 910 database.
 911
 912 .. code-block:: yaml
 913
 914   parameters:
 915     int_ctrl_net_id:
 916       type: string
 917       description: Neutron UUID for the ctrl internal network
 918     db_int_ctrl_ips:
 919       type: comma_delimited_list
 920       description: Fixed IPv4 assignments for db VMs on the ctrl internal
 921       network
 922     db_int_ctrl_v6_ips:
 923       type: comma_delimited_list
 924       description: Fixed IPv6 assignments for db VMs on the ctrl internal
 925       network
 926   resources:
 927     db_0_int_ctrl_port_0:
 928       type: OS::Neutron::Port
 929       properties:
 930         network: { get_param: int_ctrl_net_id }
 931         fixed_ips: [ { "ip_address": {get_param: [ db_int_ctrl_ips, 0 ]}}, {
 932         "ip_address": {get_param: [ db_int_ctrl_v6_ips, 0 ]}}]
 933     db_1_int_ctrl_port_0:
 934       type: OS::Neutron::Port
 935       properties:
 936         network: { get_param: int_ctrl_net_id }
 937         fixed_ips:
 938         - "ip_address": {get_param: [ db_int_ctrl_ips, 1 ]}
 939         - "ip_address": {get_param: [ db_int_ctrl_v6_ips, 1 ]}
 940
 941
 942 *Example: string parameters for IPv4 and IPv6 Address Assignments to an
 943 ONAP internal network*
 944
 945 In this example, the ``int_{network-role}`` has been defined as
 946 ``int_ctrl`` to represent a control network internal to the vnf.
 947 The ``{vm-type}`` has been defined as ``db`` for database.
 948
 949 .. code-block:: yaml
 950
 951   parameters:
 952     int_ctrl_net_id:
 953       type: string
 954       description: Neutron UUID for an OAM internal network
 955     db_int_ctrl_ip_0:
 956       type: string
 957       description: Fixed IPv4 assignment for db VM on the oam_int network
 958     db_int_ctrl_ip_1:
 959       type: string
 960       description: Fixed IPv4 assignment for db VM 1 on the oam_int network
 961     db_int_ctrl_v6_ip_0:
 962       type: string
 963       description: Fixed IPv6 assignment for db VM 0 on the oam_int network
 964     db_int_ctrl_v6_ip_1:
 965       type: string
 966       description: Fixed IPv6 assignment for db VM 1 on the oam_int network
 967   resources:
 968     db_0_int_ctrl_port_0:
 969       type: OS::Neutron::Port
 970       properties:
 971         network: { get_param: int_oam_int_net_id }
 972         fixed_ips: [ { "ip_address": {get_param: db_oam_int_ip_0}}, {
 973         "ip_address": {get_param: db_oam_int_v6_ip_0 }}]
 974     db_1_int_ctrl_port_0:
 975       type: OS::Neutron::Port
 976       properties:
 977         network: { get_param: int_oam_int_net_id }
 978         fixed_ips:
 979           - "ip_address": {get_param: db_oam_int_ip_1}
 980           - "ip_address": {get_param: db_oam_int_v6_ip_1}
 981
 982
 983 Property: fixed_ips, Map Property: subnet
 984 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 985
 986 The resource ``OS::Neutron::Port`` property ``fixed_ips`` map
 987 property ``subnet`` is used when a
 988 port is requesting an IP assignment via
 989 OpenStack’s DHCP Service (i.e., cloud assigned).
 990
 991 The IP address assignment will be made from the specified subnet.
 992
 993 Specifying the subnet is not required; it is optional.
 994
 995 If the network (ONAP external or ONAP internal) that the port is attaching
 996 to only contains one subnet, specifying the subnet is
 997 superfluous.  The IP address will be assigned from the one existing
 998 subnet.
 999
1000 If the network (ONAP external or ONAP internal) that the port is attaching
1001 to contains two or more subnets, specifying the subnet in the
1002 ``fixed_ips`` map property ``subnet`` determines which
1003 subnet the IP address will be assigned from.
1004
1005 If the network (ONAP external or ONAP internal) that the port is attaching
1006 to contains two or more subnets, and the subnet is not is not
1007 specified, OpenStack will randomly determine which subnet
1008 the IP address will be assigned from.
1009
1010 The property ``fixed_ips`` is used to assign IPs to a port. The Map Property
1011 ``subnet`` specifies the subnet the IP is assigned from.
1012
1013 .. req::
1014     :id: R-38236
1015     :target: VNF
1016     :keyword: MUST
1017     :validation_mode: static
1018     :updated: casablanca
1019
1020     The VNF's Heat Orchestration Template's
1021     resource ``OS::Neutron::Port`` property ``fixed_ips``
1022     map property ``subnet`` parameter
1023     **MUST** be declared type ``string``.
1024
1025 .. req::
1026     :id: R-62802
1027     :target: VNF
1028     :keyword: MUST
1029     :validation_mode: static
1030     :updated: frankfurt
1031
1032     When the VNF's Heat Orchestration Template's
1033     resource ``OS::Neutron::Port`` is attaching
1034     to an ONAP external network (per the ONAP definition, see
1035     Requirement R-57424 and R-16968),
1036     and an IPv4 address is being cloud assigned by OpenStack's DHCP Service
1037     and the ONAP external network IPv4 subnet is to be specified
1038     using the property ``fixed_ips``
1039     map property ``subnet``, the parameter
1040     **MUST** follow the naming convention
1041
1042       * ``{network-role}_subnet_id``
1043
1044     where
1045
1046       * ``{network-role}`` is the network role of the ONAP external network.
1047
1048
1049 Note that ONAP only supports cloud assigned IP addresses from one IPv4 subnet
1050 of a given network.
1051
1052 .. req::
1053     :id: R-83677
1054     :target: VNF
1055     :keyword: MUST NOT
1056     :validation_mode: static
1057     :updated: casablanca
1058
1059
1060     The VNF's Heat Orchestration Template's Resource
1061     ``OS::Neutron::Port`` property ``fixed_ips``
1062     map property ``subnet`` parameter
1063     ``{network-role}_subnet_id``
1064     **MUST NOT** be enumerated in the
1065     VNF's Heat Orchestration Template's Environment File.
1066
1067 ONAP's SDN-Controller provides the network's subnet's UUID
1068 value at orchestration to the Heat Orchestration Template.
1069
1070 *Example Parameter Definition*
1071
1072 .. code-block:: yaml
1073
1074   parameters:
1075
1076     {network-role}_subnet_id:
1077       type: string
1078       description: Neutron IPv4 subnet UUID for the {network-role} network
1079
1080
1081 .. req::
1082     :id: R-15287
1083     :target: VNF
1084     :keyword: MUST
1085     :validation_mode: static
1086     :updated: frankfurt
1087
1088     When the VNF's Heat Orchestration Template's
1089     resource ``OS::Neutron::Port`` is attaching
1090     to an ONAP external network (per the ONAP definition, see
1091     Requirement R-57424 and R-16968),
1092     and an IPv6 address is being cloud assigned by OpenStack's DHCP Service
1093     and the ONAP external network IPv6 subnet is to be specified
1094     using the property ``fixed_ips``
1095     map property ``subnet``, the parameter
1096     **MUST** follow the naming convention
1097
1098       * ``{network-role}_v6_subnet_id``
1099
1100     where
1101
1102       * ``{network-role}`` is the network role of the ONAP external network.
1103
1104 Note that ONAP only supports cloud assigned IP addresses from one IPv6 subnet
1105 of a given network.
1106
1107 .. req::
1108     :id: R-80829
1109     :target: VNF
1110     :keyword: MUST NOT
1111     :validation_mode: static
1112     :updated: casablanca
1113
1114     The VNF's Heat Orchestration Template's Resource
1115     ``OS::Neutron::Port`` property ``fixed_ips``
1116     map property ``subnet`` parameter
1117     ``{network-role}_v6_subnet_id``
1118     **MUST NOT** be enumerated in the
1119     VNF's Heat Orchestration Template's Environment File.
1120
1121 *Example: One Cloud Assigned IPv4 Address (DHCP) assigned to an ONAP external
1122 network that has two or more IPv4 subnets*
1123
1124 In this example, the ``{network-role}`` has been defined as ``oam`` to
1125 represent an oam network and the ``{vm-type}`` has been defined as ``lb``
1126 for load balancer. The cloud assigned IP address uses the OpenStack
1127 DHCP service to assign IP addresses.
1128
1129 .. code-block:: yaml
1130
1131   parameters:
1132     oam_net_id:
1133       type: string
1134       description: Neutron UUID for the oam network
1135     oam_subnet_id:
1136       type: string
1137       description: Neutron IPv4 subnet UUID for the oam network
1138   resources:
1139     lb_0_oam_port_0:
1140       type: OS::Neutron::Port
1141         parameters:
1142           network: { get_param: oam_net_id }
1143           fixed_ips:
1144             - subnet: { get_param: oam_subnet_id }
1145
1146 *Example: One Cloud Assigned IPv4 address and one Cloud Assigned IPv6
1147 address assigned to an ONAP external network that has at least one IPv4 subnet
1148 and one IPv6 subnet*
1149
1150 In this example, the ``{network-role}`` has been defined as ``oam`` to
1151 represent an oam network and the ``{vm-type}`` has been defined as
1152 ``lb`` for load balancer.
1153
1154 .. code-block:: yaml
1155
1156   parameters:
1157     oam_net_id:
1158       type: string
1159       description: Neutron UUID for the oam network
1160     oam_subnet_id:
1161       type: string
1162       description: Neutron IPv4 subnet UUID for the oam network
1163     oam_v6_subnet_id:
1164       type: string
1165       description: Neutron IPv6 subnet UUID for the oam network
1166   resources:
1167     lb_0_oam_port_0:
1168       type: OS::Neutron::Port
1169       properties:
1170         network: { get_param: oam_net_id }
1171         fixed_ips:
1172           - subnet: { get_param: oam_subnet_id }
1173           - subnet: { get_param: oam_v6_subnet_id }
1174
1175 .. req::
1176     :id: R-84123
1177     :target: VNF
1178     :keyword: MUST
1179     :validation_mode: static
1180     :updated: frankfurt
1181
1182     When
1183
1184       * the VNF's Heat Orchestration Template's
1185         resource ``OS::Neutron::Port`` in an Incremental Module is attaching
1186         to an ONAP internal network (per the ONAP definition, see
1187         Requirements R-52425 and R-46461 and R-35666)
1188         that is created in the Base Module, AND
1189       * an IPv4 address is being cloud assigned by OpenStack's DHCP Service AND
1190       * the internal network IPv4 subnet is to be specified
1191         using the property ``fixed_ips`` map property ``subnet``,
1192
1193     the parameter **MUST** follow the naming convention
1194
1195       * ``int_{network-role}_subnet_id``
1196
1197     where
1198
1199       * ``{network-role}`` is the network role of the ONAP internal network
1200
1201     Note that the parameter **MUST** be defined as an ``output`` parameter in
1202     the base module.
1203
1204 .. req::
1205     :id: R-69634
1206     :target: VNF
1207     :keyword: MUST NOT
1208     :validation_mode: static
1209     :updated: casablanca
1210
1211     The VNF's Heat Orchestration Template's Resource
1212     ``OS::Neutron::Port`` property ``fixed_ips``
1213     map property ``subnet`` parameter
1214     ``int_{network-role}_subnet_id``
1215     **MUST NOT** be enumerated in the
1216     VNF's Heat Orchestration Template's Environment File.
1217
1218 The assumption is that the ONAP internal networks are created in the base
1219 module.
1220 The Neutron subnet network ID will be passed as an output parameter
1221 (e.g., ONAP Base Module Output Parameter) to the incremental modules.
1222 In the incremental modules, the output parameter name will be defined as
1223 input parameter.
1224
1225 *Example Parameter Definition*
1226
1227 .. code-block:: yaml
1228
1229   parameters:
1230
1231     int_{network-role}_subnet_id:
1232       type: string
1233       description: Neutron IPv4 subnet UUID for the int_{network-role} network
1234
1235 .. req::
1236     :id: R-76160
1237     :target: VNF
1238     :keyword: MUST
1239     :validation_mode: static
1240     :updated: frankfurt
1241
1242     When
1243
1244     * the VNF's Heat Orchestration Template's
1245       resource ``OS::Neutron::Port`` in an Incremental Module is attaching
1246       to an ONAP internal network (per the ONAP definition, see Requirements
1247       R-52425 and R-46461 and R-35666)
1248       that is created in the Base Module, AND
1249     * an IPv6 address is being cloud assigned by OpenStack's DHCP Service AND
1250     * the ONAP internal network IPv6 subnet is to be specified
1251       using the property ``fixed_ips`` map property ``subnet``,
1252
1253     the parameter **MUST** follow the naming convention
1254
1255     * ``int_{network-role}_v6_subnet_id``
1256
1257     where ``{network-role}`` is the network role of the ONAP internal network.
1258
1259     Note that the parameter **MUST** be defined as an ``output`` parameter in
1260     the base module.
1261
1262 .. req::
1263     :id: R-22288
1264     :target: VNF
1265     :keyword: MUST NOT
1266     :validation_mode: static
1267     :updated: casablanca
1268
1269     The VNF's Heat Orchestration Template's Resource
1270     ``OS::Neutron::Port`` property ``fixed_ips``
1271     map property ``subnet`` parameter
1272     ``int_{network-role}_v6_subnet_id``
1273     **MUST NOT** be enumerated in the
1274     VNF's Heat Orchestration Template's Environment File.
1275
1276
1277 *Example Parameter Definition*
1278
1279 .. code-block:: yaml
1280
1281   parameters:
1282
1283     int_{network-role}_v6_subnet_id:
1284       type: string
1285       description: Neutron subnet UUID for the int_{network-role} network
1286
1287 Property: allowed\_address\_pairs, Map Property: ip\_address
1288 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1289
1290 The property ``allowed_address_pairs`` in the resource ``OS::Neutron::Port``
1291 allows the user to specify a ``mac_address`` and/or ``ip_address`` that will
1292 pass through a port regardless of subnet. This enables the use of
1293 protocols, such as VRRP, which allow for a Virtual IP (VIP) address
1294 to be shared among two or more ports, with one designated as the master
1295 and the others as backups. In case the master fails,
1296 the Virtual IP address is mapped to a backup's IP address and
1297 the backup becomes the master.
1298
1299 Note that the IP address assigned to the ``allowed_address_pairs`` property
1300 will be referred to as a Virtual IP or VIP or VIP address.
1301
1302 The management of the VIP addresses (i.e. transferring
1303 ownership between active and standby VMs) is the responsibility of
1304 the VNF application.
1305
1306 If a VNF requires a Virtual IP address,
1307 a VNF's Heat Orchestration Template's resource
1308 ``OS::Neutron::Port`` property ``allowed_address_pairs``
1309 map property ``ip_address`` parameter must be used.
1310
1311 The ``allowed_address_pairs`` is an optional property. It is not required.
1312
1313 The ONAP data model only supports the assignment of
1314
1315 * One IPv4 Virtual IP address and/or
1316 * One IPv6 Virtual IP address
1317
1318 for a set of ports associated with a ``{vm-type}`` and ``{network-role}``.
1319
1320 The ONAP data model that supports VIPs includes the
1321
1322 * SDC TOSCA model
1323 * SDN-C MD-SAL structure
1324 * AAI VNF-C object
1325
1326 However, it is possible to assign additional VIP addresses to a port.
1327 These additional VIP addresses will not be represented in the
1328 SDC TOSCA model and AAI VNF-C object and will be represented differently
1329 in the MD-SAL structure.
1330
1331 All VIP addresses will be inventoried in the
1332 A&AI vserver object.  This assumes the mechanism to populate
1333 allowed_address_pair IP addresses in the AAI vserver object has been
1334 implemented.
1335
1336 In order for the VIP address to be supported by the ONAP data model,
1337 the parameter associated with the ``OS::Neutron::Port`` property
1338 ``allowed_address_pairs`` map property ``ip_address`` must follow
1339 an explicit naming convention.
1340 As expected, the naming convention only supports one IPv4 VIP address
1341 and one IPv6 VIP address.
1342
1343 It is recommended that the first IPv4 VIP address and first
1344 IPv6 VIP address assigned follow the explicit naming convention.
1345 If additional VIP addresses are required, the naming
1346 convention is at the discretion of the user.  However,
1347 ``OS::Neutron::Port`` resource-level ``metadata`` (not property-level) must be
1348 included in the resource definition.
1349
1350 The detailed requirements follow in the sections below.
1351
1352
1353
1354 VIP Assignment, ONAP External Networks
1355 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1356
1357 .. req::
1358     :id: R-83412
1359     :target: VNF
1360     :keyword: MUST NOT
1361     :validation_mode: static
1362     :updated: frankfurt
1363
1364     If a VNF's Heat Orchestration Template's resource
1365     ``OS::Neutron::Port`` is attaching to an ONAP external network (per the
1366     ONAP definition, see Requirement R-57424 and R-16968), the
1367     property ``allowed_address_pairs``
1368     map property ``ip_address`` parameter(s)
1369     **MUST NOT** be enumerated in the
1370     VNF's Heat Orchestration Template's Environment File.
1371
1372
1373 .. req::
1374     :id: R-41492
1375     :target: VNF
1376     :keyword: MUST
1377     :validation_mode: static
1378     :updated: frankfurt
1379
1380     When the VNF's Heat Orchestration Template's resource
1381     ``OS::Neutron::Port`` is attaching to an ONAP external network
1382     (per the ONAP definition, see Requirement R-57424 and R-16968),
1383     and the IPv4 VIP is required to be supported by the ONAP data model,
1384     the property ``allowed_address_pairs`` map property ``ip_address``
1385     parameter name **MUST** follow the naming convention
1386
1387     * ``{vm-type}_{network-role}_floating_ip``
1388
1389     where
1390
1391     * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server``
1392     * ``{network-role}`` is the {network-role} of the ONAP external network
1393
1394     And the parameter **MUST** be declared as type ``string``.
1395
1396     As noted in the introduction to this section, the ONAP data model
1397     can only support one IPv4 VIP address.
1398
1399
1400 *Example Parameter Definition*
1401
1402 .. code-block:: yaml
1403
1404   parameters:
1405
1406     {vm-type}_{network-role}_floating_ip:
1407       type: string
1408       description: IPv4 VIP for {vm-type} VMs on the {network-role} network
1409
1410
1411 .. req::
1412     :id: R-35735
1413     :target: VNF
1414     :keyword: MUST
1415     :validation_mode: static
1416     :updated: frankfurt
1417
1418     When the VNF's Heat Orchestration Template's resource
1419     ``OS::Neutron::Port`` is attaching to an ONAP external network
1420     (per the ONAP definition, see Requirement R-57424 and R-16968),
1421     and the IPv6 VIP is required to be supported by the ONAP data model,
1422     the property ``allowed_address_pairs`` map property ``ip_address``
1423     parameter name **MUST** follow the naming convention
1424
1425     * ``{vm-type}_{network-role}_floating_v6_ip``
1426
1427     where
1428
1429     * ``{vm-type}`` is the {vm-type} associated with the ``OS::Nova::Server``
1430     * ``{network-role}`` is the {network-role} of the ONAP external network
1431
1432     And the parameter **MUST** be declared as type ``string``.
1433
1434     As noted in the introduction to this section, the ONAP data model
1435     can only support one IPv6 VIP address.
1436
1437
1438 *Example Parameter Definition*
1439
1440 .. code-block:: yaml
1441
1442   parameters:
1443
1444     {vm-type}_{network-role}_floating_v6_ip:
1445       type: string
1446       description: IPv6 VIP for {vm-type} VMs on the {network-role} network
1447
1448
1449 .. req::
1450     :id: R-41493
1451     :target: VNF
1452     :keyword: MUST
1453     :validation_mode: static
1454     :introduced: dublin
1455     :updated: frankfurt
1456
1457     When the VNF's Heat Orchestration Template's resource
1458     ``OS::Neutron::Port`` is attaching to an ONAP external network
1459     (per the ONAP definition, see Requirement R-57424 and R-16968),
1460     and the IPv4 VIP address and/or IPv6 VIP address
1461     is **not** supported by the ONAP data model,
1462     the property ``allowed_address_pairs`` map property ``ip_address``
1463
1464     * Parameter name **MAY** use any naming convention.  That is, there is no
1465       ONAP mandatory parameter naming convention.
1466     * Parameter **MAY** be declared as type ``string`` or type
1467     ``comma_delimited_list``.
1468
1469     And the ``OS::Neutron::Port`` resource **MUST** contain
1470     resource-level ``metadata`` (not property-level).
1471
1472     And the ``metadata`` format **MUST**  must contain the
1473     key value ``aap_exempt`` with a list of all
1474     ``allowed_address_pairs`` map property ``ip_address`` parameters
1475     **not** supported by the ONAP data model.
1476
1477
1478 *Example*
1479
1480 In the example below, the ``OS::Neutron::Port`` property
1481 ``allowed_address_pairs`` map property ``ip_address`` has two parameters,
1482 ``param1`` and ``param2``, that are not supported by the ONAP data model.
1483
1484 .. code-block:: yaml
1485
1486   db_0_oam_port_0:
1487     type: OS::Neutron::Port
1488     properties:
1489       network: { get_param: oam_net_id }
1490       fixed_ips: [ { "ip_address": {get_param: db_oam_ip_0 }}]
1491       allowed_address_pairs: [ { "ip_address": {get_param: param1 }}, { "ip_address": {get_param: param2 }}]
1492     metadata:
1493       aap_exempt:
1494         - param1
1495         - param2
1496
1497
1498 *Example*
1499
1500 In the example below, the ``OS::Neutron::Port`` property
1501 ``allowed_address_pairs`` map property ``ip_address`` has two parameters,
1502 ``db_oam_ip_0``, which is supported by the ONAP data model, and param1,
1503 which is not supported by the ONAP data model.
1504
1505 .. code-block:: yaml
1506
1507   db_0_oam_port_0:
1508     type: OS::Neutron::Port
1509     properties:
1510       network: { get_param: oam_net_id }
1511       fixed_ips: [ { "ip_address": {get_param: db_oam_ip_0 }}]
1512       allowed_address_pairs: [ { "ip_address": {get_param: db_oam_floating_ip }}, { "ip_address": {get_param: param1 }} ]
1513     metadata:
1514       aap_exempt:
1515         - param1
1516
1517
1518 Note that the parameters associated with the resource
1519 ``OS::Neutron::Port`` property ``allowed_address_pairs``
1520 map property ``ip_address``  are **not** intended to represent an OpenStack
1521 "Floating IP", for which OpenStack manages a pool of public IP
1522 addresses that are mapped to specific VM ports. In that case, the
1523 individual VMs are not even aware of the public IPs, and all assignment
1524 of public IPs to VMs is via OpenStack commands. ONAP does not support
1525 Neutron-style Floating IPs.  That is, ONAP does not support the
1526 resources ``OS::Neutron::FloatingIP``
1527 and ``OS::Neutron::FloatingIPAssociation``.
1528
1529
1530 .. req::
1531     :id: R-05257
1532     :target: VNF
1533     :keyword: MUST NOT
1534     :validation_mode: static
1535     :updated: casablanca
1536
1537     A VNF's Heat Orchestration Template's **MUST NOT**
1538     contain the Resource ``OS::Neutron::FloatingIP``.
1539
1540 .. req::
1541     :id: R-76449
1542     :target: VNF
1543     :keyword: MUST NOT
1544     :validation_mode: static
1545     :updated: casablanca
1546
1547     A VNF's Heat Orchestration Template's **MUST NOT**
1548     contain the Resource ``OS::Neutron::FloatingIPAssociation``.
1549
1550 The Floating IP functions as a NAT.  They are allocated within
1551 OpenStack, and always "terminate" within the OpenStack infrastructure.
1552 When OpenStack receives packets on a Floating IP, the packets will
1553 be forwarded to the
1554 Port that has been mapped to the Floating IP, using the private address of the
1555 port.  The VM never sees or knows about the OpenStack Floating IP.
1556 The process to use is:
1557
1558   - User allocates a floating IP from the OpenStack pool.
1559   - User ‘attaches’ that floating IP to one of the VM ports.
1560
1561 If there is a high-availability VNF that wants to "float" the IP to a
1562 different VM, it requires a Neutron command to request OpenStack to ‘attach’
1563 the floating IP to a different VM port.
1564 The pool of such addresses is managed by OpenStack infrastructure.
1565 Users cannot create new ones, they can only choose from those in the pool.
1566 The pool is typically global (i.e. any user/tenant can grab them).
1567
1568 Allowed address pairs are for more typical Linux-level "virtual IPs".
1569 They are additional IP addresses that are advertised by some port on the VM,
1570 in addition to the primary private IP address.  Typically in a
1571 high-availability VNF, an additional IP is assigned and will float between
1572 VMs (e.g., via some health-check app that will plumb the IP on one or other
1573 VM).  In order for this to work, the actual packets must be addressed to that
1574 IP address (and the allowed_ip_address list will let it pass through
1575 to the VM).  This generally requires provider network access
1576 (i.e. direct access to a data center network for the VMs), such that these
1577 IPs can pass through all of the virtual routers.
1578 Contrail also provides the enhanced networking that allows routing of such
1579 additional IPs.
1580
1581 Floating IPs are not used in ONAP due to the NAT-ting nature of the IPs,
1582 the inability to reserve such IPs for specific use, the need to manage them
1583 via OpenStack commands (i.e. a HA VNF would require direct access to
1584 OpenStack to ‘float’ such an IP from one VM to another).
1585
1586 *Example:*
1587
1588 In this example, the {network-role} has been defined as oam to represent
1589 an oam network and the {vm-type} has been defined as db for database.
1590
1591 .. code-block:: yaml
1592
1593   parameters:
1594     oam_net_id:
1595       type: string
1596       description: Neutron UUID for the oam network
1597     db_oam_ips:
1598       type: comma_delimited_list
1599       description: Fixed IPs for db VMs on the oam network
1600     db_oam_floating_ip:
1601       type: string
1602       description: VIP IP for db VMs on the oam network
1603   resources:
1604     db_0_oam_port_0:
1605       type: OS::Neutron::Port
1606       properties:
1607         network: { get_param: oam_net_id }
1608         fixed_ips: [ { "ip_address": {get_param: [db_oam_ips, 0] }}]
1609         allowed_address_pairs: [ { "ip_address": {get_param: db_oam_floating_ip}}]
1610     db_1_oam_port_0:
1611       type: OS::Neutron::Port
1612         properties:
1613           network: { get_param: oam_net_id }
1614           fixed_ips: [ { "ip_address": {get_param: [db_oam_ips, 1] }}]
1615           allowed_address_pairs: [ { "ip_address": {get_param: db_oam_floating_ip}}]
1616
1617
1618
1619
1620
1621 VIP Assignment, ONAP Internal Networks
1622 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
1623
1624 .. req::
1625     :id: R-717227
1626     :keyword: MUST
1627     :introduced: dublin
1628     :validation_mode: static
1629     :target: VNF
1630     :updated: frankfurt
1631
1632     When the VNF's Heat Orchestration Template's Resource
1633     ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the
1634     ONAP definition, see Requirements R-52425 and R-46461 and R-35666),
1635     and an IPv4 Virtual IP (VIP)
1636     address is assigned using the property ``allowed_address_pairs``
1637     map property ``ip_address``,
1638     the parameter name **MUST** follow the
1639     naming convention
1640
1641     - ``{vm-type}_int_{network-role}_floating_ip``
1642
1643     where
1644
1645     - ``{vm-type}`` is the {vm-type} associated with the
1646       OS::Nova::Server
1647     - ``{network-role}`` is the {network-role} of the ONAP internal
1648       network
1649
1650     And the parameter **MUST** be declared as ``type: string``
1651     and **MUST** be enumerated in the environment file.
1652
1653     OR
1654
1655     the parameter name **MUST** follow the
1656     naming convention
1657
1658     - ``{vm-type}_int_{network-role}_floating_ips``
1659
1660     where
1661
1662     - ``{vm-type}`` is the {vm-type} associated with the
1663       OS::Nova::Server
1664     - ``{network-role}`` is the {network-role} of the ONAP internal
1665       network
1666
1667     And the parameter **MUST** be declared as ``type: comma_delimited_list``
1668     and **MUST** be enumerated in the environment file.
1669
1670
1671 .. req::
1672     :id: R-805572
1673     :keyword: MUST
1674     :introduced: dublin
1675     :validation_mode: static
1676     :target: VNF
1677     :updated: frankfurt
1678
1679     When the VNF's Heat Orchestration Template's Resource
1680     ``OS::Neutron::Port`` is attaching to an ONAP internal network (per the
1681     ONAP definition, see Requirements R-52425 and R-46461 and R-35666),
1682     and an IPv6 Virtual IP (VIP)
1683     address is assigned
1684     using the property ``allowed_address_pairs``
1685     map property ``ip_address``,
1686     the parameter name **MUST** follow the
1687     naming convention
1688
1689     - ``{vm-type}_int_{network-role}_floating_v6_ip``
1690
1691     where
1692
1693     - ``{vm-type}`` is the {vm-type} associated with the
1694       OS::Nova::Server
1695     - ``{network-role}`` is the {network-role} of the ONAP internal
1696       network
1697
1698     And the parameter **MUST** be declared as ``type: string``
1699     and **MUST** be enumerated in the environment file
1700
1701     OR
1702
1703     the parameter name **MUST** follow the
1704     naming convention
1705
1706     - ``{vm-type}_int_{network-role}_floating_v6_ips``
1707
1708     where
1709
1710     - ``{vm-type}`` is the {vm-type} associated with the
1711       OS::Nova::Server
1712     - ``{network-role}`` is the {network-role} of the ONAP internal
1713       network
1714
1715     And the parameter **MUST** be declared as ``type: comma_delimited_list``
1716     and **MUST** be enumerated in the environment file.
1717
1718
1719 Reserve Port Concept
1720 ~~~~~~~~~~~~~~~~~~~~
1721
1722 A "Reserve Port" is an ``OS::Neutron::Port`` that ``fixed_ips``, ip_address
1723 property is assigned one or more IP addresses that are used as Virtual
1724 IP (VIP) addresses (i.e., allowed_address_pairs) on other ports.
1725
1726 A "Reserve Port" is never attached to a Virtual Machine
1727 (``OS::Nova::Server``). The reserve port ensures that the intended
1728 ``allowed_address_pair`` IP address is not inadvertently assigned as a
1729 fixed_ips to a ``OS::Neutron::Port`` that is attached ``OS::Nova::Server`` and
1730 thus causing routing issues.
1731
1732 A VNF may have one or more "Reserve Ports". A reserve port maybe created
1733 in the base module or an incremental module. If created in the base
1734 module, parameters may be defined in the outputs: section of the base
1735 template so the IP address assigned to the reserve port maybe assigned
1736 to the allowed_address_pair property of an ``OS::Neutron::Port`` in one or
1737 more incremental modules.
1738
1739 The parameter name of the IP address used in the "Reserve Port" depends
1740 on the ``allowed_address_pair`` "option" utilized by the VNF.
1741
1742 When creating a Reserve Port, if only one allowed_address_pair is configured
1743 on a port, then the parameter name depends upon the IP addresses type
1744 (IPv4 or IPv6) and network type (ONAP internal or ONAP external).
1745 The valid parameter names are:
1746
1747   * ``{vm-type}_{network-role}_floating_ip``
1748   * ``{vm-type}_{network-role}_floating_v6_ip``
1749   * ``{vm-type}_int_{network-role}_floating_ip``
1750   * ``{vm-type}_int_{network-role}_floating_v6_ip``
1751
1752 When creating a Reserve Port, if more than one (e.g., multiple)
1753 ``allowed_address_pair`` is configured on a port, then the parameter name
1754 depends
1755 upon the IP addresses type (IPv4 or IPv6) and network type
1756 (internal or external) and the option being used.  The valid parameter
1757 names are:
1758
1759   * ``{vm-type}_{network-role}_ip_{index}``
1760   * ``{vm-type}_{network-role}_ips``
1761   * ``{vm-type}_{network-role}_v6_ip_{index}``
1762   * ``{vm-type}_{network-role}_v6_ips``
1763   * ``{vm-type}_{network-role}_vip_{index}``
1764   * ``{vm-type}_{network-role}_vips``
1765   * ``{vm-type}_{network-role}_v6_vip_{index}``
1766   * ``{vm-type}_{network-role}_v6_vips``
1767   * ``{vm-type}_{network-role}_{vip-type}_vip``
1768   * ``{vm-type}_{network-role}_v6_{vip-type}_vip``
1769   * ``{vm-type}_{network-role}_{vip-type}_vips``
1770   * ``{vm-type}_{network-role}_v6_{vip-type}_vips``
1771
1772
1773 *Example IPv4 Reserve Port Definition: one allowed_address_pair
1774 configured on a port*
1775
1776 .. code-block:: yaml
1777
1778   Reserve_Port_{vm-type}_{network-role}_floating_ip_{index}:
1779     type: OS::Neutron::Port
1780     properties:
1781       network: { get_param: {network-role}_net_id }
1782       fixed_ips:
1783         - ip_address : { get_param: {vm-type}_{network-role}_floating_ip }
1784
1785 *Example IPv6 Reserve Port Definition: one allowed_address_pair
1786 configured on a port*
1787
1788 .. code-block:: yaml
1789
1790   Reserve_Port_{vm-type}_{network-role}_floating_v6_ip_{index}:
1791     type: OS::Neutron::Port
1792     properties:
1793       network: { get_param: {network-role}_net_id }
1794       fixed_ips:
1795         - ip_address : { get_param: {vm-type}_{network-role}_floating_v6_ip }
1796
1797 Note that the use of a Reserve Port may prevent the VIP address from being
1798 inventoried in the AAI VNF-C object.