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

@@ -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

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
 ################################

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: <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: <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: <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: <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.                                                         |
++------+-----------------------------------------------------------------------------+

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