Back to guides list

4.4. Listing resource providers

GET /resource_providers

List resource providers.

Source: https://docs.openstack.org/api-ref/placement/?expanded=update-resource-provider-traits-detail,list-resource-provider-traits-detail,update-traits-detail#list-resource-providers

4.4.1. Request

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

New in version 1.18

4.4.1.1. Example

curl -ks -H 'Content-Type: application/json' -H 'OpenStack-API-Version: placement 1.32' -H 'X-Auth-Token: gAAAAA<...>' \
https://<node_IP_addr>:8780/resource_providers

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

4.4.2.1. Status codes

4.4.2.1.1. Success

Code Reason
200 - OK Request was successful.

4.4.2.1.2. Error

Code Reason
400 - Bad Request Some content in the request was invalid.

4.4.2.2. Example

{
  "resource_providers": [
    {
      "uuid": "ff40fdad-6522-4565-82d5-3c9f2f18f129",
      "parent_provider_uuid": null,
      "generation": 7905,
      "links": [
        {
          "href": "/resource_providers/ff40fdad-6522-4565-82d5-3c9f2f18f129",
          "rel": "self"
        },
        {
          "href": "/resource_providers/ff40fdad-6522-4565-82d5-3c9f2f18f129/inventories",
          "rel": "inventories"
        },
        {
          "href": "/resource_providers/ff40fdad-6522-4565-82d5-3c9f2f18f129/usages",
          "rel": "usages"
        },
        {
          "href": "/resource_providers/ff40fdad-6522-4565-82d5-3c9f2f18f129/aggregates",
          "rel": "aggregates"
        },
        {
          "href": "/resource_providers/ff40fdad-6522-4565-82d5-3c9f2f18f129/traits",
          "rel": "traits"
        },
        {
          "href": "/resource_providers/ff40fdad-6522-4565-82d5-3c9f2f18f129/allocations",
          "rel": "allocations"
        }
      ],
      "root_provider_uuid": "ff40fdad-6522-4565-82d5-3c9f2f18f129",
      "name": "node2.vstoragedomain"
    },
    {
      "uuid": "acf24470-ff88-4208-88ce-e040c0bb4c91",
      "parent_provider_uuid": null,
      "generation": 7930,
      "links": [
        {
          "href": "/resource_providers/acf24470-ff88-4208-88ce-e040c0bb4c91",
          "rel": "self"
        },
        {
          "href": "/resource_providers/acf24470-ff88-4208-88ce-e040c0bb4c91/inventories",
          "rel": "inventories"
        },
        {
          "href": "/resource_providers/acf24470-ff88-4208-88ce-e040c0bb4c91/usages",
          "rel": "usages"
        },
        {
          "href": "/resource_providers/acf24470-ff88-4208-88ce-e040c0bb4c91/aggregates",
          "rel": "aggregates"
        },
        {
          "href": "/resource_providers/acf24470-ff88-4208-88ce-e040c0bb4c91/traits",
          "rel": "traits"
        },
        {
          "href": "/resource_providers/acf24470-ff88-4208-88ce-e040c0bb4c91/allocations",
          "rel": "allocations"
        }
      ],
      "root_provider_uuid": "acf24470-ff88-4208-88ce-e040c0bb4c91",
      "name": "node3.vstoragedomain"
    },
    {
      "uuid": "34233b75-4022-4539-9e3f-305e9f9f1f18",
      "parent_provider_uuid": null,
      "generation": 546,
      "links": [
        {
          "href": "/resource_providers/34233b75-4022-4539-9e3f-305e9f9f1f18",
          "rel": "self"
        },
        {
          "href": "/resource_providers/34233b75-4022-4539-9e3f-305e9f9f1f18/inventories",
          "rel": "inventories"
        },
        {
          "href": "/resource_providers/34233b75-4022-4539-9e3f-305e9f9f1f18/usages",
          "rel": "usages"
        },
        {
          "href": "/resource_providers/34233b75-4022-4539-9e3f-305e9f9f1f18/aggregates",
          "rel": "aggregates"
        },
        {
          "href": "/resource_providers/34233b75-4022-4539-9e3f-305e9f9f1f18/traits",
          "rel": "traits"
        },
        {
          "href": "/resource_providers/34233b75-4022-4539-9e3f-305e9f9f1f18/allocations",
          "rel": "allocations"
        }
      ],
      "root_provider_uuid": "34233b75-4022-4539-9e3f-305e9f9f1f18",
      "name": "node1.vstoragedomain"
    }
  ]
}
Version 5.0.0 — Feb 01, 2022
Print