Allocation API: reference documentation

Change-Id: I48f20f0b96931a17c477b9687b0ee963cb7b8879 Story: #2004341 Task: #29574
2019-02-20 12:16:22 +01:00 · 2019-02-20 12:16:22 +01:00 · acc4c402de
parent 644a412309
commit acc4c402de
17 changed files with 561 additions and 13 deletions
--- a/api-ref/regenerate-samples.sh
+++ b/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
--- a/api-ref/source/baremetal-api-v1-allocation.inc
+++ b/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
--- a/api-ref/source/baremetal-api-v1-node-allocation.inc
+++ b/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
--- a/api-ref/source/baremetal-api-v1-nodes.inc
+++ b/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:**

--- a/api-ref/source/index.rst
+++ b/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
--- a/api-ref/source/parameters.yaml
+++ b/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.
--- a/api-ref/source/samples/allocation-create-request-2.json
+++ b/api-ref/source/samples/allocation-create-request-2.json
@ -0,0 +1,6 @@
+{
+    "name": "allocation-2",
+    "resource_class": "bm-large",
+    "traits": ["CUSTOM_GOLD"]
+}
+
--- a/api-ref/source/samples/allocation-create-request.json
+++ b/api-ref/source/samples/allocation-create-request.json
@ -0,0 +1,4 @@
+{
+    "name": "allocation-1",
+    "resource_class": "bm-large"
+}
--- a/api-ref/source/samples/allocation-create-response.json
+++ b/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"
+}
--- a/api-ref/source/samples/allocation-show-response.json
+++ b/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"
+}
--- a/api-ref/source/samples/allocations-list-response.json
+++ b/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"
+    }
+  ]
+}
--- a/api-ref/source/samples/node-create-request-classic.json
+++ b/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"
 }
--- a/api-ref/source/samples/node-create-request-dynamic.json
+++ b/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"
 }
--- a/api-ref/source/samples/node-create-response.json
+++ b/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",
--- a/api-ref/source/samples/node-show-response.json
+++ b/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",
--- a/api-ref/source/samples/node-update-driver-info-response.json
+++ b/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": {},
--- a/api-ref/source/samples/nodes-list-details-response.json
+++ b/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": {},