Skip to content

Registry optionsNew#

Common configuration file section: .spec.registries

A child cluster can pull its images and Helm charts from a registry that requires authentication. Configure the registries in the MkeChildConfig, and reference a credentials Secret for any registry that requires a login.

spec:
  registries:
    imageRegistry:
      url: private-registry.example.com:8080/mke
      credentialsSecretName: mke-registry-creds
    chartRegistry:
      url: oci://private-registry.example.com:8080/mke
      credentialsSecretName: mke-registry-creds

HTTPS is required

Any registry that requires authentication must be served over HTTPS. Because MKE 4 always connects to the registry over TLS and never transmits credentials over plain HTTP, you cannot use credentialsSecretName with a registry at an http:// address.

Note

As MKE 4 only requires an account with read permissions, Mirantis strongly recommends that the credentials you provide correspond to a read-only account.

Setting                                                                Description
.imageRegistry.url Registry address and project path holding the child cluster images, for example private-registry.example.com:8080/mke. Must not end with a slash.
.imageRegistry.credentialsSecretName Name of the kubernetes.io/dockerconfigjson Secret holding pull credentials for the image registry. Optional — when empty, the image registry is accessed anonymously.
.imageRegistry.caData PEM-encoded CA certificate for the registry. Provide when the registry uses TLS certificates issued by a non-public CA.
.chartRegistry.url Registry address and project path holding the child cluster charts in OCI format, for example oci://private-registry.example.com:8080/mke. Must start with oci:// and must not end with a slash.
.chartRegistry.credentialsSecretName Name of the kubernetes.io/dockerconfigjson Secret holding pull credentials for the chart registry. Optional — when empty, the chart registry is accessed anonymously.
.chartRegistry.caData PEM-encoded CA certificate for the registry. Provide when the registry uses TLS certificates issued by a non-public CA.

Create the credentials Secret#

Unlike the mkectl apply command, child clusters have no credential flags, meaning that you need to create the kubernetes.io/dockerconfigjson Secret yourself, in the mke namespace of the management cluster, before you apply the MkeChildConfig. The operator reads it from that location, per the Registry API contract, and delivers the credentials to the child cluster.

Warning

--docker-server is not the full registry URL, but is the registry host only. MKE looks up credentials by registry host (host[:port]). The auths entry for the Secret must be keyed by that host and nothing more — do not include the oci:// scheme or the project path.

Derive --docker-server from your registry url by dropping the scheme and the path, as exemplified below:

  • private-registry.example.com:8080/mke --> private-registry.example.com:8080
  • oci://private-registry.example.com:8080/mke --> private-registry.example.com:8080
  • ghcr.io/my-org --> ghcr.io
  • oci://ghcr.io/my-org --> ghcr.io

A Secret keyed by the full path, for instance ghcr.io/my-org, does not match host ghcr.io. Refer to Troubleshooting for information on the symptom that this produces.

kubectl create secret docker-registry mke-registry-creds \
  --namespace mke \
  --docker-server=private-registry.example.com:8080 \
  --docker-username=<username> \
  --docker-password=<password>

When the image and chart registries share a host, one Secret covers both; reference the same credentialsSecretName for each registry.

How it works

When the MkeChildConfig references a credentialsSecretName, the operator resolves the credentials from that Secret and delivers them to the child cluster, writing the containerd registry authentication onto the child nodes and configuring authenticated Helm-repository access. The credentials are delivered by Secret reference and never appear in the rendered child cluster resources.

Troubleshooting#

If the child cluster stalls at ControlPlaneInitialized: Control plane not yet initialized and never becomes ready, the nodes are probably failing to pull the control-plane images. When credentialsSecretName is set but the referenced Secret has no auths entry matching the registry host, MKE 4 falls back to anonymous pulls, so pulls from a private registry are denied and the control plane never starts.

  1. Confirm the cause:

    • Check the management-cluster operator logs for a warning, such as: credentialsSecretName has no credentials for the registry host; pulls will be anonymous.

    • Verify that the auths key for the Secret is the same as the registry host (host[:port]) and not the full URL:

      kubectl get secret -n mke mke-registry-creds \
  -o jsonpath='{.data.\.dockerconfigjson}' | base64 -d

  2. Refer to the warning to recreate the Secret, with --docker-server set to the host only. Once the Secret is corrected, the operator regenerates the registry configuration for the child cluster and automatically rolls the control-plane machine.