Docker Writer Image

A general purpose docker image to retrieve secrets.


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 "SECRETS=JfXpSQ2nZG6lkdl1rxB0dg/file/example.crt > file:example.crt"

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.


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



A base64 encode configuration file.


A line-feed separated list of Keeper notation and destinations.


A filename to write the non-file destination secrets.


The format of the secrets file. Valid format are export, setenv, set, and JSON. JSON is the default.


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.


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


The writer image is best used in an Init Container.

    - name: my_app
      image: keeper/keeper-secrets-manager-writer:latest
        - 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"
    image: keeper/keeper-secrets-manager-writer:latest
      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
      - keys-volume:/etc/keys
    image: nginx
    restart: always
     - ./config:/etc/nginx/conf.d
     - keys-volume:/etc/keys
     - "80:80"
     - "443:443"
        condition: service_completed_successfully

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 "SECRETS=JfXpSQ2nZG6lkdl1rxB0dg/file/example.crt > file:example.crt"

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.

Last updated