여기서는 멈추세요
- 명령 출력의 서버·서비스·경로가 예상 대상과 다르면 변경 단계로 넘어가지 않습니다.
- 현재 접속 세션, 백업 또는 콘솔 복구 경로를 확보하지 못했다면 상태 변경 명령을 실행하지 않습니다.
CONTAINER NETWORK
Docker 컨테이너 네트워크와 DNS가 실패할 때
호스트와 컨테이너의 네트워크 namespace, DNS 설정, 사용자 정의 네트워크와 포트 공개를 차례로 비교합니다.Docker DNScontainer network127.0.0.11port mappingname resolution
환경Docker Engine on Linux · bridge·user-defined network
분류컨테이너
검토일2026-08-27
진행5단계 · 조회 우선
SAFE OPERATING BOUNDARY
중단·복구 기준부터 확인하세요
복구 기준
변경 전 설정과 출력값을 기록하고, 예상과 다른 결과가 나오면 추가 변경을 멈춘 뒤 승인된 운영 복구 절차로 되돌립니다.
담당자에게 전달할 자료
- 장애 발생 시각·정상화 시각과 원문 오류 메시지
- 민감정보를 제거한 조회 명령 출력과 변경 전후 차이
- 조치 후 동일 조건으로 수행한 재검증 결과
BEFORE YOU START
이런 증상에서 시작합니다
- 호스트에서는 되지만 컨테이너에서만 통신 실패
- 서비스 이름 DNS 조회 실패
- published port 외부 접근 실패
- 컨테이너에서 host 127.0.0.1 접근 실패
CHECK THE BRANCH
놓치기 쉬운 원인 분기
127.0.0.1 오해
컨테이너의 loopback은 호스트가 아니라 그 컨테이너 자신입니다.
기본 bridge
기본 bridge는 사용자 정의 네트워크와 이름 기반 서비스 탐색 동작이 다릅니다.
포트 공개
컨테이너 내부 포트가 LISTEN이어도 -p/ports로 공개하지 않으면 외부에서 접근할 수 없습니다.
FOLLOW THE FLOW
순서대로 확인하기
조회시스템을 변경하지 않는 확인 단계
호스트 통신을 기준선으로 확인
먼저 호스트 자체의 DNS와 HTTPS 연결이 정상인지 확인합니다.
호스트 DNS
getent ahosts example.com호스트 HTTPS
curl -I --max-time 10 https://example.com/결과 읽기
호스트도 실패하면 Docker보다 호스트 DNS·라우팅 문제를 먼저 해결합니다.
다음 판단
호스트가 성공할 때만 컨테이너 namespace 비교로 이동합니다.
조회시스템을 변경하지 않는 확인 단계
컨테이너 네트워크와 DNS 설정 확인
CONTAINER_NAME을 실제 값으로 바꿉니다.
연결 네트워크
docker inspect --format '{{json .NetworkSettings.Networks}}' CONTAINER_NAME지정 DNS 옵션
docker inspect --format '{{json .HostConfig.Dns}}' CONTAINER_NAME컨테이너 resolv.conf
docker exec CONTAINER_NAME cat /etc/resolv.conf결과 읽기
사용자 정의 네트워크는 Docker embedded DNS 127.0.0.11을 사용할 수 있으며 외부 조회는 업스트림으로 전달됩니다.
다음 판단
예상한 네트워크 이름과 DNS 서버가 적용됐는지 확인합니다.
조회시스템을 변경하지 않는 확인 단계
컨테이너 안에서 이름과 주소를 분리 테스트
이미지에 getent나 wget이 없을 수 있으며 이를 이유로 운영 이미지에 도구를 설치하지 않습니다.
서비스 이름 조회
docker exec CONTAINER_NAME getent hosts SERVICE_NAME외부 이름 조회
docker exec CONTAINER_NAME getent ahosts example.com결과 읽기
외부 이름만 실패하면 업스트림 DNS, 서비스 이름만 실패하면 네트워크 연결·alias를 확인합니다.
다음 판단
실패 범위를 외부 DNS와 컨테이너 간 서비스 탐색으로 구분합니다.
조회시스템을 변경하지 않는 확인 단계
네트워크·포트 공개와 방화벽 확인
NETWORK_NAME과 CONTAINER_NAME을 실제 값으로 바꿉니다.
네트워크 상세
docker network inspect NETWORK_NAME공개 포트
docker port CONTAINER_NAME호스트 LISTEN
sudo ss -lntp결과 읽기
컨테이너가 같은 사용자 정의 네트워크에 연결됐는지, HostIp가 127.0.0.1로 제한됐는지 확인합니다.
다음 판단
Docker가 만드는 방화벽 규칙을 임의 삭제하지 말고 Compose 설정과 정책을 먼저 수정합니다.
변경데이터·서비스 상태가 달라질 수 있는 단계
Compose 설정을 검증하고 대상 서비스만 재생성
네트워크·DNS·ports 설정을 수정했다면 전체 stack이 아니라 영향받는 서비스만 반영합니다.
변경 단계입니다. 실행 전 대상 이름과 경로, 서비스 중단 영향, 복구 방법을 다시 확인하세요.
Compose 최종 설정
docker compose config대상 서비스 반영
docker compose up -d SERVICE_NAME반영 후 DNS 확인
docker exec CONTAINER_NAME getent hosts SERVICE_NAME결과 읽기
컨테이너가 원하는 네트워크에 연결되고 DNS 조회와 실제 포트 연결이 모두 성공해야 합니다.
다음 판단
재발하면 daemon DNS, VPN·프록시와 호스트 방화벽을 함께 점검합니다.
PRIMARY REFERENCES
공식 문서
배포판과 버전에 따라 옵션·로그 위치가 다를 수 있습니다. 실행 전 서버의 --help와 로컬 매뉴얼을 함께 확인하세요.