Docker 네트워크 오류 해결: 프록시(Proxy) 설정 방법

안녕하세요. 미뇽입니다.

회사나 보안이 중요한 기관의 네트워크 환경에서 개발하다 보면 종종 마주치는 장벽이 있습니다. 바로 ‘프록시(Proxy)’ 서버인데요. 내부망에서 외부 인터넷으로 접속할 때 반드시 이 프록시를 거치도록 설정된 경우가 많습니다. 이때, Docker 역시 예외는 아닙니다. 프록시 설정을 해주지 않으면 docker pull 명령어로 이미지를 내려받거나 컨테이너 내부에서 외부 API를 호출할 때 네트워크 오류가 발생하여 당황하게 되죠.

오늘은 Docker 사용자들이 자주 마주치는 문제 중 하나인 이 ‘프록시(Proxy) 설정’에 대해 알아보겠습니다. 왜 프록시 설정이 필요하고, 설정하지 않았을 때 어떤 오류들이 발생하는지, 그리고 가장 중요한 해결 방법까지 단계별로 쉽게 설명해 드리겠습니다.

Table of Contents

왜 Docker에 프록시 설정이 필요할까요?

프록시 서버는 내부 네트워크와 외부 인터넷 사이의 중계자 역할을 합니다. 보안 정책에 따라, 내부의 모든 컴퓨터는 이 중계자, 즉 프록시 서버를 통해서만 외부와 통신할 수 있습니다.

Docker 역시 외부의 Docker Hub와 같은 이미지 레지스트리에서 이미지를 다운로드하거나, 컨테이너가 외부 네트워크와 통신하기 위해서는 이 프록시 서버를 통과해야 합니다. 하지만 Docker는 기본적으로 프록시 서버의 존재를 알지 못하므로, 우리가 직접 Docker에게 “외부와 통신할 때는 이 프록시 서버를 이용해!”라고 알려주는 과정이 필요합니다. 이 과정이 바로 ‘Docker 프록시 설정’입니다.

프록시 미설정 시 흔히 마주하는 오류들

만약 프록시 환경에서 Docker에 아무런 설정을 하지 않고 docker pull과 같은 명령어를 실행하면 어떻게 될까요? Docker는 프록시를 무시하고 외부 네트워크(예: registry-1.docker.io)에 직접 접속을 시도하다가 방화벽이나 네트워크 정책에 의해 차단되어 다음과 같은 오류들을 뱉어냅니다.

연결 시간 초과(Timeout) 오류:

Error response from daemon: Get https://registry-1.docker.io/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers)

이 메시지는 Docker가 외부 레지스트리에 연결을 시도했지만, 정해진 시간 내에 응답을 받지 못해 연결을 스스로 취소했다는 의미입니다.

연결 초기화(Connection Reset) 오류:

Error response from daemon: Get https://registry-1.docker.io/v2/: read tcp 192.168.0.1:8585->34.205.13.154:443: read: connection reset by peer

이 메시지는 연결이 설정되기는 했으나, 중간의 네트워크 장비(주로 방화벽이나 프록시)에 의해 강제로 연결이 끊어졌음을 의미합니다.

이러한 오류들을 마주했다면, Docker에 프록시 설정이 필요하다는 강력한 신호입니다.

Docker 프록시 설정 방법 (두 가지 핵심 방법)

Docker에서 프록시를 설정하는 방법은 크게 두 가지가 있습니다. 시스템의 Docker 서비스 환경 변수를 직접 설정하는 방법과 Docker 데몬의 공식 설정 파일(daemon.json)을 이용하는 방법입니다. Docker에서는 두 번째 방법인 daemon.json 사용을 권장하지만, 환경에 따라 두 가지 방법 모두 알아두면 유용합니다.

방법 1: Docker 서비스 파일(`http-proxy.conf`) 수정

이 방법은 systemd를 사용하는 리눅스 시스템에서 Docker 서비스 자체의 환경 변수를 설정하는 방식입니다.

설정 파일 디렉토리 생성 (없는 경우)먼저, 설정 파일을 저장할 디렉토리가 없다면 생성해 줍니다.

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

프록시 설정 파일 생성 및 편집http-proxy.conf 파일을 생성하고 프록시 정보를 입력합니다.

sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

파일 내용에 아래와 같이 프록시 정보를 입력합니다. proxy.example.com:8080 부분은 실제 사용하는 프록시 서버 주소와 포트로 변경해야 합니다.

[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,docker-registry.example.com"

HTTP_PROXY: HTTP 통신에 사용할 프록시 서버 주소
HTTPS_PROXY: HTTPS 통신에 사용할 프록시 서버 주소 (보통 HTTP 프록시와 동일)
NO_PROXY: 프록시를 거치지 않고 직접 통신할 호스트 주소 목록입니다.
내부망에 있는 Docker 레지스트리나 localhost 등은 프록시를 통과하면 오히려 접속이 안 될 수 있으므로 여기에 등록해 줍니다.

방법 2: Docker Daemon 설정 파일(`daemon.json`) 사용 (권장)

이 방법은 Docker가 공식적으로 권장하는 방식으로, Docker 데몬에 대한 설정을 JSON 형식으로 관리합니다.

설정 파일 생성 및 편집/etc/docker/daemon.json 파일을 열어 편집합니다. 파일이 없다면 새로 생성됩니다.

sudo nano /etc/docker/daemon.json

프록시 정보 입력아래와 같이 JSON 형식에 맞춰 프록시 정보를 입력합니다. 마찬가지로 프록시 주소는 실제 환경에 맞게 변경합니다.

{
  "proxies":
  {
    "default":
    {
      "httpProxy": "http://proxy.example.com:80",
      "httpsProxy": "http://proxy.example.com:443",
      "noProxy": "localhost,127.0.0.1,docker-registry.example.com"
    }
  }
}

이미 daemon.json 파일에 다른 설정이 있다면, 위 proxies 객체를 기존 내용에 맞게 추가해 주면 됩니다.

설정 적용 및 재시작

위 두 가지 방법 중 하나로 설정을 완료했다면, 변경 사항을 시스템에 적용하고 Docker 서비스를 재시작해야 합니다.

아래 명령어를 순서대로 실행합니다.

# 1. systemd 설정 리로드
sudo systemctl daemon-reload

# 2. Docker 서비스 재시작
sudo systemctl restart docker

daemon-reload는 systemd 서비스 파일의 변경 사항을 인식하도록 하는 명령어이며, restart docker는 Docker 서비스를 재시작하여 새로운 설정을 적용하는 명령어입니다.

프록시 설정 확인하기

마지막으로 설정이 올바르게 적용되었는지 확인하는 것이 중요합니다.

서비스 환경 변수 확인 (방법 1 사용 시)

아래 명령어로 Docker 서비스에 환경 변수가 잘 설정되었는지 확인할 수 있습니다.

systemctl show --property Environment docker

결과로 Environment=HTTP_PROXY=http://proxy.example.com:8080/와 같이 설정한 내용이 출력되면 성공입니다.

실제 동작 확인가장 확실한 방법은 이전에 실패했던 Docker 명령어를 다시 실행해 보는 것입니다.

docker pull hello-world

위 명령어가 오류 없이 성공적으로 이미지를 받아온다면, 프록시 설정이 완벽하게 적용된 것입니다.

마치며

오늘은 회사와 같은 프록시 네트워크 환경에서 Docker를 사용할 때 필수적인 ‘프록시 설정’ 방법에 대해 알아보았습니다. 처음에는 낯선 오류 메시지에 당황할 수 있지만, 원리를 이해하고 올바른 방법으로 설정을 적용하면 문제는 간단히 해결될 수 있습니다.

이 가이드를 통해 Docker가 네트워크 제약 없이 다양한 리소스에 자유롭게 접근하여 여러분의 개발과 운영을 더욱 원활하게 만들어 주기를 바랍니다.

읽어주셔서 감사합니다. 🙂