Docker Proxy Configuration: Resolving registry-1.docker.io: no such host Error

Problem Background and Error Analysis

When running Docker on Ubuntu 17.04 systems, users encounter connection errors after executing the docker run hello-world command. The error message shows: docker: Error response from daemon: Get https://registry-1.docker.io/v2/: dial tcp: lookup registry-1.docker.io: no such host. This error indicates that the Docker daemon cannot resolve the registry-1.docker.io domain name, typically occurring in corporate network environments where the Docker daemon lacks proper proxy configuration.

Docker Architecture and Proxy Configuration Mechanism

Docker employs a client-server architecture where the docker command-line tool acts as the client, while dockerd runs as a background daemon. When users execute docker run commands, if the specified image doesn't exist locally, the client sends a pull request to the daemon. The daemon handles actual network communication, including HTTPS connections to Docker Registry.

The critical issue is: although users set http_proxy and https_proxy environment variables in their shell environment, these variables only affect the client process. The Docker daemon runs as a system service and requires independent proxy configuration. This explains why the daemon cannot access external networks even when the client is properly configured.

System-Level Proxy Configuration Solution

The optimal solution involves configuring proxies for the Docker daemon through systemd service configuration. Here are the detailed steps:

First, create the systemd override directory and configuration file. This directory allows users to provide custom configurations for system services without modifying original service files:

sudo mkdir -p /etc/systemd/system/docker.service.d

Next, create the proxy configuration file. Use a text editor to create /etc/systemd/system/docker.service.d/10_docker_proxy.conf:

[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080/"
Environment="HTTPS_PROXY=http://proxy.example.com:8080/"
Environment="NO_PROXY=localhost,127.0.0.1,.localdomain.com"

Note: Replace proxy.example.com:8080 with the actual corporate proxy server address and port. If the proxy requires authentication, the format should be: http://username:password@proxy.example.com:8080/. The NO_PROXY environment variable specifies addresses that shouldn't go through the proxy, which is particularly important for local development environments.

After configuration, reload systemd configuration and restart the Docker service:

sudo systemctl daemon-reload
sudo systemctl restart docker

Verify that the configuration has been loaded:

sudo systemctl show --property=Environment docker

This command displays all environment variables for the Docker service, confirming that proxy settings are correctly loaded.

Alternative Solution Analysis

Besides the optimal solution above, several other configuration methods exist:

DNS Configuration Solution: When domain name resolution fails, Docker can be configured to use specific DNS servers. Edit the /etc/docker/daemon.json file (create it if it doesn't exist):

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Then restart the Docker service. This method addresses DNS resolution issues in network environments but cannot solve proxy authentication requirements.

Traditional Environment Variable Configuration: For systems using SysVinit, edit the /etc/default/docker file:

export http_proxy='http://proxy.example.com:8080'
export https_proxy='http://proxy.example.com:8080'

Then restart the Docker service. This method may be less reliable than service override configuration in modern systemd systems.

Simple Restart Solution: In some cases, a simple service restart might resolve temporary network connection issues:

sudo systemctl restart docker

However, this typically only works for occasional problems and has limited effectiveness for persistent proxy configuration issues.

Configuration Verification and Troubleshooting

After completing proxy configuration, comprehensive testing should be performed:

1. Test basic network connectivity: docker run --rm alpine ping -c 3 8.8.8.8
2. Test DNS resolution: docker run --rm alpine nslookup registry-1.docker.io
3. Test image pulling: docker pull hello-world
4. Complete run test: docker run hello-world

If problems persist, check the following aspects:

• Whether proxy server address and port are correct
• Whether the proxy server requires authentication
• Whether firewall allows outbound connections from Docker daemon
• Error messages in system logs: sudo journalctl -u docker.service

Security and Best Practice Recommendations

When configuring Docker proxies in enterprise environments, consider the following security practices:

1. Use the principle of least privilege: If proxies require authentication, consider creating dedicated service accounts rather than using personal credentials.

2. Configure NO_PROXY: Properly set the NO_PROXY environment variable to avoid routing internal services through external proxies:

Environment="NO_PROXY=localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16,.internal.company.com"

3. Regular configuration updates: Review and update proxy configurations periodically as network environments change.

4. Document configurations: Incorporate proxy configurations into Infrastructure as Code (IaC) management to ensure environment consistency.

By correctly configuring proxy settings for the Docker daemon, organizations can ensure stable use of Docker container technology in corporate network environments while maintaining compliance with network policies and security requirements.