Docker DNS 오류 해결: Temporary failure in name resolution·서비스 이름·VPN 점검

AI로 직접 제작한 개념 일러스트입니다. 내부 서비스 이름과 외부 도메인 조회 실패를 별도 경로로 나누어 진단합니다.

Docker 컨테이너에서 “Temporary failure in name resolution”, “Could not resolve host”, “getaddrinfo EAI_AGAIN”이 보이나요? DNS 오류라고 해서 공용 DNS 주소를 바로 덮어쓰는 것은 해결 순서가 아닙니다. Compose 서비스 이름이 안 풀리는지, 외부 도메인이 안 풀리는지, 이름은 풀렸지만 포트 연결이 실패하는지를 나누어 확인하면 문제 범위를 좁힐 수 있습니다.

1. 오류가 발생한 이름과 실행 위치를 먼저 기록하기

호스트 터미널에서 성공한 이름 조회가 컨테이너 안에서도 성공한다는 보장은 없습니다. 컨테이너의 네트워크·리졸버 경로를 따로 확인해야 합니다. 같은 URL이라도 앱 컨테이너, 빌드 단계, CI 작업 중 어느 위치에서 실패했는지 먼저 적으세요. 이 글은 실행 중인 Linux 컨테이너와 Compose의 사용자 정의 네트워크를 중심으로 설명하며, 빌드·호스트 네트워크 모드에는 별도 조건이 있습니다.

db처럼 같은 Compose 프로젝트의 서비스 이름과 api.example.com처럼 외부 또는 사내 도메인은 진단 경로가 다릅니다. Docker 네트워크와 DNS 공식 안내는 기본 bridge와 사용자 정의 네트워크의 DNS 동작을 구분합니다. 사용자 정의 네트워크의 127.0.0.11은 Docker 내장 DNS 경로이므로 그 값이 보인다는 사실만으로 오류라고 판단하지 마세요.

localhost와 포트의 의미가 헷갈리면 Docker 컨테이너 간 연결·포트 설명을 먼저 확인하세요. 공개 도메인 자체의 이름 서버 문제가 의심된다면 NXDOMAIN 도메인 진단 글로 별도 확인합니다.

2. 증상에 따른 진단 분기표

관찰한 증상	먼저 확인할 경로	구분할 다음 문제
db 등 서비스 이름만 실패	두 서비스의 공통 네트워크·이름·별칭	서로 다른 Compose 프로젝트 또는 network_mode
외부 도메인만 실패	컨테이너 리졸버·호스트 DNS·VPN 경로	DNS 서버 접근·사내 분할 DNS
NXDOMAIN 응답	정확한 이름·조회 서버·검색 도메인	이름 부재 응답과 시간 초과의 차이
이름 조회는 성공, 연결은 실패	해석된 주소·컨테이너 포트·라우팅	프로그램 대기 상태·방화벽·TLS
재생성 후에만 앱 오류	서비스 재조회·앱 DNS 캐시·재연결	고정 IP 또는 오래 유지된 연결
호스트도 이름 조회 실패	호스트 또는 조직 DNS·VPN 상태	Docker 이전의 공통 장애

DNS 서버가 응답하지 않는 것과 “그 이름이 없다”라는 NXDOMAIN 응답은 다릅니다. 시간 초과에만 맞춘 재시도를 NXDOMAIN에도 적용하면 잘못된 이름 문제를 가릴 수 있습니다. DNS 결과를 확인한 다음에 포트 연결·HTTP·TLS 단계로 넘어가세요. ping 실패 하나로 이름 해석과 모든 네트워크 접근을 동시에 판정하지 않습니다.

3. 실행 중인 컨테이너에서 읽기 위주로 점검하기

아래는 app·db라는 서비스가 있는 설명용 예시입니다. 실제 서비스 이름과 조회 권한에 맞춰 사용합니다. 파일 내용을 바꾸거나 서비스 전체를 재시작하지 않습니다. docker compose exec 문서의 exec는 실행 중 컨테이너에서 명령을 수행합니다. 이미지에 cat·getent·nslookup이 설치돼 있지 않으면 명령 부재를 DNS 실패로 해석하지 마세요.

docker compose ps
docker compose exec -T app cat /etc/resolv.conf
docker compose exec -T app getent hosts db
docker compose exec -T app getent hosts example.com

리졸버 파일에서 서버·검색 도메인을 기록하고 내부 서비스와 외부 이름을 각각 비교합니다. example.com은 설명용 외부 도메인이며 운영 API의 실제 이름을 대신 검증하지 않습니다. 진단 결과에 사내 도메인·IP가 포함될 수 있으므로 필요한 부분만 공유하세요. getent가 없고 승인된 진단 도구가 있다면 같은 이름을 해당 도구로 조회하되 도구의 동작 차이도 기록합니다.

docker compose ps -q app
docker inspect --format "{{json .NetworkSettings.Networks}}" APP_CONTAINER_ID
docker inspect --format "{{json .NetworkSettings.Networks}}" DB_CONTAINER_ID

APP_CONTAINER_ID와 DB_CONTAINER_ID는 실제 컨테이너 ID로 바꿉니다. 전체 inspect 출력에는 불필요한 설정이 포함될 수 있어 위 예시는 네트워크 항목만 조회합니다. 두 서비스에 공통 네트워크가 있는지 확인하고 Compose 네트워킹 안내에 따라 서비스 이름과 연결 경로를 대조하세요. 같은 머신에서 실행 중인 컨테이너라는 사실만으로 같은 네트워크라고 볼 수 없습니다.

4. 127.0.0.11과 사내 DNS를 혼동하지 않기

기본 bridge의 리졸버 설정 복사와 사용자 정의 네트워크의 내장 DNS 전달은 다른 경로입니다. 또한 컨테이너에서 127.0.0.1은 컨테이너 자신의 루프백 주소입니다. 호스트의 로컬 리졸버 주소를 그대로 넣으면 컨테이너에 없는 DNS 서버를 바라보게 될 수 있습니다. Docker 데몬 DNS 문제 해결 안내에서 로컬 캐시 DNS와 컨테이너 접근 범위를 구분합니다.

사내 VPN에서만 해석되는 이름은 승인된 조직 DNS와 그 서버로 가는 경로가 필요할 수 있습니다. 공용 DNS로 강제 전환하면 외부 사이트는 열려도 사내 이름은 계속 실패할 수 있습니다. VPN 재연결 전후에 호스트·컨테이너에서 같은 이름과 조회 대상을 비교하고, Desktop·VPN·조직 네트워크의 지원 설정을 확인하세요. 보안 설정을 해제하거나 전역 방화벽을 끄는 방식으로 문제를 덮지 않습니다.

5. 원인에 맞게 수정하고 같은 조건으로 재검수하기

• 내부 이름 실패: 서비스 이름·별칭·공통 네트워크를 확인하고 필요한 연결만 수정한다.
• 외부·사내 이름 실패: 승인된 DNS 서버의 접근성과 VPN 전달 경로를 확인한다.
• 이름은 정상인데 접속 실패: 컨테이너 포트와 앱 대기 상태·TLS를 별도로 진단한다.
• 재생성 뒤 실패: 고정 IP 의존을 없애고 앱의 이름 재조회·재연결 동작을 확인한다.
• 수정 후 내부 이름과 실제 외부 대상, DNS 응답과 애플리케이션 요청을 다시 나누어 확인한다.

Compose 설정을 바꿨다면 어떤 서비스 재생성이 필요한지 검토하고 데이터 저장 위치와 영향 범위를 확인한 뒤 적용합니다. 컨테이너 내부 resolv.conf를 수동 수정해 일시적으로 해결됐다는 사실만으로 재생성 후에도 유지되는 해결책이라고 판단하지 않습니다. 이 글의 명령은 제시용이며 실제 환경에서 실행한 성공 결과를 주장하지 않습니다.

6. 자주 묻는 질문

127.0.0.11을 공용 DNS로 바꾸면 되나요?
사용자 정의 네트워크의 정상 내장 DNS 주소일 수 있습니다. 서비스 이름 경로와 외부 전달 경로부터 구분하세요.

호스트에서는 되는데 컨테이너에서 안 되면 Docker 버그인가요?
리졸버·VPN·네트워크·앱 DNS 캐시 등 여러 경로가 다를 수 있습니다. 동일 이름과 실행 위치를 비교한 증거가 필요합니다.

IP로 연결하면 해결된 것인가요?
이름 해석을 건너뛴 진단일 수 있습니다. 재생성 시 주소 변경과 HTTPS 호스트 검증 문제가 남으므로 고정 IP를 최종 해결책으로 바로 채택하지 마세요.

공식 자료 확인 기준: 2026-10-06. 예시와 계산은 설명용이며 실제 실행 결과·요금 견적이 아닙니다.

공식 출처와 함께 확인하기

• Docker 네트워크와 DNS 공식 안내
• Compose 네트워킹 안내
• docker compose exec 문서
• Docker 데몬 DNS 문제 해결 안내