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" +--- + + + +# 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)