diff options
| -rw-r--r-- | docs/index.rst | 19 | ||||
| -rw-r--r-- | docs/sections/delivery.rst | 6 | ||||
| -rw-r--r-- | docs/sections/offeredapis.rst | 624 |
3 files changed, 598 insertions, 51 deletions
diff --git a/docs/index.rst b/docs/index.rst index afea941..69b61c3 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -21,18 +21,33 @@ for wider range of services, e.g., DCAE micro-services, ECOMP control loops, ser Finally, HAS provides an traceable mechanism for what-if analysis which is critical for ease of understanding a homing recommendation and resolving infeasibility scenarios. +OF-HAS is the implementation of the ONAP Homing Service. The formal project name in ONAP is *OF-HAS*. +The informal name for the project is *Conductor* (inherited from the seed-code), which is interchangeably +used through the project. + +Given the description of what needs to be deployed (demands) and the placement requirements (constraints), +Conductor determines placement candidates that meet all constraints while optimizing the resource usage +of the AIC infrastructure. A customer request may be satisfied by deploying new VMs in AIC (AIC inventory) +or by using existing service instances with enough remaining capacity (service inventory). + +From a canonical standpoint, Conductor is known as a *homing service*, in the same way OpenStack Heat +is an orchestration service, or Nova is a compute service. + + .. toctree:: :maxdepth: 1 ./sections/architecture.rst - ./sections/homingspecification.rst ./sections/offeredapis.rst + ./sections/homingspecification.rst ./sections/consumedapis.rst - ./sections/delivery.rst + Distribution <./sections/distribution.rst> ./sections/logging.rst ./sections/installation.rst ./sections/configuration.rst ./sections/administration.rst ./sections/humaninterfaces.rst + ./sections/glossary.rst + Example Homing Templates <./sections/example.rst> ./sections/release-notes.rst diff --git a/docs/sections/delivery.rst b/docs/sections/delivery.rst deleted file mode 100644 index bfe8480..0000000 --- a/docs/sections/delivery.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. 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/offeredapis.rst b/docs/sections/offeredapis.rst index 7ef44e9..9ffb6fb 100644 --- a/docs/sections/offeredapis.rst +++ b/docs/sections/offeredapis.rst @@ -66,7 +66,7 @@ List all Homing API versions This operation does not accept a request body. Plans ------------------- +----- Create a plan ------------- @@ -90,50 +90,588 @@ consisting of: - **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 +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 ++--------------------+-------+------------+-------------------+ +| Parameter | Style | Type | Description | ++====================+=======+============+===================+ +| ``name`` | plain | xsd:string | A name for the | +| (Optional) | | | new 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`` | plain | csapi:UUID | The UUID of | +| (Optional) | | | the plan. UUID | +| | | | is assigned by | +| | | | Conductor if | +| | | | no id is | +| | | | provided in | +| | | | the request. | ++--------------------+-------+------------+-------------------+ +| ``transaction_id`` | plain | csapi:UUID | The | +| | | | transaction id | +| | | | assigned by | +| | | | MSO. The logs | +| | | | should have | +| | | | this | +| | | | transaction id | +| | | | for tracking | +| | | | purposes. | ++--------------------+-------+------------+-------------------+ +| ``files`` | plain | xsd:dict | Supplies the | +| (Optional) | | | contents of | +| | | | files | +| | | | referenced in | +| | | | the template. | +| | | | Conductor | +| | | | templates can | +| | | | explicitly | +| | | | reference | +| | | | files by using | +| | | | the | +| | | | ``get_file`` | +| | | | intrinsic | +| | | | function. The | +| | | | value is a | +| | | | JSON object, | +| | | | where each key | +| | | | is a relative | +| | | | or absolute | +| | | | URI which | +| | | | serves as the | +| | | | name of a | +| | | | file, and the | +| | | | associated | +| | | | value provides | +| | | | the contents | +| | | | of the file. | +| | | | Additionally, | +| | | | some template | +| | | | authors encode | +| | | | their user | +| | | | data in a | +| | | | local file. | +| | | | The Homing | +| | | | client (e.g., | +| | | | a CLI) can | +| | | | examine the | +| | | | template for | +| | | | the | +| | | | ``get_file`` | +| | | | intrinsic | +| | | | function | +| | | | (e.g., | +| | | | ``{get_file: f | +| | | | ile.yaml}``) | +| | | | and add an | +| | | | entry to the | +| | | | ``files`` map | +| | | | with the path | +| | | | to the file as | +| | | | the name and | +| | | | the file | +| | | | contents as | +| | | | the value. Do | +| | | | not use this | +| | | | parameter to | +| | | | provide the | +| | | | content of the | +| | | | template | +| | | | located at the | +| | | | ``template_url`` | +| | | | address. | +| | | | Instead, use | +| | | | the | +| | | | ``template`` | +| | | | parameter to | +| | | | supply the | +| | | | template | +| | | | content as | +| | | | part of the | +| | | | request. | ++--------------------+-------+------------+-------------------+ +| ``template_url`` | plain | xsd:string | A URI to | +| (Optional) | | | the location | +| | | | containing the | +| | | | template on | +| | | | which to | +| | | | perform the | +| | | | operation. See | +| | | | the | +| | | | description of | +| | | | the | +| | | | ``template`` | +| | | | parameter for | +| | | | information | +| | | | about the | +| | | | expected | +| | | | template | +| | | | content | +| | | | located at the | +| | | | URI. This | +| | | | parameter is | +| | | | only required | +| | | | when you omit | +| | | | the | +| | | | ``template`` | +| | | | parameter. If | +| | | | you specify | +| | | | both | +| | | | parameters, | +| | | | this parameter | +| | | | is ignored. | ++--------------------+-------+------------+-------------------+ +| ``template`` | plain | xsd:string | The template | +| | | or xsd:dict| on which to | +| | | | perform the | +| | | | operation. See | +| | | | the Homing | +| | | | Template | +| | | | Guide | +| | | | for complete | +| | | | information on | +| | | | the format. | +| | | | This parameter | +| | | | is either | +| | | | provided as a | +| | | | ``string`` or | +| | | | ``dict`` in | +| | | | the JSON | +| | | | request body. | +| | | | For ``string`` | +| | | | content it may | +| | | | be a JSON- or | +| | | | YAML-formatted | +| | | | Conductor | +| | | | template. For | +| | | | ``dict`` | +| | | | content it | +| | | | must be a | +| | | | direct JSON | +| | | | representation | +| | | | of the | +| | | | Conductor | +| | | | template. This | +| | | | parameter is | +| | | | required only | +| | | | when you omit | +| | | | the | +| | | | ``template_url`` | +| | | | parameter. If | +| | | | you specify | +| | | | both | +| | | | parameters, | +| | | | this value | +| | | | overrides the | +| | | | ``template_url`` | +| | | | parameter | +| | | | value. | ++--------------------+-------+------------+-------------------+ +| ``timeout`` | plain | xsd:number | The timeout | +| (Optional) | | | for plan | +| | | | creation in | +| | | | minutes. | +| | | | Default is 1. | ++--------------------+-------+------------+-------------------+ +| ``limit`` | plain | xsd:number | The maximum | +| (Optional) | | | number of | +| | | | recommendations | +| | | | to return. | +| | | | Default is 1. | ++--------------------+-------+------------+-------------------+ + +**NOTE**: ``files``, ``template_url``, and ``timeout`` are not yet +supported. + +Response Parameters +~~~~~~~~~~~~~~~~~~~ + ++--------------------+----------+------------+--------------------+ +| Parameter | Style | Type | Description | ++====================+==========+============+====================+ +| ``plan`` | plain | xsd:dict | The ``plan`` | +| | | | object. | ++--------------------+----------+------------+--------------------+ +| ``id`` | plain | csapi:UUID | The UUID of | +| | | | the plan. | ++--------------------+----------+------------+--------------------+ +| ``transaction_id`` | plain | csapi:UUID | The | +| | | | transaction id | +| | | | assigned by | +| | | | the MSO. | ++--------------------+----------+------------+--------------------+ +| ``name`` | plain | xsd:string | The plan name. | +| | | | | ++--------------------+----------+------------+--------------------+ +| ``status`` | plain | xsd:string | The plan | +| | | | status. One of | +| | | | ``template``, | +| | | | ``translated``, | +| | | | ``solving``, | +| | | | ``solved``, or | +| | | | ``error``. See | +| | | | **Plan | +| | | | Status** table | +| | | | for | +| | | | descriptions | +| | | | of each value. | ++--------------------+----------+------------+--------------------+ +| ``message`` | plain | xsd:string | Additional | +| | | | context, if | +| | | | any, around | +| | | | the message | +| | | | status. If the | +| | | | status is | +| | | | ``error``, | +| | | | this may | +| | | | include a | +| | | | reason and | +| | | | suggested | +| | | | remediation, | +| | | | if available. | ++--------------------+----------+------------+--------------------+ +| ``links`` | plain | xsd:list | A list of URLs | +| | | | for the plan. | +| | | | Each URL is a | +| | | | JSON object | +| | | | with an | +| | | | ``href`` key | +| | | | indicating the | +| | | | URL and a | +| | | | ``rel`` key | +| | | | indicating its | +| | | | relationship | +| | | | to the plan in | +| | | | question. | +| | | | There may be | +| | | | multiple links | +| | | | returned. The | +| | | | ``self`` | +| | | | relationship | +| | | | identifies the | +| | | | URL of the | +| | | | plan itself. | ++--------------------+----------+------------+--------------------+ +| ``recommendations``| plain | xsd:list | A list of one | +| | | | or more | +| | | | recommendationS. | +| | | | A | +| | | | recommendation | +| | | | pairs each | +| | | | requested | +| | | | demand with an | +| | | | inventory | +| | | | provider, a | +| | | | single | +| | | | candidate, and | +| | | | an opaque | +| | | | dictionary of | +| | | | attributes. | +| | | | Refer to the | +| | | | Demand | +| | | | candidate | +| | | | schema in the | +| | | | Homing | +| | | | Template | +| | | | Guide | +| | | | for further | +| | | | details. (Note | +| | | | that, when | +| | | | ``inventory_type`` | +| | | | is ``cloud`` | +| | | | the | +| | | | candidate's | +| | | | ``candidate_id`` | +| | | | field is | +| | | | redundant and | +| | | | thus omitted.) | ++--------------------+----------+------------+--------------------+ + +Plan Status +~~~~~~~~~~~ + ++----------------+-----------------+ +| Status | Description | ++================+=================+ +| ``template`` | Plan request | +| | and homing | +| | template have | +| | been received. | +| | Awaiting | +| | translation. | ++----------------+-----------------+ +| ``translated`` | Homing | +| | template has | +| | been | +| | translated, | +| | and candidates | +| | have been | +| | obtained from | +| | inventory | +| | providers. | +| | Awaiting | +| | solving. | ++----------------+-----------------+ +| ``solving`` | Search for a | +| | solution is in | +| | progress. This | +| | may | +| | incorporate | +| | requests to | +| | service | +| | controllers | +| | for additional | +| | information. | ++----------------+-----------------+ +| ``solved`` | Search is | +| | complete. A | +| | solution with | +| | one or more | +| | recommendations | +| | was found. | ++----------------+-----------------+ +| ``not found`` | Search is | +| | complete. No | +| | recommendations | +| | were found. | ++----------------+-----------------+ +| ``error`` | An error was | +| | encountered. | ++----------------+-----------------+ + +State Diagram +^^^^^^^^^^^^^ + +.. code:: text + + ---------------------------------------- + | | + | /---> solved ---> reserving ---> done + | / / + template -> translated -> solving ------> not found / + | ^ | \ / + | | conditionally | \---> error <----/ + | | (see note) | ^ + | \---------------/ | + \---------------------------------------/ + +**NOTE**: When Conductor's solver service is started in non-concurrent +mode (the default), it will reset any plans found waiting and stuck in +the ``solving`` state back to ``translated``. + +.. code:: json + + { + "name": "PLAN_NAME", + "template": "CONDUCTOR_TEMPLATE", + "limit": 3 + } + +.. code:: json + + { + "plan": { + "name": "PLAN_NAME", + "id": "ee1c5269-c7f0-492a-8652-f0ceb15ed3bc", + "transaction_id": "6bca5f2b-ee7e-4637-8b58-1b4b36ed10f9", + "status": "solved", + "message", "Plan PLAN_NAME is solved.", + "links": [ + { + "href": "http://homing/v1/plans/ee1c5269-c7f0-492a-8652-f0ceb15ed3bc", + "rel": "self" + } + ], + "recommendations": [ + { + "DEMAND_NAME_1": { + "inventory_provider": "aai", + "service_resource_id": "4feb0545-69e2-424c-b3c4-b270e5f2a15d", + "candidate": { + "candidate_id": "99befee8-e8c0-425b-8f36-fb7a8098d9a9", + "inventory_type": "service", + "location_type": "aic", + "location_id": "dal01", + "host_id" : "vig20002vm001vig001" + }, + "attributes": {OPAQUE-DICT} + }, + "DEMAND_NAME_2": { + "inventory_provider": "aai", + "service_resource_id": "578eb063-b24a-4654-ba9e-1e5cf7eb9183", + "candidate": { + "inventory_type": "cloud", + "location_type": "aic", + "location_id": "dal02" + }, + "attributes": {OPAQUE-DICT} + } + }, + { + "DEMAND_NAME_1": { + "inventory_provider": "aai", + "service_resource_id": "4feb0545-69e2-424c-b3c4-b270e5f2a15d", + "candidate": { + "candidate_id": "99befee8-e8c0-425b-8f36-fb7a8098d9a9", + "inventory_type": "service", + "location_type": "aic", + "location_id": "dal03", + "host_id" : "vig20001vm001vig001" + }, + "attributes": {OPAQUE-DICT} + }, + "DEMAND_NAME_2": { + "inventory_provider": "aai", + "service_resource_id": "578eb063-b24a-4654-ba9e-1e5cf7eb9183", + "candidate": { + "inventory_type": "cloud", + "location_type": "aic", + "location_id": "dal04" + }, + "attributes": {OPAQUE-DICT} + } + }, + ... + ] + } + } + +Show plan details +----------------- + +**GET** ``/v1/plans/{plan_id}`` + +- **Normal response codes:** 200 +- **Error response codes:** unauthorized (401), itemNotFound (404) + +Request parameters +~~~~~~~~~~~~~~~~~~ + ++---------------+---------+--------------+-------------------------+ +| Parameter | Style | Type | Description | ++===============+=========+==============+=========================+ +| ``plan_id`` | plain | csapi:UUID | The UUID of the plan. | ++---------------+---------+--------------+-------------------------+ + +Response Parameters +~~~~~~~~~~~~~~~~~~~ + +See the Response Parameters for **Create a plan**. + +Delete a plan +------------- + +**DELETE** ``/v1/plans/{plan_id}`` + +- **Normal response codes:** 204 +- **Error response codes:** badRequest (400), unauthorized (401), + itemNotFound (404) + +Request parameters +~~~~~~~~~~~~~~~~~~ + ++---------------+---------+--------------+-------------------------+ +| Parameter | Style | Type | Description | ++===============+=========+==============+=========================+ +| ``plan_id`` | plain | csapi:UUID | The UUID of the plan. | ++---------------+---------+--------------+-------------------------+ + +This operation does not accept a request body and does not return a +response body. + +API Errors +---------- + +In the event of an error with a status other than unauthorized (401), a +detailed repsonse body is returned. + +Response parameters +~~~~~~~~~~~~~~~~~~~ + ++-----------------+--------+------------+---------------------------------------------+ +| Parameter | Style | Type | Description | ++=================+========+============+=============================================+ +| ``title`` | plain | xsd:string | Human-readable name. | ++-----------------+--------+------------+---------------------------------------------+ +| ``explanation`` | plain | xsd:string | Detailed explanation with remediation (if | +| | | | any). | ++-----------------+--------+------------+---------------------------------------------+ +| ``code`` | plain | xsd:int | HTTP Status Code. | ++-----------------+--------+------------+---------------------------------------------+ +| ``error`` | plain | xsd:dict | Error dictionary. Keys include **message**, | +| | | | **traceback**, and **type**. | ++-----------------+--------+------------+---------------------------------------------+ +| ``message`` | plain | xsd:string | Internal error message. | ++-----------------+--------+------------+---------------------------------------------+ +| ``traceback`` | plain | xsd:string | Python traceback (if available). | +| | | | | ++-----------------+--------+------------+---------------------------------------------+ +| ``type`` | plain | xsd:string | HTTP Status class name (from python-webob) | ++-----------------+--------+------------+---------------------------------------------+ + +Examples +^^^^^^^^ + +A plan with the name "pl an" is considered a bad request because the +name contains a space. + +.. code:: json + + { + "title": "Bad Request", + "explanation": "-> name -> pl an did not pass validation against callable: plan_name_type (must contain only uppercase and lowercase letters, decimal digits, hyphens, periods, underscores, and tildes [RFC 3986, Section 2.3])", + "code": 400, + "error": { + "message": "The server could not comply with the request since it is either malformed or otherwise incorrect.", + "type": "HTTPBadRequest" + } + } + +The HTTP COPY method was attempted but is not allowed. + +.. code:: json + + { + "title": "Method Not Allowed", + "explanation": "The COPY method is not allowed.", + "code": 405, + "error": { + "message": "The server could not comply with the request since it is either malformed or otherwise incorrect.", + "type": "HTTPMethodNotAllowed" + } + } |