Manage MKE certificate authorities¶

MKE deploys three certificate authority (CA) servers: MKE Cluster Root CA, MKE etcd Root CA, and MKE Client Root CA.

MKE Cluster Root CA¶

Available since MKE 3.7.0

The self-deployed MKE Cluster Root CA server issues certificates for MKE cluster nodes and internal components that enable the components to communicate with each other. The server also issues certificates that are used in admin client bundles.

To rotate the certificate material of the MKE Cluster Root CA or provide your own certificate and private key:

Caution

If there are unhealthy nodes in the cluster, CA rotation will be unable to complete. If rotation seems to be hanging, run docker node ls --format "{{.ID}} {{.Hostname}} {{.Status}} {{.TLSStatus}}" to determine whether any nodes are down or are otherwise unable to rotate TLS certificates.
MKE Cluster Root CA server is coupled with Docker Swarm Root CA, as MKE nodes are also swarm nodes. Thus, if users want to rotate the Docker Swarm Root CA certificate, they must not use the docker swarm ca command in any form as it may break their MKE cluster.
Rotating MKE Cluster Root CA causes several MKE components to restart, which can result in cluster downtime. As such, Mirantis recommends performing such rotations outside of peak business hours.
You should only rotate the MKE Cluster Root CA certificate for reasons of security, a good example being if the certificate has been compromised. The MKE Cluster Root CA certificate is valid for 20 years, thus rotation is typically not necessary.

You must use the MKE CLI to rotate the existing root CA certificate or to provide your own root CA certificate and private key:

SSH into one of the manager nodes of your cluster.
Make a backup prior to making changes to MKE Cluster Root CA.

Warning

In the event of a failure, and if troubleshooting procedures do not work, you may need to restore the cluster using the backup.
Use the mirantis/ucp:3.x.y image to run the ca --cluster command with the desired options.
```
docker container run -it --rm \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mirantis/ucp:3.x.y \
  ca --cluster <command-options>
```
Note

You can use the --rotate flag to automatically regenerate root CA material.

You can provide your own root CA certificate and private key by bind-mounting them to the CLI container at /ca/cert.pem and /ca/key.pem, respectively.
- The certificate must be a self-signed root certificate, and intermediate certificates are not allowed.
- The MKE Cluster Root CA certificate must have a common name that is equivalent to swarm-ca.
- The certificate and key must be in PEM format without a passphrase.
```
docker container run -it --rm \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/cert.pem:/ca/cert.pem \
  -v /path/to/key.pem:/ca/key.pem \
  mirantis/ucp:3.x.y \
  ca --cluster
```

MKE etcd Root CA¶

Available since MKE 3.7.2

The self-deployed MKE etcd Root CA server issues certificates for MKE components that enable the components to communicate with etcd cluster.

Important

If you upgraded your cluster from any version of MKE prior to MKE 3.7.2, the etcd root CA will not be unique. To ensure the uniqueness of the etcd root CA, rotate the etcd CA material using the instructions herein.

To rotate the certificate material of the MKE etcd Root CA or provide your own certificate and private key:

Caution

Rotating MKE etcd Root CA causes several MKE components to restart, which can result in cluster downtime. As such, Mirantis recommends performing such rotations outside of peak business hours.
Other than the aforementioned purpose of ensuring the uniqueness of the etcd root CA, you should only rotate the MKE etcd Root CA certificate for reasons of security, a good example being if the certificate has been compromised. The MKE etcd Root CA certificate is valid for 20 years, thus rotation is typically not necessary.

You must use the MKE CLI to rotate the existing root CA certificate and private key:

SSH into one of the manager nodes of your cluster.
Make a backup prior to making changes to MKE etcd Root CA.

Warning

In the event of a failure, and if troubleshooting procedures do not work, you may need to restore the cluster using the backup.
Use the mirantis/ucp:3.x.y image to run the ca --etcd command with the desired options.
```
docker container run -it --rm \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mirantis/ucp:3.x.y \
  ca --etcd <command-options>
```
Note

You can use the --rotate flag to automatically regenerate root CA material.

You can provide your own root CA certificate and private key by bind-mounting them to the CLI container at /ca/cert.pem and /ca/key.pem, respectively.
- The certificate must be a self-signed root certificate, and intermediate certificates are not allowed.
- The MKE etcd Root CA certificate must have a common name that is equivalent to MKE etcd Root CA.
- The certificate and key must be in PEM format without a passphrase.
```
docker container run -it --rm \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/cert.pem:/ca/cert.pem \
  -v /path/to/key.pem:/ca/key.pem \
  mirantis/ucp:3.x.y \
  ca --etcd
```

MKE Client Root CA¶

Available since MKE 3.7.0

MKE deploys the MKE Client Root CA server to act as the default signer of the Kubernetes Controller Manager, while also signing TLS certificates for non-admin client bundles. In addition, this CA server is used by default when accessing MKE API using HTTPS.

Note

To replace the MKE Client Root CA server with an external CA for MKE API use only, refer to Use your own TLS certificates.

To rotate the existing root CA certificate or provide your own certificate and private key:

Caution

As rotating the MKE Client Root CA invalidates all previously created non-admin client bundles, you will need to recreate these bundles following the rotation.
You should only rotate the MKE Client Root CA certificate for reasons of security, a good example being if the certificate has been compromised. The MKE Client Root CA certificate is valid for 20 years, thus rotation is typically not necessary.

You must use the MKE CLI to rotate the existing root CA certificate or to provide your own root CA certificate and private key:

SSH into one of the manager nodes of your cluster.
Make a backup prior to making changes to MKE Cluster Root CA.

Warning

In the event of a failure, and if troubleshooting procedures do not work, you may need to restore the cluster using the backup.
Use the mirantis/ucp:3.x.y image to run the ca --client command with the desired options:
```
docker container run -it --rm \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  mirantis/ucp:3.x.y \
  ca --client <command-options>
```
Note

You can use the --rotate flag to automatically regenerate root CA material.

You can provide your own root CA certificate and private key by bind-mounting them to the CLI container at /ca/cert.pem and /ca/key.pem, respectively.
- The certificate must be a self-signed root certificate, and intermediate certificates are not allowed.
- The MKE Client Root CA certificate must have UCP Client Root CA as its common name.
- The certificate and key must be in PEM format without a passphrase.
```
docker container run -it --rm \
  --name ucp \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v /path/to/cert.pem:/ca/cert.pem \
  -v /path/to/key.pem:/ca/key.pem \
  mirantis/ucp:3.x.y \
  ca --client
```