Filter Resource Provider List for Traits

Partly for continued parity with GET /allocation_candidates and partly because we need it for a bug fix, this spec proposes to add the ?required=<trait_list> queryparam filter to the GET /resource_providers placement API.

Problem description

Use Cases

As a Nova developer consuming the placement API, I want to be able to retrieve all and only the sharing providers (those with the MISC_SHARES_VIA_AGGREGATE trait) associated via aggregate with my compute node.

Proposed change

In a new microversion, allow the GET /resource_providers API to accept an additional query parameter, required, which accepts a comma-separated list of string trait names. When specified, the API results will be filtered to include only resource providers marked with all the specified traits.


As with the resources query parameter, the required semantic is different for GET /resource_providers than for GET /allocation_candidates. The latter deals with groups of providers where each group must collectively satisfy the filters; whereas the former applies the filters to each provider.

This is in addition to (logical AND) any filtering based on other query parameters.

Trait names which are empty, do not exist in the Trait database, or are otherwise invalid will result in a 400 error.


For the specific example in Use Cases, first retrieve the full list of resource providers associated via aggregate with my compute node; then iterate through each of those, invoking the GET /resource_providers/{uuid}/traits API, looking for the MISC_SHARES_VIA_AGGREGATE trait in the result, and keeping only the providers where that trait is present. This is what we may need to backport to fix the bug which prompted this spec.

Data model impact


REST API impact

See Proposed change. The parameter is optional. It does not result in the addition of any new response codes.

Security impact


Notifications impact


Other end user impact


Performance Impact

This should result in a performance improvement by reducing the number of placement API calls from N+1 to 1, where N is the number of providers that would be returned by the initial call to GET /resource_providers in the absence of the new query parameter. It is expected that the additional processing on the placement server will be negligible compared to the overhead of these additional API calls. (And that processing would have been needed on the client side anyway.)

Other deployer impact


Developer impact

Developers have a convenient way to get trait-filtered lists of resource providers in a single API call.

Upgrade impact

Until their minimum required placement microversion is at least the microversion produced by this spec, clients implementing this feature will need to invoke fallback code such as described in Alternatives when 406 is received.



Primary assignee:


Work Items

  • Create JSON Schema for a new microversion of GET /resource_providers.

  • Add a new micro-versioned handler in nova.api.openstack.placement.handlers.resource_provider.list_resource_providers to accept the new required parameter and add it to filters.

  • Adjust the ResourceProviderList.get_all_by_filters method to additionally filter on the specified trait names.

  • Update the placement-api-ref.




Gabbits will be added to validate the query parameter.

Documentation Impact




Release Name