diff --git a/docs/Advanced Functionality/monitor-akeyless.md b/docs/Advanced Functionality/monitor-akeyless.md index ea3db70f..cf85652e 100644 --- a/docs/Advanced Functionality/monitor-akeyless.md +++ b/docs/Advanced Functionality/monitor-akeyless.md @@ -87,13 +87,13 @@ Each **Gateway** cluster exposes a `/status` endpoint that provides basic runtim ## Gateway Health -To assess the Gateway’s connectivity to Akeyless SaaS core services, you can use the `/health` endpoint. Additionally, when working with [Cluster Cache](https://docs.akeyless.io/docs/gateway-kubernetes-helm-values-reference#cache-configuration), this endpoint will also be affected by the cache status. +To assess the Gateway’s connectivity to Akeyless SaaS core services, you can use the `/health` endpoint. When cluster cache is enabled, cache availability can also affect this endpoint result. For cache architecture and runtime semantics, see [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching). * If the Gateway is successfully connected, it responds with an HTTP status code `200` and the message: **Health Check Ok**. * If the connection fails, it returns an HTTP status code `503` with the message: **Health Check Error** * If Cluster Cache is used, and not available, even when the Gateway is successfully connected, it will return `503` with **Health Check Error** -To disable the effect of the [Cluster Cache](https://docs.akeyless.io/docs/gateway-kubernetes-helm-values-reference#cache-configuration) on the `/health` endpoint you can set the following env variable as part of your Gateway deployment: +To disable the effect of cluster cache health on the `/health` endpoint, set the following environment variable as part of your Gateway deployment: ```yaml Gateway chart env: diff --git a/docs/Akeyless Gateway/configure-gateway/gateway-caching.md b/docs/Akeyless Gateway/configure-gateway/gateway-caching.md deleted file mode 100644 index 913af2ab..00000000 --- a/docs/Akeyless Gateway/configure-gateway/gateway-caching.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -title: Gateway Caching -excerpt: '' -deprecated: false -hidden: false -metadata: - title: '' - description: '' - robots: index -next: - description: '' ---- -Upon network outage, the Gateway cache can still handle requests for Secrets retrievals (read-only). The cache will start working only after the Gateway is successfully operated. Only users already authenticated can get service from the Gateway cache, where the following [Authentication Methods](https://docs.akeyless.io/docs/access-and-authentication-methods) can keep authenticating on offline modes: **K8s**, **email**, **API Key**, **LDAP**, **Certificate** and **JWT**. - -> ℹ️ **Note (Offline Authentication Cache):** -> -> Offline authentication cache is only supported in [Cluster Cache](https://docs.akeyless.io/docs/gateway-caching#cluster-cache-mode) mode and requires the user being authenticated to have at least list permission on the relevant Authentication Method. - -The most straightforward use cases are the following: - -* The Gateway Cache is used to improve performance when fetching secrets. - -* The Proactive Cache enables storing secrets in the Gateway Cache in advance upon successful user authentication. - -The Gateway cache uses two primary types of caches: a **Local In-Memory Cache** for individual Gateway instances and a **Cluster Cache** for high availability in Kubernetes environments. This architecture ensures that secrets are readily available to applications while minimizing the load on the Akeyless SaaS platform. - -In a high-availability configuration, secrets are stored in a **Cluster Cache**, typically backed by an internal database instance. This shared cache ensures every pod has a consistent view of the cached data. This model is crucial for resilience, as it allows the Gateway to continue serving cached secrets even during a complete Akeyless SaaS outage. Authentication can also persist during an outage for methods that can be validated locally, such as Kubernetes ServiceAccount authentication, where the Gateway can verify the token against the cluster's Kubernetes API server without needing to contact the SaaS. - -## Gateway Cache - -To enable and configure the Gateway Cache: - -1. Open the **Akeyless Gateway Configuration Manager** at `https://Your_Akeyless_Gateway_URL:8000/console`. - -2. On the menu bar at the left, click **Gateways > Your-Gateway > Manage Gateway > Caching Configuration**. - -3. Select the **Enable Caching** checkbox. - -4. Set the **Stale Timeout** value. This is the time (in minutes) during which a secret should be kept in the cache. The secret is deleted from the cache at the end of this period. By default, cached secrets will expire after 60 minutes. - -5. Click **Save Changes**. - -> ℹ️ **Note:** -> -> Usually, after the Stale Timeout period expires for a secret, the secret is deleted from the Gateway Cache. -> -> If there is no internet connection, the Gateway Cache won’t delete old items until the internet connection is restored. - -## Proactive Gateway Cache - -The Proactive Cache fetches all secrets from the Akeyless Cloud and stores them in the Gateway Cache upon successful authentication (based on the user access policy). To manage each user's access policy, the [Gateway's default Auth Method](https://docs.akeyless.io/docs/gateway-deploy-kubernetes-helm#authentication) must have **List** permissions for **Auth-Methods** and **Roles**, as well as **Read** permission for the secret intended to be saved in the cache. - -The Gateway uses a proactive caching model with a delta-based update process to avoid the resource-intensive task of re-fetching all secrets periodically. This is managed by two parallel background processes: - -* **Refresh-TTL Ticker**: This process runs at a configurable interval (by default every 5 minutes) and queries the Akeyless SaaS platform only for secrets that have been modified within that time window. By checking just for the delta of updated secrets, the Gateway significantly reduces the overhead of keeping the cache synchronized. -* **Cleanup-TTL Ticker:** This independent process periodically compares the cache with the SaaS to remove entries for secrets that have been deleted or for which the Gateway's access permissions have been revoked. - -This dual-ticker system ensures the cache remains fresh and accurate with minimal performance impact. When a user updates a secret in the Akeyless UI, the change is picked up by the next refresh cycle, and the updated value is propagated to the cache and subsequently to the workload without requiring any manual intervention. This provides a highly efficient and scalable solution for secrets management. - -The following diagram illustrates the key phases of the Akeyless Gateway's proactive caching mechanism, showing how it efficiently populates and maintains its cache, and how an application consumes secrets from it. -In this example, the user set the Refresh-TTL Ticker to 2 minutes. - -![Illustration for: The following diagram illustrates the key phases of the Akeyless Gateway's proactive caching mechanism, showing how it efficiently populates and maintains its cache, and how an…](https://files.readme.io/1fdc1d01ea89e625913853199b7ed1aba17bdebdd713ce3b708af7c1fa9b2e77-Cache_Diagaram.png) - -To enable and configure the Proactive Cache: - -1. Open the **Akeyless Gateway Configuration Manager** at `https://Your_Akeyless_Gateway_URL:8000/console`. - -2. On the menu bar at the left, click **Gateways > Your-Gateway > Manage Gateway > Caching Configuration**. - -3. Select the **Enable Proactive Caching** checkbox. - - > 🚧 Using Legacy Mode - > - > Once you disable **Legacy Mode**, you won't be able to re-enable it. - -4. Set the **Refresh TTL** value. This setting instructs the system to update secrets in the cache if they are older than the specified value. By default, each secret kept in the cache for more than 5 minutes will be re-requested from the Akeyless Cloud or the local Gateway. - -5. Set the **Cleanup TTL** value. Compares the cache with the SaaS to remove entries for secrets that have been deleted or for which the Gateway's access permissions have been revoked. - -6. Click **Save Changes**. - -## Cluster Cache Mode - -When deploying Gateway on Kubernetes, a Cluster Cache can be set in addition to support offline authentication, this results in an additional service that syncs all pods and has a shared storage, to keep the secrets encrypted at rest, this mode requires a Kubernetes encryption key. This feature can be set **only** during deployment. To set this follow the installation guide under the [cache](https://docs.akeyless.io/docs/advanced-k8s-gateway-configuration#cache-configuration) section. - -## Bypass Cache - -When Cache is enabled by default, any client that requests a secret from the relevant Gateway will receive the latest cached value of the secret. To work directly with the Akeyless SaaS, to ensure you are retrieving the latest value of the secret, you can specify the `ignore-cache` setting as part of the request to by-pass the cache mechanism: - -```shell -akeyless get-secret-value -n /mysecret --ignore-cache true -``` - -## How does cluster cache affect communication and authentication? - -This section explains how the Gateway behaves during normal operations (BAU) and during Akeyless SaaS outages when cluster cache is enabled. - -When a Gateway with **cluster cache** is deployed, it significantly enhances resilience and efficiency by acting as a high-availability layer in front of the Gateway. The client's primary point of contact remains the Gateway, but the behavior changes to prioritize the cache. Here is how communication and authentication are handled in different situations. - -**Business As Usual (BAU) operations**: -During normal operations, the communication flow is optimized for speed and reduced load on the Akeyless SaaS. - -1. **Initial Request**: The client needs a secret and sends an authenticated request to the Akeyless Gateway. -2. **Authentication**: The Gateway forwards the initial request to the SaaS auth service, and the token and credentials (JWT) are stored in the Gateway cache. - -**Akeyless SaaS outage**: -The primary benefit of cluster cache is realized during a SaaS outage. The goal shifts from efficiency to business continuity. - -1. **Initial Request**: The client needs a secret and sends an authenticated request to the Akeyless Gateway. -2. **Authentication**: Authentication requests to the Gateway still succeed because the client's authentication information is already stored in cache and can be validated. - -Generating new tokens is not possible during an outage because this capability resides with SaaS. The system can only issue tokens that were previously retrieved and cached before the outage. - -## What are the supported cache types? - -The Akeyless Gateway uses two cache types to ensure both performance and service continuity. - -1. **Local In-Memory Cache**: Speeds up day-to-day secret retrieval by keeping the latest value locally. -2. **Cluster Cache Mode (Kubernetes only)**: Provides a shared, highly available encrypted cache service for all Gateway pods in a Kubernetes deployment. Helm chart deployment spins up a `cache` service, and all pods `read/write` through it so every pod sees the same cached objects. Secrets are stored encrypted at rest. You provide a Kubernetes Secret for the cluster cache encryption key and can optionally enable TLS between pods and cache. Because cache is external to any single pod, rolling upgrades or pod restarts do not clear the cache. An optional cache HA flag turns the service itself into a multi-replica set backed by a `ReadWriteOnce` StorageClass (`Gateway version v4.34 and later`). - -## How proactive cache works - -When proactive cache is enabled, the Gateway stays current through one startup action and two background tickers: - -1. **Startup full-sync (one-off)**: On startup (or after cache restore), the Gateway authenticates with its administrative identity and pulls every secret it is entitled to read. This warms local cache so first requests are served quickly and the Gateway is ready for offline operation. -2. **Refresh-TTL ticker**: At a configurable interval, the Gateway asks SaaS only for secrets whose last-modified timestamp falls within that window. Changed items are overwritten in cache. -3. **Cleanup-TTL ticker**: Independently, every configured interval, the Gateway compares cache with SaaS and removes entries for deleted secrets or permissions that were revoked. - -The two tickers run in parallel. If Akeyless cloud services become unreachable, they pause while the Gateway continues serving requests from existing cache. Default intervals are typically five minutes for refresh and sixty minutes for cleanup, and can be tuned to balance freshness, bandwidth, and security requirements. - -## Behavior during Gateway outage - -### Local in-memory cache - -If a single Gateway instance goes down, its in-memory cache is lost. Secrets and authentication data stored only in that instance become unavailable until a healthy Gateway can fetch them again. - -Clients targeting that failed instance will fail. If other Gateway instances are healthy, requests can still be served by them. If no Gateway is healthy, requests fail until at least one instance is restored. - -### Cluster cache - -If a Gateway instance in a cluster fails, shared cluster cache remains available to other healthy Gateway instances. Secrets and authentication data persisted in cluster cache are not lost. - -Other active Gateway instances can continue to serve requests by retrieving data from cluster cache. - -## Behavior during SaaS outage - -### Local in-memory cache - -The Gateway serves requests for secrets and authentication from local cache if values exist. Minimum fetching interval is effectively ignored while SaaS is unreachable. Gateway can continue to authenticate existing sessions for supported methods (Kubernetes, API Key, Password, LDAP, Certificate, JWT) when credentials and auth data are cached. - -In offline mode, credential expiration is ignored. - -### Cluster cache - -Similar to local cache behavior, the Gateway leverages shared cluster cache so all Gateway instances can access the same cached data. This provides a stronger offline mode for multi-instance deployments. - -## Behavior during both Gateway and SaaS outage - -If all Gateway instances are down, no requests can be served regardless of cache status. - -If Gateways restart while SaaS is still down, they try to load configuration, identities, secrets, and auth data from cluster cache. If cluster cache is unavailable, Gateways start without cached data and cannot serve requests until SaaS or cluster cache is restored. - -If cluster cache is available, Gateways warm from cluster cache and can operate in degraded offline mode for cached secrets and authentication. - -## Do behaviors differ by client type (for example, Injector versus ESO)? - -Core caching behavior and outage impact on Gateway are the same regardless of client type. Both Akeyless Injector and External Secrets Operator (ESO) call Gateway REST APIs. - -ESO's sync model generally provides more resilience for applications during Gateway or SaaS outages, since applications consume local Kubernetes Secret objects. Injector may cause pod startup failures or stale values if an outage occurs during injection and `AKEYLESS_CRASH_POD_ON_ERROR` is enabled. - -## Gateway cache deployment configuration options - -| Name | Description | -| --- | --- | -| `CACHE_ENABLE` | Whether cache is enabled. | -| `PROACTIVE_CACHE_ENABLE` | Whether proactive caching is enabled. | -| `NEW_PROACTIVE_CACHE_ENABLE` | Whether to use the newer proactive cache mechanism. | -| `PREFER_CLUSTER_CACHE_FIRST` | Whether to read cluster cache before local cache. | -| `CACHE_MAX_ITEMS` | Maximum number of proactive cache items (overrides default 50K). | -| `IGNORE_REDIS_HEALTH` | Whether `/health` should ignore Redis outage and still return `200 OK`. | - -These settings apply consistently to both Kubernetes/Helm and VM/Docker deployments. - -## Behavior when caching is enabled and a user updates a secret in UI - -When a secret is updated in UI, value retrieval by CLI/API may initially return the cached value, then sync and return the new value after cache refresh. Gateway updates local cache first, then cluster cache. - -If `PREFER_CLUSTER_CACHE_FIRST` is enabled, values are fetched from cluster cache first, which helps return newer values when multiple Gateway instances exist. - -If no request is made immediately, proactive cache updates values on its next refresh interval. - -## When SaaS is considered down for token validation and expiration - -Gateway continuously monitors SaaS connectivity. On failed connectivity checks, it switches to offline mode. While SaaS is unreachable, token validation and expiration checks are suspended. Cached tokens remain valid until SaaS connectivity is restored. - -## `Ignore Cache` behavior in disconnected mode - -By default, Gateway caches secrets for performance and resilience. `Ignore Cache` is intended to bypass cache and fetch the latest secret from SaaS. - -In disconnected mode, Gateway cannot reach SaaS. Therefore: - -* With `Ignore Cache` enabled, Gateway still checks local cache first. -* If secret exists in cache, Gateway returns cached value. -* If secret does not exist in cache, request fails because SaaS cannot be reached. diff --git a/docs/Akeyless Gateway/configure-gateway/gateway-caching/_order.yaml b/docs/Akeyless Gateway/configure-gateway/gateway-caching/_order.yaml new file mode 100644 index 00000000..9b28eb50 --- /dev/null +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/_order.yaml @@ -0,0 +1,4 @@ +- runtime-caching +- proactive-caching +- cluster-cache-standalone +- cluster-cache-ha diff --git a/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-ha.md b/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-ha.md new file mode 100644 index 00000000..c204e14e --- /dev/null +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-ha.md @@ -0,0 +1,124 @@ +--- +title: Cluster Cache HA +excerpt: '' +deprecated: false +hidden: false +metadata: + title: '' + description: '' + robots: index +next: + description: '' +--- +Cluster Cache High Availability (HA) uses a [Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/) topology for resilient shared cache service. + +> ℹ️ **Note:** +> Cluster Cache HA uses Redis Sentinel for failover and higher cache service resilience. +> If you prefer a simpler single-Redis topology with lower operational overhead, use [Cluster Cache (Standalone)](https://docs.akeyless.io/docs/cluster-cache-standalone). + +## Read Behavior + +When Cluster Cache HA 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](https://docs.akeyless.io/docs/gateway-caching). + +### Local Cache and Cluster Cache Read Preference + +When Cluster Cache HA is enabled, `PREFER_CLUSTER_CACHE_FIRST` controls read preference between the local in-memory cache and the HA 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 + +Cluster Cache HA 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, HA persistence is controlled by `cacheHA.persistentVolume.enabled`: + +* `true` (default): PVCs are mounted and Redis can persist to disk so cache data can be retained across restarts and rescheduling. +* `false`: no PersistentVolumeClaim (PVC) is mounted, so cache data is ephemeral and can be lost when cache pods restart or are rescheduled. + +For Kubernetes storage behavior details, see [Persistent Volumes and Claims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) and [StorageClasses](https://kubernetes.io/docs/concepts/storage/storage-classes/). + +## When to Use + +Use Cluster Cache HA when: + +* You need cache availability during single-pod or single-node failures. +* You run multi-pod Gateway workloads that require resilient shared cache service. +* Your platform requirements justify [Redis Sentinel operational overhead](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/#fundamental-things-to-know-about-sentinel-before-deploying). + +## When Not to Use + +Do not use Cluster Cache HA when: + +* You run a simple or low-scale environment where standalone Redis is sufficient. +* You want the smallest operational footprint for cache infrastructure. + +## Configuring Cluster Cache High Availability (HA) + +Use the following deployment-specific options to configure Cluster Cache HA: + +| Deployment option | How to configure | +| --- | --- | +| Gateway Console | Not supported. Cluster Cache HA is deployment-level and is configured in infrastructure manifests. | +| [Kubernetes (Helm)](https://docs.akeyless.io/docs/gateway-deploy-kubernetes-helm) | Set `cacheHA.enabled=true` in `values.yaml`. Configure authentication, persistence, and scheduling keys under `cacheHA.*`, then [apply a Helm upgrade](https://helm.sh/docs/helm/helm_upgrade/). | +| [Standalone Docker](https://docs.akeyless.io/docs/gateway-deploy-standalone-docker) | Not supported. Cluster Cache HA topology is not configured as a Docker-only deployment option. | +| [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose) | Not supported as a documented deployment mode for Cluster Cache HA topology. | +| [Serverless AWS](https://docs.akeyless.io/docs/gateway-deploy-serverless-aws) and [Serverless Azure](https://docs.akeyless.io/docs/gateway-deploy-serverless-azure) | Not supported. Cluster Cache HA topology requires Kubernetes deployment resources. | + +Example (`values.yaml`): + +```yaml values.yaml +globalConfig: + env: + - name: PREFER_CLUSTER_CACHE_FIRST + value: "false" +cacheHA: + enabled: true + replicas: 3 + auth: true + authKey: redis-password + existingSecret: "gw-cluster-cache-ha" + persistentVolume: + enabled: true + storageClass: "" + size: 10Gi +``` + +For the full key reference, see [Helm Values Reference](https://docs.akeyless.io/docs/gateway-kubernetes-helm-values-reference). + +### Cluster Cache (HA) Values + +* `cacheHA.enabled`: Enables HA cluster cache with Redis Sentinel. +* `PREFER_CLUSTER_CACHE_FIRST` (under `globalConfig.env`): Controls read order between local in-memory cache and HA Redis cache. For value behavior, see [Local Cache and Cluster Cache Read Preference](https://docs.akeyless.io/docs/cluster-cache-ha#local-cache-and-cluster-cache-read-preference). +* `cacheHA.replicas`: Sets the number of HA Redis pods. +* `cacheHA.auth`: Enables password authentication for HA Redis and Sentinel endpoints. Use `true` in shared or multi-tenant clusters where unauthenticated Redis access is not acceptable. +* `cacheHA.authKey`: Sets the secret key name that stores the Redis password in the [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) referenced by `cacheHA.existingSecret`. +* `cacheHA.existingSecret`: Uses an existing [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) that contains the Redis password. Use this when your platform manages secrets centrally (for example, External Secrets or an existing secret-management workflow). +* `cacheHA.persistentVolume.enabled`: Enables or disables persistent storage for HA Redis data so cache data can survive pod restarts, container restarts, and pod rescheduling events. +* `cacheHA.persistentVolume.storageClass`: Sets the [Kubernetes StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/) used for HA Redis [PersistentVolumeClaims (PVCs)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims). +* `cacheHA.persistentVolume.size`: Sets the requested PVC size for HA Redis data. See [Kubernetes Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory). +* `cacheHA.hardAntiAffinity`: Uses required [pod anti-affinity](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity) rules to spread HA cache pods across nodes. Use this when node-level failure tolerance is required. +* `cacheHA.topologySpreadConstraints.*`: Configures [topology spread constraints](https://kubernetes.io/docs/concepts/scheduling-eviction/topology-spread-constraints/) to balance pods across zones or nodes according to your availability policy. + +For complete values and examples, see [Helm Values Reference](https://docs.akeyless.io/docs/gateway-kubernetes-helm-values-reference). diff --git a/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md b/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md new file mode 100644 index 00000000..a8eeeeeb --- /dev/null +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md @@ -0,0 +1,119 @@ +--- +title: Cluster Cache (Standalone) +excerpt: '' +deprecated: false +hidden: false +metadata: + title: '' + description: '' + robots: index +next: + description: '' +--- +Standalone cluster cache provides a shared Redis-backed cache across Gateway pods. This improves cross-pod cache consistency compared to [local in-memory cache](https://docs.akeyless.io/docs/runtime-caching). + +> ℹ️ **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)](https://docs.akeyless.io/docs/cluster-cache-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](https://docs.akeyless.io/docs/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](https://redis.io/docs/latest/operate/oss_and_stack/management/config/) and [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/). + +For Kubernetes storage behavior details, see [Persistent Volumes and Claims](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) and [StorageClasses](https://kubernetes.io/docs/concepts/storage/storage-classes/). + +## 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: + +| Deployment option | How to configure | +| --- | --- | +| Gateway Console | Not supported. Standalone cluster cache topology is deployment-level and is configured in infrastructure manifests. | +| [Kubernetes (Helm)](https://docs.akeyless.io/docs/gateway-deploy-kubernetes-helm) | Set `globalConfig.clusterCache.enabled=true` in `values.yaml`. Configure persistence with `globalConfig.clusterCache.persistence.*` as needed, then [apply a Helm upgrade](https://helm.sh/docs/helm/helm_upgrade/). | +| [Standalone Docker](https://docs.akeyless.io/docs/gateway-deploy-standalone-docker) | Not supported. Standalone cluster cache topology is not configured as a Docker-only deployment option. | +| [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose) | Not supported as a documented deployment mode for standalone cluster cache topology. | +| [Serverless AWS](https://docs.akeyless.io/docs/gateway-deploy-serverless-aws) and [Serverless Azure](https://docs.akeyless.io/docs/gateway-deploy-serverless-azure) | Not supported. Standalone cluster cache topology requires Kubernetes deployment resources. | + +Example (`values.yaml`): + +```yaml 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](https://docs.akeyless.io/docs/gateway-kubernetes-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](https://docs.akeyless.io/docs/cluster-cache-standalone#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)](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#persistentvolumeclaims) instead of creating a new one. +* `globalConfig.clusterCache.persistence.accessMode`: Sets the PVC access mode (for example, `ReadWriteOnce`). See [Access Modes](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes). +* `globalConfig.clusterCache.persistence.storageClass`: Sets the Kubernetes [StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/) for the PVC. +* `globalConfig.clusterCache.persistence.size`: Sets the requested PVC size. See [Kubernetes Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#meaning-of-memory). +* `globalConfig.clusterCache.extraArgs`: Passes Redis runtime arguments to the standalone cache container. For supported options, see [Redis configuration](https://redis.io/docs/latest/operate/oss_and_stack/management/config/) and [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/). diff --git a/docs/Akeyless Gateway/configure-gateway/gateway-caching/index.md b/docs/Akeyless Gateway/configure-gateway/gateway-caching/index.md new file mode 100644 index 00000000..ab64d144 --- /dev/null +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/index.md @@ -0,0 +1,58 @@ +--- +title: Gateway Caching +excerpt: '' +deprecated: false +hidden: false +metadata: + title: '' + description: '' + robots: index +next: + description: '' +--- +Use this section to choose the right Gateway caching method for your environment. + +## Cache Types + +Gateway caching has four practical patterns to choose from: + +| Type | Best for | Avoid when | +| --- | --- | --- | +| [Runtime Caching](https://docs.akeyless.io/docs/runtime-caching) | Standard request acceleration and reduced repeated SaaS fetches | You need all reads to always bypass cache | +| [Proactive Caching](https://docs.akeyless.io/docs/proactive-caching) | Pre-warming and refresh jobs to reduce first-read latency | Your environment is rate-limit constrained | +| [Cluster Cache (Standalone)](https://docs.akeyless.io/docs/cluster-cache-standalone) | Shared Redis cache for multi-pod Gateway with low operational overhead | You require cache failover across Redis node or pod failures | +| [Cluster Cache High Availability (HA)](https://docs.akeyless.io/docs/cluster-cache-ha) | Sentinel-based high-availability cache service for resilient shared cache | You prefer the simplest deployment footprint and can accept standalone Redis risk | + +## Choosing a Caching Method + +Use this starting decision flow: + +1. Start with runtime caching for most environments. +2. Add proactive caching when you need faster first-read performance for frequently used secrets. +3. Add standalone cluster cache when running multiple Gateway pods that should share cache state. +4. Use Cluster Cache High Availability (HA) when shared cache availability across failures is a requirement. + +For planning guidance and tradeoffs, see [Gateway Best Practices: Caching strategy considerations](https://docs.akeyless.io/docs/gateway-best-practices#caching-strategy-considerations). + +For Kubernetes proactive cache sizing guidance, see [Gateway Best Practices: Resource planning for Kubernetes proactive cache](https://docs.akeyless.io/docs/gateway-best-practices#resource-planning-for-kubernetes-proactive-cache). + +## Configure in Gateway UI + +To manage cache runtime settings from Gateway Configuration Manager: + +1. Open `https://:8000/console`. +2. Go to **Gateways** > **Your Gateway** > **Manage Gateway** > **Caching Configuration**. +3. Configure cache and proactive cache options. +4. Save changes. + +For Kubernetes deployment keys (`globalConfig.clusterCache`, `cacheHA`, and persistence options), see [Helm Values Reference](https://docs.akeyless.io/docs/gateway-kubernetes-helm-values-reference). + +## ignore-cache Behavior + +The `ignore-cache` flag is intended to bypass cache and fetch directly from SaaS. + +```shell +akeyless get-secret-value --name /mysecret --ignore-cache true +``` + +In disconnected mode (when SaaS is unreachable), runtime still checks cache first even when `ignore-cache=true`. If the value is not cached, the request fails. diff --git a/docs/Akeyless Gateway/configure-gateway/gateway-caching/proactive-caching.md b/docs/Akeyless Gateway/configure-gateway/gateway-caching/proactive-caching.md new file mode 100644 index 00000000..3b3c7337 --- /dev/null +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/proactive-caching.md @@ -0,0 +1,134 @@ +--- +title: Proactive Caching +excerpt: '' +deprecated: false +hidden: false +metadata: + title: '' + description: '' + robots: index +next: + description: '' +--- +Proactive caching preloads and refreshes cache entries in the background to reduce first-read latency. + +> ℹ️ **Note:** +> Proactive caching requires [runtime cache](https://docs.akeyless.io/docs/runtime-caching) and base proactive cache to be enabled (`CACHE_ENABLE=true` and `PROACTIVE_CACHE_ENABLE=true`). +> To use the recommended implementation, also set `NEW_PROACTIVE_CACHE_ENABLE=true`. + +## Sync Behavior + +Proactive cache runs when `CACHE_ENABLE=true` and `PROACTIVE_CACHE_ENABLE=true`. + +The recommended implementation runs when `NEW_PROACTIVE_CACHE_ENABLE=true` is also set. + +1. Leadership: One Gateway pod acquires a leadership lock for proactive work. +2. Startup full fetch: The leader performs an initial list-and-load pass. +3. Modified-secrets fetch: Runs every `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME` interval. +4. Full fetch: Runs every full-fetch interval (`CACHE_TTL`-based). +5. Zombie cleanup: During full fetch, items missing from current inventory are removed from cache. + +If SaaS connectivity is unavailable, proactive jobs stop pulling from SaaS and resume when connectivity returns. + +`--ignore-cache` attempts to bypass cache and read directly from SaaS; for full behavior details, see [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching). + +### Access ID Used by Proactive Cache + +Proactive cache authenticates to SaaS using the Gateway admin access ID (`GW_ACCESS_ID` / `gatewayAccessId`). + +All `list-items` and `get-value` calls during warm-up are issued under this identity. Proactive warm-up consumes the per-access-ID SaaS rate-limit quota for that access ID. + +### Rate-Limit Behavior + +429 responses can occur when startup warm-up fan-out exhausts the per-access-ID limit window. The recommended implementation handles this automatically with a shared backoff gate: + +* Applies a shared backoff delay across all workers on 429. +* Honors `Retry-After` or `will be released in ` headers when available. +* Retries up to `PROACTIVE_CACHE_WORKERS × 10` attempts before giving up on a cycle. + +To further reduce rate-limit risk: + +* Reduce `PROACTIVE_CACHE_WORKERS` to lower burst concurrency. +* Increase `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME` to reduce incremental cycle frequency. +* Restrict admin access ID visibility using RBAC so fewer items are warmed up. +* Enable or restart proactive cache during low-traffic windows. + +## When to Use + +Use proactive caching when: + +* You want to eliminate first-read latency across your full secrets inventory. +* You want cache to remain warm through planned cache restarts or Gateway reschedules. +* You run multi-pod Gateway workloads and want consistent pre-warmed state across pods. + +## When Not to Use + +Do not use proactive caching when: + +* Your secrets inventory is very large and startup warm-up would exhaust SaaS rate limits. +* You want each read to reflect the latest SaaS value without a background warm-up delay. + +## Configuring Proactive Caching + +| Deployment option | How to configure | +| --- | --- | +| Gateway Console | In the Gateway UI, go to **Manage Gateway** > **Caching Configuration** and enable proactive caching options. | +| [Kubernetes (Helm)](https://docs.akeyless.io/docs/gateway-deploy-kubernetes-helm) | Set environment variables under `globalConfig.env` in `values.yaml` and [apply a Helm upgrade](https://helm.sh/docs/helm/helm_upgrade/). | +| [Standalone Docker](https://docs.akeyless.io/docs/gateway-deploy-standalone-docker) | Set proactive cache environment variables in container runtime configuration. | +| [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose) | Set the same environment variables in the compose service definition and redeploy. | +| [Serverless AWS](https://docs.akeyless.io/docs/gateway-deploy-serverless-aws) and [Serverless Azure](https://docs.akeyless.io/docs/gateway-deploy-serverless-azure) | Set environment variables in the serverless deployment configuration and redeploy. | + +Example (`values.yaml`): + +```yaml values.yaml +globalConfig: + env: + - name: CACHE_ENABLE + value: "true" + - name: PROACTIVE_CACHE_ENABLE + value: "true" + - name: NEW_PROACTIVE_CACHE_ENABLE + value: "true" + - name: PROACTIVE_CACHE_WORKERS + value: "3" + - name: PROACTIVE_CACHE_MINIMUM_FETCHING_TIME + value: "5" + - name: CACHE_TTL + value: "60" +``` + +For the full key reference, see [Helm Values Reference](https://docs.akeyless.io/docs/gateway-kubernetes-helm-values-reference). + +### Proactive Caching Environment Variables + +* `CACHE_ENABLE`: Enables the Gateway [runtime cache](https://docs.akeyless.io/docs/runtime-caching) subsystem required by proactive caching. Default: `false`. +* `PROACTIVE_CACHE_ENABLE`: Enables base proactive caching behavior. Default: `false`. +* `NEW_PROACTIVE_CACHE_ENABLE`: Enables proactive caching using the recommended implementation with configurable worker count and shared rate-limit backoff on 429 responses. Default: `false`. If this remains `false` while `CACHE_ENABLE=true` and `PROACTIVE_CACHE_ENABLE=true`, Gateway uses the legacy proactive implementation described in [Migrating from Legacy Proactive Caching](https://docs.akeyless.io/docs/proactive-caching#migrating-from-legacy-proactive-caching). +* `PROACTIVE_CACHE_WORKERS`: Sets the number of concurrent fetch workers for the recommended implementation (requires `NEW_PROACTIVE_CACHE_ENABLE=true`). Default: `3`. Reduce to lower startup fan-out. +* `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME`: Sets the modified-secrets fetch interval in minutes for proactive caching. Default: `5`. Increase to reduce incremental cycle frequency. This value affects proactive refresh cadence in both the legacy and recommended implementations. +* `CACHE_TTL`: Influences cache time-to-live and full-fetch cadence. Default: `60`. + +For Redis topology choices, see [Cluster Cache (Standalone)](https://docs.akeyless.io/docs/cluster-cache-standalone) and [Cluster Cache High Availability (HA)](https://docs.akeyless.io/docs/cluster-cache-ha). + +## Migrating from Legacy Proactive Caching + +The legacy implementation is enabled when `CACHE_ENABLE=true` and `PROACTIVE_CACHE_ENABLE=true` without `NEW_PROACTIVE_CACHE_ENABLE=true`. On the legacy `akeyless-api-gateway` chart, this was also exposed as the `cachingConf.proActiveCaching.enabled` value. + +| | Legacy | Current | +| --- | --- | --- | +| Enabled by | `CACHE_ENABLE=true` + `PROACTIVE_CACHE_ENABLE=true` | `CACHE_ENABLE=true` + `PROACTIVE_CACHE_ENABLE=true` + `NEW_PROACTIVE_CACHE_ENABLE=true` | +| Workers | 5 (fixed) | 3 (default, configurable via `PROACTIVE_CACHE_WORKERS`) | +| Rate-limit handling | None | `RateLimitGate` shared backoff on 429 | +| Chart | `akeyless-api-gateway` or env var only | `akeyless-gateway` | + +The legacy implementation uses a fixed worker count with no 429 handling, which can cause repeated rate-limit failures during startup warm-up on large accounts. The new implementation adds backoff and retry logic, configurable concurrency, and is the only implementation that will receive improvements going forward. + +If you remain on the legacy implementation, `PROACTIVE_CACHE_DUMP_INTERVAL` controls the periodic secure cache backup interval. Most legacy tuning decisions should still start with `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME`, while `PROACTIVE_CACHE_DUMP_INTERVAL` is mainly relevant when you need to adjust backup cadence. + +To migrate: + +1. If on the `akeyless-api-gateway` chart, [migrate to the akeyless-gateway chart](https://docs.akeyless.io/docs/gateway-deploy-kubernetes-helm) first. +2. Remove any `cachingConf.proActiveCaching.*` values if present. +3. Add `CACHE_ENABLE=true`, `PROACTIVE_CACHE_ENABLE=true`, and `NEW_PROACTIVE_CACHE_ENABLE=true` to `globalConfig.env` as shown in the [configuration example above](#configuring-proactive-caching). +4. Optionally tune `PROACTIVE_CACHE_WORKERS` and `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME`. +5. Apply a Helm upgrade. diff --git a/docs/Akeyless Gateway/configure-gateway/gateway-caching/runtime-caching.md b/docs/Akeyless Gateway/configure-gateway/gateway-caching/runtime-caching.md new file mode 100644 index 00000000..9effa302 --- /dev/null +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/runtime-caching.md @@ -0,0 +1,95 @@ +--- +title: Runtime Caching +excerpt: '' +deprecated: false +hidden: false +metadata: + title: '' + description: '' + robots: index +next: + description: '' +--- +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)](https://docs.akeyless.io/docs/cluster-cache-standalone) or [Cluster Cache High Availability (HA)](https://docs.akeyless.io/docs/cluster-cache-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](https://docs.akeyless.io/docs/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)](https://docs.akeyless.io/docs/cluster-cache-standalone) and [Cluster Cache High Availability (HA)](https://docs.akeyless.io/docs/cluster-cache-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: + +| Deployment option | How to configure | +| --- | --- | +| Gateway Console | In the Gateway UI, go to **Manage Gateway** > **Caching Configuration** and set runtime caching options. | +| [Kubernetes (Helm)](https://docs.akeyless.io/docs/gateway-deploy-kubernetes-helm) | Set runtime behavior keys under `globalConfig.env` in `values.yaml` (for example `CACHE_ENABLE`, `PREFER_CLUSTER_CACHE_FIRST`) and [apply a Helm upgrade](https://helm.sh/docs/helm/helm_upgrade/). Set `IGNORE_REDIS_HEALTH` separately when you want to change health-check behavior. | +| [Standalone Docker](https://docs.akeyless.io/docs/gateway-deploy-standalone-docker) | Set cache-related environment variables (for example `CACHE_ENABLE`, `PREFER_CLUSTER_CACHE_FIRST`) in container runtime configuration. | +| [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose) | Set the same cache-related environment variables in the compose service definition and redeploy. | +| [Serverless AWS](https://docs.akeyless.io/docs/gateway-deploy-serverless-aws) and [Serverless Azure](https://docs.akeyless.io/docs/gateway-deploy-serverless-azure) | Set cache-related environment variables in the serverless deployment configuration and redeploy. | + +Example (`values.yaml`): + +```yaml 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](https://docs.akeyless.io/docs/runtime-caching#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. diff --git a/docs/Akeyless Gateway/deploy-gateway/gateway-cloud-serverless-deployments/gateway-deploy-serverless-aws.md b/docs/Akeyless Gateway/deploy-gateway/gateway-cloud-serverless-deployments/gateway-deploy-serverless-aws.md index b50dcc8a..a1342d5d 100644 --- a/docs/Akeyless Gateway/deploy-gateway/gateway-cloud-serverless-deployments/gateway-deploy-serverless-aws.md +++ b/docs/Akeyless Gateway/deploy-gateway/gateway-cloud-serverless-deployments/gateway-deploy-serverless-aws.md @@ -199,7 +199,7 @@ The **Serverless Gateway** will boot with the version you chose. The Akeyless Serverless Gateway does not support: * [Kubernetes](https://docs.akeyless.io/docs/auth-with-kubernetes) and [LDAP](https://docs.akeyless.io/docs/auth-with-ldap) Authentication Methods -* [Caching](https://docs.akeyless.io/docs/configure-the-gateway-cache) +* [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching) (runtime and proactive caching options are covered in this section) * [Automatic Migration](https://docs.akeyless.io/docs/automatic-migration) * Event on Gateway status change * [TLS Configuration](https://docs.akeyless.io/docs/gateway-tls-settings) diff --git a/docs/Akeyless Gateway/deploy-gateway/gateway-cloud-serverless-deployments/gateway-deploy-serverless-azure.md b/docs/Akeyless Gateway/deploy-gateway/gateway-cloud-serverless-deployments/gateway-deploy-serverless-azure.md index 5ea90366..db8ac4d8 100644 --- a/docs/Akeyless Gateway/deploy-gateway/gateway-cloud-serverless-deployments/gateway-deploy-serverless-azure.md +++ b/docs/Akeyless Gateway/deploy-gateway/gateway-cloud-serverless-deployments/gateway-deploy-serverless-azure.md @@ -273,7 +273,7 @@ To configure your Akeyless Gateway: * [Kubernetes](https://docs.akeyless.io/docs/auth-with-kubernetes) * [LDAP Authentication](https://docs.akeyless.io/docs/auth-with-ldap) -* [Caching](https://docs.akeyless.io/docs/configure-the-gateway-cache) +* [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching) (runtime and proactive caching options are covered in this section) * [Automatic Migration](https://docs.akeyless.io/docs/automatic-migration) * Event on Gateway Status Change * [TLS Configuration](https://docs.akeyless.io/docs/gateway-tls-settings). diff --git a/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-docker-compose.md b/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-docker-compose.md index 0c97d651..e5676800 100644 --- a/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-docker-compose.md +++ b/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-docker-compose.md @@ -160,7 +160,7 @@ Full list of available permissions: | `classic_keys` | Management of [Classic Keys](https://docs.akeyless.io/docs/classic-keys) | | `log_forwarding` | Management of [Log Forwarding](https://docs.akeyless.io/docs/log-forwarding) settings | | `zero_knowledge_encryption` | Management of [Zero-Knowledge](https://docs.akeyless.io/docs/zero-knowledge) | -| `caching` | Management of [Gateway Cache](https://docs.akeyless.io/docs/configure-the-gateway-cache) settings | +| `caching` | Management of [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching) settings | | `event_forwarding` | Management of [Event](https://docs.akeyless.io/docs/event-center) Forwarding settings | | `ldap_auth` | Management of [LDAP](https://docs.akeyless.io/docs/auth-with-ldap) Auth Gateway configuration. | | `k8s_auth` | Management of [Kubernetes](https://docs.akeyless.io/docs/auth-with-kubernetes) Auth Gateway configuration | diff --git a/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-kubernetes-helm/gateway-kubernetes-helm-values-reference.md b/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-kubernetes-helm/gateway-kubernetes-helm-values-reference.md index 64ababee..541d8b6d 100644 --- a/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-kubernetes-helm/gateway-kubernetes-helm-values-reference.md +++ b/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-kubernetes-helm/gateway-kubernetes-helm-values-reference.md @@ -154,88 +154,83 @@ Once the Gateway is running, you can set the matching AccessID as your OIDC defa ## Cache Settings -### Cache Configuration +This section covers Helm cache deployment options. For cache behavior, terminology, outage semantics, and request flow details, see [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching). -To set up your deployment with **Cluster Cache**, the following settings will display the setup of this service from the deployment perspective. Once it's enabled on the deployment level, you should turn on the desired mode of the [Gateway Cache](https://docs.akeyless.io/docs/configure-the-gateway-cache) using the console or directly with the API. +### Cluster Cache (Standalone) -To set an internal TLS between the Gateway and cache service, set the `enableTls: true` option: +Use standalone cluster cache when Gateway pods need a shared Redis cache service. -```yaml +```yaml values.yaml +globalConfig: clusterCache: enabled: true enableTls: false ``` -To set the cache on your gateway with a default encryption key to support full offline mode, create a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) that includes your `cluster-cache-encryption-key` Base64-encoded: - -```shell -kubectl create secret generic cache-configuration \ - --from-literal=cluster-cache-encryption-key= -``` - -And add to the `values.yaml` file the Kubernetes Secret name: +To enable durable storage for standalone cluster cache, configure persistence: ```yaml values.yaml +globalConfig: clusterCache: - encryptionKeyExistingSecret: "cache-configuration" - enableTls: false + enabled: true + persistence: + enabled: true + existingClaim: "" + accessMode: "ReadWriteOnce" + storageClass: "" + size: 10Gi ``` -To force the Cache to write only to memory without writing to the file system, you can use `extraArgs`: +If `globalConfig.clusterCache.persistence.enabled` is `false`, the standalone cache does not mount a PersistentVolumeClaim at `/data`. -```yaml values.yaml - clusterCache: - enabled: true - extraArgs: - - --save - - "" - - --appendonly - - "no" -``` +Optional Redis runtime flags can be passed through `globalConfig.clusterCache.extraArgs`. This key is a direct pass-through to the `redis-server` command arguments for the standalone cluster cache pod. -To set a persistence volume you can set this with your [StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/) according to your environment, or using `emptyDir`: +* Supported options are Redis server command-line flags, documented by Redis: + * [Redis configuration](https://redis.io/docs/latest/operate/oss_and_stack/management/config/) + * [Redis persistence](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) +* There are no Akeyless-specific `extraArgs` keys. Akeyless does not parse custom keys under this field. -```yaml values.yaml with storageClass - clusterCache: - enabled: true - persistence: - enabled: false - existingClaim: "" - accessMode: "ReadWriteOnce" - storageClass: "" - size: 10Gi -``` -```yaml values.yaml with empty dir - clusterCache: - enabled: true - persistence: - extraVolumes: - - name: cache-data - emptyDir: {} +Example (`values.yaml`): - extraVolumesMounts: - - name: cache-data - mountPath: /data +```yaml values.yaml +globalConfig: + clusterCache: + extraArgs: + - --save + - "" + - --appendonly + - "no" ``` -To control the cache settings, you can [configure the cache](https://docs.akeyless.io/docs/configure-the-gateway-cache) using the Gateway Configuration Manager. +In this example, Redis snapshotting and AOF persistence are disabled by explicit Redis flags. -#### High Availability Cache +### Cluster Cache HA (`cacheHA`) -While the **Cache** setup can address many cases for some environments, there is a requirement for a full high availability architecture of the **Cache** service, in such cases when the `cacheHA` is enabled, it will **override** all existing settings of the default cache. The HA mode of the cache **must** be set with a with the `ReadWriteOnce` access mode, using this configuration requires running `helm dependency update`. +Enable `cacheHA` for a high-availability [Redis Sentinel](https://redis.io/docs/latest/operate/oss_and_stack/management/sentinel/) topology. When `cacheHA.enabled=true`, this mode replaces the default standalone cache service. -> ℹ️ **Note:** -> -> This feature is available only from GW version `4.34.0` and higher. To use Cache HA, **existing** GW Helm deployments must be fully uninstalled before proceeding with the Cache HA setup. +```yaml values.yaml +cacheHA: + enabled: true + nameOverride: cluster-cache-ha + replicas: 3 + auth: true + authKey: redis-password + existingSecret: "{{ .Release.Name }}-cluster-cache-ha" +``` -To set the default encryption key to support full offline mode, create a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) that includes your `cluster-cache-encryption-key` Base64-encoded: +Cache HA persistence is controlled separately: -```yaml -kubectl create secret generic cache-configuration \ - --from-literal=cluster-cache-encryption-key= +```yaml values.yaml +cacheHA: + persistentVolume: + enabled: true + storageClass: ~ + accessModes: + - ReadWriteOnce + size: 10Gi ``` -Set your [StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/) according to your environment, for example: +Set the appropriate [StorageClass](https://kubernetes.io/docs/concepts/storage/storage-classes/) according to the environment, for example: ```yaml AWS apiVersion: storage.k8s.io/v1 @@ -290,37 +285,26 @@ parameters: encrypted: "true" ``` -Edit the following section in your `values.yaml` file: +If you enable `cacheHA`, set or review the following keys to configure authentication and pod placement behavior: -```yaml +```yaml values.yaml cacheHA: - enabled: false - nameOverride: cluster-cache-ha - replicas: 3 - + enabled: true auth: true authKey: redis-password existingSecret: "{{ .Release.Name }}-cluster-cache-ha" - - tls: - secretName: "{{ .Release.Name }}-cluster-cache-ha-tls" - certFile: tls.crt - keyFile: tls.key - caCertFile: ca.crt - certValidityDays: 1825 - hardAntiAffinity: false ``` -To set **Authentication**, `auth` must be set to `true`, which requires a password stored in a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) specified by `existingSecret` for the secret name and `authKey` for the key containing the password. In our example: `redis-password`. +To configure cache authentication, set `auth: true` and store the password in a [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) referenced by `existingSecret` and `authKey`. When **TLS** is enabled, the Gateway deployment automatically generates a Kubernetes Secret containing the TLS certificate and key. -For production environment, set the `hardAntiAffinity` option to ensure that Gateway pods are scheduled on different nodes. +For production environments, set `hardAntiAffinity` to schedule cache HA pods on different nodes. Additionally, you can add topology spread constraint settings to control how pods are spread across your cluster in the event of failures. The full configuration settings can be found in this [link](https://github.com/DandyDeveloper/charts/blob/master/charts/redis-ha/values.yaml). -To control the cache settings, you should [configure the cache](https://docs.akeyless.io/docs/configure-the-gateway-cache#/) using the Gateway Configuration Manager. +For cache runtime behavior, terminology, `ignore-cache`, and outage semantics, see [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching). #### Cluster Cache Encryption Key and Offline Scale-Out diff --git a/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-kubernetes-helm/index.md b/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-kubernetes-helm/index.md index 52a97542..604e8e1a 100644 --- a/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-kubernetes-helm/index.md +++ b/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-kubernetes-helm/index.md @@ -430,7 +430,7 @@ Full list of available permissions: | `automatic_migration` | Management of [Dynamic Secrets](https://docs.akeyless.io/docs/how-to-create-dynamic-secret) settings | | `log_forwarding` | Management of [Log Forwarding](https://docs.akeyless.io/docs/log-forwarding) settings | | `zero_knowledge_encryption` | Management of [Zero-Knowledge](https://docs.akeyless.io/docs/zero-knowledge) | -| `caching` | Management of [Gateway Cache](https://docs.akeyless.io/docs/configure-the-gateway-cache) settings | +| `caching` | Management of [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching) settings | | `event_forwarding` | Management of [Event](https://docs.akeyless.io/docs/event-center) Forwarding settings | | `ladp_auth` | Management of [LDAP](https://docs.akeyless.io/docs/auth-with-ldap) Auth Gateway configuration. | | `k8s_auth` | Management of [Kubernetes](https://docs.akeyless.io/docs/auth-with-kubernetes) Auth Gateway configuration | diff --git a/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-standalone-docker/gateway-docker-advanced-configuration.md b/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-standalone-docker/gateway-docker-advanced-configuration.md index 8517d6a1..a50ed743 100644 --- a/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-standalone-docker/gateway-docker-advanced-configuration.md +++ b/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-standalone-docker/gateway-docker-advanced-configuration.md @@ -181,7 +181,7 @@ Full list of available permissions: | `rotate_secret_value` | Grants permission **only** to rotate the secret value, without allowing manual edits. Requires `read` permission on the item | | `log_forwarding` | Management of [Log Forwarding](https://docs.akeyless.io/docs/log-forwarding) settings | | `zero_knowledge_encryption` | Management of [Zero-Knowledge](https://docs.akeyless.io/docs/zero-knowledge) | -| `caching` | Management of [Gateway Cache](https://docs.akeyless.io/docs/configure-the-gateway-cache) settings | +| `caching` | Management of [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching) settings | | `event_forwarding` | Management of [Event](https://docs.akeyless.io/docs/event-center) Forwarding settings | | `ldap_auth` | Management of [LDAP](https://docs.akeyless.io/docs/auth-with-ldap) Auth Gateway configuration. | | `k8s_auth` | Management of [Kubernetes](https://docs.akeyless.io/docs/auth-with-kubernetes) Auth Gateway configuration | @@ -355,24 +355,20 @@ The variables `MIN_TLS_VERSION=TLSv1.3` and `GODEBUG=tlsmlkem=1` enable hybrid P ### Cache Configuration -You can enable **Local In-Memory** caching of secrets and the periodic backup of cached secrets +Use these environment variables to enable runtime and proactive cache features for Docker deployments. + +For behavior, topology semantics, and recommended proactive cache settings, see [Gateway Caching](https://docs.akeyless.io/docs/configure-the-gateway-cache). ```shell -docker run -d -p 8000:8000 -p 5696:5696 -e GATEWAY_ACCESS_ID="p-xxxxxxxxxxxx" -e GATEWAY_ACCESS_KEY="62Hu...xxx....qlg=" -e CACHE_ENABLE="true" -e PROACTIVE_CACHE_ENABLE="true" -e CACHE_TTL="60" -e PROACTIVE_CACHE_MINIMUM_FETCHING_TIME="5" -e PROACTIVE_CACHE_DUMP_INTERVAL="1" --name akeyless-gw akeyless/base:latest-akeyless +docker run -d -p 8000:8000 -p 5696:5696 -e GATEWAY_ACCESS_ID="p-xxxxxxxxxxxx" -e GATEWAY_ACCESS_KEY="62Hu...xxx....qlg=" -e CACHE_ENABLE="true" -e PROACTIVE_CACHE_ENABLE="true" -e NEW_PROACTIVE_CACHE_ENABLE="true" -e CACHE_TTL="60" -e PROACTIVE_CACHE_MINIMUM_FETCHING_TIME="5" -e PROACTIVE_CACHE_WORKERS="3" --name akeyless-gw akeyless/base:latest-akeyless ``` ```shell -docker run -d -p 8000:8000 -p 8200:8200 -p 5696:5696 -e GATEWAY_ACCESS_ID="your-access-id" -e GATEWAY_ACCESS_KEY="matching-access-key" -e CACHE_ENABLE="true" -e PROACTIVE_CACHE_ENABLE="true" -e CACHE_TTL="number-of-minutes" -e PROACTIVE_CACHE_MINIMUM_FETCHING_TIME="number-of-minutes" -e PROACTIVE_CACHE_DUMP_INTERVAL="number-of-minutes" --name akeyless-gw akeyless/base +docker run -d -p 8000:8000 -p 8200:8200 -p 5696:5696 -e GATEWAY_ACCESS_ID="your-access-id" -e GATEWAY_ACCESS_KEY="matching-access-key" -e CACHE_ENABLE="true" -e PROACTIVE_CACHE_ENABLE="true" -e NEW_PROACTIVE_CACHE_ENABLE="true" -e CACHE_TTL="number-of-minutes" -e PROACTIVE_CACHE_MINIMUM_FETCHING_TIME="number-of-minutes" -e PROACTIVE_CACHE_WORKERS="number-of-workers" --name akeyless-gw akeyless/base ``` -In the example above, - -* `CACHE_TTL` variable allows setting the time (in minutes) during which a secret should be kept in the cache. - -* `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME` variable instructs the system to update secrets in the cache if they are older than the specified value. - -* `PROACTIVE_CACHE_DUMP_INTERVAL` variable allows setting the time (in minutes) between the two consecutive backups. +`PROACTIVE_CACHE_DUMP_INTERVAL` is still supported as the legacy secure backup interval for periodic cache backup, but the recommended proactive cache implementation is selected with `NEW_PROACTIVE_CACHE_ENABLE=true` and typically tuned with `PROACTIVE_CACHE_WORKERS` and `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME` instead. -It is also possible to [configure caching](https://docs.akeyless.io/docs/configure-the-gateway-cache) in the Gateway Configuration Manager after the Gateway is deployed. +It is also possible to configure runtime and proactive caching in the Gateway Console after the Gateway is deployed. ## Access Scope and Defaults diff --git a/docs/Akeyless Gateway/gateway-best-practices.md b/docs/Akeyless Gateway/gateway-best-practices.md index d16059c8..95457528 100644 --- a/docs/Akeyless Gateway/gateway-best-practices.md +++ b/docs/Akeyless Gateway/gateway-best-practices.md @@ -258,6 +258,17 @@ Use the tables as directional capacity-planning input, not as guaranteed perform | 1M | 1.0 | 1.0 | 1.5Gi | 1Gi | | 2M | 1.0 | 1.0 | 2.5Gi | 2Gi | +### Memory and CPU limit behavior + +Use the following operational model when setting limits: + +* Memory limits are enforced as hard limits. If container working-set memory exceeds the configured limit, Kubernetes can terminate the pod with `OOMKilled`. For behavior details, see [Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/). +* CPU limits do not terminate pods. When CPU usage exceeds the configured limit, Kubernetes throttles CPU allocation, which can increase request latency. For behavior details, see [Resource Management for Pods and Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/). +* For proactive cache environments, use an operational loop: + 1. Capture baseline memory and CPU during steady state and immediately after proactive warm-up. + 2. Alert on sustained memory growth, repeated CPU throttling, and pod restarts. + 3. If warm-up pressure is sustained, first reduce `PROACTIVE_CACHE_WORKERS` and increase `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME`, then scale replicas or increase resource limits as needed. + ### Operational recommendations * Run at least 2 Gateway pods for availability. For most production environments with proactive cache, 3-4 pods is a practical baseline. diff --git a/docs/Akeyless Gateway/gateway-legacy/gateway-kubernetes-legacy-deployment.md b/docs/Akeyless Gateway/gateway-legacy/gateway-kubernetes-legacy-deployment.md index c38eadc4..47447fb4 100644 --- a/docs/Akeyless Gateway/gateway-legacy/gateway-kubernetes-legacy-deployment.md +++ b/docs/Akeyless Gateway/gateway-legacy/gateway-kubernetes-legacy-deployment.md @@ -341,7 +341,7 @@ Full list of available permissions: | `rotate_secret_value` | Grants permission **only** to rotate the secret value, without allowing manual edits. Requires `read` permission on the item | | `log_forwarding` | Management of [Log Forwarding](https://docs.akeyless.io/docs/log-forwarding) settings | | `zero_knowledge_encryption` | Management of [Zero-Knowledge](https://docs.akeyless.io/docs/zero-knowledge) | -| `caching` | Management of [Gateway Cache](https://docs.akeyless.io/docs/configure-the-gateway-cache) settings | +| `caching` | Management of [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching) settings | | `event_forwarding` | Management of [Event](https://docs.akeyless.io/docs/event-center) Forwarding settings | | `ldap_auth` | Management of [LDAP](https://docs.akeyless.io/docs/auth-with-ldap) Auth Gateway configuration. | | `k8s_auth` | Management of [Kubernetes](https://docs.akeyless.io/docs/auth-with-kubernetes) Auth Gateway configuration | diff --git a/docs/Akeyless Gateway/operate-gateway/gateway-troubleshooting-the-gateway.md b/docs/Akeyless Gateway/operate-gateway/gateway-troubleshooting-the-gateway.md index 16fdde88..e9582c4b 100644 --- a/docs/Akeyless Gateway/operate-gateway/gateway-troubleshooting-the-gateway.md +++ b/docs/Akeyless Gateway/operate-gateway/gateway-troubleshooting-the-gateway.md @@ -66,15 +66,15 @@ References: ## 4. Cache and Offline Behavior -If stale values are returned, or behavior differs during SaaS interruptions, validate cache configuration and expected offline behavior. +If stale values are returned, or behavior differs during SaaS interruptions, validate that your selected caching mode and runtime options match your requirements. Check: -* Cache mode is configured as intended (local or cluster cache). -* Refresh and cleanup intervals align with operational requirements. -* Workload behavior with `ignore-cache` matches expected disconnected-mode behavior. +* The selected caching method is configured as intended (runtime, proactive, standalone cluster cache, or HA cluster cache). +* Refresh and synchronization settings align with operational requirements. +* Workload behavior with `ignore-cache` is validated against your outage expectations. -Reference: +References: * [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching)