Spec: support mixing required traits with any traits

This is a reproposal of a nova spec to placement, originally
proposed in I9695f0cb2c0263cd0e8ca552d3a9dd720690e466.

Previously-Approved: Stein
Story: 2005345
Task: 30295
Change-Id: Ibada21dcabbb3824c8d9fdb7584d45abf844be68

doc/source/specs/yoga/approved/2005345-placement-mixing-required-traits-with-any-traits.rst

@@ -0,0 +1,204 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==============================================
+Support mixing required traits with any traits
+==============================================
+
+https://storyboard.openstack.org/#!/story/2005345
+
+The `any-traits-in-allocation-candidates-query`_ spec proposed to allow
+querying traits in the form of ``required=in:TRAIT1,TRAIT2``. This spec goes
+one step further and proposes to allow repeating the ``required`` query
+parameter to support mixing both  ``required=TRAIT1,TRAIT2,!TRAIT3`` and
+``required=in:TRAIT1,TRAIT2`` format in a single query. This is needed for
+Neutron to be able to express that a port needs a resource provider having
+a specific ``vnic_type`` trait but also having one of the physnet traits the
+port's network maps to.
+
+For example::
+
+  GET /allocation_candidates?required1=CUSTOM_VNIC_TYPE_DIRECT&
+                             required1=in:CUSTOM_PHYSNET_FOO,CUSTOM_PHYSNET_BAR
+                             ...
+
+requests a networking device RP in the candidates that supports the ``direct``
+``vnic_type`` and is connected either to ``physnet_foo`` or ``physnet_bar`` or
+both.
+
+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 as
+well as matching another specific trait in a single 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. But at the same
+time Neutron wants to express that the same RP has a specific vnic_type trait
+as well.
+
+Proposed change
+===============
+
+Extend the ``GET /allocation_candidates`` and ``GET /resource_providers``
+requests to allow repeating the ``required`` and ``required<N>`` query param
+to support both the ``required=TRAIT1,TRAIT2,!TRAIT3`` and
+``required=in:TRAIT1,TRAIT2`` syntax in a single query.
+
+Alternatives
+------------
+
+None
+
+Data model impact
+-----------------
+
+None
+
+REST API impact
+---------------
+
+In a new microversion the ``GET /allocation_candidates`` and  the
+``GET /resource_providers`` query should allow repeating the ``required``
+query parameter more than once while supporting both normal and any trait
+syntax in the same query.
+
+The ``GET /allocation_candidates`` query having
+``required=CUSTOM_VNIC_TYPE_NORMAL&
+required=in:CUSTOM_PHYSNET1,CUSTOM_PHYSNET2`` parameters should result in
+allocation candidates where each allocation candidate has the traits
+``CUSTOM_VNIC_TYPE_NORMAL`` and either ``CUSTOM_PHYSNET1`` or
+``CUSTOM_PHYSNET2`` (or both).
+
+The ``GET /resource_providers`` query having
+``required=CUSTOM_VNIC_TYPE_NORMAL&
+required=in:CUSTOM_PHYSNET1,CUSTOM_PHYSNET2`` parameters should result in
+resource providers where each resource provider has the traits
+``CUSTOM_VNIC_TYPE_NORMAL`` and either ``CUSTOM_PHYSNET1`` or
+``CUSTOM_PHYSNET2`` (or both).
+
+The response body of the ``GET /allocation_candidates`` and
+``GET /resource_providers`` query are unchanged.
+
+Note the following two queries express exactly the same requirements::
+
+  ?required=in:A,B,C
+  &required=X
+  &required=Y
+  &required=Z
+
+  ?required=in:A,B,C
+  &required=X,Y,Z
+
+
+.. note::
+    To ease the implementation we might decide to implement this API change in
+    the same microversion as `any-traits-in-allocation-candidates-query`_
+    implemented in.
+
+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. This means the the CLI should support providing
+the ``--required`` parameter more than once supporting both normal and any
+trait syntax.
+
+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
+  more than one set of required traits
+* Extend the Placement REST API with a new microversion that supports repeating
+  the ``required`` query param
+* Extend the osc-placement client plugin to support the new microversion
+
+Dependencies
+============
+
+* The `any-traits-in-allocation-candidates-query`_ spec
+
+..  _`any-traits-in-allocation-candidates-query`: https://review.openstack.org/649992
+
+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
+==========
+
+None
+
+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