Placement¶

Version:

1.39

This is a reference for the OpenStack Placement API. To learn more about OpenStack Placement API concepts, please refer to the Placement Introduction.

version¶

GET

List Versions

Fetch information about all known major versions of the placement API, including information about the minimum and maximum microversions.

Normal Response Codes: 200

Responses¶

200¶

404¶

Error

resource_classes¶

GET

/resource_classes

List resource classes

Return a list of all resource classes.

Normal Response Codes: 200

Responses¶

200¶

404¶

Error

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¶

Description

Schema

{
  "type": "object",
  "description": "Request of the resource_classes:post operation",
  "x-openstack": {
    "action-name": "decorated_func"
  }
}

Responses¶

201¶

404¶

Error

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)

Responses¶

200¶

404¶

Error

PUT

/resource_classes/{name}

Update resource class

Create or validate the existence of single resource class identified by {name}.

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¶

Description

Name

Location

Type

Description

name

path

string

name parameter for /resource_classes/{name} API

Name	Location	Type	Description
name	path	string	name parameter for /resource_classes/{name} API

Schema

{
  "type": "object",
  "description": "Request of the resource_classes/name:put operation",
  "x-openstack": {
    "action-name": "decorated_func"
  }
}

Responses¶

200¶

404¶

Error

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.

Responses¶

204¶

404¶

Error

resource_providers¶

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.

Responses¶

200¶

404¶

Error

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¶

Description

Schema

{
  "type": "object",
  "description": "Request of the resource_providers:post operation",
  "x-openstack": {
    "action-name": "create_resource_provider"
  }
}

Responses¶

201¶

404¶

Error

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)

Responses¶

200¶

404¶

Error

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¶

Description

Name

Location

Type

Description

uuid

path

string

uuid parameter for /resource_providers/{uuid}/traits API

Schema

{
  "type": "object",
  "description": "Request of the resource_providers/uuid:put operation",
  "x-openstack": {
    "action-name": "update_resource_provider"
  }
}

Responses¶

200¶

404¶

Error

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.

Responses¶

204¶

404¶

Error

GET

/resource_providers/{uuid}/inventories

List resource provider inventories

Normal Response Codes: 200

Error response codes: itemNotFound(404)

Responses¶

200¶

404¶

Error

POST

/resource_providers/{uuid}/inventories

POST to create one inventory.

On success return a 201 response, a location header pointing to the newly created inventory and an application/json representation of the inventory.

Request¶

Description

Name

Location

Type

Description

uuid

path

string

uuid parameter for /resource_providers/{uuid}/traits API

Schema

{
  "type": "object",
  "description": "Request of the resource_providers/uuid/inventories:post operation",
  "x-openstack": {
    "action-name": "create_inventory"
  }
}

Responses¶

201¶

404¶

Error

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¶

Description

Name

Location

Type

Description

uuid

path

string

uuid parameter for /resource_providers/{uuid}/traits API

Schema

{
  "type": "object",
  "description": "Request of the resource_providers/uuid/inventories:put operation",
  "x-openstack": {
    "action-name": "set_inventories"
  }
}

Responses¶

200¶

404¶

Error

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.

Normal Response Codes: 204

Error response codes: itemNotFound(404), conflict(409)

Responses¶

204¶

404¶

Error

GET

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

Show resource provider inventory

Normal Response Codes: 200

Error response codes: itemNotFound(404)

Responses¶

200¶

404¶

Error

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¶

Description

Name	Location	Type	Description
uuid	path	string	uuid parameter for /resource_providers/{uuid}/traits API
resource_class	path	string	resource_class parameter for /resource_providers/{uuid}/inventories/{resource_class} API

Schema

{
  "type": "object",
  "description": "Request of the resource_providers/uuid/inventories/resource_class:put operation",
  "x-openstack": {
    "action-name": "update_inventory"
  }
}

Responses¶

200¶

404¶

Error

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)

Responses¶

204¶

404¶

Error

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)

Responses¶

200¶

404¶

Error

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

Responses¶

200¶

404¶

Error

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¶

Description

Name

Location

Type

Description

uuid

path

string

uuid parameter for /resource_providers/{uuid}/traits API

Schema

{
  "type": "object",
  "description": "Request of the resource_providers/uuid/aggregates:put operation",
  "x-openstack": {
    "action-name": "decorated_func"
  }
}

Responses¶

200¶

404¶

Error

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)

Responses¶

200¶

404¶

Error

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)

Responses¶

200¶

404¶

Error

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)

Request¶

Description

Name

Location

Type

Description

uuid

path

string

uuid parameter for /resource_providers/{uuid}/traits API

Schema

{
  "type": "object",
  "description": "Request of the resource_providers/uuid/traits:put operation",
  "x-openstack": {
    "action-name": "decorated_func"
  }
}

Responses¶

200¶

404¶

Error

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)

Responses¶

204¶

404¶

Error

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)

Request¶

Description

Schema

{
  "type": "object",
  "description": "Request of the allocations:post operation",
  "x-openstack": {
    "action-name": "decorated_func"
  }
}

Responses¶

201¶

404¶

Error

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.

Normal Response Codes: 200

Responses¶

200¶

404¶

Error

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)

Request¶

Description

Name

Location

Type

Description

consumer_uuid

path

string

consumer_uuid parameter for /allocations/{consumer_uuid} API

Name	Location	Type	Description
consumer_uuid	path	string	consumer_uuid parameter for /allocations/{consumer_uuid} API

Schema

{
  "type": "object",
  "description": "Request of the allocations/consumer_uuid:put operation",
  "x-openstack": {
    "action-name": "decorated_func"
  }
}

Responses¶

200¶

404¶

Error

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)

Responses¶

204¶

404¶

Error

allocation_candidates¶

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)

Responses¶

200¶

404¶

Error

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.

GET

/traits

List traits

Return a list of valid trait strings according to parameters specified.

Normal Response Codes: 200

Responses¶

200¶

404¶

Error

GET

/traits/{name}

Show traits

Check if a trait name exists in this cloud.

Normal Response Codes: 204

Error response codes: itemNotFound(404)

Responses¶

200¶

404¶

Error

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)

Request¶

Description

Name

Location

Type

Description

name

path

string

name parameter for /traits/{name} API

Name	Location	Type	Description
name	path	string	name parameter for /traits/{name} API

Schema

{
  "type": "object",
  "description": "Request of the traits/name:put operation",
  "x-openstack": {
    "action-name": "decorated_func"
  }
}

Responses¶

200¶

404¶

Error

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)

Responses¶

204¶

404¶

Error

usages¶

Represent the consumption of resources for a project and user.

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)

Responses¶

200¶

404¶

Error

reshaper¶

Note

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.

Normal Response Codes: 204

Error Response Codes: badRequest(400), conflict(409)

Request¶

Description

Schema

{
  "type": "object",
  "description": "Request of the reshaper:post operation",
  "x-openstack": {
    "action-name": "decorated_func"
  }
}

Responses¶

201¶

404¶

Error