Docker Image
Using environmental variable substitution with containerized environments
- Pass secret credentials from the Keeper Vault to Docker images
- Build Docker Images with secret credentials from the Keeper Vault using build arguments
- Copy files from the Keeper vault into Docker containers
This page documents the Secrets Manager Docker Image b Actions integration. In order to utilize this integration, you will need:
- Secrets Manager addon enabled for your Keeper account
- Membership in a Role with the Secrets Manager enforcement policy enabled
The Secrets Manager CLI can be used to pull secrets from a Docker image at runtime, or it can be used by building it into the docker image. Several use cases are described in this document.
Secrets from the Keeper Vault can be built into a Docker container using Docker BuildKit. As of Docker 18.09 or later, image building supports the ability to pass secrets in via a mounted file system. As a simple example demonstrating this capability, we will be creating a user account in the destination image with a username and password from Keeper Secrets Manager.
Step 1: Set Environmental Variables with Keeper notation for the secrets that are needed. For more notation examples click here.
export MY_UID="SOAsfj_lIg0VenDr83gjDw"
export MY_USER="keeper://${MY_UID}/field/login"
export MY_PASS="keeper://${MY_UID}/field/password"
Step 2: Using the
ksm exec command, the Docker build is created with the 2 secrets (login and password). The --secret parameters will pull values from the environmental variables that have been substituted with Keeper secrets.DOCKER_BUILDKIT=1 ksm exec -- \
docker build \
--secret id=my_user,env=MY_USER \
--secret id=my_password,env=MY_PASS \
-t my_image .
Step 3: In the dockerfile, we will create a linux user account using
useradd and then set the password with chpasswd. The Docker file is below:FROM my_base_image
RUN --mount=type=secret,id=my_user,dst=/my_secrets/my_user \
--mount=type=secret,id=my_password,dst=/my_secrets/my_password \
useradd "$(cat /my_secrets/my_user)" && \
echo "$(cat /my_secrets/my_user)":"$(cat /my_secrets/my_password)" | chpasswd
In this example, each secret is mounted as a file. The 'dst' value specifies where you want to temporarily store the secret. Once the RUN command is finished, the temporary file will be removed and unmounted. You can either pass the file name as an argument or in this case we are using
cat $(/path/to/secret) to read the file contents into a variable.Similar to example 1, you can pass in secrets via the
--build-arg. This example will also demonstrate the ability of using secrets in a Docker build process.Step 1: Set Environmental Variables with Keeper notation for the secrets that are needed. For more notation examples click here.
export MY_UID="SOAsfj_lIg0VenDr83gjDw"
export MY_USER="keeper://${MY_UID}/field/login"
export MY_PASS="keeper://${MY_UID}/field/password"
Step 2: Using the
ksm exec command, the Docker build is created with the 2 secrets (login and password). The flag --inline processes the replacement of secrets. For example:ksm exec --inline -- \
docker build \
--build-arg "BUILD_MY_USER=${MY_USER}" \
--build-arg "BUILD_MY_PASSWORD=${MY_PASSWORD}" \
-t my_image .
Step 3: In the dockerfile, we will create a linux user account using
useradd and then set the password with chpasswd. The Docker file is below:FROM my_base_image
ARG BUILD_MY_USER
ARG BUILD_MY_PASSWORD
RUN useradd "$(printenv --null BUILD_MY_USER)" && \
echo "$(printenv --null BUILD_MY_USER)":"$(printenv --null BUILD_MY_PASSWORD)" | chpasswd
To prevent secrets being sent to stdout from the
printenv command, use the --null option to remove the line feed.In this example, we will use docker-compose to build an image. Docker-compose cannot populate build args from environment variables. To replace notation with secret values, the build args need to be set via the command line. Since the notation will be on the command line, the --inline replacement flag needs to be set.
Step 1: Create a simple
docker-compose.yaml file:---
version: "3"
services:
my_app:
build:
content: "."
Step 2: Using the
ksm exec command, the Docker build is created with the 2 secrets (login and password). The flag --inline processes the replacement of secrets. For example:ksm exec --inline -- \
docker-compose build \
--build-arg "BUILD_MY_USER=${MY_USER}" \
--build-arg "BUILD_MY_PASSWORD=${MY_PASSWORD}" \
-t my_image .
Step 3: In the dockerfile, we will create a linux user account using
useradd and then set the password with chpasswd. The Docker file is below:FROM my_base_image
ARG BUILD_MY_USER
ARG BUILD_MY_PASSWORD
RUN useradd "$(printenv --null BUILD_MY_USER)" && \
echo "$(printenv --null BUILD_MY_USER)":"$(printenv --null BUILD_MY_PASSWORD)" | chpasswd
To prevent secrets being sent to stdout from the
printenv command, use the --null option to remove the line feed.In this real world example, we copy an SSL certificate and passphrase from the Keeper Vault to a Tomcat container.
By default, the official Tomcat docker contains a default server configuration that does not have SSL enabled. We are going build a custom image that installs our server.xml, copies over the keystore file, and enables SSL. The server.xml file also contains the secret passphrase for the keystore file.
Step 1: Create a Keeper Secret Record
In the Keeper Vault, create a secret record that contains 2 file attachments:
server.xml and localhost-rsa.jks as seen below:
Create Record with Secret File Attachments
Make note of the Record UID in the information dialog which will be used in the dockerfile. Click the Record UID to copy to your clipboard.
Copy the Record UID
Step 2: Create the dockerfile
The below dockerfile example copies the server.xml and keystore files from the vault into the Tomcat folder.
FROM tomcat:10-jdk16
ARG BUILD_KSM_INI_CONFIG
ARG BUILD_KSM_SERVER_UID
# The names of our files in our secret record
ARG BUILD_SERVER_CONFIG="server.xml"
ARG BUILD_KEYSTORE="localhost-rsa.jks"
# Temporarily install Python3
RUN apt-get update -y && \
apt-get install -y \
python3 \
python3-pip \
python3-venv
# Install modules in a known place so we can remove them later.
ENV VIRTUAL_ENV /venv
RUN python3 -m pip install --upgrade pip && \
python3 -m venv $VIRTUAL_ENV
ENV PATH="$VIRTUAL_ENV/bin:$PATH"
# 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
RUN pip3 install keeper_secrets_manager_cli
RUN echo ${BUILD_KSM_INI_CONFIG}
# Import the KSM Client Device configuration, decode it, and store it a place where ksm can find it.
RUN ksm profile import $(printenv --null BUILD_KSM_INI_CONFIG)
# Download the server.xml and keystore into the Tomcat conf directory
RUN ksm secret download -u ${BUILD_KSM_SERVER_UID} --name ${BUILD_SERVER_CONFIG} --file-output /usr/local/tomcat/conf/server.xml
RUN ksm secret download -u ${BUILD_KSM_SERVER_UID} --name ${BUILD_KEYSTORE} --file-output /usr/local/tomcat/conf/localhost-rsa.jks
# We no longer need ksm. Remove it, python, and Debian apt to make a smaller Docker image.
RUN rm -rf /venv keeper.ini
RUN apt-get purge -y \
python3 \
python3-pip \
python3-venv && \
apt-get clean autoclean && \
apt-get autoremove -y && \
rm -rf /var/lib/{apt,dpkg,cache,log}/
# Expose port 8443 for SSL
EXPOSE 8443
Note that in this use case,
ksm is no longer needed after the build, so it is deleted.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 and Record UID that contains the secret files.
#!/bin/sh
# Export the KSM profile as a string
export CF=$(ksm profile export _default)
# Execute the docker build, passing in the Record UID
# that contains the secret files
docker build \
--build-arg "BUILD_KSM_INI_CONFIG=${CF}" \
--build-arg "BUILD_KSM_SERVER_UID=LdRkidFLPF7vDaogwJ7etQ" \
-t ksm_tomcat .
When the docker image is built, it will be fully configured with SSL, keystore file and passphrase that are managed by the Keeper Vault.
😃
😃
😃
Keeper Secrets Manager supports direct integration with Docker Compose using the KSM Writer Docker image.
If you have some great examples to contribute to this page, please ping us on Slack or email [email protected].
Last modified 1yr ago