From 11644979641eb98e336e0e1a40f43301ec5bcb83 Mon Sep 17 00:00:00 2001 From: Balazs Gibizer Date: Thu, 20 Jan 2022 14:18:51 +0100 Subject: [PATCH] Clarify trait filtering in the API doc Based on the spec[1], the user doc[2] and the implementation[3][4] the original intention of trait filtering during allocation candidate query is that the required traits in the unnamed group needs to be provided by the resource providers contributing resources to the candidate. So traits on RPs which are in the tree of the candidate but not providing resource to the candidate should be ignored. The current API doc is not clear on this and can be misunderstood. So this patch clarifies that doc. [1] https://docs.openstack.org/placement/latest/specs/train/implemented/2005575-nested-magic-1.html [2] https://docs.openstack.org/placement/latest/user/provider-tree.html#filtering-by-traits [3] https://github.com/openstack/placement/blob/d48d22ff24535eb5ae947d60fd87a9afb2e7b45d/placement/objects/research_context.py#L745 [4] https://github.com/openstack/placement/blob/d48d22ff24535eb5ae947d60fd87a9afb2e7b45d/placement/tests/functional/db/test_allocation_candidates.py#L817-L827 Story: #2009795 Task: #44334 Change-Id: Idc367df609dc8d4874fc329f2317c582b9e06a4d --- api-ref/source/parameters.yaml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 21519bf2c..6d8c5afa3 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -270,9 +270,10 @@ required_traits_unnumbered: have capacity for all requested resources and the set of those resource providers will *collectively* contain all of the required traits. These traits may be satisfied by any provider in the same non-sharing tree or - associated via aggregate. **Starting from microversion 1.22** traits which - are forbidden from any resource provider may be expressed by prefixing a - trait with a ``!``. + associated via aggregate as far as that provider also contributes resource + to the request. **Starting from microversion 1.22** traits which + are forbidden from any resource provider contributing resources to the + request may be expressed by prefixing a trait with a ``!``. **Starting from microversion 1.39** the ``required`` query parameter can be repeated. The trait lists from the repeated parameters are ANDed together.