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

​
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

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.
4

Configure authentication

Optionally enter a Redis Cache Username and Redis Cache Password. These must match credentials generated via Redis access control lists (ACL).
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.
5

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.
6

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 Keys 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.
7

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:
        current: <vault.redis_hashing_key>
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:
        current: <vault.redis_hashing_key>

tls:
  "redis-tls":
    caFile: "/etc/maverics/certs/redis-ca.pem"
    minVersion: "1.2"
When using Redis in a clustered or sentinel configuration, provide multiple server addresses. The Orchestrator connects to the available servers for high availability.
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:
        current: <vault.redis_hashing_key>

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:
        current: <vault.redis_hashing_key>

​
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.
  • 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