Getty Images


How to keep Docker secrets secret

Secrets greatly increase an environment's security but can take some trial and error to implement correctly. Learn the basics, and then follow this tutorial to create a secret.

As the name Docker secrets implies, this service manages and secures sensitive information, such as application keys, certificates and API keys.

Too often, data is either baked into the image or stored in a repository for addition to an image at build time -- or copied in from a local source. But, if unwanted users can see that repository, they can probably detect those secrets. If unauthorized users can download a poorly built image, they only need to examine the layers to pull out potentially sensitive data.

The basics of secrets

As a best practice for Docker secrets management, don't set sensitive configuration information at build time -- not least because hardcoding a password means that, when the password changes, the image must be rebuilt. It is also bad practice to leave secret information on the local disk.

Docker has a built-in set of tools to manage and distribute the secret information as required -- and only to the containers allowed to access them. Docker secrets can also be version-controlled.

A secret can be almost anything, but some examples include the following:

In short, this is any code or text that doesn't exceed the limit of 500 kilobytes. The actual distribution of secret data between nodes is managed by the Docker service. And the secret exists only for as long as the service runs in the container. The management nodes in Docker Swarm manage the secrets and encryption.

Once the service stops, the secret is removed from the container, which ensures secrets aren't left behind and visible. Also, these secrets are created via the Docker secret tool set and can take plain text or a file as an argument. When used, the secrets are mounted as files that contain the information.

Quick Docker secrets tutorial

Administrators can use these secrets however they need to. For example, they can directly reference the secrets from a configuration file, such as for web server keys and certificates, or read it out into some other variable for manipulation or consumption.

To create a simplistic secret in Swarm, use the following Bash command. You can use any language that supports piping.

echo "This is my big secret" | docker secret create my_first password -

The  (dash) at the end of the command is necessary to avoid an error. It serves as a terminator for the standard input, or STDIN, argument -- except when the administrator wants to use a file as the secret.

If all preceding steps are successful, the administrator will have created a secret called my_first_password. To check if that's true, use this command:

docker secret ls

That command will display all the secrets currently managed. Here is an example:

sysadmin@dockerl:~$ docker secret ls
ID                            NAME            DRIVER  CREATED    UPDATED
d2ugifo8qhp892nut5qoha6io     my_first_password        2 days ago  2 days ago
xxngdg2x261201gctzphysv64     my_secret_data          2 days ago 2 days ago

To then examine the secret, use the docker secret inspect command:

sysadmin@dockerl:~$ docker secret inspect my_secret_data
            "ID": "xxngdg2x261201gctzphysv64",
            "Version": {
                  "Index": 33
            "CreatedAt": "2021-06-13T21:41:52.162417061Z
            "UpdatedAt": "2021-06-12T21:41:52.162417061Z
            "Spec": {
                  "Name": "my_secret_data",
                  "Labels": {}

The docker secret info command is useful to see detailed information about specific secrets.

A Docker secret isn't useful in isolation. The services that need access to these secrets require permission. In this example, the following command grants that access:

docker service  create --name webservice --secret my_secret_data nginx

This command uses the Alpine Linux image to create the service, named webservice, and grants it access to the secret. Depending on the service's configuration, all containers running under the webservice service will receive access to the secret to perform the necessary functions.

All containers in that service can access the secret freely, thereby making secrets available automatically on the appropriate hosts.

Secrets are contained in mount points and will vary from distro to distro. In other words, your mileage may vary. Consult the documentation. The default mount point is /run/secrets/<secret_name>.

To remove secrets, use the docker secret rm command.

Dig Deeper on Containers and virtualization

Software Quality
App Architecture
Cloud Computing
Data Center