Add secret consumers documentation and release note

Change-Id: I6ef9c1307fb178158970182a6c69ca7f16d2b35d

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

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.