Apache License, Version 2.0

...

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Homing Specification Guide

Updated: 10 October 2017

This document describes the Homing Template format, used by the Homing service. It is a work in progress and subject to frequent revision.

Template Structure

Homing templates are defined in YAML and follow the structure outlined below.

...

homing_template_version: This key with value 2017-10-10 (or a later date) indicates that the YAML document is a Homing template of the specified version.
parameters: This section allows for specifying input parameters that have to be provided when instantiating the homing template. Typically, this section is used for providing runtime parameters (like SLA thresholds), which in turn is used in the existing homing policies. The section is optional and can be omitted when no input is required.
locations: This section contains the declaration of geographic locations. This section is optional and can be omitted when no input is required.
demands: This section contains the declaration of demands. This section with at least one demand should be defined in any Homing template, or the template would not really do anything when being instantiated.
constraints: This section contains the declaration of constraints. The section is optional and can be omitted when no input is required.
reservations: This section contains the declaration of required reservations. This section is optional and can be omitted when reservations are not required.
optimization: This section allows the declaration of an optimization. This section is optional and can be omitted when no input is required.

Homing Template Version

The value of homing_template_version tells HAS not only the format of the template but also features that will be validated and supported. Only one value is supported: 2017-10-10 in the initial release of HAS.

homing_template_version: 2017-10-10

Parameters

The parameters section allows for specifying input parameters that have to be provided when instantiating the template. Such parameters are typically used for providing runtime inputs (like SLA thresholds), which in turn is used in the existing homing policies. This also helps build reusable homing constraints where these parameters can be embedded design time, and it corresponding values can be supplied during runtime.

Each parameter is specified with the name followed by its value. Values can be strings, lists, or dictionaries.

Example

In this example, provider_name is a string and service_info is a dictionary containing both a string and a list (keyed by base_url and nod_config, respectively).

...

A parameter can be referenced in place of any value. See the Intrinsic Functions section for more details.

Locations

One or more locations may be declared. A location may be referenced by one or more constraints. Locations may be defined in any of the following ways:

Coordinate

A geographic coordinate expressed as a latitude and longitude.

...

| Key | Value | |-----------------------------|----------------------------| | latitude | Latitude of the location. | | longitude | Longitude of the location. |

Host Name

An opaque host name that can be translated to a coordinate via an inventory provider (e.g., A&AI).

...

| Key | Value | |-----------------------------|----------------------------| | host_name | Host name identifying a location. |

CLLI

Common Language Location Identification (CLLI) code(https://en.wikipedia.org/wiki/CLLI_code).

...

Do we need functions that can convert one of these to the other? E.g., CLLI Codes to a latitude/longitude

Placemark

An address expressed in geographic region-agnostic terms (referred to as a placemark).

...

What geocoder can we use to convert placemarks to a latitude/longitude?

Examples

The following examples illustrate a location expressed in coordinate, host_name, CLLI, and placemark, respectively.

locations:
  location_using_coordinates:
    latitude: 32.897480
    longitude: -97.040443

  host_location_using_host_name:
    host_name: USESTCDLLSTX55ANZ123

  location_using_clli:
    clli_code: DLLSTX55

  location_using_placemark:
    sub_thoroughfare: 1
    thoroughfare: ATT Way
    locality: Bedminster
    administrative_area: NJ
    postal_code: 07921-2694

Demands

A demand can be satisfied by using candidates drawn from inventories. Each demand is uniquely named. Inventory is considered to be opaque and can represent anything from which candidates can be drawn.

...

| Key | Value | |------------------------|--------------------------| | inventory_provider | A HAS-supported inventory provider. | | inventory_type | The reserved word cloud (for cloud regions) or the reserved word service (for existing service instances). Exactly one inventory type may be specified. | | attributes (Optional) | A list of key-value pairs, that is used to select inventory candidates that match all the specified attributes. The key should be a uniquely identifiable attribute at the inventory provider. | | service_type (Optional) | If inventory_type is service, a list of one or more provider-defined service types. If only one service type is specified, it may appear without list markers ([]). | | service_id (Optional) | If inventory_type is service, a list of one or more provider-defined service ids. If only one service id is specified, it may appear without list markers ([]). | | default_cost (Optional) | The default cost of an inventory candidate, expressed as currency. This must be specified if the inventory provider may not always return a cost. | | required_candidates (Optional) | A list of one or more candidates from which a solution will be explored. Must be a valid candidate as described in the candidate schema. | | excluded_candidates (Optional) | A list of one or more candidates that should be excluded from the search space. Must be a valid candidate as described in the candidate schema. | | existing_placement (Optional) | The current placement for the demand. Must be a valid candidate as described in the candidate schema. |

Examples

The following example helps understand a demand specification using Active & Available Inventory (A&AI), the inventory provider-of-record for ONAP.

...

Questions * Do we need to support cost as a function ?

Constraints

A Constraint is used to eliminate inventory candidates from one or more demands that do not meet the requirements specified by the constraint. Since reusability is one of the cornerstones of HAS, Constraints are designed to be service-agnostic, and is parameterized such that it can be reused across a wide range of services. Further, HAS is designed with a plug-in architecture that facilitates easy addition of new constraint types.

...

constraints:
  CONSTRAINT_NAME_1:
    type: CONSTRAINT_TYPE
    demands: DEMAND_NAME | [DEMAND_NAME_1, DEMAND_NAME_2, ...]
    properties: PROPERTY_DICT

  CONSTRAINT_NAME_2:
    type: CONSTRAINT_TYPE
    demands: DEMAND_NAME | [DEMAND_NAME_1, DEMAND_NAME_2, ...]
    properties: PROPERTY_DICT

  ...

Constraint Types

Type	Description
`attribute`	Constraint that matches the specified list of Attributes.
`distance_between_demands`	Geographic distance constraint between each pair of a list of demands.
`distance_to_location`	Geographic distance constraint between each of a list of demands and a specific location.
`instance_fit`	Constraint that ensures available capacity in an existing service instance for an incoming demand.
`inventory_group`	Constraint that enforces two or more demands are satisfied using candidates from a pre-established group in the inventory.
`region_fit`	Constraint that ensures available capacity in an existing cloud region for an incoming demand.
`zone`	Constraint that enforces co-location/diversity at the granularities of clouds/regions/availability-zones.
`license` (Deferred)	License availability constraint.
`network_between_demands` (Deferred)	Network constraint between each pair of a list of demands.
`network_to_location` (Deferred)	Network constraint between each of a list of demands and a specific location/address.

...

Note: Constraint names marked "Deferred" *will not

Threshold Values

Constraint property values representing a threshold may be an integer or floating point number, optionally prefixed with a comparison operator: =, <, >, <=, or >=. The default is = and optionally suffixed with a unit.

...

| Unit | Values | Default | |------------|------------------------------|----------| | Currency | USD | USD | | Time | ms, sec | ms | | Distance | km, mi | km | | Throughput | Kbps, Mbps, Gbps | Mbps |

Attribute

Constrain one or more demands by one or more attributes, expressed as properties. Attributes are mapped to the inventory provider specified properties, referenced by the demands. For example, properties could be hardware capabilities provided by the platform (flavor, CPU-Pinning, NUMA), features supported by the services, etc.

...

constraints:
  sriov_nj:
    type: attribute
    demands: [my_vnf_demand, my_other_vnf_demand]
    properties:
      evaluate:
        cloud_version: 1.1
        flavor: SRIOV
        subdivision: US-TX
        vcpu_pinning: True
        numa_topology: numa_spanning

Proposal: Evaluation Operators

To assist in evaluating attributes, the following operators and notation are proposed:

...

constraints:
  sriov_nj:
    type: attribute
    demands: [my_vnf_demand, my_other_vnf_demand]
    properties:
      evaluate:
        cloud_version: {gt: 1.0}
        flavor: {regex: /^SRIOV$/i}
        subdivision: {any: [US-TX, US-NY, US-CA]}

Distance Between Demands

Constrain each pairwise combination of two or more demands by distance requirements.

...

constraints:
  distance_vnf1_vnf2:
    type: distance_between_demands
    demands: [my_vnf_demand, my_other_vnf_demand]
    properties:
      distance: < 250 km

Distance To Location

Constrain one or more demands by distance requirements relative to a specific location.

...

constraints:
  distance_vnf1_loc:
    type: distance_to_location
    demands: [my_vnf_demand, my_other_vnf_demand, another_vnf_demand]
    properties:
      distance: < 250 km
      location: LOCATION_ID

Instance Fit

Constrain each demand by its service requirements.

...

constraints:
  check_for_availability:
    type: instance_fit
    demands: [my_vnf_demand, my_other_vnf_demand]
    properties:
      controller: sdn-c
      request: REQUEST_DICT

Region Fit

Constrain each demand's inventory candidates based on inventory provider membership.

...

constraints:
  check_for_membership:
    type: region_fit
    demands: [my_vnf_demand, my_other_vnf_demand]
    properties:
      controller: sdn-c
      request: REQUEST_DICT

Zone

Constrain two or more demands such that each is located in the same or different zone category.

...

These categories could be any of the following: disaster_zone, region, complex, time_zone, and maintenance_zone. Really, we are talking affinity/anti-affinity at the level of DCs, but these terms may cause confusion with affinity/anti-affinity in OpenStack.

Inventory Group

Constrain demands such that inventory items are grouped across two demands.

...

Note: Only pair-wise groups are supported at this time. If three or more demands are specified, only the first two will be used.

License

Constrain demands according to license availability.

...

constraints:
  my_software:
    type: license
    demands: [demand_1, demand_2, ...]
    properties:
      id: SOFTWARE_ID
      key: LICENSE_KEY

Network Between Demands

Constrain each pairwise combination of two or more demands by network requirements.

...

constraints:
  network_requirements:
    type: network_between_demands
    demands: [my_vnf_demand, my_other_vnf_demand]
    properties:
      bandwidth: >= 1000 Mbps
      distance: < 250 km
      latency: < 50 ms

Network To Location

Constrain one or more demands by network requirements relative to a specific location.

...

constraints:
  my_access_network_constraint:
    type: network_to_location
    demands: [my_vnf_demand, my_other_vnf_demand]
    properties:
      bandwidth: >= 1000 Mbps
      distance: < 250 km
      latency: < 50 ms
      location: LOCATION_ID

Capabilities

Constrain each demand by its cluster capability requirements. For example, as described by an OpenStack Heat template and operational environment.

...

constraints:
  check_for_fit:
    type: capability
    demands: [my_vnf_demand, my_other_vnf_demand]
    properties:
      specification: heat
      template: http://repository/my/stack_template
      environment: http://repository/my/stack_environment

Reservations

A Reservation allows reservation of resources associated with candidate that satisfies one or more demands.

...

resource_reservation:
  type: instance_reservation
  demands: [my_vnf_demand, my_other_vnf_demand]
  properties:
    controller: sdn-c
    request: REQUEST_DICT

Optimizations

An Optimization allows specification of a objective function, which aims to maximize or minimize a certain value that varies based on the choice of candidates for one or more demands that are a part of the objective function. For example, an objective function may be to find the closest cloud-region to a customer to home a demand.

Optimization Components

Optimization definitions can be broken down into three components:

...

| Component | Key | Value | |-----------|----------------------|---------------------------------------------------------| | Goal | minimize | A single Operand (usually sum) or Function | | Operator | sum, product | Two or more Operands (Numbers, Operators, Functions) | | Function | distance_between | A two-element list consisting of a location and demand. |

Example

Given a customer location cl, two demands vG1 and vG2, and weights w1 and w2, the optimization criteria can be expressed as:

...

In the first version, we do not support more than one dimension in the optimization (e.g., Minimize distance and cost). For supporting multiple dimensions we would need a function the normalize the unit across dimensions.

Intrinsic Functions

Homing provides a set of intrinsic functions that can be used inside templates to perform specific tasks. The following section describes the role and syntax of the intrinsic functions.

...

Note: These functions can only be used within "properties" sections.

get_file

The get_file function inserts the content of a file into the template. It is generally used as a file inclusion mechanism for files containing templates from other services (e.g., Heat).

...

If Homing will only be accessed over DMaaP, files will need to be embedded using the Homing API request format.

get_param

The get_param function references an input parameter of a template. It resolves to the value provided for this input parameter at runtime.

...

| Key | Value | |------------------|--------------------------| | id | SOFTWAREID | | key | LICENSEKEY | | provider_url | dmaap:///full.topic.name | | cost | 50 |

Contact

Shankar Narayanan (shankarpnsn@gmail.com)

Page Comparison

Versions Compared

Old Version 6

New Version 7

Key

Apache License, Version 2.0

Homing Specification Guide

Template Structure

Homing Template Version

Parameters

Example

Locations

Coordinate

Host Name

CLLI

Placemark

Examples

Demands

Examples

Constraints

Constraint Types

Threshold Values

Attribute

Proposal: Evaluation Operators

Distance Between Demands

Distance To Location

Instance Fit

Region Fit

Zone

Inventory Group

License

Network Between Demands

Network To Location

Capabilities

Reservations

Optimizations

Optimization Components

Example

Intrinsic Functions

get_file

get_param

Contact