Add secret consumers documentation5.5.0

Change-Id: I55cdf4735d6936c966f7b1638714762747f6d480

3 files changed, 317 insertions, 7 deletions

diff --git a/doc/source/cli/cli_usage.rst b/doc/source/cli/cli_usage.rst
index ae8ca32..47632da 100644
--- a/doc/source/cli/cli_usage.rst
+++ b/doc/source/cli/cli_usage.rst
@@ -44,10 +44,11 @@ Subcommand actions that a user can take for secrets are:
 
 .. code-block:: bash
 
-    secret delete  Delete a secret by providing its URI.
-    secret get     Retrieve a secret by providing its URI.
-    secret list    List secrets.
-    secret store   Store a secret in Barbican.
+    secret consumer Allow operations with secret consumers.
+    secret delete   Delete a secret by providing its URI.
+    secret get      Retrieve a secret by providing its URI.
+    secret list     List secrets.
+    secret store    Store a secret in Barbican.
 
 Each subcommand takes in a different set of arguments, and the help message
 varies from one to another. The help message for **get** can be seen below.
@@ -161,10 +162,22 @@ the secret may be written to a file.  For this method the
 Secret Delete
 ~~~~~~~~~~~~~
 
+If a secret to be deleted has at least one consumer, the secret can only be deleted after removing all consumers,
+or by using the `--force` parameter
+
 .. code-block:: bash
 
     $ barbican secret delete http://localhost:9311/v1/secrets/a70a45d8-4076-42a2-b111-8893d3b92a3e
 
+.. code-block:: bash
+
+    $ barbican secret delete http://localhost:9311/v1/secrets/0207414d-c23b-47f6-9cef-f44e907ac7a8
+    Secret has consumers! Remove them first or use the force parameter to delete it.
+
+.. code-block:: bash
+
+    $ barbican secret delete --force http://localhost:9311/v1/secrets/0207414d-c23b-47f6-9cef-f44e907ac7a8
+
 Secret Update
 ~~~~~~~~~~~~~
 
@@ -188,6 +201,120 @@ Secret List
     | http://localhost:9311/v1/secrets/bb3d8c20-8ea5-4bfc-9645-c8da79c8b371 | None | 2015-04-15 20:37:37.501475+00:00 | ACTIVE | {'default': 'application/octet-stream'} | aes       |        256 | cbc  | None       |
     +-----------------------------------------------------------------------+------+----------------------------------+--------+-----------------------------------------+-----------+------------+------+------------+
 
+Secret Consumers
+----------------
+
+.. code-block:: bash
+
+    $ barbican secret consumer <action>
+
+A subcommand describing the action to be performed should follow. The
+subcommands are mostly the same as for container consumers, although
+some optional arguments might not apply.
+
+For all subcommands, the secret URI must be specified.
+Subcommand actions that a user can take for secret consumers are:
+
+.. code-block:: bash
+
+    secret consumer create  Create a secret consumer.
+    secret consumer delete  Delete a secret consumer
+    secret consumer list    List consumers of a secret.
+
+The help message for **list** can be seen below.
+
+.. code-block:: bash
+
+    $ barbican help secret consumer list
+    usage: barbican secret consumer list [-h] [-f {csv,json,table,value,yaml}] [-c COLUMN]
+                                         [--quote {all,minimal,none,nonnumeric}] [--noindent]
+                                         [--max-width <integer>] [--fit-width] [--print-empty]
+                                         [--sort-column SORT_COLUMN]
+                                         [--sort-ascending | --sort-descending] [--limit LIMIT]
+                                         [--offset OFFSET]
+                                         URI
+
+    List consumers of a secret.
+
+    positional arguments:
+    URI           The URI reference for the secret
+
+    optional arguments:
+    -h, --help          show this help message and exit
+    --limit LIMIT, -l LIMIT
+                        specify the limit to the number of items to list per page
+                        (default: 10; maximum: 100)
+    --offset OFFSET, -o OFFSET
+                        specify the page offset (default: 0)
+
+    output formatters:
+    output formatter options
+
+    -f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}
+                        the output format, defaults to table
+    -c COLUMN, --column COLUMN
+                        specify the column(s) to include, can be repeated to show multiple columns
+    --sort-column SORT_COLUMN
+                        specify the column(s) to sort the data (columns specified first have a
+                        priority, non-existing columns are ignored), can be repeated
+    --sort-ascending    sort the column(s) in ascending order
+    --sort-descending   sort the column(s) in descending order
+
+    CSV Formatter:
+    --quote {all,minimal,none,nonnumeric}
+                        when to include quotes, defaults to nonnumeric
+
+    json formatter:
+    --noindent          whether to disable indenting the JSON
+
+    table formatter:
+    --max-width <integer>
+                        Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH
+                        environment variable, but the parameter takes precedence.
+    --fit-width         Fit the table to the display width. Implied if --max-width greater than 0.
+                        Set the environment variable CLIFF_FIT_WIDTH=1 to always enable
+    --print-empty       Print empty table if there is no data to show.
+
+Secret Consumer Create
+----------------------
+
+.. code-block:: bash
+
+    $ barbican secret consumer create --service-type-name image \
+                                      --resource-type image \
+                                      --resource-id 123e4567-e89b-12d3-a456-426614174002 \
+                                      0207414d-c23b-47f6-9cef-f44e907ac7a8
+
+Consumers are uniquely defined by the three attributes (service, resource_type, resource_id).
+It is not possible to add a second consumer with exactly the same attributes. The CLI will not
+throw any error message If the creation of a new consumer with all the three same attributes
+of an existent consumer is attempted. However, the new consumer will not be actually created.
+
+Secret Consumer List
+--------------------
+
+.. code-block:: bash
+
+    $ barbican secret consumer list 0207414d-c23b-47f6-9cef-f44e907ac7a8
+    +--------------+---------------+--------------------------------------+---------------------+
+    | Service      | Resource type | Resource id                          | Created             |
+    +--------------+---------------+--------------------------------------+---------------------+
+    | image        | image         | 123e4567-e89b-12d3-a456-426614174002 | 2023-01-30T15:54:10 |
+    +--------------+---------------+--------------------------------------+---------------------+
+
+Secret Consumer Delete
+----------------------
+
+.. code-block:: bash
+
+    $ barbican secret consumer delete --service-type-name image \
+                                      --resource-type image \
+                                      --resource-id 123e4567-e89b-12d3-a456-426614174002 \
+                                      0207414d-c23b-47f6-9cef-f44e907ac7a8
+
+To delete a secret consumer, all three attributes must be provided. Attempting to delete
+a non-existing consumer will cause the CLI to throw the following error message:
+``Not Found: Consumer not found.``
 
 ACLS
 ----
diff --git a/doc/source/cli/details.rst b/doc/source/cli/details.rst
index 8f8a699..db1b788 100644
--- a/doc/source/cli/details.rst
+++ b/doc/source/cli/details.rst
@@ -57,7 +57,7 @@ barbican usage
                    [--region-name <barbican-region-name>]
                    [--barbican-api-version <barbican-api-version>] [--insecure]
                    [--os-cacert <ca-certificate>] [--os-cert <certificate>]
-                   [--os-key <key>] [--timeout <seconds>]
+                   [--os-key <key>] [--timeout <seconds>] [--collect-timing]
 
 .. _barbican_command_options:
 
@@ -489,7 +489,7 @@ barbican secret delete
 
 .. code-block:: console
 
-   usage: barbican secret delete [-h] URI
+   usage: barbican secret delete [-h] [--force] URI
 
 Delete a secret by providing its URI.
 
@@ -503,6 +503,9 @@ Delete a secret by providing its URI.
 ``-h, --help``
   show this help message and exit
 
+``--force, -f``
+  if specified, forces the deletion of secrets that have consumers.
+
 .. _barbican_secret_get:
 
 barbican secret get
@@ -820,3 +823,137 @@ Update a secret with no payload in Barbican.
 ``-h, --help``
   show this help message and exit
 
+.. _barbican_secret_consumer_create:
+
+barbican secret consumer create
+-------------------------------
+
+.. code-block:: console
+
+   usage: barbican secret consumer create [-h] --service-type-name SERVICE_TYPE_NAME
+                                               --resource-type RESOURCE_TYPE
+                                               --resource-id RESOURCE_ID URI
+
+Create a consumer for a secret.
+
+**Positional arguments:**
+
+``URI``
+  The URI reference for the secret.
+
+**Optional arguments:**
+
+``-h, --help``
+  show this help message and exit
+
+``--service-type-name SERVICE_TYPE_NAME, -s SERVICE_TYPE_NAME``
+  the service that will consume the secret
+
+``--resource-type RESOURCE_TYPE, -t RESOURCE_TYPE``
+   the type of resource that will consume the secret
+
+``--resource-id RESOURCE_ID, -i RESOURCE_ID``
+  the id of the resource that will consume the secret
+
+.. _barbican_secret_consumer_delete:
+
+barbican secret consumer delete
+-------------------------------
+
+.. code-block:: console
+
+   usage: barbican secret consumer delete [-h] --service-type-name SERVICE_TYPE_NAME
+                                               --resource-type RESOURCE_TYPE
+                                               --resource-id RESOURCE_ID URI
+
+Delete a consumer from a secret.
+
+**Positional arguments:**
+
+``URI``
+  The URI reference for the secret.
+
+**Optional arguments:**
+
+``-h, --help``
+  show this help message and exit
+
+``--service-type-name SERVICE_TYPE_NAME, -s SERVICE_TYPE_NAME``
+  the service that will consume the secret
+
+``--resource-type RESOURCE_TYPE, -t RESOURCE_TYPE``
+  the type of resource that will consume the secret
+
+``--resource-id RESOURCE_ID, -i RESOURCE_ID``
+  the id of the resource that will consume the secret
+
+.. _barbican_secret_consumer_list:
+
+barbican secret consumer list
+-----------------------------
+
+.. code-block:: console
+
+   usage: barbican secret consumer list [-h] [-f {csv,json,table,value,yaml}]
+                                        [-c COLUMN] [--quote {all,minimal,none,nonnumeric}]
+                                        [--noindent] [--max-width <integer>]
+                                        [--fit-width] [--print-empty] [--sort-column SORT_COLUMN]
+                                        [--sort-ascending | --sort-descending] [--limit LIMIT]
+                                        [--offset OFFSET]
+                                        URI
+
+List consumers of a secret.
+
+**Positional arguments:**
+
+``URI``
+  The URI reference for the secret
+
+**Optional arguments:**
+
+``-h, --help``
+  show this help message and exit
+
+``--limit LIMIT, -l LIMIT``
+  specify the limit to the number of items to list per page (default: 10; maximum: 100)
+
+``--offset OFFSET, -o OFFSET``
+  specify the page offset (default: 0)
+
+**Output formatters:**
+
+``-f {csv,json,table,value,yaml}, --format {csv,json,table,value,yaml}``
+  the output format, defaults to table
+
+``-c COLUMN, --column COLUMN``
+  specify the column(s) to include, can be repeated to show multiple columns
+
+``--sort-column SORT_COLUMN``
+  specify the column(s) to sort the data (columns specified first have a priority, non-existing columns are ignored), can be repeated
+
+``--sort-ascending``
+  sort the column(s) in ascending order
+
+``--sort-descending``
+  sort the column(s) in descending order
+
+**CSV Formatter:**
+
+``--quote {all,minimal,none,nonnumeric}``
+  when to include quotes, defaults to nonnumeric
+
+**json formatter:**
+
+``--noindent``
+  whether to disable indenting the JSON
+
+**table formatter:**
+
+``--max-width <integer>``
+  Maximum display width, <1 to disable. You can also use the CLIFF_MAX_TERM_WIDTH environment variable, but the parameter takes precedence.
+
+``--fit-width``
+  Fit the table to the display width. Implied if --max-width greater than 0. Set the environment variable CLIFF_FIT_WIDTH=1 to always enable
+
+``--print-empty``
+  Print empty table if there is no data to show.
diff --git a/doc/source/cli/usage.rst b/doc/source/cli/usage.rst
index 4bf2d38..15cf12c 100644
--- a/doc/source/cli/usage.rst
+++ b/doc/source/cli/usage.rst
@@ -186,6 +186,52 @@ Example:
 
     retrieved_container = barbican.containers.get(my_container_ref)
 
+Secret Consumers
+================
+
+Secret consumers are represented by three attributes: service, resource type and resource id.
+Callers can register secret consumers to indicate that they are using a secret.
+For instance, in the example  below, the caller creates a secret consumer to indicate that
+the created secret is being used to encrypt a specific Glance image.
+
+Secret consumers should be managed using the
+:class:`barbicanclient.secrets.SecretManager` instance in the
+`secrets` attribute of the `Client` and by the corresponding
+`register_consumer`, `remove_consumer` and `list_consumers` methods.
+
+Example:
+
+  .. code-block:: python
+
+    # Creating a secret and adding a consumer to it
+
+    secret = barbican.secrets.create(name='image encryption key',
+                                     payload='encryption_key')
+    secret.store()
+
+    barbican.secrets.register_consumer(
+        secret.secret_ref,
+        service="image",
+        resource_type="image",
+        resource_id="123e4567-e89b-12d3-a456-426614174002"
+    )
+
+    # Listing all the secret's consumers
+
+    consumers = barbican.secrets.list_consumers(secret.secret_ref)
+    for consumer in consumers:
+        print(f"Service: {consumer['service']}\t"
+              f"Resource Type: {consumer['resource_type']}\t"
+              f"Resource id: {consumer['resource_id']}")
+
+    # Removing the previously created consumer
+
+    barbican.secrets.remove_consumer(
+        secret.secret_ref,
+        service="image",
+        resource_type="image",
+        resource_id="123e4567-e89b-12d3-a456-426614174002"
+    )
 
 ACLs
 ====
@@ -325,7 +371,7 @@ Example:
     # Case 2 - Remove same users from ACL settings for each operation type
     # --------------------------------------------------------------------
 
-    # Get ACL entity from server
+    # Get ACL from server
     acl_entity = barbican.acls.get(secret_ref)
 
     # Go through each operation ACL setting and remove users from existing list