Using Mirror Registries

Introduction

This guide describes how to use mirror registries for images deployed by KubeOne (Kubernetes core components, CNI plugins…). This is useful if don’t have access to the original registries (e.g. you’re having an offline setup) or if you want to workaround Docker Hub pull limits. To accomplish this, this guide uses the ContainerRegistry API.

Prerequisites

This guide assumes that:

• you have an image registry up and running
• all your nodes in the cluster can access the image registry

If you don’t have an image registry, you can check out the Docker Registry as a possible solution.

Configuring Mirror Registries

This section describes how to configure the mirror registries.

Docker

You can configure the mirror registries by adding the containerRuntime stanza to your KubeOne configuration file, such as:

apiVersion: kubeone.k8c.io/v1beta2
kind: KubeOneCluster
versions:
  kubernetes: 1.29.4
cloudProvider:
  aws: {}
containerRuntime:
  docker:
    registryMirrors:
      - http://host1.tld
      - https://host2.tld

For more information about the ContainerRuntime API for Docker, see the API reference.

With this done, you can reconcile your cluster by running kubeone apply.

Containerd

You can configure the mirror registries by adding the containerRuntime stanza to your KubeOne configuration file, such as:

apiVersion: kubeone.k8c.io/v1beta2
kind: KubeOneCluster
versions:
  kubernetes: 1.29.4
cloudProvider:
  aws: {}
containerRuntime:
  containerd:
    registries:
      myunknown.tld:
        mirrors:
        - host1.tld
        - https://host2.tld
        tlsConfig:
          insecureSkipVerify: true
        auth:
          username: "user1"
          password: "insecure"

tlsConfig and auth are optional. Make sure to replace the placeholder values (myunknown.tld, host1.tld, https://host2.tld…).

For more information about the ContainerRuntime API for containerd, see the API reference.

With this done, you can reconcile your cluster by running kubeone apply.

Using the credentials file for the containerd registry configuration

The registry configuration can be also provided via the credentials file. This is useful in case you’re providing authentication credentials and you want to keep them in a separate file.

The credentials file can look like the following one:

registriesAuth: |
  apiVersion: kubeone.k8c.io/v1beta2
  kind: ContainerRuntimeContainerd
  registries:
    my-cool-registry.tld:
      auth:
        username: "stone"
        password: "bridge"  

Make sure to have containerd explicitly enabled in the KubeOneCluster manifest:

...
containerRuntime:
  containerd: {}

The credentials file is provided to the kubeone apply command using the --credentials/-c flag, such as:

kubeone apply --manifest kubeone.yaml --credentials credentials.yaml