github.com/khulnasoft/cli@v0.0.0-20240402070845-01bcad7beefa/docs/reference/commandline/swarm_ca.md (about)

     1  # swarm ca
     2  
     3  <!---MARKER_GEN_START-->
     4  Display and rotate the root CA
     5  
     6  ### Options
     7  
     8  | Name                                   | Type          | Default     | Description                                                                             |
     9  |:---------------------------------------|:--------------|:------------|:----------------------------------------------------------------------------------------|
    10  | `--ca-cert`                            | `pem-file`    |             | Path to the PEM-formatted root CA certificate to use for the new cluster                |
    11  | `--ca-key`                             | `pem-file`    |             | Path to the PEM-formatted root CA key to use for the new cluster                        |
    12  | `--cert-expiry`                        | `duration`    | `2160h0m0s` | Validity period for node certificates (ns\|us\|ms\|s\|m\|h)                             |
    13  | [`-d`](#detach), [`--detach`](#detach) |               |             | Exit immediately instead of waiting for the root rotation to converge                   |
    14  | `--external-ca`                        | `external-ca` |             | Specifications of one or more certificate signing endpoints                             |
    15  | `-q`, `--quiet`                        |               |             | Suppress progress output                                                                |
    16  | [`--rotate`](#rotate)                  |               |             | Rotate the swarm CA - if no certificate or key are provided, new ones will be generated |
    17  
    18  
    19  <!---MARKER_GEN_END-->
    20  
    21  ## Description
    22  
    23  View or rotate the current swarm CA certificate.
    24  
    25  > **Note**
    26  >
    27  > This is a cluster management command, and must be executed on a swarm
    28  > manager node. To learn about managers and workers, refer to the
    29  > [Swarm mode section](https://docs.docker.com/engine/swarm/) in the
    30  > documentation.
    31  
    32  ## Examples
    33  
    34  Run the `docker swarm ca` command without any options to view the current root CA certificate
    35  in PEM format.
    36  
    37  ```console
    38  $ docker swarm ca
    39  
    40  -----BEGIN CERTIFICATE-----
    41  MIIBazCCARCgAwIBAgIUJPzo67QC7g8Ebg2ansjkZ8CbmaswCgYIKoZIzj0EAwIw
    42  EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTAzMTcxMDAwWhcNMzcwNDI4MTcx
    43  MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
    44  A0IABKL6/C0sihYEb935wVPRA8MqzPLn3jzou0OJRXHsCLcVExigrMdgmLCC+Va4
    45  +sJ+SLVO1eQbvLHH8uuDdF/QOU6jQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
    46  Af8EBTADAQH/MB0GA1UdDgQWBBSfUy5bjUnBAx/B0GkOBKp91XvxzjAKBggqhkjO
    47  PQQDAgNJADBGAiEAnbvh0puOS5R/qvy1PMHY1iksYKh2acsGLtL/jAIvO4ACIQCi
    48  lIwQqLkJ48SQqCjG1DBTSBsHmMSRT+6mE2My+Z3GKA==
    49  -----END CERTIFICATE-----
    50  ```
    51  
    52  Pass the `--rotate` flag (and optionally a `--ca-cert`, along with a `--ca-key` or
    53  `--external-ca` parameter flag), in order to rotate the current swarm root CA.
    54  
    55  ```console
    56  $ docker swarm ca --rotate
    57  desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e
    58    rotated TLS certificates:  [=========================>                         ] 1/2 nodes
    59    rotated CA certificates:   [>                                                  ] 0/2 nodes
    60  ```
    61  
    62  Once the rotation os finished (all the progress bars have completed) the now-current
    63  CA certificate will be printed:
    64  
    65  ```console
    66  $ docker swarm ca --rotate
    67  desired root digest: sha256:05da740cf2577a25224c53019e2cce99bcc5ba09664ad6bb2a9425d9ebd1b53e
    68    rotated TLS certificates:  [==================================================>] 2/2 nodes
    69    rotated CA certificates:   [==================================================>] 2/2 nodes
    70  -----BEGIN CERTIFICATE-----
    71  MIIBazCCARCgAwIBAgIUFynG04h5Rrl4lKyA4/E65tYKg8IwCgYIKoZIzj0EAwIw
    72  EzERMA8GA1UEAxMIc3dhcm0tY2EwHhcNMTcwNTE2MDAxMDAwWhcNMzcwNTExMDAx
    73  MDAwWjATMREwDwYDVQQDEwhzd2FybS1jYTBZMBMGByqGSM49AgEGCCqGSM49AwEH
    74  A0IABC2DuNrIETP7C7lfiEPk39tWaaU0I2RumUP4fX4+3m+87j0DU0CsemUaaOG6
    75  +PxHhGu2VXQ4c9pctPHgf7vWeVajQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMB
    76  Af8EBTADAQH/MB0GA1UdDgQWBBSEL02z6mCI3SmMDmITMr12qCRY2jAKBggqhkjO
    77  PQQDAgNJADBGAiEA263Eb52+825EeNQZM0AME+aoH1319Zp9/J5ijILW+6ACIQCg
    78  gyg5u9Iliel99l7SuMhNeLkrU7fXs+Of1nTyyM73ig==
    79  -----END CERTIFICATE-----
    80  ```
    81  
    82  ### <a name="rotate"></a> Root CA rotation (--rotate)
    83  
    84  > **Note**
    85  >
    86  > Mirantis Kubernetes Engine (MKE), formerly known as Docker UCP, provides an external
    87  > certificate manager service for the swarm. If you run swarm on MKE, you shouldn't
    88  > rotate the CA certificates manually. Instead, contact Mirantis support if you need
    89  > to rotate a certificate.
    90  
    91  Root CA Rotation is recommended if one or more of the swarm managers have been
    92  compromised, so that those managers can no longer connect to or be trusted by
    93  any other node in the cluster.
    94  
    95  Alternately, root CA rotation can be used to give control of the swarm CA
    96  to an external CA, or to take control back from an external CA.
    97  
    98  The `--rotate` flag does not require any parameters to do a rotation, but you can
    99  optionally specify a certificate and key, or a certificate and external CA URL,
   100  and those will be used instead of an automatically-generated certificate/key pair.
   101  
   102  Because the root CA key should be kept secret, if provided it will not be visible
   103  when viewing swarm any information via the CLI or API.
   104  
   105  The root CA rotation will not be completed until all registered nodes have
   106  rotated their TLS certificates.  If the rotation is not completing within a
   107  reasonable amount of time, try running
   108  `docker node ls --format '{{.ID}} {{.Hostname}} {{.Status}} {{.TLSStatus}}'` to
   109  see if any nodes are down or otherwise unable to rotate TLS certificates.
   110  
   111  
   112  ### <a name="detach"></a> Run root CA rotation in detached mode (--detach)
   113  
   114  Initiate the root CA rotation, but do not wait for the completion of or display the
   115  progress of the rotation.
   116  
   117  ## Related commands
   118  
   119  * [swarm init](swarm_init.md)
   120  * [swarm join](swarm_join.md)
   121  * [swarm join-token](swarm_join-token.md)
   122  * [swarm leave](swarm_leave.md)
   123  * [swarm unlock](swarm_unlock.md)
   124  * [swarm unlock-key](swarm_unlock-key.md)