summaryrefslogtreecommitdiffstats
path: root/docs/sections
diff options
context:
space:
mode:
authorfsandoval <frank.sandoval@oamtechnologies.com>2018-04-30 19:23:36 -0600
committerShankaranarayanan Puzhavakath Narayanan <snarayanan@research.att.com>2018-05-01 16:55:11 +0000
commit2c0f127d19981cbf69868265f5b4ac98cd687210 (patch)
tree4f240e117a5f545b78d6b94fc29f826f4ce9f979 /docs/sections
parentdcf83b8e6798552e614ff6fc117498d737980f9a (diff)
Beijing RC2 documentation
Change-Id: Ic8b75e4cb33d6c4562cef2f2b9342974bfae03a3 Signed-off-by: fsandoval <frank.sandoval@oamtechnologies.com> Issue-ID: OPTFRA-41
Diffstat (limited to 'docs/sections')
-rw-r--r--docs/sections/administration.rst6
-rw-r--r--docs/sections/architecture.rst55
-rw-r--r--docs/sections/configuration.rst36
-rw-r--r--docs/sections/consumedapis.rst18
-rw-r--r--docs/sections/delivery.rst6
-rw-r--r--docs/sections/diagrams/HASHeuristicGreedyAlgorithm.jpgbin0 -> 184098 bytes
-rw-r--r--docs/sections/diagrams/HAS_PolicyDrivenHoming.pngbin0 -> 684751 bytes
-rw-r--r--docs/sections/diagrams/HAS_SeedCode_Architecture_R2.jpgbin0 -> 321115 bytes
-rw-r--r--docs/sections/diagrams/PlanLifecycle.jpgbin0 -> 142896 bytes
-rw-r--r--docs/sections/homingspecification.rst1734
-rw-r--r--docs/sections/humaninterfaces.rst6
-rw-r--r--docs/sections/installation.rst22
-rw-r--r--docs/sections/logging.rst16
-rw-r--r--docs/sections/offeredapis.rst139
-rw-r--r--docs/sections/release-notes.rst43
15 files changed, 2081 insertions, 0 deletions
diff --git a/docs/sections/administration.rst b/docs/sections/administration.rst
new file mode 100644
index 0000000..0650561
--- /dev/null
+++ b/docs/sections/administration.rst
@@ -0,0 +1,6 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Administration
+=============================================
+
+ Administration - TBD \ No newline at end of file
diff --git a/docs/sections/architecture.rst b/docs/sections/architecture.rst
new file mode 100644
index 0000000..f8ecbcf
--- /dev/null
+++ b/docs/sections/architecture.rst
@@ -0,0 +1,55 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Architecture
+=============================================
+
+Introduction
+------------------
+OOF-HAS is an policy-driven placement optimizing service (or homing service) that allows ONAP to deploy services
+automatically across multiple sites and multiple clouds. It enables placement based on a wide variety of policy
+constraints including capacity, location, platform capabilities, and other service specific constraints.
+
+HAS is a distributed resource broker that enables automated policy-driven optimized placement of services on a
+global heterogeneous platform using ONAP. Given a set of service components (based on SO decomposition flows)
+and requirements for placing these components (driven by policies), HAS finds optimal resources (cloud regions
+or existing service instances) to home these service components such that it meets all the service requirements.
+HAS is architected as an extensible homing service that can accommodate a growing set of homing objectives, policy
+constraints, data sources and placement algorithms. It is also service-agnostic by design and can easily onboard
+new services with minimal effort. Therefore, HAS naturally extends to a general policy-driven optimizing placement
+platform for wider range of services, e.g., DCAE micro-services, ECOMP control loops, server capacity, etc.
+Finally, HAS provides an traceable mechanism for what-if analysis which is critical for ease of understanding a
+homing recommendation and resolving infeasibility scenarios.
+
+HAS in Service Instantiation workflows
+--------------------------------------------
+Below is an illustration of HAS interactions with other ONAP components to enable Policy driven homing. The homing
+policy constraints have been expanded (and categorized) to highlight the range of constraints that could be provided
+to HAS for determining the homing solution. The figure also shows how HAS uses a plugin-based approach to allow an
+extensible set of constraints and data models.
+
+.. image:: ./diagrams/HAS_PolicyDrivenHoming.png
+
+More information on how homing constraints are specified can be found at OOF-HAS Homing Specification Guide, and a
+sample homing template has been drawn up for residential vCPE Homing Use Case.
+
+HAS Architecture (R2)
+----------------------
+
+.. image:: ./diagrams/HAS_SeedCode_Architecture_R2.jpg
+
+Lifecycle of a Homing request in HAS
+--------------------------------------------
+
+.. image:: ./diagrams/PlanLifecycle.jpg
+
+Use cases
+----------------------
+Residential vCPE: https://wiki.onap.org/display/DW/vCPE+Homing+Use+Case
+
+5G RAN: https://wiki.onap.org/display/DW/5G+RAN+use+case
+
+
+A sample heuristic greedy algorithm of HAS (using a vCPE as example)
+------------------------------------------------------------------------
+
+.. image:: ./diagrams/HASHeuristicGreedyAlgorithm.jpg
diff --git a/docs/sections/configuration.rst b/docs/sections/configuration.rst
new file mode 100644
index 0000000..5e55a89
--- /dev/null
+++ b/docs/sections/configuration.rst
@@ -0,0 +1,36 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Configuration
+=============================================
+
+For the configuration inside the config-file, please refer to the README inside Gerrit
+
+It is worth noting that A&AI and MUSIC may be needed to run HAS project. Please refer to their setup page for installation.
+
+For MUSIC version 2.4.x and newer refer Setup for Developing MUSIC
+
+Running the example
+-----------------------
+To start the process, execute the following commands:
+
+ $ conductor-api --port=8091 -- --config-file={conductor_conf_file_location}
+
+ $ conductor-controller --config-file={conductor_conf_file_location}
+
+ $ conductor-solver --config-file={conductor_conf_file_location}
+
+ $ conductor-reservation --config-file={conductor_conf_file_location}
+
+ $ conductor-data --config-file={conductor_conf_file_location}
+
+Committing the Code
+-----------------------
+ $ git commit -am "Initial proj struct"
+
+ $ git review -s
+
+ $ git commit -as --amend
+
+# scroll down 2 lines (above your Change-ID) insert "Issue-ID: {issue_id}"
+
+ $ git review
diff --git a/docs/sections/consumedapis.rst b/docs/sections/consumedapis.rst
new file mode 100644
index 0000000..954a138
--- /dev/null
+++ b/docs/sections/consumedapis.rst
@@ -0,0 +1,18 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Consumed APIs
+=============================================
+The following are the dependencies for the project based on the scope for the Beijing Release.
+The required dependencies have been identified based on the current homing requirements for the vCPE use case,
+and the potential dependencies are tentative dependencies that may exist based on how the information required
+for homing (e.g., Hardware Platform Enablement, VIM attributes) is available.
+
+
+AAI
+--------------------------------------------
+See documentation for Active and Available Inventory component
+
+
+Multi-Cloud
+--------------------------------------------
+See documentation for Multi-Cloud component \ No newline at end of file
diff --git a/docs/sections/delivery.rst b/docs/sections/delivery.rst
new file mode 100644
index 0000000..bfe8480
--- /dev/null
+++ b/docs/sections/delivery.rst
@@ -0,0 +1,6 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Delivery
+=============================================
+
+ Delivery description TBD \ No newline at end of file
diff --git a/docs/sections/diagrams/HASHeuristicGreedyAlgorithm.jpg b/docs/sections/diagrams/HASHeuristicGreedyAlgorithm.jpg
new file mode 100644
index 0000000..c412ad6
--- /dev/null
+++ b/docs/sections/diagrams/HASHeuristicGreedyAlgorithm.jpg
Binary files differ
diff --git a/docs/sections/diagrams/HAS_PolicyDrivenHoming.png b/docs/sections/diagrams/HAS_PolicyDrivenHoming.png
new file mode 100644
index 0000000..19b2d5c
--- /dev/null
+++ b/docs/sections/diagrams/HAS_PolicyDrivenHoming.png
Binary files differ
diff --git a/docs/sections/diagrams/HAS_SeedCode_Architecture_R2.jpg b/docs/sections/diagrams/HAS_SeedCode_Architecture_R2.jpg
new file mode 100644
index 0000000..1d247ca
--- /dev/null
+++ b/docs/sections/diagrams/HAS_SeedCode_Architecture_R2.jpg
Binary files differ
diff --git a/docs/sections/diagrams/PlanLifecycle.jpg b/docs/sections/diagrams/PlanLifecycle.jpg
new file mode 100644
index 0000000..8d5cf2f
--- /dev/null
+++ b/docs/sections/diagrams/PlanLifecycle.jpg
Binary files differ
diff --git a/docs/sections/homingspecification.rst b/docs/sections/homingspecification.rst
new file mode 100644
index 0000000..9e10730
--- /dev/null
+++ b/docs/sections/homingspecification.rst
@@ -0,0 +1,1734 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. Copyright (C) 2017-2018 AT&T Intellectual Property. All rights reserved.
+
+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.
+
+.. code:: yaml
+
+ homing_template_version: 2017-10-10
+ parameters:
+ PARAMETER_DICT
+ locations:
+ LOCATION_DICT
+ demands:
+ DEMAND_DICT
+ constraints:
+ CONSTRAINT_DICT
+ reservations:
+ RESERVATION_DICT
+ optimization:
+ OPTIMIZATION
+
+- ``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.
+
+.. code:: yaml
+
+ 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).
+
+.. code:: yaml
+
+ 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.
+
+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).
+
++---------------+-------------------+
+| 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
+
+Placemark
+~~~~~~~~~
+
+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?
+
+Examples
+~~~~~~~~
+
+The following examples illustrate a location expressed in coordinate,
+host_name, CLLI, and placemark, respectively.
+
+.. code:: yaml
+
+ 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.
+
+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`` | A list of one or more candidates |
+| (Optional) | from which a solution will be |
+| | explored. Must be a valid |
+| | candidate as described in the |
+| | **candidate schema**. |
++---------------------------------+------------------------------------+
+| ``excluded_candidates`` | A list of one or more candidates |
+| (Optional) | that should be excluded from the |
+| | search space. Must be a valid |
+| | candidate as described in the |
+| | **candidate schema**. |
++---------------------------------+------------------------------------+
+| ``existing_placement`` | The current placement for the |
+| (Optional) | demand. Must be a valid candidate |
+| | as described in the **candidate |
+| | schema**. |
++---------------------------------+------------------------------------+
+
+.. _examples-1:
+
+Examples
+~~~~~~~~
+
+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`` | A list of one or more valid |
+| (Optional) | candidates. See **Candidate |
+| | Schema** for details. |
++---------------------------------+------------------------------------+
+| ``excluded_candidates`` | A list of one or more valid |
+| (Optional) | candidates. See **Candidate |
+| | Schema** for details. |
++---------------------------------+------------------------------------+
+| ``existing_placement`` | A single valid candidate, |
+| (Optional) | 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** (above). \* ``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
+*location_id*. \* ``longitude`` is a valid longitude corresponding to
+the *location_id*. \* ``city`` (Optional) city corresponding to the
+*location_id*. \* ``state`` (Optional) state corresponding to the
+*location_id*. \* ``country`` (Optional) country corresponding to the
+*location_id*. \* ``region`` (Optional) geographic region corresponding
+to the *location_id*. \* ``complex_name`` (Optional) Name of the complex
+corresponding to the *location_id*. \* ``cloud_owner`` (Optional) refers
+to the *cloud owner* (e.g., ``azure``, ``aws``, ``att``, etc.). \*
+``cloud_region_version`` (Optional) is an inventory provider supported
+version of the cloud region. \* ``physical_location_id`` (Optional) is
+an inventory provider supported CLLI code corresponding to the cloud
+region.
+
+**Examples**
+
+**``Service Candidate``**
+.. code:: json
+
+ {
+ "candidate_id": "1ac71fb8-ad43-4e16-9459-c3f372b8236d",
+ "candidate_type": "service",
+ "inventory_type": "service",
+ "inventory_provider": "aai",
+ "host_id": "vnf_123456",
+ "cost": "100",
+ "location_id": "DLLSTX9A",
+ "location_type": "azure",
+ "latitude": "32.897480",
+ "longitude": "-97.040443",
+ "city": "Dallas",
+ "state": "TX",
+ "country": "USA",
+ "region": "US",
+ "complex_name": "dalls_one",
+ "cloud_owner": "att-aic",
+ "cloud_region_version": "1.1",
+ "physical_location_id": "DLLSTX9A"
+ }
+
+**``Cloud Candidate``**
+.. code:: json
+
+ {
+ "candidate_id": "NYCNY55",
+ "candidate_type": "cloud",
+ "inventory_type": "cloud",
+ "inventory_provider": "aai",
+ "cost": "100",
+ "location_id": "NYCNY55",
+ "location_type": "azure",
+ "latitude": "40.7128",
+ "longitude": "-74.0060",
+ "city": "New York",
+ "state": "NY",
+ "country": "USA",
+ "region": "US",
+ "complex_name": "ny_one",
+ "cloud_owner": "att-aic",
+ "cloud_region_version": "1.1",
+ "physical_location_id": "NYCNY55",
+ "flavors": {
+ "flavor":[
+ {
+ "flavor-id":"9cf8220b-4d96-4c30-a426-2e9382f3fff2",
+ "flavor-name":"flavor-numa-cpu-topology-instruction-set",
+ "flavor-vcpus":64,
+ "flavor-ram":65536,
+ "flavor-disk":1048576,
+ "flavor-ephemeral":128,
+ "flavor-swap":"0",
+ "flavor-is-public":false,
+ "flavor-selflink":"pXtX",
+ "flavor-disabled":false,
+ "hpa-capabilities":{
+ "hpa-capability":[
+ {
+ "hpa-capability-id":"01a4bfe1-1993-4fda-bd1c-ef333b4f76a9",
+ "hpa-feature":"cpuInstructionSetExtensions",
+ "hpa-version":"v1",
+ "architecture":"Intel64",
+ "resource-version":"1521306560982",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"instructionSetExtensions",
+ "hpa-attribute-value":"{\"value\":{['AAA', 'BBB', 'CCC', 'DDD']}}",
+ "resource-version":"1521306560989"
+ }
+ ]
+ },
+ {
+ "hpa-capability-id":"167ad6a2-7d9c-4bf2-9a1b-30e5311b8c66",
+ "hpa-feature":"numa",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "resource-version":"1521306561020",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"numaCpu-1",
+ "hpa-attribute-value":"{\"value\":4}",
+ "resource-version":"1521306561060"
+ },
+ {
+ "hpa-attribute-key":"numaNodes",
+ "hpa-attribute-value":"{\"value\":2}",
+ "resource-version":"1521306561088"
+ },
+ {
+ "hpa-attribute-key":"numaCpu-0",
+ "hpa-attribute-value":"{\"value\":2}",
+ "resource-version":"1521306561028"
+ },
+ {
+ "hpa-attribute-key":"numaMem-0",
+ "hpa-attribute-value":"{\"value\":2, \"unit\":\"GB\" }",
+ "resource-version":"1521306561044"
+ },
+ {
+ "hpa-attribute-key":"numaMem-1",
+ "hpa-attribute-value":"{\"value\":4, \"unit\":\"GB\" }",
+ "resource-version":"1521306561074"
+ }
+ ]
+ },
+ {
+ "hpa-capability-id":"13ec6d4d-7fee-48d8-9e4a-c598feb101ed",
+ "hpa-feature":"basicCapabilities",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "resource-version":"1521306560909",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"numVirtualCpu",
+ "hpa-attribute-value":"{\"value\":64}",
+ "resource-version":"1521306560932"
+ },
+ {
+ "hpa-attribute-key":"virtualMemSize",
+ "hpa-attribute-value":"{\"value\":65536, \"unit\":\"MB\" }",
+ "resource-version":"1521306560954"
+ }
+ ]
+ },
+ {
+ "hpa-capability-id":"8fa22e64-41b4-471f-96ad-6c4708635e4c",
+ "hpa-feature":"cpuTopology",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "resource-version":"1521306561109",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"numCpuCores",
+ "hpa-attribute-value":"{\"value\":8}",
+ "resource-version":"1521306561114"
+ },
+ {
+ "hpa-attribute-key":"numCpuThreads",
+ "hpa-attribute-value":"{\"value\":8}",
+ "resource-version":"1521306561138"
+ },
+ {
+ "hpa-attribute-key":"numCpuSockets",
+ "hpa-attribute-value":"{\"value\":6}",
+ "resource-version":"1521306561126"
+ }
+ ]
+ }
+ ]
+ },
+ "resource-version":"1521306560203"
+ },
+ {
+ "flavor-id":"f5aa2b2e-3206-41b6-80d5-cf041b098c43",
+ "flavor-name":"flavor-cpu-pinning-ovsdpdk-instruction-set",
+ "flavor-vcpus":32,
+ "flavor-ram":131072,
+ "flavor-disk":2097152,
+ "flavor-ephemeral":128,
+ "flavor-swap":"0",
+ "flavor-is-public":false,
+ "flavor-selflink":"pXtX",
+ "flavor-disabled":false,
+ "hpa-capabilities":{
+ "hpa-capability":[
+ {
+ "hpa-capability-id":"4d04f4d8-e257-4442-8417-19a525e56096",
+ "hpa-feature":"cpuInstructionSetExtensions",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "resource-version":"1521306561223",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"instructionSetExtensions",
+ "hpa-attribute-value":"{\"value\":{['A11', 'B22']}}",
+ "resource-version":"1521306561228"
+ }
+ ]
+ },
+ {
+ "hpa-capability-id":"8d36a8fe-bfee-446a-bbcb-881ee66c8f78",
+ "hpa-feature":"ovsDpdk",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "resource-version":"1521306561170",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"dataProcessingAccelerationLibrary",
+ "hpa-attribute-value":"{\"value\":\"v18.02\"}",
+ "resource-version":"1521306561175"
+ }
+ ]
+ },
+ {
+ "hpa-capability-id":"c140c945-1532-4908-86c9-d7f71416f1dd",
+ "hpa-feature":"cpuPinning",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "resource-version":"1521306561191",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"logicalCpuPinningPolicy",
+ "hpa-attribute-value":"{\"value\":\"dedicated\"}",
+ "resource-version":"1521306561196"
+ },
+ {
+ "hpa-attribute-key":"logicalCpuThreadPinningPolicy",
+ "hpa-attribute-value":"{value:\"prefer\"}",
+ "resource-version":"1521306561206"
+ }
+ ]
+ },
+ {
+ "hpa-capability-id":"4565615b-1077-4bb5-a340-c5be48db2aaa",
+ "hpa-feature":"basicCapabilities",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "resource-version":"1521306561244",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"numVirtualCpu",
+ "hpa-attribute-value":"{\"value\":32}",
+ "resource-version":"1521306561259"
+ },
+ {
+ "hpa-attribute-key":"virtualMemSize",
+ "hpa-attribute-value":"{\"value\":131072, \"unit\":\"MB\" }",
+ "resource-version":"1521306561248"
+ }
+ ]
+ }
+ ]
+ },
+ "resource-version":"1521306561164"
+ }
+ ]
+ }
+ }
+
+**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.
+
+.. code:: yaml
+
+ demands:
+ vGMuxInfra:
+ - inventory_provider: aai
+ inventory_type: service
+ attributes:
+ equipment_type: vG_Mux
+ customer_id: some_company
+ orchestration-status: Activated
+ model-id: 174e371e-f514-4913-a93d-ed7e7f8fbdca
+ model-version: 2.0
+ vG:
+ - inventory_provider: aai
+ inventory_type: service
+ attributes:
+ equipment_type: vG
+ customer_id: some_company
+ provisioning-status: provisioned
+ - inventory_provider: aai
+ inventory_type: cloud
+
+**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 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. |
++-------------------------------------------+--------------------------+
+
+.. code:: yaml
+
+ 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/availabil |
+| | ity-zones. |
++-------------------------------------------+--------------------------+
+| ``hpa`` | Constraint that |
+| | recommends cloud region |
+| | with an optimal flavor |
+| | based on required HPA |
+| | capabilities for an |
+| | incoming demand. |
++-------------------------------------------+--------------------------+
+| ``vim_fit`` | Constraint that checks if|
+| | the incoming demand fits |
+| | the VIM instance. | |
++-------------------------------------------+--------------------------+
+| ``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** be supported in
+the initial release of HAS.*
+
+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.
+
+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:
+
++------------+------------------------------+----------+
+| 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.
+
+**Schema**
+
++------------+---------------------------------------------------------+
+| Property | Value |
++============+=========================================================+
+| ``evaluate | Opaque dictionary of attribute name and value pairs. |
+| `` | Values must be strings or numbers. Encoded and sent to |
+| | the service provider via a plugin. |
++------------+---------------------------------------------------------+
+
+*Note: Attribute values are not detected/parsed as thresholds by the
+Homing framework. Such interpretations and evaluations are inventory
+provider-specific and delegated to the corresponding plugin*
+
+.. code:: yaml
+
+ 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:
+
++-----------+-----------+------------------------------------------------+
+| Operator | Name | Operand |
++===========+===========+================================================+
+| ``eq`` | ``==`` | Any object (string, number, list, dict) |
++-----------+-----------+------------------------------------------------+
+| ``ne`` | ``!=`` | |
++-----------+-----------+------------------------------------------------+
+| ``lt`` | ``<`` | A number (strings are converted to float) |
++-----------+-----------+------------------------------------------------+
+| ``gt`` | ``>`` | |
++-----------+-----------+------------------------------------------------+
+| ``lte`` | ``<=`` | |
++-----------+-----------+------------------------------------------------+
+| ``gte`` | ``>=`` | |
++-----------+-----------+------------------------------------------------+
+| ``any`` | ``Any`` | A list of objects (string, number, list, dict) |
++-----------+-----------+------------------------------------------------+
+| ``all`` | ``All`` | |
++-----------+-----------+------------------------------------------------+
+| ``regex`` | ``RegEx`` | A regular expression pattern |
++-----------+-----------+------------------------------------------------+
+
+Example usage:
+
+.. code:: yaml
+
+ 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.
+
+**Schema**
+
++--------------+------------------------------------------------------------+
+| Name | Value |
++==============+============================================================+
+| ``distance`` | Distance between demands, measured by the geographic path. |
++--------------+------------------------------------------------------------+
+
+The constraint is applied between each pairwise combination of demands.
+For this reason, at least two demands must be specified, implicitly or
+explicitly.
+
+.. code:: yaml
+
+ 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.
+
+**Schema**
+
++--------------+------------------------------------------------------------+
+| Property | Value |
++==============+============================================================+
+| ``distance`` | Distance between demands, measured by the geographic path. |
++--------------+------------------------------------------------------------+
+| ``location`` | A previously declared location. |
++--------------+------------------------------------------------------------+
+
+The constraint is applied between each demand and the referenced
+location, not across all pairwise combinations of Demands.
+
+.. code:: yaml
+
+ 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.
+
+Requirements are sent as a request to a **service controller**. Service
+controllers are defined by plugins in Homing (e.g., ``sdn-c``).
+
+A service controller plugin knows how to communicate with a particular
+endpoint (via HTTP/REST, DMaaP, etc.), obtain necessary information, and
+make a decision. The endpoint and credentials can be configured through
+plugin settings.
+
+**Schema**
+
++---------------------+------------------------------------------------+
+| Property | Description |
++=====================+================================================+
+| ``controller`` | Name of a service controller. |
++---------------------+------------------------------------------------+
+| ``request`` | Opaque dictionary of key/value pairs. Values |
+| | must be strings or numbers. Encoded and sent |
+| | to the service provider via a plugin. |
++---------------------+------------------------------------------------+
+
+.. code:: yaml
+
+ 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.
+
+Requirements are sent as a request to a **service controller**. Service
+controllers are defined by plugins in Homing (e.g., ``sdn-c``).
+
+A service controller plugin knows how to communicate with a particular
+endpoint (via HTTP/REST, DMaaP, etc.), obtain necessary information, and
+make a decision. The endpoint and credentials can be configured through
+plugin settings.
+
+**Schema**
+
++---------------------+------------------------------------------------+
+| Property | Description |
++=====================+================================================+
+| ``controller`` | Name of a service controller. |
++---------------------+------------------------------------------------+
+| ``request`` | Opaque dictionary of key/value pairs. Values |
+| | must be strings or numbers. Encoded and sent |
+| | to the service provider via a plugin. |
++---------------------+------------------------------------------------+
+
+.. code:: yaml
+
+ 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.
+
+Zone categories are inventory provider-defined, based on the demands
+being constrained.
+
+**Schema**
+
++-------------+--------------------------------------------------------+
+| Property | Value |
++=============+========================================================+
+| ``qualifier | Zone qualifier. One of ``same`` or ``different``. |
+| `` | |
++-------------+--------------------------------------------------------+
+| ``category` | Zone category. One of ``disaster``, ``region``, |
+| ` | ``complex``, ``time``, or ``maintenance``. |
++-------------+--------------------------------------------------------+
+
+For example, to place two demands in different disaster zones:
+
+.. code:: yaml
+
+ constraints:
+ vnf_diversity:
+ type: zone
+ demands: [my_vnf_demand, my_other_vnf_demand]
+ properties:
+ qualifier: different
+ category: disaster
+
+Or, to place two demands in the same region:
+
+.. code:: yaml
+
+ constraints:
+ vnf_affinity:
+ type: zone
+ demands: [my_vnf_demand, my_other_vnf_demand]
+ properties:
+ qualifier: same
+ category: region
+
+**Notes**
+
+- 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.
+
+HPA
+~~~~
+
+Constrain each demand's inventory candidates based on cloud regions' Hardware
+platform capabilities (HPA)
+
+Requirements mapped to the inventory provider specified properties, referenced
+by the demands. For eg, properties could be hardware capabilities provided by
+the platform through flavors or cloud-region eg:(CPU-Pinning, NUMA), features
+supported by the services, etc.
+
+
+**Schema**
+
++-------------+--------------------------------------------------------+
+| Property | Value |
++=============+========================================================+
+| ``evaluate | List of flavorLabel, flavorProperties of each VM of the|
+| `` | VNF demand. |
++-------------+--------------------------------------------------------+
+
+.. code:: yaml
+
+ constraints:
+ hpa_constraint:
+ type: hpa
+ demands: [my_vnf_demand, my_other_vnf_demand]
+ properties:
+ evaluate:
+ - [ List of {flavorLabel : {flavor label name},
+ flavorProperties: HPACapability DICT} ]
+ HPACapability DICT :
+ hpa-feature: basicCapabilities
+ hpa-version: v1
+ architecture: generic
+ hpa-feature-attributes:
+ - HPAFEATUREATTRIBUTES LIST
+
+ HPAFEATUREATTRIBUTES LIST:
+ hpa-attribute-key: String
+ hpa-attribute-value: String
+ operator: One of OPERATOR
+ unit: String
+ OPERATOR : ['=', '<', '>', '<=', '>=', 'ALL']
+
+**Example**
+
+.. code:: json
+ {
+ "hpa_constraint":{
+ "type":"hpa",
+ "demands":[
+ "vG"
+ ],
+ "properties":{
+ "evaluate":[
+ {
+ "flavorLabel":"flavor_label_1",
+ "flavorProperties":[
+ {
+ "hpa-feature":"basicCapabilities",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "mandatory": "True",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"numVirtualCpu",
+ "hpa-attribute-value":"32",
+ "operator":"="
+ },
+ {
+ "hpa-attribute-key":"virtualMemSize",
+ "hpa-attribute-value":"64",
+ "operator":"=",
+ "unit":"GB"
+ }
+ ]
+ },
+ {
+ "hpa-feature":"ovsDpdk",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "mandatory": "False",
+ "score": "10",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"dataProcessingAccelerationLibrary",
+ "hpa-attribute-value":"v18.02",
+ "operator":"="
+ }
+ ]
+ }
+ ]
+ },
+ {
+ "flavorLabel":"flavor_label_2",
+ "flavorProperties":[
+ {
+ "hpa-feature":"basicCapabilities",
+ "hpa-version":"v1",
+ "architecture":"generic",
+ "mandatory": "False",
+ "score": "5",
+ "hpa-feature-attributes":[
+ {
+ "hpa-attribute-key":"numVirtualCpu",
+ "hpa-attribute-value":"8",
+ "operator":">="
+ },
+ {
+ "hpa-attribute-key":"virtualMemSize",
+ "hpa-attribute-value":"16",
+ "operator":">=",
+ "unit":"GB"
+ }
+ ]
+ }
+ ]
+ }
+ ]
+ }
+ }
+ }
+
+VIM Fit
+~~~~~~~
+
+Constrain each demand's inventory candidates based on capacity check for
+available capacity at the VIM instances.
+
+Requirements are sent as an opaque request object understood by the VIM
+controllers or MultiCloud. Each controller is defined and implemented as a
+plugin in Conductor.
+
+A vim controller plugin knows how to communicate with a particular endpoint
+(via HTTP/REST, DMaaP, etc.), obtain necessary information, and make a
+decision. The endpoint and credentials can be configured through plugin
+settings.
+
+
+**Schema**
+
++--------------+--------------------------------------------------------+
+| Property | Value |
++==============+========================================================+
+| ``controller | Name of a vim controller. (e.g., multicloud) |
++--------------+--------------------------------------------------------+
+| ``request`` | Opaque dictionary of key/value pairs. Values |
+| | must be strings or numbers. Encoded and sent |
+| | to the vim controller via a plugin. |
++--------------+--------------------------------------------------------+
+
+.. code:: yaml
+
+ constraints:
+ check_cloud_capacity:
+ type: vim_fit
+ demands: [my_vnf_demand, my_other_vnf_demand]
+ properties:
+ controller: multicloud
+ request: REQUEST_DICT
+
+**Notes**
+
+- For ONAP Beijing release the REQUEST_DICT is of the following format as
+ defined by the policy for vim_fit. The REQUEST_DICT is an opaque request
+ object defined through policy, so it is not restricted to this format. In
+ ONAP Beijing release MultiCloud supports the check_vim_capacity using the
+ following grammar.
+ .. code:: json
+ {
+ "request":{
+ "vCPU":10,
+ "Memory":{
+ "quantity":{
+ "get_param":"REQUIRED_MEM"
+ },
+ "unit":"GB"
+ },
+ "Storage":{
+ "quantity":{
+ "get_param":"REQUIRED_DISK"
+ },
+ "unit":"GB"
+ }
+ }
+ }
+
+Inventory Group
+~~~~~~~~~~~~~~~
+
+Constrain demands such that inventory items are grouped across two
+demands.
+
+This constraint has no properties.
+
+.. code:: yaml
+
+ constraints:
+ my_group:
+ type: inventory_group
+ demands: [demand_1, demand_2]
+
+*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.
+
+*Support for this constraint is deferred.*
+
+**Schema**
+
++----------+----------------------------------------------------------+
+| Property | Value |
++==========+==========================================================+
+| ``id`` | Unique license identifier |
++----------+----------------------------------------------------------+
+| ``key`` | Opaque license key, particular to the license identifier |
++----------+----------------------------------------------------------+
+
+.. code:: yaml
+
+ 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.
+
+*Support for this constraint is deferred.*
+
+**Schema**
+
++-------------------+--------------------------------------------------+
+| Property | Value |
++===================+==================================================+
+| ``bandwidth`` | Desired network bandwidth. |
+| (Optional) | |
++-------------------+--------------------------------------------------+
+| ``distance`` | Desired distance between demands, measured by |
+| (Optional) | the network path. |
++-------------------+--------------------------------------------------+
+| ``latency`` | Desired network latency. |
+| (Optional) | |
++-------------------+--------------------------------------------------+
+
+Any combination of ``bandwidth``, ``distance``, or ``latency`` must be
+specified. If none of these properties are used, it is treated as a
+malformed request.
+
+The constraint is applied between each pairwise combination of demands.
+For this reason, at least two demands must be specified, implicitly or
+explicitly.
+
+.. code:: yaml
+
+ 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.
+
+*Support for this constraint is deferred.*
+
+**Schema**
+
++-----------------------------------+-----------------------------------+
+| Property | Value |
++===================================+===================================+
+| ``bandwidth`` | Desired network bandwidth. |
++-----------------------------------+-----------------------------------+
+| ``distance`` | Desired distance between demands, |
+| | measured by the network path. |
++-----------------------------------+-----------------------------------+
+| ``latency`` | Desired network latency. |
++-----------------------------------+-----------------------------------+
+| ``location`` | A previously declared location. |
++-----------------------------------+-----------------------------------+
+
+Any combination of ``bandwidth``, ``distance``, or ``latency`` must be
+specified. If none of these properties are used, it is treated as a
+malformed request.
+
+The constraint is applied between each demand and the referenced
+location, not across all pairwise combinations of Demands.
+
+.. code:: yaml
+
+ 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.
+
+*Support for this constraint is deferred.*
+
+**Schema**
+
++------------+---------------------------------------------------------+
+| Property | Value |
++============+=========================================================+
+| ``specific | Indicates the kind of specification being provided in |
+| ation`` | the properties. Must be ``heat``. Future values may |
+| | include ``tosca``, ``Homing``, etc. |
++------------+---------------------------------------------------------+
+| ``template | For specifications of type ``heat``, a single stack in |
+| `` | OpenStack Heat Orchestration Template (HOT) format. |
+| | Stacks may be expressed as a URI reference or a string |
+| | of well-formed YAML/JSON. Templates are validated by |
+| | the Heat service configured for use by HAS. Nested |
+| | stack references are unsupported. |
++------------+---------------------------------------------------------+
+| ``environm | For specifications of type ``heat``, an optional Heat |
+| ent`` | environment. Environments may be expressed as a URI |
+| (Optional) | reference or a string of well-formed YAML/JSON. |
+| | Environments are validated by the Heat service |
+| | configured for use by Homing. |
++------------+---------------------------------------------------------+
+
+.. code:: yaml
+
+ 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.
+
+Similar to the *instance_fit* constraint, requirements are sent as a
+request to a **service controller** that handles the reservation.
+Service controllers are defined by plugins in Homing (e.g., ``sdn-c``).
+
+The service controller plugin knows how to make a reservation (and
+initiate rollback on a failure) with a particular endpoint (via
+HTTP/REST, DMaaP, etc.) of the service controller. The endpoint and
+credentials can be configured through plugin settings.
+
+**Schema**
+
++---------------------+------------------------------------------------+
+| Property | Description |
++=====================+================================================+
+| ``controller`` | Name of a service controller. |
++---------------------+------------------------------------------------+
+| ``request`` | Opaque dictionary of key/value pairs. Values |
+| | must be strings or numbers. Encoded and sent |
+| | to the service provider via a plugin. |
++---------------------+------------------------------------------------+
+
+.. code:: yaml
+
+ 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:
+
++-------+----------------+--------------------------------------------+
+| Compo | Key | Value |
+| nent | | |
++=======+================+============================================+
+| Goal | ``minimize`` | A single Operand (usually ``sum``) or |
+| | | Function |
++-------+----------------+--------------------------------------------+
+| Opera | ``sum``, | Two or more Operands (Numbers, Operators, |
+| tor | ``product`` | Functions) |
++-------+----------------+--------------------------------------------+
+| Funct | ``distance_bet | A two-element list consisting of a |
+| ion | ween`` | location and demand. |
++-------+----------------+--------------------------------------------+
+
+.. _example-1:
+
+Example
+~~~~~~~
+
+Given a customer location ``cl``, two demands ``vG1`` and ``vG2``, and
+weights ``w1`` and ``w2``, the optimization criteria can be expressed
+as:
+
+``minimize(weight1 * distance_between(cl, vG1) + weight2 * distance_between(cl, vG2))``
+
+This can be read as: “Minimize the sum of weighted distances from cl to
+vG1 and from cl to vG2.”
+
+Such optimizations may be expressed in a template as follows:
+
+.. code:: yaml
+
+ parameters:
+ w1: 10
+ w2: 20
+
+ optimization:
+ minimize:
+ sum:
+ - product:
+ - {get_param: w1}
+ - {distance_between: [cl, vG1]}
+ - product:
+ - {get_param: w2}
+ - {distance_between: [cl, vG2]}
+
+Or without the weights as:
+
+.. code:: yaml
+
+ optimization:
+ minimize:
+ sum:
+ - {distance_between: [cl, vG1]}
+ - {distance_between: [cl, vG2]}
+
+**Template Restriction**
+
+While the template format supports any number of arrangements of
+numbers, operators, and functions, HAS’s solver presently expects a very
+specific arrangement.
+
+Until further notice:
+
+- Optimizations must conform to a single goal of ``minimize`` followed
+ by a ``sum`` operator.
+- The sum can consist of two ``distance_between`` function calls, or
+ two ``product`` operators.
+- If a ``product`` operator is present, it must contain at least a
+ ``distance_between`` function call, plus one optional number to be
+ used for weighting.
+- Numbers may be referenced via ``get_param``.
+- The objective function has to be written in the sum-of-product
+ format. In the future, HAS can convert product-of-sum into
+ sum-of-product automatically.
+
+The first two examples in this section illustrate both of these use
+cases.
+
+**Inline Operations**
+
+If desired, operations can be rewritten inline. For example, the two
+``product`` operations from the previous example can also be expressed
+as:
+
+.. code:: yaml
+
+ parameters:
+ w1: 10
+ w2: 20
+
+ optimization:
+ minimize:
+ sum:
+ - {product: [{get_param: w1}, {distance_between: [cl, vG1]}]}
+ - {product: [{get_param: w2}, {distance_between: [cl, vG2]}]}
+
+In turn, even the ``sum`` operation can be rewritten inline, however
+there is a point of diminishing returns in terms of readability!
+
+**Notes**
+
+- 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.
+
+Functions are written as a dictionary with one key/value pair. The key
+is the function name. The value is a list of arguments. If only one
+argument is provided, a string may be used instead.
+
+.. code:: yaml
+
+ a_property: {FUNCTION_NAME: [ARGUMENT_LIST]}
+
+ a_property: {FUNCTION_NAME: ARGUMENT_STRING}
+
+*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).
+
+The syntax of the ``get_file`` function is:
+
+.. code:: yaml
+
+ {get_file: <content key>}
+
+The ``content`` key is used to look up the ``files`` dictionary that is
+provided in the REST API call. The Homing client command (``Homing``) is
+``get_file`` aware and populates the ``files`` dictionary with the
+actual content of fetched paths and URLs. The Homing client command
+supports relative paths and transforms these to the absolute URLs
+required by the Homing API.
+
+**Note**: The ``get_file`` argument must be a static path or URL and not
+rely on intrinsic functions like ``get_param``. The Homing client does
+not process intrinsic functions. They are only processed by the Homing
+engine.
+
+The example below demonstrates the ``get_file`` function usage with both
+relative and absolute URLs:
+
+.. code:: yaml
+
+ constraints:
+ check_for_fit:
+ type: capacity
+ demands: [my_vnf_demand, my_other_vnf_demand]
+ properties:
+ template: {get_file: stack_template.yaml}
+ environment: {get_file: http://hostname/environment.yaml}
+
+The ``files`` dictionary generated by the Homing client during
+instantiation of the plan would contain the following keys. Each value
+would be of that file’s contents.
+
+- ``file:///path/to/stack_template.yaml``
+- ``http://hostname/environment.yaml``
+
+**Questions**
+
+- 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.
+
+The syntax of the ``get_param`` function is:
+
+.. code:: yaml
+
+ {get_param: <parameter name>}
+
+ {get_param: [<parameter name>, <key/index1> (optional), <key/index2> (optional), ...]}
+
+**parameter name** is the parameter name to be resolved. If the
+parameters returns a complex data structure such as a list or a dict,
+then subsequent keys or indices can be specified. These additional
+parameters are used to navigate the data structure to return the desired
+value. Indices are zero-based.
+
+The following example demonstrates how the ``get_param`` function is
+used:
+
+.. code:: yaml
+
+ parameters:
+ software_id: SOFTWARE_ID
+ license_key: LICENSE_KEY
+ service_info:
+ provider: dmaap:///full.topic.name
+ costs: [10, 20, 30, 40, 50, 60, 70, 80, 90, 100]
+
+ constraints:
+ my_software:
+ type: license
+ demands: [demand_1, demand_2, ...]
+ properties:
+ id: {get_param: software_id}
+ key: {get_param: license_key}
+
+ check_for_availability:
+ type: service
+ demands: [my_vnf_demand, my_other_vnf_demand]
+ properties:
+ provider_url: {get_param: [service_info, provider]}
+ request: REQUEST_DICT
+ cost: {get_param: [service_info, costs, 4]}
+
+In this example, properties would be set as follows:
+
++------------------+--------------------------+
+| Key | Value |
++==================+==========================+
+| ``id`` | SOFTWARE_ID |
++------------------+--------------------------+
+| ``key`` | LICENSE_KEY |
++------------------+--------------------------+
+| ``provider_url`` | dmaap:///full.topic.name |
++------------------+--------------------------+
+| ``cost`` | 50 |
++------------------+--------------------------+
+
+Contact
+-------
+
+Shankar Narayanan shankarpnsn@gmail.com
diff --git a/docs/sections/humaninterfaces.rst b/docs/sections/humaninterfaces.rst
new file mode 100644
index 0000000..5b8c3e7
--- /dev/null
+++ b/docs/sections/humaninterfaces.rst
@@ -0,0 +1,6 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Human Interfaces
+=============================================
+
+ OOF HAS does not expose a human interface \ No newline at end of file
diff --git a/docs/sections/installation.rst b/docs/sections/installation.rst
new file mode 100644
index 0000000..65029c6
--- /dev/null
+++ b/docs/sections/installation.rst
@@ -0,0 +1,22 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Installation
+=============================================
+
+Installing from the Source Code
+------------------------------------
+Get HAS seed code from the Linux Foundation Projects page
+ $ git clone https://gerrit.onap.org/r/optf/has
+
+Use python virtual environment (https://virtualenv.pypa.io/en/stable/) to create and manage libraries and dependencies for HAS project.
+ $ virtualenv {virtual_environment_location}
+
+ $ source {virtual_environemtn_location}/bin/activate
+
+Inside of /has/conductor folder, run the following commands:
+ $ python setup.py install
+
+ $ pip install -e .
+
+In {virtual_environment_location}/bin folder, you should see the five components of HAS/Conductor project
+conductor-api,conductor-controller, conductor-solver, conductor-reservation, conductor-data
diff --git a/docs/sections/logging.rst b/docs/sections/logging.rst
new file mode 100644
index 0000000..86b63f9
--- /dev/null
+++ b/docs/sections/logging.rst
@@ -0,0 +1,16 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Logging
+=============================================
+
+HAS uses a single logger, oslo, across all the components. The logging format is compliant with the EELF recommendations,
+including having the following logs:
+error, audit, metric, application.
+
+The log statements follow the following format (values default to preset values when missing):
+
+Timestamp|RequestId|ServiceInstanceId|ThreadId|Virtual Server Name|ServiceName|InstanceUUID|Log Level|Alarm Severity Level|Server IP Address|HOST NAME|Remote IP Address|Class name|Timer|Detailed Message
+
+The logger util module can be found at:
+
+<>/has/conductor/conductor/common/utils/conductor_logging_util.py \ No newline at end of file
diff --git a/docs/sections/offeredapis.rst b/docs/sections/offeredapis.rst
new file mode 100644
index 0000000..ed215d3
--- /dev/null
+++ b/docs/sections/offeredapis.rst
@@ -0,0 +1,139 @@
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+
+Offered APIs
+=============================================
+
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. Copyright (C) 2017-2018 AT&T Intellectual Property. All rights reserved.
+
+Homing API v1
+------------------
+
+*Updated: 28 Feb 2018*
+
+This document describes the Homing API, provided by the Homing and Allocation service (Conductor).
+It is a work in progress and subject to frequent revision.
+
+General API Information
+------------------
+
+Authenticated calls that target a known URI but that use an HTTP method
+the implementation does not support return a 405 Method Not Allowed
+status. In addition, the HTTP OPTIONS method is supported for each known
+URI. In both cases, the Allow response header indicates the supported
+HTTP methods. See the API Errors section for more information about the
+error response structure.
+
+API versions
+------------------
+
+List all Homing API versions
+----------------------------
+
+**GET** ``/``\ F
+
+**Normal response codes:** 200
+
+.. code:: json
+
+ {
+ "versions": [
+ {
+ "status": "EXPERIMENTAL",
+ "id": "v1",
+ "updated": "2016-11-01T00:00:00Z",
+ "media-types": [
+ {
+ "base": "application/json",
+ "type": "application/vnd.onap.homing-v1+json"
+ }
+ ],
+ "links": [
+ {
+ "href": "http://has.ip/v1",
+ "rel": "self"
+ },
+ {
+ "href": "http://has.url/",
+ "type": "text/html",
+ "rel": "describedby"
+ }
+ ]
+ }
+ ]
+ }
+
+This operation does not accept a request body.
+
+Plans
+------------------
+
+Create a plan
+-------------
+
+**POST** ``/v1/plans``
+
+- **Normal response codes:** 201
+- **Error response codes:** badRequest (400), unauthorized (401),
+ internalServerError (500)
+
+Request an inventory plan for one or more related service demands.
+
+The request includes or references a declarative **template**,
+consisting of:
+
+- **Parameters** that can be referenced like macros
+- **Demands** for service made against inventory
+- **Locations** that are common to the overall plan
+- **Constraints** made against demands, resulting in a set of inventory
+ candidates
+- **Optimizations** to further narrow down the remaining candidates
+
+The response contains an inventory **plan**, consisting of one or more
+sets of recommended pairings of demands with an inventory candidate’s
+attributes and region.
+
+Request Parameters
+~~~~~~~~~~~~~~~~~~
+
++--------------------+------------+----------+------------------------+
+| Parameter | Style | Type | Description |
++====================+============+==========+========================+
+| ``name`` | plain | xsd:stri | A name for the new |
+| (Optional) | | ng | plan. If a name is not |
+| | | | provided, it will be |
+| | | | auto-generated based |
+| | | | on the homing |
+| | | | template. This name |
+| | | | must be unique within |
+| | | | a given Conductor |
+| | | | environment. When |
+| | | | deleting a plan, its |
+| | | | name will not become |
+| | | | available for reuse |
+| | | | until the deletion |
+| | | | completes |
+| | | | successfully. Must |
+| | | | only contain letters, |
+| | | | numbers, hypens, full |
+| | | | stops, underscores, |
+| | | | and tildes (RFC 3986, |
+| | | | Section 2.3). This |
+| | | | parameter is |
+| | | | immutable. |
++--------------------+------------+----------+------------------------+
+| ``id`` (Optional) | plain | csapi:UU | The UUID of the plan. |
+| | | ID | UUID is assigned by |
+| | | | Conductor if no id is |
+| | | | provided in the |
+| | | | request. |
++--------------------+------------+----------+------------------------+
+| ``transaction_id`` | plain | csapi:UU | The transaction id |
+| | | ID | assigned by SO. The |
+| | | | logs should have this |
+| | | | transaction id for |
+| | | | tracking purposes. |
++--------------------+------------+----------+------------------------+
+| ``files`` | plain | xsd:dict | Supplies the contents |
+| (Optional) | | | of files referenced. |
++--------------------+------------+----------+------------------------+ \ No newline at end of file
diff --git a/docs/sections/release-notes.rst b/docs/sections/release-notes.rst
new file mode 100644
index 0000000..32ea3a0
--- /dev/null
+++ b/docs/sections/release-notes.rst
@@ -0,0 +1,43 @@
+..
+ This work is licensed under a Creative Commons Attribution 4.0
+ International License.
+
+=============
+Release Notes
+=============
+
+Release Date
+------------
+2018-05-24
+
+
+New Features
+------------
+* Baseline HAS functionality
+* Integration with OOF OSDF, AAI, and Multi-Cloud
+* Platform Maturity Level 1
+* ~50%+ unit test coverage
+
+Bug Fixes
+---------
+None
+
+Known Issues
+------------
+None
+
+Security Issues
+---------------
+None
+
+Upgrade Notes
+-------------
+None
+
+Deprecation Notes
+-----------------
+None
+
+Other
+-----
+None \ No newline at end of file