could not resolve host 또는 간헐적으로 느린 API 호출 — 애플리케이션 버그처럼 보이지만 클러스터 안에서는 DNS가 원인인 경우가 매우 많습니다. 쿠버네티스에서 모든 이름 해석은 CoreDNS(kube-system 네임스페이스의 Deployment)를 거칩니다. Pod는 clusterIP로 노출된 CoreDNS를 /etc/resolv.conf의 nameserver로 바라봅니다.
먼저 — CoreDNS가 살아 있는지
kubectl get pods -n kube-system -l k8s-app=kube-dns
kubectl logs -n kube-system -l k8s-app=kube-dns --tail=50
CoreDNS Pod가 CrashLoop이거나 로그에 plugin/errors가 쏟아지면 그 자체가 원인입니다. 정상이라면 다음으로 넘어갑니다.
1단계 — Pod 안에서 직접 조회
디버그용 Pod를 띄워 단계별로 끊어 봅니다.
kubectl run dns-test --image=busybox:1.36 --rm -it --restart=Never -- sh
# 클러스터 내부 서비스
nslookup kubernetes.default
# 외부 도메인
nslookup google.com
Server: 10.96.0.10
Address: 10.96.0.10:53
** server can't find google.com: NXDOMAIN
내부는 되는데 외부가 NXDOMAIN이면 CoreDNS의 업스트림 포워딩(forward . /etc/resolv.conf) 설정이나 노드 DNS 문제입니다. 둘 다 안 되면 CoreDNS 연결 자체가 끊긴 것입니다.
2단계 — ndots와 search 도메인 함정
Pod의 /etc/resolv.conf를 보면 보통 options ndots:5가 있습니다. 이는 점(.)이 5개 미만인 이름은 먼저 search 도메인을 붙여 시도하라는 뜻입니다.
search default.svc.cluster.local svc.cluster.local cluster.local
options ndots:5
문제는 api.github.com처럼 점이 2개뿐인 외부 도메인입니다. ndots가 5라 search 도메인을 먼저 다 붙여 api.github.com.default.svc.cluster.local부터 조회하고, 전부 NXDOMAIN으로 실패한 뒤에야 진짜 조회를 합니다. 외부 호출마다 불필요한 조회 4번이 더해져 느려지는 겸형 원인입니다.
원인별 판단
| 증상 | 원인 | 대응 |
|---|---|---|
| 내부·외부 전부 실패 | CoreDNS Pod 죽음/네트워크 정책 차단 | CoreDNS 로그·NetworkPolicy 확인 |
| 외부만 NXDOMAIN | 업스트림 forward 설정 | kubectl -n kube-system get cm coredns -o yaml |
| 외부 조회가 느림 | ndots 과다 조회 | Pod에 dnsConfig로 ndots:2 지정 |
| 간헐적 실패 | CoreDNS 부하·replica 부족 | replica 증설, NodeLocal DNSCache 검토 |
체크리스트
kubectl get pods -n kube-system -l k8s-app=kube-dns # CoreDNS 상태
kubectl exec <pod> -- cat /etc/resolv.conf # ndots·search 확인
kubectl run dns-test --image=busybox:1.36 --rm -it --restart=Never -- nslookup kubernetes.default
kubectl -n kube-system get cm coredns -o yaml # Corefile forward 설정
내부와 외부 조회를 끊어서 본 것이 범위를 절반으로 줄여 줍니다.
서비스 디스커버리와 CoreDNS가 클러스터 안에서 어떻게 맞물리는지 직접 조회해 보며 익히는 실습은 쿠버네티스 트랙에서 해볼 수 있습니다 — 회원가입 없이 무료로.