Allocation API: reference documentation

Change-Id: I48f20f0b96931a17c477b9687b0ee963cb7b8879
Story: #2004341
Task: #29574
This commit is contained in:
Dmitry Tantsur 2019-02-20 12:16:22 +01:00
parent 644a412309
commit acc4c402de
17 changed files with 561 additions and 13 deletions

View File

@ -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_CREATED_AT="2016-08-18T22:28:48.643434+11:11"
DOC_UPDATED_AT="2016-08-18T22:28:49.653974+00:00" DOC_UPDATED_AT="2016-08-18T22:28:49.653974+00:00"
DOC_IRONIC_CONDUCTOR_HOSTNAME="897ab1dad809" DOC_IRONIC_CONDUCTOR_HOSTNAME="897ab1dad809"
DOC_ALLOCATION_UUID="3bf138ba-6d71-44e7-b6a1-ca9cac17103e"
function GET { function GET {
# GET $RESOURCE # 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/detail > nodes-list-details-response.json
GET v1/nodes/$NID > node-show-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 # Node traits
PUT v1/nodes/$NID/traits node-set-traits-request.json PUT v1/nodes/$NID/traits node-set-traits-request.json
GET v1/nodes/$NID/traits > node-traits-list-response.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 # PORTGROUPS
@ -312,6 +337,7 @@ sed -i "s/$PID/$DOC_PORT_UUID/" *.json
sed -i "s/$PGID/$DOC_PORTGROUP_UUID/" *.json sed -i "s/$PGID/$DOC_PORTGROUP_UUID/" *.json
sed -i "s/$VCID/$DOC_VOL_CONNECTOR_UUID/" *.json sed -i "s/$VCID/$DOC_VOL_CONNECTOR_UUID/" *.json
sed -i "s/$VTID/$DOC_VOL_TARGET_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/$(hostname)/$DOC_IRONIC_CONDUCTOR_HOSTNAME/" *.json
sed -i "s/created_at\": \".*\"/created_at\": \"$DOC_CREATED_AT\"/" *.json sed -i "s/created_at\": \".*\"/created_at\": \"$DOC_CREATED_AT\"/" *.json
sed -i "s/updated_at\": \".*\"/updated_at\": \"$DOC_UPDATED_AT\"/" *.json sed -i "s/updated_at\": \".*\"/updated_at\": \"$DOC_UPDATED_AT\"/" *.json

View File

@ -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

View File

@ -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

View File

@ -98,6 +98,9 @@ supplied when the Node is created, or the resource may be updated later.
.. versionadded:: 1.51 .. versionadded:: 1.51
Introduced the ``description`` field. Introduced the ``description`` field.
.. versionadded:: 1.52
Introduced the ``allocation_uuid`` field.
Normal response codes: 201 Normal response codes: 201
Error codes: 400,403,406 Error codes: 400,403,406
@ -199,6 +202,7 @@ microversion 1.48.
- conductor: conductor - conductor: conductor
- owner: owner - owner: owner
- description: n_description - description: n_description
- allocation_uuid: allocation_uuid
**Example JSON representation of a Node:** **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 .. versionadded:: 1.51
Introduced the ``description`` field. Introduced the ``description`` field.
.. versionadded:: 1.52
Introduced the ``allocation_uuid`` field.
Normal response codes: 200 Normal response codes: 200
Error codes: 400,403,406 Error codes: 400,403,406
@ -418,6 +425,7 @@ Response
- owner: owner - owner: owner
- description: n_description - description: n_description
- conductor: conductor - conductor: conductor
- allocation_uuid: allocation_uuid
**Example detailed list of Nodes:** **Example detailed list of Nodes:**
@ -458,6 +466,9 @@ only the specified set.
.. versionadded:: 1.51 .. versionadded:: 1.51
Introduced the ``description`` field. Introduced the ``description`` field.
.. versionadded:: 1.52
Introduced the ``allocation_uuid`` field.
Normal response codes: 200 Normal response codes: 200
Error codes: 400,403,404,406 Error codes: 400,403,404,406
@ -523,6 +534,7 @@ Response
- owner: owner - owner: owner
- description: n_description - description: n_description
- conductor: conductor - conductor: conductor
- allocation_uuid: allocation_uuid
**Example JSON representation of a Node:** **Example JSON representation of a Node:**
@ -617,6 +629,7 @@ Response
- owner: owner - owner: owner
- description: n_description - description: n_description
- conductor: conductor - conductor: conductor
- allocation_uuid: allocation_uuid
**Example JSON representation of a Node:** **Example JSON representation of a Node:**

View File

@ -21,8 +21,11 @@
.. include:: baremetal-api-v1-nodes-volume.inc .. include:: baremetal-api-v1-nodes-volume.inc
.. include:: baremetal-api-v1-drivers.inc .. include:: baremetal-api-v1-drivers.inc
.. include:: baremetal-api-v1-driver-passthru.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-nodes-bios.inc
.. include:: baremetal-api-v1-conductors.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

View File

@ -38,6 +38,12 @@ x-openstack-ironic-api-version:
type: string type: string
# variables in path # variables in path
allocation_ident:
description: |
The UUID or name of the allocation.
in: path
required: true
type: string
bios_setting: bios_setting:
description: | description: |
The name of the Bios setting. The name of the Bios setting.
@ -208,7 +214,20 @@ r_addresses:
required: false required: false
type: array 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: r_associated:
description: | description: |
Filter the list of returned nodes and only return those which are, or are Filter the list of returned nodes and only return those which are, or are
@ -372,7 +391,6 @@ sort_key:
type: string type: string
# variable returned from /lookup # variable returned from /lookup
agent_config: agent_config:
description: | description: |
@ -397,6 +415,57 @@ alive:
in: body in: body
required: true required: true
type: boolean 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: bios_setting_name:
description: | description: |
The name of a Bios setting for a Node, eg. "virtualization". The name of a Bios setting for a Node, eg. "virtualization".
@ -428,6 +497,12 @@ boot_interface:
in: body in: body
required: true required: true
type: string 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: chassis:
description: | description: |
A ``chassis`` object. A ``chassis`` object.
@ -1108,6 +1183,24 @@ reason:
in: body in: body
required: false required: false
type: string 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: req_boot_device:
description: | description: |
The boot device for a Node, eg. "pxe" or "disk". The boot device for a Node, eg. "pxe" or "disk".
@ -1120,6 +1213,13 @@ req_boot_interface:
in: body in: body
required: false required: false
type: string 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: req_chassis:
description: | description: |
A ``chassis`` object. A ``chassis`` object.

View File

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

View File

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

View File

@ -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"
}

View File

@ -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"
}

View File

@ -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"
}
]
}

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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