This operation does not accept a request body.
Plans
-------------------
+-----
Create a plan
-------------
- **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"
+ }
+ }
Code Review / optf / has.git / commitdiff