docs: enhance the example of PushSecret/ClusterPushSecret (#4872)

Signed-off-by: Ahmed AbouZaid <6760103+aabouzaid@users.noreply.github.com>
Co-authored-by: Gergely Brautigam <182850+Skarlso@users.noreply.github.com>

docs/api/clusterpushsecret.md

@@ -10,3 +10,15 @@ Below is an example of the `ClusterPushSecret` in use.
 ```yaml
 {% include 'full-cluster-push-secret.yaml' %}
 ```
+
+The result of the created Secret object will look like:
+
+```yaml
+# The destination secret that will be templated and pushed by ClusterPushSecret.
+apiVersion: v1
+kind: Secret
+metadata:
+  name: destination-secret
+stringData:
+  best-pokemon-dst: "PIKACHU is the really best!"
+```

docs/api/pushsecret.md

@@ -6,11 +6,27 @@ The `PushSecret` is namespaced and it describes what data should be pushed to th
 * you can specify what secret keys should be pushed by using `spec.data`.
 * you can also template the resulting property values using [templating](#templating).
 
+## Example
+
+Below is an example of the `PushSecret` in use.
+
 ``` yaml
 {% include 'full-pushsecret.yaml' %}
 ```
 
-## Templating
+The result of the created Secret object will look like:
+
+```yaml
+# The destination secret that will be templated and pushed by PushSecret.
+apiVersion: v1
+kind: Secret
+metadata:
+  name: destination-secret
+stringData:
+  best-pokemon-dst: "PIKACHU is the really best!"
+```
+
+## Template
 
 When the controller reconciles the `PushSecret` it will use the `spec.template` as a blueprint to construct a new property.
 You can use golang templates to define the blueprint and use template functions to transform the defined properties.

docs/snippets/full-cluster-push-secret.yaml

@@ -1,4 +1,13 @@
 {% raw %}
+---
+# The source secret that will be pushed to the destination secret by ClusterPushSecret.
+apiVersion: v1
+kind: Secret
+metadata:
+  name: source-secret
+stringData:
+  best-pokemon-src: "Pikachu"
+---
 apiVersion: external-secrets.io/v1alpha1
 kind: ClusterPushSecret
 metadata:
@@ -30,7 +39,7 @@ spec:
         kind: SecretStore
     selector:
       secret:
-        name: pokedex-credentials # Source Kubernetes secret to be pushed
+        name: source-secret # Source Kubernetes secret to be pushed
       # Alternatively, you can point to a generator that produces values to be pushed
       generatorRef:
         apiVersion: external-secrets.io/v1alpha1
@@ -41,10 +50,12 @@ spec:
         annotations: { }
         labels: { }
       data:
-        best-pokemon: "{{ .best-pokemon | toString | upper }} is the really best!"
-      # Uses an existing template from configmap
-      # Secret is fetched, merged and templated within the referenced configMap data
-      # It does not update the configmap, it creates a secret with: data["alertmanager.yml"] = ...result...
+        # If the key source secret key has dashes, then it cannot be accessed directly,
+        # and the "index" function should be used.
+        best-pokemon: "{{ index . \"best-pokemon-src\" | toString | upper }} is the really best!"
+      # Also, it's possible to use an existing template from configmap where Secret is fetched, 
+      # merged and templated within the referenced configMap data.
+      # It does not update the configmap, it creates a secret with: data["config.yml"] = ...result...
       templateFrom:
         - configMap:
             name: application-config-tmpl
@@ -53,10 +64,11 @@ spec:
     data:
       - conversionStrategy: None # Also supports the ReverseUnicode strategy
         match:
-          secretKey: best-pokemon # Source Kubernetes secret key to be pushed
+          # The secretKey is used within ClusterPushSecret (it should match key under spec.pushSecretSpec.template.data)
+          secretKey: best-pokemon
           remoteRef:
-            remoteKey: my-first-parameter # Remote reference (where the secret is going to be pushed)
-
+            remoteKey: destination-secret # The destination secret object name (where the secret is going to be pushed)
+            property: best-pokemon-dst # The key within the destination secret object.
 status:
   # This will list any namespaces where the creation of the ExternalSecret failed
   # This will not list any issues with the ExternalSecrets, you will have to check the

docs/snippets/full-pushsecret.yaml

@@ -1,4 +1,13 @@
 {% raw %}
+---
+# The source secret that will be pushed to the destination secret by PushSecret.
+apiVersion: v1
+kind: Secret
+metadata:
+  name: source-secret
+stringData:
+  best-pokemon-src: "Pikachu"
+---
 apiVersion: external-secrets.io/v1alpha1
 kind: PushSecret
 metadata:
@@ -24,10 +33,12 @@ spec:
       annotations: { }
       labels: { }
     data:
-      best-pokemon: "{{ .best-pokemon | toString | upper }} is the really best!"
-    # Uses an existing template from configmap
-    # Secret is fetched, merged and templated within the referenced configMap data
-    # It does not update the configmap, it creates a secret with: data["alertmanager.yml"] = ...result...
+      # If the key source secret key has dashes, then it cannot be accessed directly,
+      # and the "index" function should be used.
+      best-pokemon: "{{ index . \"best-pokemon-src\" | toString | upper }} is the really best!"
+    # Also, it's possible to use an existing template from configmap where Secret is fetched, 
+    # merged and templated within the referenced configMap data.
+    # It does not update the configmap, it creates a secret with: data["config.yml"] = ...result...
     templateFrom:
       - configMap:
           name: application-config-tmpl
@@ -36,7 +47,9 @@ spec:
   data:
     - conversionStrategy: None # Also supports the ReverseUnicode strategy
       match:
-        secretKey: best-pokemon # Source Kubernetes secret key to be pushed
+        # The secretKey is used within PushSecret (it should match key under spec.template.data)
+        secretKey: best-pokemon
         remoteRef:
-          remoteKey: my-first-parameter # Remote reference (where the secret is going to be pushed)
+          remoteKey: destination-secret # The destination secret object name (where the secret is going to be pushed)
+          property: best-pokemon-dst # The key within the destination secret object.
 {% endraw %}