Private Registries
Configure registries.yaml so k3s can pull images from private or mirrored registries.
Syntax
/etc/rancher/k3s/registries.yamlBy default k3s pulls images from public registries like Docker Hub. To use a private registry or a local mirror, create a registries.yaml file that k3s reads at startup.
What it can do
- Provide credentials for authenticated registries.
- Mirror a public registry through a local cache.
- Point at a registry using a custom or self-signed TLS certificate.
The file lives at /etc/rancher/k3s/registries.yaml on each node that needs it, and k3s must be restarted to pick up changes.
Example
# /etc/rancher/k3s/registries.yaml
mirrors:
registry.internal:5000:
endpoint:
- "https://registry.internal:5000"
configs:
registry.internal:5000:
auth:
username: deploy
password: s3cret
tls:
ca_file: /etc/ssl/certs/internal-ca.crtWhen to use it
- A team configures k3s to pull images from an on-prem Harbor registry so pods never make external requests to Docker Hub.
- An operator adds authentication credentials for AWS ECR in registries.yaml so k3s nodes can pull private images without manual docker login.
- An air-gapped deployment uses a local registry mirror defined in registries.yaml to serve images cached from an external source.
More examples
Configure a private registry
Tells k3s to mirror Docker Hub pulls through an internal registry and provides credentials for authentication.
# /etc/rancher/k3s/registries.yaml
mirrors:
docker.io:
endpoint:
- 'https://registry.example.com'
configs:
'registry.example.com':
auth:
username: admin
password: s3cr3tAdd TLS config for insecure registry
Allows k3s to pull from a local registry using a self-signed certificate by skipping TLS verification.
# /etc/rancher/k3s/registries.yaml
configs:
'192.168.1.50:5000':
tls:
insecure_skip_verify: trueReload and verify registry config
Restarts k3s to apply the registries.yaml changes, then runs a test pod to confirm the private image can be pulled.
systemctl restart k3s
journalctl -u k3s -n 20 | grep -i registry
kubectl run test --image=registry.example.com/myapp:latest --restart=Never
Discussion