From 64ae6832db2bea4c06d666695958ee64728d42d8 Mon Sep 17 00:00:00 2001 From: Andrey Volkov Date: Mon, 26 Jun 2017 14:27:49 +0300 Subject: [PATCH] [placement] Add api-ref for allocations This provides simple documentation of the path, request and response body parameters when listing, creating, updating and deleting allocations. Change-Id: I58e9dfcb62a2f485addeab98dcd835568ba792cf --- placement-api-ref/source/allocations.inc | 106 ++++++++++++++++++ placement-api-ref/source/get-allocations.json | 17 +++ placement-api-ref/source/index.rst | 1 + placement-api-ref/source/parameters.yaml | 51 +++++++++ .../source/update-allocations-request.json | 23 ++++ 5 files changed, 198 insertions(+) create mode 100644 placement-api-ref/source/allocations.inc create mode 100644 placement-api-ref/source/get-allocations.json create mode 100644 placement-api-ref/source/update-allocations-request.json diff --git a/placement-api-ref/source/allocations.inc b/placement-api-ref/source/allocations.inc new file mode 100644 index 000000000000..0987250f6f92 --- /dev/null +++ b/placement-api-ref/source/allocations.inc @@ -0,0 +1,106 @@ +=========== +Allocations +=========== + +Allocations are records representing resources that have been assigned +and used by some consumer of that resource. They indicate the amount +of a particular resource that has been allocated to a given consumer +of that resource from a particular resource provider. + +List allocations +================ + +List all allocation records for the consumer identified by +`{consumer_uuid}` on all the resource providers it is consuming. + +.. rest_method:: GET /allocations/{consumer_uuid} + +Normal Response Codes: 200 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - consumer_uuid: consumer_uuid + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - allocations: allocations_by_resource_provider + - generation: resource_provider_generation + - resources: resources + +Response Example +---------------- + +.. literalinclude:: get-allocations.json + :language: javascript + +Update allocations +================== + +Create or update one or more allocation records representing the consumption of +one or more classes of resources from one or more resource providers by +the consumer identified by `{consumer_uuid}`. +If allocations already exist for this consumer, they are replaced. + +.. rest_method:: PUT /allocations/{consumer_uuid} + +Normal Response Codes: 204 + +Error response codes: badRequest(400), itemNotFound(404), conflict(409) + +* `409 Conflict` if there is no available inventory in any of the + resource providers for any specified resource classes or inventories + are updated by another thread while attempting the operation. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - consumer_uuid: consumer_uuid + - allocations: allocations_array + - resources: resources + - resource_provider: resource_provider_object + - uuid: resource_provider_uuid + - project_id: project_id_body + - user_id: user_id_body + +Request example +--------------- + +.. literalinclude:: update-allocations-request.json + :language: javascript + +Response +-------- + +No body content is returned on a successful PUT. + +Delete allocations +================== + +Delete all allocation records for the consumer identified by +`{consumer_uuid}` on all resource providers it is consuming. + +.. rest_method:: DELETE /allocations/{consumer_uuid} + +Normal Response Codes: 204 + +Error response codes: itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - consumer_uuid: consumer_uuid + +Response +-------- + +No body content is returned on a successful DELETE. diff --git a/placement-api-ref/source/get-allocations.json b/placement-api-ref/source/get-allocations.json new file mode 100644 index 000000000000..3d12298b90b0 --- /dev/null +++ b/placement-api-ref/source/get-allocations.json @@ -0,0 +1,17 @@ +{ + "allocations": { + "92637880-2d79-43c6-afab-d860886c6391": { + "generation": 2, + "resources": { + "DISK_GB": 5 + } + }, + "ba8e1ef8-7fa3-41a4-9bb4-d7cb2019899b": { + "generation": 8, + "resources": { + "MEMORY_MB": 512, + "VCPU": 2 + } + } + } +} diff --git a/placement-api-ref/source/index.rst b/placement-api-ref/source/index.rst index 3773477fa4d2..277d5d2639b0 100644 --- a/placement-api-ref/source/index.rst +++ b/placement-api-ref/source/index.rst @@ -22,3 +22,4 @@ Openstack Placement API concepts, please refer to the .. include:: aggregates.inc .. include:: traits.inc .. include:: resource_provider_traits.inc +.. include:: allocations.inc diff --git a/placement-api-ref/source/parameters.yaml b/placement-api-ref/source/parameters.yaml index 603fb41de74a..eb0b0a9fa57f 100644 --- a/placement-api-ref/source/parameters.yaml +++ b/placement-api-ref/source/parameters.yaml @@ -1,4 +1,10 @@ # variables in path +consumer_uuid: + type: string + in: path + required: true + description: > + The uuid of a consumer. resource_class_path: &resource_class_path type: string in: path @@ -27,6 +33,12 @@ member_of: 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. +project_id: &project_id + type: string + in: query + required: true + description: > + The uuid of a project. resource_provider_name_query: type: string in: query @@ -67,6 +79,12 @@ trait_name_query: `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: @@ -92,6 +110,18 @@ allocation_ratio: &allocation_ratio allocation_ratio_opt: <<: *allocation_ratio required: false +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. inventories: type: object in: body @@ -116,6 +146,10 @@ min_unit: &min_unit min_unit_opt: <<: *min_unit required: false +project_id_body: + <<: *project_id + in: body + min_version: 1.8 reserved: &reserved type: integer in: body @@ -162,6 +196,12 @@ resource_provider_name: required: true description: > The name of one resource provider. +resource_provider_object: + type: object + in: body + required: true + description: > + A dictionary contains uuid of the resource provider. resource_provider_uuid: <<: *resource_provider_uuid_path in: body @@ -175,6 +215,12 @@ resource_providers: 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 @@ -198,6 +244,11 @@ traits: required: true description: > A list of traits. +user_id_body: + <<: *user_id + in: body + required: true + min_version: 1.8 version_id: type: string in: body diff --git a/placement-api-ref/source/update-allocations-request.json b/placement-api-ref/source/update-allocations-request.json new file mode 100644 index 000000000000..49d7eb39fd86 --- /dev/null +++ b/placement-api-ref/source/update-allocations-request.json @@ -0,0 +1,23 @@ +{ + "allocations": [ + { + "resource_provider": { + "uuid": "844ac34d-620e-474c-833c-4c9921251353" + }, + "resources": { + "MEMORY_MB": 512, + "VCPU": 2 + } + }, + { + "resource_provider": { + "uuid": "92637880-2d79-43c6-afab-d860886c6391" + }, + "resources": { + "DISK_GB": 5 + } + } + ], + "project_id": "6e3b2ce9-9175-4830-a862-b9de690bdceb", + "user_id": "81c516e3-5e0e-4dcb-9a38-4473d229a950" +}