TLS certificates#

To ensure that all communications between clients and MKE 4 are encrypted, MKE 4 services are exposed using HTTPS. By default, this is done using self-signed TLS certificates that are not trusted by client tools such as web browsers. Thus, when you try to access MKE 4, your browser warns that it does not trust MKE 4 or that MKE 4 has an invalid certificate.

Configure custom TLS certificates#

You can configure MKE 4 to use your own TLS certificates so that your browser and other client tools will trust your MKE 4 installation. The address you configure for these custom TLS certificates must differ from the address that is specified in .spec.apiServer.externalAddress, and you must use a separate DNS name for the endpoint where the custom TLS certificates are applied.

Info

Mirantis recommends that you make TLS certificate changes outside of peak business hours. Your applications will continue to run normally. The Kube API Server and Ingress Controller will both restart, though, and as such your workloads may experience a short period of unavailability.

Use the MKE 4 CLI (mkectl) to configure MKE 4 to use your own TLS certificates and keys:

All keys and certificates must be uploaded in PEM format.
Enable your custom TLS certificates.

In the spec.certificates section of the mke4.yaml configuration file:
- Set enabled to true.
- Add your TLS certificates in the PEM format under ca, cert and key.
Set a fully qualified domain name in the .spec.certificates.domainName section of the mke4.yaml configuration file.
Important
- Do not use the address specified in .spec.apiServer.externalAddress as the domain name.
- Use an IP address as the domain name only if that IP address is assigned to a controller node. Clients do not send the TLS Server Name Indication (SNI) for an IP address, so the Kubernetes API server cannot select the custom certificate for an IP address that belongs to another host, such as a load balancer. In that case, port 6443 presents the k0s-generated certificate, which causes certificate errors with mkectl login and in generated kubeconfig files. For details and a workaround, refer to TLS verification fails when the custom TLS domain name is an IP address.
A fully configured spec.certificates section is illustrated below:
```
spec:
  certificates:
    enabled: true
    domainName: "not.external-address.com"
    ca: |
      -----BEGIN CERTIFICATE-----
      <pem-data>
      -----END CERTIFICATE-----
    cert: |
      -----BEGIN CERTIFICATE-----
      <pem-data>
      -----END CERTIFICATE-----
    key: |
      -----BEGIN PRIVATE KEY-----
      <pem-data>
      -----END PRIVATE KEY-----
```
Apply the configuration:
```
mkectl apply
```
Once the mkectl apply command completes, to avoid storing sensitive data in the local file you can remove the cert and key fields from .spec.certificates, as at this point the certificates have been stored securely in the cluster.

Warning

Do not remove the ca key and its value from .spec.certificates.

Retrieve the MKE CA certificates#

MKE 4 serves the CA certificates of the cluster at two endpoints, so that users and automation can obtain the certificates they need for mkectl login and kubeconfig files without administrator access to the cluster:

Endpoint	Returns	Use for
`https://<mke-address>/ca`	The CA of the MKE gateway, which serves the MKE 4 Dashboard and authentication (Dex/OIDC) on port `443`.	The `--ca-file` option of `mkectl login` and `mkectl get-token`
`https://<mke-address>/cluster-ca`	The Kubernetes cluster CA that k0s generates.	The `--cluster-ca-file` option of `mkectl login`, and the `certificate-authority-data` field of a kubeconfig file

Both endpoints:

Are served on the MKE 4 address, on HTTPS port 443.
Do not require authentication. CA certificates are public data that clients need to establish trust in the cluster.
Return the certificate in PEM format, with the Content-Type: application/x-pem-file header.
Accept a trailing slash (/ca/ and /cluster-ca/). Deeper paths, such as /ca/ca.crt, return 404.
Reflect CA rotation, whether through mkectl certs rotate or through the replacement of custom certificates. The new certificate is served within about a minute.

Content of the `/ca` endpoint#

The certificate that /ca returns depends on whether custom TLS certificates are enabled:

Custom TLS certificates disabled (default): The MKE-generated client CA, which mkectl certs rotate --client-ca rotates.
Custom TLS certificates enabled (.spec.certificates.enabled: true): The CA that you provide in .spec.certificates.ca.

The /cluster-ca endpoint always returns the k0s-generated Kubernetes cluster CA, even when custom TLS certificates are enabled.

Download the CA certificates#

curl --fail --silent --show-error --insecure --output ca.pem https://<mke-address>/ca
curl --fail --silent --show-error --insecure --output cluster-ca.pem https://<mke-address>/cluster-ca

The --insecure option is necessary only for the first download, as the client does not yet trust the MKE CA. On an untrusted network, compare the certificate fingerprint with a value obtained out of band before you rely on the certificate:
```
openssl x509 -in ca.pem -noout -fingerprint -sha256
```
The --fail option causes curl to exit with an error, rather than save an HTML error page as the certificate, if the request fails.

For the certificates to pass to mkectl login, refer to Choose the CA certificates for mkectl login.

Migrate to the CA endpoints#

If your tooling reads CA data from the /env.json file, switch to the /ca and /cluster-ca endpoints. The /env.json file is internal and unsupported, and Mirantis will remove its CA fields in a future release.

If you are migrating from MKE 3, update any tooling that uses the /ca certificate for the Kubernetes API. In MKE 3, port 443 and the Kubernetes API present the same certificate, so the /ca endpoint covers both. In MKE 4, k0s serves the Kubernetes API with its own CA. With the default certificates, Kubernetes API clients require the /cluster-ca certificate. With custom TLS certificates and a DNS domain name, the /ca certificate covers both, as in MKE 3.