placement/placement/rest_api_version_history.rst

REST API Version History

This documents the changes made to the REST API with every microversion change. The description for each version should be a verbose one which has enough information to be suitable for use in user documentation.

Newton

1.0 - Initial Version

Newton

This is the initial version of the placement REST API that was released in Nova 14.0.0 (Newton). This contains the following routes:

• /resource_providers
• /resource_providers/allocations
• /resource_providers/inventories
• /resource_providers/usages
• /allocations

Ocata

1.1 - Resource provider aggregates

Ocata

The 1.1 version adds support for associating aggregates with resource providers.

The following new operations are added:

GET /resource_providers/{uuid}/aggregates

Return all aggregates associated with a resource provider

PUT /resource_providers/{uuid}/aggregates

Update the aggregates associated with a resource provider

1.2 - Add custom resource classes

Ocata

Placement API version 1.2 adds basic operations allowing an admin to create, list and delete custom resource classes.

The following new routes are added:

GET /resource_classes

Return all resource classes

POST /resource_classes

Create a new custom resource class

PUT /resource_classes/{name}

Update the name of a custom resource class

DELETE /resource_classes/{name}

Delete a custom resource class

GET /resource_classes/{name}

Get a single resource class

Custom resource classes must begin with the prefix CUSTOM_ and contain only the letters A through Z, the numbers 0 through 9 and the underscore _ character.

1.3 - 'member_of' query parameter

Ocata

Version 1.3 adds support for listing resource providers that are members of any of the list of aggregates provided using a member_of query parameter:

?member_of=in:{agg1_uuid},{agg2_uuid},{agg3_uuid}

1.4 - Filter resource providers by requested resource capacity

Ocata

The 1.4 version adds support for querying resource providers that have the ability to serve a requested set of resources. A new "resources" query string parameter is now accepted to the GET /resource_providers API call. This parameter indicates the requested amounts of various resources that a provider must have the capacity to serve. The "resources" query string parameter takes the form:

?resources=$RESOURCE_CLASS_NAME:$AMOUNT,$RESOURCE_CLASS_NAME:$AMOUNT

For instance, if the user wishes to see resource providers that can service a request for 2 vCPUs, 1024 MB of RAM and 50 GB of disk space, the user can issue a request to:

GET /resource_providers?resources=VCPU:2,MEMORY_MB:1024,DISK_GB:50

If the resource class does not exist, then it will return a HTTP 400.

Note

The resources filtering is also based on the min_unit, max_unit and step_size of the inventory record. For example, if the max_unit is 512 for the DISK_GB inventory for a particular resource provider and a GET request is made for DISK_GB:1024, that resource provider will not be returned. The min_unit is the minimum amount of resource that can be requested for a given inventory and resource provider. The step_size is the increment of resource that can be requested for a given resource on a given provider.

Pike

1.5 - 'DELETE' all inventory for a resource provider

Pike

Placement API version 1.5 adds DELETE method for deleting all inventory for a resource provider. The following new method is supported:

DELETE /resource_providers/{uuid}/inventories

Delete all inventories for a given resource provider

1.6 - Traits API

Pike

The 1.6 version adds basic operations allowing an admin to create, list, and delete custom traits, also adds basic operations allowing an admin to attach traits to a resource provider.

The following new routes are added:

GET /traits

Return all resource classes.

PUT /traits/{name}

Insert a single custom trait.

GET /traits/{name}

Check if a trait name exists.

DELETE /traits/{name}

Delete the specified trait.

GET /resource_providers/{uuid}/traits

Return all traits associated with a specific resource provider.

PUT /resource_providers/{uuid}/traits

Update all traits for a specific resource provider.

DELETE /resource_providers/{uuid}/traits

Remove any existing trait associations for a specific resource provider

Custom traits must begin with the prefix CUSTOM_ and contain only the letters A through Z, the numbers 0 through 9 and the underscore _ character.

1.7 - Idempotent 'PUT /resource_classes/{name}'

Pike

The 1.7 version changes handling of PUT /resource_classes/{name} to be a create or verification of the resource class with {name}. If the resource class is a custom resource class and does not already exist it will be created and a 201 response code returned. If the class already exists the response code will be 204. This makes it possible to check or create a resource class in one request.

1.8 - Require placement 'project_id', 'user_id' in 'PUT /allocations'

Pike

The 1.8 version adds project_id and user_id required request parameters to PUT /allocations.

1.9 - Add 'GET /usages'

Pike

The 1.9 version adds usages that can be queried by a project or project/user.

The following new routes are added:

GET /usages?project_id=<project_id>

Return all usages for a given project.

GET /usages?project_id=<project_id>&user_id=<user_id>

Return all usages for a given project and user.

1.10 - Allocation candidates

Pike

The 1.10 version brings a new REST resource endpoint for getting a list of allocation candidates. Allocation candidates are collections of possible allocations against resource providers that can satisfy a particular request for resources.

Queens

1.11 - Add 'allocations' link to the 'GET /resource_providers' response

Queens

The /resource_providers/{rp_uuid}/allocations endpoint has been available since version 1.0, but was not listed in the links section of the GET /resource_providers response. The link is included as of version 1.11.

1.12 - 'PUT' dict format to '/allocations/{consumer_uuid}'

Queens

In version 1.12 the request body of a PUT /allocations/{consumer_uuid} is expected to have an object for the allocations property, not as array as with earlier microversions. This puts the request body more in alignment with the structure of the GET /allocations/{consumer_uuid} response body. Because the PUT request requires user_id and project_id in the request body, these fields are added to the GET response. In addition, the response body for GET /allocation_candidates is updated so the allocations in the alocation_requests object work with the new PUT format.

1.13 - 'POST' multiple allocations to '/allocations'

Queens

Version 1.13 gives the ability to set or clear allocations for more than one consumer UUID with a request to POST /allocations.

1.14 - Add nested resource providers

Queens

The 1.14 version introduces the concept of nested resource providers. The resource provider resource now contains two new attributes:

• parent_provider_uuid indicates the provider's direct parent, or null if there is no parent. This attribute can be set in the call to POST /resource_providers and PUT /resource_providers/{uuid} if the attribute has not already been set to a non-NULL value (i.e. we do not support "reparenting" a provider)
• root_provider_uuid indicates the UUID of the root resource provider in the provider's tree. This is a read-only attribute

A new in_tree=<UUID> parameter is now available in the GET /resource-providers API call. Supplying a UUID value for the in_tree parameter will cause all resource providers within the "provider tree" of the provider matching <UUID> to be returned.

1.15 - Add 'last-modified' and 'cache-control' headers

Queens

Throughout the API, 'last-modified' headers have been added to GET responses and those PUT and POST responses that have bodies. The value is either the actual last modified time of the most recently modified associated database entity or the current time if there is no direct mapping to the database. In addition, 'cache-control: no-cache' headers are added where the 'last-modified' header has been added to prevent inadvertent caching of resources.

1.16 - Limit allocation candidates

Queens

Add support for a limit query parameter when making a GET /allocation_candidates request. The parameter accepts an integer value, N, which limits the maximum number of candidates returned.

1.17 - Add 'required' parameter to the allocation candidates

Queens

Add the required parameter to the GET /allocation_candidates API. It accepts a list of traits separated by ,. The provider summary in the response will include the attached traits also.

Rocky

1.18 - Support '?required=<traits>' queryparam on 'GET /resource_providers'

Rocky

Add support for the required query parameter to the GET /resource_providers API. It accepts a comma-separated list of string trait names. When specified, the API results will be filtered to include only resource providers marked with all the specified traits. This is in addition to (logical AND) any filtering based on other query parameters.

Trait names which are empty, do not exist, or are otherwise invalid will result in a 400 error.

1.19 - Include generation and conflict detection in provider aggregates APIs

Rocky

Enhance the payloads for the GET /resource_providers/{uuid}/aggregates response and the PUT /resource_providers/{uuid}/aggregates request and response to be identical, and to include the resource_provider_generation. As with other generation-aware APIs, if the resource_provider_generation specified in the PUT request does not match the generation known by the server, a 409 Conflict error is returned.

1.20 - Return 200 with provider payload from 'POST /resource_providers'

Rocky

The POST /resource_providers API, on success, returns 200 with a payload representing the newly-created resource provider, in the same format as the corresponding GET /resource_providers/{uuid} call. This is to allow the caller to glean automatically-set fields, such as UUID and generation, without a subsequent GET.

1.21 - Support '?member_of=<aggregates>' queryparam on 'GET /allocation_candidates'

Rocky

Add support for the member_of query parameter to the GET /allocation_candidates API. It accepts a comma-separated list of UUIDs for aggregates. Note that if more than one aggregate UUID is passed, the comma-separated list must be prefixed with the "in:" operator. If this parameter is provided, the only resource providers returned will be those in one of the specified aggregates that meet the other parts of the request.

1.22 - Support forbidden traits on resource providers and allocations candidates

Rocky

Add support for expressing traits which are forbidden when filtering GET /resource_providers or GET /allocation_candidates. A forbidden trait is a properly formatted trait in the existing required parameter, prefixed by a !. For example required=!STORAGE_DISK_SSD asks that the results not include any resource providers that provide solid state disk.

1.23 - Include 'code' attribute in JSON error responses

Rocky

JSON formatted error responses gain a new attribute, code, with a value that identifies the type of this error. This can be used to distinguish errors that are different but use the same HTTP status code. Any error response which does not specifically define a code will have the code placement.undefined_code.

1.24 - Support multiple '?member_of' queryparams

Rocky

Add support for specifying multiple member_of query parameters to the GET /resource_providers API. When multiple member_of query parameters are found, they are AND'd together in the final query. For example, issuing a request for GET /resource_providers?member_of=agg1&member_of=agg2 means get the resource providers that are associated with BOTH agg1 and agg2. Issuing a request for GET /resource_providers?member_of=in:agg1,agg2&member_of=agg3 means get the resource providers that are associated with agg3 and are also associated with any of (agg1, agg2).

1.25 - Granular resource requests to 'GET /allocation_candidates'

Rocky

GET /allocation_candidates is enhanced to accept numbered groupings of resource, required/forbidden trait, and aggregate association requests. A resources query parameter key with a positive integer suffix (e.g. resources42) will be logically associated with required and/or member_of query parameter keys with the same suffix (e.g. required42, member_of42). The resources, required/forbidden traits, and aggregate associations in that group will be satisfied by the same resource provider in the response. When more than one numbered grouping is supplied, the group_policy query parameter is required to indicate how the groups should interact. With group_policy=none, separate groupings - numbered or unnumbered - may or may not be satisfied by the same provider. With group_policy=isolate, numbered groups are guaranteed to be satisfied by different providers - though there may still be overlap with the unnumbered group. In all cases, each allocation_request will be satisfied by providers in a single non-sharing provider tree and/or sharing providers associated via aggregate with any of the providers in that tree.

The required and member_of query parameters for a given group are optional. That is, you may specify resources42=XXX without a corresponding required42=YYY or member_of42=ZZZ. However, the reverse (specifying required42=YYY or member_of42=ZZZ without resources42=XXX) will result in an error.

The semantic of the (unnumbered) resources, required, and member_of query parameters is unchanged: the resources, traits, and aggregate associations specified thereby may be satisfied by any provider in the same non-sharing tree or associated via the specified aggregate(s).

1.26 - Allow inventories to have reserved value equal to total

Rocky

Starting with this version, it is allowed to set the reserved value of the resource provider inventory to be equal to total.

1.27 - Include all resource class inventories in 'provider_summaries'

Rocky

Include all resource class inventories in the provider_summaries field in response of the GET /allocation_candidates API even if the resource class is not in the requested resources.

1.28 - Consumer generation support

Rocky

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

A consumer generation is now returned from the following URIs:

GET /resource_providers/{uuid}/allocations

The response continues to be a dict with a key of allocations, which itself is a dict, keyed by consumer UUID, of allocations against the resource provider. For each of those dicts, a consumer_generation field will now be shown.

GET /allocations/{consumer_uuid}

The response continues to be a dict with a key of allocations, which 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 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 generation that the caller understands the consumer to be at the time of the call.

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 of POST /allocations, which uses an empty allocations object to indicate that the allocations for a particular consumer should be removed. Passing an empty allocations object along with a consumer_generation makes PUT /allocations/{consumer_uuid} a safe way to delete allocations for a consumer. The DELETE /allocations/{consumer_uuid} URI remains unsafe to call in deployments where multiple callers may simultaneously be attempting to modify a consumer's allocations.

The POST /allocations URI variant has also been changed to require a consumer_generation field in the request payload for each consumer involved in the request. Similar responses to PUT /allocations/{consumer_uuid} are returned when any of the consumers 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.

1.29 - Support allocation candidates with nested resource providers

Rocky

Add support for nested resource providers with the following two features. 1) GET /allocation_candidates is aware of nested providers. Namely, when provider trees are present, allocation_requests in the response of GET /allocation_candidates can include allocations on combinations of multiple resource providers in the same tree. 2) root_provider_uuid and parent_provider_uuid are added to provider_summaries in the response of GET /allocation_candidates.

1.30 - Provide a '/reshaper' resource

Rocky

Add support for a POST /reshaper resource that provides for atomically migrating resource provider inventories and associated allocations when some of the inventory moves from one resource provider to another, such as when a class of inventory moves from a parent provider to a new child provider.

Note

This is a special operation that should only be used in rare cases of resource provider topology changing when inventory is in use. Only use this if you are really sure of what you are doing.

Stein

1.31 - Add 'in_tree' queryparam on 'GET /allocation_candidates'

Stein

Add support for the in_tree query parameter to the GET /allocation_candidates API. It accepts a UUID for a resource provider. If this parameter is provided, the only resource providers returned will be those in the same tree with the given resource provider. The numbered syntax in_tree<N> is also supported. This restricts providers satisfying the Nth granular request group to the tree of the specified provider. This may be redundant with other in_tree<N> values specified in other groups (including the unnumbered group). However, it can be useful in cases where a specific resource (e.g. DISK_GB) needs to come from a specific sharing provider (e.g. shared storage).

For example, a request for VCPU and VGPU resources from myhost and DISK_GB resources from sharing1 might look like:

?resources=VCPU:1&in_tree=<myhost_uuid>
&resources1=VGPU:1&in_tree1=<myhost_uuid>
&resources2=DISK_GB:100&in_tree2=<sharing1_uuid>

Train

1.32 - Support forbidden aggregates

Train

Add support for forbidden aggregates in member_of queryparam in GET /resource_providers and GET /allocation_candidates. Forbidden aggregates are prefixed with a !.

This negative expression can also be used in multiple member_of parameters:

?member_of=in:<agg1>,<agg2>&member_of=<agg3>&member_of=!<agg4>

would translate logically to

"Candidate resource providers must be at least one of agg1 or agg2, definitely in agg3 and definitely not in agg4."

We do NOT support ! within the in: list:

?member_of=in:<agg1>,<agg2>,!<agg3>

but we support !in: prefix:

?member_of=!in:<agg1>,<agg2>,<agg3>

which is equivalent to:

?member_of=!<agg1>&member_of=!<agg2>&member_of=!<agg3>``

where candidate resource providers must not be in agg1, agg2, or agg3.

1.33 - Support string request group suffixes

Train

The syntax for granular groupings of resource, required/forbidden trait, and aggregate association requests introduced in 1.25 has been extended to allow, in addition to numbers, strings from 1 to 64 characters in length consisting of a-z, A-Z, 0-9, _, and -. This is done to allow naming conventions (e.g., resources_COMPUTE and resources_NETWORK) to emerge in situations where multiple services are collaborating to make requests.

For example, in addition to the already supported:

resources42=XXX&required42=YYY&member_of42=ZZZ

it is now possible to use more complex strings, including UUIDs:

resources_PORT_fccc7adb-095e-4bfd-8c9b-942f41990664=XXX
&required_PORT_fccc7adb-095e-4bfd-8c9b-942f41990664=YYY
&member_of_PORT_fccc7adb-095e-4bfd-8c9b-942f41990664=ZZZ

1.34 - Request group mappings in allocation candidates

Train

The body of the response to a GET /allocation_candidates request has been extended to include a mappings field with each allocation request. The value is a dictionary associating request group suffixes with the uuids of those resource providers that satisfy the identified request group. For convenience, this mapping can be included in the request payload for POST /allocations, PUT /allocations/{consumer_uuid}, and POST /reshaper, but it will be ignored.

1.35 - Support 'root_required' queryparam on GET /allocation_candidates

Train

Add support for the root_required query parameter to the GET /allocation_candidates API. It accepts a comma-delimited list of trait names, each optionally prefixed with ! to indicate a forbidden trait, in the same format as the required query parameter. This restricts allocation requests in the response to only those whose (non-sharing) tree's root resource provider satisfies the specified trait requirements. See filtering by root provider traits for details.

1.36 - Support 'same_subtree' queryparam on GET /allocation_candidates

Train

Add support for the same_subtree query parameter to the GET /allocation_candidates API. It accepts a comma-separated list of request group suffix strings $S. Each must exactly match a suffix on a granular group somewhere else in the request. Importantly, the identified request groups need not have a resources$S. If this is provided, at least one of the resource providers satisfying a specified request group must be an ancestor of the rest. The same_subtree query parameter can be repeated and each repeat group is treated independently.