Allocation API: reference documentation

Change-Id: I48f20f0b96931a17c477b9687b0ee963cb7b8879
Story: #2004341
Task: #29574

api-ref/regenerate-samples.sh

@@ -27,6 +27,7 @@ DOC_PROVISION_UPDATED_AT="2016-08-18T22:28:49.946416+00:00"
 DOC_CREATED_AT="2016-08-18T22:28:48.643434+11:11"
 DOC_UPDATED_AT="2016-08-18T22:28:49.653974+00:00"
 DOC_IRONIC_CONDUCTOR_HOSTNAME="897ab1dad809"
+DOC_ALLOCATION_UUID="3bf138ba-6d71-44e7-b6a1-ca9cac17103e"
 
 function GET {
     # GET $RESOURCE
@@ -167,13 +168,37 @@ GET v1/nodes > nodes-list-response.json
 GET v1/nodes/detail > nodes-list-details-response.json
 GET v1/nodes/$NID > node-show-response.json
 
-# Put the Node in maintenance mode, then continue doing everything else
-PUT v1/nodes/$NID/maintenance node-maintenance-request.json
-
 # Node traits
 PUT v1/nodes/$NID/traits node-set-traits-request.json
 GET v1/nodes/$NID/traits > node-traits-list-response.json
 
+############
+# ALLOCATIONS
+
+POST v1/allocations allocation-create-request.json > allocation-create-response.json
+AID=$(cat allocation-create-response.json | grep '"uuid"' | sed 's/.*"\([0-9a-f\-]*\)",*/\1/')
+if [ "$AID" == "" ]; then
+    exit 1
+else
+    echo "Allocation created. UUID: $AID"
+fi
+
+# Create a failed allocation for listing
+POST v1/allocations allocation-create-request-2.json
+
+# Poor man's wait_for_allocation
+sleep 1
+
+GET v1/allocations > allocations-list-response.json
+GET v1/allocations/$AID > allocation-show-response.json
+GET v1/nodes/$NID/allocation > node-allocation-show-response.json
+
+############
+# NODES - MAINTENANCE
+
+# Do this after allocation API to be able to create successful allocations
+PUT v1/nodes/$NID/maintenance node-maintenance-request.json
+
 ############
 # PORTGROUPS
 
@@ -312,6 +337,7 @@ sed -i "s/$PID/$DOC_PORT_UUID/" *.json
 sed -i "s/$PGID/$DOC_PORTGROUP_UUID/" *.json
 sed -i "s/$VCID/$DOC_VOL_CONNECTOR_UUID/" *.json
 sed -i "s/$VTID/$DOC_VOL_TARGET_UUID/" *.json
+sed -i "s/$AID/$DOC_ALLOCATION_UUID/" *.json
 sed -i "s/$(hostname)/$DOC_IRONIC_CONDUCTOR_HOSTNAME/" *.json
 sed -i "s/created_at\": \".*\"/created_at\": \"$DOC_CREATED_AT\"/" *.json
 sed -i "s/updated_at\": \".*\"/updated_at\": \"$DOC_UPDATED_AT\"/" *.json

api-ref/source/baremetal-api-v1-allocation.inc

@@ -0,0 +1,210 @@
+.. -*- rst -*-
+
+=========================
+Allocations (allocations)
+=========================
+
+The Allocation resource represents a request to find and allocate a Node for
+deployment.
+
+.. versionadded:: 1.52
+    Allocation API was introduced.
+
+Create Allocation
+=================
+
+.. rest_method::  POST /v1/allocations
+
+Creates an allocation.
+
+A Node can be requested by its resource class and traits. Additionally, Nodes
+can be pre-filtered on the client side, and the resulting list of UUIDs and/or
+names can be submitted as ``candidate_nodes``. Otherwise all nodes are
+considered.
+
+A Node is suitable for an Allocation if all of the following holds:
+
+* ``provision_state`` is ``available``
+* ``power_state`` is not ``null``
+* ``maintenance`` is false
+* ``instance_uuid`` is ``null``
+* ``resource_class`` matches requested one
+* ``traits`` list contains the requested ones
+
+The allocation process is asynchronous. The new Allocation is returned in
+the ``allocating`` state, and the process continues in background. If it
+succeeds, the ``node_uuid`` field is populated with the Node's UUID, and the
+Node's ``instance_uuid`` field is set to the Allocation's UUID.
+
+.. versionadded:: 1.52
+    Allocation API was introduced.
+
+Normal response codes: 201
+
+Error response codes: 400, 401, 403, 409, 503
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - resource_class: req_allocation_resource_class
+   - candidate_nodes: req_candidate_nodes
+   - name: req_allocation_name
+   - traits: req_allocation_traits
+   - uuid: req_uuid
+   - extra: req_extra
+
+Request Example
+---------------
+
+.. literalinclude:: samples/allocation-create-request.json
+   :language: javascript
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - candidate_nodes: candidate_nodes
+   - last_error: allocation_last_error
+   - name: allocation_name
+   - node_uuid: allocation_node
+   - resource_class: allocation_resource_class
+   - state: allocation_state
+   - traits: allocation_traits
+   - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+Response Example
+----------------
+
+.. literalinclude:: samples/allocation-create-response.json
+   :language: javascript
+
+List Allocations
+================
+
+.. rest_method::  GET /v1/allocations
+
+Lists all Allocations.
+
+.. versionadded:: 1.52
+    Allocation API was introduced.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node: r_allocation_node
+   - resource_class: r_resource_class
+   - state: r_allocation_state
+   - fields: fields
+   - limit: limit
+   - marker: marker
+   - sort_dir: sort_dir
+   - sort_key: sort_key
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - candidate_nodes: candidate_nodes
+   - last_error: allocation_last_error
+   - name: allocation_name
+   - node_uuid: allocation_node
+   - resource_class: allocation_resource_class
+   - state: allocation_state
+   - traits: allocation_traits
+   - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+Response Example
+----------------
+
+.. literalinclude:: samples/allocations-list-response.json
+   :language: javascript
+
+Show Allocation Details
+=======================
+
+.. rest_method::  GET /v1/allocations/{allocation_id}
+
+Shows details for an Allocation.
+
+.. versionadded:: 1.52
+    Allocation API was introduced.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - fields: fields
+   - allocation_id: allocation_ident
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - candidate_nodes: candidate_nodes
+   - last_error: allocation_last_error
+   - name: allocation_name
+   - node_uuid: allocation_node
+   - resource_class: allocation_resource_class
+   - state: allocation_state
+   - traits: allocation_traits
+   - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+Response Example
+----------------
+
+.. literalinclude:: samples/allocation-show-response.json
+   :language: javascript
+
+Delete Allocation
+=================
+
+.. rest_method::  DELETE /v1/allocations/{allocation_id}
+
+Deletes an Allocation.
+
+If the Allocation has a Node associated, the Node's ``instance_uuid`` is reset.
+
+The deletion will fail if the Allocation has a Node assigned and the Node is
+``active`` and not in the maintenance mode.
+
+.. versionadded:: 1.52
+    Allocation API was introduced.
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 403, 404, 409, 503
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - allocation_id: allocation_ident

api-ref/source/baremetal-api-v1-node-allocation.inc

@@ -0,0 +1,81 @@
+.. -*- rst -*-
+
+====================================
+Node Allocation (allocations, nodes)
+====================================
+
+Given a Node identifier (``uuid`` or ``name``), the API allows to get and
+delete the associated allocation.
+
+.. versionadded:: 1.52
+    Allocation API was introduced.
+
+Show Allocation by Node
+=======================
+
+.. rest_method::  GET /v1/nodes/{node_ident}/allocation
+
+Shows details for an allocation.
+
+.. versionadded:: 1.52
+    Allocation API was introduced.
+
+Normal response codes: 200
+
+Error response codes: 400, 401, 403, 404
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - node_ident: node_ident
+   - fields: fields
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - uuid: uuid
+   - candidate_nodes: candidate_nodes
+   - last_error: allocation_last_error
+   - name: allocation_name
+   - node_uuid: allocation_node
+   - resource_class: allocation_resource_class
+   - state: allocation_state
+   - traits: allocation_traits
+   - extra: extra
+   - created_at: created_at
+   - updated_at: updated_at
+   - links: links
+
+Response Example
+----------------
+
+.. literalinclude:: samples/allocation-show-response.json
+   :language: javascript
+
+Delete Allocation by Node
+=========================
+
+.. rest_method::  DELETE /v1/nodes/{node_ident}/allocation
+
+Deletes the allocation of this node.
+
+The deletion will fail if the allocation the node is ``active`` and not in
+the ``maintenance`` mode.
+
+.. versionadded:: 1.52
+    Allocation API was introduced.
+
+Normal response codes: 204
+
+Error response codes: 400, 401, 403, 404, 409, 503
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+  - node_ident: node_ident

api-ref/source/baremetal-api-v1-nodes.inc

@@ -98,6 +98,9 @@ supplied when the Node is created, or the resource may be updated later.
 .. versionadded:: 1.51
   Introduced the ``description`` field.
 
+.. versionadded:: 1.52
+  Introduced the ``allocation_uuid`` field.
+
 Normal response codes: 201
 
 Error codes: 400,403,406
@@ -199,6 +202,7 @@ microversion 1.48.
     - conductor: conductor
     - owner: owner
     - description: n_description
+    - allocation_uuid: allocation_uuid
 
 **Example JSON representation of a Node:**
 
@@ -340,6 +344,9 @@ Nova instance, eg. with a request to ``v1/nodes/detail?instance_uuid={NOVA INSTA
 .. versionadded:: 1.51
   Introduced the ``description`` field.
 
+.. versionadded:: 1.52
+  Introduced the ``allocation_uuid`` field.
+
 Normal response codes: 200
 
 Error codes: 400,403,406
@@ -418,6 +425,7 @@ Response
     - owner: owner
     - description: n_description
     - conductor: conductor
+    - allocation_uuid: allocation_uuid
 
 **Example detailed list of Nodes:**
 
@@ -458,6 +466,9 @@ only the specified set.
 .. versionadded:: 1.51
   Introduced the ``description`` field.
 
+.. versionadded:: 1.52
+  Introduced the ``allocation_uuid`` field.
+
 Normal response codes: 200
 
 Error codes: 400,403,404,406
@@ -523,6 +534,7 @@ Response
     - owner: owner
     - description: n_description
     - conductor: conductor
+    - allocation_uuid: allocation_uuid
 
 **Example JSON representation of a Node:**
 
@@ -617,6 +629,7 @@ Response
     - owner: owner
     - description: n_description
     - conductor: conductor
+    - allocation_uuid: allocation_uuid
 
 **Example JSON representation of a Node:**
 

api-ref/source/index.rst

@@ -21,8 +21,11 @@
 .. include:: baremetal-api-v1-nodes-volume.inc
 .. include:: baremetal-api-v1-drivers.inc
 .. include:: baremetal-api-v1-driver-passthru.inc
-.. include:: baremetal-api-v1-chassis.inc
-.. include:: baremetal-api-v1-misc.inc
 .. include:: baremetal-api-v1-nodes-bios.inc
 .. include:: baremetal-api-v1-conductors.inc
-
+.. include:: baremetal-api-v1-allocation.inc
+.. include:: baremetal-api-v1-node-allocation.inc
+.. NOTE(dtantsur): keep chassis close to the end since it's semi-deprecated
+.. include:: baremetal-api-v1-chassis.inc
+.. NOTE(dtantsur): keep misc last, since it covers internal API
+.. include:: baremetal-api-v1-misc.inc

api-ref/source/parameters.yaml

@@ -38,6 +38,12 @@ x-openstack-ironic-api-version:
   type: string
 
 # variables in path
+allocation_ident:
+  description: |
+    The UUID or name of the allocation.
+  in: path
+  required: true
+  type: string
 bios_setting:
   description: |
     The name of the Bios setting.
@@ -208,7 +214,20 @@ r_addresses:
   required: false
   type: array
 
-# variables in the node query string
+# variables in the query string
+r_allocation_node:
+  description: |
+    Filter the list of allocations by the node UUID or name.
+  in: query
+  required: false
+  type: string
+r_allocation_state:
+  description: |
+    Filter the list of allocations by the allocation state, one of ``active``,
+    ``allocating`` or ``error``.
+  in: query
+  required: false
+  type: string
 r_associated:
   description: |
     Filter the list of returned nodes and only return those which are, or are
@@ -372,7 +391,6 @@ sort_key:
   type: string
 
 
-
 # variable returned from /lookup
 agent_config:
   description: |
@@ -397,6 +415,57 @@ alive:
   in: body
   required: true
   type: boolean
+allocation_last_error:
+  description: |
+    The error message for the allocation if it is in the ``error`` state,
+    ``null`` otherwise.
+  in: body
+  required: true
+  type: string
+allocation_name:
+  description: |
+    The unique name of the allocation.
+  in: body
+  required: true
+  type: string
+allocation_node:
+  description: |
+    The UUID of the node assigned to the allocation. Will be ``null`` if a node
+    is not yet assigned.
+  in: body
+  required: true
+  type: string
+allocation_resource_class:
+  description: |
+    The resource class requested for the allocation.
+  in: body
+  required: true
+  type: string
+allocation_state:
+  description: |
+    The current state of the allocation. One of:
+
+    * ``allocating`` - allocation is in progress.
+    * ``active`` - allocation is finished and ``node_uuid`` is assigned.
+    * ``error`` - allocation has failed, see ``last_error`` for details.
+  in: body
+  required: true
+  type: string
+allocation_traits:
+  description: |
+    The list of the traits requested for the allocation.
+  in: body
+  required: true
+  type: array
+allocation_uuid:
+  description: |
+    The UUID of the allocation associated with the node. If not ``null``, will
+    be the same as ``instance_uuid`` (the opposite is not always true).
+    Unlike ``instance_uuid``, this field is read-only. Please use the
+    Allocation API to remove allocations.
+  in: body
+  required: true
+  type: string
 bios_setting_name:
   description: |
     The name of a Bios setting for a Node, eg. "virtualization".
@@ -428,6 +497,12 @@ boot_interface:
   in: body
   required: true
   type: string
+candidate_nodes:
+  description: |
+    A list of UUIDs of the nodes that are candidates for this allocation.
+  in: body
+  required: true
+  type: array
 chassis:
   description: |
     A ``chassis`` object.
@@ -1108,6 +1183,24 @@ reason:
   in: body
   required: false
   type: string
+req_allocation_name:
+  description: |
+    The unique name of the Allocation.
+  in: body
+  required: false
+  type: string
+req_allocation_resource_class:
+  description: |
+    The requested resource class for the allocation.
+  in: body
+  required: true
+  type: string
+req_allocation_traits:
+  description: |
+    The list of requested traits for the allocation.
+  in: body
+  required: false
+  type: array
 req_boot_device:
   description: |
     The boot device for a Node, eg. "pxe" or "disk".
@@ -1120,6 +1213,13 @@ req_boot_interface:
   in: body
   required: false
   type: string
+req_candidate_nodes:
+  description: |
+    The list of nodes that should be considered for this allocation. If not
+    provided, all available nodes will be considered.
+  in: body
+  required: false
+  type: array
 req_chassis:
   description: |
     A ``chassis`` object.

api-ref/source/samples/allocation-create-request-2.json

@@ -0,0 +1,6 @@
+{
+    "name": "allocation-2",
+    "resource_class": "bm-large",
+    "traits": ["CUSTOM_GOLD"]
+}
+

api-ref/source/samples/allocation-create-request.json

@@ -0,0 +1,4 @@
+{
+    "name": "allocation-1",
+    "resource_class": "bm-large"
+}

api-ref/source/samples/allocation-create-response.json

@@ -0,0 +1,23 @@
+{
+  "candidate_nodes": [],
+  "created_at": "2019-02-20T09:43:58+00:00",
+  "extra": {},
+  "last_error": null,
+  "links": [
+    {
+      "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
+      "rel": "bookmark"
+    }
+  ],
+  "name": "allocation-1",
+  "node_uuid": null,
+  "resource_class": "bm-large",
+  "state": "allocating",
+  "traits": [],
+  "updated_at": null,
+  "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
+}

api-ref/source/samples/allocation-show-response.json

@@ -0,0 +1,23 @@
+{
+  "candidate_nodes": [],
+  "created_at": "2019-02-20T09:43:58+00:00",
+  "extra": {},
+  "last_error": null,
+  "links": [
+    {
+      "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
+      "rel": "self"
+    },
+    {
+      "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
+      "rel": "bookmark"
+    }
+  ],
+  "name": "allocation-1",
+  "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+  "resource_class": "bm-large",
+  "state": "active",
+  "traits": [],
+  "updated_at": "2019-02-20T09:43:58+00:00",
+  "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
+}

api-ref/source/samples/allocations-list-response.json

@@ -0,0 +1,52 @@
+{
+  "allocations": [
+    {
+      "candidate_nodes": [],
+      "created_at": "2019-02-20T09:43:58+00:00",
+      "extra": {},
+      "last_error": null,
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/allocations/5344a3e2-978a-444e-990a-cbf47c62ef88",
+          "rel": "bookmark"
+        }
+      ],
+      "name": "allocation-1",
+      "node_uuid": "6d85703a-565d-469a-96ce-30b6de53079d",
+      "resource_class": "bm-large",
+      "state": "active",
+      "traits": [],
+      "updated_at": "2019-02-20T09:43:58+00:00",
+      "uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88"
+    },
+    {
+      "candidate_nodes": [],
+      "created_at": "2019-02-20T09:43:58+00:00",
+      "extra": {},
+      "last_error": "Failed to process allocation eff80f47-75f0-4d41-b1aa-cf07c201adac: no available nodes match the resource class bm-large.",
+      "links": [
+        {
+          "href": "http://127.0.0.1:6385/v1/allocations/eff80f47-75f0-4d41-b1aa-cf07c201adac",
+          "rel": "self"
+        },
+        {
+          "href": "http://127.0.0.1:6385/allocations/eff80f47-75f0-4d41-b1aa-cf07c201adac",
+          "rel": "bookmark"
+        }
+      ],
+      "name": "allocation-2",
+      "node_uuid": null,
+      "resource_class": "bm-large",
+      "state": "error",
+      "traits": [
+        "CUSTOM_GOLD"
+      ],
+      "updated_at": "2019-02-20T09:43:58+00:00",
+      "uuid": "eff80f47-75f0-4d41-b1aa-cf07c201adac"
+    }
+  ]
+}

api-ref/source/samples/node-create-request-classic.json

@@ -4,5 +4,6 @@
     "driver_info": {
         "ipmi_username": "ADMIN",
         "ipmi_password": "password"
-    }
+    },
+    "resource_class": "bm-large"
 }

api-ref/source/samples/node-create-request-dynamic.json

@@ -5,5 +5,6 @@
         "ipmi_username": "ADMIN",
         "ipmi_password": "password"
     },
-    "power_interface": "ipmitool"
+    "power_interface": "ipmitool",
+    "resource_class": "bm-large"
 }

api-ref/source/samples/node-create-response.json

@@ -1,4 +1,5 @@
 {
+  "allocation_uuid": null,
   "boot_interface": null,
   "chassis_uuid": null,
   "clean_step": {},
@@ -69,7 +70,7 @@
   "raid_interface": null,
   "rescue_interface": null,
   "reservation": null,
-  "resource_class": null,
+  "resource_class": "bm-large",
   "states": [
     {
       "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",

api-ref/source/samples/node-show-response.json

@@ -1,4 +1,5 @@
 {
+  "allocation_uuid": null,
   "boot_interface": null,
   "chassis_uuid": null,
   "clean_step": {},
@@ -72,7 +73,7 @@
   "raid_interface": null,
   "rescue_interface": null,
   "reservation": null,
-  "resource_class": null,
+  "resource_class": "bm-large",
   "states": [
     {
       "href": "http://127.0.0.1:6385/v1/nodes/6d85703a-565d-469a-96ce-30b6de53079d/states",

api-ref/source/samples/node-update-driver-info-response.json

@@ -1,4 +1,5 @@
 {
+  "allocation_uuid": null,
   "boot_interface": null,
   "chassis_uuid": null,
   "clean_step": {},

api-ref/source/samples/nodes-list-details-response.json

@@ -1,6 +1,7 @@
 {
   "nodes": [
     {
+      "allocation_uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88",
       "boot_interface": null,
       "chassis_uuid": null,
       "clean_step": {},
@@ -25,7 +26,7 @@
       "inspection_finished_at": null,
       "inspection_started_at": null,
       "instance_info": {},
-      "instance_uuid": null,
+      "instance_uuid": "5344a3e2-978a-444e-990a-cbf47c62ef88",
       "last_error": null,
       "links": [
         {
@@ -105,6 +106,7 @@
       ]
     },
     {
+      "allocation_uuid": null,
       "boot_interface": "pxe",
       "chassis_uuid": null,
       "clean_step": {},