Pulling cached Docker Hub images | Container Registry documentation

Container Registry is deprecated. After May 15, 2024. Artifact Registry will host images for the gcr.io domain in projects without previous Container Registry usage. If you use Container Registry, learn about the deprecation. To get started with managing containers on Google Cloud, use Artifact Registry.

Starting January 8, 2024, if your organization has not previously used Container Registry, new gcr.io repositories will be hosted on Artifact Registry by default. For more information on this change, see gcr.io hosted on Artifact Registry.

Stay organized with collections Save and categorize content based on your preferences.

Container Registry caches frequently-accessed public Docker Hub images onmirror.gcr.io. You can configure the Docker daemon to use a cached publicimage if one is available, or pull the image from Docker Hub if a cached copyis unavailable.

Google Cloud services such as Cloud Build and Google Kubernetes Engine automaticallycheck for cached images before attempting to pull an image from Docker Hub.

Cached images at mirror.gcr.io are:

Stored in a repository that Google manages.
More insulated from Docker Hub outages.
Easily integrated with the Google Cloud ecosystem.
Kept in sync with Docker Hub.

Configuring the Docker daemon

To configure your Docker daemon to pull images from the Container Registrycache:

CLI

Configure the daemon in one of the following ways:
- To configure the Docker daemon automatically on startup, setthe following value in /etc/docker/daemon.json
```
{ "registry-mirrors": ["https://mirror.gcr.io"]}
```
- When you start the daemon, pass in the Container Registryhostname:
```
dockerd --registry-mirror=https://mirror.gcr.io
```
- Add the following line to your /etc/default/docker file:
```
DOCKER_OPTS="${DOCKER_OPTS} --registry-mirror=https://mirror.gcr.io"
```
Restart the Docker daemon.
- On Linux, run one of the following commands:
```
sudo service docker restart
```
  or
```
sudo service docker stop && sudo service docker start
```
- On macOS or Windows, run the following command:
```
docker-machine restart
```

Docker UI

Open Docker's Preferences menu.
Click Daemon.
Click Advanced. In the JSON field, add a registry-mirrors key withhttps://mirror.gcr.io as a value:
```
{ "registry-mirrors" : [ "https://mirror.gcr.io" ]}
```
Click Apply & Restart.

To verify that the cache is correctly configured, run:

docker system info

The output should include Registry Mirrors, and should look similar tothe following:

Containers: 2 Running: 0 Paused: 0 Stopped: 2Images: 2Server Version: 17.03.1-ceStorage Driver: overlay2 Backing Filesystem: extfs Supports d_type: true Native Overlay Diff: trueLogging Driver: json-file...Registry Mirrors: https://mirror.gcr.io

Pulling cached images

Container Registry adds frequently requested images to the cacheso they are available for future requests. It also periodically removes imagesthat are no longer requested.

After you configure the Docker daemon to use the Container Registry cache,Docker performs the following steps when you pull a public Docker Hub imagewith a docker pull command:

The Docker daemon checks the Container Registry cache and fetchesthe images if it exists. If your daemon configuration includes other Dockermirrors, the daemon checks each one in order for a cached copy of the image.
If the image still isn't found, the Docker daemon fetches the image fromthe canonical repository on Docker Hub.

Pulling cached images does not count against Docker Hub rate limits. However,there is no guarantee that a particular image will remain cached for an extendedperiod of time. Only obtain cached images on mirror.gcr.io byconfiguring the Docker daemon. A request to pull directly frommirror.gcr.io will fail if a cached copy of the image does not exist.

What's next

You can create your own local Docker mirrors to cache images. For details,see theDocker documentation.
Read theDocker Hub documentation.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2024-03-05 UTC.

Pulling cached Docker Hub images | Container Registry documentation | Google Cloud (2024)

Configuring the Docker daemon

CLI

Docker UI

Pulling cached images

What's next