docs/homingspecification.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. Copyright (C) 2017-2018 AT&T Intellectual Property. All rights reserved.
   3
   4 Homing Specification Guide
   5 ==========================
   6
   7 *Updated: 10 October 2017*
   8
   9 This document describes the Homing Template format, used by the Homing
  10 service. It is a work in progress and subject to frequent revision.
  11
  12 Template Structure
  13 ------------------
  14
  15 Homing templates are defined in YAML and follow the structure outlined
  16 below.
  17
  18 .. code:: yaml
  19
  20     homing_template_version: 2017-10-10
  21     parameters:
  22       PARAMETER_DICT
  23     locations:
  24       LOCATION_DICT
  25     demands:
  26       DEMAND_DICT
  27     constraints:
  28       CONSTRAINT_DICT
  29     reservations:
  30       RESERVATION_DICT
  31     optimization:
  32       OPTIMIZATION
  33
  34 -  ``homing_template_version``: This key with value 2017-10-10 (or a
  35    later date) indicates that the YAML document is a Homing template of
  36    the specified version.
  37 -  ``parameters``: This section allows for specifying input parameters
  38    that have to be provided when instantiating the homing template.
  39    Typically, this section is used for providing runtime parameters
  40    (like SLA thresholds), which in turn is used in the existing homing
  41    policies. The section is optional and can be omitted when no input is
  42    required.
  43 -  ``locations``: This section contains the declaration of geographic
  44    locations. This section is optional and can be omitted when no input
  45    is required.
  46 -  ``demands``: This section contains the declaration of demands. This
  47    section with at least one demand should be defined in any Homing
  48    template, or the template would not really do anything when being
  49    instantiated.
  50 -  ``constraints``: This section contains the declaration of
  51    constraints. The section is optional and can be omitted when no input
  52    is required.
  53 -  ``reservations``: This section contains the declaration of required
  54    reservations. This section is optional and can be omitted when
  55    reservations are not required.
  56 -  ``optimization``: This section allows the declaration of an
  57    optimization. This section is optional and can be omitted when no
  58    input is required.
  59
  60 Homing Template Version
  61 -----------------------
  62
  63 The value of ``homing_template_version`` tells HAS not only the format
  64 of the template but also features that will be validated and supported.
  65 Only one value is supported: ``2017-10-10`` in the initial release of
  66 HAS.
  67
  68 .. code:: yaml
  69
  70     homing_template_version: 2017-10-10
  71
  72 Parameters
  73 ----------
  74
  75 The **parameters** section allows for specifying input parameters that
  76 have to be provided when instantiating the template. Such parameters are
  77 typically used for providing runtime inputs (like SLA thresholds), which
  78 in turn is used in the existing homing policies. This also helps build
  79 reusable homing constraints where these parameters can be embedded
  80 design time, and it corresponding values can be supplied during runtime.
  81
  82 Each parameter is specified with the name followed by its value. Values
  83 can be strings, lists, or dictionaries.
  84
  85 Example
  86 ~~~~~~~
  87
  88 In this example, ``provider_name`` is a string and ``service_info`` is a
  89 dictionary containing both a string and a list (keyed by ``base_url``
  90 and ``nod_config``, respectively).
  91
  92 .. code:: yaml
  93
  94     parameters:
  95       provider_name: multicloud
  96       service_info:
  97         base_url: http://serviceprovider.sdngc.com/
  98         nod_config:
  99         - http://nod/config_a.yaml
 100         - http://nod/config_b.yaml
 101         - http://nod/config_c.yaml
 102         - http://nod/config_d.yaml
 103
 104 A parameter can be referenced in place of any value. See the **Intrinsic
 105 Functions** section for more details.
 106
 107 Locations
 108 ---------
 109
 110 One or more **locations** may be declared. A location may be referenced
 111 by one or more ``constraints``. Locations may be defined in any of the
 112 following ways:
 113
 114 Coordinate
 115 ~~~~~~~~~~
 116
 117 A geographic coordinate expressed as a latitude and longitude.
 118
 119 +---------------+----------------------------+
 120 | Key           | Value                      |
 121 +===============+============================+
 122 | ``latitude``  | Latitude of the location.  |
 123 +---------------+----------------------------+
 124 | ``longitude`` | Longitude of the location. |
 125 +---------------+----------------------------+
 126
 127 Host Name
 128 ~~~~~~~~~
 129
 130 An opaque host name that can be translated to a coordinate via an
 131 inventory provider (e.g., A&AI).
 132
 133 +---------------+-----------------------------------+
 134 | Key           | Value                             |
 135 +===============+===================================+
 136 | ``host_name`` | Host name identifying a location. |
 137 +---------------+-----------------------------------+
 138
 139 CLLI
 140 ~~~~
 141
 142 Common Language Location Identification (CLLI)
 143 code(https://en.wikipedia.org/wiki/CLLI_code).
 144
 145 +---------------+-------------------+
 146 | Key           | Value             |
 147 +===============+===================+
 148 | ``clli_code`` | 8 character CLLI. |
 149 +---------------+-------------------+
 150
 151 **Questions**
 152
 153 -  Do we need functions that can convert one of these to the other?
 154    E.g., CLLI Codes to a latitude/longitude
 155
 156 Placemark
 157 ~~~~~~~~~
 158
 159 An address expressed in geographic region-agnostic terms (referred to as
 160 a *placemark*).
 161
 162 *Support for this schema is deferred.*
 163
 164 +-----------------------------------+----------------------------------+
 165 | Key                               | Value                            |
 166 +===================================+==================================+
 167 | ``iso_country_code``              | The abbreviated country name     |
 168 |                                   | associated with the placemark.   |
 169 +-----------------------------------+----------------------------------+
 170 | ``postal_code``                   | The postal code associated with  |
 171 |                                   | the placemark.                   |
 172 +-----------------------------------+----------------------------------+
 173 | ``administrative_area``           | The state or province associated |
 174 |                                   | with the placemark.              |
 175 +-----------------------------------+----------------------------------+
 176 | ``sub_administrative_area``       | Additional administrative area   |
 177 |                                   | information for the placemark.   |
 178 +-----------------------------------+----------------------------------+
 179 | ``locality``                      | The city associated with the     |
 180 |                                   | placemark.                       |
 181 +-----------------------------------+----------------------------------+
 182 | ``sub_locality``                  | Additional city-level            |
 183 |                                   | information for the placemark.   |
 184 +-----------------------------------+----------------------------------+
 185 | ``thoroughfare``                  | The street address associated    |
 186 |                                   | with the placemark.              |
 187 +-----------------------------------+----------------------------------+
 188 | ``sub_thoroughfare``              | Additional street-level          |
 189 |                                   | information for the placemark.   |
 190 +-----------------------------------+----------------------------------+
 191
 192 **Questions**
 193
 194 -  What geocoder can we use to convert placemarks to a
 195    latitude/longitude?
 196
 197 Examples
 198 ~~~~~~~~
 199
 200 The following examples illustrate a location expressed in coordinate,
 201 host_name, CLLI, and placemark, respectively.
 202
 203 .. code:: yaml
 204
 205     locations:
 206       location_using_coordinates:
 207         latitude: 32.897480
 208         longitude: -97.040443
 209
 210       host_location_using_host_name:
 211         host_name: USESTCDLLSTX55ANZ123
 212
 213       location_using_clli:
 214         clli_code: DLLSTX55
 215
 216       location_using_placemark:
 217         sub_thoroughfare: 1
 218         thoroughfare: ATT Way
 219         locality: Bedminster
 220         administrative_area: NJ
 221         postal_code: 07921-2694
 222
 223 Demands
 224 -------
 225
 226 A **demand** can be satisfied by using candidates drawn from
 227 inventories. Each demand is uniquely named. Inventory is considered to
 228 be opaque and can represent anything from which candidates can be drawn.
 229
 230 A demand’s resource requirements are determined by asking an **inventory
 231 provider** for one or more sets of **inventory candidates** against
 232 which the demand will be made. An explicit set of candidates may also be
 233 declared, for example, if the only candidates for a demand are
 234 predetermined.
 235
 236 Demand criteria is dependent upon the inventory provider in use.
 237
 238 **Provider-agnostic Schema**
 239
 240 +---------------------------------+------------------------------------+
 241 | Key                             | Value                              |
 242 +=================================+====================================+
 243 | ``inventory_provider``          | A HAS-supported inventory          |
 244 |                                 | provider.                          |
 245 +---------------------------------+------------------------------------+
 246 | ``inventory_type``              | The reserved word ``cloud`` (for   |
 247 |                                 | cloud regions) or the reserved     |
 248 |                                 | word ``service`` (for existing     |
 249 |                                 | service instances). Exactly one    |
 250 |                                 | inventory type may be specified.   |
 251 +---------------------------------+------------------------------------+
 252 | ``attributes`` (Optional)       | A list of key-value pairs, that is |
 253 |                                 | used to select inventory           |
 254 |                                 | candidates that match *all* the    |
 255 |                                 | specified attributes. The key      |
 256 |                                 | should be a uniquely identifiable  |
 257 |                                 | attribute at the inventory         |
 258 |                                 | provider.                          |
 259 +---------------------------------+------------------------------------+
 260 | ``service_type`` (Optional)     | If ``inventory_type`` is           |
 261 |                                 | ``service``, a list of one or more |
 262 |                                 | provider-defined service types. If |
 263 |                                 | only one service type is           |
 264 |                                 | specified, it may appear without   |
 265 |                                 | list markers (``[]``).             |
 266 +---------------------------------+------------------------------------+
 267 | ``service_id`` (Optional)       | If ``inventory_type`` is           |
 268 |                                 | ``service``, a list of one or more |
 269 |                                 | provider-defined service ids. If   |
 270 |                                 | only one service id is specified,  |
 271 |                                 | it may appear without list markers |
 272 |                                 | (``[]``).                          |
 273 +---------------------------------+------------------------------------+
 274 | ``default_cost`` (Optional)     | The default cost of an inventory   |
 275 |                                 | candidate, expressed as currency.  |
 276 |                                 | This must be specified if the      |
 277 |                                 | inventory provider may not always  |
 278 |                                 | return a cost.                     |
 279 +---------------------------------+------------------------------------+
 280 | ``required_candidates``         | A list of one or more candidates   |
 281 | (Optional)                      | from which a solution will be      |
 282 |                                 | explored. Must be a valid          |
 283 |                                 | candidate as described in the      |
 284 |                                 | **candidate schema**.              |
 285 +---------------------------------+------------------------------------+
 286 | ``excluded_candidates``         | A list of one or more candidates   |
 287 | (Optional)                      | that should be excluded from the   |
 288 |                                 | search space. Must be a valid      |
 289 |                                 | candidate as described in the      |
 290 |                                 | **candidate schema**.              |
 291 +---------------------------------+------------------------------------+
 292 | ``existing_placement``          | The current placement for the      |
 293 | (Optional)                      | demand. Must be a valid candidate  |
 294 |                                 | as described in the **candidate    |
 295 |                                 | schema**.                          |
 296 +---------------------------------+------------------------------------+
 297
 298 .. _examples-1:
 299
 300 Examples
 301 ~~~~~~~~
 302
 303 The following example helps understand a demand specification using
 304 Active & Available Inventory (A&AI), the inventory provider-of-record
 305 for ONAP.
 306
 307 **Inventory Provider Criteria**
 308
 309 +---------------------------------+------------------------------------+
 310 | Key                             | Value                              |
 311 +=================================+====================================+
 312 | ``inventory_provider``          | Examples: ``aai``, ``multicloud``. |
 313 +---------------------------------+------------------------------------+
 314 | ``inventory_type``              | The reserved word ``cloud`` (for   |
 315 |                                 | new inventory) or the reserved     |
 316 |                                 | word ``service`` (for existing     |
 317 |                                 | inventory). Exactly one inventory  |
 318 |                                 | type may be specified.             |
 319 +---------------------------------+------------------------------------+
 320 | ``attributes`` (Optional)       | A list of key-value pairs to match |
 321 |                                 | against inventory when drawing     |
 322 |                                 | candidates.                        |
 323 +---------------------------------+------------------------------------+
 324 | ``service_type`` (Optional)     | Examples may include ``vG``,       |
 325 |                                 | ``vG_MuxInfra``, etc.              |
 326 +---------------------------------+------------------------------------+
 327 | ``service_id`` (Optional)       | Must be a valid service id.        |
 328 |                                 | Examples may include ``vCPE``,     |
 329 |                                 | ``VoLTE``, etc.                    |
 330 +---------------------------------+------------------------------------+
 331 | ``default_cost`` (Optional)     | The default cost of an inventory   |
 332 |                                 | candidate, expressed as a unitless |
 333 |                                 | number.                            |
 334 +---------------------------------+------------------------------------+
 335 | ``required_candidates``         | A list of one or more valid        |
 336 | (Optional)                      | candidates. See **Candidate        |
 337 |                                 | Schema** for details.              |
 338 +---------------------------------+------------------------------------+
 339 | ``excluded_candidates``         | A list of one or more valid        |
 340 | (Optional)                      | candidates. See **Candidate        |
 341 |                                 | Schema** for details.              |
 342 +---------------------------------+------------------------------------+
 343 | ``existing_placement``          | A single valid candidate,          |
 344 | (Optional)                      | representing the current placement |
 345 |                                 | for the demand. See **candidate    |
 346 |                                 | schema** for details.              |
 347 +---------------------------------+------------------------------------+
 348
 349 **Candidate Schema**
 350
 351 The following is the schema for a valid ``candidate``: \*
 352 ``candidate_id`` uniquely identifies a candidate. Currently, it is
 353 either a Service Instance ID or Cloud Region ID. \* ``candidate_type``
 354 identifies the type of the candidate. Currently, it is either ``cloud``
 355 or ``service``. \* ``inventory_type`` is defined as described in
 356 **Inventory Provider Criteria** (above). \* ``inventory_provider``
 357 identifies the inventory from which the candidate was drawn. \*
 358 ``host_id`` is an ID of a specific host (used only when referring to
 359 service/existing inventory). \* ``cost`` is expressed as a unitless
 360 number. \* ``location_id`` is always a location ID of the specified
 361 location type (e.g., for a type of ``cloud`` this will be an Cloud
 362 Region ID). \* ``location_type`` is an inventory provider supported
 363 location type. \* ``latitude`` is a valid latitude corresponding to the
 364 *location_id*. \* ``longitude`` is a valid longitude corresponding to
 365 the *location_id*. \* ``city`` (Optional) city corresponding to the
 366 *location_id*. \* ``state`` (Optional) state corresponding to the
 367 *location_id*. \* ``country`` (Optional) country corresponding to the
 368 *location_id*. \* ``region`` (Optional) geographic region corresponding
 369 to the *location_id*. \* ``complex_name`` (Optional) Name of the complex
 370 corresponding to the *location_id*. \* ``cloud_owner`` (Optional) refers
 371 to the *cloud owner* (e.g., ``azure``, ``aws``, ``att``, etc.). \*
 372 ``cloud_region_version`` (Optional) is an inventory provider supported
 373 version of the cloud region. \* ``physical_location_id`` (Optional) is
 374 an inventory provider supported CLLI code corresponding to the cloud
 375 region.
 376
 377 **Examples**
 378
 379 .. code:: json
 380
 381     {
 382         "candidate_id": "1ac71fb8-ad43-4e16-9459-c3f372b8236d",
 383         "candidate_type": "service",
 384         "inventory_type": "service",
 385         "inventory_provider": "aai",
 386         "host_id": "vnf_123456",
 387         "cost": "100",
 388         "location_id": "DLLSTX9A",
 389         "location_type": "azure",
 390         "latitude": "32.897480",
 391         "longitude": "-97.040443",
 392         "city": "Dallas",
 393         "state": "TX",
 394         "country": "USA",
 395         "region": "US",
 396         "complex_name": "dalls_one",
 397         "cloud_owner": "att-aic",
 398         "cloud_region_version": "1.1",
 399         "physical_location_id": "DLLSTX9A",
 400     }
 401
 402 **Questions** \* Currently, candidates are either service instances or
 403 cloud regions. As new services are on-boarded, this can be evolved to
 404 represent different types of resources.
 405
 406 **Examples**
 407
 408 The following examples illustrate two demands:
 409
 410 -  ``vGMuxInfra``: A vGMuxInfra service, drawing candidates of type
 411    *service* from the inventory. Only candidates that match the
 412    customer_id and orchestration-status will be included in the search
 413    space.
 414 -  ``vG``: A vG, drawing candidates of type *service* and *cloud* from
 415    the inventory. Only candidates that match the customer_id and
 416    provisioning-status will be included in the search space.
 417
 418 .. code:: yaml
 419
 420     demands:
 421       vGMuxInfra:
 422       - inventory_provider: aai
 423         inventory_type: service
 424         attributes:
 425           equipment_type: vG_Mux
 426           customer_id: some_company
 427           orchestration-status: Activated
 428           model-id: 174e371e-f514-4913-a93d-ed7e7f8fbdca
 429           model-version: 2.0
 430       vG:
 431       - inventory_provider: aai
 432         inventory_type: service
 433         attributes:
 434           equipment_type: vG
 435           customer_id: some_company
 436           provisioning-status: provisioned
 437       - inventory_provider: aai
 438         inventory_type: cloud
 439
 440 **Questions** \* Do we need to support cost as a function ?
 441
 442 Constraints
 443 -----------
 444
 445 A **Constraint** is used to *eliminate* inventory candidates from one or
 446 more demands that do not meet the requirements specified by the
 447 constraint. Since reusability is one of the cornerstones of HAS,
 448 Constraints are designed to be service-agnostic, and is parameterized
 449 such that it can be reused across a wide range of services. Further, HAS
 450 is designed with a plug-in architecture that facilitates easy addition
 451 of new constraint types.
 452
 453 Constraints are denoted by a ``constraints`` key. Each constraint is
 454 uniquely named and set to a dictionary containing a constraint type, a
 455 list of demands to apply the constraint to, and a dictionary of
 456 constraint properties.
 457
 458 **Considerations while using multiple constraints** \* Constraints
 459 should be treated as a unordered list, and no assumptions should be made
 460 as regards to the order in which the constraints are evaluated for any
 461 given demand. \* All constraints are effectively AND-ed together.
 462 Constructs such as “Constraint X OR Y” are unsupported. \* Constraints
 463 are reducing in nature, and does not increase the available candidates
 464 at any point during the constraint evaluations.
 465
 466 **Schema**
 467
 468 +-------------------------------------------+--------------------------+
 469 | Key                                       | Value                    |
 470 +===========================================+==========================+
 471 | ``CONSTRAINT_NAME``                       | Key is a unique name.    |
 472 +-------------------------------------------+--------------------------+
 473 | ``type``                                  | The type of constraint.  |
 474 |                                           | See **Constraint Types** |
 475 |                                           | for a list of currently  |
 476 |                                           | supported values.        |
 477 +-------------------------------------------+--------------------------+
 478 | ``demands``                               | One or more previously   |
 479 |                                           | declared demands. If     |
 480 |                                           | only one demand is       |
 481 |                                           | specified, it may appear |
 482 |                                           | without list markers     |
 483 |                                           | (``[]``).                |
 484 +-------------------------------------------+--------------------------+
 485 | ``properties`` (Optional)                 | Properties particular to |
 486 |                                           | the specified constraint |
 487 |                                           | type. Use if required by |
 488 |                                           | the constraint.          |
 489 +-------------------------------------------+--------------------------+
 490
 491 .. code:: yaml
 492
 493     constraints:
 494       CONSTRAINT_NAME_1:
 495         type: CONSTRAINT_TYPE
 496         demands: DEMAND_NAME | [DEMAND_NAME_1, DEMAND_NAME_2, ...]
 497         properties: PROPERTY_DICT
 498
 499       CONSTRAINT_NAME_2:
 500         type: CONSTRAINT_TYPE
 501         demands: DEMAND_NAME | [DEMAND_NAME_1, DEMAND_NAME_2, ...]
 502         properties: PROPERTY_DICT
 503
 504       ...
 505
 506 Constraint Types
 507 ~~~~~~~~~~~~~~~~
 508
 509 +-------------------------------------------+--------------------------+
 510 | Type                                      | Description              |
 511 +===========================================+==========================+
 512 | ``attribute``                             | Constraint that matches  |
 513 |                                           | the specified list of    |
 514 |                                           | Attributes.              |
 515 +-------------------------------------------+--------------------------+
 516 | ``distance_between_demands``              | Geographic distance      |
 517 |                                           | constraint between each  |
 518 |                                           | pair of a list of        |
 519 |                                           | demands.                 |
 520 +-------------------------------------------+--------------------------+
 521 | ``distance_to_location``                  | Geographic distance      |
 522 |                                           | constraint between each  |
 523 |                                           | of a list of demands and |
 524 |                                           | a specific location.     |
 525 +-------------------------------------------+--------------------------+
 526 | ``instance_fit``                          | Constraint that ensures  |
 527 |                                           | available capacity in an |
 528 |                                           | existing service         |
 529 |                                           | instance for an incoming |
 530 |                                           | demand.                  |
 531 +-------------------------------------------+--------------------------+
 532 | ``inventory_group``                       | Constraint that enforces |
 533 |                                           | two or more demands are  |
 534 |                                           | satisfied using          |
 535 |                                           | candidates from a        |
 536 |                                           | pre-established group in |
 537 |                                           | the inventory.           |
 538 +-------------------------------------------+--------------------------+
 539 | ``region_fit``                            | Constraint that ensures  |
 540 |                                           | available capacity in an |
 541 |                                           | existing cloud region    |
 542 |                                           | for an incoming demand.  |
 543 +-------------------------------------------+--------------------------+
 544 | ``zone``                                  | Constraint that enforces |
 545 |                                           | co-location/diversity at |
 546 |                                           | the granularities of     |
 547 |                                           | clouds/regions/availabil |
 548 |                                           | ity-zones.               |
 549 +-------------------------------------------+--------------------------+
 550 | ``license`` (Deferred)                    | License availability     |
 551 |                                           | constraint.              |
 552 +-------------------------------------------+--------------------------+
 553 | ``network_between_demands`` (Deferred)    | Network constraint       |
 554 |                                           | between each pair of a   |
 555 |                                           | list of demands.         |
 556 +-------------------------------------------+--------------------------+
 557 | ``network_to_location`` (Deferred)        | Network constraint       |
 558 |                                           | between each of a list   |
 559 |                                           | of demands and a         |
 560 |                                           | specific                 |
 561 |                                           | location/address.        |
 562 +-------------------------------------------+--------------------------+
 563
 564 *Note: Constraint names marked “Deferred” **will not** be supported in
 565 the initial release of HAS.*
 566
 567 Threshold Values
 568 ~~~~~~~~~~~~~~~~
 569
 570 Constraint property values representing a threshold may be an integer or
 571 floating point number, optionally prefixed with a comparison operator:
 572 ``=``, ``<``, ``>``, ``<=``, or ``>=``. The default is ``=`` and
 573 optionally suffixed with a unit.
 574
 575 Whitespace may appear between the comparison operator and value, and
 576 between the value and units. When a range values is specified (e.g.,
 577 ``10-20 km``), the comparison operator is omitted.
 578
 579 Each property is documented with a default unit. The following units are
 580 supported:
 581
 582 +------------+------------------------------+----------+
 583 | Unit       | Values                       | Default  |
 584 +============+==============================+==========+
 585 | Currency   | ``USD``                      | ``USD``  |
 586 +------------+------------------------------+----------+
 587 | Time       | ``ms``, ``sec``              | ``ms``   |
 588 +------------+------------------------------+----------+
 589 | Distance   | ``km``, ``mi``               | ``km``   |
 590 +------------+------------------------------+----------+
 591 | Throughput | ``Kbps``, ``Mbps``, ``Gbps`` | ``Mbps`` |
 592 +------------+------------------------------+----------+
 593
 594 Attribute
 595 ~~~~~~~~~
 596
 597 Constrain one or more demands by one or more attributes, expressed as
 598 properties. Attributes are mapped to the **inventory provider**
 599 specified properties, referenced by the demands. For example, properties
 600 could be hardware capabilities provided by the platform (flavor,
 601 CPU-Pinning, NUMA), features supported by the services, etc.
 602
 603 **Schema**
 604
 605 +------------+---------------------------------------------------------+
 606 | Property   | Value                                                   |
 607 +============+=========================================================+
 608 | ``evaluate | Opaque dictionary of attribute name and value pairs.    |
 609 | ``         | Values must be strings or numbers. Encoded and sent to  |
 610 |            | the service provider via a plugin.                      |
 611 +------------+---------------------------------------------------------+
 612
 613 *Note: Attribute values are not detected/parsed as thresholds by the
 614 Homing framework. Such interpretations and evaluations are inventory
 615 provider-specific and delegated to the corresponding plugin*
 616
 617 .. code:: yaml
 618
 619     constraints:
 620       sriov_nj:
 621         type: attribute
 622         demands: [my_vnf_demand, my_other_vnf_demand]
 623         properties:
 624           evaluate:
 625             cloud_version: 1.1
 626             flavor: SRIOV
 627             subdivision: US-TX
 628             vcpu_pinning: True
 629             numa_topology: numa_spanning
 630
 631 Proposal: Evaluation Operators
 632 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 633
 634 To assist in evaluating attributes, the following operators and notation
 635 are proposed:
 636
 637 +-----------+-----------+------------------------------------------------+
 638 | Operator  | Name      | Operand                                        |
 639 +===========+===========+================================================+
 640 | ``eq``    | ``==``    | Any object (string, number, list, dict)        |
 641 +-----------+-----------+------------------------------------------------+
 642 | ``ne``    | ``!=``    |                                                |
 643 +-----------+-----------+------------------------------------------------+
 644 | ``lt``    | ``<``     | A number (strings are converted to float)      |
 645 +-----------+-----------+------------------------------------------------+
 646 | ``gt``    | ``>``     |                                                |
 647 +-----------+-----------+------------------------------------------------+
 648 | ``lte``   | ``<=``    |                                                |
 649 +-----------+-----------+------------------------------------------------+
 650 | ``gte``   | ``>=``    |                                                |
 651 +-----------+-----------+------------------------------------------------+
 652 | ``any``   | ``Any``   | A list of objects (string, number, list, dict) |
 653 +-----------+-----------+------------------------------------------------+
 654 | ``all``   | ``All``   |                                                |
 655 +-----------+-----------+------------------------------------------------+
 656 | ``regex`` | ``RegEx`` | A regular expression pattern                   |
 657 +-----------+-----------+------------------------------------------------+
 658
 659 Example usage:
 660
 661 .. code:: yaml
 662
 663     constraints:
 664       sriov_nj:
 665         type: attribute
 666         demands: [my_vnf_demand, my_other_vnf_demand]
 667         properties:
 668           evaluate:
 669             cloud_version: {gt: 1.0}
 670             flavor: {regex: /^SRIOV$/i}
 671             subdivision: {any: [US-TX, US-NY, US-CA]}
 672
 673 Distance Between Demands
 674 ~~~~~~~~~~~~~~~~~~~~~~~~
 675
 676 Constrain each pairwise combination of two or more demands by distance
 677 requirements.
 678
 679 **Schema**
 680
 681 +--------------+------------------------------------------------------------+
 682 | Name         | Value                                                      |
 683 +==============+============================================================+
 684 | ``distance`` | Distance between demands, measured by the geographic path. |
 685 +--------------+------------------------------------------------------------+
 686
 687 The constraint is applied between each pairwise combination of demands.
 688 For this reason, at least two demands must be specified, implicitly or
 689 explicitly.
 690
 691 .. code:: yaml
 692
 693     constraints:
 694       distance_vnf1_vnf2:
 695         type: distance_between_demands
 696         demands: [my_vnf_demand, my_other_vnf_demand]
 697         properties:
 698           distance: < 250 km
 699
 700 Distance To Location
 701 ~~~~~~~~~~~~~~~~~~~~
 702
 703 Constrain one or more demands by distance requirements relative to a
 704 specific location.
 705
 706 **Schema**
 707
 708 +--------------+------------------------------------------------------------+
 709 | Property     | Value                                                      |
 710 +==============+============================================================+
 711 | ``distance`` | Distance between demands, measured by the geographic path. |
 712 +--------------+------------------------------------------------------------+
 713 | ``location`` | A previously declared location.                            |
 714 +--------------+------------------------------------------------------------+
 715
 716 The constraint is applied between each demand and the referenced
 717 location, not across all pairwise combinations of Demands.
 718
 719 .. code:: yaml
 720
 721     constraints:
 722       distance_vnf1_loc:
 723         type: distance_to_location
 724         demands: [my_vnf_demand, my_other_vnf_demand, another_vnf_demand]
 725         properties:
 726           distance: < 250 km
 727           location: LOCATION_ID
 728
 729 Instance Fit
 730 ~~~~~~~~~~~~
 731
 732 Constrain each demand by its service requirements.
 733
 734 Requirements are sent as a request to a **service controller**. Service
 735 controllers are defined by plugins in Homing (e.g., ``sdn-c``).
 736
 737 A service controller plugin knows how to communicate with a particular
 738 endpoint (via HTTP/REST, DMaaP, etc.), obtain necessary information, and
 739 make a decision. The endpoint and credentials can be configured through
 740 plugin settings.
 741
 742 **Schema**
 743
 744 +---------------------+------------------------------------------------+
 745 | Property            | Description                                    |
 746 +=====================+================================================+
 747 | ``controller``      | Name of a service controller.                  |
 748 +---------------------+------------------------------------------------+
 749 | ``request``         | Opaque dictionary of key/value pairs. Values   |
 750 |                     | must be strings or numbers. Encoded and sent   |
 751 |                     | to the service provider via a plugin.          |
 752 +---------------------+------------------------------------------------+
 753
 754 .. code:: yaml
 755
 756     constraints:
 757       check_for_availability:
 758         type: instance_fit
 759         demands: [my_vnf_demand, my_other_vnf_demand]
 760         properties:
 761           controller: sdn-c
 762           request: REQUEST_DICT
 763
 764 Region Fit
 765 ~~~~~~~~~~
 766
 767 Constrain each demand’s inventory candidates based on inventory provider
 768 membership.
 769
 770 Requirements are sent as a request to a **service controller**. Service
 771 controllers are defined by plugins in Homing (e.g., ``sdn-c``).
 772
 773 A service controller plugin knows how to communicate with a particular
 774 endpoint (via HTTP/REST, DMaaP, etc.), obtain necessary information, and
 775 make a decision. The endpoint and credentials can be configured through
 776 plugin settings.
 777
 778 **Schema**
 779
 780 +---------------------+------------------------------------------------+
 781 | Property            | Description                                    |
 782 +=====================+================================================+
 783 | ``controller``      | Name of a service controller.                  |
 784 +---------------------+------------------------------------------------+
 785 | ``request``         | Opaque dictionary of key/value pairs. Values   |
 786 |                     | must be strings or numbers. Encoded and sent   |
 787 |                     | to the service provider via a plugin.          |
 788 +---------------------+------------------------------------------------+
 789
 790 .. code:: yaml
 791
 792     constraints:
 793       check_for_membership:
 794         type: region_fit
 795         demands: [my_vnf_demand, my_other_vnf_demand]
 796         properties:
 797           controller: sdn-c
 798           request: REQUEST_DICT
 799
 800 Zone
 801 ~~~~
 802
 803 Constrain two or more demands such that each is located in the same or
 804 different zone category.
 805
 806 Zone categories are inventory provider-defined, based on the demands
 807 being constrained.
 808
 809 **Schema**
 810
 811 +-------------+--------------------------------------------------------+
 812 | Property    | Value                                                  |
 813 +=============+========================================================+
 814 | ``qualifier | Zone qualifier. One of ``same`` or ``different``.      |
 815 | ``          |                                                        |
 816 +-------------+--------------------------------------------------------+
 817 | ``category` | Zone category. One of ``disaster``, ``region``,        |
 818 | `           | ``complex``, ``time``, or ``maintenance``.             |
 819 +-------------+--------------------------------------------------------+
 820
 821 For example, to place two demands in different disaster zones:
 822
 823 .. code:: yaml
 824
 825     constraints:
 826       vnf_diversity:
 827         type: zone
 828         demands: [my_vnf_demand, my_other_vnf_demand]
 829         properties:
 830           qualifier: different
 831           category: disaster
 832
 833 Or, to place two demands in the same region:
 834
 835 .. code:: yaml
 836
 837     constraints:
 838       vnf_affinity:
 839         type: zone
 840         demands: [my_vnf_demand, my_other_vnf_demand]
 841         properties:
 842           qualifier: same
 843           category: region
 844
 845 **Notes**
 846
 847 -  These categories could be any of the following: ``disaster_zone``,
 848    ``region``, ``complex``, ``time_zone``, and ``maintenance_zone``.
 849    Really, we are talking affinity/anti-affinity at the level of DCs,
 850    but these terms may cause confusion with affinity/anti-affinity in
 851    OpenStack.
 852
 853 Inventory Group
 854 ~~~~~~~~~~~~~~~
 855
 856 Constrain demands such that inventory items are grouped across two
 857 demands.
 858
 859 This constraint has no properties.
 860
 861 .. code:: yaml
 862
 863     constraints:
 864       my_group:
 865         type: inventory_group
 866         demands: [demand_1, demand_2]
 867
 868 *Note: Only pair-wise groups are supported at this time. If three or
 869 more demands are specified, only the first two will be used.*
 870
 871 License
 872 ~~~~~~~
 873
 874 Constrain demands according to license availability.
 875
 876 *Support for this constraint is deferred.*
 877
 878 **Schema**
 879
 880 +----------+----------------------------------------------------------+
 881 | Property | Value                                                    |
 882 +==========+==========================================================+
 883 | ``id``   | Unique license identifier                                |
 884 +----------+----------------------------------------------------------+
 885 | ``key``  | Opaque license key, particular to the license identifier |
 886 +----------+----------------------------------------------------------+
 887
 888 .. code:: yaml
 889
 890     constraints:
 891       my_software:
 892         type: license
 893         demands: [demand_1, demand_2, ...]
 894         properties:
 895           id: SOFTWARE_ID
 896           key: LICENSE_KEY
 897
 898 Network Between Demands
 899 ~~~~~~~~~~~~~~~~~~~~~~~
 900
 901 Constrain each pairwise combination of two or more demands by network
 902 requirements.
 903
 904 *Support for this constraint is deferred.*
 905
 906 **Schema**
 907
 908 +-------------------+--------------------------------------------------+
 909 | Property          | Value                                            |
 910 +===================+==================================================+
 911 | ``bandwidth``     | Desired network bandwidth.                       |
 912 | (Optional)        |                                                  |
 913 +-------------------+--------------------------------------------------+
 914 | ``distance``      | Desired distance between demands, measured by    |
 915 | (Optional)        | the network path.                                |
 916 +-------------------+--------------------------------------------------+
 917 | ``latency``       | Desired network latency.                         |
 918 | (Optional)        |                                                  |
 919 +-------------------+--------------------------------------------------+
 920
 921 Any combination of ``bandwidth``, ``distance``, or ``latency`` must be
 922 specified. If none of these properties are used, it is treated as a
 923 malformed request.
 924
 925 The constraint is applied between each pairwise combination of demands.
 926 For this reason, at least two demands must be specified, implicitly or
 927 explicitly.
 928
 929 .. code:: yaml
 930
 931     constraints:
 932       network_requirements:
 933         type: network_between_demands
 934         demands: [my_vnf_demand, my_other_vnf_demand]
 935         properties:
 936           bandwidth: >= 1000 Mbps
 937           distance: < 250 km
 938           latency: < 50 ms
 939
 940 Network To Location
 941 ~~~~~~~~~~~~~~~~~~~
 942
 943 Constrain one or more demands by network requirements relative to a
 944 specific location.
 945
 946 *Support for this constraint is deferred.*
 947
 948 **Schema**
 949
 950 +-----------------------------------+-----------------------------------+
 951 | Property                          | Value                             |
 952 +===================================+===================================+
 953 | ``bandwidth``                     | Desired network bandwidth.        |
 954 +-----------------------------------+-----------------------------------+
 955 | ``distance``                      | Desired distance between demands, |
 956 |                                   | measured by the network path.     |
 957 +-----------------------------------+-----------------------------------+
 958 | ``latency``                       | Desired network latency.          |
 959 +-----------------------------------+-----------------------------------+
 960 | ``location``                      | A previously declared location.   |
 961 +-----------------------------------+-----------------------------------+
 962
 963 Any combination of ``bandwidth``, ``distance``, or ``latency`` must be
 964 specified. If none of these properties are used, it is treated as a
 965 malformed request.
 966
 967 The constraint is applied between each demand and the referenced
 968 location, not across all pairwise combinations of Demands.
 969
 970 .. code:: yaml
 971
 972     constraints:
 973       my_access_network_constraint:
 974         type: network_to_location
 975         demands: [my_vnf_demand, my_other_vnf_demand]
 976         properties:
 977           bandwidth: >= 1000 Mbps
 978           distance: < 250 km
 979           latency: < 50 ms
 980           location: LOCATION_ID
 981
 982 Capabilities
 983 ~~~~~~~~~~~~
 984
 985 Constrain each demand by its cluster capability requirements. For
 986 example, as described by an OpenStack Heat template and operational
 987 environment.
 988
 989 *Support for this constraint is deferred.*
 990
 991 **Schema**
 992
 993 +------------+---------------------------------------------------------+
 994 | Property   | Value                                                   |
 995 +============+=========================================================+
 996 | ``specific | Indicates the kind of specification being provided in   |
 997 | ation``    | the properties. Must be ``heat``. Future values may     |
 998 |            | include ``tosca``, ``Homing``, etc.                     |
 999 +------------+---------------------------------------------------------+
1000 | ``template | For specifications of type ``heat``, a single stack in  |
1001 | ``         | OpenStack Heat Orchestration Template (HOT) format.     |
1002 |            | Stacks may be expressed as a URI reference or a string  |
1003 |            | of well-formed YAML/JSON. Templates are validated by    |
1004 |            | the Heat service configured for use by HAS. Nested      |
1005 |            | stack references are unsupported.                       |
1006 +------------+---------------------------------------------------------+
1007 | ``environm | For specifications of type ``heat``, an optional Heat   |
1008 | ent``      | environment. Environments may be expressed as a URI     |
1009 | (Optional) | reference or a string of well-formed YAML/JSON.         |
1010 |            | Environments are validated by the Heat service          |
1011 |            | configured for use by Homing.                           |
1012 +------------+---------------------------------------------------------+
1013
1014 .. code:: yaml
1015
1016     constraints:
1017       check_for_fit:
1018         type: capability
1019         demands: [my_vnf_demand, my_other_vnf_demand]
1020         properties:
1021           specification: heat
1022           template: http://repository/my/stack_template
1023           environment: http://repository/my/stack_environment
1024
1025 Reservations
1026 ------------
1027
1028 A **Reservation** allows reservation of resources associated with
1029 candidate that satisfies one or more demands.
1030
1031 Similar to the *instance_fit* constraint, requirements are sent as a
1032 request to a **service controller** that handles the reservation.
1033 Service controllers are defined by plugins in Homing (e.g., ``sdn-c``).
1034
1035 The service controller plugin knows how to make a reservation (and
1036 initiate rollback on a failure) with a particular endpoint (via
1037 HTTP/REST, DMaaP, etc.) of the service controller. The endpoint and
1038 credentials can be configured through plugin settings.
1039
1040 **Schema**
1041
1042 +---------------------+------------------------------------------------+
1043 | Property            | Description                                    |
1044 +=====================+================================================+
1045 | ``controller``      | Name of a service controller.                  |
1046 +---------------------+------------------------------------------------+
1047 | ``request``         | Opaque dictionary of key/value pairs. Values   |
1048 |                     | must be strings or numbers. Encoded and sent   |
1049 |                     | to the service provider via a plugin.          |
1050 +---------------------+------------------------------------------------+
1051
1052 .. code:: yaml
1053
1054     resource_reservation:
1055       type: instance_reservation
1056       demands: [my_vnf_demand, my_other_vnf_demand]
1057       properties:
1058         controller: sdn-c
1059         request: REQUEST_DICT
1060
1061 Optimizations
1062 -------------
1063
1064 An **Optimization** allows specification of a objective function, which
1065 aims to maximize or minimize a certain value that varies based on the
1066 choice of candidates for one or more demands that are a part of the
1067 objective function. For example, an objective function may be to find
1068 the *closest* cloud-region to a customer to home a demand.
1069
1070 Optimization Components
1071 ~~~~~~~~~~~~~~~~~~~~~~~
1072
1073 Optimization definitions can be broken down into three components:
1074
1075 +-------+----------------+--------------------------------------------+
1076 | Compo | Key            | Value                                      |
1077 | nent  |                |                                            |
1078 +=======+================+============================================+
1079 | Goal  | ``minimize``   | A single Operand (usually ``sum``) or      |
1080 |       |                | Function                                   |
1081 +-------+----------------+--------------------------------------------+
1082 | Opera | ``sum``,       | Two or more Operands (Numbers, Operators,  |
1083 | tor   | ``product``    | Functions)                                 |
1084 +-------+----------------+--------------------------------------------+
1085 | Funct | ``distance_bet | A two-element list consisting of a         |
1086 | ion   | ween``         | location and demand.                       |
1087 +-------+----------------+--------------------------------------------+
1088
1089 .. _example-1:
1090
1091 Example
1092 ~~~~~~~
1093
1094 Given a customer location ``cl``, two demands ``vG1`` and ``vG2``, and
1095 weights ``w1`` and ``w2``, the optimization criteria can be expressed
1096 as:
1097
1098 ``minimize(weight1 * distance_between(cl, vG1) + weight2 * distance_between(cl, vG2))``
1099
1100 This can be read as: “Minimize the sum of weighted distances from cl to
1101 vG1 and from cl to vG2.”
1102
1103 Such optimizations may be expressed in a template as follows:
1104
1105 .. code:: yaml
1106
1107     parameters:
1108       w1: 10
1109       w2: 20
1110
1111     optimization:
1112       minimize:
1113         sum:
1114         - product:
1115           - {get_param: w1}
1116           - {distance_between: [cl, vG1]}
1117         - product:
1118           - {get_param: w2}
1119           - {distance_between: [cl, vG2]}
1120
1121 Or without the weights as:
1122
1123 .. code:: yaml
1124
1125     optimization:
1126       minimize:
1127         sum:
1128         - {distance_between: [cl, vG1]}
1129         - {distance_between: [cl, vG2]}
1130
1131 **Template Restriction**
1132
1133 While the template format supports any number of arrangements of
1134 numbers, operators, and functions, HAS’s solver presently expects a very
1135 specific arrangement.
1136
1137 Until further notice:
1138
1139 -  Optimizations must conform to a single goal of ``minimize`` followed
1140    by a ``sum`` operator.
1141 -  The sum can consist of two ``distance_between`` function calls, or
1142    two ``product`` operators.
1143 -  If a ``product`` operator is present, it must contain at least a
1144    ``distance_between`` function call, plus one optional number to be
1145    used for weighting.
1146 -  Numbers may be referenced via ``get_param``.
1147 -  The objective function has to be written in the sum-of-product
1148    format. In the future, HAS can convert product-of-sum into
1149    sum-of-product automatically.
1150
1151 The first two examples in this section illustrate both of these use
1152 cases.
1153
1154 **Inline Operations**
1155
1156 If desired, operations can be rewritten inline. For example, the two
1157 ``product`` operations from the previous example can also be expressed
1158 as:
1159
1160 .. code:: yaml
1161
1162     parameters:
1163       w1: 10
1164       w2: 20
1165
1166     optimization:
1167       minimize:
1168         sum:
1169         - {product: [{get_param: w1}, {distance_between: [cl, vG1]}]}
1170         - {product: [{get_param: w2}, {distance_between: [cl, vG2]}]}
1171
1172 In turn, even the ``sum`` operation can be rewritten inline, however
1173 there is a point of diminishing returns in terms of readability!
1174
1175 **Notes**
1176
1177 -  In the first version, we do not support more than one dimension in
1178    the optimization (e.g., Minimize distance and cost). For supporting
1179    multiple dimensions we would need a function the normalize the unit
1180    across dimensions.
1181
1182 Intrinsic Functions
1183 -------------------
1184
1185 Homing provides a set of intrinsic functions that can be used inside
1186 templates to perform specific tasks. The following section describes the
1187 role and syntax of the intrinsic functions.
1188
1189 Functions are written as a dictionary with one key/value pair. The key
1190 is the function name. The value is a list of arguments. If only one
1191 argument is provided, a string may be used instead.
1192
1193 .. code:: yaml
1194
1195     a_property: {FUNCTION_NAME: [ARGUMENT_LIST]}
1196
1197     a_property: {FUNCTION_NAME: ARGUMENT_STRING}
1198
1199 *Note: These functions can only be used within “properties” sections.*
1200
1201 get_file
1202 ~~~~~~~~
1203
1204 The ``get_file`` function inserts the content of a file into the
1205 template. It is generally used as a file inclusion mechanism for files
1206 containing templates from other services (e.g., Heat).
1207
1208 The syntax of the ``get_file`` function is:
1209
1210 .. code:: yaml
1211
1212     {get_file: <content key>}
1213
1214 The ``content`` key is used to look up the ``files`` dictionary that is
1215 provided in the REST API call. The Homing client command (``Homing``) is
1216 ``get_file`` aware and populates the ``files`` dictionary with the
1217 actual content of fetched paths and URLs. The Homing client command
1218 supports relative paths and transforms these to the absolute URLs
1219 required by the Homing API.
1220
1221 **Note**: The ``get_file`` argument must be a static path or URL and not
1222 rely on intrinsic functions like ``get_param``. The Homing client does
1223 not process intrinsic functions. They are only processed by the Homing
1224 engine.
1225
1226 The example below demonstrates the ``get_file`` function usage with both
1227 relative and absolute URLs:
1228
1229 .. code:: yaml
1230
1231     constraints:
1232       check_for_fit:
1233         type: capacity
1234         demands: [my_vnf_demand, my_other_vnf_demand]
1235         properties:
1236           template: {get_file: stack_template.yaml}
1237           environment: {get_file: http://hostname/environment.yaml}
1238
1239 The ``files`` dictionary generated by the Homing client during
1240 instantiation of the plan would contain the following keys. Each value
1241 would be of that file’s contents.
1242
1243 -  ``file:///path/to/stack_template.yaml``
1244 -  ``http://hostname/environment.yaml``
1245
1246 **Questions**
1247
1248 -  If Homing will only be accessed over DMaaP, files will need to be
1249    embedded using the Homing API request format.
1250
1251 get_param
1252 ~~~~~~~~~
1253
1254 The ``get_param`` function references an input parameter of a template.
1255 It resolves to the value provided for this input parameter at runtime.
1256
1257 The syntax of the ``get_param`` function is:
1258
1259 .. code:: yaml
1260
1261     {get_param: <parameter name>}
1262
1263     {get_param: [<parameter name>, <key/index1> (optional), <key/index2> (optional), ...]}
1264
1265 **parameter name** is the parameter name to be resolved. If the
1266 parameters returns a complex data structure such as a list or a dict,
1267 then subsequent keys or indices can be specified. These additional
1268 parameters are used to navigate the data structure to return the desired
1269 value. Indices are zero-based.
1270
1271 The following example demonstrates how the ``get_param`` function is
1272 used:
1273
1274 .. code:: yaml
1275
1276     parameters:
1277       software_id: SOFTWARE_ID
1278       license_key: LICENSE_KEY
1279       service_info:
1280         provider: dmaap:///full.topic.name
1281         costs: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
1282
1283     constraints:
1284       my_software:
1285         type: license
1286         demands: [demand_1, demand_2, ...]
1287         properties:
1288           id: {get_param: software_id}
1289           key: {get_param: license_key}
1290
1291       check_for_availability:
1292         type: service
1293         demands: [my_vnf_demand, my_other_vnf_demand]
1294         properties:
1295           provider_url: {get_param: [service_info, provider]}
1296           request: REQUEST_DICT
1297           cost: {get_param: [service_info, costs, 4]}
1298
1299 In this example, properties would be set as follows:
1300
1301 +------------------+--------------------------+
1302 | Key              | Value                    |
1303 +==================+==========================+
1304 | ``id``           | SOFTWARE_ID              |
1305 +------------------+--------------------------+
1306 | ``key``          | LICENSE_KEY              |
1307 +------------------+--------------------------+
1308 | ``provider_url`` | dmaap:///full.topic.name |
1309 +------------------+--------------------------+
1310 | ``cost``         | 50                       |
1311 +------------------+--------------------------+
1312
1313 Contact
1314 -------
1315
1316 Shankar Narayanan shankarpnsn@gmail.com