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 req- + UUID (UUID4). If not in accordance with the format, it is ignored. It is associated with the request and appears in the log lines for that request. By default, the middleware configuration ensures that the global request ID appears in the log files.

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 a status 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 a code attribute in the JSON body. These are documented below. Where a response does not use a specific code placement.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

placement.undefined_code

The default code used when a specific code has not been defined or is not required.

placement.inventory.inuse

An attempt has been made to remove or shrink inventory that has capacity in use.

placement.concurrent_update

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.

placement.duplicate_name

A resource of this type already exists with the same name, and duplicate names are not allowed.

placement.resource_provider.inuse

An attempt was made to remove a resource provider, but there are allocations against its inventory.

placement.resource_provider.cannot_delete_parent

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.

placement.resource_provider.not_found

A resource provider mentioned in an operation involving multiple resource providers, such as Reshaper, does not exist.

placement.query.duplicate_key

A request included multiple instances of a query parameter that may only be specified once.

placement.query.bad_value

A value in a request conformed to the schema, but failed semantic validation.

placement.query.missing_value

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.

GET
/

List Versions

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.

GET
/resource_providers

List resource providers

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 in: followed by a comma-separated list of strings representing aggregate uuids. The returned resource providers must directly be associated with at least one of the aggregates identified by uuid:

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 query string parameters is possible. Multiple member_of parameters will result in filtering providers that are associated with aggregates listed in all of the member_of query string values. For example, to get the providers that are associated with aggregate A as well as associated with any of aggregates B or C, the user could issue the following query:

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 query string parameter. Forbidden aggregates are prefixed with a !. This negative expression can also be used in multiple member_of parameters:

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 ! on the values within in:, but we support !in:. Both of the following two example queries return candidate resource providers that are NOT in AGGA, AGGB, or AGGC:

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 resource_providers, while:

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 query parameter can be repeated. The trait lists from the repeated parameters are ANDed together. So:

required=T1,!T2&required=T3

means T1 and not T2 and T3.

Also starting from microversion 1.39 the required parameter supports the syntax:

required=in:T1,T2,T3

which means T1 or T2 or T3.

Mixing forbidden traits into an in: prefixed value is not supported and rejected. But mixing normal trait list and in: trait list in two query params within the same request is supported. So:

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

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"
    }
  ]
}
POST
/resource_providers

Create resource provider

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.

  • Before version 1.37, once set, the parent of a resource provider cannot be changed.

  • Since version 1.37, it can be set to any existing provider UUID excepts to providers that would cause a loop. Also it can be set to null to transform the provider to a new root provider. This operation needs to be used carefully. Moving providers can mean that the original rules used to create the existing resource allocations may be invalidated by that move.

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.

GET
/resource_providers/{uuid}

Show resource provider

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"
}
PUT
/resource_providers/{uuid}

Update resource provider

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.

  • Before version 1.37, once set, the parent of a resource provider cannot be changed.

  • Since version 1.37, it can be set to any existing provider UUID excepts to providers that would cause a loop. Also it can be set to null to transform the provider to a new root provider. This operation needs to be used carefully. Moving providers can mean that the original rules used to create the existing resource allocations may be invalidated by that move.

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
/resource_providers/{uuid}

Delete resource provider

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.

GET
/resource_classes

List resource classes

Return a list of all resource classes.

Normal Response Codes: 200

Response

Name

In

Type

Description

resource_classes

body

array

A list of resource_class objects.

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"
        }
    ]
}
POST
/resource_classes

Create resource class

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 CUSTOM_. If not, the request returns a Bad Request (400) response code.

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.

GET
/resource_classes/{name}

Show resource class

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"
}
PUT
/resource_classes/{name}

Update resource class

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 CUSTOM_. If not, the request returns a Bad Request (400) response code.

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.

PUT
/resource_classes/{name}

Update resource class (microversions 1.2 - 1.6)

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 CUSTOM_. If not, the request returns a Bad Request (400) response code.

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
/resource_classes/{name}

Delete resource class

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.

GET
/resource_providers/{uuid}/inventories

List resource provider inventories

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
}
PUT
/resource_providers/{uuid}/inventories

Update resource provider inventories

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 total. Starting from microversion 1.26, this value has to be less than or equal to the value of total.

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
}
DELETE
/resource_providers/{uuid}/inventories

Delete resource provider inventories

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.

GET
/resource_providers/{uuid}/inventories/{resource_class}

Show resource provider inventory

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
}
PUT
/resource_providers/{uuid}/inventories/{resource_class}

Update resource provider inventory

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 total. Starting from microversion 1.26, this value has to be less than or equal to the value of total.

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
/resource_providers/{uuid}/inventories/{resource_class}

Delete resource provider inventory

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.

GET
/resource_providers/{uuid}/aggregates

List resource provider aggregates

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
}
PUT
/resource_providers/{uuid}/aggregates

Update resource provider aggregates

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.

GET
/traits

List traits

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"
    ]
}
GET
/traits/{name}

Show traits

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.

PUT
/traits/{name}

Update traits

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
/traits/{name}

Delete traits

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.

GET
/resource_providers/{uuid}/traits

List resource provider traits

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"
    ]
}
PUT
/resource_providers/{uuid}/traits

Update resource provider traits

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"
    ]
}
DELETE
/resource_providers/{uuid}/traits

Delete resource provider traits

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.

POST
/allocations

Manage allocations

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 null when indicating that the caller expects the consumer does not yet exist.

New in version 1.28

consumer_type

body

string

A string that consists of numbers, A-Z, and _ describing what kind of consumer is creating, or has created, allocations using a quantity of inventory. The string is determined by the client when writing allocations and it is up to the client to ensure correct choices amongst collaborating services. For example, the compute service may choose to type some consumers ‘INSTANCE’ and others ‘MIGRATION’.

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 [a-zA-Z0-9_-]+ are valid suffixes. This field may be sent when writing allocations back to the server but will be ignored; this preserves symmetry between read and write representations.

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

GET
/allocations/{consumer_uuid}

List allocations

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, A-Z, and _ describing what kind of consumer is creating, or has created, allocations using a quantity of inventory. The string is determined by the client when writing allocations and it is up to the client to ensure correct choices amongst collaborating services. For example, the compute service may choose to type some consumers ‘INSTANCE’ and others ‘MIGRATION’.

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"
}
PUT
/allocations/{consumer_uuid}

Update allocations

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 null when indicating that the caller expects the consumer does not yet exist.

New in version 1.28

consumer_type

body

string

A string that consists of numbers, A-Z, and _ describing what kind of consumer is creating, or has created, allocations using a quantity of inventory. The string is determined by the client when writing allocations and it is up to the client to ensure correct choices amongst collaborating services. For example, the compute service may choose to type some consumers ‘INSTANCE’ and others ‘MIGRATION’.

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 [a-zA-Z0-9_-]+ are valid suffixes. This field may be sent when writing allocations back to the server but will be ignored; this preserves symmetry between read and write representations.

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
/allocations/{consumer_uuid}

Delete allocations

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.

GET
/resource_providers/{uuid}/allocations

List resource provider allocations

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.

GET
/usages

List usages

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, A-Z, and _ describing the consumer type by which to filter usage results. For example, to retrieve only usage information for ‘INSTANCE’ type consumers a parameter of consumer_type=INSTANCE should be provided. The all query parameter may be specified to group all results under one key, all. The unknown query parameter may be specified to group all results under one key, unknown.

New in version 1.38

Response (microversions 1.38 - )

Name

In

Type

Description

usages.consumer_type

body

string

A string that consists of numbers, A-Z, and _ describing what kind of consumer is creating, or has created, allocations using a quantity of inventory. The string is determined by the client when writing allocations and it is up to the client to ensure correct choices amongst collaborating services. For example, the compute service may choose to type some consumers ‘INSTANCE’ and others ‘MIGRATION’.

New in version 1.38

usages.consumer_type.consumer_count

body

integer

The number of consumers of a particular consumer_type.

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.

GET
/resource_providers/{uuid}/usages

List resource provider usages

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, "VCPU": 1 means 1 VCPU is used.

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.

GET
/allocation_candidates

List allocation candidates

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 query parameter can be repeated. The trait lists from the repeated parameters are ANDed together. So:

required=T1,!T2&required=T3

means T1 and not T2 and T3.

Also starting from microversion 1.39 the required parameter supports the syntax:

required=in:T1,T2,T3

which means T1 or T2 or T3.

Mixing forbidden traits into an in: prefixed value is not supported and rejected. But mixing a normal trait list and an in: prefixed trait list in two query params within the same request is supported. So:

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 in: followed by a comma-separated list of strings representing aggregate uuids. The resource providers in the allocation request in the response must directly or via the root provider be associated with the aggregate or aggregates identified by uuid:

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 query string parameters is possible. Multiple member_of parameters will result in filtering providers that are directly or via root provider associated with aggregates listed in all of the member_of query string values. For example, to get the providers that are associated with aggregate A as well as associated with any of aggregates B or C, the user could issue the following query:

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 query string parameter. Forbidden aggregates are prefixed with a !. This negative expression can also be used in multiple member_of parameters:

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 ! on the values within in:, but we support !in:. Both of the following two example queries return candidate resource providers that are NOT in AGGA, AGGB, or AGGC:

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 allocation_requests and provider_summaries, while:

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 resourcesN, where N represents a unique suffix. The value format is the same as for the (not granular) resources parameter, but the resources specified in a resourcesN parameter will always be satisfied by a single provider.

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, a-z, A-Z, -, and _.

Separate groupings - with or without a suffix - may or may not be satisfied by the same provider depending on the value of the group_policy parameter.

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 !) not have:

required42=HW_CPU_X86_AVX,HW_CPU_X86_SSE,!HW_CPU_X86_AVX2

The parameter key is requiredN, where N represents a suffix corresponding with a resourcesN parameter.

The value format is the same as for the (not granular) required parameter; but all of the resources and traits specified in a suffixed grouping will always be satisfied by the same resource provider. Separate groupings - with or without a suffix - may or may not be satisfied by the same provider, depending on the value of the group_policy parameter.

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, a-z, A-Z, -, and _.

It is an error to specify a requiredN parameter without a corresponding resourcesN parameter with the same suffix.

Starting from microversion 1.39 the granular requiredN query parameter gained support for the in: syntax as well as the repetition of the parameter. So:

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 in: followed by a comma-separated list of strings representing aggregate uuids. The returned resource providers must directly be associated with at least one of the aggregates identified by uuid. Starting from microversion 1.32 specifying forbidden aggregates is supported. Forbidden aggregates are expressed with a ! prefix; or the prefix !in: followed by a comma-separated list of strings representing aggregate uuids. The returned resource providers must not directly be associated with any of the aggregates identified by uuid. The parameter key is member_ofN, where N represents a suffix corresponding with a resourcesN parameter. The value format is the same as for the (not granular) member_of parameter; but all of the resources and traits specified in a granular grouping will always be satisfied by the same resource provider. 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, a-z, A-Z, -, and _. Separate groupings - with or without a suffix - may or may not be satisfied by the same provider, depending on the value of the group_policy parameter. It is an error to specify a member_ofN parameter without a corresponding resourcesN parameter with the same suffix.

New in version 1.25

in_treeN (Optional)

query

string

A string representing a resource provider uuid. The parameter key is in_treeN, where N represents a suffix corresponding with a resourcesN parameter. When supplied, it will filter the returned allocation candidates for that suffixed group to only those resource providers that are in the same tree with the given resource provider. 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, a-z, A-Z, -, and _.

New in version 1.31

group_policy (Optional)

query

string

When more than one resourcesN query parameter is supplied, group_policy is required to indicate how the groups should interact. With group_policy=none, separate groupings - with or without a suffix - may or may not be satisfied by the same provider. With group_policy=isolate, suffixed groups are guaranteed to be satisfied by different providers - though there may still be overlap with the suffixless group.

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 same_subtree query parameter can be repeated and each repeat group is treated independently.

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 allocation_requests, of dictionaries of inventory/capacity information. The list of traits the resource provider has associated with it is included in version 1.17 and above. Starting from microversion 1.29, the provider summaries include all resource providers in the same resource provider tree that has one or more resource providers included in the allocation_requests.

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 [a-zA-Z0-9_-]+ are valid suffixes. This field may be sent when writing allocations back to the server but will be ignored; this preserves symmetry between read and write representations.

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 allocation_requests, of dictionaries of inventory/capacity information.

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.

POST
/reshaper

Reshaper

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 dictionary within a consumer dictionary indicates that all allocations for that consumer should be deleted.

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 [a-zA-Z0-9_-]+ are valid suffixes. This field may be sent when writing allocations back to the server but will be ignored; this preserves symmetry between read and write representations.

New in version 1.34

allocations.{consumer_uuid}.consumer_generation

body

integer

The generation of the consumer. Should be set to null when indicating that the caller expects the consumer does not yet exist.

allocations.{consumer_uuid}.consumer_type

body

string

A string that consists of numbers, A-Z, and _ describing what kind of consumer is creating, or has created, allocations using a quantity of inventory. The string is determined by the client when writing allocations and it is up to the client to ensure correct choices amongst collaborating services. For example, the compute service may choose to type some consumers ‘INSTANCE’ and others ‘MIGRATION’.

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.