Docker Secrets: An Introductory Guide with Examples

Securing sensitive data is crucial for any application, but managing this data can be complex and error-prone. Docker secrets provide a reliable and secure way to handle sensitive information like passwords, API keys, and certificates in your Docker environment. 

In this introductory guide, we’ll explore what Docker secrets are, how to use them with practical examples, and share some best practices to help you safeguard your sensitive data effectively. Additionally, we’ll touch upon Docker Swarm, managing secrets without Swarm, and using secrets with Docker Compose. So, let’s dive in and unlock the secrets of Docker secrets!

What Are Secrets in Docker?

Docker secrets are a secure way to manage sensitive data in your Docker environment, such as passwords, API keys, and other important information. They are designed to help developers and DevOps professionals avoid accidentally leaking these sensitive details in their applications or Docker images. Secrets are encrypted and stored securely and can only be accessed by authorized services running in your Docker Swarm. 

Speaking of Docker Swarm, it’s important to note that Docker secrets are a Swarm feature. Swarm is a native clustering and orchestration solution for Docker. It allows you to create and manage a group of Docker nodes as a single, logical entity, making it easier to deploy, scale, and manage services across multiple nodes. While Docker secrets are built explicitly for Swarm, there are alternative ways to manage sensitive data in non-Swarm environments, which we’ll touch upon later. 

Docker Secrets Example

Now, let’s dive into a practical example of how to use Docker secrets. We’ll start by creating a secret, then show how to use it within a service. First, let’s create a new secret containing a password: 

$ echo "mypassword" | docker secret create my_secret -

This command will create a new secret called my_secret, containing the password “mypassword.” Notice the use of the - at the end of the command, which tells Docker to read the secret’s value from standard input instead of a file. Next, let’s create a simple service that makes use of this secret. We’ll use the official NGINX image, and our secret will be used as the basic authentication password: 

$ docker service create --name nginx --secret my_secret nginx:latest

In this command, we create a new service called nginx, using the official NGINX image. We also attach our previously created secret (my_secret) to the service. Now, the secret is available to the NGINX container as a file located at /run/secrets/my_secret. We can reference this file in our nginx configuration to use the secret password for basic authentication. Keep in mind that the secret is not exposed as an environment variable, but as a file. This approach provides an additional layer of security, as environment variables can be leaked through logs or process listings. 

How Can I See My Docker Secrets

You can use the Docker secret ls command to view a list of your Docker secrets. This command will display a table with the secret IDs, names, and creation dates. Here’s an example of the command:

$ docker secret ls

The output will look something like this:

ID                          NAME                CREATED             UPDATED
vqnz6btp7gru0z6gk8zvtey6k   my_secret           2 minutes ago       2 minutes ago

However, the Docker secret ls command only shows the list of secrets and their metadata. It does not display the actual content of the secrets. To inspect a secret and view its metadata in a more detailed format, you can use the docker secret inspect command followed by the secret’s name or ID:

$ docker secret inspect my_secret

This command will return the metadata in a JSON format, but still won’t reveal the actual content of the secret. Docker secrets are designed to be secure, and exposing their content through CLI commands would defeat their purpose. So instead, to access the content of a secret, you need to attach it to a service within your Docker Swarm, and the secret will be available as a file inside the containers of that service. 

Using Docker Secrets for Different Purposes

You can use Docker secrets for various purposes within your application, such as: 

1. Database credentials: Store the username and password for your database as secrets, and reference them in your application’s configuration file.
2. API keys: If your application relies on third-party APIs, you can store the API keys as secrets and use them when making API calls.
3. Private keys: Secrets can also store private keys for SSL/TLS certificates or other cryptographic operations.

These are just a few examples, but the possibilities are endless. By using Docker secrets, you can enhance the security of your sensitive data and reduce the risk of data breaches. 

Best Practices for Docker Secrets

Here are some best practices to keep in mind when working with Docker secrets: 

1. Limit access to secrets: Ensure that only the services that require a secret have access to it. You can do this by only attaching the necessary secrets when creating a service, as shown in the example above.
2. Use version control for secrets: You can create new versions of secrets whenever you need to change their values. This approach helps you keep track of changes and easily revert to a previous version if required.
3. Avoid hardcoding secrets: It’s tempting to hardcode secrets directly into your application’s source code or configuration files, but this is a bad practice. Instead, use Docker secrets to store sensitive data and reference them within your application.
4. Rotate secrets regularly: Regularly rotate your secrets to minimize the risk of unauthorized access. Develop a process for rotating secrets and updating services that use them. This might involve creating new secrets, updating services to use the new secrets, and then removing the old secrets.
5. Never store secrets in version control systems: Ensure that you never store your secrets in your version control system (e.g., Git). Add files containing secrets to your .gitignore file or equivalent, and use a secrets management system, such as Docker secrets, to store and manage them securely.
6. Use strong, unique secrets: Generate strong and unique secrets for each service or component that requires them. Avoid using the same secret across multiple services, as this increases the potential impact of a breach.
7. Encrypt secrets at rest: Docker secrets are encrypted by default when stored in the Swarm. However, if you use an alternative secrets management solution, ensure you encrypt your secrets at rest.

Docker Secrets Without Swarm

As mentioned earlier, Docker secrets are a feature of Docker Swarm. If you’re not using Swarm, you might wonder how to manage secrets in your environment securely. While Docker secrets offer a native solution for Swarm, there are alternative ways to handle sensitive data in non-Swarm environments: 

1. Environment variables: While not as secure as Docker secrets, you can use environment variables to pass sensitive data to your containers. Be cautious; environment variables can be exposed in logs or process listings.
2. Docker secrets with bind mounts: In non-Swarm environments, you can still use Docker secrets by creating a secrets file on the host and mounting it as a read-only volume inside the container. However, this method requires careful management of the secrets file on the host and ensuring that it is not accessible to unauthorized users.
3. Third-party secrets management tools: There are several third-party secrets management tools available, such as HashiCorp Vault, AWS Secrets Manager, and Azure Key Vault. These tools can be used to securely store and manage sensitive data in your Docker environment, regardless of whether you are using Swarm or not.

Build/Compose/Create Secrets

If you use Docker Compose to define your application stack, you can also manage secrets using the secrets configuration. This allows you to define and use secrets within your docker-compose.yml file. For example: 

version: '3.9'

services:
  nginx:
    image: nginx:latest
    secrets:
      - my_secret

secrets:
  my_secret:
    file: ./my_secret.txt

 In this example, we define a secret called my_secret and specify its value from a local file named my_secret.txt. The secret is then attached to the NGINX service, making it available at /run/secrets/my_secret within the container. 

Remember that this method of managing secrets with Docker Compose is designed for development and testing environments, not production. Therefore, using Docker Swarm secrets or another secrets management solution for production environments would be best. 

In Summary

In summary, Docker secrets provide a secure way to manage sensitive data in your Docker environment, mainly when using Docker Swarm. By following the best practices and examples outlined in this guide, you can enhance the security of your applications and protect your sensitive data from unauthorized access. If you found this article on Docker secrets useful you might be interested in our blog on Kubernetes secrets too. 

This post was written by Juan Reyes. As an entrepreneur, skilled engineer, and mental health champion, Juan pursues sustainable self-growth, embodying leadership, wit, and passion. With over 15 years of experience in the tech industry, Juan has had the opportunity to work with some of the most prominent players in mobile development, web development, and e-commerce in Japan and the US.