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
  • macOS
  • Windows

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:

  1. provision:
  2.   - mode: system
  3.     script: |
  4.       #!/bin/sh
  5.       set -eux
  6.       mkdir -p /etc/rancher/k3s
  7.       cat <<EOF >/etc/rancher/k3s/registries.yaml
  8.       mirrors:
  9.         "<my.private.registry>:5000":
  10.           endpoint:
  11.           - http://<my.private.registry>:5000
  12.       EOF

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

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

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:

  1. provision:
  2.   - mode: system
  3.     script: |
  4.       #!/bin/sh
  5.       set -eux
  6.       mkdir -p /etc/rancher/k3s
  7.       cat <<EOF >/etc/rancher/k3s/registries.yaml
  8.       mirrors:
  9.         "<my.private.registry>:5000":
  10.           endpoint:
  11.           - http://<my.private.registry>:5000
  12.       EOF

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

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

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:

  1. #!/bin/sh
  3. set -eux
  5. mkdir -p /etc/rancher/k3s
  7. cat <<EOF >/etc/rancher/k3s/registries.yaml
  8. mirrors:
  9.   "localhost:5000":
  10.   endpoint:
  11.     - http://localhost:5000
  12. EOF

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

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