> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Redis Cache

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.

<Info>Redis caching is **supported for production** use. It is the recommended approach for sharing cached data across multiple Orchestrator instances.</Info>

<Note>
  Redis is used for **caching**, not for session storage. These are configured separately. See [Sessions](/reference/orchestrator/sessions) for session store configuration.
</Note>

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

<Tip>
  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.
</Tip>

For more on Redis topologies, see the [Redis cluster documentation](https://redis.io/docs/latest/operate/oss_and_stack/management/scaling/).

## Setup

<Tabs>
  <Tab title="Console UI">
    Redis caches are configured per deployment under **Orchestrator Settings**.

    <Steps>
      <Step title="Open Redis cache settings">
        Navigate to **Deployments**, select a deployment, and click **Add** in the **Redis Caches** section.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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](/reference/orchestrator/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.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Configure authentication">
        Optionally enter a **Redis Cache Username** and **Redis Cache Password**. These must match credentials generated via Redis access control lists (ACL).

        <Note>
          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.
        </Note>

        <Warning>
          Store passwords and other secrets in a [secret provider](/reference/orchestrator/configuration/secret-providers) 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.
        </Warning>
      </Step>

      <Step title="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.
      </Step>

      <Step title="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).

        <Warning>
          Use [secret references](/reference/orchestrator/configuration/secret-providers) (e.g., `<vault.redis_encryption_key>`) for all key values rather than entering them directly. See [Secret Providers](/reference/orchestrator/configuration/secret-providers) for setup.
        </Warning>
      </Step>

      <Step title="Save">
        Click **Add** to save the cache configuration.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Configuration">
    Redis caches are defined with a name, type, and Redis connection details:

    ```yaml maverics.yaml theme={null}
    caches:
      - name: my-redis
        type: redis
        redis:
          addresses:
            - "redis.example.com:6379"
          username: "maverics"
          password: <vault.redis_password>
          tls: redis-tls
        keys:
          disablePrefix: false
        encryption:
          disabled: false
          keys:
            current: <vault.redis_encryption_key>
            old:
              - <vault.redis_encryption_key_old>
        hashing:
          keys:
            disabled: false
    ```

    Modes that support caching reference the cache by name. For example:

    ```yaml maverics.yaml theme={null}
    oidcProvider:
      cache: my-redis
      # ... other oidcProvider config

    samlProvider:
      cache: my-redis
      # ... other samlProvider config
    ```

    <Note>
      Do not use `local_default` as a cache name -- it is reserved for the built-in local cache.
    </Note>

    #### Configuration Reference

    ##### Redis Fields

    | Key                        | Type   | Default | Required | Description                                                                                                                                                                                         |
    | -------------------------- | ------ | ------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `caches[].name`            | string | --      | Yes      | Unique cache name                                                                                                                                                                                   |
    | `caches[].type`            | string | --      | Yes      | Must be `"redis"`                                                                                                                                                                                   |
    | `caches[].redis.addresses` | array  | --      | Yes      | Redis server addresses (at least one required)                                                                                                                                                      |
    | `caches[].redis.username`  | string | --      | No       | Redis username for authentication. Only Redis ACL username/password authentication is supported -- cloud-provider-specific mechanisms (e.g., IAM or managed-identity token auth) are not supported. |
    | `caches[].redis.password`  | string | --      | No       | Redis password. Use a [secret reference](/reference/orchestrator/configuration/secret-providers), e.g., `<vault.redis_password>`.                                                                   |
    | `caches[].redis.tls`       | string | --      | No       | TLS profile name for the Redis connection (references a named profile under `tls`)                                                                                                                  |

    ##### Encryption, Hashing, and Key Options

    The following options control client-side encryption, key hashing, and key prefixing for external caches. Encryption encrypts cached values before they are sent to the external cache service. Hashing ensures cache keys do not contain sensitive data -- before reading or writing, keys are hashed and the hash is used for storage and lookup.

    | Key                                | Type    | Default | Description                                                                                                                                                                               |
    | ---------------------------------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `caches[].keys.disablePrefix`      | boolean | `false` | Disable feature-specific key prefix (useful for Service Extensions reading non-Orchestrator data)                                                                                         |
    | `caches[].encryption.disabled`     | boolean | `false` | Disable client-side encryption of cached values (encryption is enabled by default)                                                                                                        |
    | `caches[].encryption.keys.current` | string  | --      | AES-256-GCM encryption key: a 64-character hex string (32 bytes). Generate with `openssl rand -hex 32`. Use a [secret reference](/reference/orchestrator/configuration/secret-providers). |
    | `caches[].encryption.keys.old`     | array   | `[]`    | Previous encryption keys, used during key rotation to decrypt data encrypted with an older key. Use [secret references](/reference/orchestrator/configuration/secret-providers).          |
    | `caches[].hashing.keys.disabled`   | boolean | `false` | Disable cache key hashing (hashing is enabled by default)                                                                                                                                 |
  </Tab>
</Tabs>

## Examples

<AccordionGroup>
  <Accordion title="Minimal Redis cache">
    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.

    ```yaml maverics.yaml theme={null}
    caches:
      - name: my-redis
        type: redis
        redis:
          addresses:
            - "redis.example.com:6379"
        encryption:
          keys:
            current: <vault.redis_encryption_key>
        hashing:
          keys:
            disabled: false
    ```
  </Accordion>

  <Accordion title="Redis with TLS and authentication">
    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.

    ```yaml maverics.yaml theme={null}
    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"
    ```
  </Accordion>

  <Accordion title="Redis cluster with multiple addresses">
    When Redis runs in [cluster mode](#standalone-vs-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.)

    ```yaml maverics.yaml theme={null}
    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"
    ```
  </Accordion>

  <Accordion title="Encryption key rotation">
    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.

    ```yaml maverics.yaml theme={null}
    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
    ```
  </Accordion>

  <Accordion title="Shared cache for Service Extensions (disable key prefix)">
    By default, the Orchestrator prepends a feature-specific namespace prefix to every cache key. Set `keys.disablePrefix: true` when a [Service Extension](/reference/orchestrator/service-extensions) 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.

    ```yaml maverics.yaml theme={null}
    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
    ```
  </Accordion>
</AccordionGroup>

## 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](#standalone-vs-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`.

## Related Pages

<CardGroup cols={2}>
  <Card title="Caches" icon="database" href="/reference/orchestrator/caches">
    Overview of cache types and production support status
  </Card>

  <Card title="Service Extensions" icon="puzzle-piece" href="/reference/orchestrator/service-extensions">
    Read and write cache entries from Service Extensions via the api.Cache() interface
  </Card>

  <Card title="Secret Providers" icon="key" href="/reference/orchestrator/configuration/secret-providers">
    Store passwords and encryption keys securely with secret references
  </Card>

  <Card title="Transport Layer Security (TLS)" icon="shield-halved" href="/reference/orchestrator/tls-security">
    Secure Redis connections with named TLS profiles
  </Card>
</CardGroup>