From 19b395f8775a81939e2d18dbd80507f090dbd3c2 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 13:37:02 -0600 Subject: [PATCH 01/10] docs(docker): clarify GATEWAY_AUTHORIZED_ACCESS_ID deprecation, add cache var table, add SRA Docker Compose guidance (DOCS-424) --- .../gateway-docker-advanced-configuration.md | 33 +++++++++++++++++++ 1 file changed, 33 insertions(+) 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 b9ece1fbe..5fa30ef8e 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 @@ -147,9 +147,16 @@ Run the following: docker run -d -p 8000:8000 -p 5696:5696 -e GATEWAY_ACCESS_ID="p-xxxxxxx" -e ALLOWED_ACCESS_PERMISSIONS='[ {"name": "Administrators", "access_id": "p-yyyyyy", "sub_claims": {"email": ["test01@testhost.com", "test02@testhost.com"], "group": ["Devops"]}, "permissions": ["admin"]}]' --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-csp-access-id" -e ALLOWED_ACCESS_PERMISSIONS='[ {"name": "access1", "access_id": "p-xxxxxxx", "sub_claims": {"username": ["username1", "username2"], "group": ["IT"]}, "permissions": ["admin"]},\n {"name": "access2", "access_id": "p-yyyyyy", "sub_claims": {"username": ["username1"], "group": ["rnd"]}, "permissions": ["targets", "defaults"]}, {"name": "access3", "access_id": "p-zzzzzzz", "sub_claims": {"email": ["xxx@example.com", "zzz@example.com"]}, "permissions": ["admin"]}]' --name akeyless-gw akeyless/base:latest-akeyless +``` +```shell Legacy docker run -d -p 8000:8000 -p 8200:8200 -p 5696:5696 -e GATEWAY_ACCESS_ID="your-csp-access-id" -e GATEWAY_AUTHORIZED_ACCESS_ID='[ {"name": "access1", "access_id": "p-xxxxxxx", "sub_claims": {"username": ["username1", "username2"], "group": ["IT"]}, "permissions": ["admin"]},\n {"name": "access2", "access_id": "p-yyyyyy", "sub_claims": {"username": ["username1"], "group": ["rnd"]}, "permissions": ["targets", "defaults"]}, {"name": "access3", "access_id": "p-zzzzzzz", "sub_claims": {"email": ["xxx@example.com", "zzz@example.com"]}, "permissions": ["admin"]}]' --name akeyless-gw akeyless/base:latest-akeyless ``` +> ℹ️ **Note (`GATEWAY_AUTHORIZED_ACCESS_ID`):** +> +> `GATEWAY_AUTHORIZED_ACCESS_ID` is the legacy name for `ALLOWED_ACCESS_PERMISSIONS`. Both variables are accepted, but `ALLOWED_ACCESS_PERMISSIONS` is the current standard. New deployments should use `ALLOWED_ACCESS_PERMISSIONS`. The Legacy tab above shows the deprecated form for reference only. + In this case, the above creates an **Access Permission** object named **Administrators**, associated with an Auth Method `p-yyyyyy`, which is, for example, your [SAML](https://docs.akeyless.io/docs/auth-with-saml) or [OIDC](https://docs.akeyless.io/docs/auth-with-oidc) `Access ID`. A user that matches at least one [Sub-Claims](https://docs.akeyless.io/docs/sub-claims) attribute is authorized to access the Gateway with **Admin** permissions: In our example, `test01@testhost.com` and `test02@testhost.com` are authorized, and any member of `group=Devops` is also authorized. @@ -359,6 +366,16 @@ Use these environment variables to enable runtime and proactive cache features f For behavior, topology semantics, and recommended proactive cache settings, see [Gateway Caching](https://docs.akeyless.io/docs/gateway-caching). +| Variable | Type | Description | +| --- | --- | --- | +| `CACHE_ENABLE` | `true`/`false` | Enables the runtime cache. When `true`, the Gateway caches secret values locally to reduce SaaS round-trips. | +| `CACHE_TTL` | Integer (minutes) | How long cached values are retained before expiry. | +| `PROACTIVE_CACHE_ENABLE` | `true`/`false` | Enables the legacy proactive cache mode (periodic background fetch). Set `NEW_PROACTIVE_CACHE_ENABLE` instead for new deployments. | +| `NEW_PROACTIVE_CACHE_ENABLE` | `true`/`false` | Enables the current proactive cache implementation. Recommended over `PROACTIVE_CACHE_ENABLE`. | +| `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME` | Integer (minutes) | Minimum interval between background refresh attempts per secret. | +| `PROACTIVE_CACHE_WORKERS` | Integer | Number of parallel workers used to refresh the proactive cache. | +| `PROACTIVE_CACHE_DUMP_INTERVAL` | Integer (minutes) | Legacy: interval for periodic secure cache backup. Retained for backwards compatibility; prefer the `NEW_PROACTIVE_CACHE_ENABLE` model. | + ```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 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 ``` @@ -472,3 +489,19 @@ To enable **gRPC** on your Gateway set the following environment variable `ENABL ```shell docker run -d -p 8000:8000 -p 8085:8085 -p 5696:5696 -e ENABLE_GRPC=true --name akeyless-gw akeyless/base:latest-akeyless ``` + +## Secure Remote Access (SRA) with Docker Compose + +When deploying SRA alongside the Gateway using Docker Compose, note the following requirements and limitations. + +> ❗ **Important:** +> +> The Docker-based SRA deployment supports a subset of the configuration options available in Kubernetes. Review these constraints before deploying SRA in a Docker Compose environment. + +* **SRA container image**: SRA requires a separate container image. Refer to the [Secure Remote Access setup guide](https://docs.akeyless.io/docs/remote-access-setup-k8s) for the image and required environment variables. +* **Networking**: The SRA container and the Gateway container must share a Docker network so that SRA can reach the Gateway on port `8000`. Define a named network in your `docker-compose.yaml` and attach both containers to it. +* **Port exposure**: The SRA SSH service listens on port `2222` by default. Expose this port to allow inbound SRA connections from user workstations. +* **Volume mounts**: If you configure SRA with TLS certificates or SSH host keys, mount those files consistently across container restarts using a named volume or bind mount. +* **Environment variables**: The SRA container requires at minimum `GATEWAY_URL` (pointing to the Gateway container) and the same `GATEWAY_ACCESS_ID` used by the Gateway. Refer to your SRA release notes for the full variable reference. + +For a reference Docker Compose file that includes both the Gateway and SRA containers, see the [Akeyless Helm Charts repository](https://github.com/akeylesslabs/helm-charts/tree/main/docker-compose). From a1719f4fa3813bd1f60cf24615377efa4b1237c2 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 13:52:15 -0600 Subject: [PATCH 02/10] fix(docker): remove inaccurate GATEWAY_AUTHORIZED_ACCESS_ID legacy claim --- .../gateway-docker-advanced-configuration.md | 7 ------- 1 file changed, 7 deletions(-) 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 5fa30ef8e..6a1dc10d3 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 @@ -149,13 +149,6 @@ docker run -d -p 8000:8000 -p 5696:5696 -e GATEWAY_ACCESS_ID="p-xxxxxxx" -e ALLO ```shell docker run -d -p 8000:8000 -p 8200:8200 -p 5696:5696 -e GATEWAY_ACCESS_ID="your-csp-access-id" -e ALLOWED_ACCESS_PERMISSIONS='[ {"name": "access1", "access_id": "p-xxxxxxx", "sub_claims": {"username": ["username1", "username2"], "group": ["IT"]}, "permissions": ["admin"]},\n {"name": "access2", "access_id": "p-yyyyyy", "sub_claims": {"username": ["username1"], "group": ["rnd"]}, "permissions": ["targets", "defaults"]}, {"name": "access3", "access_id": "p-zzzzzzz", "sub_claims": {"email": ["xxx@example.com", "zzz@example.com"]}, "permissions": ["admin"]}]' --name akeyless-gw akeyless/base:latest-akeyless ``` -```shell Legacy -docker run -d -p 8000:8000 -p 8200:8200 -p 5696:5696 -e GATEWAY_ACCESS_ID="your-csp-access-id" -e GATEWAY_AUTHORIZED_ACCESS_ID='[ {"name": "access1", "access_id": "p-xxxxxxx", "sub_claims": {"username": ["username1", "username2"], "group": ["IT"]}, "permissions": ["admin"]},\n {"name": "access2", "access_id": "p-yyyyyy", "sub_claims": {"username": ["username1"], "group": ["rnd"]}, "permissions": ["targets", "defaults"]}, {"name": "access3", "access_id": "p-zzzzzzz", "sub_claims": {"email": ["xxx@example.com", "zzz@example.com"]}, "permissions": ["admin"]}]' --name akeyless-gw akeyless/base:latest-akeyless -``` - -> ℹ️ **Note (`GATEWAY_AUTHORIZED_ACCESS_ID`):** -> -> `GATEWAY_AUTHORIZED_ACCESS_ID` is the legacy name for `ALLOWED_ACCESS_PERMISSIONS`. Both variables are accepted, but `ALLOWED_ACCESS_PERMISSIONS` is the current standard. New deployments should use `ALLOWED_ACCESS_PERMISSIONS`. The Legacy tab above shows the deprecated form for reference only. In this case, the above creates an **Access Permission** object named **Administrators**, associated with an Auth Method `p-yyyyyy`, which is, for example, your [SAML](https://docs.akeyless.io/docs/auth-with-saml) or [OIDC](https://docs.akeyless.io/docs/auth-with-oidc) `Access ID`. A user that matches at least one [Sub-Claims](https://docs.akeyless.io/docs/sub-claims) attribute is authorized to access the Gateway with **Admin** permissions: From 7c3f22d9fd5131177001d68f122aadb7b4c0ac16 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 14:50:44 -0600 Subject: [PATCH 03/10] DOCS-424: fix SRA links/env-vars, add cluster cache vars, add deprecated alias note --- .../gateway-docker-advanced-configuration.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) 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 6a1dc10d3..10418c146 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 @@ -132,6 +132,10 @@ docker run -d -p 8000:8000 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxx" -v $PWD/ To support local management of your Gateway configuration, you can set a list of `Access ID` values that can log in and manage your Gateway. This setting can also work with [Sub-Claims](https://docs.akeyless.io/docs/sub-claims) (when a shared authentication method is used), where for each entry you need to define a unique `name` which should describe the **Access Permission** object, with an `access-id`, `sub_claims` when applicable, and a list of `permissions`. +> ℹ️ **Note:** +> +> Older documentation and example configurations may reference `GATEWAY_AUTHORIZED_ACCESS_ID` for this setting. That name is deprecated. Use `ALLOWED_ACCESS_PERMISSIONS` for all current deployments. + For example: ```shell @@ -368,6 +372,9 @@ For behavior, topology semantics, and recommended proactive cache settings, see | `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME` | Integer (minutes) | Minimum interval between background refresh attempts per secret. | | `PROACTIVE_CACHE_WORKERS` | Integer | Number of parallel workers used to refresh the proactive cache. | | `PROACTIVE_CACHE_DUMP_INTERVAL` | Integer (minutes) | Legacy: interval for periodic secure cache backup. Retained for backwards compatibility; prefer the `NEW_PROACTIVE_CACHE_ENABLE` model. | +| `USE_CLUSTER_CACHE` | `true`/`false` | Enables the Redis-backed cluster cache. Required alongside `GATEWAY_CLUSTER_CACHE`. | +| `GATEWAY_CLUSTER_CACHE` | `"enable"` | Activates cluster cache mode. Set to `"enable"` when using a Redis-backed cluster cache. If left set after removing the Redis instance, the Gateway may fail to start until the container is recreated. | +| `REDIS_ADDR` | `host:port` | Address of the Redis instance used for the cluster cache, for example `akeyless-cache:6379`. | ```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 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 @@ -491,10 +498,10 @@ When deploying SRA alongside the Gateway using Docker Compose, note the followin > > The Docker-based SRA deployment supports a subset of the configuration options available in Kubernetes. Review these constraints before deploying SRA in a Docker Compose environment. -* **SRA container image**: SRA requires a separate container image. Refer to the [Secure Remote Access setup guide](https://docs.akeyless.io/docs/remote-access-setup-k8s) for the image and required environment variables. +* **SRA container image**: SRA requires separate container images for the web and SSH proxy components. Refer to the [Remote Access on Docker Compose guide](https://docs.akeyless.io/docs/sra-docker) for image references and required environment variables. * **Networking**: The SRA container and the Gateway container must share a Docker network so that SRA can reach the Gateway on port `8000`. Define a named network in your `docker-compose.yaml` and attach both containers to it. * **Port exposure**: The SRA SSH service listens on port `2222` by default. Expose this port to allow inbound SRA connections from user workstations. * **Volume mounts**: If you configure SRA with TLS certificates or SSH host keys, mount those files consistently across container restarts using a named volume or bind mount. -* **Environment variables**: The SRA container requires at minimum `GATEWAY_URL` (pointing to the Gateway container) and the same `GATEWAY_ACCESS_ID` used by the Gateway. Refer to your SRA release notes for the full variable reference. +* **Environment variables**: The SRA `sra.env` file requires at minimum `GATEWAY_URL` (the Gateway API endpoint, for example `http://akeyless-gateway:8000`) and `INTERNAL_GATEWAY_API` (the Gateway internal/health endpoint, for example `http://akeyless-gateway:8080`). For the full variable reference, see [Docker Compose Advanced Configuration](https://docs.akeyless.io/docs/sra-advanced-configuration-docker). -For a reference Docker Compose file that includes both the Gateway and SRA containers, see the [Akeyless Helm Charts repository](https://github.com/akeylesslabs/helm-charts/tree/main/docker-compose). +For a reference Docker Compose file that includes both the Gateway and SRA containers, see the [Akeyless Docker Compose repository](https://github.com/akeylesslabs/docker-compose). From 15024b00920ad84a57d75b6169ebc59c440a01ae Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 14:54:29 -0600 Subject: [PATCH 04/10] DOCS-424: move cache vars to caching pages, move SRA guidance to SRA docs --- .../cluster-cache-standalone.md | 9 +++++ .../gateway-caching/proactive-caching.md | 1 + .../gateway-docker-advanced-configuration.md | 37 ++----------------- .../sra-setup/sra-docker/index.md | 4 ++ 4 files changed, 17 insertions(+), 34 deletions(-) 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 index a8eeeeeb3..1c942f134 100644 --- a/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md @@ -117,3 +117,12 @@ For the full key reference, see [Helm Values Reference](https://docs.akeyless.io * `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/). + +### Cluster Cache Environment Variables (Docker Compose) + +When deploying with [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose), configure standalone cluster cache using environment variables in `gateway.env` rather than Helm values: + +* `USE_CLUSTER_CACHE`: Set to `true` to enable the Redis-backed cluster cache. Required alongside `GATEWAY_CLUSTER_CACHE`. +* `GATEWAY_CLUSTER_CACHE`: Set to `"enable"` to activate cluster cache mode. If this 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](https://docs.akeyless.io/docs/cluster-cache-standalone#local-cache-and-cluster-cache-read-preference). diff --git a/docs/Akeyless Gateway/configure-gateway/gateway-caching/proactive-caching.md b/docs/Akeyless Gateway/configure-gateway/gateway-caching/proactive-caching.md index 2055210cf..46b7cd1d9 100644 --- a/docs/Akeyless Gateway/configure-gateway/gateway-caching/proactive-caching.md +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/proactive-caching.md @@ -107,6 +107,7 @@ For the full key reference, see [Helm Values Reference](https://docs.akeyless.io * `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`. +* `PROACTIVE_CACHE_DUMP_INTERVAL`: Sets the periodic secure cache backup interval in minutes for the legacy implementation. This variable has no effect when `NEW_PROACTIVE_CACHE_ENABLE=true`. For most tuning decisions on the legacy implementation, prefer `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME`; adjust `PROACTIVE_CACHE_DUMP_INTERVAL` only when you need to change backup cadence specifically. 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). 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 10418c146..6cfbcbc4a 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 @@ -359,22 +359,9 @@ The variables `MIN_TLS_VERSION=TLSv1.3` and `GODEBUG=tlsmlkem=1` enable hybrid P ### Cache Configuration -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/gateway-caching). - -| Variable | Type | Description | -| --- | --- | --- | -| `CACHE_ENABLE` | `true`/`false` | Enables the runtime cache. When `true`, the Gateway caches secret values locally to reduce SaaS round-trips. | -| `CACHE_TTL` | Integer (minutes) | How long cached values are retained before expiry. | -| `PROACTIVE_CACHE_ENABLE` | `true`/`false` | Enables the legacy proactive cache mode (periodic background fetch). Set `NEW_PROACTIVE_CACHE_ENABLE` instead for new deployments. | -| `NEW_PROACTIVE_CACHE_ENABLE` | `true`/`false` | Enables the current proactive cache implementation. Recommended over `PROACTIVE_CACHE_ENABLE`. | -| `PROACTIVE_CACHE_MINIMUM_FETCHING_TIME` | Integer (minutes) | Minimum interval between background refresh attempts per secret. | -| `PROACTIVE_CACHE_WORKERS` | Integer | Number of parallel workers used to refresh the proactive cache. | -| `PROACTIVE_CACHE_DUMP_INTERVAL` | Integer (minutes) | Legacy: interval for periodic secure cache backup. Retained for backwards compatibility; prefer the `NEW_PROACTIVE_CACHE_ENABLE` model. | -| `USE_CLUSTER_CACHE` | `true`/`false` | Enables the Redis-backed cluster cache. Required alongside `GATEWAY_CLUSTER_CACHE`. | -| `GATEWAY_CLUSTER_CACHE` | `"enable"` | Activates cluster cache mode. Set to `"enable"` when using a Redis-backed cluster cache. If left set after removing the Redis instance, the Gateway may fail to start until the container is recreated. | -| `REDIS_ADDR` | `host:port` | Address of the Redis instance used for the cluster cache, for example `akeyless-cache:6379`. | +Use the following environment variables to enable runtime and proactive cache features for Docker deployments. + +For the full variable reference and behavior details, see [Runtime Caching](https://docs.akeyless.io/docs/runtime-caching), [Proactive Caching](https://docs.akeyless.io/docs/proactive-caching), and [Cluster Cache (Standalone)](https://docs.akeyless.io/docs/cluster-cache-standalone). ```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 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 @@ -383,8 +370,6 @@ docker run -d -p 8000:8000 -p 5696:5696 -e GATEWAY_ACCESS_ID="p-xxxxxxxxxxxx" -e 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 ``` -`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 runtime and proactive caching in the Gateway Console after the Gateway is deployed. ## Access Scope and Defaults @@ -489,19 +474,3 @@ To enable **gRPC** on your Gateway set the following environment variable `ENABL ```shell docker run -d -p 8000:8000 -p 8085:8085 -p 5696:5696 -e ENABLE_GRPC=true --name akeyless-gw akeyless/base:latest-akeyless ``` - -## Secure Remote Access (SRA) with Docker Compose - -When deploying SRA alongside the Gateway using Docker Compose, note the following requirements and limitations. - -> ❗ **Important:** -> -> The Docker-based SRA deployment supports a subset of the configuration options available in Kubernetes. Review these constraints before deploying SRA in a Docker Compose environment. - -* **SRA container image**: SRA requires separate container images for the web and SSH proxy components. Refer to the [Remote Access on Docker Compose guide](https://docs.akeyless.io/docs/sra-docker) for image references and required environment variables. -* **Networking**: The SRA container and the Gateway container must share a Docker network so that SRA can reach the Gateway on port `8000`. Define a named network in your `docker-compose.yaml` and attach both containers to it. -* **Port exposure**: The SRA SSH service listens on port `2222` by default. Expose this port to allow inbound SRA connections from user workstations. -* **Volume mounts**: If you configure SRA with TLS certificates or SSH host keys, mount those files consistently across container restarts using a named volume or bind mount. -* **Environment variables**: The SRA `sra.env` file requires at minimum `GATEWAY_URL` (the Gateway API endpoint, for example `http://akeyless-gateway:8000`) and `INTERNAL_GATEWAY_API` (the Gateway internal/health endpoint, for example `http://akeyless-gateway:8080`). For the full variable reference, see [Docker Compose Advanced Configuration](https://docs.akeyless.io/docs/sra-advanced-configuration-docker). - -For a reference Docker Compose file that includes both the Gateway and SRA containers, see the [Akeyless Docker Compose repository](https://github.com/akeylesslabs/docker-compose). diff --git a/docs/Secure Remote Access/sra-setup/sra-docker/index.md b/docs/Secure Remote Access/sra-setup/sra-docker/index.md index 10e7aafc8..c00a50d7b 100644 --- a/docs/Secure Remote Access/sra-setup/sra-docker/index.md +++ b/docs/Secure Remote Access/sra-setup/sra-docker/index.md @@ -12,6 +12,10 @@ next: --- In this guide, we will deploy the SRA utility using Docker Compose and the most basic configuration. +> ℹ️ **Note:** +> +> The Docker Compose SRA deployment supports a subset of the configuration options available in Kubernetes. For production workloads or advanced configuration requirements, see [Remote Access on Kubernetes](https://docs.akeyless.io/docs/sra-setup-k8s). + You can get the [configuration files](https://github.com/akeylesslabs/docker-compose/blob/main/README.md) that will be used to deploy the gateway with the SRA by cloning the following repository to your environment: ```shell From a55b04db13f47d0d3b8362b4dbd276de9bc0fa23 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 14:58:38 -0600 Subject: [PATCH 05/10] DOCS-424: fix GATEWAY_AUTHORIZED_ACCESS_ID deprecation note, document as separate restriction var --- .../gateway-docker-advanced-configuration.md | 22 ++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) 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 6cfbcbc4a..e6ef7ad6e 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 @@ -134,7 +134,7 @@ To support local management of your Gateway configuration, you can set a list of > ℹ️ **Note:** > -> Older documentation and example configurations may reference `GATEWAY_AUTHORIZED_ACCESS_ID` for this setting. That name is deprecated. Use `ALLOWED_ACCESS_PERMISSIONS` for all current deployments. +> Older deployments may use `ALLOWED_ACCESS_IDS`, which accepts a comma-separated list of access IDs but does not support per-entry permissions or sub-claims. `ALLOWED_ACCESS_PERMISSIONS` is the current variable and supersedes `ALLOWED_ACCESS_IDS`. For example: @@ -199,6 +199,26 @@ Full list of available permissions: You may also edit this parameter on your console, by going to the Gateways tab and selecting the desired Gateway. On the right of the screen, you will see the Gateway details, including **Access Permissions**. +### Restrict Gateway Callers by Access ID + +Use `GATEWAY_AUTHORIZED_ACCESS_ID` to restrict which access IDs can call the Gateway API at all. This is a transport-layer allowlist enforced before any permission check: if the variable is set, the Gateway rejects requests from any access ID not on the list (the Gateway's own `GATEWAY_ACCESS_ID` is always implicitly allowed). + +Set the value to a comma-separated list of access IDs: + +```shell +docker run -d -p 8000:8000 -p 5696:5696 \ + -e GATEWAY_ACCESS_ID="p-xxxxxxx" \ + -e GATEWAY_ACCESS_KEY="matching-access-key" \ + -e GATEWAY_AUTHORIZED_ACCESS_ID="p-aaaaaa,p-bbbbbb" \ + --name akeyless-gw akeyless/base:latest-akeyless +``` + +> ℹ️ **Note:** +> +> `GATEWAY_AUTHORIZED_ACCESS_ID` replaces the legacy `RESTRICT_SERVICE_TO_ACCESS_IDS`. Both names are accepted, but `GATEWAY_AUTHORIZED_ACCESS_ID` is preferred for current deployments. + +`GATEWAY_AUTHORIZED_ACCESS_ID` and `ALLOWED_ACCESS_PERMISSIONS` serve different purposes and can be used together. `GATEWAY_AUTHORIZED_ACCESS_ID` controls **who can reach the Gateway**, while `ALLOWED_ACCESS_PERMISSIONS` controls **what those callers are permitted to do inside the Gateway**. + ## Cluster Identity and Encryption ### Cluster Name & URL From 9fdc6892b3ec7932a5d5aabcf36bcce35d904c2d Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 15:06:07 -0600 Subject: [PATCH 06/10] DOCS-424: fix USE_CLUSTER_CACHE/GATEWAY_CLUSTER_CACHE relationship, fix stale gateway.env comment --- .../gateway-caching/cluster-cache-standalone.md | 4 ++-- samples/unified-gateway/docker-compose-deploy/gateway.env | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) 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 index 1c942f134..727d6e878 100644 --- a/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md @@ -122,7 +122,7 @@ For the full key reference, see [Helm Values Reference](https://docs.akeyless.io When deploying with [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose), configure standalone cluster cache using environment variables in `gateway.env` rather than Helm values: -* `USE_CLUSTER_CACHE`: Set to `true` to enable the Redis-backed cluster cache. Required alongside `GATEWAY_CLUSTER_CACHE`. -* `GATEWAY_CLUSTER_CACHE`: Set to `"enable"` to activate cluster cache mode. If this remains set after the Redis instance is removed, the Gateway may fail to start until the container is recreated. +* `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](https://docs.akeyless.io/docs/cluster-cache-standalone#local-cache-and-cluster-cache-read-preference). diff --git a/samples/unified-gateway/docker-compose-deploy/gateway.env b/samples/unified-gateway/docker-compose-deploy/gateway.env index 9b57e0492..6ac1b8320 100644 --- a/samples/unified-gateway/docker-compose-deploy/gateway.env +++ b/samples/unified-gateway/docker-compose-deploy/gateway.env @@ -1,7 +1,7 @@ # CLUSTER_NAME: The name of your Akeyless cluster (must match what's configured in Akeyless). # GATEWAY_ACCESS_ID / GATEWAY_ACCESS_KEY: Credentials obtained from the Akeyless console. # GATEWAY_ACCESS_TYPE: e.g., access_key/k8s/azure_ad/aws_iam/universal_identity/gcp/cert/ -# GATEWAY_AUTHORIZED_ACCESS_ID: Additional Access ID for delegated or extended usage. +# GATEWAY_AUTHORIZED_ACCESS_ID: Comma-separated allowlist of access IDs permitted to call the Gateway API. If set, all callers not on the list (except the gateway admin) are rejected at the transport layer before any permission check. # VERSION: Which Gateway Docker image version/tag to pull (e.g. "latest"). # ENABLE_METRICS: Set to "true" or "false" to enable metrics in the Gateway. # GATEWAY_CLUSTER_CACHE: Should remain "enable" From e1932e12863f341ceaac7cad82f042521643cb8a Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 15:12:33 -0600 Subject: [PATCH 07/10] DOCS-424: clarify Docker Compose cache vars vs standalone topology provisioning --- .../gateway-caching/cluster-cache-standalone.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 index 727d6e878..574724307 100644 --- a/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md @@ -85,7 +85,7 @@ Use the following deployment-specific options to configure standalone cluster ca | 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. | +| [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose) | Standalone cluster cache topology is not provisioned by Docker Compose. Docker Compose supports cache behavior tuning through Gateway environment variables (see [Cluster Cache Environment Variables (Docker Compose)](https://docs.akeyless.io/docs/cluster-cache-standalone#cluster-cache-environment-variables-docker-compose)). | | [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`): @@ -120,7 +120,7 @@ For the full key reference, see [Helm Values Reference](https://docs.akeyless.io ### Cluster Cache Environment Variables (Docker Compose) -When deploying with [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose), configure standalone cluster cache using environment variables in `gateway.env` rather than Helm values: +When deploying with [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose), use the following environment variables in `gateway.env` to control Redis-backed cache behavior. These variables do not provision 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. From 8e13e78eb8d9968d8bb2bb264e3f16618ffd91d0 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 15:13:31 -0600 Subject: [PATCH 08/10] DOCS-424: clarify Docker Compose cache behavior sentence --- .../gateway-caching/cluster-cache-standalone.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 574724307..849d19d8a 100644 --- a/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md @@ -120,7 +120,7 @@ For the full key reference, see [Helm Values Reference](https://docs.akeyless.io ### Cluster Cache Environment Variables (Docker Compose) -When deploying with [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose), use the following environment variables in `gateway.env` to control Redis-backed cache behavior. These variables do not provision standalone cluster cache topology resources. +When deploying with [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose), set these `gateway.env` variables to control how 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. From 032e2c38faa226156128c8c29341ca1217782f31 Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 15:14:47 -0600 Subject: [PATCH 09/10] DOCS-424: clarify language on Docker Compose gateway.env variables for Redis caching Co-authored-by: Copilot --- .../gateway-caching/cluster-cache-standalone.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 index 849d19d8a..b662098f6 100644 --- a/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md +++ b/docs/Akeyless Gateway/configure-gateway/gateway-caching/cluster-cache-standalone.md @@ -120,7 +120,7 @@ For the full key reference, see [Helm Values Reference](https://docs.akeyless.io ### Cluster Cache Environment Variables (Docker Compose) -When deploying with [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-docker-compose), set these `gateway.env` variables to control how 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. +When deploying with [Docker Compose](https://docs.akeyless.io/docs/gateway-deploy-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. From b1f5eab3ab7db1c4ffe0fb50694411c5eb20c96d Mon Sep 17 00:00:00 2001 From: Harrison Sherwin - Akeyless Date: Tue, 5 May 2026 15:18:32 -0600 Subject: [PATCH 10/10] DOCS-424: add explicit access-control variable warning comparison --- .../deploy-gateway/gateway-deploy-docker-compose.md | 2 ++ .../gateway-docker-advanced-configuration.md | 9 +++++++++ 2 files changed, 11 insertions(+) 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 b204a4f66..c0f90ae57 100644 --- a/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-docker-compose.md +++ b/docs/Akeyless Gateway/deploy-gateway/gateway-deploy-docker-compose.md @@ -116,6 +116,8 @@ ALLOWED_ACCESS_PERMISSIONS='[{"access_id":"","name":"