From 67028cb732ccee70bc2094c1111652b9a175e3c8 Mon Sep 17 00:00:00 2001 From: Andrey Volkov Date: Wed, 14 Jun 2017 14:41:33 +0300 Subject: [PATCH] [placement] Add api-ref for traits This provides simple documentation of the path, request and response body parameters when listing, creating, updating and deleting traits. Change-Id: If377b725e0910de2e1768666184a0212c8c9fdbc --- placement-api-ref/source/get-traits.json | 7 ++ placement-api-ref/source/index.rst | 1 + placement-api-ref/source/parameters.yaml | 32 ++++++ placement-api-ref/source/traits.inc | 131 +++++++++++++++++++++++ 4 files changed, 171 insertions(+) create mode 100644 placement-api-ref/source/get-traits.json create mode 100644 placement-api-ref/source/traits.inc diff --git a/placement-api-ref/source/get-traits.json b/placement-api-ref/source/get-traits.json new file mode 100644 index 0000000000..bf81909ca2 --- /dev/null +++ b/placement-api-ref/source/get-traits.json @@ -0,0 +1,7 @@ +{ + "traits": [ + "CUSTOM_HW_FPGA_CLASS1", + "CUSTOM_HW_FPGA_CLASS2", + "CUSTOM_HW_FPGA_CLASS3" + ] +} diff --git a/placement-api-ref/source/index.rst b/placement-api-ref/source/index.rst index a948c9a3a3..097e3fbd52 100644 --- a/placement-api-ref/source/index.rst +++ b/placement-api-ref/source/index.rst @@ -20,3 +20,4 @@ Openstack Placement API concepts, please refer to the .. include:: inventories.inc .. include:: inventory.inc .. include:: aggregates.inc +.. include:: traits.inc diff --git a/placement-api-ref/source/parameters.yaml b/placement-api-ref/source/parameters.yaml index 95814163fb..603fb41de7 100644 --- a/placement-api-ref/source/parameters.yaml +++ b/placement-api-ref/source/parameters.yaml @@ -11,6 +11,12 @@ resource_provider_uuid_path: &resource_provider_uuid_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 member_of: @@ -41,6 +47,26 @@ resources_query: capacity 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: + + `starts_with` operator filters the traits whose name begins with a + specific prefix, e.g. name=starts_with: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. # variables in body aggregates: @@ -166,6 +192,12 @@ total: 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. version_id: type: string in: body diff --git a/placement-api-ref/source/traits.inc b/placement-api-ref/source/traits.inc new file mode 100644 index 0000000000..ca571a9f5f --- /dev/null +++ b/placement-api-ref/source/traits.inc @@ -0,0 +1,131 @@ +====== +Traits +====== + +Traits are *qualitative* characteristics of resource providers. +The classic example for traits can be requesting disk from different +providers: a user may request 80GB of disk space for an instance +(quantitative), but may also expect that the disk be SSD instead of +spinning disk (qualitative). Traits provide a way to mark that a +storage provider is SSD or spinning. + +.. note:: Traits API requests are availiable starting from version 1.6. + +List traits +=========== + +Return a list of valid trait strings according to parameters specified. + +.. rest_method:: GET /traits + +Normal Response Codes: 200 + +Request +------- + +Several query parameters are available to filter the returned list of +traits. If multiple different parameters are provided, the results +of all filters are merged with a boolean `AND`. + +.. rest_parameters:: parameters.yaml + + - name: trait_name_query + - associated: trait_associated + +Response +-------- + +.. rest_parameters:: parameters.yaml + + - traits: traits + +Response Example +---------------- + +.. literalinclude:: get-traits.json + :language: javascript + +Show traits +=========== + +Check if a trait name exists in this cloud. + +.. rest_method:: GET /traits/{name} + +Normal Response Codes: 204 + +Error response codes: itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - name: trait_name + +Response +-------- + +No body content is returned on a successful GET. + +Update traits +============= + +Insert a new custom trait. If traits already exists 204 will be returned. + +There are two kinds of traits: the standard traits and the custom traits. +The standard traits are interoperable across different Openstack cloud +deployments. The definition of standard traits comes from the `os-traits` +library. The standard traits are read-only in the placement API which means +that the user can't modify any standard traits through API. +The custom traits are used by admin users to manage the non-standard +qualitative information of resource providers. + +.. rest_method:: PUT /traits/{name} + +Normal Response Codes: 201, 204 + +Error response codes: badRequest(400) + +* `400 BadRequest` if trait name is not prefixed with `CUSTOM_` prefix. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - name: trait_name + +Response +-------- + +No body content is returned on a successful PUT. + +Delete traits +============= + +Delete the trait specified be `{name}`. Note that only custom traits can be +deleted. + +.. rest_method:: DELETE /traits/{name} + +Normal Response Codes: 204 + +Error response codes: badRequest(400), itemNotFound(404), conflict(409) + +* `400 BadRequest` if the name to delete is standard trait. +* `404 Not Found` if no such trait exists. +* `409 Conflict` if the name to delete has associations with any + ResourceProvider. + +Request +------- + +.. rest_parameters:: parameters.yaml + + - name: trait_name + +Response +-------- + +No body content is returned on a successful DELETE.