chore: improve naming in examples, regenerate api doc spec (#1746)

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>

Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>

.github/workflows/ci.yml

@@ -77,6 +77,11 @@ jobs:
       - name: Checkout
         uses: actions/checkout@v3
 
+      - name: Configure Git
+        run: |
+          git config user.name "$GITHUB_ACTOR"
+          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
+
       - name: Setup Go
         uses: actions/setup-go@v3
         with:

.github/workflows/docs.yml

@@ -18,6 +18,11 @@ jobs:
         with:
           go-version-file: "go.mod"
 
+      - name: Configure Git
+        run: |
+          git config user.name "$GITHUB_ACTOR"
+          git config user.email "$GITHUB_ACTOR@users.noreply.github.com"
+
       - name: Build Docs
         run: make docs.publish
         env:

Makefile

@@ -74,7 +74,7 @@ FAIL	= (echo ${TIME} ${RED}[FAIL]${CNone} && false)
 # ====================================================================================
 # Conformance
 
-reviewable: generate manifests helm.generate helm.docs lint ## Ensure a PR is ready for review.
+reviewable: generate docs manifests helm.generate helm.docs lint ## Ensure a PR is ready for review.
 	@go mod tidy
 	@cd e2e/ && go mod tidy
 

docs/api/externalsecret.md

@@ -25,6 +25,17 @@ You can trigger a secret refresh by using kubectl or any other kubernetes api cl
 kubectl annotate es my-es force-sync=$(date +%s) --overwrite
 ```
 
+## Features
+
+Individual features are described in the [Guides section](../guides/):
+
+* [Find many secrets / Extract from structured data](../guides/getallsecrets.md)
+* [Templating](../guides/templating.md)
+* [Using Generators](../guides/generator.md)
+* [Secret Ownership and Deletion](../guides/ownership-deletion-policy.md)
+* [Key Rewriting](../guides/datafrom-rewrite.md)
+* [Decoding Strategy](../guides/decoding-strategy.md)
+
 ## Example
 
 Take a look at an annotated example to understand the design behind the

docs/api/spec.md

@@ -97,6 +97,19 @@ github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector
 <p>The SecretAccessKey is used for authentication</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>sessionTokenSecretRef</code></br>
+<em>
+github.com/external-secrets/external-secrets/apis/meta/v1.SecretKeySelector
+</em>
+</td>
+<td>
+<p>The SessionToken used for authentication
+This must be defined if AccessKeyID and SecretAccessKey are temporary credentials
+see: <a href="https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html">https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_use-resources.html</a></p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="external-secrets.io/v1beta1.AWSJWTAuth">AWSJWTAuth
@@ -1354,6 +1367,20 @@ int
 <p>Used to configure store refresh interval in seconds. Empty or 0 will default to the controller config.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>conditions</code></br>
+<em>
+<a href="#external-secrets.io/v1beta1.ClusterSecretStoreCondition">
+[]ClusterSecretStoreCondition
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Used to constraint a ClusterSecretStore to specific namespaces. Relevant only to ClusterSecretStore</p>
+</td>
+</tr>
 </table>
 </td>
 </tr>
@@ -1371,6 +1398,51 @@ SecretStoreStatus
 </tr>
 </tbody>
 </table>
+<h3 id="external-secrets.io/v1beta1.ClusterSecretStoreCondition">ClusterSecretStoreCondition
+</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#external-secrets.io/v1beta1.SecretStoreSpec">SecretStoreSpec</a>)
+</p>
+<p>
+<p>ClusterSecretStoreCondition describes a condition by which to choose namespaces to process ExternalSecrets in
+for a ClusterSecretStore instance.</p>
+</p>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>namespaceSelector</code></br>
+<em>
+<a href="https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/#labelselector-v1-meta">
+Kubernetes meta/v1.LabelSelector
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Choose namespace using a labelSelector</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>namespaces</code></br>
+<em>
+[]string
+</em>
+</td>
+<td>
+<p>Choose namespaces by name</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="external-secrets.io/v1beta1.DopplerAuth">DopplerAuth
 </h3>
 <p>
@@ -1563,6 +1635,7 @@ SecretStoreRef
 </em>
 </td>
 <td>
+<em>(Optional)</em>
 </td>
 </tr>
 <tr>
@@ -1738,6 +1811,8 @@ string
 </em>
 </td>
 <td>
+<p>SecretKey defines the key in which the controller stores
+the value. This is the key in the Kind=Secret</p>
 </td>
 </tr>
 <tr>
@@ -1750,6 +1825,22 @@ ExternalSecretDataRemoteRef
 </em>
 </td>
 <td>
+<p>RemoteRef points to the remote secret and defines
+which secret (version/property/..) to fetch.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>sourceRef</code></br>
+<em>
+<a href="#external-secrets.io/v1beta1.SourceRef">
+SourceRef
+</a>
+</em>
+</td>
+<td>
+<p>SourceRef allows you to override the source
+from which the value will pulled from.</p>
 </td>
 </tr>
 </tbody>
@@ -1781,7 +1872,8 @@ ExternalSecretDataRemoteRef
 </td>
 <td>
 <em>(Optional)</em>
-<p>Used to extract multiple key/value pairs from one secret</p>
+<p>Used to extract multiple key/value pairs from one secret
+Note: Extract does not support sourceRef.Generator or sourceRef.GeneratorRef.</p>
 </td>
 </tr>
 <tr>
@@ -1795,7 +1887,8 @@ ExternalSecretFind
 </td>
 <td>
 <em>(Optional)</em>
-<p>Used to find secrets based on tags or regular expressions</p>
+<p>Used to find secrets based on tags or regular expressions
+Note: Find does not support sourceRef.Generator or sourceRef.GeneratorRef.</p>
 </td>
 </tr>
 <tr>
@@ -1813,6 +1906,24 @@ ExternalSecretFind
 Multiple Rewrite operations can be provided. They are applied in a layered order (first to last)</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>sourceRef</code></br>
+<em>
+<a href="#external-secrets.io/v1beta1.SourceRef">
+SourceRef
+</a>
+</em>
+</td>
+<td>
+<p>SourceRef points to a store or generator
+which contains secret values ready to use.
+Use this in combination with Extract or Find pull values out of
+a specific SecretStore.
+When sourceRef points to a generator Extract or Find is not supported.
+The generator returns a static map of values</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="external-secrets.io/v1beta1.ExternalSecretDataRemoteRef">ExternalSecretDataRemoteRef
@@ -2179,6 +2290,7 @@ SecretStoreRef
 </em>
 </td>
 <td>
+<em>(Optional)</em>
 </td>
 </tr>
 <tr>
@@ -2885,6 +2997,58 @@ string
 </tr>
 </tbody>
 </table>
+<h3 id="external-secrets.io/v1beta1.GeneratorRef">GeneratorRef
+</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#external-secrets.io/v1beta1.SourceRef">SourceRef</a>)
+</p>
+<p>
+<p>GeneratorRef points to a generator custom resource.</p>
+</p>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>apiVersion</code></br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>Specify the apiVersion of the generator resource</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>kind</code></br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>Specify the Kind of the resource, e.g. Password, ACRAccessToken etc.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>name</code></br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>Specify the name of the generator resource</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="external-secrets.io/v1beta1.GenericStore">GenericStore
 </h3>
 <p>
@@ -2977,6 +3141,39 @@ string
 <p>ProjectID specifies a project where secrets are located.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>inheritFromGroups</code></br>
+<em>
+bool
+</em>
+</td>
+<td>
+<p>InheritFromGroups specifies whether parent groups should be discovered and checked for secrets.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>groupIDs</code></br>
+<em>
+[]string
+</em>
+</td>
+<td>
+<p>GroupIDs specify, which gitlab groups to pull secrets from. Group secrets are read from left to right followed by the project variables.</p>
+</td>
+</tr>
+<tr>
+<td>
+<code>environment</code></br>
+<em>
+string
+</em>
+</td>
+<td>
+<p>Environment environment_scope of gitlab CI/CD variables (Please see <a href="https://docs.gitlab.com/ee/ci/environments/#create-a-static-environment">https://docs.gitlab.com/ee/ci/environments/#create-a-static-environment</a> on how to create environments)</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="external-secrets.io/v1beta1.GitlabSecretRef">GitlabSecretRef
@@ -3718,6 +3915,20 @@ int
 <p>Used to configure store refresh interval in seconds. Empty or 0 will default to the controller config.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>conditions</code></br>
+<em>
+<a href="#external-secrets.io/v1beta1.ClusterSecretStoreCondition">
+[]ClusterSecretStoreCondition
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Used to constraint a ClusterSecretStore to specific namespaces. Relevant only to ClusterSecretStore</p>
+</td>
+</tr>
 </table>
 </td>
 </tr>
@@ -4039,7 +4250,8 @@ DopplerProvider
 </h3>
 <p>
 (<em>Appears on:</em>
-<a href="#external-secrets.io/v1beta1.ExternalSecretSpec">ExternalSecretSpec</a>)
+<a href="#external-secrets.io/v1beta1.ExternalSecretSpec">ExternalSecretSpec</a>, 
+<a href="#external-secrets.io/v1beta1.SourceRef">SourceRef</a>)
 </p>
 <p>
 <p>SecretStoreRef defines which SecretStore to fetch the ExternalSecret data.</p>
@@ -4186,6 +4398,20 @@ int
 <p>Used to configure store refresh interval in seconds. Empty or 0 will default to the controller config.</p>
 </td>
 </tr>
+<tr>
+<td>
+<code>conditions</code></br>
+<em>
+<a href="#external-secrets.io/v1beta1.ClusterSecretStoreCondition">
+[]ClusterSecretStoreCondition
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Used to constraint a ClusterSecretStore to specific namespaces. Relevant only to ClusterSecretStore</p>
+</td>
+</tr>
 </tbody>
 </table>
 <h3 id="external-secrets.io/v1beta1.SecretStoreStatus">SecretStoreStatus
@@ -4445,6 +4671,55 @@ bool
 </tr>
 </tbody>
 </table>
+<h3 id="external-secrets.io/v1beta1.SourceRef">SourceRef
+</h3>
+<p>
+(<em>Appears on:</em>
+<a href="#external-secrets.io/v1beta1.ExternalSecretData">ExternalSecretData</a>, 
+<a href="#external-secrets.io/v1beta1.ExternalSecretDataFromRemoteRef">ExternalSecretDataFromRemoteRef</a>)
+</p>
+<p>
+<p>SourceRef allows you to override the source
+from which the secret will be pulled from.
+You can define at maximum one property.</p>
+</p>
+<table>
+<thead>
+<tr>
+<th>Field</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody>
+<tr>
+<td>
+<code>storeRef</code></br>
+<em>
+<a href="#external-secrets.io/v1beta1.SecretStoreRef">
+SecretStoreRef
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+</td>
+</tr>
+<tr>
+<td>
+<code>generatorRef</code></br>
+<em>
+<a href="#external-secrets.io/v1beta1.GeneratorRef">
+GeneratorRef
+</a>
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>GeneratorRef points to a generator custom resource in</p>
+</td>
+</tr>
+</tbody>
+</table>
 <h3 id="external-secrets.io/v1beta1.TemplateEngineVersion">TemplateEngineVersion
 (<code>string</code> alias)</p></h3>
 <p>

docs/provider/aws-parameter-store.md

@@ -11,6 +11,7 @@ way users of the `SecretStore` can only access the secrets necessary.
 ``` yaml
 {% include 'aws-parameter-store.yaml' %}
 ```
+
 **NOTE:** In case of a `ClusterSecretStore`, Be sure to provide `namespace` in `accessKeyIDSecretRef` and `secretAccessKeySecretRef`  with the namespaces where the secrets reside.
 
 !!! warning "API Pricing & Throttling"
@@ -42,7 +43,7 @@ Create a IAM Policy to pin down access to secrets matching `dev-*`, for further
 
 You can store JSON objects in a parameter. You can access nested values or arrays using [gjson syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md):
 
-Consider the following JSON object that is stored in the Parameter Store key `my-json-secret`:
+Consider the following JSON object that is stored in the Parameter Store key `friendslist`:
 ``` json
 {
   "name": {"first": "Tom", "last": "Anderson"},
@@ -59,17 +60,17 @@ This is an example on how you would look up nested keys in the above json object
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: example
+  name: extract-data
 spec:
   # [omitted for brevity]
   data:
-  - secretKey: firstname
+  - secretKey: my_name
     remoteRef:
-      key: my-json-secret
+      key: friendslist
       property: name.first # Tom
   - secretKey: first_friend
     remoteRef:
-      key: my-json-secret
+      key: friendslist
       property: friends.1.first # Roger
 
 ```

docs/provider/aws-secrets-manager.md

@@ -39,7 +39,7 @@ Create a IAM Policy to pin down access to secrets matching `dev-*`.
 
 SecretsManager supports *simple* key/value pairs that are stored as json. If you use the API you can store more complex JSON objects. You can access nested values or arrays using [gjson syntax](https://github.com/tidwall/gjson/blob/master/SYNTAX.md):
 
-Consider the following JSON object that is stored in the SecretsManager key `my-json-secret`:
+Consider the following JSON object that is stored in the SecretsManager key `friendslist`:
 ``` json
 {
   "name": {"first": "Tom", "last": "Anderson"},
@@ -63,26 +63,30 @@ SecretsManager creates a new version of a secret every time it is updated. The s
 
 The `version` field on the `remoteRef` of the ExternalSecret will normally consider the version to be a `VersionStage`, but if the field is prefixed with `uuid/`, then the version will be considered a `VersionId`.
 
-So in this example, the operator will request the secret with `VersionStage` as `AWSPREVIOUS`:
+So in this example, the operator will request the same secret with different versions: `AWSCURRENT` and `AWSPREVIOUS`:
 
 ``` yaml
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: example
+  name: versioned-api-key
 spec:
   refreshInterval: 1h
   secretStoreRef:
-    name: secretstore-sample
+    name: aws-secretsmanager
     kind: SecretStore
   target:
-    name: secret-to-be-created
+    name: versioned-api-key
     creationPolicy: Owner
   data:
-  - secretKey: secret-key-to-be-managed
+  - secretKey: previous-api-key
     remoteRef:
-      key: "example/secret"
+      key: "production/api-key"
       version: "AWSPREVIOUS"
+  - secretKey: current-api-key
+    remoteRef:
+      key: "production/api-key"
+      version: "AWSCURRENT"
 ```
 
 While in this example, the operator will request the secret with `VersionId` as `abcd-1234`
@@ -91,20 +95,20 @@ While in this example, the operator will request the secret with `VersionId` as
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: example
+  name: versioned-api-key
 spec:
   refreshInterval: 1h
   secretStoreRef:
-    name: secretstore-sample
+    name: aws-secretsmanager
     kind: SecretStore
   target:
-    name: secret-to-be-created
+    name: versioned-api-key
     creationPolicy: Owner
   data:
-  - secretKey: secret-key-to-be-managed
+  - secretKey: api-key
     remoteRef:
-      key: "example/secret"
-      version: "uuid/abcd-1234"
+      key: "production/api-key"
+      version: "uuid/123e4567-e89b-12d3-a456-426614174000"
 ```
 
 --8<-- "snippets/provider-aws-access.md"

docs/provider/azure-key-vault.md

@@ -13,7 +13,7 @@ To use Managed Identity authentication, you should use [aad-pod-identity](https:
 
 We support connecting to different cloud flavours azure supports: `PublicCloud`, `USGovernmentCloud`, `ChinaCloud` and `GermanCloud`. You have to specify the `environmentType` and point to the correct cloud flavour. This defaults to `PublicCloud`.
 
-```
+```yaml
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:

docs/provider/google-secrets-manager.md

@@ -12,7 +12,7 @@ Your Google Kubernetes Engine (GKE) applications can consume GCP services like S
 
 You can find the documentation for Workload Identity [here](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity). We will walk you through how to navigate it here.
 
-Search [the document](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) for this editable values and change them to your values:  
+Search [the document](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) for this editable values and change them to your values:
 _Note: If you have installed ESO, a serviceaccount has already been created. You can either patch the existing `external-secrets` SA or create a new one that fits your needs._
 
 - `CLUSTER_NAME`: The name of your cluster
@@ -107,4 +107,3 @@ The operator will fetch the GCP Secret Manager secret and inject it as a `Kind=S
 ```
 kubectl get secret secret-to-be-created -n <namespace> | -o jsonpath='{.data.dev-secret-test}' | base64 -d
 ```
-

docs/provider/kubernetes.md

@@ -1,4 +1,4 @@
-External Secrets Operator allows to retrieve secrets from a Kubernetes Cluster - this can be either a remote cluster or the local where the operator runs in.
+External Secrets Operator allows to retrieve secrets from a Kubernetes Cluster - this can be either a remote cluster or the local one where the operator runs in.
 
 A `SecretStore` points to a **specific namespace** in the target Kubernetes Cluster. You are able to retrieve all secrets from that particular namespace given you have the correct set of RBAC permissions.
 
@@ -12,19 +12,24 @@ This provider supports the use of the `Property` field. With it you point to the
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: example
+  name: database-credentials
 spec:
   refreshInterval: 1h
   secretStoreRef:
     kind: SecretStore
-    name: example               # name of the SecretStore (or kind specified)
+    name: k8s-store             # name of the SecretStore (or kind specified)
   target:
-    name: secret-to-be-created  # name of the k8s Secret to be created
+    name: database-credentials  # name of the k8s Secret to be created
   data:
-  - secretKey: extra
+  - secretKey: username
     remoteRef:
-      key: secret-example
-      property: extra
+      key: database-credentials
+      property: username
+
+  - secretKey: password
+    remoteRef:
+      key: database-credentials
+      property: password
 ```
 
 #### find by tag & name
@@ -35,19 +40,19 @@ You can fetch secrets based on labels or names matching a regexp:
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: example
+  name: fetch-tls-and-nginx
 spec:
   refreshInterval: 1h
   secretStoreRef:
     kind: SecretStore
-    name: example
+    name: k8s-store
   target:
-    name: secret-to-be-created
+    name: fetch-tls-and-nginx
   dataFrom:
   - find:
       name:
         # match secret name with regexp
-        regexp: "key-.*"
+        regexp: "tls-.*"
   - find:
       tags:
         # fetch secrets based on label combination
@@ -66,10 +71,11 @@ You may also define it inline as base64 encoded value using the `caBundle` prope
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example
+  name: k8s-store-default-ns
 spec:
   provider:
     kubernetes:
+      # with this, the store is able to pull only from `default` namespace
       remoteNamespace: default
       server:
         url: "https://myapiserver.tld"
@@ -115,7 +121,7 @@ Create a Kubernetes secret with a client token. There are many ways to acquire s
 apiVersion: v1
 kind: Secret
 metadata:
-  name: mydefaulttoken
+  name: my-token
 data:
   token: "...."
 ```
@@ -126,18 +132,19 @@ Create a SecretStore: The `auth` section indicates that the type `token` will be
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example
+  name: k8s-store-token-auth
 spec:
   provider:
     kubernetes:
+      # with this, the store is able to pull only from `default` namespace
+      remoteNamespace: default
       server:
         # ...
       auth:
         token:
           bearerToken:
-            name: mydefaulttoken
+            name: my-token
             key: token
-      remoteNamespace: default
 ```
 
 #### Authenticating with ServiceAccount
@@ -160,16 +167,17 @@ Create a SecretStore: the `auth` section indicates that the type `serviceAccount
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example
+  name: k8s-store-sa-auth
 spec:
   provider:
     kubernetes:
+      # with this, the store is able to pull only from `default` namespace
+      remoteNamespace: default
       server:
         # ...
       auth:
         serviceAccount:
           name: "my-store"
-      remoteNamespace: default
 ```
 
 #### Authenticating with Client Certificates
@@ -186,10 +194,12 @@ Reference the `tls-secret` in the SecretStore
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example
+  name: k8s-store-cert-auth
 spec:
   provider:
     kubernetes:
+      # with this, the store is able to pull only from `default` namespace
+      remoteNamespace: default
       server:
         # ...
       auth:
@@ -200,5 +210,4 @@ spec:
           clientKey:
             name: "tls-secret"
             key: "tls.key"
-      remoteNamespace: default
-```
+```

docs/snippets/akeyless-external-secret-json.yaml

@@ -1,7 +1,7 @@
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: akeyless-external-secret-example-json
+  name: database-credentials
 spec:
   refreshInterval: 1h
 
@@ -10,10 +10,10 @@ spec:
     name: akeyless-secret-store # Must match SecretStore on the cluster
 
   target:
-    name: akeyless-secret-to-create-json # Name for the secret to be created on the cluster
+    name: database-credentials # Name for the secret to be created on the cluster
     creationPolicy: Owner
 
   # for json formatted secrets: each key in the json will be used as the secret key in the SECRET k8s target object
   dataFrom:
   - extract:
-      key: secret-name # Full path of the secret on Akeyless
+      key: database-credentials # Full path of the secret on Akeyless

docs/snippets/akeyless-external-secret.yaml

@@ -1,7 +1,7 @@
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: akeyless-external-secret-example
+  name: database-credentials
 spec:
   refreshInterval: 1h
 
@@ -10,10 +10,13 @@ spec:
     name: akeyless-secret-store # Must match SecretStore on the cluster
 
   target:
-    name: akeyless-secret-to-create # Name for the secret to be created on the cluster
+    name: database-credentials # Name for the secret to be created on the cluster
     creationPolicy: Owner
 
   data:
-    - secretKey: secretKey # Key given to the secret to be created on the cluster
+    - secretKey: username # Key given to the secret to be created on the cluster
       remoteRef:
-        key: secret-name # Full path of the secret on Akeyless
+        key: db-username  # Full path of the secret on Akeyless
+    - secretKey: password # Key given to the secret to be created on the cluster
+      remoteRef:
+        key: db-password  # Full path of the secret on Akeyless

docs/snippets/aws-parameter-store.yaml

@@ -1,14 +1,14 @@
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: secretstore-sample
+  name: parameterstore
 spec:
   provider:
     aws:
       service: ParameterStore
       # define a specific role to limit access
       # to certain secrets
-      role: iam-role
+      role: arn:aws:iam::123456789012:role/external-secrets
       region: eu-central-1
       auth:
         secretRef:

docs/snippets/aws-sm-external-secret.yaml

@@ -5,17 +5,17 @@ metadata:
 spec:
   refreshInterval: 1m
   secretStoreRef:
-    name: secretstore-sample
+    name: aws-secretsmanager
     kind: SecretStore
   target:
-    name: secret-to-be-created
+    name: friends
     creationPolicy: Owner
   data:
-  - secretKey: firstname
+  - secretKey: my_name
     remoteRef:
-      key: my-json-secret
+      key: friendslist
       property: name.first # Tom
   - secretKey: first_friend
     remoteRef:
-      key: my-json-secret
+      key: friendslist
       property: friends.1.first # Roger

docs/snippets/aws-sm-store.yaml

@@ -1,16 +1,16 @@
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: secretstore-sample
+  name: aws-secretsmanager
 spec:
   provider:
     aws:
       service: SecretsManager
       # define a specific role to limit access
       # to certain secrets.
-      # role is a optional field that 
+      # role is a optional field that
       # can be omitted for test purposes
-      role: iam-role
+      role: arn:aws:iam::123456789012:role/external-secrets
       region: eu-central-1
       auth:
         secretRef:

docs/snippets/azkv-datafrom-external-secret.yaml

@@ -1,27 +1,31 @@
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: example
+  name: all-secrets
 spec:
-  refreshInterval: 1h           # rate SecretManager pulls Azure Key Vault
+  refreshInterval: 1h           # rate ESO pulls Azure Key Vault
   secretStoreRef:
     kind: SecretStore
-    name: example               # name of the SecretStore (or kind specified)
+    name: azure-store           # name of the SecretStore (or kind specified)
   target:
-    name: secret-to-be-created  # name of the k8s Secret to be created
+    name: all-secrets           # name of the k8s Secret to be created
     creationPolicy: Owner
   dataFrom:
+  # find all secrets starting with dev-
   - find:
       name:
-        regexp: "^example"
+        regexp: "^dev"
+  # find all secrets with tags
   - find:
       tags:
-        author: seb
         environment: dev
-  # secret value is in JSON format and we unmarshall it into multiple key/values in k8s secret
-  - extract: 
-      key: test
-  # get all tags and the tags in JSON format will be unmarshall 
-  - extract: 
-      key: test
+
+  # extract data from a json value
+  - extract:
+      key: database-credentials
+
+  # fetch tags from `database-credentials`
+  # and store them as individual keys in a secret
+  - extract:
+      key: database-credentials
       metadataPolicy: Fetch

docs/snippets/azkv-external-secret.yaml

@@ -1,49 +1,49 @@
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: example-external-secret
+  name: database-credentials
 spec:
   refreshInterval: 1h
   secretStoreRef:
     kind: SecretStore
-    name: example-secret-store
+    name: azure-store
 
   target:
-    name: secret-to-be-created
+    name: database-credentials
     creationPolicy: Owner
 
   data:
   # name of the SECRET in the Azure KV (no prefix is by default a SECRET)
-  - secretKey: dev-secret-test
+  - secretKey: database-username
     remoteRef:
-      key: dev-secret-test
+      key: database-username
 
   # explicit type and name of secret in the Azure KV
-  - secretKey: dev-another-secret-test
+  - secretKey: database-password
     remoteRef:
-      key: secret/dev-secret-test
+      key: secret/database-password
 
   # metadataPolicy to fetch all the tags in JSON format
-  - secretKey: dev-secret-test
+  - secretKey: database-credentials-metadata
     remoteRef:
-      key: dev-secret-test
+      key: database-credentials
       metadataPolicy: Fetch
 
   # metadataPolicy to fetch a specific tag which name must be in property
-  - secretKey: dev-secret-test
+  - secretKey: database-credentials
     remoteRef:
-      key: dev-secret-test
+      key: database-credentials
       metadataPolicy: Fetch
-      property: tagname
+      property: environment
 
   # type/name of certificate in the Azure KV
   # raw value will be returned, use templating features for data processing
-  - secretKey: dev-cert-test
+  - secretKey: db-client-cert
     remoteRef:
-      key: cert/dev-cert-test
+      key: cert/db-client-cert
 
   # type/name of the public key in the Azure KV
   # the key is returned PEM encoded
-  - secretKey: dev-key-test
+  - secretKey: encryption-pubkey
     remoteRef:
-      key: key/dev-key-test
+      key: key/encryption-pubkey

docs/snippets/azkv-pkcs12-cert-external-secret.yaml

@@ -2,23 +2,23 @@
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: mycert
+  name: tls-client-credentials
 spec:
-  refreshInterval: 24h
+  refreshInterval: 1h
   secretStoreRef:
-    kind: ClusterSecretStore
-    name: kv-mycert
+    kind: SecretStore
+    name: azure-store
   target:
     template:
       type: kubernetes.io/tls
       engineVersion: v2
       data:
-        tls.crt: "{{ .mycert | b64dec | pkcs12cert }}"
-        tls.key: "{{ .mycert | b64dec | pkcs12key }}"
+        tls.crt: "{{ .tls | b64dec | pkcs12cert }}"
+        tls.key: "{{ .tls | b64dec | pkcs12key }}"
   data:
-  - secretKey: mycert
+  - secretKey: tls
     remoteRef:
       # Azure Key Vault certificates must be fetched as secret/cert-name
-      key: secret/mycert
+      key: secret/tls-client-credentials
 
 {% endraw %}

docs/snippets/azkv-secret-store-mi.yaml

@@ -1,7 +1,7 @@
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example-secret-store
+  name: azure-store
 spec:
   provider:
     # provider type: azure keyvault

docs/snippets/azkv-secret-store.yaml

@@ -1,7 +1,7 @@
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example-secret-store
+  name: azure-store
 spec:
   provider:
     # provider type: azure keyvault

docs/snippets/azkv-workload-identity-mounted.yaml

@@ -10,7 +10,7 @@ metadata:
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example-secret-store
+  name: azure-store
 spec:
   provider:
     azurekv:

docs/snippets/azkv-workload-identity.yaml

@@ -10,7 +10,7 @@ metadata:
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example-secret-store
+  name: azure-store
 spec:
   provider:
     azurekv:

docs/snippets/full-external-secret.yaml

@@ -13,9 +13,9 @@ metadata:
 
 spec:
 
-  # SecretStoreRef defines which SecretStore to use when fetching the secret data
+  # Optional, SecretStoreRef defines the default SecretStore to use when fetching the secret data.
   secretStoreRef:
-    name: secret-store-name
+    name: aws-store
     kind: SecretStore  # or ClusterSecretStore
 
   # RefreshInterval is the amount of time before the values reading again from the SecretStore provider
@@ -30,7 +30,7 @@ spec:
     # The secret name of the resource
     # Defaults to .metadata.name of the ExternalSecret
     # It is immutable
-    name: my-secret
+    name: application-config
 
     # Enum with values: 'Owner', 'Merge', or 'None'
     # Default value of 'Owner'
@@ -55,47 +55,58 @@ spec:
       # Use inline templates to construct your desired config file that contains your secret
       data:
         config.yml: |
-          endpoints:
-          - https://{{ .data.user }}:{{ .data.password }}@api.exmaple.com
+          database:
+            connection: postgres://{{ .username }}:{{ .password }}@{{ .database_host }}:5432/payments
 
       # 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...
       templateFrom:
       - configMap:
-          name: alertmanager
+          name: application-config-tmpl
           items:
-          - key: alertmanager.yaml
+          - key: config.yml
 
   # Data defines the connection between the Kubernetes Secret keys and the Provider data
   data:
-    - secretKey: secret-key-to-be-managed
+    - secretKey: username
       remoteRef:
-        key: provider-key
-        version: provider-key-version
-        property: provider-key-property
+        key: database-credentials
+        version: v1
+        property: username
         decodingStrategy: None # can be None, Base64, Base64URL or Auto
 
+      # define the source of the secret. Can be a SecretStore or a Generator kind
+      sourceRef:
+        # point to a SecretStore that should be used to fetch a secret.
+        # must be defined if no spec.secretStoreRef is defined.
+        storeRef:
+          name: aws-secretstore
+          kind: ClusterSecretStore
+
+        # point to a generator resource that provides the secret value
+        generatorRef:
+          apiVersion: generators.external-secrets.io/v1alpha1
+          kind: Password
+          name: db-password
+
   # Used to fetch all properties from the Provider key
   # If multiple dataFrom are specified, secrets are merged in the specified order
   dataFrom:
   - extract:
-      key: provider-key
-      version: provider-key-version
-      property: provider-key-property
+      key: database-credentials
+      version: v1
+      property: data
       conversionStrategy: Default
       decodingStrategy: Auto
     rewrite:
     - regexp:
-        source: "foo"
-        target: "bar"
-    - regexp:
         source: "exp-(.*?)-ression"
-        target: "rewriting-$1-with-groups"
+        target: "rewriting-${1}-with-groups"
   - find:
       path: path-to-filter
           source: "exp-(.*?)-ression"
-          target: "rewriting-$1-with-groups"
+          target: "rewriting-${1}-with-groups"
       name:
         regexp: ".*foobar.*"
       tags:
@@ -106,7 +117,6 @@ spec:
     - regexp:
         source: "foo"
         target: "bar"
-    - regexp:
 
 status:
   # refreshTime is the time and date the external secret was fetched and

docs/snippets/gcpsm-external-secret.yaml

@@ -1,16 +1,19 @@
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: example
+  name: database-credentials
 spec:
-  refreshInterval: 1h           # rate SecretManager pulls GCPSM
+  refreshInterval: 1h             # rate SecretManager pulls GCPSM
   secretStoreRef:
     kind: SecretStore
-    name: example               # name of the SecretStore (or kind specified)
+    name: gcp-store               # name of the SecretStore (or kind specified)
   target:
-    name: secret-to-be-created  # name of the k8s Secret to be created
+    name: database-credentials    # name of the k8s Secret to be created
     creationPolicy: Owner
   data:
-  - secretKey: dev-secret-test  # name of the GCPSM secret key
+  - secretKey: database_username
     remoteRef:
-      key: dev-secret-test
+      key: database_username      # name of the GCPSM secret key
+  - secretKey: database_password
+    remoteRef:
+      key: database_password      # name of the GCPSM secret key

docs/snippets/gcpsm-pod-wi-secret-store.yaml

@@ -1,8 +1,8 @@
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example
+  name: gcp-store
 spec:
   provider:
     gcpsm:
-      projectID: pid
+      projectID: alphabet-123

docs/snippets/gcpsm-secret-store.yaml

@@ -1,7 +1,7 @@
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: example
+  name: gcp-store
 spec:
   provider:
       gcpsm:                                  # gcpsm provider
@@ -10,4 +10,4 @@ spec:
             secretAccessKeySecretRef:
               name: gcpsm-secret              # secret name containing SA key
               key: secret-access-credentials  # key name containing SA key
-        projectID: myproject                  # name of Google Cloud project
+        projectID: alphabet-123               # name of Google Cloud project

docs/snippets/gcpsm-wi-secret-store.yaml

@@ -1,17 +1,17 @@
 apiVersion: external-secrets.io/v1beta1
 kind: ClusterSecretStore
 metadata:
-  name: example
+  name: gcp-store
 spec:
   provider:
     gcpsm:
-      projectID: my-project
+      projectID: alphabet-123
       auth:
         workloadIdentity:
           # name of the cluster region
           clusterLocation: europe-central2
           # name of the GKE cluster
-          clusterName: example-workload-identity
+          clusterName: alpha-cluster-42
           # projectID of the cluster (if omitted defaults to spec.provider.gcpsm.projectID)
           clusterProjectID: my-cluster-project
           # reference the sa from above

docs/snippets/ibm-es-types.yaml

@@ -25,9 +25,9 @@ spec:
       key: public_cert/zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz
       property: certificate
   - secretKey: prvt_cert
-      remoteRef:
-        key: private_cert/zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz
-        property: certificate
+    remoteRef:
+      key: private_cert/zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz
+      property: certificate
   - secretKey: kv_without_key
     remoteRef:
       key: kv/zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz
@@ -39,5 +39,3 @@ spec:
     remoteRef:
       key: kv/zzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz
       property: 'key.path'
-  dataFrom:
-

docs/snippets/ibm-external-secret.yaml

@@ -1,16 +1,19 @@
 apiVersion: external-secrets.io/v1beta1
 kind: ExternalSecret
 metadata:
-  name: external-secret-sample
+  name: database-credentials
 spec:
   refreshInterval: 60m
   secretStoreRef:
-    name: secretstore-sample
+    name: ibm-store
     kind: SecretStore
   target:
-    name: secret-to-be-created
+    name: database-credentials
     creationPolicy: Owner
   data:
-  - secretKey: test
+  - secretKey: username
     remoteRef:
-      key: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
+      key: database_user
+  - secretKey: password
+    remoteRef:
+      key: database_password

docs/snippets/ibm-secret-store.yaml

@@ -1,11 +1,11 @@
 apiVersion: external-secrets.io/v1beta1
 kind: SecretStore
 metadata:
-  name: secretstore-sample
+  name: ibm-store
 spec:
   provider:
     ibm:
-      serviceUrl: "https://SECRETS_MANAGER_ID.REGION.secrets-manager.appdomain.cloud"
+      serviceUrl: "https://<SECRETS_MANAGER_ID>.<REGION>.secrets-manager.appdomain.cloud"
       auth:
         containerAuth:
           profile: "test container auth profile"

hack/api-docs/Makefile

@@ -53,7 +53,7 @@ build: image generate $(SOURCES)
 		--rm \
 		--user $(UID):$(GID) \
 		$(MKDOCS_IMAGE) \
-		/bin/bash -c "cd /repo && git config user.email "docs@external-secrets.io" && git config user.name "Docs" && $(MIKE) deploy --ignore --update-aliases -F hack/api-docs/mkdocs.yml $(DOCS_VERSION) $(DOCS_ALIAS);"
+		/bin/bash -c "cd /repo && $(MIKE) deploy --ignore --update-aliases -F hack/api-docs/mkdocs.yml $(DOCS_VERSION) $(DOCS_ALIAS);"
 .PHONY: build.publish
 build.publish: image generate $(SOURCES)
 	mkdir -p $(GENROOT)
@@ -63,10 +63,10 @@ build.publish: image generate $(SOURCES)
 		--rm \
 		--user $(UID):$(GID) \
 		$(MKDOCS_IMAGE) \
-		/bin/bash -c "cd /repo && git config user.email "docs@external-secrets.io" && git config user.name "Docs" && $(MIKE) deploy --update-aliases -p -F hack/api-docs/mkdocs.yml $(DOCS_VERSION) $(DOCS_ALIAS);"
+		/bin/bash -c "cd /repo && $(MIKE) deploy --update-aliases -p -F hack/api-docs/mkdocs.yml $(DOCS_VERSION) $(DOCS_ALIAS);"
 .PHONY: generate
 generate:
-	./generate.sh $(SRCDIR)/spec.md
+	./generate.sh $(SRCDIR)/api/spec.md
 
 .PHONY: clean
 clean: