From ad14b64a7a1a3d4d1315891c486a12e0a4567846 Mon Sep 17 00:00:00 2001 From: Mauricio Harley Date: Mon, 13 Feb 2023 17:49:00 +0100 Subject: Add secret consumers documentation Change-Id: I55cdf4735d6936c966f7b1638714762747f6d480 --- doc/source/cli/cli_usage.rst | 135 +++++++++++++++++++++++++++++++++++++++-- doc/source/cli/details.rst | 141 ++++++++++++++++++++++++++++++++++++++++++- doc/source/cli/usage.rst | 48 ++++++++++++++- 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 + +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 ] [--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 + 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-api-version ] [--insecure] [--os-cacert ] [--os-cert ] - [--os-key ] [--timeout ] + [--os-key ] [--timeout ] [--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 ] + [--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 `` + 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 -- cgit v1.2.1