diff --git a/nova/api/openstack/placement/rest_api_version_history.rst b/nova/api/openstack/placement/rest_api_version_history.rst index 60c8182f17f6..ddfe38425d13 100644 --- a/nova/api/openstack/placement/rest_api_version_history.rst +++ b/nova/api/openstack/placement/rest_api_version_history.rst @@ -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 ----------------------------------------------------------------- diff --git a/placement-api-ref/source/parameters.yaml b/placement-api-ref/source/parameters.yaml index 82a6ef963429..82dcbdaa135c 100644 --- a/placement-api-ref/source/parameters.yaml +++ b/placement-api-ref/source/parameters.yaml @@ -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 diff --git a/releasenotes/notes/consumer_generation-f576ac2594b24e2e.yaml b/releasenotes/notes/consumer_generation-f576ac2594b24e2e.yaml index adcb96f62adc..3cca2c1d9e2b 100644 --- a/releasenotes/notes/consumer_generation-f576ac2594b24e2e.yaml +++ b/releasenotes/notes/consumer_generation-f576ac2594b24e2e.yaml @@ -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.