api-ref: Document generations

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

api-ref/source/allocations.inc

@@ -28,8 +28,14 @@ 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 or inventories
-  are updated by another thread while attempting the operation.
+  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
 -------
@@ -122,8 +128,14 @@ 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 or inventories
-  are updated by another thread while attempting the operation.
+  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 - )
 -------------------------------

api-ref/source/errors.inc

@@ -30,6 +30,7 @@ error response is defined by the OpenStack errors_ guideline.
           the above because the error is produced by code other than the
           placement service.
 
+.. _`error_codes`:
 
 Error Codes
 ===========

api-ref/source/generations.inc

@@ -0,0 +1,48 @@
+.. _generations:
+
+==========================================
+Resource Provider and Consumer Generations
+==========================================
+Placement handles concurrent requests against the same entity by maintaining a
+**generation** for resource providers and consumers. The generation is an
+opaque value that is updated every time its entity is successfully changed on
+the server.
+
+At appropriate microversions, the generation is returned in responses involving
+resource providers and/or consumers (allocations), and must be included in
+requests which make changes to those entities. The server checks to make sure
+the generation specified in the request matches the internal value. A mismatch
+indicates that a different request successfully updated that entity in the
+interim, thereby changing its generation. This will result in an HTTP 409
+Conflict response with `error code <error_codes_>`_
+``placement.concurrent_update``.
+
+Depending on the usage scenario, an appropriate reaction to such an error may
+be to re-``GET`` the entity in question, re-evaluate and update as appropriate,
+and resubmit the request with the new payload.
+
+The following pseudocode is a simplistic example of how one might ensure that a
+trait is set on a resource provider.
+
+.. note:: This is not production code. Aside from not being valid syntax for
+          any particular programming language, it deliberately glosses over
+          details and good programming practices such as error checking, retry
+          limits, etc. It is purely for illustrative purposes.
+
+::
+
+ function _is_concurrent_update(resp) {
+     if(resp.status_code != 409) return False
+     return(resp.json()["errors"][0]["code"] == "placement.concurrent_update")
+ }
+
+ function ensure_trait_on_provider(provider_uuid, trait) {
+     do {
+         path = "/resource_providers/" + provider_uuid + "/traits"
+         get_resp = placement.GET(path)
+         payload = get_resp.json()
+         if(trait in payload["traits"]) return
+         payload["traits"].append(trait)
+         put_resp = placement.PUT(path, payload)
+     } while _is_concurrent_update(put_resp)
+ }

api-ref/source/index.rst

@@ -16,6 +16,7 @@ header for APIs sending data payloads in the request body (i.e. ``PUT`` and
 
 .. include:: request-ids.inc
 .. include:: errors.inc
+.. include:: generations.inc
 .. include:: root.inc
 .. include:: resource_providers.inc
 .. include:: resource_provider.inc