2b55444f37
This change finds a node with the same name as the allocation and moves it to the beginning of the shuffled candidate list so that node is the first allocation attempt. It is common for node naming scheme to match the node's role (such as compute-1, compute-2). Also this often matches the hostname (allocation name) scheme. Without this change, this scenario will generally result in swapped names (node compute-1 having hostname compute-2, etc). By preferring matching names this situation can be avoided in the majority of cases, while not otherwise affecting the candidiate allocation approach. Change-Id: Ie990bfc209959d58852b9080778602eab5aa30af
295 lines
6.7 KiB
ReStructuredText
295 lines
6.7 KiB
ReStructuredText
.. -*- 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 all of the requested ones
|
|
|
|
The allocation process is asynchronous. The new Allocation is returned in
|
|
the ``allocating`` state, and the process continues in the 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.
|
|
|
|
If you want to backfill an allocation for an already deployed node, you can
|
|
pass the UUID or name of this node to ``node``. In this case the allocation
|
|
is created immediately, bypassing the normal allocation process. Other
|
|
parameters must be missing or match the provided node.
|
|
|
|
.. versionadded:: 1.52
|
|
Allocation API was introduced.
|
|
|
|
.. versionadded:: 1.58
|
|
Added support for backfilling allocations.
|
|
|
|
.. versionadded:: 1.60
|
|
Introduced the ``owner`` field.
|
|
|
|
.. versionadded:: 1.79
|
|
A node with the same name as the allocation ``name`` is moved to the
|
|
start of the derived candidiate list.
|
|
|
|
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
|
|
- node: req_allocation_node
|
|
- owner: owner
|
|
|
|
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
|
|
- owner: owner
|
|
- 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.
|
|
|
|
.. versionadded:: 1.60
|
|
Introduced the ``owner`` field.
|
|
|
|
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
|
|
- owner: owner
|
|
- 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
|
|
- owner: owner
|
|
- 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.
|
|
|
|
.. versionadded:: 1.60
|
|
Introduced the ``owner`` field.
|
|
|
|
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
|
|
- owner: owner
|
|
- extra: extra
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- links: links
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/allocation-show-response.json
|
|
:language: javascript
|
|
|
|
Update Allocation
|
|
=================
|
|
|
|
.. rest_method:: PATCH /v1/allocations/{allocation_id}
|
|
|
|
Updates an allocation. Allows updating only name and extra fields.
|
|
|
|
.. versionadded:: 1.57
|
|
Allocation update API was introduced.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 400, 401, 403, 404, 409, 503
|
|
|
|
Request
|
|
-------
|
|
|
|
The BODY of the PATCH request must be a JSON PATCH document, adhering to
|
|
`RFC 6902 <https://tools.ietf.org/html/rfc6902>`_.
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- allocation_id: allocation_ident
|
|
- name: req_allocation_name
|
|
- extra: req_extra
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/allocation-update-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
|
|
- owner: owner
|
|
- extra: extra
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- links: links
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/allocation-update-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
|