Mirroring Private Registries

Rancher Desktop can be configured to mirror private registries using either container runtime (containerd or dockerd) via provisioning scripts or updating the registry file used by k3s. Please see the k3s documentation for further information on private registry configuration.

Linux

Below is an example provisioning script that can be used to mirror private registries.

Check if you have the override.yaml file in the path below, otherwise you can create the file in the path with the suggested provisioning commands.

Override File Path: $HOME/.local/share/rancher-desktop/lima/_config/override.yaml

Example Script:

provision:
  - mode: system
    script: |
      #!/bin/sh
      set -eux
      mkdir -p /etc/rancher/k3s
      cat <<EOF >/etc/rancher/k3s/registries.yaml
      mirrors:
        "<my.private.registry>:5000":
          endpoint:
          - http://<my.private.registry>:5000
      EOF

After restarting the application, you can verify the script being applied using the rdctl shell command below:

rdctl shell -- cat /etc/rancher/k3s/registries.yaml

macOS

Below is an example provisioning script that can be used to mirror private registries.

Check if you have the override.yaml file in the path below, otherwise you can create the file in the path with the suggested provisioning commands.

Override File Path: $HOME/Library/Application Support/rancher-desktop/lima/_config/override.yaml

Example Script:

provision:
  - mode: system
    script: |
      #!/bin/sh
      set -eux
      mkdir -p /etc/rancher/k3s
      cat <<EOF >/etc/rancher/k3s/registries.yaml
      mirrors:
        "<my.private.registry>:5000":
          endpoint:
          - http://<my.private.registry>:5000
      EOF

After restarting the application, you can verify the script being applied using the rdctl shell command below:

rdctl shell -- cat /etc/rancher/k3s/registries.yaml

Windows

Ensure that you have initialized the application with a first run in order to create the \provisioning\ directory. Once created, provisioning scripts can be utilized to mirror private registries using a .start file.

The file path and example provisioning script are provided below. After you have created the file with the appropriate configuration, restart the Rancher Desktop application for the provisioning script to take effect.

.start File Path: $HOME\AppData\Roaming\rancher-desktop\provisioning\mirror-registry.start

Example Script:

#!/bin/sh

set -eux

mkdir -p /etc/rancher/k3s

cat <<EOF >/etc/rancher/k3s/registries.yaml
mirrors:
  "localhost:5000":
  endpoint:
    - http://localhost:5000
EOF

Verify using the rdctl shell command below that the script is applied:

rdctl shell -- cat /etc/rancher/k3s/registries.yaml