156 lines
5.3 KiB
ReStructuredText
156 lines
5.3 KiB
ReStructuredText
..
|
|
This work is licensed under a Creative Commons Attribution 3.0 Unported
|
|
License.
|
|
|
|
http://creativecommons.org/licenses/by/3.0/legalcode
|
|
|
|
========================================
|
|
Filter Resource Provider List for Traits
|
|
========================================
|
|
https://blueprints.launchpad.net/nova/+spec/traits-on-list-resource-providers
|
|
|
|
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.
|
|
|
|
.. note:: 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.
|
|
|
|
Alternatives
|
|
------------
|
|
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
|
|
-----------------
|
|
None
|
|
|
|
REST API impact
|
|
---------------
|
|
See `Proposed change`_. The parameter is optional. It does not result in the
|
|
addition of any new response codes.
|
|
|
|
Security impact
|
|
---------------
|
|
None
|
|
|
|
Notifications impact
|
|
--------------------
|
|
None
|
|
|
|
Other end user impact
|
|
---------------------
|
|
None
|
|
|
|
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
|
|
---------------------
|
|
None
|
|
|
|
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.
|
|
|
|
Implementation
|
|
==============
|
|
Assignee(s)
|
|
-----------
|
|
Primary assignee:
|
|
efried
|
|
|
|
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.
|
|
|
|
Dependencies
|
|
============
|
|
None
|
|
|
|
Testing
|
|
=======
|
|
Gabbits will be added to validate the query parameter.
|
|
|
|
Documentation Impact
|
|
====================
|
|
* Update the placement API reference section for `GET /resource_providers`_.
|
|
* Update the `REST API Version History`_.
|
|
|
|
References
|
|
==========
|
|
* The bug_ that prompted this change.
|
|
* The fix_ required if this API change is not implemented.
|
|
* The `GET /allocation_candidates`_ API documentation.
|
|
* The `GET /resource_providers`_ API documentation.
|
|
* The `GET /resource_providers/{uuid}/traits`_ API documentation.
|
|
* The placement `REST API Version History`_ documentation.
|
|
|
|
.. _bug: https://bugs.launchpad.net/nova/+bug/1750084
|
|
.. _fix: https://review.openstack.org/#/c/545494/1/nova/scheduler/client/report.py@485
|
|
.. _GET /allocation_candidates: https://developer.openstack.org/api-ref/placement/#list-allocation-candidates
|
|
.. _GET /resource_providers: https://developer.openstack.org/api-ref/placement/#list-resource-providers
|
|
.. _GET /resource_providers/{uuid}/traits: https://developer.openstack.org/api-ref/placement/#list-resource-provider-traits
|
|
.. _REST API Version History: https://docs.openstack.org/nova/latest/user/placement.html#rest-api-version-history
|
|
|
|
History
|
|
=======
|
|
.. list-table:: Revisions
|
|
:header-rows: 1
|
|
|
|
* - Release Name
|
|
- Description
|
|
* - Rocky
|
|
- Introduced
|