Docker Hub registry mirror

Instruqt hosts a Docker Hub registry mirror to help with rate limits.

Instruqt provides a Docker Hub mirror available at https://docker.registry.instruqt.io/. This can be useful if a track needs to pull a number of images and error messages are being received related to Docker hub rate limits outlined in the docker docs.

Docker Hub's rate limits apply when your workload that is running inside the sandbox environment, pulls images directly from Docker Hub. This happens, for example, when you run a docker pull command or a Kubernetes deployment that fetches an image.

It is generally recommended to pre-pull docker images on VM hosts where possible. This improves the learner experience by having a local cache of the docker images, and reduces the amount of API calls from the sandbox.

There are two ways to use the Docker Hub registry mirror:

1. Use a pre-configured k3s/docker image supplied by Instruqt

2. Setting up the container runtime to use the registry mirror - setup varies by client, transparent to most learners

3. Directly pulling from the mirror - stricter guarantees of image pull location, visible to users

Usage

Use a pre-configured image

The Docker and Kubernetes images in the Add Host page both come pre-configured with the Docker Hub registry mirror.

Setting up the container runtime to use the mirror

The instructions vary depending on the operating system and the container runtime.

General instructions for common runtimes:

• Docker [Community Edition] and dockerd: https://docs.docker.com/docker-hub/image-library/mirror/#configure-the-docker-daemon e.g. adding the mirror to /etc/docker/daemon.json

• containerd - specifically crictl and nerdctl: https://github.com/containerd/containerd/blob/main/docs/hosts.md#registry-configuration---examples e.g. adding an appropriate /etc/containerd/certs.d/docker.io/hosts.toml. ⚠️ctr does not respect the containerd hosts.toml configuration

• k3s - specifically rancher: https://docs.k3s.io/installation/private-registry#mirrors e.g. adding an appropriate /etc/rancher/k3s/registries.yaml with the mirror config.

When editing the configuration settings above, ensure that the relevant service has been restarted.

Testing the mirror varies per tool. A fairly consistent test is as follows:

1. Ensure an image is removed from the runtime: e.g. docker image rm nginx:latest

2. Pull the again: e.g. docker pull nginx:latest

The container mirror is hosted on Google Cloud, so the pull of the container should be very fast (< 1ms when using nginx:latest).

Directly pulling images from the mirror

Pulling images directly from the mirror can be done by prefixing (or replacing docker.io) with the mirror address as follows:

docker pull docker.registry.instruqt.io/library/nginx:latest

It is generally not recommended to create tracks with this substitution, however it might help in pinpointing registry mirror setup issues.

Notes:

• library/ can be omitted, but is generally recommended to be used. This value is generally implied when using Docker CLI.

• The first pull may take slightly longer when added to the cache

FAQ

Are there any usage restrictions?

The container mirror is open for anyone developing tracks on Instruqt.

Instruqt reserves the right to block access to the container mirror if it is being used for purposes not related to Instruqt tracks and/or content creation.

Can I use the container mirror in my Custom VM image?

Yes absolutely! We encourage the usage of this mirror in Custom VM images.

I am getting an unauthorized message when pulling containers

This is likely due to your docker client attempting to authenticate to docker hub. This is not needed when using the container mirror.

Can I use private container images on my own docker hub account?

Not at this time.