Caching

This guide explains how to connect Zitadel caches to Redis or Valkey on Kubernetes.

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.

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)

Pass the Redis URL as an environment variable:

zitadel:
  env:
    - name: ZITADEL_CACHES_CONNECTORS_REDIS_URL
      value: "redis://redis-master.caching.svc.cluster.local:6379"
    - name: ZITADEL_CACHES_CONNECTORS_REDIS_ENABLED
      value: "true"

Use this only on isolated clusters where the Redis endpoint does not require authentication.

Connect with password from a Kubernetes Secret

Store the Redis URL (with credentials) in a secret and pass it as an environment variable:

kubectl create secret generic zitadel-cache-credentials \
  --from-literal=url="redis://cache-user:your-redis-password@redis.database.svc.cluster.local:6379"

zitadel:
  env:
    - name: ZITADEL_CACHES_CONNECTORS_REDIS_URL
      valueFrom:
        secretKeyRef:
          name: zitadel-cache-credentials
          key: url
    - name: ZITADEL_CACHES_CONNECTORS_REDIS_ENABLED
      value: "true"

Connect with TLS (Redis or Valkey)

Use the rediss:// scheme (note the double s) when your endpoint requires encryption. This uses server-auth TLS with the container's trust store.

kubectl create secret generic zitadel-cache-credentials \
  --from-literal=url="rediss://cache-user:your-redis-password@redis.example.com:6380"

zitadel:
  env:
    - name: ZITADEL_CACHES_CONNECTORS_REDIS_URL
      valueFrom:
        secretKeyRef:
          name: zitadel-cache-credentials
          key: url
    - name: ZITADEL_CACHES_CONNECTORS_REDIS_ENABLED
      value: "true"

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.