Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 38 ยท Swarm Architecture

Swarm Security and PKI

See how Docker Swarm secures a cluster by default: the built-in certificate authority, mutual TLS, certificate rotation, join tokens and autolock.

Swarm is "secure by default", which is unusual for an orchestrator. As soon as you run docker swarm init, the nodes communicate over mutually authenticated, encrypted channels, and you did not configure a single certificate. This lesson explains how that works and the few knobs you should know: certificate expiry, CA rotation, token hygiene and autolock.

A certificate authority inside the managers

swarm init creates a root CA. Managers act as the CA servers. When a node joins, it sends a certificate signing request with its join token, and a manager answers with a signed node certificate. From then on:

  • Each node proves who it is with its certificate (and the certificate says its role: manager or worker, in the organization field).
  • Nodes talk over mutual TLS (mTLS): both sides verify each other's certificate against the swarm CA.
  • A node that is not part of the swarm cannot talk to the managers, and a worker cannot claim to be a manager, because its certificate says worker.
flowchart TB
  CA["Swarm root CA (on managers)"] --> M["Manager certificates"]
  CA --> W["Worker certificates"]
  M <-->|"mutual TLS"| W

Every node holds a certificate signed by the swarm CA, and every connection verifies it.

Certificate lifetime and rotation

Node certificates are short-lived. The default validity is 90 days, and nodes renew automatically well before expiry (around 80 percent of the lifetime) without any restart. You can change the period:

CONSOLE
$ docker swarm update --cert-expiry 720h

(720 hours is 30 days.) Shorter lifetimes limit the damage of a stolen certificate but make the cluster less tolerant of a long outage: if a node is offline longer than its certificate lifetime, it must rejoin.

If you suspect the root CA was compromised, rotate it:

CONSOLE
$ docker swarm ca --rotate

Swarm issues a new root, cross-signs it so the transition is smooth, reissues every node's certificate and finally drops the old root. You can also bring your own root CA with --ca-cert and --ca-key or delegate signing to an external CA (CFSSL).

Join tokens

Tokens (see swarm init and join) are the doorway. Good habits:

  • Never commit them to Git or paste them into chat. They grant the right to join.
  • Rotate after a leak or when someone leaves the team: docker swarm join-token --rotate manager.
  • Remember the manager token is far more powerful than the worker token: a new manager can read all secrets.

Encryption of the control plane and data

  • Control plane traffic (management, Raft, gossip) is always encrypted with AES-GCM; gossip keys rotate every 12 hours.
  • Overlay data between containers is not encrypted by default. Opt in per network with --opt encrypted (Overlay networks). It uses IPsec ESP, so IP protocol 50 must be allowed.
  • Raft log at rest is stored on the managers' disks. Secrets in it are encrypted, but the key sits next to the data unless you enable autolock.

Autolock

Without autolock, a manager's disk holds both the encrypted log and the key that decrypts it (the "data encryption key", itself protected by a key stored on the same disk). Whoever steals the disk or a backup of /var/lib/docker/swarm can read the secrets. Autolock moves that protecting key out of the disk: a unlock key that you store elsewhere.

CONSOLE
$ docker swarm init --autolock
$ docker swarm update --autolock=true
$ docker swarm unlock-key

After enabling it:

  • Every time the Docker daemon restarts on a manager, the manager stays locked and refuses to join Raft until you run docker swarm unlock and paste the key.
  • Store the key in a password manager or vault, not on the same machines. If you lose the key and all managers restart, the data is unrecoverable.
  • You can rotate the key: docker swarm unlock-key --rotate.

Trade-off: security versus automatic recovery. After a power cut, locked managers wait for a human.

Defence checklist

Hardening a swarm

Firewall 2377 Private network only
Guard the tokens Rotate after any leak
1 / 2

Remember that anyone who can talk to the Docker socket on a manager is effectively root on the cluster. Protect SSH access to managers more than anything else.

Stand-in: certificate renewal timeline

This calculator uses the lifetimes above to show when a node renews and what happens to a node that is offline too long. The 80 percent figure is approximate and Swarm randomizes the exact moment; this is an illustration, not the real algorithm.

Python Stand-in: certificate timeline

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.

Stand-in: how the unlock key decides

This tiny state machine shows the behaviour of autolock after a manager restart.

Python Stand-in: autolock after restart

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.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. How do swarm nodes authenticate each other?

    Each node holds a certificate from the swarm's built-in CA and both sides verify it.
  2. 2. Is overlay network data encrypted by default?

    Control plane traffic is always encrypted; application data on overlays needs the encrypted option.
  3. 3. What does autolock protect against?

    With autolock the key that decrypts the Raft log is not stored on the manager's disk; you supply it after a restart.

Summary

  • Swarm has a built-in CA and uses mutual TLS between all nodes.
  • Certificates renew automatically; rotate the CA with docker swarm ca --rotate.
  • Guard join tokens; encrypt overlays that carry sensitive data.
  • Autolock keeps the log key off the disk at the cost of manual unlocking.

Next: The Orchestrator and Reconciliation