docs: add HashiCorp Vault Generator documentation (#2123)

* docs: add HashiCorp Vault Generator documentation

Document the Vault dynamic secrets Generator from #2074.

Signed-off-by: Kristián Leško <kristian.lesko@gooddata.com>

* fix: add vault generator to nav

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

---------

Signed-off-by: Kristián Leško <kristian.lesko@gooddata.com>
Signed-off-by: Moritz Johner <beller.moritz@googlemail.com>
Co-authored-by: Moritz Johner <beller.moritz@googlemail.com>

docs/api/generator/vault.md

@@ -0,0 +1,19 @@
+The `VaultDynamicSecret` Generator provides an interface to HashiCorp Vault's
+[Secrets engines](https://developer.hashicorp.com/vault/docs/secrets). Specifically,
+it enables obtaining dynamic secrets not covered by the
+[HashiCorp Vault provider](../../provider/hashicorp-vault.md).
+
+Any Vault authentication method supported by the provider can be used here
+(`provider` block of the spec).
+
+All secrets engines should be supported by providing matching `path`, `method`
+and `parameters` values to the Generator spec (see example below).
+
+Exact output keys and values depend on the Vault secret engine used; nested values
+are stored into the resulting Secret in JSON format.
+
+## Example manifest
+
+```yaml
+{% include 'generator-vault.yaml' %}
+```

docs/provider/hashicorp-vault.md

@@ -2,9 +2,11 @@
 
 ## Hashicorp Vault
 
-External Secrets Operator integrates with [HashiCorp Vault](https://www.vaultproject.io/) for secret
-management. Vault itself implements lots of different secret engines, as of now we only support the
-[KV Secrets Engine](https://www.vaultproject.io/docs/secrets/kv).
+External Secrets Operator integrates with [HashiCorp Vault](https://www.vaultproject.io/) for secret management.
+
+The [KV Secrets Engine](https://www.vaultproject.io/docs/secrets/kv) is the only
+one supported by this provider. For other secrets engines, please refer to the
+[Vault Generator](../api/generator/vault.md).
 
 ### Example
 

docs/snippets/generator-vault.yaml

@@ -0,0 +1,38 @@
+{% raw %}
+
+---
+apiVersion: generators.external-secrets.io/v1alpha1
+kind: VaultDynamicSecret
+metadata:
+  name: "pki-example"
+spec:
+  path: "/pki/issue/example-dot-com"
+  method: "POST"
+  parameters:
+    common_name: "localhost"
+    ip_sans: "127.0.0.1,127.0.0.11"
+  provider:
+    server: "http://vault.default.svc.cluster.local:8200"
+    auth:
+      kubernetes:
+        mountPath: "kubernetes"
+        role: "external-secrets-operator"
+        serviceAccountRef:
+          name: "default"
+---
+apiVersion: external-secrets.io/v1beta1
+kind: ExternalSecret
+metadata:
+  name: "pki-example-com"
+spec:
+  refreshInterval: "768h"
+  target:
+    name: pki-example-com
+  dataFrom:
+  - sourceRef:
+      generatorRef:
+        apiVersion: generators.external-secrets.io/v1alpha1
+        kind: VaultDynamicSecret
+        name: "pki-example"
+
+{% endraw %}

hack/api-docs/mkdocs.yml

@@ -24,8 +24,8 @@ plugins:
   - macros:
       include_dir: docs/snippets
 copyright: |
-  &copy; 2022 The external-secrets Authors.<br/>
-  &copy; 2022 The Linux Foundation. All rights reserved.<br/><br/>
+  &copy; 2023 The external-secrets Authors.<br/>
+  &copy; 2023 The Linux Foundation. All rights reserved.<br/><br/>
   The Linux Foundation has registered trademarks and uses trademarks.<br/>
   For a list of trademarks of The Linux Foundation, please see our <a href="https://www.linuxfoundation.org/trademark-usage/">Trademark Usage page</a>.
 extra:
@@ -55,6 +55,7 @@ nav:
       - Azure Container Registry: api/generator/acr.md
       - AWS Elastic Container Registry: api/generator/ecr.md
       - Google Container Registry: api/generator/gcr.md
+      - Vault Dynamic Secret: api/generator/vault.md
       - Password: api/generator/password.md
       - Fake: api/generator/fake.md
     - Reference Docs: