Secrets in Compose (original) (raw)

How to use secrets in Docker Compose

A secret is any piece of data, such as a password, certificate, or API key, that shouldn’t be transmitted over a network or stored unencrypted in a Dockerfile or in your application’s source code.

Docker Compose provides a way for you to use secrets without having to use environment variables to store information. If you’re injecting passwords and API keys as environment variables, you risk unintentional information exposure. Services can only access secrets when explicitly granted by a secrets attribute within the services top-level element.

Environment variables are often available to all processes, and it can be difficult to track access. They can also be printed in logs when debugging errors without your knowledge. Using secrets mitigates these risks.

Secrets are mounted as a file in /run/secrets/<secret_name> inside the container.

Getting a secret into a container is a two-step process. First, define the secret using thetop-level secrets element in your Compose file. Next, update your service definitions to reference the secrets they require with thesecrets attribute. Compose grants access to secrets on a per-service basis.

Unlike the other methods, this permits granular access control within a service container via standard filesystem permissions.

Simple

In the following example, the frontend service is given access to the my_secret secret. In the container, /run/secrets/my_secret is set to the contents of the file ./my_secret.txt.

Advanced

In the advanced example above:

The secrets attribute under each service defines the secrets you want to inject into the specific container.
The top-level secrets section defines the variables db_password and db_root_password and provides the file that populates their values.
The deployment of each container means Docker creates a temporary filesystem mount under /run/secrets/<secret_name> with their specific values.

The _FILE environment variables demonstrated here are a convention used by some images, including Docker Official Images like mysql and postgres.

Build secrets

In the following example, the npm_token secret is made available at build time. Its value is taken from the NPM_TOKEN environment variable.