Skip to content

How to configure system-default-registry with a registry namespace in RKE2 and K3s clusters

Article Number: 000022119

Environment

  • Rancher v2.6+
  • A Rancher-provisioned RKE2 or K3s cluster
  • A private registry with Rancher images under a registry namespace, e.g. registry.example.com/docker.io

Procedure

This article details how to configure the system-default-registry settings, for Rancher-provisioned RKE2 and K3s clusters, if you have a private registry where the rancher images from a public repo, e.g. DockerHub or other, are mirrored under a registry namespace, for example docker.io (registry.example.com/docker.io/rancher/hardened-kubernetes:v1.33.5-rke2r1-build20250910), i.e. your global system-default-registry setting within Rancher is registry.example.com/docker.io

This is necessary, as the Rancher global system-default-registry setting will accept a registry hostname with a namespace, but the RKE2/K3s system-default-registry setting accepts a hostname only.

The Rancher and cluster-level system-default-registry setting

The system-default-registry setting within Rancher is used to configure the registry for all Rancher-deployed images (e.g., cattle-cluster-agent, fleet-agent, etc.), as well as the default system-default-registry parameter for all Rancher-provisioned RKE2 and K3s clusters that do not have a cluster-level system-default-registry configured.

How to configure a system-default-registry with a registry namespace

To use a private registry with a namespace (e.g. registry.example.com/docker.io) as the system-default-registry in an RKE2 or K3s cluster you need to configure a registry rewrite rule. The cluster-level system-default-registry for the RKE2 or K3s clusters is set to the registry hostname only (e.g. registry.example.com), a registry mirror configuration is then defined, to rewrite the registry path for rancher images in this private registry to the required namespace (docker.io in this example).

The following snippet from a cluster.provisioning.cattle.io resource configures a private repository available under registry.example.com/docker.io, as the system-default-registry for a cluster. 

    machine_selector_config {
      config = {
        system-default-registry: "registry.example.com"
      }
    }

    registries {
      mirrors {
        endpoints = ["https://registry.example.com"]
        hostname  = "registry.example.com"
        rewrites  = {
          "^rancher/(.*)" = "/docker.io/$1"
        }
      }
    }

These options can be configured by navigating to Cluster Management, selecting Edit Config for a cluster, then clicking on the Registries tab:

  1. Under Container Registry enter the private registry hostname (e.g. registry.example.com)
  2. Click Show Advanced
  3. In Registry Hostname enter the private registry hostname (e.g. registry.example.com)
  4. In Mirror Endpoints enter the private registry with the protocol, and port if required (e.g. https://registry.example.com)
  5. Click Add Rewrite Config
  6. In Rewrite pattern enter ^rancher/(.*)
  7. In Rewrite replacement enter /<namespace>/$1 (e.g. /docker.io/$1)

After setting up this configuration, any Rancher-deployed workload images (e.g. the cluster-agent) are pulled according to the Rancher global system-default-registry setting (e.g. registry.example.com/docker.io), without any rewriting, whilst RKE2/K3s images use the cluster-level system-default-registry (e.g. registry.example.com) and are rewritten (e.g. under registry.example.com/docker.io).