Docker Runtime
Retrieve secrets from Keeper Secrets Manager at Docker runtime


  • Dynamically retrieve secrets from the Keeper Vault when Docker containers execute
For a complete list of Keeper Secrets Manager features see the Overview


This page documents the Secrets Manager Docker Runtime integration. In order to utilize this integration, you will need:


Keeper Secrets Manager integrates with the Docker Runtime so that you can dynamically retrieve a secret from the vault when the container executes.
The ksm command is used to set environment variables when the container is started instead of hard-coding them into a deployment script. A real world example of this implementation is demonstrated below.

Example: Provision MySQL network user account

The official MySQL docker allows a user to set the MySQL root password and create a network accessible user via environment variables. The MySQL instance is then provisioned when a container is run.
The official MySQL dockerfile is below:
FROM debian:buster-slim
EXPOSE 3306 33060
CMD ["mysqld"]
In the standard implementation, the ENTRYPOINT does the provisioning of the container and will use environmental variables that are passed in to set up MYSQL. The environmental variables referenced are the following:
The below steps will show how to initialize the MySQL database with secrets that are stored in the Keeper Vault.
Step 1: Create 2 Vault Records with Secrets
Create two records in the Vault that are managed by the Secrets Manager application. One record contains the root password. The other record contains the regular user, password and database values.
Make sure to copy the Record UID that appears in the vault records. These are used in Step 3 below when referencing the vault secrets.
Capture Record UID for Root Record
Capture Record UID for User Record
Step 2: Create dockerfile that builds on the default MySQL dockerfile
We'll create a dockerfile that installs Keeper Secrets Manager CLI (ksm) and then wraps the ENTRYPOINT with ksm exec
In the below dockerfile, the 4 environment variables are replaced using Keeper Notation. We are also passing in the Secrets Manager profile that points to the vault where the secrets are stored.
FROM mysql:debian
RUN apt-get update && \
apt-get install -y python3 python3-pip python3-venv && \
apt-get clean
# Avoid system installed modules that might interfer.
RUN python3 -m pip install --upgrade pip && \
python3 -m venv $VIRTUAL_ENV
# Upgrade pip since the distro's Python might be old enough that it doesn't like to install newer modules.
RUN pip3 install --upgrade pip
# Install Keeper Secrets Manager CLI
RUN pip3 install keeper-secrets-manager-cli
# Import our configuration, decode it, and store it a place where ksm can find it.
RUN ksm profile import $(printenv --null BUILD_KSM_INI_CONFIG)
ENV MYSQL_ROOT_PASSWORD keeper://${BUILD_ROOT_UID}/field/password
ENV MYSQL_USER keeper://${BUILD_USER_UID}/field/login
ENV MYSQL_PASSWORD keeper://${BUILD_USER_UID}/field/password
ENV MYSQL_DATABASE keeper://${BUILD_USER_UID}/custom_field/database
ENTRYPOINT ["ksm", "exec", "--", ""]
​Step 3: Create a shell script to execute the docker build
To execute the docker build, the below script will pass in the Secrets Manager device configuration, root user Record UID and network user Record UID from the vault that contains the secrets.
​export CF=$(ksm profile export)
docker build \
--build-arg "BUILD_KSM_INI_CONFIG=${CF}" \
--build-arg "BUILD_ROOT_UID=DvpMcO4xV5nZF6jqLGF1fQ" \
--build-arg "BUILD_USER_UID=VNxZvvNAZ8j2mL4WIjEzjg" \
-t mysql_custom \

Example: Using KSM CLI Docker Image

The KSM CLI Docker includes a volume mount to both GLIBC (most Linux distributions) and MUSL (Alpine Linux) CLI binaries. The volume is /cli. This directory can be mounted into another container using the volumes_from in docker-compose or -v from command line docker. The ksm executables exists in directory based on the version of C library your Linux distribution is using.
  • /cli/glibc/ksm - For standard GLIBC distributions like Ubuntu, Debian, Fedora, and CentOS.
  • /cli/musl/ksm - For Alpine Linux.
For example, the following is simple framework showing how to access the CLI binary.
version: "2"
image: keeper/keeper-secrets-manager-cli:latest
image: ubuntu:latest
- init:ro
command: [ '/cli/glibc/ksm', 'exec', 'printenv', 'MY_LOGIN' ]
KSM_CONFIG: ewog ... M09IemdQMnc9Igp9
MY_LOGIN: keeper://bf18xLR3aVut5eYy7oIZZZ/field/login
condition: service_completed_successfully
The init service will load the CLI docker. The container will start, display a CLI splash screen, and then will exit. Even though the container has stopped, the /cli volume is still accessible from other containers.
The main service will mount the CLI docker's volume under the directory /cli using volumes_from. The command is overridden to run the GLIBC version of the KSM CLI. The command is using the exec function of the CLI. That will replace environment variables environment variable, that use the Keeper Notation, with a secret value. The exec command, of the CLI, is running the printenv application. That will print the environment variable, MY_LOGIN, that has been set to Keeper Notation, and has had its value replaced with a secret by the exec command.
$ example : docker-compose up
[+] Running 2/0
⠿ Container example-init-1 Created 0.0s
⠿ Container example-main-1 Recreated 0.1s
Attaching to example-init-1, example-main-1
example-init-1 |
example-init-1 | ██╗ ██╗███████╗███╗ ███╗ ██████╗██╗ ██╗
example-init-1 | ██║ ██╔╝██╔════╝████╗ ████║ ██╔════╝██║ ██║
example-init-1 | █████╔╝ ███████╗██╔████╔██║ ██║ ██║ ██║
example-init-1 | ██╔═██╗ ╚════██║██║╚██╔╝██║ ██║ ██║ ██║
example-init-1 | ██║ ██╗███████║██║ ╚═╝ ██║ ╚██████╗███████╗██║
example-init-1 | ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝ ╚═════╝╚══════╝╚═╝
example-init-1 |
example-init-1 | Current Version: 1.0.13
example-init-1 |
example-init-1 | Running in shell mode. Type 'quit' to exit.
example-init-1 |
example-init-1 exited with code 0
example-main-1 | [email protected]
example-main-1 exited with code 0

Contribute to the Docker Runtime Examples

If you have some great examples to contribute to this page, please ping us on Slack or email [email protected]
Export as PDF
Copy link
On this page
Example: Provision MySQL network user account
Example: Using KSM CLI Docker Image
Contribute to the Docker Runtime Examples