From f1046a605292498399de1a9959f1d4926ba09f22 Mon Sep 17 00:00:00 2001 From: Grzegorz Grasza Date: Fri, 9 Sep 2022 12:23:49 +0200 Subject: [PATCH] Secret consumers documentation This also adds the requirements.txt to the docs tox env, to fix the failing openstack-tox-docs CI job. Change-Id: Id920d274100078ad922f8686d29c0b9a8612ac7d --- doc/source/api/index.rst | 3 +- ...{consumers.rst => container_consumers.rst} | 16 +- doc/source/api/reference/secret_consumers.rst | 305 ++++++++++++++++++ tox.ini | 1 + 4 files changed, 316 insertions(+), 9 deletions(-) rename doc/source/api/reference/{consumers.rst => container_consumers.rst} (97%) create mode 100644 doc/source/api/reference/secret_consumers.rst diff --git a/doc/source/api/index.rst b/doc/source/api/index.rst index 33b3355c5..bd3df4cff 100644 --- a/doc/source/api/index.rst +++ b/doc/source/api/index.rst @@ -19,12 +19,13 @@ API Reference ./reference/secrets.rst ./reference/secret_types.rst + ./reference/secret_consumers.rst ./reference/secret_metadata.rst ./reference/store_backends.rst ./reference/containers.rst + ./reference/container_consumers.rst ./reference/acls.rst ./reference/quotas.rst - ./reference/consumers.rst ./reference/orders.rst ./microversions.rst ./microversion_history.rst diff --git a/doc/source/api/reference/consumers.rst b/doc/source/api/reference/container_consumers.rst similarity index 97% rename from doc/source/api/reference/consumers.rst rename to doc/source/api/reference/container_consumers.rst index 472d4efe3..bdb82d23c 100644 --- a/doc/source/api/reference/consumers.rst +++ b/doc/source/api/reference/container_consumers.rst @@ -1,6 +1,6 @@ -************************* -Consumers API - Reference -************************* +*********************************** +Container consumers API - Reference +*********************************** GET {container_ref}/consumers ############################# @@ -8,7 +8,7 @@ Lists a container's consumers. The list of consumers can be filtered by the parameters passed in via the URL. -.. _consumer_parameters: +.. _container_consumer_list_parameters: Parameters ********** @@ -93,7 +93,7 @@ Request: "previous": "http://localhost:9311/v1/containers/{container_ref}/consumers?limit=1&offset=0" } -.. _consumer_response_attributes: +.. _container_consumer_response_attributes: Response Attributes ******************* @@ -116,7 +116,7 @@ Response Attributes +-----------+---------+----------------------------------------------------------------+ -.. _consumer_status_codes: +.. _container_consumer_status_codes: HTTP Status Codes ***************** @@ -132,7 +132,7 @@ HTTP Status Codes | | delete a consumer. This can be based on the user's role. | +------+-----------------------------------------------------------------------------+ -.. _post_consumers: +.. _post_container_consumers: POST {container_ref}/consumers ############################## @@ -215,7 +215,7 @@ HTTP Status Codes +------+-----------------------------------------------------------------------------+ -.. _delete_consumer: +.. _delete_container_consumer: DELETE {container_ref}/consumers ################################ diff --git a/doc/source/api/reference/secret_consumers.rst b/doc/source/api/reference/secret_consumers.rst new file mode 100644 index 000000000..465793448 --- /dev/null +++ b/doc/source/api/reference/secret_consumers.rst @@ -0,0 +1,305 @@ +******************************** +Secret consumers API - Reference +******************************** + +GET {secret_ref}/consumers +########################## +Lists a secret's consumers. + +The list of consumers can be filtered by the parameters passed in via the URL. + +.. _secret_consumer_list_parameters: + +Parameters +********** + ++----------+---------+----------------------------------------------------------------+ +| Name | Type | Description | ++==========+=========+================================================================+ +| offset | integer | The starting index within the total list of the consumers that | +| | | you would like to retrieve. | ++----------+---------+----------------------------------------------------------------+ +| limit | integer | The maximum number of records to return (up to 100). The | +| | | default limit is 10. | ++----------+---------+----------------------------------------------------------------+ + + +Request: +******** + +.. code-block:: javascript + + GET {secret_ref}/consumers + Headers: + X-Auth-Token: + +Response: +********* + +.. code-block:: javascript + + 200 OK + + { + "total": 3, + "consumers": [ + { + "created": "2015-10-15T21:06:33.123872", + "updated": "2015-10-15T21:06:33.123878", + "status": "ACTIVE", + "service": "image", + "resource_type": "image", + "resource_id": "123e4567-e89b-12d3-a456-426614174001" + }, + { + "created": "2015-10-15T21:17:08.092408", + "updated": "2015-10-15T21:17:08.092416", + "status": "ACTIVE", + "service": "volume", + "resource_type": "volume", + "resource_id": "123e4567-e89b-12d3-a456-426614174002" + }, + { + "created": "2015-10-15T21:21:29.970365", + "updated": "2015-10-15T21:21:29.970370", + "status": "ACTIVE", + "service": "load-balancer", + "resource_type": "listener", + "resource_id": "123e4567-e89b-12d3-a456-426614174003" + } + ] + } + +Request: +******** + +.. code-block:: console + + GET {secret_ref}/consumers?limit=1&offset=1 + Headers: + X-Auth-Token: + +.. code-block:: javascript + + { + "total": 3, + "next": "http://localhost:9311/v1/secrets/{secret_ref}/consumers?limit=1&offset=2", + "consumers": [ + { + "created": "2015-10-15T21:17:08.092408", + "updated": "2015-10-15T21:17:08.092416", + "status": "ACTIVE", + "service": "volume", + "resource_type": "volume", + "resource_id": "123e4567-e89b-12d3-a456-426614174002" + } + ], + "previous": "http://localhost:9311/v1/secrets/{secret_ref}/consumers?limit=1&offset=0" + } + +.. _secret_consumer_response_attributes: + +Response Attributes +******************* + ++-----------+---------+----------------------------------------------------------------+ +| Name | Type | Description | ++===========+=========+================================================================+ +| consumers | list | Contains a list of dictionaries filled with consumer metadata. | ++-----------+---------+----------------------------------------------------------------+ +| total | integer | The total number of consumers available to the user. | ++-----------+---------+----------------------------------------------------------------+ +| next | string | A HATEOAS URL to retrieve the next set of consumers based on | +| | | the offset and limit parameters. This attribute is only | +| | | available when the total number of consumers is greater than | +| | | offset and limit parameter combined. | ++-----------+---------+----------------------------------------------------------------+ +| previous | string | A HATEOAS URL to retrieve the previous set of consumers based | +| | | on the offset and limit parameters. This attribute is only | +| | | available when the request offset is greater than 0. | ++-----------+---------+----------------------------------------------------------------+ + + +.. _secret_consumer_status_codes: + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | OK. | ++------+-----------------------------------------------------------------------------+ +| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource.| ++------+-----------------------------------------------------------------------------+ +| 403 | Forbidden. The user has been authenticated, but is not authorized to | +| | list consumers. This can be based on the user's role. | ++------+-----------------------------------------------------------------------------+ + +.. _post_secret_consumers: + +POST {secret_ref}/consumers +########################### + +Creates a consumer + +Attributes +********** + ++--------------------+---------+---------------------------------------------------------+------------+ +| Attribute Name | Type | Description | Default | ++====================+=========+=========================================================+============+ +| service | string | Consumer’s OpenStack service type. Each service should | None | +| | | preferably use it's reserved name, as shown in: | | +| | | https://service-types.openstack.org/service-types.json | | ++--------------------+---------+---------------------------------------------------------+------------+ +| resource_type | string | Name of the resource type using the secret | None | +| | | e.g. “images” or “lbaas/loadbalancers” | | ++--------------------+---------+---------------------------------------------------------+------------+ +| resource_id | string | Unique identifier for the resource using this secret. | None | ++--------------------+---------+---------------------------------------------------------+------------+ + +Request: +******** + +.. code-block:: javascript + + POST {secret_ref}/consumers + Headers: + X-Auth-Token: + Content-Type: application/json + + Content: + { + "service": "image", + "resource_type": "image", + "resource_id": "123e4567-e89b-12d3-a456-426614174000" + } + +Response: +********* + +.. code-block:: javascript + + 200 OK + + { + "status": "ACTIVE", + "updated": "2015-10-15T17:56:18.626724", + "name": "secret name", + "consumers": [ + { + "service": "image", + "resource_type": "image", + "resource_id": "123e4567-e89b-12d3-a456-426614174000" + } + ], + "created": "2015-10-15T17:55:44.380002", + "secret_ref": "http://localhost:9311/v1/secrets/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9", + "creator_id": "b17c815d80f946ea8505c34347a2aeba", + "secret_type": "opaque", + "expiration": null, + "algorithm": "aes", + "bit_length": 256, + "mode": "cbc" + } + + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | OK. | ++------+-----------------------------------------------------------------------------+ +| 400 | Bad Request. | ++------+-----------------------------------------------------------------------------+ +| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource.| ++------+-----------------------------------------------------------------------------+ +| 403 | Forbidden. The user has been authenticated, but is not authorized to | +| | create a consumer. This can be based on the user's role or the | +| | project's quota. | ++------+-----------------------------------------------------------------------------+ + + +.. _delete_secret_consumer: + +DELETE {secret_ref}/consumers +############################# + +Delete a consumer. + +Attributes +********** + ++--------------------+---------+---------------------------------------------------------+------------+ +| Attribute Name | Type | Description | Default | ++====================+=========+=========================================================+============+ +| service | string | Consumer’s OpenStack service type as shown in | None | +| | | https://service-types.openstack.org/service-types.json | | ++--------------------+---------+---------------------------------------------------------+------------+ +| resource_type | string | Name of the resource type using the secret | None | +| | | e.g. “images” or “lbaas/loadbalancers” | | ++--------------------+---------+---------------------------------------------------------+------------+ +| resource_id | string | Unique identifier for the resource using this secret. | None | ++--------------------+---------+---------------------------------------------------------+------------+ + +Request: +******** + +.. code-block:: javascript + + DELETE {secret_ref}/consumers + Headers: + X-Auth-Token: + Content-Type: application/json + + Content: + { + "service": "image", + "resource_type": "image", + "resource_id": "123e4567-e89b-12d3-a456-426614174000" + } + + +Response: +********* + +.. code-block:: javascript + + 200 OK + + { + "status": "ACTIVE", + "updated": "2015-10-15T17:56:18.626724", + "name": "secret name", + "consumers": [], + "created": "2015-10-15T17:55:44.380002", + "secret_ref": "http://localhost:9311/v1/secrets/74bbd3fd-9ba8-42ee-b87e-2eecf10e47b9", + "creator_id": "b17c815d80f946ea8505c34347a2aeba", + "secret_type": "opaque", + "expiration": null, + "algorithm": "aes", + "bit_length": 256, + "mode": "cbc" + } + + +HTTP Status Codes +***************** + ++------+-----------------------------------------------------------------------------+ +| Code | Description | ++======+=============================================================================+ +| 200 | OK. | ++------+-----------------------------------------------------------------------------+ +| 400 | Bad Request. | ++------+-----------------------------------------------------------------------------+ +| 401 | Invalid X-Auth-Token or the token doesn't have permissions to this resource.| ++------+-----------------------------------------------------------------------------+ +| 403 | Forbidden. The user has been authenticated, but is not authorized to | +| | delete a consumer. This can be based on the user's role. | ++------+-----------------------------------------------------------------------------+ +| 404 | Consumer Not Found. | ++------+-----------------------------------------------------------------------------+ diff --git a/tox.ini b/tox.ini index c53945445..089e78c44 100644 --- a/tox.ini +++ b/tox.ini @@ -69,6 +69,7 @@ commands = oslo_debug_helper -t barbican/tests {posargs} description = Build main documentation deps = -c{env:TOX_CONSTRAINTS_FILE:https://releases.openstack.org/constraints/upper/master} + -r{toxinidir}/requirements.txt -r{toxinidir}/doc/requirements.txt commands= rm -rf doc/build doc/build/doctrees