Copyright (C) 2017 AT&T Intellectual Property. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-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.

Updated: 27 Mar 2018

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

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

homing_template_version: 2018-02-01 parameters: PARAMETER_DICT locations: LOCATION_DICT demands: DEMAND_DICT constraints: CONSTRAINT_DICT reservations: RESERVATION_DICT optimization: OPTIMIZATION

• homing_template_version: This key with value 2016-11-01 (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.

The value of homing_template_version tells HAS not only the format of the template but also features that will be validated and supported. The following values are supported: "2016-11-01" or "2018-02-01" in the initial release of HAS.

homing_template_version: 2018-02-01

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.

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).

parameters: provider_name: multicloud service_info: base_url: http://serviceprovider.sdngc.com/ nod_config: - http://nod/config_a.yaml - http://nod/config_b.yaml - http://nod/config_c.yaml - http://nod/config_d.yaml

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

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:

A geographic coordinate expressed as a latitude and longitude.

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

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. |

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

| Key | Value | |-----------------------------|----------------------------| | clli_code | 8 character CLLI. |

Questions

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

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

Support for this schema is deferred.

| Key | Value | |-----------------------------|----------------------------| | iso_country_code | The abbreviated country name associated with the placemark. | | postal_code | The postal code associated with the placemark. | | administrative_area | The state or province associated with the placemark. | | sub_administrative_area | Additional administrative area information for the placemark. | | locality | The city associated with the placemark. | | sub_locality | Additional city-level information for the placemark. | | thoroughfare | The street address associated with the placemark. | | sub_thoroughfare | Additional street-level information for the placemark. |

Questions

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

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

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.

A demand's resource requirements are determined by asking an inventory provider for one or more sets of inventory candidates against which the demand will be made. An explicit set of candidates may also be declared, for example, if the only candidates for a demand are predetermined.

Demand criteria is dependent upon the inventory provider in use.

Provider-agnostic Schema

| 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. |

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

Inventory Provider Criteria

| Key | Value | |------------------------|--------------------------| | inventory_provider | Examples: aai, multicloud. | | inventory_type | The reserved word cloud (for new inventory) or the reserved word service (for existing inventory). Exactly one inventory type may be specified. | | attributes (Optional) | A list of key-value pairs to match against inventory when drawing candidates. | | service_type (Optional) | Examples may include vG, vG_MuxInfra, etc. | | service_id (Optional) | Must be a valid service id. Examples may include vCPE, VoLTE, etc. | | default_cost (Optional) | The default cost of an inventory candidate, expressed as a unitless number. | | required_candidates (Optional) | A list of one or more valid candidates. See Candidate Schema for details. | | excluded_candidates (Optional) | A list of one or more valid candidates. See Candidate Schema for details. | | existing_placement (Optional) | A single valid candidate, representing the current placement for the demand. See candidate schema for details. |

Candidate Schema

The following is the schema for a valid candidate: candidate_id uniquely identifies a candidate. Currently, it is either a Service Instance ID or Cloud Region ID. candidate_type identifies the type of the candidate. Currently, it is either cloud or service. inventory_type is defined as described in *Inventory Provider Criteria inventory_provider identifies the inventory from which the candidate was drawn. host_id is an ID of a specific host (used only when referring to service/existing inventory). cost is expressed as a unitless number. location_id is always a location ID of the specified location type (e.g., for a type of cloud this will be an Cloud Region ID). location_type is an inventory provider supported location type. latitude is a valid latitude corresponding to the locationid. longitude is a valid longitude corresponding to the *locationid. city (Optional) city corresponding to the location_id. state (Optional) state corresponding to the locationid. country (Optional) country corresponding to the *locationid. region (Optional) geographic region corresponding to the location_id. complex_name (Optional) Name of the complex corresponding to the locationid. ``cloudowner(Optional) refers to the *cloud owner* (e.g.,azure,aws,att, etc.). *cloudregionversion(Optional) is an inventory provider supported version of the cloud region. *physicallocationid`` (Optional) is an inventory provider supported CLLI code corresponding to the cloud region.

Examples

Questions * Currently, candidates are either service instances or cloud regions. As new services are on-boarded, this can be evolved to represent different types of resources.

Examples

The following examples illustrate two demands:

• vGMuxInfra: A vGMuxInfra service, drawing candidates of type service from the inventory. Only candidates that match the customer_id and orchestration-status will be included in the search space.

• vG: A vG, drawing candidates of type service and cloud from the inventory. Only candidates that match the customer_id and provisioning-status will be included in the search space.

demands: vGMuxInfra: - inventory_provider: aai inventory_type: service service_type: vG_Mux attributes: customer-id: some_company orchestration-status: Activated vG: - inventory_provider: aai inventory_type: service service_type: vG attributes: customer-id: some_company provisioning-status: provisioned - inventory_provider: aai inventory_type: cloud

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

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 are denoted by a constraints key. Each constraint is uniquely named and set to a dictionary containing a constraint type, a list of demands to apply the constraint to, and a dictionary of constraint properties.

Considerations while using multiple constraints Constraints should be treated as a unordered list, and no assumptions should be made as regards to the order in which the constraints are evaluated for any given demand. All constraints are effectively AND-ed together. Constructs such as "Constraint X OR Y" are unsupported. * Constraints are reducing in nature, and does not increase the available candidates at any point during the constraint evaluations.

Schema

| Key | Value | |---------------------|-------------| | CONSTRAINT_NAME | Key is a unique name. | | type | The type of constraint. See Constraint Types for a list of currently supported values. | | demands | One or more previously declared demands. If only one demand is specified, it may appear without list markers ([]). | | properties (Optional) | Properties particular to the specified constraint type. Use if required by the constraint. |

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 ...

| 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. | | hpa | Constraint that recommends optimal flavor and cloud region based on required hardware platform capabilities for an incoming demand. | | vim_fit | Constraint that ensures capacity check with available capacity of VIMs based on incoming request. | | 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

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.

Whitespace may appear between the comparison operator and value, and between the value and units. When a range values is specified (e.g., 10-20 km), the comparison operator is omitted.

Each property is documented with a default unit. The following units are supported: