Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 38 ยท Secrets and Configs

Rotating Secrets and Configs in Docker Swarm

Use docker config for non-sensitive files, and learn the safe rotate pattern for immutable secrets and configs: new name, service update, remove the old one.

Secrets hold sensitive values. Many files your containers need are not sensitive: an nginx.conf, a feature-flag file, a logging setup. Baking them into an image forces a rebuild for every tweak. Swarm configs solve this. They work almost exactly like secrets, but they are meant for non-sensitive data: they are mounted straight into the container's filesystem (no RAM disk) and their content can be inspected, which makes them a good fit for configuration files.

Both objects are immutable, so changing them follows a fixed pattern called rotation. This lesson shows the commands (read-only; the swarm is not available on this site) and a runnable stand-in that models the rotation logic.

Configs in practice

Terminal
docker config create nginx_conf_v1 ./nginx.conf
docker config ls
docker config inspect --pretty nginx_conf_v1

docker service create --name web \
  --config source=nginx_conf_v1,target=/etc/nginx/nginx.conf \
  -p 80:80 nginx:1.27

Differences from secrets:

Secret Config
Intended content Passwords, keys, tokens Non-sensitive settings
Default mount /run/secrets/<name> on a tmpfs Any path you choose (default /<name>)
Encrypted in the Raft log Yes Yes (stored in the same encrypted log)
Reaches worker disk No, memory only Not tmpfs-backed; it is a file in the container filesystem
Value readable with inspect No Yes, docker config inspect shows the data
Size limit 500 KB 500 KB

Because inspect reveals a config, never put a credential in one.

Why rotation exists

A secret or config cannot be edited. That is a feature: every task that mounts nginx_conf_v1 sees the same bytes, so you can always tell what a running container used. To change content you create a new object under a new name and swap it in. The standard way to avoid downtime is to remove the old mount and add the new one in a single update:

Terminal
docker config create nginx_conf_v2 ./nginx.conf

docker service update \
  --config-rm nginx_conf_v1 \
  --config-add source=nginx_conf_v2,target=/etc/nginx/nginx.conf \
  web

docker config rm nginx_conf_v1

The update triggers a normal rolling update (see Rolling Updates): Swarm replaces tasks a few at a time, so the service stays available. Only after the update finishes can you delete the old config; Docker refuses to remove an object that a service still uses.

flowchart LR
  V1["config v1<br/>in use"] --> U["service update:<br/>rm v1, add v2"]
  U --> V2["config v2<br/>in use"]
  V1 -. "docker config rm" .-> G["deleted"]

Create new, swap in one update, delete old.

Naming strategies

Put a version or a hash in the name so rotation is obvious and repeatable:

  • Counter: db_password_v3.
  • Date: api_token_2026_11.
  • Content hash: nginx_conf_ plus the first 8 characters of the file's SHA-256. In Compose stack files this is automated with the name: key, as shown in Stack Files. When the hash is part of the name, an unchanged file reuses the same object and a changed file produces a new one.

Templates

Configs can be rendered from Go templates with --template-driver golang, which lets a config reference service metadata such as {{ .Service.Name }} or the contents of a secret with {{ secret "name" }}. This is useful for generating a config file that embeds a password without ever storing the final text in the swarm. It is an advanced feature; the simpler pattern is to mount the secret and let the app read it.

A stand-in: rotation without downtime

The block below is a stand-in, not Docker. It models a service with replicas that each mount one object and a rolling update with parallelism 1. It also enforces Docker's rule that you cannot delete an object that is still in use.

Python Stand-in: rotate a config safely

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: content-hash names

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.

Practical advice

  • Rotate secrets on a schedule and after any suspected leak. Because rotation is a rolling update, it is routine, not an outage.
  • Keep the old object until the new tasks are healthy, then delete it. If the new version breaks, roll back and the old mount returns.
  • Do not rotate by deleting first: the service would have nothing to mount.
  • Store the source files for configs in Git; store secret values only in your password manager or a vault.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. How do you change the contents of an existing Swarm config?

    Configs and secrets are immutable, so you rotate by creating a new object and swapping it in.
  2. 2. What happens if you try to remove a config that a service still uses?

    Swarm protects running services by refusing to delete objects in use.
  3. 3. Which statement about configs is true?

    Configs are for non-sensitive data and their content can be inspected.

Summary

  • Configs deliver non-sensitive files to services without rebuilding images; secrets deliver sensitive ones.
  • Both are immutable: rotate by creating a versioned object, swapping it in one docker service update, then removing the old one.
  • Hash-based names make rotation automatic and repeatable.
  • Never put credentials in a config, because inspect shows its data.

Next: Protecting Swarm Secrets at Rest