쿠버네티스 실습: 운영 환경 트러블슈팅 사례 정리

쿠버네티스 실습: 운영 환경 트러블슈팅 사례 정리

앞선 글에서는 Helm Chart를 활용해 NestJS + NextJS + PostgreSQL + Redis를 쿠버네티스에 통합 배포했습니다.
이번 글에서는 실제 운영 과정에서 자주 마주치는 트러블슈팅 시나리오를 정리하고, 문제 원인과 해결 방법을 단계별로 살펴보겠습니다.

---

1) Pod가 CrashLoopBackOff 상태일 때

증상

kubectl get pods

nestjs-deployment-xxx   0/1   CrashLoopBackOff   5   2m

원인

• 컨테이너 실행 중 에러 발생
• 환경 변수(예: DB URL) 누락
• 애플리케이션 포트 불일치

해결 방법

kubectl logs nestjs-deployment-xxx
kubectl describe pod nestjs-deployment-xxx

• 로그에서 에러 메시지를 확인
• ConfigMap/Secret을 올바르게 주입했는지 점검
• Deployment의 containerPort와 Service의 targetPort가 일치하는지 확인

---

2) PVC가 Bound 되지 않는 경우

증상

kubectl get pvc

NAME           STATUS    VOLUME   CAPACITY   ACCESS MODES   AGE
postgres-pvc   Pending                                      5m

원인

• PV 용량이 부족하거나 조건이 맞지 않음
• StorageClass 미설정

해결 방법

kubectl get pv

• PVC 요청(requests.storage)과 PV 용량이 일치하는지 확인
• StorageClass가 필요한 경우 PVC에 지정

예시 수정:

spec:
  storageClassName: standard

---

3) Ingress가 외부에서 접속되지 않을 때

증상

브라우저에서 http://api.fuel.local 접속 시 응답 없음.

원인

• Ingress Controller 미설치 또는 비정상
• /etc/hosts 매핑 누락
• 잘못된 Ingress 규칙

해결 방법

minikube addons enable ingress
kubectl get pods -n kube-system | grep ingress

• Ingress Controller가 Running 상태인지 확인
• /etc/hosts에 minikube ip와 도메인 매핑 확인
• kubectl describe ingress <INGRESS_NAME>로 규칙 점검

---

4) HPA가 Pod를 늘리지 않는 경우

반응형

증상

kubectl get hpa

NAME        REFERENCE           TARGETS   MINPODS   MAXPODS   REPLICAS   AGE
cpu-app     Deployment/cpu-app  5%/50%    1         5         1          10m

→ CPU 사용률이 낮게만 표시됨.

원인

• Metrics Server 미설치
• Pod의 resources.requests.cpu 미설정

해결 방법

minikube addons enable metrics-server
kubectl top pods

• Metrics Server가 정상 동작하는지 확인
• Deployment에 최소 CPU request 지정

resources:
  requests:
    cpu: "100m"

---

5) Pod가 Pending 상태에서 생성되지 않을 때

증상

kubectl get pods

frontend-xxx   0/1   Pending   0   3m

원인

• 노드에 리소스 부족 (CPU, 메모리)
• NodeSelector/Taint 설정 불일치

해결 방법

kubectl describe pod frontend-xxx

• 노드 리소스 확인

kubectl describe node

• 필요 시 requests 값 줄이거나 노드 리소스 늘리기

---

6) 정리

• CrashLoopBackOff → 로그 확인, 환경 변수 및 포트 점검
• PVC Pending → PV 용량 및 StorageClass 확인
• Ingress 문제 → Controller 상태, hosts 매핑, 규칙 점검
• HPA 미동작 → Metrics Server 활성화, CPU requests 지정
• Pod Pending → 노드 리소스 부족 여부 확인

다음 글에서는 Service Mesh (예: Istio, Linkerd) 개념 소개와 적용 실습을 다뤄, 마이크로서비스 간 통신과 보안을 한층 강화하는 방법을 알아보겠습니다.

---

 

쿠버네티스,트러블슈팅,CrashLoopBackOff,PVC,Ingress,HPA,PodPending,운영환경,DevOps,K8s실습

 

 

🔍 웹 자료 참고

주제 출처 & 요약

CrashLoopBackOff 원인 및 해결책	Lumigo “Kubernetes CrashLoopBackOff Error: Common Causes & Solutions” — 리소스 부족, 환경 변수 에러, 포트 충돌, Probe 설정 오류 등 여러 원인 제시됨. (Lumigo)
PVC가 Pending 상태로 남는 경우	StackOverflow “Persistent Volume Claim Indefinitely in Pending State” — StorageClass 및 volumeName 문제, 기존 PV/PVC가 매칭되지 않음 등이 원인으로 나옴. (Stack Overflow)
Persistent Volume Best Practices	vcluster.com 블로그 — PV/PVC의 AccessModes, StorageClass, reclamation policy 등의 올바른 설정 중요성 강조됨. (vcluster.com)

---

✅ 보강 제안: 각 트러블슈팅 사례 업그레이드

아래는 이미 쓰신 사례들에 웹 자료 근거를 추가하고, 단계별 해결책을 더 구체화한 버전 예시입니다.

---

1) Pod가 CrashLoopBackOff 상태일 때

증상

• READY 컬럼이 0/1
• 재시작 횟수(RESTARTS) 증가
• 상태 CrashLoopBackOff 보임

원인 (웹 자료 기반 추가)

• 메모리 또는 CPU 한도(Limits)가 너무 낮아서 OOM 발생 (Google Cloud)
• 잘못된 Probe (Liveness / Readiness) 설정: 경로, 포트, 초기 지연 시간(initialDelaySeconds) 등이 애플리케이션 준비 상태와 맞지 않을 때 (Google Cloud)
• 이미지 Pull 실패 또는 잘못된 이미지 태그 / 인증 문제 (appvia.io)
• 환경변수 누락 / 잘못된 구성으로 앱이 시작 시 에러 발생 (Lumigo)

해결 방법 (업그레이드된 단계)

1. kubectl describe pod <pod-name>로 “Last State”, “Reason”, 이벤트 메시지 확인
2. kubectl logs <pod-name> 또는 kubectl logs <pod-name> -c <container>로 애플리케이션 로그 확인
3. Probe 설정 확인
   • livenessProbe/readinessProbe의 path, port가 실제 서비스 포트 및 엔드포인트와 일치하는지
   • initialDelaySeconds 충분한지 (앱 시작 시간 고려)
4. 리소스 Requests / Limits 조정
   • limits.memory 늘리기
   • requests.cpu/memory 올려서 스케줄링 가능 여부 확인
5. 이미지 Pull 관련 문제일 경우
   • 이미지 이름/태그 확인
   • Private registry인 경우 imagePullSecrets 설정 여부 확인

---

2) PVC가 Bound 되지 않는 경우 (Pending 상태)

증상

• kubectl get pvc 상태가 Pending
• kubectl get pv가 적절한 PV 없음 또는 Available 상태의 PV 존재하지만 바인딩 되지 않음

원인 (웹 자료 기반 추가)

• PVC 요청 사이즈(requests.storage)가 PV의 capacity보다 큼 (Stack Overflow)
• StorageClass 지정이 없거나, StorageClass의 volumeBindingMode가 WaitForFirstConsumer 설정되어 있어서 Pod 스케줄 시점까지 PV 바인딩이 지연됨 (DevOps Stack Exchange)
• PV의 AccessModes 불일치 (예: PV는 ReadWriteMany인데 PVC는 ReadWriteOnce 등) (vcluster.com)
• StorageClass가 존재하지 않거나 올바르지 않은 provisioner 설정됨

해결 방법 (업그레이드된 단계)

1. kubectl describe pvc <name>로 바인딩 조건 메시지 확인
2. kubectl get storageclass 와 kubectl get pv로 사용 가능한 PV 및 StorageClass 확인
3. PVC manifest에 storageClassName 명시하거나 PV가 기본 StorageClass로 설정되었는지 확인
4. 요청 크기를 PV capacity 이하로 조정
5. AccessModes 호환성 확인
6. 만약 동적 프로비저닝(dynamic provisioning) 사용 가능하면 StorageClass 설정 활용

---

⚙️ 수정된 사례 항목 정리

마지막으로, 문서의 트러블슈팅 항목들을 웹 자료와 보강 내용 기반으로 업데이트한 버전 예시는 다음과 같습니다:

---

사례 1: CrashLoopBackOff 상태

• 증상: 0/1 Ready, 반복 재시작
• 원인: 리소스 부족 (메모리/CPU), Probe 오설정, 이미지/환경변수 오류 등
• 해결:
  • Probe 설정 수정: initialDelaySeconds, timeoutSeconds 조정
  • 리소스 Limits / Requests 재검토
  • 이미지 태그 / 레지스트리 접근성 확인
• kubectl describe pod <pod> kubectl logs <pod> kubectl get events -n <namespace>

---

사례 2: PVC Bound 안 됨 (Pending)

• 증상: PVC 상태 Pending, PV 없음 또는 매칭 실패
• 원인: 요청 크기 > PV 용량, StorageClass 누락 / 불일치, AccessModes 불일치
• 해결:
  • PVC manifest에 storageClassName 지정
  • PV capacity 늘리거나 PVC의 요청 크기 낮춤
  • AccessModes 맞춤 (예: both PV & PVC에 RWO 등 동일)
  • 동적 프로비저닝 가능한 StorageClass 활용
• kubectl describe pvc <pvc-name> kubectl get pv kubectl get storageclass

---