Adding documentation for populating Kubernetes Secret with metadata f… (#2487)

* Adding documentation for populating Kubernetes Secret with metadata from IBM Cloud Secrets Manager

Signed-off-by: Vishal Singha Roy <vishal.singha.roy@ibm.com>

* Rephrasing a few lines

Signed-off-by: Vishal Singha Roy <vishal.singha.roy@ibm.com>

---------

Signed-off-by: Vishal Singha Roy <vishal.singha.roy@ibm.com>
Co-authored-by: Vishal Singha Roy <vishal.singha.roy@ibm.com>

docs/provider/ibm-secrets-manager.md

@@ -208,3 +208,70 @@ The operator will fetch the IBM Secret Manager secret and inject it as a `Kind=S
 ```
 kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath='{.data.test}' | base64 -d
 ```
+
+### Populating the Kubernetes secret with metadata from IBM Secrets Manager Provider
+ESO can add metadata while creating or updating a Kubernetes secret to be reflected in its labels or annotations. The metadata could be any of the fields that are supported and returned in the response by IBM Secrets Manager.
+
+In order for the user to opt-in to adding metadata to secret, an existing optional field `spec.dataFrom.extract.metadataPolicy` can be be set to `Fetch`, its default value being `None`. In addition to this, templating provided be ESO can be leveraged to specify the key-value pairs of the resultant secrets' labels and annotation.
+
+In order for the required metadata to be populated in the Kubernetes secret, combination of below should be provided in the External Secrets resource:
+1. The required metadata should be specified under `template.metadata.labels` or `template.metadata.annotations`.
+2. The required secret data should be specified under `template.data`.
+3. The spec.dataFrom.extract should be specified with details of the Secrets Manager secret with `spec.dataFrom.extract.metadataPolicy` set to `Fetch`.
+Below is an example, where `secret_id` and `updated_at` are the metadata of a secret in IBM Secrets Manager.:
+
+```yaml
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: database-credentials
+  namespace: external-secrets
+spec:
+  dataFrom:
+  - extract:
+      key: username_password/<SECRET_ID>
+      metadataPolicy: Fetch           # leveraging optional parameter, defaults to None
+    secretKey: username
+  secretStoreRef:
+    kind: SecretStore
+    name: ibm-store
+  target:
+    name: database-credentials
+    template:
+      engineVersion: v2
+      data:
+        secret: "{{ .password }}" 
+      metadata:
+        annotations:
+          secret_id: "{{ .id }}"     # adding metadata key whose value would be added to the secret as a label
+          updated_at: "{{ .updated_at }}"
+```
+
+While the secret is being reconciled, it will have the secret data along with the required annotations. Below is the example of the secret after reconciliation:
+
+```yaml
+apiVersion: v1
+data:
+  secret: OHE0MFV5MGhQb2FmRjZTOGVva3dPQjRMeVZXeXpWSDlrSWgyR1BiVDZTMyc=
+immutable: false
+kind: Secret
+metadata:
+  annotations:
+    reconcile.external-secrets.io/data-hash: 02217008d13ed228e75cf6d26fe74324
+  creationTimestamp: "2023-05-04T08:41:24Z"
+  annotations:
+    secret_id: 1234
+    updated_at: 2023-05-04T08:57:19Z
+  name: database-credentials
+  namespace: external-secrets
+  ownerReferences:
+  - apiVersion: external-secrets.io/v1beta1
+    blockOwnerDeletion: true
+    controller: true
+    kind: ExternalSecret
+    name: database-credentials
+    uid: c2a018e7-1ac3-421b-bd3b-d9497204f843
+  resourceVersion: "1803567"
+  uid: f5dff604-611b-4d41-9d65-b860c61a0b8d
+type: Opaque
+```