diff options
author | Andrey Volkov <avolkov@mirantis.com> | 2017-06-14 14:41:33 +0300 |
---|---|---|
committer | Andrey Volkov <avolkov@mirantis.com> | 2017-07-18 12:44:04 +0300 |
commit | 67028cb732ccee70bc2094c1111652b9a175e3c8 (patch) | |
tree | e3895ac10e5bbb605dc88fbe15c120048a0b6dff /placement-api-ref | |
parent | e2d0442b5eea1371367ad3378e6701f425b92afe (diff) | |
download | nova-67028cb732ccee70bc2094c1111652b9a175e3c8.tar.gz |
[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
Diffstat (limited to 'placement-api-ref')
-rw-r--r-- | placement-api-ref/source/get-traits.json | 7 | ||||
-rw-r--r-- | placement-api-ref/source/index.rst | 1 | ||||
-rw-r--r-- | placement-api-ref/source/parameters.yaml | 32 | ||||
-rw-r--r-- | placement-api-ref/source/traits.inc | 131 |
4 files changed, 171 insertions, 0 deletions
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. |