Placement API

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.

Versions

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.

Response Example

{
    "versions" : [
        {
            "min_version" : "1.0",
            "id" : "v1.0",
            "max_version" : "1.2"
        }
    ]
}

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

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
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 to serve:

resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
member_of (Optional) query string A comma-separated list of strings representing aggregate uuids. The returned resource providers must be associated with at least one of the aggregates identified by uuid.
uuid (Optional) query string The uuid of a resource provider.
name (Optional) query string The name of a resource provider to filter the list.

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

Trait relationship link is available starting from version 1.6.

name body string The name of one resource provider.

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"
        }
      ],
      "name": "vgr.localdomain"
    },
    {
      "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"
        }
      ],
      "name": "pony1"
    }
  ]
}
POST
/resource_providers

Create resource provider

Create a new resource provider.

Normal Response Codes: 201

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.

Request example

{
    "name": "NFS Share",
    "uuid": "7d2590ae-fb85-4080-9306-058b4c915e3f"
}

Response

No body content is returned on a successful POST.

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

Trait relationship link is available starting from version 1.6.

name body string The name of one resource provider.

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"
        }
    ],
    "name": "Ceph Storage Pool",
    "uuid": "3b4005be-d64b-456f-ba36-0ffd02718868"
}
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.

Request example

 {"name": "Shared storage"}

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

Trait relationship link is available starting from version 1.6.

name body string The name of one resource provider.

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"
        }
    ],
    "name": "Shared storage",
    "uuid": "33f26ae0-dbf2-485b-a24a-244d8280e29f"
}
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.

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.

Normal Response Codes: 201

Error response codes: badRequest(400), 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 body string The name of one resource class.

Request example

{"name": "CUSTOM_FPGA"}

Response

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

Response

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 body string The name of one resource class.

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: itemNotFound(404), conflict(409)

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.
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.
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.
total body integer The actual amount of the resource that the provider can accommodate.

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

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.
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.
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.
total body integer The actual amount of the resource that the provider can accommodate.

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.

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. Placement aggregates have no concept of an availability zone.

Note

Aggregates API requests are availiable 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)

Request

Name In Type Description
uuid path string The uuid of a resource provider.

Response

Name In Type Description
aggregates body array A list of aggregate uuids.

Response Example

{
    "aggregates": [
        "42896e0d-205d-4fe3-bd1e-100924931787",
        "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
    ]
}
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)

Request

Name In Type Description
uuid path string The uuid of a resource provider.
aggregates body array A list of aggregate uuids.

Request example

[
    "42896e0d-205d-4fe3-bd1e-100924931787",
    "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
]

Response

Name In Type Description
aggregates body array A list of aggregate uuids.

Response Example

{
    "aggregates": [
        "42896e0d-205d-4fe3-bd1e-100924931787",
        "5e08ea53-c4c6-448e-9334-ac4953de3cfa"
    ]
}

Traits

Traits are qualitative characteristics of resource providers. The classic example for traits can be requesting disk from different providers: a user may request 80GB 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 availiable 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

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

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.

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

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.

Response Example

{
    "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
            }
        }
    }
}
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 or inventories are updated by another thread while attempting the operation.

Request

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

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

Response

Name In Type Description
usages body object A dictionary of resource records keyed by resource class name.

Response Example

{
    "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 availiable 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.

Normal Response Codes: 200

Error response codes: badRequest(400)

Request

Name In Type Description
resources 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:

resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048

Response

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

{
    "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
                }
            }
        }
    }
}
Creative Commons Attribution 3.0 License

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.