.. -*- 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.

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