Docker Image

Using environmental variable substitution with containerized environments

Docker Secrets Management

Features

• 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

For a complete list of Keeper Secrets Manager features see the Overview

Prerequisites

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

• Keeper Secrets Manager access (See the Quick Start Guide for more details)

  • Secrets Manager addon enabled for your Keeper account

  • Membership in a Role with the Secrets Manager enforcement policy enabled

• A Keeper Secrets Manager Application with secrets shared to it

  • See the Quick Start Guide for instructions on creating an Application

• A One Time Access Token

• The Keeper Secrets Manager (KSM) CLI Tool

  • See instructions on setting up the KSM CLI here

About

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.

Example 1: Build an Image with Secrets using BuildKit

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.

Example 2: Build an Image with Secrets using Build Arguments

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.

Example 3: Using docker-compose to Build an Image with Secrets

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.

Example 4: Copy files from vault to Docker Image

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. 😃😃😃

Integration with Docker Compose

Keeper Secrets Manager supports direct integration with Docker Compose using the KSM Writer Docker image.

Learn more about the KSM Writer Docker image here.

Contribute to the Docker Image Examples

If you have some great examples to contribute to this page, please ping us on Slack or email [e-mail].