77d3fc3838
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
466 lines
12 KiB
YAML
466 lines
12 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_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.
|
|
allocation_candidates_required:
|
|
type: string
|
|
in: query
|
|
required: false
|
|
min_version: 1.17
|
|
description: >
|
|
Accepts a list of comma-separated traits. 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. **Starting from
|
|
microversion 1.22** traits which are forbidden from any resource provider
|
|
may be expressed by prefixing a trait with a ``!``.
|
|
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
|
|
min_version: 1.3
|
|
member_of_1_21:
|
|
<<: *member_of
|
|
min_version: 1.21
|
|
project_id: &project_id
|
|
type: string
|
|
in: query
|
|
required: true
|
|
description: >
|
|
The uuid of a project.
|
|
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:
|
|
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_required:
|
|
type: string
|
|
in: query
|
|
required: true
|
|
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
|
|
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_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,
|
|
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.
|
|
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
|
|
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: &resource_provider_parent_provider_uuid
|
|
type: string
|
|
in: body
|
|
required: false
|
|
description: >
|
|
The UUID of the immediate parent of the resource provider.
|
|
resource_provider_parent_provider_uuid_1_14: &resource_provider_parent_provider_uuid_1_14
|
|
<<: *resource_provider_parent_provider_uuid
|
|
min_version: 1.14
|
|
resource_provider_parent_provider_uuid_required:
|
|
<<: *resource_provider_parent_provider_uuid
|
|
required: true
|
|
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:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of traits.
|
|
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_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.
|
|
versions:
|
|
type: array
|
|
in: body
|
|
required: true
|
|
description: >
|
|
A list of version objects that describe the API versions available.
|