Docker Writer Image

A general purpose docker image to retrieve secrets.

Overview

The Docker Writer Image for KSM is an image that can download secret files and also generate a file containing secrets.

The image can be pulled with the following command:

$ docker pull keeper/keeper-secrets-manager-writer

When run, its parameters are passed in via environmental variables.

$ docker run \
    -v $PWD:/wd --workdir /wd \
    -e "KSM_CONIFG=BASE64 CONFIG" \
    -e "SECRETS=JfXpSQ2nZG6lkdl1rxB0dg/file/example.crt > file:example.crt"
    keeper/keeper-secrets-manager-writer

The writer is used to copy files from the vault and to create files containing secrets. Due to writing information to disk, there is always risk of exposure. An alternative is the keeper/keeper-secrets-manager-cli image and the exec command.

Parameters

The parameters are handled by passing environment variables into the container.

Parameter	Description
KSM_CONFIG	A base64 encode configuration file.
SECRETS	A line-feed separated list of Keeper notation and destinations.
SECRETS_FILE	A filename to write the non-file destination secrets.
SECRETS_FILE_TYPE	The format of the secrets file. Valid format are export, setenv, set, and JSON. JSON is the default.
CLEANUP_FILE	If set, all files created will be added to the shell file to be removed when executed. This file can be executed to remove the files created.

Secrets List

The SECRETS are a list of Keeper Notation and destinations. The values are separated by line feeds. For example:

fXpSQ2nZG6lkdl1rxB0dg/file/example.crt > file:example.crt
cl9a9k0DWP-Iy227rBo5gQ/field/login > MY_LOGIN
gpsBL343CVYMFgOKZ-L2hQ/custom_field/Ip Address > IP_ADDR

Each line is "Keeper Notation > destination". The destination can be either an environmental variable/JSON key or a file path and name. If a file, the path is prefixed with the text file:. It is recommended not to place binary data into an environmental variable due to unknown string encoding.

Secret File Type

The secrets file contains the values of the environmental variable SECRETS. The format of the file is based on the value of SECRETS_FILE_TYPE. The type can be the following values:

• json - Values stored in a JSON format.

• export - Values stored as export commands commonly used with a BASH shell.

• setenv - Values stored as setenv commands commonly used with C shell.

• set - Values stored as set commands commonly used with C shell.

The types related to a shell can be sourced to place the secrets into the environment.

Examples

The Docker Writer Image for KSM can be used for many applications. Here are some examples.

Kubernetes

The writer image is best used in an Init Container.

 initContainers:
    - name: my_app
      image: keeper/keeper-secrets-manager-writer:latest
      env:
        - name: SECRETS
          value: |
            qCAw9dMQgr3Hs7EdfFpfkA/field/password > my_password
            qCAw9dMQgr3Hs7EdfFpfkA/file/exmaple.crt > file:/etc/keys/example.crt
            qCAw9dMQgr3Hs7EdfFpfkA/file/exmaple.key > file:/etc/keys/example.key

In this container, the writer image is used to save a file and create a secrets file that the main container can access. This can be done by mounting a volume, writing the files, and then having the main container mount the same value. The pod's emptyDir is a good choice.

Docker Compose

By using the depends_on options in the main service, the Docker Writer Image for KSM can be used in the initialization service. In the example below, the Docker Writer pulls secrets from the vault and shares them on a volume mount to the main image.

---
version: "2"
services:
  init:
    image: keeper/keeper-secrets-manager-writer:latest
    environment:
      KSM_CONFIG: R2VwWTVDS ... dmVyUHVibGljS2V5SWQiOiAiMTAiCn0=
      SECRETS: |
        qCAw9dMQgr3Hs7EdfFpfkA/field/password > file:/etc/keys/global.pass
        qCAw9dMQgr3Hs7EdfFpfkA/file/myserver.crt > file:/etc/keys/myserver.crt
        qCAw9dMQgr3Hs7EdfFpfkA/file/myserver.key > file:/etc/keys/myserver.key
    volumes:
      - keys-volume:/etc/keys
  main:
    image: nginx
    restart: always
    volumes:
     - ./config:/etc/nginx/conf.d
     - keys-volume:/etc/keys
    ports:
     - "80:80"
     - "443:443"
    environment:
     - NGINX_HOST=example.com
    depends_on:
      init:
        condition: service_completed_successfully
volumes:
  keys-volume:

Normally services start in parallel, however by using the depends_on option the service startup can be controlled. In the above, the main service depends on the init service.

The init service will start, retrieve and save the files into the keys-volume, then exit. By using the condition service_completed_successfully, when the init service successfully exits, it will start the main service. The main service will also mount the keys-volume and use the stored keys.

Docker Command Line

The writer image can be executed in the command line by using docker run.

docker run \
    -v $PWD:/wd --workdir /wd \
    -e "KSM_CONIFG=BASE64 CONFIG" \
    -e "SECRETS=JfXpSQ2nZG6lkdl1rxB0dg/file/example.crt > file:example.crt"
    keeper/keeper-secrets-manager-writer

If SECRETS has multiple secrets, the line-feed character (\n) is hard to represent. The solution is to surround the --env,-e value with $". For example

-e $'SECRETS=V8lFbio0Bs0LuvaSD5DDHA/file/IMG_0036.png > file:my.png\nIumwT1QYRr8TTCtY8rqzhw/custom_field/S3_BUCKET > s3'

Between file:my.png and the next record UID, there is a '\n'. If you don't wrap the entire value with $'' the my.png file name will include the escape line feed and the next record UID.