Runtime Caching

Runtime caching controls how the Akeyless Gateway serves and refreshes cached secrets during request handling.

Read Behavior

When runtime caching is enabled, secret retrieval follows this flow:

1. The request reaches the Gateway and a cache lookup begins.
2. If cluster cache is enabled (Cluster Cache (Standalone) or Cluster Cache High Availability (HA)), lookup order is controlled by PREFER_CLUSTER_CACHE_FIRST.
3. If a valid cached value is found, the Gateway returns it immediately to the caller.
4. After a cache hit, the Gateway can refresh from SaaS in the background to keep cache entries current.
5. If no cached value exists, the Gateway reads from SaaS, stores the value in cache, and then returns it to the caller.
6. If SaaS is unreachable and no cached value exists, 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 cluster cache is enabled, PREFER_CLUSTER_CACHE_FIRST controls read preference between the local in-memory cache and the Redis cache.

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

For Redis deployment topology, see Cluster Cache (Standalone) and Cluster Cache High Availability (HA).

Write and Update Behavior

Gateway write operations are SaaS-first. There is no synchronous write-through update to cache.

Current implementation pattern:

1. A write or update request is sent to SaaS.
2. Matching cached items are invalidated (removed) by update, delete, and rotate flows.
3. Cache converges on the next read-through fetch or proactive synchronization cycle.

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

When to Use

Use runtime caching when:

• You want lower read latency for repeated secret retrieval requests.
• You want Gateway to continue serving cached values during temporary SaaS interruptions.
• You need a baseline caching mode that can be combined with proactive caching or cluster cache.

When Not to Use

Do not rely on runtime caching alone when:

• You require strict read-after-write consistency for every request.
• You need shared cache state across multiple Gateway pods without local cache divergence.
• Your workload requires every read to fetch directly from SaaS.

Configuring Runtime Caching

Use the following deployment-specific options to configure runtime caching:

Example (values.yaml):

globalConfig:
  env:
    - name: CACHE_ENABLE
      value: "true"
    - name: PREFER_CLUSTER_CACHE_FIRST
      value: "false"
    - name: IGNORE_REDIS_HEALTH
      value: "false"

Runtime Caching Environment Variables

• CACHE_ENABLE: Enables or disables the Gateway cache subsystem. This controls runtime caching behavior and is a prerequisite for proactive cache activity.
• PREFER_CLUSTER_CACHE_FIRST: Controls cache lookup order when cluster cache is enabled. For value behavior, see Local Cache and Cluster Cache Read Preference.
• IGNORE_REDIS_HEALTH: Controls whether Redis connectivity affects the /health handler result. This does not change runtime cache read or write behavior directly, but it does affect how orchestration and load balancers treat Gateway availability when Redis is degraded.
  • false (default): Redis connectivity failures can fail /health.
  • true: Redis connectivity is ignored by /health checks.