diff --git a/docs/reference/commandline/swarm.md b/docs/reference/commandline/swarm.md
index 395db69056..e8a8224f84 100644
--- a/docs/reference/commandline/swarm.md
+++ b/docs/reference/commandline/swarm.md
@@ -24,6 +24,7 @@ Options:
--help Print usage
Commands:
+ ca Manage root CA
init Initialize a swarm
join Join a swarm as a node and/or manager
join-token Manage join tokens
diff --git a/docs/reference/commandline/swarm_ca.md b/docs/reference/commandline/swarm_ca.md
new file mode 100644
index 0000000000..4a9010c896
--- /dev/null
+++ b/docs/reference/commandline/swarm_ca.md
@@ -0,0 +1,122 @@
+---
+title: "swarm ca"
+description: "The swarm ca command description and usage"
+keywords: "swarm, ca"
+---
+
+<!-- This file is maintained within the docker/docker Github
+ repository at https://github.com/docker/docker/. Make all
+ pull requests against that repo. If you see this file in
+ another repository, consider it read-only there, as it will
+ periodically be overwritten by the definitive file. Pull
+ requests which include edits to this file in other repositories
+ will be rejected.
+-->
+
+# swarm ca
+
+```markdown
+Usage: docker swarm ca [OPTIONS]
+
+Manage root CA
+
+Options:
+ --ca-cert pem-file Path to the PEM-formatted root CA certificate to use for the new cluster
+ --ca-key pem-file Path to the PEM-formatted root CA key to use for the new cluster
+ --cert-expiry duration Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s)
+ -d, --detach Exit immediately instead of waiting for the root rotation to converge
+ --external-ca external-ca Specifications of one or more certificate signing endpoints
+ --help Print usage
+ -q, --quiet Suppress progress output
+ --rotate Rotate the swarm CA - if no certificate or key are provided, new ones will be generated
+```
+
+## Description
+
+View or rotate the current swarm CA certificate. This command must target a manager node.
+
+## Examples
+
+Run the `docker swarm ca` command without any options to view the current root CA certificate
+in PEM format.
+
+```bash
+$ docker swarm ca
+-----BEGIN CERTIFICATE-----
+MIIBazCCARCgAwIBAgIUJPzo67QC7g8Ebg2ansjkZ8CbmaswCgYIKoZIzj0EAwIw
+EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAzMTcxMDAwWhcNMzcwNDI4MTcx
+MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
+A0IABKL6/C0sihYEb935wVPRA8MqzPLn3jzou0OJRXHsCLcVExigrMdgmLCC+Va4
++sJ+SLVO1eQbvLHH8uuDdF/QOU6jQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
+Af8EBTADAQH/MB0GA1UdDgQWBBSfUy5bjUnBAx/B0GkOBKp91XvxzjAKBggqhkjO
+PQQDAgNJADBGAiEAnbvh0puOS5R/qvy1PMHY1iksYKh2acsGLtL/jAIvO4ACIQCi
+lIwQqLkJ48SQqCjG1DBTSBsHmMSRT+6mE2My+Z3GKA==
+-----END CERTIFICATE-----
+```
+
+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
+-----BEGIN CERTIFICATE-----
+MIIBazCCARCgAwIBAgIUFynG04h5Rrl4lKyA4/E65tYKg8IwCgYIKoZIzj0EAwIw
+EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTE2MDAxMDAwWhcNMzcwNTExMDAx
+MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
+A0IABC2DuNrIETP7C7lfiEPk39tWaaU0I2RumUP4fX4+3m+87j0DU0CsemUaaOG6
++PxHhGu2VXQ4c9pctPHgf7vWeVajQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
+Af8EBTADAQH/MB0GA1UdDgQWBBSEL02z6mCI3SmMDmITMr12qCRY2jAKBggqhkjO
+PQQDAgNJADBGAiEA263Eb52+825EeNQZM0AME+aoH1319Zp9/J5ijILW+6ACIQCg
+gyg5u9Iliel99l7SuMhNeLkrU7fXs+Of1nTyyM73ig==
+-----END CERTIFICATE-----
+```
+
+### `--rotate`
+
+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.
+
+
+### `--detach`
+
+Initiate the root CA rotation, but do not wait for the completion of or display the
+progress of the rotation.
+
+## Related commands
+
+* [swarm init](swarm_init.md)
+* [swarm join](swarm_join.md)
+* [swarm join-token](swarm_join_token.md)
+* [swarm leave](swarm_leave.md)
+* [swarm unlock](swarm_unlock.md)
+* [swarm unlock-key](swarm_unlock_key.md)
diff --git a/docs/reference/commandline/swarm_init.md b/docs/reference/commandline/swarm_init.md
index 0daace038f..f011758a3a 100644
--- a/docs/reference/commandline/swarm_init.md
+++ b/docs/reference/commandline/swarm_init.md
@@ -159,6 +159,7 @@ by passing `--availability=drain` to `docker swarm init`.
## Related commands
+* [swarm ca](swarm_ca.md)
* [swarm join](swarm_join.md)
* [swarm join-token](swarm_join_token.md)
* [swarm leave](swarm_leave.md)
diff --git a/docs/reference/commandline/swarm_join.md b/docs/reference/commandline/swarm_join.md
index 346fb3532e..8d2dfe6d00 100644
--- a/docs/reference/commandline/swarm_join.md
+++ b/docs/reference/commandline/swarm_join.md
@@ -121,6 +121,7 @@ by passing `--availability=drain` to `docker swarm join`.
## Related commands
+* [swarm ca](swarm_ca.md)
* [swarm init](swarm_init.md)
* [swarm join-token](swarm_join_token.md)
* [swarm leave](swarm_leave.md)
diff --git a/docs/reference/commandline/swarm_join_token.md b/docs/reference/commandline/swarm_join_token.md
index 4638a92fd4..44d9cf3ec7 100644
--- a/docs/reference/commandline/swarm_join_token.md
+++ b/docs/reference/commandline/swarm_join_token.md
@@ -106,6 +106,7 @@ Only print the token. Do not print a complete command for joining.
## Related commands
+* [swarm ca](swarm_ca.md)
* [swarm init](swarm_init.md)
* [swarm join](swarm_join.md)
* [swarm leave](swarm_leave.md)
diff --git a/docs/reference/commandline/swarm_leave.md b/docs/reference/commandline/swarm_leave.md
index c5da595d95..1c898ea9a5 100644
--- a/docs/reference/commandline/swarm_leave.md
+++ b/docs/reference/commandline/swarm_leave.md
@@ -62,6 +62,7 @@ command.
## Related commands
+* [swarm ca](swarm_ca.md)
* [node rm](node_rm.md)
* [swarm init](swarm_init.md)
* [swarm join](swarm_join.md)
diff --git a/docs/reference/commandline/swarm_unlock.md b/docs/reference/commandline/swarm_unlock.md
index b507008c1a..d2f5fc4954 100644
--- a/docs/reference/commandline/swarm_unlock.md
+++ b/docs/reference/commandline/swarm_unlock.md
@@ -40,6 +40,7 @@ Please enter unlock key:
## Related commands
+* [swarm ca](swarm_ca.md)
* [swarm init](swarm_init.md)
* [swarm join](swarm_join.md)
* [swarm join-token](swarm_join_token.md)
diff --git a/docs/reference/commandline/swarm_unlock_key.md b/docs/reference/commandline/swarm_unlock_key.md
index 42faae83aa..c0efd04922 100644
--- a/docs/reference/commandline/swarm_unlock_key.md
+++ b/docs/reference/commandline/swarm_unlock_key.md
@@ -83,6 +83,7 @@ Only print the unlock key, without instructions.
## Related commands
+* [swarm ca](swarm_ca.md)
* [swarm init](swarm_init.md)
* [swarm join](swarm_join.md)
* [swarm join-token](swarm_join_token.md)
diff --git a/docs/reference/commandline/swarm_update.md b/docs/reference/commandline/swarm_update.md
index 981eeba194..544ef381c0 100644
--- a/docs/reference/commandline/swarm_update.md
+++ b/docs/reference/commandline/swarm_update.md
@@ -43,6 +43,7 @@ $ docker swarm update --cert-expiry 720h
## Related commands
+* [swarm ca](swarm_ca.md)
* [swarm init](swarm_init.md)
* [swarm join](swarm_join.md)
* [swarm join-token](swarm_join_token.md)