Placement API¶
This is a reference for the OpenStack Placement API. To learn more about OpenStack Placement API concepts, please refer to the Placement Introduction.
The Placement API uses JSON for data exchange. As such, the Content-Type
header for APIs sending data payloads in the request body (i.e. PUT
and
POST
) must be set to application/json
unless otherwise noted.
Request IDs¶
All logs on the system, by default, include the global request ID and
the local request ID when available.
The local request ID is a unique ID locally generated by each service,
and thus different for each service (Nova, Cinder, Glance, Neutron, etc.)
involved in that operation. The format is req-
+ UUID (UUID4).
The global request ID is a user-specified request ID which is utilized as
a common identifier by all services. This request ID is same among all
services involved in that operation. The format is req-
+ UUID (UUID4).
This allows an administrator to track
the API request processing as it transitions between all the different
nova services or between nova and other component services called by Nova
during that request.
Even if specifying a global request ID in a request, users receive always a local request ID as the response.
For more details about request IDs, please reference: Faults (It is not for Placement APIs, but there are some common points.)
Request
Name |
In |
Type |
Description |
---|---|---|---|
X-Openstack-Request-Id (Optional) |
header |
string |
The global request ID, which is a unique common ID for tracking each
request in OpenStack components. The format of the global request ID
must be |
Response
Name |
In |
Type |
Description |
---|---|---|---|
X-Openstack-Request-Id |
header |
string |
The local request ID, which is a unique ID generated automatically for tracking each request to placement. It is associated with the request and appears in the log lines for that request. By default, the middleware configuration ensures that the local request ID appears in the log files. |
Errors¶
When there is an error interacting with the placement API, the response will
include a few different signals of what went wrong, include the status header
and information in the response body. The structure of the JSON
body of an
error response is defined by the OpenStack errors guideline.
- HTTP Status Code
The
Status
header of the response will include a code, defined by RFC 7231#section-6 that gives a general overview of the problem. This value also shows up in astatus
attribute in the body of the response.- Detail Message
A textual description of the error condition, in a
detail
attribute. The value is usually the message associated with whatever exception happened within the service.- Error Code
When the microversion is
>=1.23
responses will also include acode
attribute in theJSON
body. These are documented below. Where a response does not use a specific codeplacement.undefined_code
is present.
Note
In some cases, for example when keystone is being used and no
authentication information is provided in a request (causing a
401
response), the structure of the error response will not match
the above because the error is produced by code other than the
placement service.
Error Codes¶
The defined errors are:
Code |
Meaning |
---|---|
|
The default code used when a specific code has not been defined or is not required. |
|
An attempt has been made to remove or shrink inventory that has capacity in use. |
|
Another operation has concurrently made a request that involves one or more of the same resources referenced in this request, changing state. The current state should be retrieved to determine if the desired operation should be retried. |
|
A resource of this type already exists with the same name, and duplicate names are not allowed. |
|
An attempt was made to remove a resource provider, but there are allocations against its inventory. |
|
An attempt was made to remove a resource provider, but it has one or more child providers. They must be removed first in order to remove this provider. |
|
A resource provider mentioned in an operation involving multiple resource providers, such as Reshaper, does not exist. |
|
A request included multiple instances of a query parameter that may only be specified once. |
|
A value in a request conformed to the schema, but failed semantic validation. |
|
A required query parameter is not present in a request. |
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
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 Versions¶
In order to bring new features to users over time, the Placement API
supports microversioning. Microversions allow use of certain features on a
per-request basis via the OpenStack-API-Version
header. For example, to
request microversion 1.10, specify the header:
OpenStack-API-Version: placement 1.10
For more details about Microversions, please reference: Microversion Specification
Note
The maximum microversion supported by each release varies. Please reference: REST API Version History for API microversion history details.
Fetch information about all known major versions of the placement API, including information about the minimum and maximum microversions.
Note
At this time there is only one major version of the placement API: version 1.0.
Normal Response Codes: 200
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
versions |
body |
array |
A list of version objects that describe the API versions available. |
id |
body |
string |
A common name for the version being described. Informative only. |
min_version |
body |
string |
The minimum microversion that is supported. |
max_version |
body |
string |
The maximum microversion that is supported. |
status |
body |
string |
The status of the version being described. With placement this is “CURRENT”. |
links |
body |
array |
A list of links related to and describing this version. |
Response Example¶
{
"versions" : [
{
"min_version" : "1.0",
"id" : "v1.0",
"max_version" : "1.28",
"status": "CURRENT",
"links": [
{
"href": "",
"rel": "self"
}
]
}
]
}
Resource Providers¶
Resource providers are entities which provide consumable inventory of one or more classes of resource (such as disk or memory). They can be listed (with filters), created, updated and deleted.
List an optionally filtered collection of resource providers.
Normal Response Codes: 200
Error response codes: badRequest(400)
A 400 BadRequest response code will be returned
if a resource class specified in resources
request parameter
does not exist.
Request¶
Several query parameters are available to filter the returned list of resource providers. If multiple different parameters are provided, the results of all filters are merged with a boolean AND.
Name |
In |
Type |
Description |
---|---|---|---|
name (Optional) |
query |
string |
The name of a resource provider to filter the list. |
uuid (Optional) |
query |
string |
The uuid of a resource provider. |
member_of (Optional) |
query |
string |
A string representing an aggregate uuid; or the prefix member_of=5e08ea53-c4c6-448e-9334-ac4953de3cfa
member_of=in:42896e0d-205d-4fe3-bd1e-100924931787,5e08ea53-c4c6-448e-9334-ac4953de3cfa
Starting from microversion 1.24 specifying multiple member_of=AGGA_UUID&member_of=in:AGGB_UUID,AGGC_UUID
Starting from microversion 1.32 specifying forbidden aggregates is supported in the member_of=AGGA_UUID&member_of=!AGGB_UUID
would translate logically to “Candidate resource providers must be in AGGA and not in AGGB.”
We do NOT support member_of=!in:AGGA_UUID,AGGB_UUID,AGGC_UUID
member_of=!AGGA_UUID&member_of=!AGGB_UUID&member_of=!AGGC_UUID
We do not check if the same aggregate uuid is in both positive and negative expression to return 400 BadRequest. We still return 200 for such cases. For example: member_of=AGGA_UUID&member_of=!AGGA_UUID
would return an empty list for member_of=in:AGGA_UUID,AGGB_UUID&member_of=!AGGA_UUID
would return resource providers that are NOT in AGGA but in AGGB. New in version 1.3 |
resources (Optional) |
query |
string |
A comma-separated list of strings indicating an amount of resource of a specified class that a provider must have the capacity and availability to serve: resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
Note that the amount must be an integer greater than 0. New in version 1.4 |
in_tree (Optional) |
query |
string |
A UUID of a resource provider. The returned resource providers will be in the same “provider tree” as the specified provider. New in version 1.14 |
required (Optional) |
query |
string |
A comma-delimited list of string trait names. Results will be filtered to
include only resource providers having all the specified traits. Starting
from microversion 1.22 traits which are forbidden from any resource
provider may be expressed by prefixing a trait with a Starting from microversion 1.39 the required=T1,!T2&required=T3
means T1 and not T2 and T3. Also starting from microversion 1.39 the required=in:T1,T2,T3
which means T1 or T2 or T3. Mixing forbidden traits into an required=in:T3,T4&required=T1,!T2
is supported and it means T1 and not T2 and (T3 or T4). New in version 1.18 |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
resource_providers |
body |
array |
A list of |
generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
uuid |
body |
string |
The uuid of a resource provider. |
links |
body |
array |
A list of links associated with one resource provider. Note Aggregates relationship link is available starting from version 1.1. Traits relationship link is available starting from version 1.6. Allocations relationship link is available starting from version 1.11. |
name |
body |
string |
The name of one resource provider. |
parent_provider_uuid |
body |
string |
The UUID of the immediate parent of the resource provider. New in version 1.14 |
root_provider_uuid |
body |
string |
Read-only UUID of the top-most provider in this provider tree. New in version 1.14 |
Response Example¶
{
"resource_providers": [
{
"generation": 1,
"uuid": "99c09379-6e52-4ef8-9a95-b9ce6f68452e",
"links": [
{
"href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e",
"rel": "self"
},
{
"href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/aggregates",
"rel": "aggregates"
},
{
"href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/inventories",
"rel": "inventories"
},
{
"href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/usages",
"rel": "usages"
},
{
"href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/traits",
"rel": "traits"
},
{
"href": "/resource_providers/99c09379-6e52-4ef8-9a95-b9ce6f68452e/allocations",
"rel": "allocations"
}
],
"name": "vgr.localdomain",
"parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8",
"root_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
},
{
"generation": 2,
"uuid": "d0b381e9-8761-42de-8e6c-bba99a96d5f5",
"links": [
{
"href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5",
"rel": "self"
},
{
"href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/aggregates",
"rel": "aggregates"
},
{
"href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/inventories",
"rel": "inventories"
},
{
"href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/usages",
"rel": "usages"
},
{
"href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/traits",
"rel": "traits"
},
{
"href": "/resource_providers/d0b381e9-8761-42de-8e6c-bba99a96d5f5/allocations",
"rel": "allocations"
}
],
"name": "pony1",
"parent_provider_uuid": null,
"root_provider_uuid": "d0b381e9-8761-42de-8e6c-bba99a96d5f5"
}
]
}
Create a new resource provider.
Normal Response Codes: 201 (microversions 1.0 - 1.19), 200 (microversions 1.20 - )
Error response codes: conflict(409)
A 409 Conflict response code will be returned if another resource provider exists with the provided name or uuid.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
body |
string |
The name of one resource provider. |
uuid (Optional) |
body |
string |
The uuid of a resource provider. |
parent_provider_uuid (Optional) |
body |
string |
The UUID of the immediate parent of the resource provider.
New in version 1.14 |
Request example¶
{
"name": "NFS Share",
"uuid": "7d2590ae-fb85-4080-9306-058b4c915e3f",
"parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
}
Response (microversions 1.0 - 1.19)¶
Name |
In |
Type |
Description |
---|---|---|---|
Location |
header |
string |
The location URL of the resource created, HTTP header “Location: <Location URL>” will be returned. |
No body content is returned on a successful POST.
Response (microversions 1.20 - )¶
Name |
In |
Type |
Description |
---|---|---|---|
Location |
header |
string |
The location URL of the resource created, HTTP header “Location: <Location URL>” will be returned. |
generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
uuid |
body |
string |
The uuid of a resource provider. |
links |
body |
array |
A list of links associated with the resource provider. |
name |
body |
string |
The name of one resource provider. |
parent_provider_uuid |
body |
string |
The UUID of the immediate parent of the resource provider. |
root_provider_uuid |
body |
string |
UUID of the top-most provider in this provider tree. |
Response Example (microversions 1.20 - )¶
{
"generation": 0,
"links": [
{
"href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f",
"rel": "self"
},
{
"href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/aggregates",
"rel": "aggregates"
},
{
"href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/inventories",
"rel": "inventories"
},
{
"href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/usages",
"rel": "usages"
},
{
"href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/traits",
"rel": "traits"
},
{
"href": "/placement/resource_providers/7d2590ae-fb85-4080-9306-058b4c915e3f/allocations",
"rel": "allocations"
}
],
"name": "NFS Share",
"uuid": "7d2590ae-fb85-4080-9306-058b4c915e3f",
"parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8",
"root_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
}
Resource Provider¶
See Resource providers for a description. This group of API calls works with a single resource provider identified by uuid. One resource provider can be listed, updated and deleted.
Return a representation of the resource provider identified by {uuid}.
Normal Response Codes: 200
Error response codes: itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
uuid |
body |
string |
The uuid of a resource provider. |
links |
body |
array |
A list of links associated with one resource provider. Note Aggregates relationship link is available starting from version 1.1. Traits relationship link is available starting from version 1.6. Allocations relationship link is available starting from version 1.11. |
name |
body |
string |
The name of one resource provider. |
parent_provider_uuid |
body |
string |
The UUID of the immediate parent of the resource provider. New in version 1.14 |
root_provider_uuid |
body |
string |
Read-only UUID of the top-most provider in this provider tree. New in version 1.14 |
Response Example¶
{
"generation": 0,
"links": [
{
"href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868",
"rel": "self"
},
{
"href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/aggregates",
"rel": "aggregates"
},
{
"href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/inventories",
"rel": "inventories"
},
{
"href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/usages",
"rel": "usages"
},
{
"href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/traits",
"rel": "traits"
},
{
"href": "/placement/resource_providers/3b4005be-d64b-456f-ba36-0ffd02718868/allocations",
"rel": "allocations"
}
],
"name": "Ceph Storage Pool",
"uuid": "3b4005be-d64b-456f-ba36-0ffd02718868",
"parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8",
"root_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
}
Update the name of the resource provider identified by {uuid}.
Normal Response Codes: 200
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
A 409 Conflict response code will be returned if another resource provider exists with the provided name.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
name |
body |
string |
The name of one resource provider. |
parent_provider_uuid (Optional) |
body |
string |
The UUID of the immediate parent of the resource provider.
New in version 1.14 |
Request example¶
{
"name": "Shared storage",
"parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8"
}
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
uuid |
body |
string |
The uuid of a resource provider. |
links |
body |
array |
A list of links associated with one resource provider. Note Aggregates relationship link is available starting from version 1.1. Traits relationship link is available starting from version 1.6. Allocations relationship link is available starting from version 1.11. |
name |
body |
string |
The name of one resource provider. |
parent_provider_uuid |
body |
string |
The UUID of the immediate parent of the resource provider. New in version 1.14 |
root_provider_uuid |
body |
string |
Read-only UUID of the top-most provider in this provider tree. New in version 1.14 |
Response Example¶
{
"generation": 0,
"links": [
{
"href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f",
"rel": "self"
},
{
"href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/aggregates",
"rel": "aggregates"
},
{
"href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/inventories",
"rel": "inventories"
},
{
"href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/usages",
"rel": "usages"
},
{
"href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/traits",
"rel": "traits"
},
{
"href": "/placement/resource_providers/33f26ae0-dbf2-485b-a24a-244d8280e29f/allocations",
"rel": "allocations"
}
],
"name": "Shared storage",
"uuid": "33f26ae0-dbf2-485b-a24a-244d8280e29f",
"parent_provider_uuid": "542df8ed-9be2-49b9-b4db-6d3183ff8ec8",
"root_provider_uuid": "d0b381e9-8761-42de-8e6c-bba99a96d5f5"
}
Delete the resource provider identified by {uuid}. This will also disassociate aggregates and delete inventories.
Normal Response Codes: 204
Error response codes: itemNotFound(404), conflict(409)
A 409 Conflict response code will be returned if there exist allocations records for any of the inventories that would be deleted as a result of removing the resource provider.
This error code will be also returned if there are existing child resource providers under the parent resource provider being deleted.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
Response¶
No body content is returned on a successful DELETE.
Resource Classes¶
Resource classes are entities that indicate standard or deployer-specific resources that can be provided by a resource provider.
Note
Resource class API calls are available starting from version 1.2.
Return a list of all resource classes.
Normal Response Codes: 200
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
resource_classes |
body |
array |
A list of |
links |
body |
array |
A list of links associated with one resource class. |
name |
body |
string |
The name of one resource class. |
Response Example¶
{
"resource_classes": [
{
"links": [
{
"href": "/placement/resource_classes/VCPU",
"rel": "self"
}
],
"name": "VCPU"
},
{
"links": [
{
"href": "/placement/resource_classes/MEMORY_MB",
"rel": "self"
}
],
"name": "MEMORY_MB"
},
{
"links": [
{
"href": "/placement/resource_classes/DISK_GB",
"rel": "self"
}
],
"name": "DISK_GB"
},
{
"links": [
{
"href": "/placement/resource_classes/PCI_DEVICE",
"rel": "self"
}
],
"name": "PCI_DEVICE"
},
{
"links": [
{
"href": "/placement/resource_classes/SRIOV_NET_VF",
"rel": "self"
}
],
"name": "SRIOV_NET_VF"
},
{
"links": [
{
"href": "/placement/resource_classes/NUMA_SOCKET",
"rel": "self"
}
],
"name": "NUMA_SOCKET"
},
{
"links": [
{
"href": "/placement/resource_classes/NUMA_CORE",
"rel": "self"
}
],
"name": "NUMA_CORE"
},
{
"links": [
{
"href": "/placement/resource_classes/NUMA_THREAD",
"rel": "self"
}
],
"name": "NUMA_THREAD"
},
{
"links": [
{
"href": "/placement/resource_classes/NUMA_MEMORY_MB",
"rel": "self"
}
],
"name": "NUMA_MEMORY_MB"
},
{
"links": [
{
"href": "/placement/resource_classes/IPV4_ADDRESS",
"rel": "self"
}
],
"name": "IPV4_ADDRESS"
}
]
}
Create a new resource class. The new class must be a custom resource class, prefixed with CUSTOM_ and distinct from the standard resource classes.
Normal Response Codes: 201
Error response codes: badRequest(400), conflict(409)
A 400 BadRequest response code will be returned if the resource class does not have prefix CUSTOM_.
A 409 Conflict response code will be returned if another resource class exists with the provided name.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
body |
string |
The name of one resource class. The name must start with the prefix |
Request example¶
{"name": "CUSTOM_FPGA"}
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
Location |
header |
string |
The location URL of the resource created, HTTP header “Location: <Location URL>” will be returned. |
No body content is returned on a successful POST.
Resource Class¶
See resource classes for a description. This group of API calls works with a single resource class identified by name. One resource class can be listed, updated and deleted.
Note
Resource class API calls are available starting from version 1.2.
Return a representation of the resource class identified by {name}.
Normal Response Codes: 200
Error response codes: itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
path |
string |
The name of one resource class. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
body |
string |
The name of one resource class. |
links |
body |
array |
A list of links associated with one resource class. |
Response Example¶
{
"links": [
{
"href": "/placement/resource_classes/CUSTOM_FPGA",
"rel": "self"
}
],
"name": "CUSTOM_FPGA"
}
Create or validate the existence of single resource class identified by {name}.
Note
Method is available starting from version 1.7.
Normal Response Codes: 201, 204
A 201 Created response code will be returned if the new resource class is successfully created. A 204 No Content response code will be returned if the resource class already exists.
Error response codes: badRequest(400)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
path |
string |
The name of one resource class. The name must start with the prefix |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
Location |
header |
string |
The location URL of the resource created, HTTP header “Location: <Location URL>” will be returned. |
No body content is returned on a successful PUT.
Warning
Changing resource class names using the <1.7 microversion is strongly discouraged.
Update the name of the resource class identified by {name}.
Normal Response Codes: 200
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
A 409 Conflict response code will be returned if another resource class exists with the provided name.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
path |
string |
The name of one resource class. |
name |
body |
string |
The name of one resource class. The name must start with the prefix |
Request example¶
{"name": "CUSTOM_FPGA_V2"}
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
body |
string |
The name of one resource class. |
links |
body |
array |
A list of links associated with one resource class. |
Response Example¶
{
"links": [
{
"href": "/placement/resource_classes/CUSTOM_FPGA_V2",
"rel": "self"
}
],
"name": "CUSTOM_FPGA_V2"
}
Delete the resource class identified by {name}.
Normal Response Codes: 204
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
A 400 BadRequest response code will be returned if trying to delete a standard resource class.
A 409 Conflict response code will be returned if there exist inventories for the resource class.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
path |
string |
The name of one resource class. |
Response¶
No body content is returned on a successful DELETE.
Resource provider inventories¶
Each resource provider has inventory records for one or more classes of resources. An inventory record contains information about the total and reserved amounts of the resource and any consumption constraints for that resource against the provider.
Normal Response Codes: 200
Error response codes: itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
inventories |
body |
object |
A dictionary of inventories keyed by resource classes. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
allocation_ratio |
body |
float |
It is used in determining whether consumption of the resource of the provider can exceed physical constraints. For example, for a vCPU resource with: allocation_ratio = 16.0
total = 8
Overall capacity is equal to 128 vCPUs. |
max_unit |
body |
integer |
A maximum amount any single allocation against an inventory can have. |
min_unit |
body |
integer |
A minimum amount any single allocation against an inventory can have. |
reserved |
body |
integer |
The amount of the resource a provider has reserved for its own use. |
step_size |
body |
integer |
A representation of the divisible amount of the resource that may be requested. For example, step_size = 5 means that only values divisible by 5 (5, 10, 15, etc.) can be requested. |
total |
body |
integer |
The actual amount of the resource that the provider can accommodate. |
Response Example¶
{
"inventories": {
"DISK_GB": {
"allocation_ratio": 1.0,
"max_unit": 35,
"min_unit": 1,
"reserved": 0,
"step_size": 1,
"total": 35
},
"MEMORY_MB": {
"allocation_ratio": 1.5,
"max_unit": 5825,
"min_unit": 1,
"reserved": 512,
"step_size": 1,
"total": 5825
},
"VCPU": {
"allocation_ratio": 16.0,
"max_unit": 4,
"min_unit": 1,
"reserved": 0,
"step_size": 1,
"total": 4
}
},
"resource_provider_generation": 7
}
Replaces the set of inventory records for the resource provider identified by {uuid}.
Normal Response Codes: 200
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
inventories |
body |
object |
A dictionary of inventories keyed by resource classes. |
total |
body |
integer |
The actual amount of the resource that the provider can accommodate. |
allocation_ratio (Optional) |
body |
float |
It is used in determining whether consumption of the resource of the provider can exceed physical constraints. For example, for a vCPU resource with: allocation_ratio = 16.0
total = 8
Overall capacity is equal to 128 vCPUs. |
max_unit (Optional) |
body |
integer |
A maximum amount any single allocation against an inventory can have. |
min_unit (Optional) |
body |
integer |
A minimum amount any single allocation against an inventory can have. |
reserved (Optional) |
body |
integer |
The amount of the resource a provider has reserved for its own use. Up to microversion 1.25, this value has to be less than the value of |
step_size (Optional) |
body |
integer |
A representation of the divisible amount of the resource that may be requested. For example, step_size = 5 means that only values divisible by 5 (5, 10, 15, etc.) can be requested. |
Request example¶
{
"inventories": {
"MEMORY_MB": {
"allocation_ratio": 2.0,
"max_unit": 16,
"step_size": 4,
"total": 128
},
"VCPU": {
"allocation_ratio": 10.0,
"reserved": 2,
"total": 64
}
},
"resource_provider_generation": 1
}
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
inventories |
body |
object |
A dictionary of inventories keyed by resource classes. |
allocation_ratio |
body |
float |
It is used in determining whether consumption of the resource of the provider can exceed physical constraints. For example, for a vCPU resource with: allocation_ratio = 16.0
total = 8
Overall capacity is equal to 128 vCPUs. |
max_unit |
body |
integer |
A maximum amount any single allocation against an inventory can have. |
min_unit |
body |
integer |
A minimum amount any single allocation against an inventory can have. |
reserved |
body |
integer |
The amount of the resource a provider has reserved for its own use. |
step_size |
body |
integer |
A representation of the divisible amount of the resource that may be requested. For example, step_size = 5 means that only values divisible by 5 (5, 10, 15, etc.) can be requested. |
total |
body |
integer |
The actual amount of the resource that the provider can accommodate. |
Response Example¶
{
"inventories": {
"MEMORY_MB": {
"allocation_ratio": 2.0,
"max_unit": 16,
"min_unit": 1,
"reserved": 0,
"step_size": 4,
"total": 128
},
"VCPU": {
"allocation_ratio": 10.0,
"max_unit": 2147483647,
"min_unit": 1,
"reserved": 2,
"step_size": 1,
"total": 64
}
},
"resource_provider_generation": 2
}
Deletes all inventory records for the resource provider identified by {uuid}.
Troubleshooting
The request returns an HTTP 409 when there are allocations against the provider or if the provider’s inventory is updated by another thread while attempting the operation.
Note
Method is available starting from version 1.5.
Normal Response Codes: 204
Error response codes: itemNotFound(404), conflict(409)
Note
Since this request does not accept the resource provider generation,
it is not safe to use when multiple threads are managing inventories
for a single provider. In such situations, use the
PUT /resource_providers/{uuid}/inventories
API with an empty
inventories
dict.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
Response¶
No body content is returned on a successful DELETE.
Resource provider inventory¶
See Resource provider inventories for a description.
This group of API calls works with a single inventory identified by resource_class
.
One inventory can be listed, created, updated and deleted per each call.
Normal Response Codes: 200
Error response codes: itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
resource_class |
path |
string |
The name of one resource class. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
allocation_ratio |
body |
float |
It is used in determining whether consumption of the resource of the provider can exceed physical constraints. For example, for a vCPU resource with: allocation_ratio = 16.0
total = 8
Overall capacity is equal to 128 vCPUs. |
max_unit |
body |
integer |
A maximum amount any single allocation against an inventory can have. |
min_unit |
body |
integer |
A minimum amount any single allocation against an inventory can have. |
reserved |
body |
integer |
The amount of the resource a provider has reserved for its own use. |
step_size |
body |
integer |
A representation of the divisible amount of the resource that may be requested. For example, step_size = 5 means that only values divisible by 5 (5, 10, 15, etc.) can be requested. |
total |
body |
integer |
The actual amount of the resource that the provider can accommodate. |
Response Example¶
{
"allocation_ratio": 16.0,
"max_unit": 4,
"min_unit": 1,
"reserved": 0,
"resource_provider_generation": 9,
"step_size": 1,
"total": 4
}
Replace the inventory record of the {resource_class} for the resource provider identified by {uuid}.
Normal Response Codes: 200
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
resource_class |
path |
string |
The name of one resource class. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
total |
body |
integer |
The actual amount of the resource that the provider can accommodate. |
allocation_ratio (Optional) |
body |
float |
It is used in determining whether consumption of the resource of the provider can exceed physical constraints. For example, for a vCPU resource with: allocation_ratio = 16.0
total = 8
Overall capacity is equal to 128 vCPUs. |
max_unit (Optional) |
body |
integer |
A maximum amount any single allocation against an inventory can have. |
min_unit (Optional) |
body |
integer |
A minimum amount any single allocation against an inventory can have. |
reserved (Optional) |
body |
integer |
The amount of the resource a provider has reserved for its own use. Up to microversion 1.25, this value has to be less than the value of |
step_size (Optional) |
body |
integer |
A representation of the divisible amount of the resource that may be requested. For example, step_size = 5 means that only values divisible by 5 (5, 10, 15, etc.) can be requested. |
Request example¶
{
"resource_provider_generation": 7,
"total": 50
}
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
allocation_ratio |
body |
float |
It is used in determining whether consumption of the resource of the provider can exceed physical constraints. For example, for a vCPU resource with: allocation_ratio = 16.0
total = 8
Overall capacity is equal to 128 vCPUs. |
max_unit |
body |
integer |
A maximum amount any single allocation against an inventory can have. |
min_unit |
body |
integer |
A minimum amount any single allocation against an inventory can have. |
reserved |
body |
integer |
The amount of the resource a provider has reserved for its own use. |
step_size |
body |
integer |
A representation of the divisible amount of the resource that may be requested. For example, step_size = 5 means that only values divisible by 5 (5, 10, 15, etc.) can be requested. |
total |
body |
integer |
The actual amount of the resource that the provider can accommodate. |
Response Example¶
{
"allocation_ratio": 1.0,
"max_unit": 2147483647,
"min_unit": 1,
"reserved": 0,
"resource_provider_generation": 8,
"step_size": 1,
"total": 50
}
Delete the inventory record of the {resource_class} for the resource provider identified by {uuid}.
See Troubleshooting section in Delete resource provider
inventories
for a description. In addition, the request returns
HTTP 409 when there are allocations for the specified resource
provider and resource class.
Normal Response Codes: 204
Error response codes: itemNotFound(404), conflict(409)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
resource_class |
path |
string |
The name of one resource class. |
Response¶
No body content is returned on a successful DELETE.
Resource provider aggregates¶
Each resource provider can be associated with one or more other resource providers in groups called aggregates. API calls in this section are used to list and update the aggregates that are associated with one resource provider.
Provider aggregates are used for modeling relationships among providers. Examples may include:
A shared storage pool providing DISK_GB resources to compute node providers that provide VCPU and MEMORY_MB resources.
Affinity/anti-affinity relationships such as physical location, power failure domains, or other reliability/availability constructs.
Groupings of compute host providers corresponding to Nova host aggregates or availability zones.
Note
Placement aggregates are not the same as Nova host aggregates and should not be considered equivalent.
The primary differences between Nova’s host aggregates and placement aggregates are the following:
In Nova, a host aggregate associates a nova-compute service with other nova-compute services. Placement aggregates are not specific to a nova-compute service and are, in fact, not compute-specific at all. A resource provider in the Placement API is generic, and placement aggregates are simply groups of generic resource providers. This is an important difference especially for Ironic, which when used with Nova, has many Ironic baremetal nodes attached to a single nova-compute service. In the Placement API, each Ironic baremetal node is its own resource provider and can therefore be associated to other Ironic baremetal nodes via a placement aggregate association.
In Nova, a host aggregate may have metadata key/value pairs attached to it. All nova-compute services associated with a Nova host aggregate share the same metadata. Placement aggregates have no such metadata because placement aggregates only represent the grouping of resource providers. In the Placement API, resource providers are individually decorated with traits that provide qualitative information about the resource provider.
In Nova, a host aggregate dictates the availability zone within which one or more nova-compute services reside. While placement aggregates may be used to model availability zones, they have no inherent concept thereof.
Note
Aggregates API requests are available starting from version 1.1.
Return a list of aggregates associated with the resource provider identified by {uuid}.
Normal Response Codes: 200
Error response codes: itemNotFound(404) if the provider does not exist. (If the provider has no aggregates, the result is 200 with an empty aggregate list.)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
Response (microversions 1.1 - 1.18)¶
Name |
In |
Type |
Description |
---|---|---|---|
aggregates |
body |
array |
A list of aggregate uuids. Previously nonexistent aggregates are created automatically. |
Response Example (microversions 1.1 - 1.18)¶
{
"aggregates": [
"42896e0d-205d-4fe3-bd1e-100924931787",
"5e08ea53-c4c6-448e-9334-ac4953de3cfa"
]
}
Response (microversions 1.19 - )¶
Name |
In |
Type |
Description |
---|---|---|---|
aggregates |
body |
array |
A list of aggregate uuids. Previously nonexistent aggregates are created automatically. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
Response Example (microversions 1.19 - )¶
{
"aggregates": [
"42896e0d-205d-4fe3-bd1e-100924931787",
"5e08ea53-c4c6-448e-9334-ac4953de3cfa"
],
"resource_provider_generation": 8
}
Associate a list of aggregates with the resource provider identified by {uuid}.
Normal Response Codes: 200
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
Request (microversion 1.1 - 1.18)¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
aggregates |
body |
array |
A list of aggregate uuids. Previously nonexistent aggregates are created automatically. |
Request example (microversion 1.1 - 1.18)¶
[
"42896e0d-205d-4fe3-bd1e-100924931787",
"5e08ea53-c4c6-448e-9334-ac4953de3cfa"
]
Request (microversion 1.19 - )¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
aggregates |
body |
array |
A list of aggregate uuids. Previously nonexistent aggregates are created automatically. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
Request example (microversion 1.19 - )¶
{
"aggregates": [
"42896e0d-205d-4fe3-bd1e-100924931787",
"5e08ea53-c4c6-448e-9334-ac4953de3cfa"
],
"resource_provider_generation": 9
}
Response (microversion 1.1 - )¶
Name |
In |
Type |
Description |
---|---|---|---|
aggregates |
body |
array |
A list of aggregate uuids. Previously nonexistent aggregates are created automatically. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. New in version 1.19 |
Response Example (microversion 1.1 - 1.18)¶
{
"aggregates": [
"42896e0d-205d-4fe3-bd1e-100924931787",
"5e08ea53-c4c6-448e-9334-ac4953de3cfa"
]
}
Response Example (microversion 1.19 - )¶
{
"aggregates": [
"42896e0d-205d-4fe3-bd1e-100924931787",
"5e08ea53-c4c6-448e-9334-ac4953de3cfa"
],
"resource_provider_generation": 9
}
Traits¶
Traits are qualitative characteristics of resource providers. The classic example for traits can be requesting disk from different providers: a user may request 80GiB of disk space for an instance (quantitative), but may also expect that the disk be SSD instead of spinning disk (qualitative). Traits provide a way to mark that a storage provider is SSD or spinning.
Note
Traits API requests are available starting from version 1.6.
Return a list of valid trait strings according to parameters specified.
Normal Response Codes: 200
Request¶
Several query parameters are available to filter the returned list of traits. If multiple different parameters are provided, the results of all filters are merged with a boolean AND.
Name |
In |
Type |
Description |
---|---|---|---|
name (Optional) |
query |
string |
A string to filter traits. The following options are available: startswith operator filters the traits whose name begins with a specific prefix, e.g. name=startswith:CUSTOM, in operator filters the traits whose name is in the specified list, e.g. name=in:HW_CPU_X86_AVX,HW_CPU_X86_SSE,HW_CPU_X86_INVALID_FEATURE. |
associated (Optional) |
query |
string |
If this parameter has a true value, the returned traits will be those that are associated with at least one resource provider. Available values for the parameter are true and false. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
traits |
body |
array |
A list of traits. |
Response Example¶
{
"traits": [
"CUSTOM_HW_FPGA_CLASS1",
"CUSTOM_HW_FPGA_CLASS2",
"CUSTOM_HW_FPGA_CLASS3"
]
}
Check if a trait name exists in this cloud.
Normal Response Codes: 204
Error response codes: itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
path |
string |
The name of a trait. |
Response¶
No body content is returned on a successful GET.
Insert a new custom trait. If traits already exists 204 will be returned.
There are two kinds of traits: the standard traits and the custom traits. The standard traits are interoperable across different OpenStack cloud deployments. The definition of standard traits comes from the os-traits library. The standard traits are read-only in the placement API which means that the user can’t modify any standard traits through API. The custom traits are used by admin users to manage the non-standard qualitative information of resource providers.
Normal Response Codes: 201, 204
Error response codes: badRequest(400)
400 BadRequest if trait name is not prefixed with CUSTOM_ prefix.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
path |
string |
The name of a trait. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
Location |
header |
string |
The location URL of the resource created, HTTP header “Location: <Location URL>” will be returned. |
No body content is returned on a successful PUT.
Delete the trait specified be {name}. Note that only custom traits can be deleted.
Normal Response Codes: 204
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
400 BadRequest if the name to delete is standard trait.
404 Not Found if no such trait exists.
409 Conflict if the name to delete has associations with any ResourceProvider.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
name |
path |
string |
The name of a trait. |
Response¶
No body content is returned on a successful DELETE.
Resource provider traits¶
See Traits for a description. This group of API requests queries/edits the association between traits and resource providers.
Note
Traits API requests are available starting from version 1.6.
Return a list of traits for the resource provider identified by {uuid}.
Normal Response Codes: 200
Error response codes: itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
traits |
body |
array |
A list of traits. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
Response Example¶
{
"resource_provider_generation": 1,
"traits": [
"CUSTOM_HW_FPGA_CLASS1",
"CUSTOM_HW_FPGA_CLASS3"
]
}
Associate traits with the resource provider identified by {uuid}. All the associated traits will be replaced by the traits specified in the request body.
Normal Response Codes: 200
Error response codes: badRequest(400), itemNotFound(404), conflict(409)
400 Bad Request if any of the specified traits are not valid. The valid traits can be queried by GET /traits.
409 Conflict if the resource_provider_generation doesn’t match with the server side.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
traits |
body |
array |
A list of traits. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
Request example¶
{
"resource_provider_generation": 0,
"traits": [
"CUSTOM_HW_FPGA_CLASS1",
"CUSTOM_HW_FPGA_CLASS3"
]
}
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
traits |
body |
array |
A list of traits. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
Response Example¶
{
"resource_provider_generation": 1,
"traits": [
"CUSTOM_HW_FPGA_CLASS1",
"CUSTOM_HW_FPGA_CLASS3"
]
}
Dissociate all the traits from the resource provider identified by {uuid}.
Normal Response Codes: 204
Error response codes: itemNotFound(404), conflict(409)
409 Conflict if the provider’s traits are updated by another thread while attempting the operation.
Note
Since this request does not accept the resource provider generation,
it is not safe to use when multiple threads are managing traits for
a single provider. In such situations, use the
PUT /resource_providers/{uuid}/traits
API with an empty
traits
list.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
Response¶
No body content is returned on a successful DELETE.
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.
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.
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
placement.concurrent_update
if inventories are updated by another request while attempting the operation. See Resource Provider and Consumer Generations.409 Conflict with error code
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 Resource Provider and Consumer Generations.
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
consumer_uuid |
body |
string |
The uuid of a consumer. |
consumer_generation |
body |
integer |
The generation of the consumer. Should be set to New in version 1.28 |
consumer_type |
body |
string |
A string that consists of numbers, New in version 1.38 |
project_id |
body |
string |
The uuid of a project. |
user_id |
body |
string |
The uuid of a user. |
allocations |
body |
object |
A dictionary of resource allocations keyed by resource provider uuid. If this is an empty object, allocations for this consumer will be removed. |
generation (Optional) |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. The value is ignored; it is present to preserve symmetry between read and write representations. |
resources |
body |
object |
A dictionary of resource records keyed by resource class name. |
mappings (Optional) |
body |
object |
A dictionary associating request group suffixes with a list of uuids identifying the resource providers that satisfied each group. The empty string and New in version 1.34 |
Request example (microversions 1.38 - )¶
{
"30328d13-e299-4a93-a102-61e4ccabe474": {
"consumer_generation": 1,
"project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"allocations": {
"e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
"resources": {
"VCPU": 2,
"MEMORY_MB": 3
},
"generation": 4
}
},
"consumer_type": "INSTANCE"
},
"71921e4e-1629-4c5b-bf8d-338d915d2ef3": {
"consumer_generation": 1,
"project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"allocations": {},
"consumer_type": "MIGRATION"
},
"48c1d40f-45d8-4947-8d46-52b4e1326df8": {
"consumer_generation": 1,
"project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"allocations": {
"e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
"resources": {
"VCPU": 4,
"MEMORY_MB": 5
},
"generation": 12
}
},
"consumer_type": "INSTANCE"
}
}
Request example (microversions 1.28 - 1.36)¶
{
"30328d13-e299-4a93-a102-61e4ccabe474": {
"consumer_generation": 1,
"project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"allocations": {
"e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
"resources": {
"VCPU": 2,
"MEMORY_MB": 3
},
"generation": 4
}
}
},
"71921e4e-1629-4c5b-bf8d-338d915d2ef3": {
"consumer_generation": 1,
"project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"allocations": {}
},
"48c1d40f-45d8-4947-8d46-52b4e1326df8": {
"consumer_generation": 1,
"project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"allocations": {
"e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
"resources": {
"VCPU": 4,
"MEMORY_MB": 5
},
"generation": 12
}
}
}
}
Request example (microversions 1.13 - 1.27)¶
{
"30328d13-e299-4a93-a102-61e4ccabe474": {
"project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"allocations": {
"e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
"resources": {
"VCPU": 2,
"MEMORY_MB": 3
}
}
}
},
"71921e4e-1629-4c5b-bf8d-338d915d2ef3": {
"project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"allocations": {}
},
"48c1d40f-45d8-4947-8d46-52b4e1326df8": {
"project_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"user_id": "131d4efb-abc0-4872-9b92-8c8b9dc4320f",
"allocations": {
"e10927c4-8bc9-465d-ac60-d2f79f7e4a00": {
"resources": {
"VCPU": 4,
"MEMORY_MB": 5
}
}
}
}
}
Response¶
No body content is returned after a successful request
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": {}}
.
Normal Response Codes: 200
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
consumer_uuid |
path |
string |
The uuid of a consumer. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
allocations |
body |
object |
A dictionary of allocations keyed by resource provider uuid. |
generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
resources |
body |
object |
A dictionary of resource records keyed by resource class name. |
consumer_generation |
body |
integer |
The generation of the consumer. Will be absent when listing allocations for a consumer uuid that has no allocations. New in version 1.28 |
consumer_type |
body |
string |
A string that consists of numbers, New in version 1.38 |
project_id |
body |
string |
The uuid of a project. Will be absent when listing allocations for a consumer uuid that has no allocations. New in version 1.12 |
user_id |
body |
string |
The uuid of a user. Will be absent when listing allocations for a consumer uuid that has no allocations. New in version 1.12 |
Response Example (1.38 - )¶
{
"allocations": {
"92637880-2d79-43c6-afab-d860886c6391": {
"generation": 2,
"resources": {
"DISK_GB": 5
}
},
"ba8e1ef8-7fa3-41a4-9bb4-d7cb2019899b": {
"generation": 8,
"resources": {
"MEMORY_MB": 512,
"VCPU": 2
}
}
},
"consumer_generation": 1,
"project_id": "7e67cbf7-7c38-4a32-b85b-0739c690991a",
"user_id": "067f691e-725a-451a-83e2-5c3d13e1dffc",
"consumer_type": "INSTANCE"
}
Response Example (1.28 - 1.36)¶
{
"allocations": {
"92637880-2d79-43c6-afab-d860886c6391": {
"generation": 2,
"resources": {
"DISK_GB": 5
}
},
"ba8e1ef8-7fa3-41a4-9bb4-d7cb2019899b": {
"generation": 8,
"resources": {
"MEMORY_MB": 512,
"VCPU": 2
}
}
},
"consumer_generation": 1,
"project_id": "7e67cbf7-7c38-4a32-b85b-0739c690991a",
"user_id": "067f691e-725a-451a-83e2-5c3d13e1dffc"
}
Response Example (1.12 - 1.27)¶
{
"allocations": {
"92637880-2d79-43c6-afab-d860886c6391": {
"generation": 2,
"resources": {
"DISK_GB": 5
}
},
"ba8e1ef8-7fa3-41a4-9bb4-d7cb2019899b": {
"generation": 8,
"resources": {
"MEMORY_MB": 512,
"VCPU": 2
}
}
},
"project_id": "7e67cbf7-7c38-4a32-b85b-0739c690991a",
"user_id": "067f691e-725a-451a-83e2-5c3d13e1dffc"
}
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.
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
placement.concurrent_update
if inventories are updated by another request while attempting the operation. See Resource Provider and Consumer Generations.409 Conflict with error code
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 Resource Provider and Consumer Generations.
Request (microversions 1.12 - )¶
Name |
In |
Type |
Description |
---|---|---|---|
consumer_uuid |
path |
string |
The uuid of a consumer. |
allocations |
body |
object |
A dictionary of resource allocations keyed by resource provider uuid. |
resources |
body |
object |
A dictionary of resource records keyed by resource class name. |
consumer_generation |
body |
integer |
The generation of the consumer. Should be set to New in version 1.28 |
consumer_type |
body |
string |
A string that consists of numbers, New in version 1.38 |
project_id |
body |
string |
The uuid of a project. |
user_id |
body |
string |
The uuid of a user. |
generation (Optional) |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. The value is ignored; it is present to preserve symmetry between read and write representations. |
mappings (Optional) |
body |
object |
A dictionary associating request group suffixes with a list of uuids identifying the resource providers that satisfied each group. The empty string and New in version 1.34 |
Request example (microversions 1.38 - )¶
{
"allocations": {
"4e061c03-611e-4caa-bf26-999dcff4284e": {
"resources": {
"DISK_GB": 20
}
},
"89873422-1373-46e5-b467-f0c5e6acf08f": {
"resources": {
"MEMORY_MB": 1024,
"VCPU": 1
}
}
},
"consumer_generation": 1,
"user_id": "66cb2f29-c86d-47c3-8af5-69ae7b778c70",
"project_id": "42a32c07-3eeb-4401-9373-68a8cdca6784",
"consumer_type": "INSTANCE"
}
Request example (microversions 1.28 - 1.36)¶
{
"allocations": {
"4e061c03-611e-4caa-bf26-999dcff4284e": {
"resources": {
"DISK_GB": 20
}
},
"89873422-1373-46e5-b467-f0c5e6acf08f": {
"resources": {
"MEMORY_MB": 1024,
"VCPU": 1
}
}
},
"consumer_generation": 1,
"user_id": "66cb2f29-c86d-47c3-8af5-69ae7b778c70",
"project_id": "42a32c07-3eeb-4401-9373-68a8cdca6784"
}
Request example (microversions 1.12 - 1.27)¶
{
"allocations": {
"4e061c03-611e-4caa-bf26-999dcff4284e": {
"resources": {
"DISK_GB": 20
}
},
"89873422-1373-46e5-b467-f0c5e6acf08f": {
"resources": {
"MEMORY_MB": 1024,
"VCPU": 1
}
}
},
"user_id": "66cb2f29-c86d-47c3-8af5-69ae7b778c70",
"project_id": "42a32c07-3eeb-4401-9373-68a8cdca6784"
}
Request (microversions 1.0 - 1.11)¶
Name |
In |
Type |
Description |
---|---|---|---|
consumer_uuid |
path |
string |
The uuid of a consumer. |
allocations |
body |
array |
A list of dictionaries. |
resources |
body |
object |
A dictionary of resource records keyed by resource class name. |
resource_provider |
body |
object |
A dictionary which contains the UUID of the resource provider. |
uuid |
body |
string |
The uuid of a resource provider. |
project_id |
body |
string |
The uuid of a project. New in version 1.8 |
user_id |
body |
string |
The uuid of a user. New in version 1.8 |
Request example (microversions 1.0 - 1.11)¶
{
"allocations": [
{
"resource_provider": {
"uuid": "844ac34d-620e-474c-833c-4c9921251353"
},
"resources": {
"MEMORY_MB": 512,
"VCPU": 2
}
},
{
"resource_provider": {
"uuid": "92637880-2d79-43c6-afab-d860886c6391"
},
"resources": {
"DISK_GB": 5
}
}
],
"project_id": "6e3b2ce9-9175-4830-a862-b9de690bdceb",
"user_id": "81c516e3-5e0e-4dcb-9a38-4473d229a950"
}
Response¶
No body content is returned on a successful PUT.
Delete all allocation records for the consumer identified by {consumer_uuid} on all resource providers it is consuming.
Normal Response Codes: 204
Error response codes: itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
consumer_uuid |
path |
string |
The uuid of a consumer. |
Response¶
No body content is returned on a successful DELETE.
Resource provider allocations¶
See Allocations for a description.
Return a representation of all allocations made against this resource provider, keyed by consumer uuid. Each allocation includes one or more classes of resource and the amount consumed.
Normal Response Codes: 200
Error response codes: itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
allocations |
body |
object |
A dictionary of allocation records keyed by consumer uuid. |
resources |
body |
object |
A dictionary of resource records keyed by resource class name. |
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
Response Example¶
{
"allocations": {
"56785a3f-6f1c-4fec-af0b-0faf075b1fcb": {
"resources": {
"MEMORY_MB": 256,
"VCPU": 1
}
},
"9afd5aeb-d6b9-4dea-a588-1e6327a91834": {
"resources": {
"MEMORY_MB": 512,
"VCPU": 2
}
},
"9d16a611-e7f9-4ef3-be26-c61ed01ecefb": {
"resources": {
"MEMORY_MB": 1024,
"VCPU": 1
}
}
},
"resource_provider_generation": 12
}
Usages¶
Represent the consumption of resources for a project and user.
Note
Usages API requests are available starting from version 1.9.
Return a report of usage information for resources associated with the project identified by project_id and user identified by user_id. The value is a dictionary of resource classes paired with the sum of the allocations of that resource class for provided parameters.
Normal Response Codes: 200
Error response codes: badRequest(400)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
project_id |
query |
string |
The uuid of a project. |
user_id (Optional) |
query |
string |
The uuid of a user. |
consumer_type (Optional) |
query |
string |
A string that consists of numbers, New in version 1.38 |
Response (microversions 1.38 - )¶
Name |
In |
Type |
Description |
---|---|---|---|
usages.consumer_type |
body |
string |
A string that consists of numbers, New in version 1.38 |
usages.consumer_type.consumer_count |
body |
integer |
The number of consumers of a particular New in version 1.38 |
usages.consumer_type.RESOURCE_CLASS |
body |
integer |
An amount of resource class consumed in a usage report. |
Response Example (microversions 1.38 - )¶
{
"usages" : {
"INSTANCE" : {
"consumer_count" : 5,
"MEMORY_MB" : 512,
"VCPU" : 2,
"DISK_GB" : 5
},
"MIGRATION" : {
"DISK_GB" : 5,
"VCPU" : 2,
"consumer_count" : 2,
"MEMORY_MB" : 512
},
"unknown" : {
"VCPU" : 2,
"DISK_GB" : 5,
"consumer_count" : 1,
"MEMORY_MB" : 512
}
}
}
Response (microversions 1.9 - 1.36)¶
Name |
In |
Type |
Description |
---|---|---|---|
usages |
body |
object |
A dictionary of resource records keyed by resource class name. |
Response Example (microversions 1.9 - 1.36)¶
{
"usages": {
"DISK_GB": 5,
"MEMORY_MB": 512,
"VCPU": 2
}
}
Resource provider usages¶
Show the consumption of resources for a resource provider in an aggregated form, i.e. without information for a particular consumer. See Resource provider allocations.
Return a report of usage information for resources associated with the resource provider identified by {uuid}. The value is a dictionary of resource classes paired with the sum of the allocations of that resource class for this resource provider.
Normal Response Codes: 200
Error response codes: itemNotFound(404)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
uuid |
path |
string |
The uuid of a resource provider. |
Response¶
Name |
In |
Type |
Description |
---|---|---|---|
resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
usages |
body |
object |
The usage summary of the resource provider. This is a dictionary that describes how much each class of resource is being consumed on this resource provider. For example, |
Response Example¶
{
"resource_provider_generation": 1,
"usages": {
"DISK_GB": 1,
"MEMORY_MB": 512,
"VCPU": 1
}
}
Allocation candidates¶
Note
Allocation candidates API requests are available starting from version 1.10.
Returns a dictionary representing a collection of allocation requests
and resource provider summaries. Each allocation request has
information to form a PUT /allocations/{consumer_uuid}
request to claim
resources against a related set of resource providers. Additional parameters
might be required, see Update allocations. As several allocation
requests are available it’s necessary to select one. To make a
decision, resource provider summaries are provided with the
inventory/capacity information. For example, this information is used by
nova-scheduler’s FilterScheduler to make decisions about on which compute host
to build a server.
You can also find additional case studies of the request parameters in the Modeling with Provider Trees document.
Normal Response Codes: 200
Error response codes: badRequest(400)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
resources (Optional) |
query |
string |
A comma-separated list of strings indicating an amount of resource of a specified class that providers in each allocation request must collectively have the capacity and availability to serve: resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
These resources may be satisfied by any provider in the same non-sharing tree or associated via aggregate. |
required (Optional) |
query |
string |
A comma-separated list of traits that a provider must have: required=HW_CPU_X86_AVX,HW_CPU_X86_SSE
Allocation requests in the response will be for resource providers that
have capacity for all requested resources and the set of those resource
providers will collectively contain all of the required traits. These
traits may be satisfied by any provider in the same non-sharing tree or
associated via aggregate as far as that provider also contributes resource
to the request. Starting from microversion 1.22 traits which
are forbidden from any resource provider contributing resources to the
request may be expressed by prefixing a trait with a Starting from microversion 1.39 the required=T1,!T2&required=T3
means T1 and not T2 and T3. Also starting from microversion 1.39 the required=in:T1,T2,T3
which means T1 or T2 or T3. Mixing forbidden traits into an required=in:T3,T4&required=T1,!T2
is supported and it means T1 and not T2 and (T3 or T4). New in version 1.17 |
member_of (Optional) |
query |
string |
A string representing an aggregate uuid; or the prefix member_of=5e08ea53-c4c6-448e-9334-ac4953de3cfa
member_of=in:42896e0d-205d-4fe3-bd1e-100924931787,5e08ea53-c4c6-448e-9334-ac4953de3cfa
Starting from microversion 1.24 specifying multiple member_of=AGGA_UUID&member_of=in:AGGB_UUID,AGGC_UUID
Starting from microversion 1.32 specifying forbidden aggregates is supported in the member_of=AGGA_UUID&member_of=!AGGB_UUID
would translate logically to “Candidate resource providers must be in AGGA and not in AGGB.”
We do NOT support member_of=!in:AGGA_UUID,AGGB_UUID,AGGC_UUID
member_of=!AGGA_UUID&member_of=!AGGB_UUID&member_of=!AGGC_UUID
We do not check if the same aggregate uuid is in both positive and negative expression to return 400 BadRequest. We still return 200 for such cases. For example: member_of=AGGA_UUID&member_of=!AGGA_UUID
would return empty member_of=in:AGGA_UUID,AGGB_UUID&member_of=!AGGA_UUID
would return resource providers that are NOT in AGGA but in AGGB. New in version 1.21 |
in_tree (Optional) |
query |
string |
A string representing a resource provider uuid. When supplied, it will filter the returned allocation candidates to only those resource providers that are in the same tree with the given resource provider. New in version 1.31 |
resourcesN (Optional) |
query |
string |
A comma-separated list of strings indicating an amount of resource of a specified class that a provider must have the capacity to serve: resources42=VCPU:4,DISK_GB:64,MEMORY_MB:2048
The parameter key is In microversions 1.25 - 1.32 the suffix is a number. Starting from microversion 1.33 the suffix is a string that may be 1-64
characters long and consist of numbers, Separate groupings - with or without a suffix - may or may not be satisfied
by the same provider depending on the value of the New in version 1.25 |
requiredN (Optional) |
query |
string |
A comma-separated list of traits that a provider must have, or (if prefixed
with a required42=HW_CPU_X86_AVX,HW_CPU_X86_SSE,!HW_CPU_X86_AVX2
The parameter key is The value format is the same as for the (not granular) In microversions 1.25 - 1.32 the suffix is a number. Starting from microversion 1.33 the suffix is a string that may be 1-64
characters long and consist of numbers, It is an error to specify a Starting from microversion 1.39 the granular requiredN=in:T3,T4&requiredN=T1,!T2
is supported and it means T1 and not T2 and (T3 or T4). New in version 1.25 |
member_ofN (Optional) |
query |
string |
A string representing an aggregate uuid; or the prefix New in version 1.25 |
in_treeN (Optional) |
query |
string |
A string representing a resource provider uuid. The parameter key is New in version 1.31 |
group_policy (Optional) |
query |
string |
When more than one New in version 1.25 |
limit (Optional) |
query |
integer |
A positive integer used to limit the maximum number of allocation candidates returned in the response. New in version 1.16 |
root_required (Optional) |
query |
string |
A comma-separated list of trait requirements that the root provider of the (non-sharing) tree must satisfy: root_required=COMPUTE_SUPPORTS_MULTI_ATTACH,!CUSTOM_WINDOWS_LICENSED
Allocation requests in the response will be limited to those whose
(non-sharing) tree’s root provider satisfies the specified trait
requirements. Traits which are forbidden (must not be present on the
root provider) are expressed by prefixing the trait with a New in version 1.35 |
same_subtree (Optional) |
query |
string |
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 New in version 1.36 |
Response (microversions 1.12 - )¶
Name |
In |
Type |
Description |
---|---|---|---|
allocation_requests |
body |
array |
A list of objects that contain a serialized HTTP body that a client may subsequently use in a call to PUT /allocations/{consumer_uuid} to claim resources against a related set of resource providers. |
provider_summaries |
body |
object |
A dictionary keyed by resource provider UUID included in the |
allocations |
body |
object |
A dictionary of allocations keyed by resource provider uuid. |
resources |
body |
object |
A dictionary of resource records keyed by resource class name. |
capacity |
body |
integer |
The amount of the resource that the provider can accommodate. |
used |
body |
integer |
The amount of the resource that has been already allocated. |
traits |
body |
array |
A list of traits. New in version 1.17 |
parent_provider_uuid |
body |
string |
The UUID of the immediate parent of the resource provider. New in version 1.29 |
root_provider_uuid |
body |
string |
UUID of the top-most provider in this provider tree. New in version 1.29 |
mappings |
body |
object |
A dictionary associating request group suffixes with a list of uuids identifying the resource providers that satisfied each group. The empty string and New in version 1.34 |
Response Example (microversions 1.34 - )¶
{
"allocation_requests": [
{
"allocations": {
"92e971c9-777a-48bf-a181-a2ca1105c015": {
"resources": {
"NET_BW_EGR_KILOBIT_PER_SEC": 10
}
},
"cefbdf54-05a8-4db4-ad2b-d6729e5a4de8": {
"resources": {
"NET_BW_EGR_KILOBIT_PER_SEC": 20
}
},
"9a9c6b0f-e8d1-4d16-b053-a2bfe8a76757": {
"resources": {
"VCPU": 1
}
}
},
"mappings": {
"_NET1": [
"92e971c9-777a-48bf-a181-a2ca1105c015"
],
"_NET2": [
"cefbdf54-05a8-4db4-ad2b-d6729e5a4de8"
],
"": [
"9a9c6b0f-e8d1-4d16-b053-a2bfe8a76757"
]
}
}
],
"provider_summaries": {
"be99627d-e848-44ef-8341-683e2e557c58": {
"resources": {},
"traits": [
"COMPUTE_VOLUME_MULTI_ATTACH"
],
"parent_provider_uuid": null,
"root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
},
"9a9c6b0f-e8d1-4d16-b053-a2bfe8a76757": {
"resources": {
"VCPU": {
"capacity": 4,
"used": 0
},
"MEMORY_MB": {
"capacity": 2048,
"used": 0
}
},
"traits": [
"HW_NUMA_ROOT",
"CUSTOM_FOO"
],
"parent_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58",
"root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
},
"ba415f98-1960-4488-b2ed-4518b77eaa60": {
"resources": {},
"traits": [
"CUSTOM_VNIC_TYPE_DIRECT"
],
"parent_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58",
"root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
},
"92e971c9-777a-48bf-a181-a2ca1105c015": {
"resources": {
"NET_BW_EGR_KILOBIT_PER_SEC": {
"capacity": 10000,
"used": 0
}
},
"traits": [
"CUSTOM_PHYSNET1"
],
"parent_provider_uuid": "ba415f98-1960-4488-b2ed-4518b77eaa60",
"root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
},
"cefbdf54-05a8-4db4-ad2b-d6729e5a4de8": {
"resources": {
"NET_BW_EGR_KILOBIT_PER_SEC": {
"capacity": 20000,
"used": 0
}
},
"traits": [
"CUSTOM_PHYSNET2"
],
"parent_provider_uuid": "ba415f98-1960-4488-b2ed-4518b77eaa60",
"root_provider_uuid": "be99627d-e848-44ef-8341-683e2e557c58"
}
}
}
Response Example (microversions 1.29 - 1.33)¶
{
"allocation_requests": [
{
"allocations": {
"a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
"resources": {
"DISK_GB": 100
}
},
"35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
"resources": {
"VCPU": 1,
"MEMORY_MB": 1024
}
}
}
},
{
"allocations": {
"a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
"resources": {
"DISK_GB": 100
}
},
"915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
"resources": {
"VCPU": 1,
"MEMORY_MB": 1024
}
}
}
}
],
"provider_summaries": {
"a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
"resources": {
"DISK_GB": {
"used": 0,
"capacity": 1900
}
},
"traits": ["MISC_SHARES_VIA_AGGREGATE"],
"parent_provider_uuid": null,
"root_provider_uuid": "a99bad54-a275-4c4f-a8a3-ac00d57e5c64"
},
"35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
"resources": {
"VCPU": {
"used": 0,
"capacity": 384
},
"MEMORY_MB": {
"used": 0,
"capacity": 196608
}
},
"traits": ["HW_CPU_X86_SSE2", "HW_CPU_X86_AVX2"],
"parent_provider_uuid": null,
"root_provider_uuid": "35791f28-fb45-4717-9ea9-435b3ef7c3b3"
},
"915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
"resources": {
"VCPU": {
"used": 0,
"capacity": 384
},
"MEMORY_MB": {
"used": 0,
"capacity": 196608
}
},
"traits": ["HW_NIC_SRIOV"],
"parent_provider_uuid": null,
"root_provider_uuid": "915ef8ed-9b91-4e38-8802-2e4224ad54cd"
},
"f5120cad-67d9-4f20-9210-3092a79a28cf": {
"resources": {
"SRIOV_NET_VF": {
"used": 0,
"capacity": 8
}
},
"traits": [],
"parent_provider_uuid": "915ef8ed-9b91-4e38-8802-2e4224ad54cd",
"root_provider_uuid": "915ef8ed-9b91-4e38-8802-2e4224ad54cd"
}
}
}
Response Example (microversions 1.17 - 1.28)¶
{
"allocation_requests": [
{
"allocations": {
"a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
"resources": {
"DISK_GB": 100
}
},
"35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
"resources": {
"VCPU": 1,
"MEMORY_MB": 1024
}
}
}
},
{
"allocations": {
"a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
"resources": {
"DISK_GB": 100
}
},
"915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
"resources": {
"VCPU": 1,
"MEMORY_MB": 1024
}
}
}
}
],
"provider_summaries": {
"a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
"resources": {
"DISK_GB": {
"used": 0,
"capacity": 1900
}
},
"traits": ["HW_CPU_X86_SSE2", "HW_CPU_X86_AVX2"]
},
"915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
"resources": {
"VCPU": {
"used": 0,
"capacity": 384
},
"MEMORY_MB": {
"used": 0,
"capacity": 196608
}
},
"traits": ["HW_NIC_SRIOV"]
},
"35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
"resources": {
"VCPU": {
"used": 0,
"capacity": 384
},
"MEMORY_MB": {
"used": 0,
"capacity": 196608
}
},
"traits": []
}
}
}
Response Example (microversions 1.12 - 1.16)¶
{
"allocation_requests": [
{
"allocations": {
"a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
"resources": {
"DISK_GB": 100
}
},
"35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
"resources": {
"VCPU": 1,
"MEMORY_MB": 1024
}
}
}
},
{
"allocations": {
"a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
"resources": {
"DISK_GB": 100
}
},
"915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
"resources": {
"VCPU": 1,
"MEMORY_MB": 1024
}
}
}
}
],
"provider_summaries": {
"a99bad54-a275-4c4f-a8a3-ac00d57e5c64": {
"resources": {
"DISK_GB": {
"used": 0,
"capacity": 1900
}
}
},
"915ef8ed-9b91-4e38-8802-2e4224ad54cd": {
"resources": {
"VCPU": {
"used": 0,
"capacity": 384
},
"MEMORY_MB": {
"used": 0,
"capacity": 196608
}
}
},
"35791f28-fb45-4717-9ea9-435b3ef7c3b3": {
"resources": {
"VCPU": {
"used": 0,
"capacity": 384
},
"MEMORY_MB": {
"used": 0,
"capacity": 196608
}
}
}
}
}
Response (microversions 1.10 - 1.11)¶
Name |
In |
Type |
Description |
---|---|---|---|
allocation_requests |
body |
array |
A list of objects that contain a serialized HTTP body that a client may subsequently use in a call to PUT /allocations/{consumer_uuid} to claim resources against a related set of resource providers. |
provider_summaries |
body |
object |
A dictionary keyed by resource provider UUID included in the |
allocations |
body |
array |
A list of dictionaries. |
resource_provider |
body |
object |
A dictionary which contains the UUID of the resource provider. |
uuid |
body |
string |
The uuid of a resource provider. |
resources |
body |
object |
A dictionary of resource records keyed by resource class name. |
capacity |
body |
integer |
The amount of the resource that the provider can accommodate. |
used |
body |
integer |
The amount of the resource that has been already allocated. |
Response Example (microversions 1.10 - 1.11)¶
{
"allocation_requests": [
{
"allocations": [
{
"resource_provider": {
"uuid": "30742363-f65e-4012-a60a-43e0bec38f0e"
},
"resources": {
"MEMORY_MB": 512
}
}
]
}
],
"provider_summaries": {
"30742363-f65e-4012-a60a-43e0bec38f0e": {
"resources": {
"DISK_GB": {
"capacity": 77,
"used": 0
},
"MEMORY_MB": {
"capacity": 11206,
"used": 256
},
"VCPU": {
"capacity": 64,
"used": 0
}
}
}
}
}
Reshaper¶
Note
Reshaper requests are available starting from version 1.30.
Atomically migrate resource provider inventories and associated allocations. This is used when some of the inventory needs to move 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.
Normal Response Codes: 204
Error Response Codes: badRequest(400), conflict(409)
Request¶
Name |
In |
Type |
Description |
---|---|---|---|
inventories |
body |
object |
A dictionary of multiple inventories, keyed by resource provider uuid. Each inventory describes the desired full inventory for each resource provider. An empty dictionary causes the inventory for that provider to be deleted. |
inventories.{resource_provider_uuid}.resource_provider_generation |
body |
integer |
A consistent view marker that assists with the management of concurrent resource provider updates. |
inventories.{resource_provider_uuid}.inventories |
body |
object |
A dictionary of inventories keyed by resource classes. |
allocations |
body |
object |
A dictionary of multiple allocations, keyed by consumer uuid. Each collection of allocations describes the full set of allocations for each consumer. Each consumer allocations dict is itself a dictionary of resource allocations keyed by resource provider uuid. An empty dictionary indicates no change in existing allocations, whereas an empty |
allocations.{consumer_uuid}.allocations |
body |
object |
A dictionary of resource allocations keyed by resource provider uuid. If this is an empty object, allocations for this consumer will be removed. |
allocations.{consumer_uuid}.allocations.{resource_provider_uuid}.resources |
body |
object |
A dictionary of resource records keyed by resource class name. |
allocations.{consumer_uuid}.project_id |
body |
string |
The uuid of a project. |
allocations.{consumer_uuid}.user_id |
body |
string |
The uuid of a user. |
allocations.{consumer_uuid}.mappings |
body |
object |
A dictionary associating request group suffixes with a list of uuids identifying the resource providers that satisfied each group. The empty string and New in version 1.34 |
allocations.{consumer_uuid}.consumer_generation |
body |
integer |
The generation of the consumer. Should be set to |
allocations.{consumer_uuid}.consumer_type |
body |
string |
A string that consists of numbers, New in version 1.38 |
Request Example¶
{
"allocations": {
"9ae60315-80c2-48a0-a168-ca4f27c307e1": {
"allocations": {
"a7466641-cd72-499b-b6c9-c208eacecb3d": {
"resources": {
"DISK_GB": 1000
}
}
},
"project_id": "2f0c4ffc-4c4d-407a-b334-56297b871b7f",
"user_id": "cc8a0fe0-2b7c-4392-ae51-747bc73cf473",
"consumer_generation": 1,
"consumer_type": "INSTANCE"
},
"4a6444e5-10d6-43f6-9a0b-8acce9309ac9": {
"allocations": {
"c4ddddbb-01ee-4814-85c9-f57a962c22ba": {
"resources": {
"VCPU": 1
}
},
"a7466641-cd72-499b-b6c9-c208eacecb3d": {
"resources": {
"DISK_GB": 20
}
}
},
"project_id": "2f0c4ffc-4c4d-407a-b334-56297b871b7f",
"user_id": "406e1095-71cb-47b9-9b3c-aedb7f663f5a",
"consumer_generation": 1,
"consumer_type": "INSTANCE"
},
"e10e7ca0-2ac5-4c98-bad9-51c95b1930ed": {
"allocations": {
"c4ddddbb-01ee-4814-85c9-f57a962c22ba": {
"resources": {
"VCPU": 8
}
}
},
"project_id": "2f0c4ffc-4c4d-407a-b334-56297b871b7f",
"user_id": "cc8a0fe0-2b7c-4392-ae51-747bc73cf473",
"consumer_generation": 1,
"consumer_type": "INSTANCE"
}
},
"inventories": {
"c4ddddbb-01ee-4814-85c9-f57a962c22ba": {
"inventories": {
"VCPU": {
"max_unit": 8,
"total": 10
}
},
"resource_provider_generation": null
},
"a7466641-cd72-499b-b6c9-c208eacecb3d": {
"inventories": {
"DISK_GB": {
"min_unit": 10,
"total": 2048,
"max_unit": 1200,
"step_size": 10
}
},
"resource_provider_generation": 5
}
}
}
No body content is returned on a successful POST.