nova/placement-api-ref/source/parameters.yaml

618 lines
18 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 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
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 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.
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:
type: integer
in: body
required: true
min_version: 1.28
description: >
The generation of the consumer. Should be set to ``null`` when indicating
that the caller expects the consumer does not yet exist.
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``.
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.