The placement project has published the API reference
in its own repository and the related jobs for the nova project
has been removed since Ia4680f24d78af1260f2f0106a458b78a079c1287.
So remove the files and definitions related to
the placement API reference in the nova repository.
Change-Id: Ia43b958a28e7e763e7ecb29e06f8d21d2b9a850f
/reshaper provides a way to atomically modify some allocations and
inventory in a single transaction, allowing operations like migrating
some inventory from a parent provider to a new child.
A fair amount of code is reused from handler/inventory.py, some
refactoring is in order before things get too far with that.
In handler/allocation.py some code is extracted to its own methods
so it can be reused from reshaper.py.
This is done as microversion 1.30.
A suite of gabbi tests is provided which attempt to cover various
failures including schema violations, generation conflicts, and
data conflicts.
api-ref, release notes and rest history are updated
Change-Id: I5b33ac3572bc3789878174ffc86ca42ae8035cfa
Partially-Implements: blueprint reshape-provider-tree
Mention that if any nonexistent aggregate uuids are provided, those
aggregates will be created automatically first during the update call.
I think this is a good addition since in fact I was much confused how
the aggregates can be created in the first place when playing with
the placement APIs.
Change-Id: I2f86715a21784eb974b73fc3edc74eedd73ad48b
Add description for nested resource providers
in allocation candidates, Placement API microversion 1.29
in the Placement API reference.
Change-Id: I22c2068ae860c1ef2cbdb0801e85a40acc2a097a
Implements: blueprint nested-resource-providers-allocation-candidates
Due to a regression in I8624e194fe0173531c5aa2119c903e3c68b8c6cd, the
min_version on the parent_provider_uuid response parameter was missing
and is added back here. For sanity reasons, the variables are renamed
and substitution anchor usage is dropped.
To recap the microversions:
1.14
----
parent_provider_uuid and root_provider_uuid were added to the
responses for:
* GET /resource_providers (list)
* GET /resource_providers/{uuid} (show)
* PUT /resource_providers/{uuid} (update)
parent_provider_uuid was added to the request for:
* POST /resource_providers (create)
* PUT /resource_providers/{uuid} (update)
1.20
----
We started returning a response body from
POST /resource_providers (create) which included
parent_provider_uuid and root_provider_uuid but the parameters
are not versioned in that case since the entire response is
versioned for 1.20.
Change-Id: I6c9a1072fa2a59e408472f1a4b52b3a8c6a9b343
Closes-Bug: #1779700
In the "List allocation candidates" API,
the 'traits' parameter is missing.
So add it and update examples.
Change-Id: I4a307759f9e8fa80d003d92142f8e99b2c09c9fe
Partial-Bug: #1778670
Add description for placement microversion 1.26
in the following APIs in the placement API reference.
* PUT /resource_providers/{uuid}/inventories
* PUT /resource_providers/{uuid}/inventories/{resource_class}
Up to microversion 1.25, the value of 'reserved' has to be less
than the value of 'total' in the request.
Starting from microversion 1.26, it has to be less than or
equal to the value of 'total'.
Change-Id: Id1857abf323c9776ab8fe957202848ff7ab3fbd2
Closes-Bug: #1783380
Address various minor issues from
https://review.openstack.org/#/c/565604/
Change-Id: I69df4c8d8c4b8813f78aeeb46f7b788d36238d35
Blueprint: add-consumer-generation
This patch adds new placement API microversion for handling consumer
generations.
Change-Id: I978fdea51f2d6c2572498ef80640c92ab38afe65
Co-Authored-By: Ed Leafe <ed@leafe.com>
Blueprint: add-consumer-generation
According to the spec [1] the version discovery doc must have a status
and links for each version. For the primary version the status value
should be 'CURRENT'. For placement the version discovery doc and "self"
are the same thing, so the provided "self" href looks redundant, but it
makes keystoneauth1 happy when doing version discovery.
In placement, since there is only one version at the moment, set status
to CURRENT.
Add a gabbi test that verifies the presence of both fields and values.
Without these fields, use of placement with a client that follows the
documented version discovery process will fail to work.
As the version doc is not considered microversioned[2] and in any case
this is making version discovery work where it didn't before, this is
not a candidate for a microversion and can be backported to the
beginning of placement's history if we like.
I've updated the api-ref docs. In the process I made the max
microversion in the sample discovery doc a bit more realistic and
in alignment with these modern times.
[1] http://specs.openstack.org/openstack/api-wg/guidelines/microversion_specification.html#version-discovery
[2] http://eavesdrop.openstack.org/irclogs/%23openstack-sdks/%23openstack-sdks.2018-06-13.log.html#t2018-06-13T13:40:12
Change-Id: Ie602ab1768efbf103563d8f6b9d28965fc81021a
Closes-Bug: #1776668
This just updates the POST/PUT resource providers API reference
for the parent_provider_uuid field to mention it can't be changed
to another parent provider once set.
Change-Id: Ie733517a8b413ec0b54d217d779bb7405e162e28
In a new microversion, the GET /allocation_candidates API now accepts
granular resource request syntax:
?resourcesN=...&requiredN=...&member_ofN=...&group_policy={isolate|none}
Change-Id: I4e99974443aa513fd9f837a6057f67d744caf1b4
blueprint: granular-resource-requests
Adds a new placement API microversion that supports specifying multiple
member_of parameters to the GET /resource_providers and GET
/allocation_candidates API endpoints.
When multiple member_of parameters are found, they are passed down to
the ResourceProviderList.get_by_filters() method as a list. Items in
this list are lists of aggregate UUIDs.
The list of member_of items is evaluated so that resource providers
matching ALL of the member_of constraints are returned.
When a member_of item contains multiple UUIDs, we look up resource
providers that have *any* of those aggregate UUIDs associated with them.
Change-Id: Ib4f1955f06f2159dfb221f3d2bc8ff7bfce71ee2
blueprint: alloc-candidates-member-of
In an earlier patch [0], there were some valid criticisms noted. They
were not critical enough to require holding off on that patch, so they
are being addressed here in a follow-up patch.
[0] I5857e927a830914c96e040936804e322baccc24c
Blueprint: alloc-candidates-member-of
Change-Id: I762dc4a70613056f1bd9ba7bf11c3a4588bdac70
In a new microversion (1.22) expose support for processing
forbidden traits in GET /resource_providers and GET
/allocation_candidates. A forbidden trait is expressed as
part of the required parameter with a "!" prefix:
required=CUSTOM_FAST,!CUSTOM_SLOW
This change uses db and query processing code adjustments
already present in the code but guarded by a flag. If the
currently requested microversion matches 1.22 or beyond
that flag is True, otherwise False.
Reno, api-ref update and api history update are included.
Because this microversion changes the value of an existing
parameter it was unclear how to best express that in the
api-ref. In this case existing parameter references were
annotated.
Partially implements blueprint placement-forbidden-traits
Change-Id: I43e92bc5f97db7a2b09e64c6cb953c07d0561e63
To facilitate opaqueness of resource provider generation internals, we
need to return the (initial) generation when a provider is created. For
consistency with other APIs, we will do this by returning the entire
resource provider record (which includes the generation) from POST
/resource_providers.
Change-Id: I8624e194fe0173531c5aa2119c903e3c68b8c6cd
blueprint: generation-from-create-provider
Placement API microversion 1.19 enhances the payloads for the `GET
/resource_providers/{uuid}/aggregates` response and the `PUT
/resource_providers/{uuid}/aggregates` request and response to be
identical, and to include the ``resource_provider_generation``. As with
other generation-aware APIs, if the ``resource_provider_generation``
specified in the `PUT` request does not match the generation known by
the server, a 409 Conflict error is returned.
Change-Id: I86416e35da1798cdf039b42c9ed7629f0f9c75fc
blueprint: placement-aggregate-generation
Introduce placement microversion 1.18 with a new ?required=<trait list>
query parameter accepted on the GET /resource_providers API. Results
are filtered by providers possessing *all* of the specified traits.
Empty/invalid traits result in 400 errors.
Change-Id: I8191c9a390cb02b2a38a3f1c6e29457435994981
blueprint: traits-on-list-resource-providers
It was pointed out [1] that the semantic difference between how the
`resources` query parameter is handled by GET /resource_providers versus
GET /allocation_candidates is not clear based on the API reference
descriptions, which are identical. This change set clarifies the
wording for both, making it clear that a) allocations are taking into
account; and b) GET /allocation_candidates is working with groups of
providers that must *collectively* satisfy the resource specification.
[1] https://review.openstack.org/#/c/547056/2/specs/rocky/approved/traits-on-list-resource-providers.rst@33
Change-Id: Ia2a4f8f80ec68dd9c95e084c292a2fe2d6ec1b2d
This patch add new query parameter `required` to the
`GET /allocation_candidates` API, which is used to filter candidates
with required traits. The candidate attached traits return in the
provider summary also. Those API changes are added by new microversion.
Also using specific exception TraitNotFound instead of the generic
exception ValueError when invalid traits in the request.
Change-Id: Id821b5b2768dcc698695ba6570c6201e1e9a8233
Implement blueprint add-trait-support-in-allocation-candidates
This adds a limit query parameter to GET
/allocation_candidates?limit=5&resource=VCPU:1
A 'limit' filter is added to the AllocationCandidates. If set, after
the database query has been run to create the allocation requests and
provider summaries, a slice or sample of the allocation requests is
taken to limit the results. The summaries are then filtered to only
include those in the allocation requests.
This method avoids needing to make changes to the generated SQL, the
creation of which is fairly complex, or the database tables. The amount
of data queried is still high in the extreme case, but the amount of
data sent over the wire (as JSON) is shrunk. This is a trade-off that
was discussed in the spec and the discussion surrounding its review.
If it turns out that memory use server-side is an issue we can
investigate changing the SQL.
A configuration setting, [placement]/randomize_allocation_candidates,
is added to allow deployers to declare whether they want the results
to be returned in whatever order the database chooses or a random
order. The default is "False" which is expected to preserve existing
behavior and impose a packing placement strategy.
When the config setting is combined with the limit parameter, if
"True" the limited results are a random sampling from the full
results. If "False", it is a slice from the front.
This is done as a new microversion, 1.16, with updates to docs, a reno
and adjustments to the api history doc.
Change-Id: I5f3d4f49c34fd3cd6b9d2e12b3c3c4cdcb409bec
Implements: bp allocation-candidates-limit
It is a follow-up for I4db74e4dc682bc03df6ec94cd1c3a5f5dc927a7b.
Fix description of placement microversion 1.14.
Change-Id: I7a7ffc395d444fe7cf0434ea6745dde0dae11ad5
blueprint nested-resource-providers
The 'Location' parameters are missing in the follwoing APIs of
Placement API reference. So add them.
* POST /resource_providers
* POST /resource_classes
* PUT /resource_classes/{name} (microversion 1.7-)
* PUT /traits/{name}
Change-Id: Ieed5cb7d4697472ab46b2e80d6d2df68098c5631
Closes-Bug: #1733329
Adds a new microversion (1.14) to the placement REST API for supporting
nested resource providers.
For POST /resource_providers and PUT /resource_providers/{uuid}, a new
optional 'parent_provider_uuid' field is added to the request payload.
For GET /resource_providers/{uuid} responses, the
'parent_provider_uuid' field and a convenience field called
'root_provider_uuid' are provided.
For GET /resource_providers, a new '?in_tree=<rp_uuid>' parameter is
supported. This parameter accepts a UUID of a resource provider. This
will cause the resulting list of resource providers to be only the
providers within the same "provider tree" as the provider identified by
<rp_uuid>
Clients for the placement REST API can specify either
'OpenStack-API-Version: placement 1.14' or 'placement latest' to handle
the new 'parent_provider_uuid' attribute and to query for resource
providers in a provider tree.
Change-Id: I4db74e4dc682bc03df6ec94cd1c3a5f5dc927a7b
blueprint: nested-resource-providers
APIImpact
The aggregate link has been added in resource provider APIs
since microversion 1.1.
But the note is missing in Placement API reference.
Add the note.
The allocations link is missing in the response example
of "Update resource provider" API.
Add it as well.
Change-Id: I325ff34c8b436429c2a2623cf1fb16b368807d29
Closes-Bug: #1733317
In the review of I49f5680c15413bce27f2abba68b699f3ea95dcdc, a few
non-blocking nits were identified. This change addresses some of
those nits, fixing some typos, clarifying method names and what
microversion is in use at particular times.
Change-Id: Iff15340502ce43eba3b98db26aa0652b1da24504
This provides microversion 1.13 of the placement API, giving the
ability to POST to /allocations to set (or clear) allocations for
more than one consumer uuid.
It builds on the recent work to support a dict-based JSON format
when doing a PUT to /allocations/{consumer_uuid}.
Being able to set allocations for multiple consumers in one request
helps to address race conditions when cleaning up allocations during
move operations in nova.
Clearing allocations is done by setting the 'allocations' key for a
specific consumer to an empty dict.
Updates to placement-api-ref, rest version history and a reno are
included.
Change-Id: I239f33841bb9fcd92b406f979674ae8c5f8d57e3
Implements: bp post-allocations
In the following resource class APIs,
the name of a resource class must start with 'CUSTOM_'.
If not, the request returns a 'Bad Request (400)' response code.
It should be described in the API reference. So add it.
* POST /resource_classes
* PUT /resource_classes/{name}
Change-Id: I132c532678bb74a460515067187fbf1e30885335
Closes-Bug: #1733308
In a new microversion, 1.12, include project_id and user_id in the
output of GET /allocations/{consumer_uuid} and add JSON schema
to enable PUT to /allocations/{consumer_uuid} using the same dict-based
format for request body that is used in the GET response. In later
commits a similar format will be used in POST /allocations. This
symmetry is general good form and also will make client code a little
easier.
Since GET /allocation_candiates includes objects which are capable
of being PUT to /allocations/{consumer_uuid}, its response body has
been updated as well, to change the 'allocation_requests' object
to use the dict-based format.
Internally to handlers/allocation.py the same method (_set_allocations)
is used for every microversion. Any previous data structure is
transformed into the dict-ish form. This means that pre-existing tests
(like allocation-bad-class.yaml) continue to exercise the problems it
was made for, but needs to be pinned to an older microversion, rather than
being latest.
Info about these changes is added to placement-api-ref,
rest_api_version_history and a reno.
Change-Id: I49f5680c15413bce27f2abba68b699f3ea95dcdc
Implements: bp symmetric-allocations
Closes-Bug: #1708204
Following on [1], this change updates the placement api-ref to include
the allocations link in the sample output for GET
/resource_providers[/uuid].
[1] https://review.openstack.org/499826
Depends-On: I6a1d320ce914926791d5f45e89bf4c601a6b10a0
Change-Id: I161da67258afaccd90df12364153f068ef55a3b1
The member_of query parameter was new in 1.3.
The resources query parameter was new in 1.4.
As a result, the 'resources' parameter description used for
allocation_candidates has to be decoupled since the entire
allocation_candidates API was new in 1.10 and is not specified
per parameter.
Change-Id: I6e0688b4a12212ace98a6876132735094df84b77
Closes-Bug: #1716046
In the Placement API reference, the GET /traits [1] query parameter
'name' says it accepts a key called 'starts_with'. The actual API
accepts 'startswith' (no underscore).
[1] https://developer.openstack.org/api-ref/placement/#list-traits
Change-Id: I5a1fa51fc751f2492ae6aa2b38893a9e06a26ed1
Closes-Bug: #1714283
This provides simple documentation of the path and response
body parameters when listing resource provider allocations.
Co-Authored-by: Andrey Volkov <avolkov@gmail.com>
Change-Id: I40fcbc3077151227f33c6a021229b5c549889bbe
This provides simple documentation of the path, request and response
body parameters when listing, creating, updating and deleting allocations.
Change-Id: I58e9dfcb62a2f485addeab98dcd835568ba792cf
This provides simple documentation of the path, request and response
body parameters when listing, creating, updating and deleting traits.
Change-Id: If377b725e0910de2e1768666184a0212c8c9fdbc
This provides simple documentation of the path, request and response
body parameters when listing and updating aggregates.
Change-Id: Ife94d22e87a73fc26c4dcbda9545a9f59680f44f
This provides simple documentation of the path, request and response
body parameters when listing, creating, updating and deleting a resource
class.
Change-Id: I4038d116d53b68344282ef59f9f01753766d2ef8
This provides simple documentation of the response body and path
parameters when listing a single resource provider.
Change-Id: I84d472067e4365d59cab4863f87df9d24718701f
This provides simple documentation of the response body and path
parameters when showing a single class of inventory for a resource
provider.
Change-Id: Ic562baa3e74445c8f6dbeb416c1ec183cc2ad14d
Takashi NATSUME