Browse code
Document the swarm root CA rotation CLI command.
Signed-off-by: Ying Li <ying.li@docker.com>
Ying Li authored on 2017/05/11 07:34:56Showing 9 changed files
- docs/reference/commandline/swarm.md
- docs/reference/commandline/swarm_ca.md
- docs/reference/commandline/swarm_init.md
- docs/reference/commandline/swarm_join.md
- docs/reference/commandline/swarm_join_token.md
- docs/reference/commandline/swarm_leave.md
- docs/reference/commandline/swarm_unlock.md
- docs/reference/commandline/swarm_unlock_key.md
- docs/reference/commandline/swarm_update.md
| 30 | 31 |
new file mode 100644 |
| ... | ... |
@@ -0,0 +1,122 @@ |
| 0 |
+--- |
|
| 1 |
+title: "swarm ca" |
|
| 2 |
+description: "The swarm ca command description and usage" |
|
| 3 |
+keywords: "swarm, ca" |
|
| 4 |
+--- |
|
| 5 |
+ |
|
| 6 |
+<!-- This file is maintained within the docker/docker Github |
|
| 7 |
+ repository at https://github.com/docker/docker/. Make all |
|
| 8 |
+ pull requests against that repo. If you see this file in |
|
| 9 |
+ another repository, consider it read-only there, as it will |
|
| 10 |
+ periodically be overwritten by the definitive file. Pull |
|
| 11 |
+ requests which include edits to this file in other repositories |
|
| 12 |
+ will be rejected. |
|
| 13 |
+--> |
|
| 14 |
+ |
|
| 15 |
+# swarm ca |
|
| 16 |
+ |
|
| 17 |
+```markdown |
|
| 18 |
+Usage: docker swarm ca [OPTIONS] |
|
| 19 |
+ |
|
| 20 |
+Manage root CA |
|
| 21 |
+ |
|
| 22 |
+Options: |
|
| 23 |
+ --ca-cert pem-file Path to the PEM-formatted root CA certificate to use for the new cluster |
|
| 24 |
+ --ca-key pem-file Path to the PEM-formatted root CA key to use for the new cluster |
|
| 25 |
+ --cert-expiry duration Validity period for node certificates (ns|us|ms|s|m|h) (default 2160h0m0s) |
|
| 26 |
+ -d, --detach Exit immediately instead of waiting for the root rotation to converge |
|
| 27 |
+ --external-ca external-ca Specifications of one or more certificate signing endpoints |
|
| 28 |
+ --help Print usage |
|
| 29 |
+ -q, --quiet Suppress progress output |
|
| 30 |
+ --rotate Rotate the swarm CA - if no certificate or key are provided, new ones will be generated |
|
| 31 |
+``` |
|
| 32 |
+ |
|
| 33 |
+## Description |
|
| 34 |
+ |
|
| 35 |
+View or rotate the current swarm CA certificate. This command must target a manager node. |
|
| 36 |
+ |
|
| 37 |
+## Examples |
|
| 38 |
+ |
|
| 39 |
+Run the `docker swarm ca` command without any options to view the current root CA certificate |
|
| 40 |
+in PEM format. |
|
| 41 |
+ |
|
| 42 |
+```bash |
|
| 43 |
+$ docker swarm ca |
|
| 44 |
+-----BEGIN CERTIFICATE----- |
|
| 45 |
+MIIBazCCARCgAwIBAgIUJPzo67QC7g8Ebg2ansjkZ8CbmaswCgYIKoZIzj0EAwIw |
|
| 46 |
+EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAzMTcxMDAwWhcNMzcwNDI4MTcx |
|
| 47 |
+MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH |
|
| 48 |
+A0IABKL6/C0sihYEb935wVPRA8MqzPLn3jzou0OJRXHsCLcVExigrMdgmLCC+Va4 |
|
| 49 |
++sJ+SLVO1eQbvLHH8uuDdF/QOU6jQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB |
|
| 50 |
+Af8EBTADAQH/MB0GA1UdDgQWBBSfUy5bjUnBAx/B0GkOBKp91XvxzjAKBggqhkjO |
|
| 51 |
+PQQDAgNJADBGAiEAnbvh0puOS5R/qvy1PMHY1iksYKh2acsGLtL/jAIvO4ACIQCi |
|
| 52 |
+lIwQqLkJ48SQqCjG1DBTSBsHmMSRT+6mE2My+Z3GKA== |
|
| 53 |
+-----END CERTIFICATE----- |
|
| 54 |
+``` |
|
| 55 |
+ |
|
| 56 |
+Pass the `--rotate` flag (and optionally a `--ca-cert`, along with a `--ca-key` or |
|
| 57 |
+`--external-ca` parameter flag), in order to rotate the current swarm root CA. |
|
| 58 |
+ |
|
| 59 |
+``` |
|
| 60 |
+$ docker swarm ca --rotate |
|
| 61 |
+desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e |
|
| 62 |
+ rotated TLS certificates: [=========================> ] 1/2 nodes |
|
| 63 |
+ rotated CA certificates: [> ] 0/2 nodes |
|
| 64 |
+``` |
|
| 65 |
+ |
|
| 66 |
+Once the rotation os finished (all the progress bars have completed) the now-current |
|
| 67 |
+CA certificate will be printed: |
|
| 68 |
+ |
|
| 69 |
+``` |
|
| 70 |
+$ docker swarm ca --rotate |
|
| 71 |
+desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e |
|
| 72 |
+ rotated TLS certificates: [==================================================>] 2/2 nodes |
|
| 73 |
+ rotated CA certificates: [==================================================>] 2/2 nodes |
|
| 74 |
+-----BEGIN CERTIFICATE----- |
|
| 75 |
+MIIBazCCARCgAwIBAgIUFynG04h5Rrl4lKyA4/E65tYKg8IwCgYIKoZIzj0EAwIw |
|
| 76 |
+EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTE2MDAxMDAwWhcNMzcwNTExMDAx |
|
| 77 |
+MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH |
|
| 78 |
+A0IABC2DuNrIETP7C7lfiEPk39tWaaU0I2RumUP4fX4+3m+87j0DU0CsemUaaOG6 |
|
| 79 |
++PxHhGu2VXQ4c9pctPHgf7vWeVajQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB |
|
| 80 |
+Af8EBTADAQH/MB0GA1UdDgQWBBSEL02z6mCI3SmMDmITMr12qCRY2jAKBggqhkjO |
|
| 81 |
+PQQDAgNJADBGAiEA263Eb52+825EeNQZM0AME+aoH1319Zp9/J5ijILW+6ACIQCg |
|
| 82 |
+gyg5u9Iliel99l7SuMhNeLkrU7fXs+Of1nTyyM73ig== |
|
| 83 |
+-----END CERTIFICATE----- |
|
| 84 |
+``` |
|
| 85 |
+ |
|
| 86 |
+### `--rotate` |
|
| 87 |
+ |
|
| 88 |
+Root CA Rotation is recommended if one or more of the swarm managers have been |
|
| 89 |
+compromised, so that those managers can no longer connect to or be trusted by |
|
| 90 |
+any other node in the cluster. |
|
| 91 |
+ |
|
| 92 |
+Alternately, root CA rotation can be used to give control of the swarm CA |
|
| 93 |
+to an external CA, or to take control back from an external CA. |
|
| 94 |
+ |
|
| 95 |
+The `--rotate` flag does not require any parameters to do a rotation, but you can |
|
| 96 |
+optionally specify a certificate and key, or a certificate and external CA URL, |
|
| 97 |
+and those will be used instead of an automatically-generated certificate/key pair. |
|
| 98 |
+ |
|
| 99 |
+Because the root CA key should be kept secret, if provided it will not be visible |
|
| 100 |
+when viewing swarm any information via the CLI or API. |
|
| 101 |
+ |
|
| 102 |
+The root CA rotation will not be completed until all registered nodes have |
|
| 103 |
+rotated their TLS certificates. If the rotation is not completing within a |
|
| 104 |
+reasonable amount of time, try running |
|
| 105 |
+`docker node ls --format {{.ID}} {{.Hostname}} {{.Status}} {{.TLSStatus}}` to
|
|
| 106 |
+see if any nodes are down or otherwise unable to rotate TLS certificates. |
|
| 107 |
+ |
|
| 108 |
+ |
|
| 109 |
+### `--detach` |
|
| 110 |
+ |
|
| 111 |
+Initiate the root CA rotation, but do not wait for the completion of or display the |
|
| 112 |
+progress of the rotation. |
|
| 113 |
+ |
|
| 114 |
+## Related commands |
|
| 115 |
+ |
|
| 116 |
+* [swarm init](swarm_init.md) |
|
| 117 |
+* [swarm join](swarm_join.md) |
|
| 118 |
+* [swarm join-token](swarm_join_token.md) |
|
| 119 |
+* [swarm leave](swarm_leave.md) |
|
| 120 |
+* [swarm unlock](swarm_unlock.md) |
|
| 121 |
+* [swarm unlock-key](swarm_unlock_key.md) |