Docker Secrets vs. Environment Variables

1. The Standard: Configuration with Environment Variables

A core principle in modern application development, popularized by the 12-Factor App methodology, is to store configuration in the environment, completely separate from the application code. This allows you to deploy the same container image across different environments (dev, staging, prod) simply by changing its configuration.

Docker embraces this principle, making it easy to pass environment variables to containers.

While environment variables are perfect for non-sensitive data like port numbers or feature flags, they become a significant liability when used for secrets.

2. The Problem: Why Environment Variables Are Unsafe for Secrets

Using environment variables for secrets is a widespread but dangerous practice. The fundamental issue is that they are stored in plain text and can be exposed in numerous ways.

Let's return to Bret Fisher's video, where he explicitly discusses what should not go into environment variables.

To summarize and reinforce these points, let's review a short article.

The key risks are:

• Inspection: Anyone with access to the Docker host can run docker inspect <container_id> and see all environment variables in plain text.
• Process Snooping: On the host, a simple ps aux command can sometimes reveal environment variables of running processes.
• Log Leakage: Applications often log errors that include a full environment dump for debugging, inadvertently writing secrets to logs.
• Linked Containers: Child processes and linked containers can inherit environment variables, exposing secrets to services that don't need them.
• Source Control: Storing secrets in .env files or docker-compose.yml files which are then committed to version control is a very common mistake.

3. The Solution: Docker Secrets

To address these risks, Docker provides a built-in mechanism for managing secrets securely: Docker Secrets. This feature is available for services running in Docker Swarm or managed by Docker Compose.

How Docker Secrets Work

Instead of injecting secrets as plain text, Docker Secrets works differently.

As the documentation describes, a secret is:

1. Encrypted at Rest: Stored in the encrypted Raft log on swarm manager nodes.
2. Encrypted in Transit: Sent to authorized containers over a secure TLS connection.
3. Stored in Memory: Mounted into the container as a file in a tmpfs in-memory filesystem (by default at /run/secrets/<secret_name>). This is the same tmpfs concept we saw in the last lesson for read-only filesystems. Since it's in memory, it's never written to the container's disk and vanishes when the container stops.

Docker Secrets vs. Environment Variables: The Differentiation

Let's clearly differentiate the two approaches.

4. Implementing Docker Secrets

To use Docker Secrets, your application needs to be able to read its configuration from files instead of just environment variables. Many official images support this with a special convention.

The common pattern is:

1. Define your secrets in a top-level secrets: block in your docker-compose.yml, pointing to external files. This keeps the secret values out of your version-controlled Compose file.
2. Grant a service access to a secret using the secrets: block within that service's definition.
3. The application image is designed to look for an environment variable ending in _FILE (e.g., MYSQL_PASSWORD_FILE). If it finds this, it reads the content of the file specified by that variable instead of looking for the MYSQL_PASSWORD variable.
4. You set this _FILE variable in your docker-compose.yml to point to the file path where Docker mounts the secret (e.g., /run/secrets/db_password).

services:
  api:
    image: my-api:1.0
    environment:
      - DB_PASSWORD=supersecret123

5. Bonus: Secrets at Build Time

So far, we've discussed runtime secrets. But what if you need a secret during the docker build process, for example, to git clone a private repository or download packages from a private registry? A common mistake is to use ARG.

Using --mount=type=secret is a critical technique for secure CI/CD pipelines, ensuring your build-time credentials don't end up embedded in your final production image.

Conclusion

You now have a clear understanding of the crucial differences between environment variables and Docker Secrets for managing sensitive data. This knowledge is fundamental to building secure, production-grade containerized applications.

Key Takeaways:

• Environment variables are for non-sensitive configuration only. They are insecure for secrets as they can be easily leaked through logs, inspection, and process lists.
• Docker Secrets are the secure, built-in mechanism for managing runtime secrets in Docker Compose and Swarm. They are encrypted, managed centrally, and mounted into a container's memory as a temporary file.
• The _FILE suffix is a common convention used by container images to read a secret's value from its mounted file path.
• For build-time secrets, never use ARG. Instead, use Docker BuildKit's --mount=type=secret feature to temporarily provide credentials during the build process without embedding them in the image.

In our final lesson for this security module, we will investigate another high-stakes topic: analyzing the security implications of mounting the Docker socket in a container. This is a powerful but potentially dangerous pattern that you will frequently encounter in the wild.