From 365618a6650c6c7d1ce6709a21d4877e9fa57c46 Mon Sep 17 00:00:00 2001
From: Grzegorz Grasza <xek@redhat.com>
Date: Fri, 17 Feb 2023 14:36:31 +0100
Subject: [PATCH] Add secret consumers documentation and release note

Change-Id: I6ef9c1307fb178158970182a6c69ca7f16d2b35d
---
 doc/source/user/index.rst                     | 41 +++++++++++++++++++
 .../secret-consumers-0253330a65b6638b.yaml    | 10 +++++
 2 files changed, 51 insertions(+)
 create mode 100644 releasenotes/notes/secret-consumers-0253330a65b6638b.yaml

diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst
index cc564e36..7e2381ab 100644
--- a/doc/source/user/index.rst
+++ b/doc/source/user/index.rst
@@ -173,6 +173,47 @@ delete the key by using its identifier. Under normal conditions, this call
 will not return anything but may raise exceptions if there are communication,
 identification, or authorization issues.
 
+**Example. Secret consumers.**
+
+.. code:: python
+
+    import myapp
+    from castellan import key_manager
+
+    manager = key_manager.API()
+
+    # Listing consumers:
+    stored_secret = self.key_mgr.get(myapp.context(), stored_id)
+    consumer_list = stored_secret.consumers  # consumers is a list of dicts
+
+    # Adding consumers:
+    consumer = {'service': 'glance',
+	        'resource_type': 'image',
+                'resource_id': 'image_id'}
+    try:
+        manager.add_consumer(myapp.context(), stored_id, consumer)
+    except NotImplementedError:
+        pass  # backends like Vault don't support adding/removing consumers
+
+    # Remove the consumer before calling secret delete without the force flag:
+    try:
+	manager.remove_consumer(myapp.context(), stored_id, consumer)
+    except NotImplementedError:
+        pass
+    manager.delete(myapp.context(), stored_key_id)
+
+    # Alternatively, force delete a secret
+    manager.delete(myapp.context(), stored_key_id, force=True)
+
+After creating a secret, we can add consumers to it. Secrets with consumers
+cannot be deleted without using the force flag.
+
+.. note::
+
+  Secret consumers are currently only avaliable for the Barbican backend.
+  https://docs.openstack.org/barbican/latest/api/reference/secret_consumers.html
+
+
 Configuring castellan
 ~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/releasenotes/notes/secret-consumers-0253330a65b6638b.yaml b/releasenotes/notes/secret-consumers-0253330a65b6638b.yaml
new file mode 100644
index 00000000..849728e3
--- /dev/null
+++ b/releasenotes/notes/secret-consumers-0253330a65b6638b.yaml
@@ -0,0 +1,10 @@
+---
+features: >
+    The Barbican API has been extended to allow secrets to have one or
+    more consumers.  This extension has been documented here:
+    https://docs.openstack.org/barbican/latest/api/reference/secret_consumers.html
+
+    This functionality has now been exposed in the castellan client.
+    Users may add, remove or delete consumers by calling new mechods on the
+    SecretManager.  Note that this functionality is only available for
+    the Barbican backend.