Merge "Spec: support any trait in allocation candidates"

doc/source/specs/yoga/approved/2005346-any-traits-in-allocation_candidates-query.rst

@@ -0,0 +1,197 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+=================================================
+Support any traits in allocation_candidates query
+=================================================
+
+https://storyboard.openstack.org/#!/story/2005346
+
+The ``GET /allocation_candidates`` request in Placement supports the
+``required`` query parameter. If the caller specifies a list of traits in the
+``required`` parameter then placement will limit the returned allocation
+candidates to those RP trees that fulfill *every* traits in that list. To
+support minimum bandwidth guarantees in Neutron + Nova we need to be able to
+query allocation candidates that fulfill *at least one* trait from a list of
+traits specified in the query. This is required for the case when a Neutron
+network maps to more than one physnets but the port's bandwidth request can be
+fulfilled from any physnet the port's network maps to.
+
+Problem description
+===================
+
+Neutron through Nova needs to be able to query Placement for allocation
+candidates that are matching to *at least one* trait from the list of traits
+provided in the query.
+
+Use Cases
+---------
+
+Neutron wants to use this any(traits) query to express that a port's bandwidth
+resource request needs to be fulfilled by a Network device RP that is connected
+to one of the physnets the network of the given port is connected to. With
+Neutron's multiprovider network extension a single Neutron network can consist
+of multiple network segments connected to different physnets.
+
+Proposed change
+===============
+
+Extend the ``GET /allocation_candidates`` and ``GET /resource_providers``
+requests with a new ``required=in:TRAIT1,TRAIT2`` query parameter syntax and
+change the placement implementation to support this new syntax.
+
+The `granular-resource-requests`_ spec proposes support for multiple request
+groups in the Placement query identified by a positive integer postfix in the
+``required`` query param. The new ``in:TRAIT1,TRAIT2`` syntax is applicable to
+the ``required<N>`` query params as well.
+
+..  _`granular-resource-requests`: https://specs.openstack.org/openstack/nova-specs/specs/rocky/approved/granular-resource-requests.html
+
+Alternatives
+------------
+
+During the train review Sean suggested to use ``any``, ``all``, ``none``
+instead of using the currently proposed ``in:`` syntax. However to keep the API
+consistent we decided to continue using ``in:`` for traits as it is already
+used for aggregates. Still we think that ``any``, ``all``, ``none`` would be a
+better syntax but that requires a separate effort changing the existing query
+syntax as well.
+
+Data model impact
+-----------------
+
+None
+
+REST API impact
+---------------
+Today the ``GET /allocation_candidates`` and ``GET /resource_providers`` query
+support the ``required`` query param in the form of
+``required=TRAIT1,TRAIT2,!TRAIT3``. This spec proposes to implement a new
+microversion to allow the format of ``required=in:TRAIT1,TRAIT2`` as well
+as the old format.
+
+Each resource provider returned from a request having
+``required=in:TRAIT1,TRAIT2`` should have *at least* one matching trait from
+TRAIT1 and TRAIT2.
+
+``required=in:TRAIT1,TRAIT2`` used in a ``GET /allocation_candidates`` query
+means that the union of all the traits across all the providers in every
+allocation candidate must contain at least one of T1, T2.
+
+``requiredX=in:TRAIT1,TRAIT2`` used in a ``GET /allocation_candidates`` query
+means that the resource provider that satisfies the requirement of the granular
+request group ``X`` must also has at least one of T1, T2.
+
+The response body of the ``GET /allocation_candidates`` and
+``GET /resource_providers`` query are unchanged.
+
+A separate subsequent spec will propose to support repeating the ``required``
+query param more than once to allow mixing the two formats.
+
+Note that mixing required and forbidden trait requirements in the same
+``required=in:`` query param, like ``required=in:TRAIT1,!TRAIT2`` will not be
+supported and will result a HTTP 400 response.
+
+Security impact
+---------------
+
+None
+
+Notifications impact
+--------------------
+
+None
+
+Other end user impact
+---------------------
+
+The osc-placement client plugin needs to be updated to support the new
+Placement API microversion. That plugin currently support the --required CLI
+parameter accepting a list of traits. So this patch propose to extend that
+parameter to accept in:TRAIT1,TRAIT2 format.
+
+Performance Impact
+------------------
+
+None
+
+Other deployer impact
+---------------------
+
+None
+
+Developer impact
+----------------
+
+None
+
+Upgrade impact
+--------------
+
+None
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  balazs-gibizer
+
+Work Items
+----------
+
+* Extend the resource provider and allocation candidate DB query to support the
+  new type of query
+* Extend the Placement REST API with a new microversion that supports the any
+  trait syntax
+* Extend the osc-placement client plugin to support the new microversion
+
+Dependencies
+============
+
+* the osc-placement client plugin can only be extended with the new
+  microversion support if every older microversion is already supported which
+  is not the case today.
+
+Testing
+=======
+
+Both new gabbi and functional tests needs to be written for the Placement API
+change. Also the osc-placement client plugin will need additional functional
+test coverage.
+
+Documentation Impact
+====================
+
+The Placement API reference needs to be updated.
+
+References
+==========
+
+* osc-placement `review`_ series adding support for latest Placement
+  microversions
+
+..  _`review`: https://review.openstack.org/#/c/548326
+
+
+History
+=======
+
+.. list-table:: Revisions
+   :header-rows: 1
+
+   * - Release Name
+     - Description
+   * - Rocky
+     - Introduced
+   * - Stein
+     - Reproposed, approved but not implemented
+   * - Train
+     - Reproposed but not approved due to lack of focus
+   * - Yoga
+     - Reproposed