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.
4 Homing Specification Guide
5 ==========================
7 *Updated: 10 October 2017*
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.
15 Homing templates are defined in YAML and follow the structure outlined
20 homing_template_version: 2017-10-10
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
43 - ``locations``: This section contains the declaration of geographic
44 locations. This section is optional and can be omitted when no input
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
50 - ``constraints``: This section contains the declaration of
51 constraints. The section is optional and can be omitted when no input
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
60 Homing Template Version
61 -----------------------
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
70 homing_template_version: 2017-10-10
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.
82 Each parameter is specified with the name followed by its value. Values
83 can be strings, lists, or dictionaries.
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).
95 provider_name: multicloud
97 base_url: http://serviceprovider.sdngc.com/
99 - http://nod/config_a.yaml
100 - http://nod/config_b.yaml
101 - http://nod/config_c.yaml
102 - http://nod/config_d.yaml
104 A parameter can be referenced in place of any value. See the **Intrinsic
105 Functions** section for more details.
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
117 A geographic coordinate expressed as a latitude and longitude.
119 +---------------+----------------------------+
121 +===============+============================+
122 | ``latitude`` | Latitude of the location. |
123 +---------------+----------------------------+
124 | ``longitude`` | Longitude of the location. |
125 +---------------+----------------------------+
130 An opaque host name that can be translated to a coordinate via an
131 inventory provider (e.g., A&AI).
133 +---------------+-----------------------------------+
135 +===============+===================================+
136 | ``host_name`` | Host name identifying a location. |
137 +---------------+-----------------------------------+
142 Common Language Location Identification (CLLI)
143 code(https://en.wikipedia.org/wiki/CLLI_code).
145 +---------------+-------------------+
147 +===============+===================+
148 | ``clli_code`` | 8 character CLLI. |
149 +---------------+-------------------+
153 - Do we need functions that can convert one of these to the other?
154 E.g., CLLI Codes to a latitude/longitude
159 An address expressed in geographic region-agnostic terms (referred to as
162 *Support for this schema is deferred.*
164 +-----------------------------------+----------------------------------+
166 +===================================+==================================+
167 | ``iso_country_code`` | The abbreviated country name |
168 | | associated with the placemark. |
169 +-----------------------------------+----------------------------------+
170 | ``postal_code`` | The postal code associated with |
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 |
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 +-----------------------------------+----------------------------------+
194 - What geocoder can we use to convert placemarks to a
200 The following examples illustrate a location expressed in coordinate,
201 host_name, CLLI, and placemark, respectively.
206 location_using_coordinates:
208 longitude: -97.040443
210 host_location_using_host_name:
211 host_name: USESTCDLLSTX55ANZ123
216 location_using_placemark:
218 thoroughfare: ATT Way
220 administrative_area: NJ
221 postal_code: 07921-2694
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.
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
236 Demand criteria is dependent upon the inventory provider in use.
238 **Provider-agnostic Schema**
240 +---------------------------------+------------------------------------+
242 +=================================+====================================+
243 | ``inventory_provider`` | A HAS-supported inventory |
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 |
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 |
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 |
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 |
296 +---------------------------------+------------------------------------+
303 The following example helps understand a demand specification using
304 Active & Available Inventory (A&AI), the inventory provider-of-record
307 **Inventory Provider Criteria**
309 +---------------------------------+------------------------------------+
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 |
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 |
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 +---------------------------------+------------------------------------+
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
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",
388 "location_id": "DLLSTX9A",
389 "location_type": "azure",
390 "latitude": "32.897480",
391 "longitude": "-97.040443",
396 "complex_name": "dalls_one",
397 "cloud_owner": "att-aic",
398 "cloud_region_version": "1.1",
399 "physical_location_id": "DLLSTX9A",
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.
408 The following examples illustrate two demands:
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
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.
422 - inventory_provider: aai
423 inventory_type: service
425 equipment_type: vG_Mux
426 customer_id: some_company
427 orchestration-status: Activated
428 model-id: 174e371e-f514-4913-a93d-ed7e7f8fbdca
431 - inventory_provider: aai
432 inventory_type: service
435 customer_id: some_company
436 provisioning-status: provisioned
437 - inventory_provider: aai
438 inventory_type: cloud
440 **Questions** \* Do we need to support cost as a function ?
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.
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.
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.
468 +-------------------------------------------+--------------------------+
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 |
484 +-------------------------------------------+--------------------------+
485 | ``properties`` (Optional) | Properties particular to |
486 | | the specified constraint |
487 | | type. Use if required by |
488 | | the constraint. |
489 +-------------------------------------------+--------------------------+
495 type: CONSTRAINT_TYPE
496 demands: DEMAND_NAME | [DEMAND_NAME_1, DEMAND_NAME_2, ...]
497 properties: PROPERTY_DICT
500 type: CONSTRAINT_TYPE
501 demands: DEMAND_NAME | [DEMAND_NAME_1, DEMAND_NAME_2, ...]
502 properties: PROPERTY_DICT
509 +-------------------------------------------+--------------------------+
510 | Type | Description |
511 +===========================================+==========================+
512 | ``attribute`` | Constraint that matches |
513 | | the specified list of |
515 +-------------------------------------------+--------------------------+
516 | ``distance_between_demands`` | Geographic distance |
517 | | constraint between each |
518 | | pair of a list of |
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 |
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 |
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 |
549 +-------------------------------------------+--------------------------+
550 | ``license`` (Deferred) | License availability |
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 |
561 | | location/address. |
562 +-------------------------------------------+--------------------------+
564 *Note: Constraint names marked “Deferred” **will not** be supported in
565 the initial release of HAS.*
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.
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.
579 Each property is documented with a default unit. The following units are
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 +------------+------------------------------+----------+
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.
605 +------------+---------------------------------------------------------+
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 +------------+---------------------------------------------------------+
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*
622 demands: [my_vnf_demand, my_other_vnf_demand]
629 numa_topology: numa_spanning
631 Proposal: Evaluation Operators
632 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
634 To assist in evaluating attributes, the following operators and notation
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 +-----------+-----------+------------------------------------------------+
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 +-----------+-----------+------------------------------------------------+
666 demands: [my_vnf_demand, my_other_vnf_demand]
669 cloud_version: {gt: 1.0}
670 flavor: {regex: /^SRIOV$/i}
671 subdivision: {any: [US-TX, US-NY, US-CA]}
673 Distance Between Demands
674 ~~~~~~~~~~~~~~~~~~~~~~~~
676 Constrain each pairwise combination of two or more demands by distance
681 +--------------+------------------------------------------------------------+
683 +==============+============================================================+
684 | ``distance`` | Distance between demands, measured by the geographic path. |
685 +--------------+------------------------------------------------------------+
687 The constraint is applied between each pairwise combination of demands.
688 For this reason, at least two demands must be specified, implicitly or
695 type: distance_between_demands
696 demands: [my_vnf_demand, my_other_vnf_demand]
703 Constrain one or more demands by distance requirements relative to a
708 +--------------+------------------------------------------------------------+
710 +==============+============================================================+
711 | ``distance`` | Distance between demands, measured by the geographic path. |
712 +--------------+------------------------------------------------------------+
713 | ``location`` | A previously declared location. |
714 +--------------+------------------------------------------------------------+
716 The constraint is applied between each demand and the referenced
717 location, not across all pairwise combinations of Demands.
723 type: distance_to_location
724 demands: [my_vnf_demand, my_other_vnf_demand, another_vnf_demand]
727 location: LOCATION_ID
732 Constrain each demand by its service requirements.
734 Requirements are sent as a request to a **service controller**. Service
735 controllers are defined by plugins in Homing (e.g., ``sdn-c``).
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
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 +---------------------+------------------------------------------------+
757 check_for_availability:
759 demands: [my_vnf_demand, my_other_vnf_demand]
762 request: REQUEST_DICT
767 Constrain each demand’s inventory candidates based on inventory provider
770 Requirements are sent as a request to a **service controller**. Service
771 controllers are defined by plugins in Homing (e.g., ``sdn-c``).
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
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 +---------------------+------------------------------------------------+
793 check_for_membership:
795 demands: [my_vnf_demand, my_other_vnf_demand]
798 request: REQUEST_DICT
803 Constrain two or more demands such that each is located in the same or
804 different zone category.
806 Zone categories are inventory provider-defined, based on the demands
811 +-------------+--------------------------------------------------------+
813 +=============+========================================================+
814 | ``qualifier | Zone qualifier. One of ``same`` or ``different``. |
816 +-------------+--------------------------------------------------------+
817 | ``category` | Zone category. One of ``disaster``, ``region``, |
818 | ` | ``complex``, ``time``, or ``maintenance``. |
819 +-------------+--------------------------------------------------------+
821 For example, to place two demands in different disaster zones:
828 demands: [my_vnf_demand, my_other_vnf_demand]
833 Or, to place two demands in the same region:
840 demands: [my_vnf_demand, my_other_vnf_demand]
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
856 Constrain demands such that inventory items are grouped across two
859 This constraint has no properties.
865 type: inventory_group
866 demands: [demand_1, demand_2]
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.*
874 Constrain demands according to license availability.
876 *Support for this constraint is deferred.*
880 +----------+----------------------------------------------------------+
882 +==========+==========================================================+
883 | ``id`` | Unique license identifier |
884 +----------+----------------------------------------------------------+
885 | ``key`` | Opaque license key, particular to the license identifier |
886 +----------+----------------------------------------------------------+
893 demands: [demand_1, demand_2, ...]
898 Network Between Demands
899 ~~~~~~~~~~~~~~~~~~~~~~~
901 Constrain each pairwise combination of two or more demands by network
904 *Support for this constraint is deferred.*
908 +-------------------+--------------------------------------------------+
910 +===================+==================================================+
911 | ``bandwidth`` | Desired network bandwidth. |
913 +-------------------+--------------------------------------------------+
914 | ``distance`` | Desired distance between demands, measured by |
915 | (Optional) | the network path. |
916 +-------------------+--------------------------------------------------+
917 | ``latency`` | Desired network latency. |
919 +-------------------+--------------------------------------------------+
921 Any combination of ``bandwidth``, ``distance``, or ``latency`` must be
922 specified. If none of these properties are used, it is treated as a
925 The constraint is applied between each pairwise combination of demands.
926 For this reason, at least two demands must be specified, implicitly or
932 network_requirements:
933 type: network_between_demands
934 demands: [my_vnf_demand, my_other_vnf_demand]
936 bandwidth: >= 1000 Mbps
943 Constrain one or more demands by network requirements relative to a
946 *Support for this constraint is deferred.*
950 +-----------------------------------+-----------------------------------+
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 +-----------------------------------+-----------------------------------+
963 Any combination of ``bandwidth``, ``distance``, or ``latency`` must be
964 specified. If none of these properties are used, it is treated as a
967 The constraint is applied between each demand and the referenced
968 location, not across all pairwise combinations of Demands.
973 my_access_network_constraint:
974 type: network_to_location
975 demands: [my_vnf_demand, my_other_vnf_demand]
977 bandwidth: >= 1000 Mbps
980 location: LOCATION_ID
985 Constrain each demand by its cluster capability requirements. For
986 example, as described by an OpenStack Heat template and operational
989 *Support for this constraint is deferred.*
993 +------------+---------------------------------------------------------+
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 +------------+---------------------------------------------------------+
1019 demands: [my_vnf_demand, my_other_vnf_demand]
1022 template: http://repository/my/stack_template
1023 environment: http://repository/my/stack_environment
1028 A **Reservation** allows reservation of resources associated with
1029 candidate that satisfies one or more demands.
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``).
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.
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 +---------------------+------------------------------------------------+
1054 resource_reservation:
1055 type: instance_reservation
1056 demands: [my_vnf_demand, my_other_vnf_demand]
1059 request: REQUEST_DICT
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.
1070 Optimization Components
1071 ~~~~~~~~~~~~~~~~~~~~~~~
1073 Optimization definitions can be broken down into three components:
1075 +-------+----------------+--------------------------------------------+
1076 | Compo | Key | Value |
1078 +=======+================+============================================+
1079 | Goal | ``minimize`` | A single Operand (usually ``sum``) or |
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 +-------+----------------+--------------------------------------------+
1094 Given a customer location ``cl``, two demands ``vG1`` and ``vG2``, and
1095 weights ``w1`` and ``w2``, the optimization criteria can be expressed
1098 ``minimize(weight1 * distance_between(cl, vG1) + weight2 * distance_between(cl, vG2))``
1100 This can be read as: “Minimize the sum of weighted distances from cl to
1101 vG1 and from cl to vG2.”
1103 Such optimizations may be expressed in a template as follows:
1116 - {distance_between: [cl, vG1]}
1119 - {distance_between: [cl, vG2]}
1121 Or without the weights as:
1128 - {distance_between: [cl, vG1]}
1129 - {distance_between: [cl, vG2]}
1131 **Template Restriction**
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.
1137 Until further notice:
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
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.
1151 The first two examples in this section illustrate both of these use
1154 **Inline Operations**
1156 If desired, operations can be rewritten inline. For example, the two
1157 ``product`` operations from the previous example can also be expressed
1169 - {product: [{get_param: w1}, {distance_between: [cl, vG1]}]}
1170 - {product: [{get_param: w2}, {distance_between: [cl, vG2]}]}
1172 In turn, even the ``sum`` operation can be rewritten inline, however
1173 there is a point of diminishing returns in terms of readability!
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
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.
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.
1195 a_property: {FUNCTION_NAME: [ARGUMENT_LIST]}
1197 a_property: {FUNCTION_NAME: ARGUMENT_STRING}
1199 *Note: These functions can only be used within “properties” sections.*
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).
1208 The syntax of the ``get_file`` function is:
1212 {get_file: <content key>}
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.
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
1226 The example below demonstrates the ``get_file`` function usage with both
1227 relative and absolute URLs:
1234 demands: [my_vnf_demand, my_other_vnf_demand]
1236 template: {get_file: stack_template.yaml}
1237 environment: {get_file: http://hostname/environment.yaml}
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.
1243 - ``file:///path/to/stack_template.yaml``
1244 - ``http://hostname/environment.yaml``
1248 - If Homing will only be accessed over DMaaP, files will need to be
1249 embedded using the Homing API request format.
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.
1257 The syntax of the ``get_param`` function is:
1261 {get_param: <parameter name>}
1263 {get_param: [<parameter name>, <key/index1> (optional), <key/index2> (optional), ...]}
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.
1271 The following example demonstrates how the ``get_param`` function is
1277 software_id: SOFTWARE_ID
1278 license_key: LICENSE_KEY
1280 provider: dmaap:///full.topic.name
1281 costs: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
1286 demands: [demand_1, demand_2, ...]
1288 id: {get_param: software_id}
1289 key: {get_param: license_key}
1291 check_for_availability:
1293 demands: [my_vnf_demand, my_other_vnf_demand]
1295 provider_url: {get_param: [service_info, provider]}
1296 request: REQUEST_DICT
1297 cost: {get_param: [service_info, costs, 4]}
1299 In this example, properties would be set as follows:
1301 +------------------+--------------------------+
1303 +==================+==========================+
1304 | ``id`` | SOFTWARE_ID |
1305 +------------------+--------------------------+
1306 | ``key`` | LICENSE_KEY |
1307 +------------------+--------------------------+
1308 | ``provider_url`` | dmaap:///full.topic.name |
1309 +------------------+--------------------------+
1311 +------------------+--------------------------+
1316 Shankar Narayanan shankarpnsn@gmail.com