Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 38 ยท Secrets and Configs

Docker Swarm Secrets: Create and Use Them

Learn what Swarm secrets are, how docker secret create works, how services read them from /run/secrets, and why secrets beat environment variables for passwords.

Almost every real application needs a password, a token or a private key. Putting them in an image or an environment variable leaks them to anyone who can run docker inspect or read your Git history. Swarm has a built-in answer: secrets. A secret is a small blob of sensitive data (up to 500 KB) that the swarm stores encrypted and hands only to the services you name.

Docker Swarm is not available inside this website, so the commands below are shown as read-only text and I never print output I cannot be certain of. The runnable blocks are small Python stand-ins that model the same rules, so you can experiment with the ideas.

What a secret is, and where it lives

When you create a secret on a manager node, the value is sent over the mutually authenticated TLS connection of the control plane and written to the Raft log, the replicated store described in the architecture chapter. Raft data on disk is encrypted, and every manager holds a copy. Worker nodes never keep secrets on disk: a worker receives a secret only when it is about to run a task that needs it, and the secret is kept in memory.

Inside the container the secret appears as a file in an in-memory filesystem (tmpfs) at /run/secrets/<name>. The file is owned by root and readable only by the process owner unless you change the mode. When the task stops, the node removes the file from memory.

flowchart LR
  A["docker secret create"] --> B["Manager Raft log<br/>(encrypted at rest)"]
  B --> C["Worker node<br/>(memory only)"]
  C --> D["Container<br/>/run/secrets/db_password"]

A secret travels from the manager to exactly the nodes that run tasks which need it.

Creating a secret

You can create a secret from a file or from standard input. The - argument means "read stdin":

Terminal
printf 'S3cr3t-Pa55' | docker secret create db_password -
docker secret create tls_key ./server.key
docker secret ls
docker secret inspect db_password

Two details matter. First, use printf and not echo: echo adds a trailing newline that becomes part of the password, and the application will then compare against the wrong value. Second, docker secret inspect shows metadata (ID, name, creation time, labels) but never the value. There is no command that prints a secret back; if you lose it, you create a new one.

Secrets are immutable. You cannot edit one in place. To change a value you create a new secret with a new name and update the service, a process covered in Rotating Secrets and Configs.

Giving a secret to a service

A secret is granted per service, at creation time or later:

Terminal
docker service create --name db \
  --secret db_password \
  -e POSTGRES_PASSWORD_FILE=/run/secrets/db_password \
  postgres:17

docker service update --secret-add tls_key web

The official postgres, mysql and mariadb images support the *_FILE convention: instead of POSTGRES_PASSWORD=... you pass the path of a file that contains the password. Many other images follow the same pattern. If an image does not, add a small entrypoint script that reads the file and exports the variable for its own process only.

You can rename or re-mode the file with the long syntax:

Terminal
docker service create --name api \
  --secret source=db_password,target=pg_pass,uid=1000,gid=1000,mode=0400 \
  myorg/api:1.4

Here the container sees /run/secrets/pg_pass, owned by user 1000 and readable only by that user. Only services that list a secret can see it; a sibling service on the same node cannot.

Why not environment variables?

Environment variables are convenient, but they leak easily: docker inspect shows them, they are copied into child processes, they appear in crash dumps and debug endpoints, and logging frameworks sometimes print the whole environment. A file under /run/secrets is read deliberately, on demand, by code that needs it, and it never ends up in image layers or in docker inspect output.

The same reasoning applies to build arguments: ARG PASSWORD is stored in the image history. Never bake secrets into images; for build-time needs use BuildKit secret mounts.

A stand-in: the rules of /run/secrets

The Python below is a stand-in, not Docker. It models one rule: a service can read only the secrets it was granted, and values never appear in the metadata listing.

Python Stand-in: which service can read which secret?

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Python Stand-in: the trailing newline trap

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Expecting a secret to exist for plain docker run. Secrets are a swarm feature; with docker run use a bind-mounted file or docker compose file-based secrets.
  • Putting the secret value in the service command line, which is visible in docker service inspect.
  • Forgetting that secrets are immutable and trying to "update" one.
  • Granting every secret to every service. Grant the minimum.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a container find a Swarm secret?

    Secrets are mounted as files on a tmpfs at /run/secrets, so they are never written to the container's disk layers.
  2. 2. Which command prints the value of an existing secret?

    inspect returns metadata only. If you lose the value you create a new secret.
  3. 3. Why use printf instead of echo when piping a password to docker secret create?

    The newline would be stored with the password and break comparisons.
  4. 4. Which nodes receive a secret?

    Workers get a secret only when scheduled a task that needs it, and keep it in memory.

Summary

  • Swarm secrets are encrypted at rest in the Raft log and sent over mutual TLS.
  • A task sees a secret as a file in /run/secrets, on a tmpfs, only if its service was granted it.
  • Secrets cannot be read back or edited; create a new one to change a value.
  • Prefer secrets (and *_FILE variables) over environment variables and build arguments.

Next: Rotating Secrets and Configs