Docker pull 시 간헐적으로 발생하는 TLS handshake timeout 오류 해결 방법
Docker를 사용하다 보면 이미지를 pull할 때 간헐적으로 'TLS handshake timeout' 오류를 마주치는 경우가 있습니다. 이 글에서는 이 오류의 원인과 다양한 해결 방법에 대해 알아보겠습니다.
1. 오류 증상
주로 다음과 같은 오류 메시지가 나타납니다:
error pulling image configuration: Get https://registry-1.docker.io/v2/: net/http: TLS handshake timeout이 오류는 Docker 이미지를 pull하는 과정에서 레지스트리와의 TLS 핸드셰이크가 시간 내에 완료되지 않을 때 발생합니다[1].
2. 주요 원인
- 네트워크 연결 불안정 또는 속도 저하
- 프록시 설정 문제
- 방화벽 또는 보안 소프트웨어의 간섭
- Docker 데몬의 설정 문제
- DNS 해결 문제
3. 해결 방법
3.1 네트워크 연결 확인 및 개선
안정적인 인터넷 연결을 확보하세요. 필요한 경우 네트워크 인터페이스를 변경해 보세요[1].
3.2 프록시 설정 확인
프록시를 사용 중이라면, Docker의 프록시 설정이 올바른지 확인하세요[2].
# /etc/systemd/system/docker.service.d/https-proxy.conf
[Service]
Environment="HTTP_PROXY=http://proxy.example.com:8080"
Environment="HTTPS_PROXY=https://proxy.example.com:8080"
Environment="NO_PROXY=localhost,127.0.0.1"
3.3 방화벽 설정 검토
방화벽이 Docker의 네트워크 통신을 차단하고 있지 않은지 확인하세요[3].
3.4 Docker 데몬 재시작
간단하지만 효과적인 방법으로, Docker 데몬을 재시작해 보세요[3].
sudo systemctl restart docker3.5 DNS 설정 확인
DNS 설정이 올바른지 확인하고, 필요한 경우 공용 DNS 서버(예: 8.8.8.8)를 사용해 보세요[1].
3.6 Docker 클라이언트 타임아웃 설정 조정
DOCKER_CLIENT_TIMEOUT 환경 변수를 설정하여 타임아웃 시간을 늘려보세요[3].
export DOCKER_CLIENT_TIMEOUT=1204. 고급 트러블슈팅
- Wireshark나 tcpdump를 사용하여 네트워크 트래픽을 분석해 보세요.
- curl 명령어를 사용하여 Docker 레지스트리에 직접 연결을 시도하고 결과를 분석하세요.
- Docker 로그를 자세히 살펴보고 추가적인 오류 정보를 확인하세요.
결론
Docker pull 시 발생하는 간헐적인 TLS handshake timeout 오류는 대부분 네트워크 관련 문제입니다. 네트워크 연결 상태 개선, 프록시 및 방화벽 설정 검토, Docker 데몬 재시작 등의 방법을 통해 대부분의 경우 해결할 수 있습니다. 문제가 지속될 경우, 네트워크 환경을 자세히 분석하고 필요하다면 Docker 지원팀이나 네트워크 관리자의 도움을 받는 것이 좋습니다.