Skip to main content
The Redis cache provides distributed key-value storage across multiple Orchestrator nodes. When configured, the Orchestrator stores cached data in Redis rather than in local memory, enabling multiple instances behind a load balancer to share the same cached data. Modes and features that support caching reference named caches — because all cache types share the same interface, you can use Redis without changing any mode configuration.
Redis caching is supported for production use. It is the recommended approach for sharing cached data across multiple Orchestrator instances.
Redis is used for caching, not for session storage. These are configured separately. See Sessions for session store configuration.

​
Use Cases

  • Multi-node deployments — share cached data across multiple Orchestrator instances behind a load balancer so any node can serve any request
  • External durability — persist cached data in Redis so it survives Orchestrator restarts

​
Standalone vs. Cluster Mode

Use standalone Redis by default. A standalone Redis is a single primary that holds all the data. It is still fully highly available: run replicas (typically across availability zones) that automatically take over if the primary fails. Standalone gives you redundancy without the added complexity of sharding, and is the recommended topology for Orchestrator caching, including the OIDC Provider (Auth Provider). Cluster mode shards (splits) data across multiple primary nodes and is rarely needed for Orchestrator caching. If you do run Redis in cluster mode, you must list the addresses of all cluster nodes in redis.addresses. If the Orchestrator knows about only some nodes, Redis returns MOVED errors whenever a requested key lives on a shard it cannot reach.
Seeing MOVED errors? Your Redis is running in cluster mode but not all node addresses are configured. Either add every cluster node address to redis.addresses, or reconfigure the Redis instance to run in standalone mode.
For more on Redis topologies, see the Redis cluster documentation.

​
Setup

Redis caches are configured per deployment under Orchestrator Settings.
1

Open Redis cache settings

Navigate to Deployments, select a deployment, and click Add in the Redis Caches section.
2

Set the cache name

Enter a Name to identify this cache. Modes that support caching reference the cache by this name. Do not use local_default — it is reserved for the built-in local cache.
3

Configure the key prefix (optional)

Leave Disable Prefix off for normal use. By default, the Orchestrator prepends a feature-specific namespace prefix to every cache key. Enable this toggle only when Service Extensions need to read and write data in this cache that is not owned by the Orchestrator — disabling the prefix lets the keys match those used by the external system.
4

Add Redis server addresses

Enter at least one Address in host:port format (e.g., redis.example.com:6379). Click Add Redis Address to add additional servers.
5

Configure authentication

Optionally enter a Redis Cache Username and Redis Cache Password. These must match credentials generated via Redis access control lists (ACL).
The Orchestrator authenticates to Redis using Redis username and password (ACL) credentials only. Cloud-provider-specific authentication mechanisms (such as IAM-based or managed-identity token authentication) are not supported — enable Redis ACL credentials on your Redis instance and reference them here.
Store passwords and other secrets in a secret provider rather than entering them directly in the Console. Use the secret reference syntax (e.g., <vault.redis_password>) so the Orchestrator resolves the value at runtime.
6

Configure TLS

TLS is enabled by default. Set the Min Version (default: 1.2) and optionally provide a CA Path for self-signed certificates. Disable the Enable TLS toggle if your Redis server does not use TLS.
7

Configure encryption and hashing

Encryption is enabled by default. The Orchestrator encrypts cached values client-side using AES-256-GCM before sending them to Redis, so data is protected at rest in the external cache. Enter a Current Key — a 64-character hex string (generate one with openssl rand -hex 32). To rotate keys, add the previous key to Old Keys — the Orchestrator will use old keys to decrypt existing data while encrypting new data with the current key. Use the Disable Encryption toggle only if your Redis instance already provides encryption at rest.Hashing is enabled by default. The Orchestrator hashes cache keys before storing or looking up data, ensuring that key names in Redis do not contain sensitive information. Use the Disable Hashing toggle only if you need to inspect raw cache keys in Redis (e.g., for debugging).
Use secret references (e.g., <vault.redis_encryption_key>) for all key values rather than entering them directly. See Secret Providers for setup.
8

Save

Click Add to save the cache configuration.

​
Examples

A single Redis server with client-side encryption and key hashing enabled. This is the simplest production-ready configuration for sharing cached data across Orchestrator instances.
maverics.yaml
caches:
  - name: my-redis
    type: redis
    redis:
      addresses:
        - "redis.example.com:6379"
    encryption:
      keys:
        current: <vault.redis_encryption_key>
    hashing:
      keys:
        disabled: false
Secure the Redis connection with a named TLS profile and authenticate with username and password. The TLS profile references a CA certificate for verifying the Redis server’s certificate.
maverics.yaml
caches:
  - name: my-redis
    type: redis
    redis:
      addresses:
        - "redis.example.com:6379"
      username: "maverics"
      password: <vault.redis_password>
      tls: redis-tls
    encryption:
      keys:
        current: <vault.redis_encryption_key>
    hashing:
      keys:
        disabled: false

tls:
  "redis-tls":
    caFile: "/etc/maverics/certs/redis-ca.pem"
    minVersion: "1.2"
When Redis runs in cluster mode, list the addresses of all cluster nodes. The Orchestrator needs every node address to route requests to the correct shard; otherwise Redis returns MOVED errors. (For a standalone primary with replicas, a single endpoint is sufficient.)
maverics.yaml
caches:
  - name: my-redis
    type: redis
    redis:
      addresses:
        - "redis-1.example.com:6379"
        - "redis-2.example.com:6379"
        - "redis-3.example.com:6379"
      password: <vault.redis_password>
      tls: redis-tls
    encryption:
      keys:
        current: <vault.redis_encryption_key>
    hashing:
      keys:
        disabled: false

tls:
  "redis-tls":
    caFile: "/etc/maverics/certs/redis-ca.pem"
Rotate encryption keys without downtime by adding the old key to the old list. The Orchestrator encrypts new data with the current key and decrypts existing data with either the current or old keys. Once all data encrypted with the old key has expired or been rewritten, remove the old key.
maverics.yaml
caches:
  - name: my-redis
    type: redis
    redis:
      addresses:
        - "redis.example.com:6379"
    encryption:
      keys:
        current: <vault.redis_encryption_key_new>
        old:
          - <vault.redis_encryption_key_old>
    hashing:
      keys:
        disabled: false
By default, the Orchestrator prepends a feature-specific namespace prefix to every cache key. Set keys.disablePrefix: true when a Service Extension reads and writes data in this cache that is not owned by the Orchestrator — for example, sharing entries with an external system that writes keys without the Orchestrator’s prefix. With the prefix disabled, keys written by the extension match the keys the external system expects.
maverics.yaml
caches:
  - name: shared-redis
    type: redis
    redis:
      addresses:
        - "redis.example.com:6379"
      password: <vault.redis_password>
      tls: redis-tls
    keys:
      disablePrefix: true
    encryption:
      keys:
        current: <vault.redis_encryption_key>
    hashing:
      keys:
        disabled: false

​
Troubleshooting

  • Connection refused — verify Redis is accessible from the Orchestrator host. Check that the address and port are correct and that firewalls allow the connection.
  • MOVED errors — your Redis is running in cluster mode but not all node addresses are configured. Add every cluster node address to redis.addresses, or reconfigure the Redis instance to run in standalone mode.
  • Authentication errors — confirm the username and password are correct. If using a secret reference, ensure the secret provider is configured and the secret resolves.
  • TLS handshake failures — for Redis with TLS, ensure the named TLS profile includes the correct CA certificate. Verify the Redis server’s certificate is trusted.
  • Encryption key errors — check that the encryption key secret reference resolves correctly. The key must be a 64-character hex string (32 bytes). Generate a valid key with openssl rand -hex 32.

Caches

Overview of cache types and production support status

Service Extensions

Read and write cache entries from Service Extensions via the api.Cache() interface

Secret Providers

Store passwords and encryption keys securely with secret references

Transport Layer Security (TLS)

Secure Redis connections with named TLS profiles