Manage credentials with Docker Secrets

Docker Secrets provides secret distribution for Swarm services. Swarm encrypts secrets in its Raft store and in transit, and grants them only to selected services. On Linux, authorized tasks receive secrets as files in an in-memory mount, commonly under /run/secrets/.

This reduces several risks of baking credentials into images or passing them through container environment configuration. It does not prevent an authorized process or administrator from reading a secret, and an application can still leak its contents to a file or log.

Understand the exposure model

Container environment values can appear in inspection output, inherited process environments, and some diagnostics. Access depends on the process and host permissions; environment variables are not automatically public to everyone, but they are often copied into more places than intended.

Linux Swarm secret mounts avoid writing the distributed secret into the container's persistent layer. Windows containers behave differently: secrets are stored in clear text in the container's root disk while the task runs. Protect the host disk appropriately, for example with BitLocker where applicable.

Create and grant a Swarm secret

On a Swarm manager, with a restricted, untracked secret file already prepared:

docker secret create db_password ./secrets/db_password.txt
docker service create --name api --secret db_password myimage
# The application reads /run/secrets/db_password inside its task.

myimage is your application image. Docker does not automatically turn the file into an application configuration value: the application must read it, or the image must implement a documented file-based configuration convention.

Use a secret file in standalone Compose

services:
  api:
    image: myimage
    secrets: [db_password]
secrets:
  db_password:
    file: ./secrets/db_password.txt

A file-based secret in ordinary standalone Compose is backed by a host file mount. It does not acquire Swarm's encrypted Raft storage merely because the YAML uses the word secrets. Secure the source file, backups, filesystem permissions, and access to the Docker daemon.

Rotate deliberately

A useful rotation sequence is:

1. Create a new versioned secret and prepare the backing service to accept the new credential as needed.
2. Update the application service's grants and configuration to use it.
3. Verify that every relevant client authenticates successfully, without logging secret values.
4. Remove the old service grant and obsolete secret after the transition is complete.

Swarm secrets are immutable. Rotation creates a new secret and updates services; it is not an in-place edit to the existing object. Coordinate database or API credential changes with the deployment so the two sides do not disagree during the transition.

Keep plaintext secret files out of Git and images. Grant only the services that need each secret, and avoid copying the value into secondary files or logs after reading it. An encrypted repository file is only as safe as its key management and decryption process.

Integrate an external secret manager

A controlled automation process can retrieve a value from a system such as HashiCorp Vault or a cloud secrets manager, create a Swarm secret, and update the service. A container fetching a file at startup does not automatically create or manage a Swarm secret.

Choose the model around identity, permissions, audit needs, rotation, and failure recovery rather than adding an orchestrator solely to obtain a secret API.

Frequently asked questions

Is a Kubernetes Secret the same thing?

No. Kubernetes encodes Secret data values with base64, which is not encryption. Encryption at rest is a separate cluster configuration, though a managed service may enable it. Swarm and Kubernetes have different storage, access, and distribution models.

Can a Swarm secret be hot-edited?

No. Create a new object and update the service. Whether the application reloads a file or needs a new task is part of the application's deployment design; changing the Swarm grant requires a service update.

What should a single-host deployment use without Swarm?

Restricted Compose file secrets can suit a small setup. An external secret manager may offer stronger centralized identity, audit, and rotation capabilities. Evaluate those requirements rather than assuming file mounts and Swarm secrets provide identical protection.

References

• Docker Swarm secrets
• Use secrets in Compose

Related reading

• Run a Docker image as a container
• Docker security practices (Chinese)