From b817c6b6a673da867d14daed8057b25a60a86708 Mon Sep 17 00:00:00 2001 From: Andrey Volkov Date: Fri, 2 Jun 2017 15:43:18 +0300 Subject: [PATCH] [placement] Add api-ref for aggregates This provides simple documentation of the path, request and response body parameters when listing and updating aggregates. Change-Id: Ife94d22e87a73fc26c4dcbda9545a9f59680f44f --- placement-api-ref/source/aggregates.inc | 108 ++++++++++++++++++ placement-api-ref/source/get-aggregates.json | 6 + placement-api-ref/source/index.rst | 1 + placement-api-ref/source/parameters.yaml | 6 + .../source/update-aggregates-request.json | 4 + .../source/update-aggregates.json | 6 + 6 files changed, 131 insertions(+) create mode 100644 placement-api-ref/source/aggregates.inc create mode 100644 placement-api-ref/source/get-aggregates.json create mode 100644 placement-api-ref/source/update-aggregates-request.json create mode 100644 placement-api-ref/source/update-aggregates.json diff --git a/placement-api-ref/source/aggregates.inc b/placement-api-ref/source/aggregates.inc new file mode 100644 index 000000000..17cd4f782 --- /dev/null +++ b/placement-api-ref/source/aggregates.inc @@ -0,0 +1,108 @@ +============================ +Resource provider aggregates +============================ + +Each resource provider can be associated with one or more other +resource providers in groups called aggregates. API calls in this +section are used to list and update the aggregates that are associated +with one resource provider. + +.. note:: Placement aggregates are *not* the same as Nova host + aggregates and should not be considered equivalent. + +The primary differences between Nova's host aggregates and placement +aggregates are the following: + +* In Nova, a host aggregate associates a *nova-compute service* with + other nova-compute services. Placement aggregates are not specific + to a nova-compute service and are, in fact, not + compute-specific at all. A resource provider in the Placement API is + generic, and placement aggregates are simply groups of generic + resource providers. This is an important difference especially for + Ironic, which when used with Nova, has many Ironic baremetal nodes + attached to a single nova-compute service. In the Placement API, + each Ironic baremetal node is its own resource provider and can + therefore be associated to other Ironic baremetal nodes via a + placement aggregate association. +* In Nova, a host aggregate may have *metadata* key/value pairs + attached to it. All nova-compute services associated with a Nova + host aggregate share the same metadata. Placement aggregates have no + such metadata because placement aggregates *only* represent the + grouping of resource providers. In the Placement API, resource + providers are individually decorated with *traits* that provide + qualitative information about the resource provider. +* In Nova, a host aggregate dictates the *availability zone* within + which one or more nova-compute services reside. Placement aggregates + have no concept of an availability zone. + +.. note:: Aggregates API requests are availiable starting from version 1.1. + +List resource provider aggregates +================================= + +.. rest_method:: GET /resource_providers/{uuid}/aggregates + +Return a list of aggregates associated with the resource provider +identified by `{uuid}`. + +Normal Response Codes: 200 + +Error response codes: itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - uuid: resource_provider_uuid_path + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - aggregates: aggregates + +Response Example +---------------- + +.. literalinclude:: get-aggregates.json + :language: javascript + +Update resource provider aggregates +=================================== + +Associate a list of aggregates with the resource provider identified by `{uuid}`. + +.. rest_method:: PUT /resource_providers/{uuid}/aggregates + +Normal Response Codes: 200 + +Error response codes: badRequest(400), itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - uuid: resource_provider_uuid_path + - aggregates: aggregates + +Request example +--------------- + +.. literalinclude:: update-aggregates-request.json + :language: javascript + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - aggregates: aggregates + +Response Example +---------------- + +.. literalinclude:: update-aggregates.json + :language: javascript diff --git a/placement-api-ref/source/get-aggregates.json b/placement-api-ref/source/get-aggregates.json new file mode 100644 index 000000000..6871048a7 --- /dev/null +++ b/placement-api-ref/source/get-aggregates.json @@ -0,0 +1,6 @@ +{ + "aggregates": [ + "42896e0d-205d-4fe3-bd1e-100924931787", + "5e08ea53-c4c6-448e-9334-ac4953de3cfa" + ] +} diff --git a/placement-api-ref/source/index.rst b/placement-api-ref/source/index.rst index 6b6d0b917..a948c9a3a 100644 --- a/placement-api-ref/source/index.rst +++ b/placement-api-ref/source/index.rst @@ -19,3 +19,4 @@ Openstack Placement API concepts, please refer to the .. include:: resource_class.inc .. include:: inventories.inc .. include:: inventory.inc +.. include:: aggregates.inc diff --git a/placement-api-ref/source/parameters.yaml b/placement-api-ref/source/parameters.yaml index 7c9a2a3d9..95814163f 100644 --- a/placement-api-ref/source/parameters.yaml +++ b/placement-api-ref/source/parameters.yaml @@ -43,6 +43,12 @@ resources_query: resources=VCPU:4,DISK_GB:64,MEMORY_MB:2048 # variables in body +aggregates: + type: array + in: body + required: true + description: > + A list of aggregate uuids. allocation_ratio: &allocation_ratio type: float in: body diff --git a/placement-api-ref/source/update-aggregates-request.json b/placement-api-ref/source/update-aggregates-request.json new file mode 100644 index 000000000..502a73638 --- /dev/null +++ b/placement-api-ref/source/update-aggregates-request.json @@ -0,0 +1,4 @@ +[ + "42896e0d-205d-4fe3-bd1e-100924931787", + "5e08ea53-c4c6-448e-9334-ac4953de3cfa" +] diff --git a/placement-api-ref/source/update-aggregates.json b/placement-api-ref/source/update-aggregates.json new file mode 100644 index 000000000..6871048a7 --- /dev/null +++ b/placement-api-ref/source/update-aggregates.json @@ -0,0 +1,6 @@ +{ + "aggregates": [ + "42896e0d-205d-4fe3-bd1e-100924931787", + "5e08ea53-c4c6-448e-9334-ac4953de3cfa" + ] +}