docs: Add Grafana generator documentation (#6227)

Co-authored-by: Gergely Bräutigam <gergely.brautigam@sap.com>

docs/api/generator/grafana.md

@@ -0,0 +1,48 @@
+The Grafana generator creates short-lived [Grafana Service Account Tokens](https://grafana.com/docs/grafana/latest/administration/service-accounts/).
+It creates or reuses a Grafana service account (not a Kubernetes ServiceAccount) and generates a new API token for it.
+When the ExternalSecret is deleted, the generated token is cleaned up automatically. Note that the Grafana service account itself is not deleted.
+
+## Authentication
+
+You can authenticate against the Grafana instance using either a service account token or basic auth credentials.
+The credentials must have sufficient permissions to create service accounts and tokens.
+See the [Grafana RBAC documentation](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/access-control/rbac-fixed-basic-role-definitions/) for details on required roles.
+
+## Output Keys
+
+The generator produces two keys:
+
+| Key     | Description                                |
+|---------|--------------------------------------------|
+| `login` | The login name of the created Grafana service account |
+| `token` | The generated Grafana service account token         |
+
+## Example Manifests
+
+Regardless of the authentication method, the credentials (token or user) must have permissions to manage service accounts and tokens in Grafana.
+The simplest approach is to use the `Admin` role.
+Alternatively, with Grafana's [fine-grained RBAC](https://grafana.com/docs/grafana/latest/administration/roles-and-permissions/access-control/), you can grant a non-Admin role the following permissions: `serviceaccounts:read`, `serviceaccounts:write`, `serviceaccounts.tokens:write`, and `serviceaccounts.tokens:delete`.
+
+### Using Token Auth
+
+Use a Grafana [Service Account Token](https://grafana.com/docs/grafana/latest/administration/service-accounts/#service-account-tokens) stored in a Kubernetes Secret, referenced via `spec.auth.token`.
+
+```yaml
+{% include 'generator-grafana.yaml' %}
+```
+
+### Using Basic Auth
+
+Use a Grafana user's username and password. The password is stored in a Kubernetes Secret and referenced via `spec.auth.basic.password`, while the username is set directly in the spec.
+
+```yaml
+{% include 'generator-grafana-basicauth.yaml' %}
+```
+
+### Example ExternalSecret
+
+An `ExternalSecret` that references the Grafana generator:
+
+```yaml
+{% include 'generator-grafana-example.yaml' %}
+```

docs/snippets/generator-grafana-basicauth.yaml

@@ -0,0 +1,15 @@
+apiVersion: generators.external-secrets.io/v1alpha1
+kind: Grafana
+metadata:
+  name: grafana-token
+spec:
+  url: https://grafana.example.com
+  auth:
+    basic:
+      username: admin
+      password:
+        name: grafana-basic-auth
+        key: password
+  serviceAccount:
+    name: my-service-account
+    role: Editor

docs/snippets/generator-grafana-example.yaml

@@ -0,0 +1,14 @@
+apiVersion: external-secrets.io/v1
+kind: ExternalSecret
+metadata:
+  name: grafana-token
+spec:
+  refreshInterval: "30m0s"
+  target:
+    name: grafana-token
+  dataFrom:
+  - sourceRef:
+      generatorRef:
+        apiVersion: generators.external-secrets.io/v1alpha1
+        kind: Grafana
+        name: grafana-token

docs/snippets/generator-grafana.yaml

@@ -0,0 +1,13 @@
+apiVersion: generators.external-secrets.io/v1alpha1
+kind: Grafana
+metadata:
+  name: grafana-token
+spec:
+  url: https://grafana.example.com
+  auth:
+    token:
+      name: grafana-admin-token
+      key: token
+  serviceAccount:
+    name: my-service-account
+    role: Viewer

hack/api-docs/mkdocs.yml

@@ -78,6 +78,7 @@ nav:
           - Cloudsmith: api/generator/cloudsmith.md
           - Cluster Generator: api/generator/cluster.md
           - Google Container Registry: api/generator/gcr.md
+          - Grafana: api/generator/grafana.md
           - Quay: api/generator/quay.md
           - Vault Dynamic Secret: api/generator/vault.md
           - Password: api/generator/password.md