docs: added docs for confguiring caching when provisioning zitadel on k8 (#11492)

2026-10-21 15:04:25 +00:00 · 2026-02-11 07:46:16 +01:00
parent 5a2181bcec
commit e545d7c5b1
2 changed files with 109 additions and 1 deletions
@@ -0,0 +1,107 @@
+---
+title: Caching
+sidebar_label: Caching
+---
+
+
+
+This guide explains how to connect Zitadel caches to Redis or Valkey on Kubernetes.
+
+<Callout type="info">
+Caching is an experimental beta feature. See the [Caches](/self-hosting/manage/cache) page for behavior, objects, and tuning guidance.
+</Callout>
+
+Zitadel supports Redis or any Redis-compatible store (for example, Valkey) in standalone mode. Sentinel and Redis Cluster are not supported because the cache connector expects a single endpoint and does not implement cluster routing or sentinel failover logic.
+
+<Callout type="note">
+Zitadel supports server-auth TLS (`EnableTLS: true`) but does not support client certificates/mTLS for cache connections.
+</Callout>
+
+Each cache uses its own Redis database index. Set `DBOffset` so Zitadel-owned indexes do not overlap with other applications. Zitadel issues `FLUSHDB` on its cache databases, so sharing an index with other apps is unsafe.
+
+## Connect without authentication (development only)
+
+```yaml
+zitadel:
+  configmapConfig:
+    Caches:
+      Connectors:
+        Redis:
+          Enabled: true
+          Addr: "redis-master.caching.svc.cluster.local:6379"
+          DBOffset: 10
+      Instance:
+        Connector: "redis"
+        MaxAge: 1h
+        LastUseAge: 10m
+      Organization:
+        Connector: "redis"
+        MaxAge: 1h
+        LastUseAge: 10m
+```
+
+Use this only on isolated clusters where the Redis endpoint does not require authentication.
+
+## Connect with password from a Kubernetes Secret
+
+Keep credentials in a secret while the rest of the cache configuration stays in values:
+
+```yaml
+zitadel:
+  configSecretName: zitadel-cache-credentials
+  configmapConfig:
+    Caches:
+      Connectors:
+        Redis:
+          Enabled: true
+          Addr: "redis.database.svc.cluster.local:6379"
+          DBOffset: 10
+      Instance:
+        Connector: "redis"
+        MaxAge: 1h
+        LastUseAge: 10m
+      Organization:
+        Connector: "redis"
+        MaxAge: 1h
+        LastUseAge: 10m
+```
+
+Create the secret with your Redis ACL user and password:
+
+```bash
+kubectl create secret generic zitadel-cache-credentials \
+  --from-literal=config.yaml="
+Caches:
+  Connectors:
+    Redis:
+      Username: cache-user        # Omit for default user
+      Password: your-redis-password
+"
+```
+
+## Connect with TLS (Redis or Valkey)
+
+Enable TLS when your endpoint requires encryption. This uses server-auth TLS with the container's trust store.
+
+```yaml
+zitadel:
+  configSecretName: zitadel-cache-credentials
+  configmapConfig:
+    Caches:
+      Connectors:
+        Redis:
+          Enabled: true
+          Addr: "redis.example.com:6380"
+          EnableTLS: true
+          DBOffset: 10
+      Instance:
+        Connector: "redis"
+        MaxAge: 1h
+        LastUseAge: 10m
+      Organization:
+        Connector: "redis"
+        MaxAge: 1h
+        LastUseAge: 10m
+```
+
+Reuse the secret from the previous section for credentials if needed. Custom certificate authorities must be added to the container's trust bundle (for example, by mounting a CA file into the pod); client certificate authentication is not supported.
@@ -752,6 +752,7 @@ export const guidesSidebar: readonly SidebarItem[] = [
              "self-hosting/deploy/kubernetes/configuration",
              "self-hosting/deploy/kubernetes/ingress",
              "self-hosting/deploy/kubernetes/database",
+              "self-hosting/deploy/kubernetes/caching",
              "self-hosting/deploy/kubernetes/observability",
              "self-hosting/deploy/kubernetes/operations",
              "self-hosting/deploy/kubernetes/uninstalling",
@@ -1128,4 +1129,4 @@ export const legalSidebar: readonly SidebarItem[] = [
 ] as const;

 // Self Hosting Sidebar (Exporting empty array if empty, or move logic here if needed)
-export const selfHostingSidebar: readonly SidebarItem[] = [];
+export const selfHostingSidebar: readonly SidebarItem[] = [];