Configure an image accelerator-Container Registry(ACR)-阿里云帮助中心

Pulls from Docker Hub can be slow or fail due to ISP network issues. Container Registry (ACR) provides an official image accelerator to speed up these downloads.

Important

The ACR image accelerator no longer syncs the latest images. If you cannot pull an image, or if an image pulled using the latest tag is not the most recent version, consider the following alternatives:
- Subscribe to overseas source images using Container Registry. For instructions, see Sync images by using artifact subscription.
- Create a Global Accelerator (GA) instance to pull images directly using its global acceleration network. For details, see Accelerate cross-region ACK image pulls with GA.
The image accelerator is intended for personal development scenarios only. It must not be repackaged or used for commercial purposes.
In a production environment, to avoid image pull failures caused by Docker network access issues, carefully consider your dependency on container images from Docker Hub.
The accelerator does not support browsing the list of image tags. To view available tags, visit the official Docker Hub website.

Step 1: Obtain the accelerator endpoint

Container Registry generates an image accelerator endpoint for each Alibaba Cloud account or RAM user. Before you configure an image accelerator, you must obtain its endpoint.

Log on to the Container Registry console.
In the left-side navigation pane, choose Image Tool > Image Accelerator.
On the Image Accelerator page, find and copy the Accelerator endpoint.

Step 2: Configure the image accelerator

Configuration differs between Docker and containerd. Choose the configuration method that matches your runtime.

Docker runtime

You can first use docker --version to check your Docker version, and then choose a different configuration method based on the version.

Modern Docker (1.10 or later)

Create and edit the /etc/docker/daemon.json file:

{
    "registry-mirrors": ["<your accelerator endpoint>"]
}

Then, restart the Docker daemon.

Older Docker versions

Modify the configuration file for your operating system.

Ubuntu 12.04 - 14.04

On Ubuntu, the configuration file is located at /etc/default/docker. Add the accelerator configuration to this file and restart Docker.

echo "DOCKER_OPTS=\"\$DOCKER_OPTS --registry-mirror=<your accelerator endpoint>\"" | sudo tee -a /etc/default/docker
sudo service docker restart

Ubuntu 15.04 - 15.10

On Ubuntu, the configuration directory is /etc/systemd/system/docker.service.d/. Create any *.conf file in this directory as a configuration file. Add the accelerator configuration to the file and restart Docker.

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo tee /etc/systemd/system/docker.service.d/mirror.conf <<-'EOF'
[Service]
ExecStart=
ExecStart=/usr/bin/docker daemon -H fd:// --registry-mirror=<your accelerator endpoint>
EOF
sudo systemctl daemon-reload
sudo systemctl restart docker

CentOS 7

On CentOS, the configuration is slightly more complex. First, copy the default configuration file from /lib/systemd/system/docker.service to /etc/systemd/system/docker.service. Then, add the accelerator endpoint to the startup command in the configuration file and restart Docker.

sudo cp -n /lib/systemd/system/docker.service /etc/systemd/system/docker.service
sudo sed -i "s|ExecStart=/usr/bin/docker daemon|ExecStart=/usr/bin/docker daemon --registry-mirror=<your accelerator endpoint>|g" /etc/systemd/system/docker.service
sudo sed -i "s|ExecStart=/usr/bin/dockerd|ExecStart=/usr/bin/dockerd --registry-mirror=<your accelerator endpoint>|g" /etc/systemd/system/docker.service
sudo systemctl daemon-reload
sudo service docker restart

Red Hat 7

To configure an accelerator for Red Hat 7, edit the /etc/sysconfig/docker configuration file. In the OPTIONS option, add the accelerator configuration --registry-mirror=<your accelerator address>. Finally, run the sudo service docker restart command to restart the Docker Daemon.
Red Hat 6/CentOS 6

You cannot directly install Docker on these systems. You must upgrade the kernel first.

To configure the accelerator, edit the /etc/sysconfig/docker configuration file. In the other_args parameter, add the accelerator configuration --registry-mirror=<your_accelerator_address>. Finally, run the sudo service docker restart command to restart the Docker daemon.
Docker Toolbox (for Windows and macOS)

If you use Docker Toolbox on Windows or macOS, we recommend that you configure the accelerator endpoint when you create the Linux virtual machine.
```
docker-machine create --engine-registry-mirror=<your accelerator endpoint> -d virtualbox default
docker-machine env default
eval "$(docker-machine env default)"
docker info            
```
If you already created a virtual machine with docker-machine, log on to it to modify the configuration.
1. Run the docker-machine ssh <machine-name> command to log in to the virtual machine.
2. Modify the /var/lib/boot2docker/profile file and add --registry-mirror=<your accelerator address> to EXTRA_ARGS.
3. Run the sudo /etc/init.d/docker restart command to restart the Docker service.

Containerd runtime

Containerd uses /etc/containerd/config.toml as its default configuration file path at startup. If you use a different path, you can make adjustments accordingly.

Ensure that the configuration file contains config_path.

Run the following command to check if the default configuration file contains the config_path configuration (for example, "/etc/containerd/cert.d").
```
cat /etc/containerd/config.toml |grep config_path -C 5
```
If this setting does not exist, add the following configuration to the file.

Note
If [plugins."io.containerd.grpc.v1.cri".registry] already exists, you only need to add config_path under it. Pay attention to the indentation. If it does not exist, you can add it anywhere.
```
   [plugins."io.containerd.grpc.v1.cri".registry]
     config_path = "/etc/containerd/certs.d"
```
Check the mirror configurations.

You can use the cat /etc/containerd/config.toml | grep mirror -C 5 command to check if the configuration file contains any configurations related to mirror. If any exist, remove them to avoid conflicts.
```
[plugins."io.containerd.grpc.v1.cri".registry.mirrors]
  [plugins."io.containerd.grpc.v1.cri".registry.mirrors."docker.io"]
    endpoint = ["https://registry-1.docker.io"]
```
If you modify a mirror-related configuration, run the following command to restart containerd.
```
systemctl restart containerd
```
If containerd fails to start, run the following command to check for errors. Failures are often caused by configuration conflicts. Adjust your configuration based on the error messages.
```
journalctl -u containerd
```
Create the image accelerator configuration file.

Create a docker.io/hosts.toml file with the following content in the directory specified by config_path. The path of the created file is /etc/containerd/certs.d/docker.io/hosts.toml.
```
server = "https://registry-1.docker.io"

[host."<your accelerator endpoint, such as https://xxx.mirror.aliyuncs.com>"]
  capabilities = ["pull", "resolve", "push"]
```
Pull a Docker image to verify that acceleration is working. If it is not, see Reference.

FAQ

HTTP 403 error when pulling images

The accelerator endpoint allows access only from ECS instances. Accessing it from a non-Alibaba Cloud environment results in an HTTP 403 error. To pull Docker Hub images in a non-Alibaba Cloud environment, use the artifact subscription feature of Container Registry to obtain the required images.