Skip to content

Custom TLS certificates#

Common configuration file section: .spec.certificates

A child cluster can present your own TLS certificate for its customer-facing services instead of the default self-signed one. To do this, you supply the certificate as a Secret on the management cluster, in the k0rdent namespace alongside the MkeChildConfig that references it.

spec:
  certificates:
    enabled: true
    domainName: child.example.com
    secretName: my-child-tls

When enabled is true, domainName and secretName are both required.

The domain name is the fully qualified domain name at which the custom certificate is served. As with management clusters, it must differ from the address of the Kubernetes API server.

Referenced Secret requirements#

The Secret named by secretName must meet the requirements detailed in the following table:

Requirement Detail
Namespace The k0rdent namespace, alongside the MkeChildConfig
Type kubernetes.io/tls
Certificate and key tls.crt and tls.key must form a valid pair
CA certificate The Secret must also carry a ca.crt key

The requirements are checked when you apply the MkeChildConfig. If the Secret does not meet the requirements, it is rejected immediately so as not to leave the child cluster in a failed state.

Adding the ca.crt key#

The kubernetes.io/tls Secret type does not require a ca.crt key, and such a key is not created when you run the kubectl create secret tls command. MKE 4 requires a ca.crt key, though, as the MKE 4 Dashboard chart mounts it as a required volume, and without it the dashboard pod never starts on the child cluster.

  1. Run the kubectl create secret generic command to create the Secret. This allows both the Secret type and the ca.crt key to be set:

    kubectl -n k0rdent create secret generic my-child-tls \
  --type=kubernetes.io/tls \
  --from-file=tls.crt=tls.crt \
  --from-file=tls.key=tls.key \
  --from-file=ca.crt=ca.crt

  2. Verify that the Secret type and all three keys are present:

    kubectl -n k0rdent describe secret my-child-tls

    Type:  kubernetes.io/tls

Data
====
ca.crt:   1273 bytes
tls.crt:  1517 bytes
tls.key:  1704 bytes

Validation errors#

The application of a MkeChildConfig with certificates.enabled: true fails when a requirement is not met, with the display of one of the messages detailed in the table below. Each of these messages is reported against the spec.certificates.secretName field, unless noted otherwise.

Message Cause
custom TLS certificate is enabled but the secret name is not specified secretName is empty.
domain name is required when custom TLS certificates are enabled domainName is empty; reported against spec.certificates.domainName.
secret with custom TLS certificate is not found No Secret by that name exists in the k0rdent namespace.
referenced secret has incorrect type. The only supported type is kubernetes.io/tls The Secret is of another type, for example Opaque.
referenced secret is missing the "ca.crt" key holding the CA certificate The Secret has no ca.crt key.

An invalid tls.crt and tls.key pair is reported against the same field, with the underlying certificate validation error.

Note

The use of a custom TLS certificate on a management cluster differs significantly from that of a child cluster. For more information, refer to TLS certificates.