a09defd661
The API reference for POST /allocations [1] and PUT
/allocations/{consumer_uuid} [2] specifically mentions that you can get
a 409 on provider/inventory conflict. In microversion 1.28, it also
became possible to get a 409 on an allocation (consumer generation)
conflict.
In the process of adding that information, it became evident that we
weren't doing a good job explaining the whole generation thing in
general, so this commit also adds a descriptive section to the front
matter of the API reference.
Links are included from the updated descriptions for the two affected
allocations operations. Future commits can add links from other
appropriate sections of the reference (e.g. the parameters.yaml entries
for resource provider and consumer generation fields). Future commits
could also enhance the descriptions of error codes for other operations
to (at least) the level of detail at which these have ended up.
[1] https://developer.openstack.org/api-ref/placement/?expanded=manage-allocations-detail#manage-allocations
[2] https://developer.openstack.org/api-ref/placement/?expanded=update-allocations-detail#update-allocations
Change-Id: I42e76785e0fe456b107fe843dbb242f2c5f5b9f7
Story: #2006180
Task: #35705
213 lines
6.1 KiB
PHP
213 lines
6.1 KiB
PHP
===========
|
|
Allocations
|
|
===========
|
|
|
|
Allocations are records representing resources that have been assigned
|
|
and used by some consumer of that resource. They indicate the amount
|
|
of a particular resource that has been allocated to a given consumer
|
|
of that resource from a particular resource provider.
|
|
|
|
Manage allocations
|
|
==================
|
|
|
|
Create, update or delete allocations for multiple consumers in a single
|
|
request. This allows a client to atomically set or swap allocations for
|
|
multiple consumers as may be required during a migration or move type
|
|
operation.
|
|
|
|
The allocations for an individual consumer uuid mentioned in the request
|
|
can be removed by setting the `allocations` to an empty object (see the
|
|
example below).
|
|
|
|
**Available as of microversion 1.13.**
|
|
|
|
.. rest_method:: POST /allocations
|
|
|
|
Normal response codes: 204
|
|
|
|
Error response codes: badRequest(400), conflict(409)
|
|
|
|
* `409 Conflict` if there is no available inventory in any of the
|
|
resource providers for any specified resource classes.
|
|
* `409 Conflict` with `error code <error_codes_>`_
|
|
``placement.concurrent_update`` if inventories are updated by another request
|
|
while attempting the operation. See :ref:`generations`.
|
|
* `409 Conflict` with `error code <error_codes_>`_
|
|
``placement.concurrent_update`` at microversion 1.28 or higher if allocations
|
|
for a specified consumer have been created, updated, or removed by another
|
|
request while attempting the operation. See :ref:`generations`.
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- consumer_uuid: consumer_uuid_body
|
|
- consumer_generation: consumer_generation_min
|
|
- project_id: project_id_body
|
|
- user_id: user_id_body
|
|
- allocations: allocations_dict_empty
|
|
- generation: resource_provider_generation_optional
|
|
- resources: resources
|
|
- mappings: mappings_in_allocations
|
|
|
|
Request example (microversions 1.28 - )
|
|
---------------------------------------
|
|
|
|
.. literalinclude:: ./samples/allocations/manage-allocations-request-1.28.json
|
|
:language: javascript
|
|
|
|
Request example (microversions 1.13 - 1.27)
|
|
-------------------------------------------
|
|
|
|
.. literalinclude:: ./samples/allocations/manage-allocations-request.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
No body content is returned after a successful request
|
|
|
|
List allocations
|
|
================
|
|
|
|
List all allocation records for the consumer identified by
|
|
`{consumer_uuid}` on all the resource providers it is consuming.
|
|
|
|
.. note:: When listing allocations for a consumer uuid that has no
|
|
allocations a dict with an empty value is returned
|
|
``{"allocations": {}}``.
|
|
|
|
.. rest_method:: GET /allocations/{consumer_uuid}
|
|
|
|
Normal Response Codes: 200
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- consumer_uuid: consumer_uuid
|
|
|
|
Response
|
|
--------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- allocations: allocations_by_resource_provider
|
|
- generation: resource_provider_generation
|
|
- resources: resources
|
|
- consumer_generation: consumer_generation_min
|
|
- project_id: project_id_body_1_12
|
|
- user_id: user_id_body_1_12
|
|
|
|
Response Example (1.28 - )
|
|
--------------------------
|
|
|
|
.. literalinclude:: ./samples/allocations/get-allocations-1.28.json
|
|
:language: javascript
|
|
|
|
Response Example (1.12 - 1.27)
|
|
------------------------------
|
|
|
|
.. literalinclude:: ./samples/allocations/get-allocations.json
|
|
:language: javascript
|
|
|
|
Update allocations
|
|
==================
|
|
|
|
Create or update one or more allocation records representing the consumption of
|
|
one or more classes of resources from one or more resource providers by
|
|
the consumer identified by `{consumer_uuid}`.
|
|
If allocations already exist for this consumer, they are replaced.
|
|
|
|
.. rest_method:: PUT /allocations/{consumer_uuid}
|
|
|
|
Normal Response Codes: 204
|
|
|
|
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
|
|
|
|
* `409 Conflict` if there is no available inventory in any of the
|
|
resource providers for any specified resource classes.
|
|
* `409 Conflict` with `error code <error_codes_>`_
|
|
``placement.concurrent_update`` if inventories are updated by another request
|
|
while attempting the operation. See :ref:`generations`.
|
|
* `409 Conflict` with `error code <error_codes_>`_
|
|
``placement.concurrent_update`` at microversion 1.28 or higher if allocations
|
|
for the specified consumer have been created, updated, or removed by another
|
|
request while attempting the operation. See :ref:`generations`.
|
|
|
|
Request (microversions 1.12 - )
|
|
-------------------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- consumer_uuid: consumer_uuid
|
|
- allocations: allocations_dict
|
|
- resources: resources
|
|
- consumer_generation: consumer_generation_min
|
|
- project_id: project_id_body
|
|
- user_id: user_id_body
|
|
- generation: resource_provider_generation_optional
|
|
- mappings: mappings_in_allocations
|
|
|
|
Request example (microversions 1.28 - )
|
|
---------------------------------------
|
|
|
|
.. literalinclude:: ./samples/allocations/update-allocations-request-1.28.json
|
|
:language: javascript
|
|
|
|
Request example (microversions 1.12 - 1.27)
|
|
-------------------------------------------
|
|
|
|
.. literalinclude:: ./samples/allocations/update-allocations-request-1.12.json
|
|
:language: javascript
|
|
|
|
Request (microversions 1.0 - 1.11)
|
|
----------------------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- consumer_uuid: consumer_uuid
|
|
- allocations: allocations_array
|
|
- resources: resources
|
|
- resource_provider: resource_provider_object
|
|
- uuid: resource_provider_uuid
|
|
- project_id: project_id_body_1_8
|
|
- user_id: user_id_body_1_8
|
|
|
|
Request example (microversions 1.0 - 1.11)
|
|
------------------------------------------
|
|
|
|
.. literalinclude:: ./samples/allocations/update-allocations-request.json
|
|
:language: javascript
|
|
|
|
Response
|
|
--------
|
|
|
|
No body content is returned on a successful PUT.
|
|
|
|
Delete allocations
|
|
==================
|
|
|
|
Delete all allocation records for the consumer identified by
|
|
`{consumer_uuid}` on all resource providers it is consuming.
|
|
|
|
.. rest_method:: DELETE /allocations/{consumer_uuid}
|
|
|
|
Normal Response Codes: 204
|
|
|
|
Error response codes: itemNotFound(404)
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- consumer_uuid: consumer_uuid
|
|
|
|
Response
|
|
--------
|
|
|
|
No body content is returned on a successful DELETE.
|