Docker Secrets: Managing Sensitive Data – A Guide for Beginners

Hello, everyone! In today’s tutorial, I will explain to you the concept of Docker secrets and how they are used to manage sensitive data. As we proceed, you will learn about secrets management and how to use Docker secrets in your applications.

To learn more about Docker, checkout the Docker tutorials for beginners page.

Introduction to Docker Secrets

Before we jump into the how-to, let’s understand what Docker secrets are. Docker secrets is a secure tool that allows you to store and manage sensitive information, such as passwords, OAuth tokens, and ssh keys. Unlike environment variables, Docker secrets are designed to be safely shared between services. This is important because it reduces the risk of exposing sensitive data in application logs or saving it in intermediate layers of a Docker image.

Docker Secrets: Core Concepts

Docker secrets are primarily used in Docker Swarm mode. Swarm mode is a Docker feature that provides native clustering and orchestration capabilities. In a swarm, a secret is accessible only to services that have been explicitly granted access to it, providing additional security.

The secrets are stored in the Swarm’s Raft store, which is encrypted on disk, and transmitted securely among nodes in the swarm. When a service task tries to access a secret, it’s decrypted and loaded into an in-memory filesystem in the container. This way, the secret is never written to the container’s writable layer, reducing the risk of exposure.

Setting Up Docker and Swarm Mode

Before we start working with Docker secrets, you need to have Docker installed and running on your machine. For installing Docker, you can follow the official Docker documentation.

Once Docker is installed, we need to initialize a swarm. Run the following command in your terminal:

docker swarm init

This command will create a single-node swarm on your machine. Docker Swarm is now active and we can proceed to the next steps.

Creating a Docker Secret

Now that we have Docker Swarm running, we can create our first secret. Let’s say we want to store a secret database password. Run the following command:

echo "mysecretpassword" | docker secret create db_password -

In this command, db_password is the name of the secret, and mysecretpassword is the actual secret data. The - after db_password tells Docker to read the secret data from the standard input.

You can verify that the secret is created using the docker secret ls command, which will list all the secrets.

Using Docker Secrets in Services

Now that our secret is created, we can use it in a service. Let’s create a PostgreSQL service and use our secret as the database password.

docker service create --name pg_db --secret db_password postgres:latest

In this command, --secret db_password tells Docker to give the service access to the db_password secret. Inside the service, the secret will be available as a file in the /run/secrets/ directory with the same name as the secret, i.e., db_password.

The PostgreSQL service can now read the database password from the /run/secrets/db_password file when it starts up.

Updating and Removing Secrets

To update a secret, you have to remove the old secret and create a new one. Please note that you cannot update a secret that is currently in use by a service.

To remove a secret, use the docker secret rm command followed by the name of the secret:

docker secret rm db_password

Then you can create a new secret with the updated value.

Best Practices with Docker Secrets

While we’ve covered the basics, let’s dive into some best practices when using Docker secrets:

  1. Least Privilege: Only grant secret access to services that absolutely need it. This follows the principle of least privilege, reducing the potential impact if a service is compromised.
  2. Regular Rotation: You should regularly rotate secrets, meaning you should periodically change them. This reduces the risk if a secret is compromised. Remember, however, that rotating secrets will require restarting services.
  3. Avoid Embedding Secrets in Images: Never include secrets in a Docker image. If a secret is in an image, anyone who can pull the image also has access to the secret. Instead, use Docker secrets to securely inject the secret at runtime.
  4. Avoid Environment Variables for Secrets: Avoid using environment variables to handle sensitive data. Environment variables can be unintentionally leaked, such as through logs or debugging tools.

Managing Secrets in Development and Production

When it comes to managing secrets in development and production environments, it’s important to have different strategies:

  1. Development: In a development environment, you might not use Docker Swarm and Docker secrets. Instead, you could use placeholder data for testing. If you need to use real secrets for development, consider using a .env file, which is not committed to the version control system.
  2. Production: In a production environment, always use Docker secrets to manage sensitive data. Ensure that production secrets are only accessible to production services.

Dealing with Secret Files in your Application

Your application needs to be designed to read secrets from files, as Docker secrets are exposed as files in the /run/secrets/ directory.

For example, in a Python application, you can read a secret using the following code:

def read_secret(secret_name):
        with open(f"/run/secrets/{secret_name}", "r") as secret_file:
    except IOError:
        return None

db_password = read_secret("db_password")

This Python function reads the secret from the file and returns it as a string.

Here is an equivalent Java code snippet to read a Docker secret from a file.

import java.nio.file.Files;
import java.nio.file.Paths;

public class DockerSecrets {

    public static void main(String[] args) {
        String dbPassword = readSecret("db_password");

    private static String readSecret(String secretName) {
        String secret = "";
        try {
            secret = new String(Files.readAllBytes(Paths.get("/run/secrets/" + secretName))).trim();
        } catch (IOException e) {
            // Handle exception here, possibly logging that the secret file could not be read
            System.out.println("Unable to read secret: " + secretName);
        return secret;

This Java code reads the Docker secret from the file and returns it as a String. The readSecret method reads all bytes from the file, converts them to a String and trims any leading or trailing whitespace. If the file can’t be read, it catches the IOException and logs that the secret file could not be read. In the main method, it calls readSecret to read the “db_password” secret and then prints it.


And that’s a wrap! You’ve now learned not just the basics, but also some best practices when working with Docker secrets. By leveraging Docker secrets, you can greatly enhance the security posture of your applications by providing a secure means of using sensitive data.

Remember, Docker secrets are a secure tool designed for use in production environments. While they require Docker Swarm, the added layer of security is well worth it. Keep in mind the principles of least privilege and regular secret rotation, and you’ll be well on your way to creating more secure applications with Docker.

Thanks for joining me in this tutorial. I hope you found it useful and informative. Keep exploring and happy Dockering!