openstack/nova
Code Issues Proposed changes

Merge "Address nits from consumer generation"

Browse Source
This commit is contained in:
Zuul 2018-07-24 02:19:41 +00:00 committed by Gerrit Code Review
commit 47bab7588e
3 changed files with 38 additions and 35 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
nova/api/openstack/placement/rest_api_version_history.rst
View File

@ -423,8 +423,11 @@ is not in the requested resources.
A new generation field has been added to the consumer concept. Consumers are
the actors that are allocated resources in the placement API. When an
allocation is created, a consumer UUID is specified, along with a project and
user ID (after microversion 1.8).
allocation is created, a consumer UUID is specified. Starting with microversion
1.8, a project and user ID are also required. If using microversions prior to
1.8, these are populated from the ``incomplete_consumer_project_id`` and
``incomplete_consumer_user_id`` config options from the ``[placement]``
section.
The consumer generation facilitates safe concurrent modification of an
allocation.
@ -445,22 +448,22 @@ itself is a dict, keyed by resource provider UUID, of allocations being
consumed by the consumer with the ``{consumer_uuid}``. The top-level dict will
also now contain a ``consumer_generation`` field.
The value of the ``consumer_generation`` field will be an unsigned integer.
The value of the ``consumer_generation`` field is opaque and should only be
used to send back to subsequent operations on the consumer's allocations.
The ``PUT /allocations/{consumer_uuid}`` URI has been modified to now require a
``consumer_generation`` field in the request payload. This field is required to
be ``null`` if the caller expects that there are no allocations already
existing for the consumer. Otherwise, it should contain the integer generation
that the caller understands the consumer to be at the time of the call.
existing for the consumer. Otherwise, it should contain the generation that the
caller understands the consumer to be at the time of the call.
A ``409 Conflict`` will be returned from the ``PUT
/allocations/{consumer_uuid}`` if there was a mismatch between the supplied
generation and the consumer's generation as known by the server. Similarly, a
``409 Conflict`` will be returned if during the course of replacing the
consumer's allocations another process concurrently changed the consumer's
allocations. This allows the caller to react to the concurrent write by
re-reading the consumer's allocations and re-issuing the call to replace
allocations as needed.
A ``409 Conflict`` will be returned from ``PUT /allocations/{consumer_uuid}``
if there was a mismatch between the supplied generation and the consumer's
generation as known by the server. Similarly, a ``409 Conflict`` will be
returned if during the course of replacing the consumer's allocations another
process concurrently changed the consumer's allocations. This allows the caller
to react to the concurrent write by re-reading the consumer's allocations and
re-issuing the call to replace allocations as needed.
The ``PUT /allocations/{consumer_uuid}`` URI has also been modified to accept
an empty allocations object, thereby bringing it to parity with the behaviour
@ -479,14 +482,13 @@ involved in the request**. Similar responses to ``PUT
generations conflict with the server's view of those consumers or if any of the
consumers involved in the request are modified by another process.
**WARNING**:
In all cases, it is absolutely **NOT SAFE** to create and modify allocations
for a consumer using different microversions where one of the microversions is
prior to 1.28. The only way to safely modify allocations for a consumer and
satisfy expectations you have regarding the prior existence (or lack of
existence) of those allocations is to always use microversion 1.28+ when
calling allocations API endpoints.
.. warning:: In all cases, it is absolutely **NOT SAFE** to create and modify
allocations for a consumer using different microversions where one
of the microversions is prior to 1.28. The only way to safely
modify allocations for a consumer and satisfy expectations you
have regarding the prior existence (or lack of existence) of those
allocations is to always use microversion 1.28+ when calling
allocations API endpoints.
1.29 Support allocation candidates with nested resource providers
-----------------------------------------------------------------

4
placement-api-ref/source/parameters.yaml
View File

@ -320,8 +320,8 @@ consumer_generation:
required: true
min_version: 1.28
description: >
The generation of the consumer. Should be set to ``None`` when indicating
the the caller expects the consumer does not yet exist.
The generation of the consumer. Should be set to ``null`` when indicating
that the caller expects the consumer does not yet exist.
consumer_uuid_body:
<<: *consumer_uuid
in: body

25
releasenotes/notes/consumer_generation-f576ac2594b24e2e.yaml
View File

@ -3,15 +3,16 @@ features:
- |
Adds a new ``generation`` column to the consumers table. This value is
incremented every time allocations are made for a consumer. The new
placement microversion 1.28 requires that all ``POST`` and ``PUT
/allocations`` requests now include the ``consumer_generation`` parameter
to ensure that if two processes are allocating resources for the same
consumer, the second one to post doesn't overwrite the first. If there is a
mismatch between the ``consumer_generation`` in the request and the current
value in the database, the allocation will fail, and a 409 Conflict
response will be returned. The calling process must then get the
allocations for that consumer by calling ``GET /allocations/{consumer}``.
That response will now contain, in addition to the allocations, the current
value of the generation value for that consumer. The calling process should
then combine the existing allocations with the ones it is trying to post,
and re-submit with the current consumer_generation.
placement microversion 1.28 requires that all ``POST /allocations`` and
``PUT /allocations/{consumer_uuid}`` requests now include the
``consumer_generation`` parameter to ensure that if two processes are
allocating resources for the same consumer, the second one to complete
doesn't overwrite the first. If there is a mismatch between the
``consumer_generation`` in the request and the current value in the
database, the allocation will fail, and a 409 Conflict response will be
returned. The calling process must then get the allocations for that
consumer by calling ``GET /allocations/{consumer}``. That response will now
contain, in addition to the allocations, the current generation value for
that consumer. Depending on the use case, the calling process may error; or
it may wish to combine or replace the existing allocations with the ones it
is trying to post, and re-submit with the current consumer_generation.