nova/placement-api-ref/source/parameters.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 ``None`` when indicating
    the 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,
    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
  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:
  <<: *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_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.