c85ae69ee9
When placement picks up allocation candidates, the aggregates of nested providers were assumed as the same as root providers. This means that the `GET /allocation_candidates API` ignored the aggregates on the nested providers. This could result in the lack of allocation candidates when an aggregate is on a nested provider but the aggregate is not on its root provider and the aggregate is specified in the API by the `member_of` query parameter. This patch fixes the bug changing it to consider the aggregates not only on root rps but also on the nested rp itself and adds a release note for this. The document which explains the whole constraint of `member_of` and other query parameters with nested providers, will be submitted in a follow up patch. Change-Id: I9a11a577174f85a1b47a9e895bb25cadd90bd2ea Closes-Bug: #1792503
660 lines
20 KiB
YAML
660 lines
20 KiB
YAML
# variables in header
|
|
location:
|
|
description: |
|
|
The location URL of the resource created,
|
|
HTTP header "Location: <Location URL>" will be returned.
|
|
in: header
|
|
required: true
|
|
type: string
|
|
|
|
# variables in path
|
|
consumer_uuid: &consumer_uuid
|
|
type: string
|
|
in: path
|
|
required: true
|
|
description: >
|
|
The uuid of a consumer.
|
|
resource_class_path: &resource_class_path
|
|
type: string
|
|
in: path
|
|
required: true
|
|
description: >
|
|
The name of one resource class.
|
|
resource_class_path_custom: &resource_class_path_custom
|
|
type: string
|
|
in: path
|
|
required: true
|
|
description: >
|
|
The name of one resource class. The name must start with
|
|
the prefix ``CUSTOM_``. If not, the request returns a ``Bad Request (400)``
|
|
response code.
|
|
resource_provider_uuid_path: &resource_provider_uuid_path
|
|
type: string
|
|
in: path
|
|
required: true
|
|
description: >
|
|
The uuid of a resource provider.
|
|
trait_name:
|
|
type: string
|
|
in: path
|
|
required: true
|
|
description: >
|
|
The name of a trait.
|
|
|
|
# variables in query
|
|
allocation_candidates_group_policy:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
min_version: 1.25
|
|
description: >
|
|
When more than one ``resourcesN`` query parameter is supplied,
|
|
``group_policy`` is required to indicate how the groups should interact.
|
|
With ``group_policy=none``, separate groupings - numbered or unnumbered -
|
|
may or may not be satisfied by the same provider. With
|
|
``group_policy=isolate``, numbered groups are guaranteed to be satisfied by
|
|
*different* providers - though there may still be overlap with the
|
|
unnumbered group.
|
|
allocation_candidates_limit:
|
|
type: integer
|
|
in: query
|
|
required: false
|
|
min_version: 1.16
|
|
description: >
|
|
A positive integer used to limit the maximum number of allocation
|
|
candidates returned in the response.
|
|
member_of: &member_of
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: >
|
|
A string representing an aggregate uuid; or the prefix ``in:`` followed by
|
|
a comma-separated list of strings representing aggregate uuids. The
|
|
returned resource providers must directly be associated with at least one
|
|
of the aggregates identified by uuid::
|
|
|
|
member_of=5e08ea53-c4c6-448e-9334-ac4953de3cfa
|
|
member_of=in:42896e0d-205d-4fe3-bd1e-100924931787,5e08ea53-c4c6-448e-9334-ac4953de3cfa
|
|
|
|
**Starting from microversion 1.24** specifying multiple ``member_of`` query
|
|
string parameters is possible. Multiple ``member_of`` parameters will
|
|
result in filtering providers that are associated with aggregates listed in
|
|
all of the ``member_of`` query string values. For example, to get the
|
|
providers that are associated with aggregate A as well as associated with
|
|
any of aggregates B or C, the user could issue the following query::
|
|
|
|
member_of=AGGA_UUID&member_of=in:AGGB_UUID,AGGC_UUID
|
|
min_version: 1.3
|
|
member_of_1_21:
|
|
<<: *member_of
|
|
description: >
|
|
A string representing an aggregate uuid; or the prefix ``in:`` followed by
|
|
a comma-separated list of strings representing aggregate uuids. The
|
|
resource providers in the allocation request in the response must directly
|
|
or via the root provider be associated with the aggregate or aggregates
|
|
identified by uuid::
|
|
|
|
member_of=5e08ea53-c4c6-448e-9334-ac4953de3cfa
|
|
member_of=in:42896e0d-205d-4fe3-bd1e-100924931787,5e08ea53-c4c6-448e-9334-ac4953de3cfa
|
|
|
|
**Starting from microversion 1.24** specifying multiple ``member_of`` query
|
|
string parameters is possible. Multiple ``member_of`` parameters will
|
|
result in filtering providers that are directly or via root provider
|
|
associated with aggregates listed in all of the ``member_of`` query string
|
|
values. For example, to get the providers that are associated with
|
|
aggregate A as well as associated with any of aggregates B or C, the user
|
|
could issue the following query::
|
|
|
|
member_of=AGGA_UUID&member_of=in:AGGB_UUID,AGGC_UUID
|
|
min_version: 1.21
|
|
member_of_granular:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: >
|
|
A string representing an aggregate uuid; or the prefix ``in:`` followed by
|
|
a comma-separated list of strings representing aggregate uuids. The
|
|
returned resource providers must directly be associated with at least one
|
|
of the aggregates identified by uuid. The parameter key is ``member_ofN``,
|
|
where ``N`` represents a positive integer suffix corresponding with a
|
|
``resourcesN`` parameter. The value format is the same as for the
|
|
(unnumbered) ``member_of`` parameter; but all of the resources and traits
|
|
specified in a numbered grouping will always be satisfied by the same
|
|
resource provider. Separate groupings - numbered or unnumbered - may or may
|
|
not be satisfied by the same provider, depending on the value of the
|
|
``group_policy`` parameter.
|
|
|
|
It is an error to specify a ``member_ofN`` parameter without a
|
|
corresponding ``resourcesN`` parameter with the same suffix.
|
|
min_version: 1.25
|
|
project_id: &project_id
|
|
type: string
|
|
in: query
|
|
required: true
|
|
description: >
|
|
The uuid of a project.
|
|
required_traits_granular:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |
|
|
A comma-separated list of traits that a provider must have, or (if prefixed
|
|
with a ``!``) **not** have::
|
|
|
|
required42=HW_CPU_X86_AVX,HW_CPU_X86_SSE,!HW_CPU_X86_AVX2
|
|
|
|
The parameter key is ``requiredN``, where ``N`` represents a
|
|
positive integer suffix corresponding with a ``resourcesN`` parameter.
|
|
The value format is the same as for the (unnumbered) ``required``
|
|
parameter; but all of the resources and traits specified in a numbered
|
|
grouping will always be satisfied by the same resource provider. Separate
|
|
groupings - numbered or unnumbered - may or may not be satisfied by the
|
|
same provider, depending on the value of the ``group_policy`` parameter.
|
|
|
|
It is an error to specify a ``requiredN`` parameter without a corresponding
|
|
``resourcesN`` parameter with the same suffix.
|
|
min_version: 1.25
|
|
required_traits_unnumbered:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
min_version: 1.17
|
|
description: |
|
|
A comma-separated list of traits that a provider must have::
|
|
|
|
required=HW_CPU_X86_AVX,HW_CPU_X86_SSE
|
|
|
|
Allocation requests in the response will be for resource providers that
|
|
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 ``!``.
|
|
resource_provider_name_query:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: >
|
|
The name of a resource provider to filter the list.
|
|
resource_provider_required_query:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: >
|
|
A comma-delimited list of string trait names. Results will be filtered to
|
|
include only resource providers having all the specified traits. **Starting
|
|
from microversion 1.22** traits which are forbidden from any resource
|
|
provider may be expressed by prefixing a trait with a ``!``.
|
|
min_version: 1.18
|
|
resource_provider_tree_query:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: >
|
|
A UUID of a resource provider. The returned resource providers will be in
|
|
the same "provider tree" as the specified provider.
|
|
min_version: 1.14
|
|
resource_provider_uuid_query:
|
|
<<: *resource_provider_uuid_path
|
|
in: query
|
|
required: false
|
|
resources_query_1_4:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |
|
|
A comma-separated list of strings indicating an amount of
|
|
resource of a specified class that a provider must have the
|
|
capacity and availability to serve::
|
|
|
|
resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
|
|
min_version: 1.4
|
|
resources_query_ac:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |
|
|
A comma-separated list of strings indicating an amount of
|
|
resource of a specified class that providers in each allocation request
|
|
must *collectively* have the capacity and availability to serve::
|
|
|
|
resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048
|
|
|
|
These resources may be satisfied by any provider in the same non-sharing
|
|
tree or associated via aggregate.
|
|
resources_query_granular:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |
|
|
A comma-separated list of strings indicating an amount of
|
|
resource of a specified class that a provider must have the
|
|
capacity to serve::
|
|
|
|
resources42=VCPU:4,DISK_GB:64,MEMORY_MB:2048
|
|
|
|
The parameter key is ``resourcesN``, where ``N`` represents a unique
|
|
positive integer suffix. The value format is the same as for the
|
|
(unnumbered) ``resources`` parameter, but the resources specified in a
|
|
``resourcesN`` parameter will always be satisfied by a single provider.
|
|
Separate groupings - numbered or unnumbered - may or may not be satisfied
|
|
by the same provider depending on the value of the ``group_policy``
|
|
parameter.
|
|
min_version: 1.25
|
|
trait_associated:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: >
|
|
If this parameter has a true value, the returned traits will be
|
|
those that are associated with at least one resource provider.
|
|
Available values for the parameter are true and false.
|
|
trait_name_query:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: |
|
|
A string to filter traits. The following options are available:
|
|
|
|
`startswith` operator filters the traits whose name begins with a
|
|
specific prefix, e.g. name=startswith:CUSTOM,
|
|
|
|
`in` operator filters the traits whose name is in the specified list, e.g.
|
|
name=in:HW_CPU_X86_AVX,HW_CPU_X86_SSE,HW_CPU_X86_INVALID_FEATURE.
|
|
user_id: &user_id
|
|
type: string
|
|
in: query
|
|
required: false
|
|
description: >
|
|
The uuid of a user.
|
|
|
|
# variables in body
|
|
aggregates:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of aggregate uuids. Previously nonexistent aggregates are
|
|
created automatically.
|
|
allocation_ratio: &allocation_ratio
|
|
type: float
|
|
in: body
|
|
required: true
|
|
description: |
|
|
It is used in determining whether consumption of the resource of
|
|
the provider can exceed physical constraints.
|
|
|
|
For example, for a vCPU resource with::
|
|
|
|
allocation_ratio = 16.0
|
|
total = 8
|
|
|
|
Overall capacity is equal to 128 vCPUs.
|
|
allocation_ratio_opt:
|
|
<<: *allocation_ratio
|
|
required: false
|
|
allocation_requests:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of objects that contain a
|
|
serialized HTTP body that a client may subsequently use in a call
|
|
to PUT /allocations/{consumer_uuid} to claim resources against a
|
|
related set of resource providers.
|
|
allocations_array:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of dictionaries.
|
|
allocations_by_resource_provider:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary of allocations keyed by resource provider uuid.
|
|
allocations_dict: &allocations_dict
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary of resource allocations keyed by resource provider uuid.
|
|
allocations_dict_empty:
|
|
<<: *allocations_dict
|
|
description: >
|
|
A dictionary of resource allocations keyed by resource provider uuid.
|
|
If this is an empty object, allocations for this consumer will be
|
|
removed.
|
|
min_version: null
|
|
capacity:
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The amount of the resource that the provider can accommodate.
|
|
consumer_generation: &consumer_generation
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The generation of the consumer. Should be set to ``null`` when indicating
|
|
that the caller expects the consumer does not yet exist.
|
|
consumer_generation_min:
|
|
<<: *consumer_generation
|
|
min_version: 1.28
|
|
consumer_uuid_body:
|
|
<<: *consumer_uuid
|
|
in: body
|
|
inventories:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary of inventories keyed by resource classes.
|
|
max_unit: &max_unit
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A maximum amount any single allocation against an inventory can have.
|
|
max_unit_opt:
|
|
<<: *max_unit
|
|
required: false
|
|
min_unit: &min_unit
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A minimum amount any single allocation against an inventory can have.
|
|
min_unit_opt:
|
|
<<: *min_unit
|
|
required: false
|
|
project_id_body: &project_id_body
|
|
<<: *project_id
|
|
in: body
|
|
project_id_body_1_12:
|
|
<<: *project_id_body
|
|
min_version: 1.12
|
|
project_id_body_1_8:
|
|
<<: *project_id_body
|
|
min_version: 1.8
|
|
provider_summaries:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary keyed by resource provider UUID included in the
|
|
``allocation_requests``, of dictionaries of inventory/capacity information.
|
|
provider_summaries_1_12:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary keyed by resource provider UUID included in the
|
|
``allocation_requests``, of dictionaries of inventory/capacity information.
|
|
The list of traits the resource provider has associated with it is included
|
|
in version 1.17 and above.
|
|
Starting from microversion 1.29, the provider summaries include
|
|
all resource providers in the same resource provider tree that has one
|
|
or more resource providers included in the ``allocation_requests``.
|
|
reserved: &reserved
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The amount of the resource a provider has reserved for its own use.
|
|
reserved_opt:
|
|
<<: *reserved
|
|
required: false
|
|
description: >
|
|
The amount of the resource a provider has reserved for its own use.
|
|
Up to microversion 1.25, this value has to be less than the value of
|
|
``total``. Starting from microversion 1.26, this value has to be less
|
|
than or equal to the value of ``total``.
|
|
reshaper_allocations:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary of multiple allocations, keyed by consumer uuid. Each
|
|
collection of allocations describes the full set of allocations for
|
|
each consumer. Each consumer allocations dict is itself a dictionary
|
|
of resource allocations keyed by resource provider uuid. An empty
|
|
dictionary indicates no change in existing allocations, whereas an empty
|
|
``allocations`` dictionary **within** a consumer dictionary indicates that
|
|
all allocations for that consumer should be deleted.
|
|
reshaper_inventories:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary of multiple inventories, keyed by resource provider uuid. Each
|
|
inventory describes the desired full inventory for each resource provider.
|
|
An empty dictionary causes the inventory for that provider to be deleted.
|
|
resource_class:
|
|
<<: *resource_class_path
|
|
in: body
|
|
resource_class_custom:
|
|
<<: *resource_class_path_custom
|
|
in: body
|
|
resource_class_links:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of links associated with one resource class.
|
|
resource_classes:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of ``resource_class`` objects.
|
|
resource_provider_allocations:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary of allocation records keyed by consumer uuid.
|
|
resource_provider_generation: &resource_provider_generation
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A consistent view marker that assists with the management of
|
|
concurrent resource provider updates.
|
|
resource_provider_generation_optional:
|
|
<<: *resource_provider_generation
|
|
required: false
|
|
description: >
|
|
A consistent view marker that assists with the management of
|
|
concurrent resource provider updates. The value is ignored;
|
|
it is present to preserve symmetry between read and
|
|
write representations.
|
|
resource_provider_generation_v1_19:
|
|
<<: *resource_provider_generation
|
|
min_version: 1.19
|
|
resource_provider_links: &resource_provider_links
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: |
|
|
A list of links associated with one resource provider.
|
|
|
|
.. note::
|
|
|
|
Aggregates relationship link is available starting from version 1.1.
|
|
Traits relationship link is available starting from version 1.6.
|
|
Allocations relationship link is available starting from version 1.11.
|
|
|
|
resource_provider_links_v1_20:
|
|
<<: *resource_provider_links
|
|
description: |
|
|
A list of links associated with the resource provider.
|
|
|
|
resource_provider_name:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The name of one resource provider.
|
|
resource_provider_object:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary which contains the UUID of the resource provider.
|
|
resource_provider_parent_provider_uuid_request:
|
|
type: string
|
|
in: body
|
|
required: false
|
|
description: >
|
|
The UUID of the immediate parent of the resource provider. Once set, the
|
|
parent of a resource provider cannot be changed.
|
|
min_version: 1.14
|
|
resource_provider_parent_provider_uuid_required_no_min:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The UUID of the immediate parent of the resource provider.
|
|
resource_provider_parent_provider_uuid_response_1_14:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The UUID of the immediate parent of the resource provider.
|
|
min_version: 1.14
|
|
resource_provider_parent_provider_uuid_response_1_29:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The UUID of the immediate parent of the resource provider.
|
|
min_version: 1.29
|
|
resource_provider_root_provider_uuid_1_29:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
UUID of the top-most provider in this provider tree.
|
|
min_version: 1.29
|
|
resource_provider_root_provider_uuid_no_min: &resource_provider_root_provider_uuid_no_min
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
UUID of the top-most provider in this provider tree.
|
|
resource_provider_root_provider_uuid_required:
|
|
<<: *resource_provider_root_provider_uuid_no_min
|
|
description: >
|
|
Read-only UUID of the top-most provider in this provider tree.
|
|
min_version: 1.14
|
|
resource_provider_usages:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The usage summary of the resource provider. This is a dictionary that
|
|
describes how much each class of resource is being consumed on this
|
|
resource provider. For example, ``"VCPU": 1`` means 1 VCPU is used.
|
|
resource_provider_uuid:
|
|
<<: *resource_provider_uuid_path
|
|
in: body
|
|
resource_provider_uuid_opt:
|
|
<<: *resource_provider_uuid_path
|
|
in: body
|
|
required: false
|
|
resource_providers:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of ``resource_provider`` objects.
|
|
resources:
|
|
type: object
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A dictionary of resource records keyed by resource class name.
|
|
step_size: &step_size
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A representation of the divisible amount of the resource
|
|
that may be requested. For example, step_size = 5 means
|
|
that only values divisible by 5 (5, 10, 15, etc.) can be requested.
|
|
step_size_opt:
|
|
<<: *step_size
|
|
required: false
|
|
total:
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The actual amount of the resource that the provider can accommodate.
|
|
traits: &traits
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of traits.
|
|
traits_1_17:
|
|
<<: *traits
|
|
min_version: 1.17
|
|
used:
|
|
type: integer
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The amount of the resource that has been already allocated.
|
|
user_id_body: &user_id_body
|
|
<<: *user_id
|
|
in: body
|
|
required: true
|
|
user_id_body_1_12:
|
|
<<: *user_id_body
|
|
min_version: 1.12
|
|
user_id_body_1_8:
|
|
<<: *user_id_body
|
|
min_version: 1.8
|
|
version_id:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A common name for the version being described. Informative only.
|
|
version_links:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of links related to and describing this version.
|
|
version_max:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The maximum microversion that is supported.
|
|
version_min:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The minimum microversion that is supported.
|
|
version_status:
|
|
type: string
|
|
in: body
|
|
required: true
|
|
description: >
|
|
The status of the version being described. With placement this is
|
|
"CURRENT".
|
|
versions:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of version objects that describe the API versions available.
|