> ## 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.
# Cluster Cache
The cluster cache is a distributed key-value store built directly into the Orchestrator. Data written on one node propagates automatically to every other node in the cluster -- no external infrastructure to deploy or manage. This makes it the simplest option for sharing cached data across Orchestrator instances in environments where eventual consistency is acceptable.
Cluster caches require the `experimental.clusters` feature flag and are **not supported for production and may be changed or removed without notice**. For production multi-node deployments, use a [Redis cache](/reference/orchestrator/caches/redis).
**Console deployments:** Cluster caches are not available natively in the Maverics Console. To use cluster caches with Console-deployed Orchestrators, use the [**config override**](/reference/console/config-publishing#override-config) feature. Config override requires enablement for your organization -- contact your Strata account team or [Strata support](https://strataidentity.my.site.com/support/s/) to enable it.
**Prerequisite:** Cluster caches require a configured cluster. See the [Clusters](/reference/orchestrator/experimental/clusters) reference page for setup instructions including discovery, encryption, and data plane configuration.
## Overview
Every node in the cluster holds a replica of every cache entry. When a node writes a cache value -- a provider token, a policy decision, a user attribute -- that value propagates to all other nodes automatically. Any node can serve any request without reaching out to an external store.
A cluster must be defined in the configuration before cluster caches can be used.
### Consistency Model
Cluster caches are **eventually consistent**. A write completes immediately on the local node and is then propagated to other nodes via the gossip protocol. Other nodes may briefly return stale data until the update arrives. In practice, for small clusters (3-10 nodes) within the same region, updates typically converge in **under one second**. Cross-region deployments or larger clusters may take a few seconds. Conflict resolution is automatic and deterministic -- no manual intervention is required, including after network partitions.
Because cluster caches are eventually consistent, a cache entry written on one node may not be immediately visible on another. For most Orchestrator use cases, the brief convergence window does not affect correctness. If your deployment requires immediate consistency for cached data, use a [Redis cache](/reference/orchestrator/caches/redis) instead.
### When to Use Cluster Cache vs. Redis
| | Cluster Cache | Redis |
| --------------------- | ---------------------------------------------------------------- | ------------------------------------------------------- |
| **Infrastructure** | None -- built into the Orchestrator | Requires a separate Redis deployment |
| **Consistency** | Eventually consistent (sub-second convergence in most cases) | Immediately consistent |
| **Production status** | Experimental | Production-supported |
| **Best for** | Development, testing, and deployments that prioritize simplicity | Production workloads that require immediate consistency |
## Use Cases
* **Infrastructure-free shared state** -- every node sees the same data without deploying and managing Redis
* **Regional data isolation** -- with [multi-cluster topologies](/reference/orchestrator/experimental/clusters#multi-cluster-topologies), keep regional cache data in regional clusters for performance and data residency compliance while still routing requests globally
* **Development velocity** -- no Redis to install locally; clustering just works between Orchestrator nodes
## Configuration
Cluster caches are defined with a name, type, and a reference to a configured cluster:
```yaml maverics.yaml theme={null}
caches:
- name: my-cache
type: cluster
cluster:
name: my-cluster
```
Modes that support caching reference the cache by name. For example:
```yaml maverics.yaml theme={null}
oidcProvider:
cache: my-cache
# ... other oidcProvider config
samlProvider:
cache: my-cache
# ... other samlProvider config
```
The cluster cache requires a `clusters` definition in your configuration. See the [Clusters](/reference/orchestrator/experimental/clusters) reference for complete cluster setup including membership, data plane, and discovery.
### Configuration Reference
#### Cluster Cache Fields
| Key | Type | Default | Required | Description |
| ----------------------- | ------ | ------- | -------- | ------------------------------------------------------------ |
| `caches[].name` | string | -- | Yes | Unique cache name |
| `caches[].type` | string | -- | Yes | Must be `"cluster"` |
| `caches[].cluster.name` | string | -- | Yes | Cluster name -- must match a defined cluster in `clusters[]` |
## Examples
A minimal cluster cache configuration. The cache references a configured cluster by name -- all nodes in that cluster automatically share cached data.
```yaml maverics.yaml theme={null}
caches:
- name: my-cache
type: cluster
cluster:
name: my-cluster
clusters:
- name: my-cluster
# ... cluster configuration (see Clusters reference)
```
An OIDC Provider mode using a cluster cache for shared token and authorization state. This configuration is suitable for development and testing environments where you want multi-node state sharing without deploying Redis.
```yaml maverics.yaml theme={null}
caches:
- name: oidc-cache
type: cluster
cluster:
name: dev-cluster
clusters:
- name: dev-cluster
# ... cluster configuration (see Clusters reference)
oidcProvider:
cache: oidc-cache
# ... other oidcProvider config
```
## Troubleshooting
* **Cluster cache not working** -- cluster caches require the `experimental.clusters` feature flag and a valid cluster definition. Verify that your cluster is configured and that the cache's cluster name matches a defined cluster.
* **Cache data not shared across nodes** -- ensure all nodes are members of the same cluster and that the data plane is configured correctly. Check Orchestrator logs for cluster membership and replication errors.
* **Stale reads after a write** -- cluster caches are eventually consistent. A write on one node may take up to a few seconds to appear on other nodes. This is normal behavior, not a bug. If your use case cannot tolerate eventual consistency, use a [Redis cache](/reference/orchestrator/caches/redis).
## Related Pages
Overview of cache types and production support status
Production-ready distributed caching backed by Redis
Read and write cache entries from Service Extensions via the api.Cache() interface
Cluster setup including discovery, encryption, and data plane configuration