Cluster Cache (Standalone)

Standalone cluster cache provides a shared Redis-backed cache across Gateway pods. This improves cross-pod cache consistency compared to local in-memory cache.

ℹ️

Note:

Standalone cluster cache uses a single Redis topology with lower operational overhead.
If you need Redis failover and higher cache service resilience, use Cluster Cache High Availability (HA).

Read Behavior

When standalone cluster cache is enabled, runtime reads follow this flow:

1. Gateway receives a read request and starts a cache lookup.
2. Read order is controlled by PREFER_CLUSTER_CACHE_FIRST.
3. If a valid cached value is found, Gateway returns it.
4. If no cached value is found, Gateway fetches from SaaS, stores the result in cache, and returns it.
5. If SaaS is unreachable and the value is not already cached, the request fails.

--ignore-cache attempts to bypass cache and read directly from SaaS; for full behavior details, see Gateway Caching.

Local Cache and Cluster Cache Read Preference

When standalone cluster cache is enabled, PREFER_CLUSTER_CACHE_FIRST controls read preference between the local in-memory cache and the standalone Redis cache.

When PREFER_CLUSTER_CACHE_FIRST=false (the default local-first mode), Gateway compares local and Redis lastModified metadata and refreshes local entries when Redis is newer.

Write and Update Behavior

Standalone cluster cache does not change write semantics. Writes are SaaS-first:

1. Gateway writes the update to SaaS.
2. Related cached entries are invalidated.
3. Cache is repopulated on the next read-through fetch (or proactive sync, if enabled).

As a result, short-lived stale reads can occur between a successful write and the next cache refresh.

To reduce this stale-read window:

• For the first read after a write, use --ignore-cache true when SaaS connectivity is available.
• Enable proactive caching and tune refresh intervals to shorten convergence time.
• Avoid immediate dependent reads that assume strict read-after-write consistency from cache.

Persistence

In the Helm chart, standalone persistence is controlled by globalConfig.clusterCache.persistence.enabled:

• false (default): no PersistentVolumeClaim (PVC) is mounted at /data, so cached data is ephemeral and can be lost when the cache pod restarts or is rescheduled.
• true: a PVC is mounted at /data and Redis can persist to disk so cache data can be retained across restarts and rescheduling.

By default, Redis durability flags are not forced in chart templates. You can pass Redis runtime flags through globalConfig.clusterCache.extraArgs. For supported options, see Redis configuration and Redis persistence.

For Kubernetes storage behavior details, see Persistent Volumes and Claims and StorageClasses.

When to Use

Use standalone cluster cache when:

• You run multiple Gateway pods and want shared cache state.
• You want lower operational complexity than HA Sentinel.
• A single Redis instance is acceptable for your availability target.

When Not to Use

Do not use standalone cluster cache when:

• You require Redis high availability across node failures.
• You need Sentinel-managed failover behavior.

Configuring Cluster Cache (Standalone)

Use the following deployment-specific options to configure standalone cluster cache:

Example (values.yaml):

globalConfig:
  env:
    - name: PREFER_CLUSTER_CACHE_FIRST
      value: "false"
  clusterCache:
    enabled: true
    persistence:
      enabled: true
      existingClaim: ""
      accessMode: "ReadWriteOnce"
      storageClass: ""
      size: 10Gi

For the full key reference, see Helm Values Reference.

Cluster Cache (Standalone) Values

• globalConfig.clusterCache.enabled: Enables standalone cluster cache.
• PREFER_CLUSTER_CACHE_FIRST (under globalConfig.env): Controls read order between local in-memory cache and standalone Redis cache. For value behavior, see Local Cache and Cluster Cache Read Preference.
• globalConfig.clusterCache.persistence.enabled: Enables Redis data persistence for standalone cluster cache so cached data can survive pod restarts, container restarts, and pod rescheduling events.
• globalConfig.clusterCache.persistence.existingClaim: Uses an existing PersistentVolumeClaim (PVC) instead of creating a new one.
• globalConfig.clusterCache.persistence.accessMode: Sets the PVC access mode (for example, ReadWriteOnce). See Access Modes.
• globalConfig.clusterCache.persistence.storageClass: Sets the Kubernetes StorageClass for the PVC. In most environments, leave this unset to use the cluster default.
• globalConfig.clusterCache.persistence.size: Sets the requested PVC size. See Kubernetes Resource Management for Pods and Containers.
• globalConfig.clusterCache.extraArgs: Passes Redis runtime arguments to the standalone cache container. For supported options, see Redis configuration and Redis persistence.

Cluster Cache Environment Variables (Docker Compose)

When deploying with Docker Compose, set these gateway.env variables to control how the Gateway uses Redis for caching (enablement and read preference). These settings tune runtime cache behavior only; they do not create, deploy, or manage standalone cluster cache topology resources.

• USE_CLUSTER_CACHE: Set to true to enable the Redis-backed cluster cache for the curl proxy (proactive cache) layer. In a full Gateway deployment, set this together with GATEWAY_CLUSTER_CACHE; the SRA process uses USE_CLUSTER_CACHE alone.
• GATEWAY_CLUSTER_CACHE: Set to "enable" to activate cluster cache mode for the Gateway configuration layer. Any non-empty value enables this; "enable" is the conventional value. If this variable remains set after the Redis instance is removed, the Gateway may fail to start until the container is recreated.
• REDIS_ADDR: Address of the Redis instance, for example akeyless-cache:6379.
• PREFER_CLUSTER_CACHE_FIRST: Controls read preference between the local in-memory cache and the Redis cache. For value behavior, see Local Cache and Cluster Cache Read Preference.