/Docker 19

docker swarm ca


Display and rotate the root CA

API 1.30+ The client and daemon API must both be at least 1.30 to use this command. Use the docker version command on the client to check your client and daemon API versions.

Swarm This command works with the Swarm orchestrator.


docker swarm ca [OPTIONS]


Name, shorthand Default Description
--ca-cert Path to the PEM-formatted root CA certificate to use for the new cluster
--ca-key Path to the PEM-formatted root CA key to use for the new cluster
--cert-expiry 2160h0m0s Validity period for node certificates (ns|us|ms|s|m|h)
--detach , -d Exit immediately instead of waiting for the root rotation to converge
--external-ca Specifications of one or more certificate signing endpoints
--quiet , -q Suppress progress output
--rotate Rotate the swarm CA - if no certificate or key are provided, new ones will be generated

Parent command

Command Description
docker swarm Manage Swarm
Command Description
docker swarm ca Display and rotate the root CA
docker swarm init Initialize a swarm
docker swarm join Join a swarm as a node and/or manager
docker swarm join-token Manage join tokens
docker swarm leave Leave the swarm
docker swarm unlock Unlock swarm
docker swarm unlock-key Manage the unlock key
docker swarm update Update the swarm

Extended description

View or rotate the current swarm CA certificate. This command must target a manager node.


Run the docker swarm ca command without any options to view the current root CA certificate in PEM format.

$ docker swarm ca

Pass the --rotate flag (and optionally a --ca-cert, along with a --ca-key or --external-ca parameter flag), in order to rotate the current swarm root CA.

$ docker swarm ca --rotate
desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e
  rotated TLS certificates:  [=========================>                         ] 1/2 nodes
  rotated CA certificates:   [>                                                  ] 0/2 nodes

Once the rotation os finished (all the progress bars have completed) the now-current CA certificate will be printed:

$ docker swarm ca --rotate
desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e
  rotated TLS certificates:  [==================================================>] 2/2 nodes
  rotated CA certificates:   [==================================================>] 2/2 nodes


Root CA Rotation is recommended if one or more of the swarm managers have been compromised, so that those managers can no longer connect to or be trusted by any other node in the cluster.

Alternately, root CA rotation can be used to give control of the swarm CA to an external CA, or to take control back from an external CA.

The --rotate flag does not require any parameters to do a rotation, but you can optionally specify a certificate and key, or a certificate and external CA URL, and those will be used instead of an automatically-generated certificate/key pair.

Because the root CA key should be kept secret, if provided it will not be visible when viewing swarm any information via the CLI or API.

The root CA rotation will not be completed until all registered nodes have rotated their TLS certificates. If the rotation is not completing within a reasonable amount of time, try running docker node ls --format '{{.ID}} {{.Hostname}} {{.Status}} {{.TLSStatus}}' to see if any nodes are down or otherwise unable to rotate TLS certificates.


Initiate the root CA rotation, but do not wait for the completion of or display the progress of the rotation.

© 2019 Docker, Inc.
Licensed under the Apache License, Version 2.0.
Docker and the Docker logo are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.
Docker, Inc. and other parties may also have trademark rights in other terms used herein.