Advanсed Configuration

Standalone Gateway

The structure of the Gateway installation command when using environment variables should be the following:

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ENV_VARIABLE_1="value1" -e ENV_VARIABLE_2="value2" -v /HOST/PATH/TO/FILE:/GATEWAY/PATH/TO/FILE --name akeyless-gw akeyless/base

👍

Tip

To update an existing Gateway, use the same Admin Access ID and Cluster Name for the new Gateway in order to retrieve the latest settings and data from the previously removed docker instance.

Authentication

To set your Gateway with a default Authentication Methods to control the level of access your Gateway instance will have inside your Akeyless account.

The following Authentication Methods are supported for Docker deployments:

👍

Tip:

Your Gateway Authentication Method should have permission to create and manged both Secret & Keys along with Targets items only.

While working with Cloud Service Providers Authentication Methods you can provide a list of allowed users that will be able to log in and manage your Gateway configuration.

Email Authentication

To set your Gateway default authentication based on your email\password which you used to create your Akeyless account:

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="email" -e ADMIN_PASSWORD="password" --name akeyless-gw akeyless/base

🚧

Note:

Using your default account credentials is not recommended for production environments.

API Key Authentication

To set your Gateway default authentication based on API Key provide the relevant Access ID and Access Key using those variables:

ADMIN_ACCESS_ID="your-access-id" , ADMIN_ACCESS_KEY="matching-access-key".

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxx" -e ADMIN_ACCESS_KEY="62Hu...xxx....qlg=" --name akeyless-gw akeyless/base

CSP IAM Authentication

While running your Gateway instance inside your cloud environment, you can use AWS IAM, GCP GCE, or Azure Active Directory, using machine-to-machine authentication between Akeyless and your Cloud Service Provider with a list of allowed users that will be able to manage your Gateway configuration.

Set the ADMIN_ACCESS_ID="access-id" variable with your IAM Authentication Methods Access ID, where you need to set a list of users that will be able to manage your Gateway configuration using ALLOWED_ACCESS_IDS variable with any other Authentication Method like SAML or OIDC or an API Key.

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxx" -e ALLOWED_ACCESS_IDS="p-yyyyyy" --name akeyless-gw akeyless/base

Gateway Admins

To support local management of your Gateway configuration, you can set a list of allowed Access ID that will be able to log in and manage your Gateway. This setting can also work with sub-claims (when a shared authentication method is used), for example:

ALLOWED_ACCESS_IDS= "p-yyyyyy [email protected],p-yyyyyy [email protected],p-yyyyyy group=Devops"

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxx" -e ALLOWED_ACCESS_IDS="p-yyyyyy [email protected],p-yyyyyy [email protected], p-yyyyy group=Devops"  --name akeyless-gw akeyless/base
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-csp-access-id" -e ALLOWED_ACCESS_IDS="access-id1,access-id2 subclaim1=subclaimValue1,access-id3 subclaim1=subclaimValue2"  --name akeyless-gw akeyless/base

In this case,p-yyyyyy is your SAML or OIDC Access ID, where a user that matches at least one sub-claim attribute will be authorized to access the Gateway.

In our example, [email protected] and [email protected] will be authorized, and any member of group=Devops will also be authorized.

In addition, you can simply set an API Key Access ID :

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="aws-iam-access-id" -e ALLOWED_ACCESS_IDS="api-key-access-id"  --name akeyless-gw akeyless/base

🚧

Important

When using ALLOWED_ACCESS_IDS to set up access to your Gateway using a shared authentication method, make sure to provide the relevant Sub-Claim defining the exact users that will be able to log in and manage your Gateway.

Otherwise, all users authenticated by your Identity Provider (IDP) can log in to your Gateway with admin privileges and make changes to its configuration.

Cluster Name

Each Gateway instance is uniquely identified by combining the Admin Access ID Authentication Method and the Cluster Name.

It means that changing the Admin Access ID or the Cluster Name of your Gateway instance will create an entirely new Gateway instance, and it will not retrieve the settings and data from the previous Gateway instance.

That’s why we recommend setting up a meaningful Cluster Name for your Gateway instance from the very beginning. By default, your cluster name is defaultCluster.

To do that, you can set the CLUSTER_NAME="meaningful-cluster-name" variable as part of the Gateway Installation command.

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-access-id" -e ADMIN_ACCESS_KEY="matching-access-key" -e CLUSTER_NAME="meaningful-cluster-name" -e INITIAL_DISPLAY_NAME="display-name" --name akeyless-gw akeyless/base

You can also provide a custom display name for the Gateway Instance using the INITIAL_DISPLAY_NAME variable, but this is arbitrary. This name can be changed in the Akeyless Console after the Gateway is installed.

Encryption Key

To choose an Encryption Key to encrypt your Gateway configuration, you can choose an existing key using the following variable CONFIG_PROTECTION_KEY_NAME

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxxxxxxx" -e ADMIN_ACCESS_KEY="62Hu...xxx....qlg=" -e CONFIG_PROTECTION_KEY_NAME="My-Encryption-Key" --name akeyless-gw akeyless/base

By default, the Gateway configuration is encrypted with your account's default encryption key.

Customer Fragment

If your Encryption Key works with Zero Knowledge, provide the path to a local JSON containing your Customer Fragment:

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -v {path-to}/customer_fragments.json:/root/.akeyless/customer_fragments.json -v ~/api-gw-logs:/var/log/akeyless -e CLUSTER_NAME="test-cluster" -e ADMIN_ACCESS_ID="p-xxxxxxx" -e ADMIN_ACCESS_KEY="<YourAccessKey" -e CONFIG_PROTECTION_KEY_NAME="My-Encryption-Key" --name api-gw-test akeyless/base

Version Selection

To work with a specific Gateway version use the VERSION variable to install a specific version of the Akeyless Gateway.

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-access-id" -e ADMIN_ACCESS_KEY="matching-access-key" -e VERSION="gw-app-version" --name akeyless-gw akeyless/base

TLS Configuration

We strongly recommend using Akeyless Gateway with TLS to ensure all traffic is encrypted at transit.
Please note that when you're enabling TLS, you must provide a TLS certificate and a TLS Private Key in PEM format.

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-access-id" -e ADMIN_ACCESS_KEY="matching-access-key" -e ENABLE_TLS="true" -e ENABLE_TLS_CONFIGURE="true" -e ENABLE_TLS_CURL="true" -e ENABLE_TLS_HVP="true" -v $PWD/cert.crt:/var/akeyless/conf/api-proxy/akeyless-api-cert.crt -v $PWD/key.pem:/var/akeyless/conf/api-proxy/akeyless-api-cert.key --name akeyless-gw akeyless/base

In the example above,

  • The ENABLE_TLS variable enables TLS for the Gateway Console.

  • The ENABLE_TLS_CONFIGURE variable enables TLS for the Gateway Configuration Manager.

  • The ENABLE_TLS_HVP variable enables TLS for the HVP service.

  • The ENABLE_TLS_CURL variable enables TLS for the Akeyless API Services.

With the following attributes, you can mount the TLS certificate and the TLS Private Key from the Present Working Directory to the Gateway target directory:

  • -v $PWD/cert.crt:/root/.akeyless/akeyless-api-cert.crt

  • -v $PWD/key.pem:/root/akeyless-api-cert.key

It is also possible to set up TLS in the Gateway Configuration Manager after the Gateway is installed.

Cache Configuration

You can enable caching of secrets and periodic backup of cached secrets

docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="p-xxxxxxxxxxxx" -e ADMIN_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
docker run -d -p 8000:8000 -p 8200:8200 -p 18888:18888 -p 8080:8080 -p 8081:8081 -p 5696:5696 -e ADMIN_ACCESS_ID="your-access-id" -e ADMIN_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

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.

It is also possible to configure caching in the Gateway Configuration Manager after the Gateway is installed.


Did this page help you?