📌 [Pod 심화편 #6] Pod 트러블슈팅: 자주 발생하는 문제들

 

1️⃣ 개요

 

쿠버네티스를 운영하다 보면 Pod가 실행되지 않거나, 예기치 않은 오류로 인해 서비스가 중단되는 상황을 자주 겪게 됩니다.

이런 문제를 빠르게 해결하려면 Pod의 동작 원리와 장애 발생 원인을 정확히 이해하고, 적절한 트러블슈팅 방법을 적용하는 것이 중요합니다.

 

이번 글에서는 자주 발생하는 Pod 문제 유형을 정리하고, 각각의 원인과 해결 방법을 표로 정리하여 빠르게 대응할 수 있도록 하겠습니다.

 

---

2️⃣ Pod 트러블슈팅 주요 유형과 해결 방법

 

아래는 실무에서 가장 자주 발생하는 Pod 관련 문제와 해결 방법을 정리한 표입니다.

 

📌 Pod 문제 유형 및 해결 방법 정리

문제 유형	증상	원인	해결 방법
Pod이 Pending 상태에서 멈춤	kubectl get pod 실행 시 Pending 상태 유지	- 스케줄링할 노드 부족- PVC(Persistent Volume Claim) 미바인딩	- 노드 리소스 상태 확인 (kubectl describe node)- PVC 상태 확인 (kubectl get pvc)
Pod이 CrashLoopBackOff 상태	Pod가 계속 재시작됨	- 애플리케이션 내부 오류- livenessProbe 설정 오류	- kubectl logs로 로그 확인- livenessProbe 조건 수정
Pod이 ImagePullBackOff 상태	이미지 다운로드 실패	- 컨테이너 이미지 태그 오타- Private Registry 인증 문제	- 이미지 태그 확인 (kubectl describe pod)- Secret 기반 인증 설정
Pod 네트워크 문제	다른 Pod 또는 외부 서비스와 통신 불가	- NetworkPolicy로 인해 차단됨- CoreDNS 문제	- kubectl get networkpolicy로 정책 확인- CoreDNS 재시작 (kubectl rollout restart deployment coredns -n kube-system)
Pod이 OOMKilled 상태	kubectl describe pod 실행 시 "OOMKilled" 메시지 출력	- 메모리 사용량 초과 (limits.memory 초과)	- kubectl top pod로 사용량 확인- limits.memory 값 조정

✅ 이 표를 활용하면 문제 발생 시 빠르게 원인을 확인하고, 적절한 해결 방법을 적용할 수 있습니다.

 

---

3️⃣ Pod이 Pending 상태에서 멈출 때 해결 방법

 

kubectl get pod 실행 시 Pending 상태가 지속되는 경우, 가장 먼저 노드 리소스 부족 및 PVC 바인딩 상태를 확인해야 합니다.

 

📌 트러블슈팅 방법

 

1️⃣ Pod의 이벤트 확인 (kubectl describe pod <pod-name>)

kubectl describe pod my-pod

 

2️⃣ 노드 상태 확인 (kubectl describe node)

kubectl describe node <node-name>

 

3️⃣ PVC 상태 확인 (kubectl get pvc)

kubectl get pvc

 

4️⃣ 필요 시 노드 추가 또는 PVC 수정

 

✅ Pod이 Pending 상태로 멈춘다면 리소스 부족 또는 PVC 문제일 가능성이 큽니다.

 

---

4️⃣ Pod이 CrashLoopBackOff 상태일 때 해결 방법

 

CrashLoopBackOff는 Pod가 비정상 종료된 후 계속 재시작되는 상태를 의미합니다.

 

📌 트러블슈팅 방법

 

1️⃣ Pod의 로그 확인 (kubectl logs)

kubectl logs my-pod

 

2️⃣ 컨테이너 실행 상태 확인 (kubectl describe pod)

kubectl describe pod my-pod

 

3️⃣ Liveness Probe 설정 확인 및 수정

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 3
  periodSeconds: 10

✅ 로그를 먼저 확인한 후, 애플리케이션 오류인지 livenessProbe 설정 오류인지 판단해야 합니다.

 

---

5️⃣ Pod이 ImagePullBackOff 상태일 때 해결 방법

 

ImagePullBackOff는 컨테이너 이미지를 다운로드할 수 없을 때 발생하는 오류입니다.

 

📌 트러블슈팅 방법

 

1️⃣ Pod의 상세 정보 확인 (kubectl describe pod)

kubectl describe pod my-pod

 

2️⃣ 오류 메시지에서 이미지 태그 확인 (kubectl get pod -o jsonpath)

kubectl get pod my-pod -o jsonpath="{.spec.containers[*].image}"

 

3️⃣ Private Registry 인증 문제 해결 (kubectl create secret docker-registry)

kubectl create secret docker-registry my-registry-secret \
  --docker-server=<REGISTRY_SERVER> \
  --docker-username=<USERNAME> \
  --docker-password=<PASSWORD>

✅ 이미지 태그가 잘못되었는지 확인하고, 필요하면 Private Registry 인증을 설정해야 합니다.

 

---

6️⃣ Pod 네트워크 문제 해결 방법

 

Pod가 다른 서비스 또는 외부 네트워크와 통신할 수 없는 경우, 다음과 같은 원인일 가능성이 높습니다.

 

📌 트러블슈팅 방법

 

1️⃣ 네트워크 정책(NetworkPolicy) 확인

kubectl get networkpolicy -A

 

2️⃣ Pod 내부에서 DNS 조회 확인 (nslookup)

kubectl exec -it my-pod -- nslookup my-service

 

3️⃣ CoreDNS 상태 확인 및 재시작

kubectl get pod -n kube-system | grep coredns
kubectl rollout restart deployment coredns -n kube-system

✅ 네트워크 정책 문제인지 DNS 문제인지 먼저 확인하고, 각각의 해결 방법을 적용해야 합니다.

 

---

7️⃣ Pod이 OOMKilled 상태일 때 해결 방법

 

Pod이 OOMKilled 상태로 종료되었다면 메모리 부족 문제일 가능성이 큽니다.

 

📌 트러블슈팅 방법

 

1️⃣ Pod의 상세 이벤트 확인 (kubectl describe pod)

kubectl describe pod my-pod

 

2️⃣ 현재 메모리 사용량 확인 (kubectl top pod)

kubectl top pod

 

3️⃣ 리소스 제한 조정 (limits.memory 수정)

resources:
  requests:
    memory: "512Mi"
  limits:
    memory: "1Gi"

✅ Pod의 메모리 제한을 조정하거나, VPA(Vertical Pod Autoscaler)를 활용하여 자동으로 리소스를 최적화할 수 있습니다.

 

---

🔥 8️⃣ 결론

 

✔ 쿠버네티스에서 Pod 문제를 해결하려면, kubectl logs, kubectl describe pod, kubectl get events 등을 활용하여 원인을 분석하는 것이 중요합니다.

✔ Pod이 Pending, CrashLoopBackOff, ImagePullBackOff, OOMKilled 상태가 되면 각각의 원인을 찾아 해결해야 합니다.

✔ 네트워크 문제는 NetworkPolicy 및 CoreDNS 설정을 확인하여 원인을 파악해야 합니다.

✔ 메모리 부족 문제는 kubectl top pod을 사용하여 리소스 사용량을 확인한 후, 적절한 리소스 제한을 설정해야 합니다.