9. EKS 활용 사례 3 (Troubleshooting)
Update : 2025.08.07
EKS 디버깅 워크샵 – Amazon Q 기반 Kubernetes 문제 해결
이 가이드는 Amazon Q와 함께 마이크로서비스 기반 Kubernetes 애플리케이션에서 자주 발생하는 문제들을 어떻게 진단하고 수정하는지를 실습 중심으로 설명합니다.
각 시나리오는 다음 요소로 구성됩니다:
초기 정상 상태
문제를 의도적으로 유발하는 방법
증상 및 에러 메시지
문제 해결을 위한 Amazon Q 프롬프트
kubectl을 통한 결과 검증
1. Kubernetes 문제 해결 시나리오
1.1 Scenario 1: 잘못된 Service Selector
초기 상태
UI 서비스가 정상적으로 Catalog 서비스에 연결되어 상품 목록을 불러옵니다.
문제 유발 프롬프트:
cd ~/environment/eks-workshop-v2/
# 현재 catalog 서비스 정의 추출
kubectl get service catalog -n catalog -o yaml > catalog-service.yaml
# selector 값을 잘못된 값으로 변경
sed -i 's/app.kubernetes.io\/name: catalog/app.kubernetes.io\/name: catalog-wrong/g' catalog-service.yaml
# 변경된 서비스 적용
kubectl apply -f catalog-service.yaml증상
UI에서 상품 목록을 로드할 때 오류 발생
UI 파드 로그에서 catalog 서비스 연결 거부 메시지
catalog 서비스는 존재하지만, 트래픽이 파드로 전달되지 않음
Amazon Q 프롬프트 예시 :
Kubernetes 애플리케이션의 UI가 EKS 클러스터 내 catalog 서비스에 연결되지 않습니다.
catalog 파드는 실행 중이지만, 서비스가 트래픽을 해당 파드로 라우팅하지 않고 있습니다.
서비스 셀렉터(selector) 불일치 여부를 어떻게 확인하고, 이를 어떻게 수정할 수 있을까요?실행 결과는 아래와 같습니다:
## ✅ Catalog 서비스 연결 문제 해결 완료!
UI가 catalog 서비스에 연결되지 않는 문제를 성공적으로 해결했습니다.
### 🔍 발견된 문제
서비스 셀렉터 불일치:
• **파드 레이블**: app.kubernetes.io/name: catalog ✅
• **서비스 셀렉터**: app.kubernetes.io/name: catalog-wrong ❌
### 🛠️ 해결 과정
1. 문제 진단: 파드 레이블과 서비스 셀렉터 비교
2. 엔드포인트 확인: <none> 상태로 파드 연결 안됨 확인
3. YAML 재적용: kubectl apply -k 명령어로 올바른 설정 적용
4. 연결 테스트: HTTP 200 응답으로 정상 동작 확인
### 📊 수정 결과
수정 전:
NAME ENDPOINTS AGE
catalog <none> 72m
수정 후:
NAME ENDPOINTS AGE
catalog 10.11.74.186:8080 72m
### 🧪 연결 테스트 성공
bash
kubectl exec -n ui deployment/ui -- curl -s -o /dev/null -w "%{http_code}" http://catalog.catalog.svc:80/health
# 결과: 200 ✅
### 📋 진단 체크리스트
향후 유사한 문제 발생 시 사용할 수 있는 체크리스트:
1. 파드 레이블 확인: kubectl get pods -n <namespace> --show-labels
2. 서비스 셀렉터 확인: kubectl get service <name> -n <namespace> -o yaml
3. 엔드포인트 상태 확인: kubectl get endpoints <name> -n <namespace>
4. 연결 테스트: curl 명령어로 실제 연결 확인
📝 상세한 문제 해결 과정과 예방 조치는 ~/output/catalog-service-selector-fix.md 파일에 저장되었습니다.
이제 UI 애플리케이션이 catalog 서비스와 정상적으로 통신할 수 있습니다! 🎉문제 검증 및 복구
# 서비스의 selector 확인
kubectl get service catalog -n catalog -o jsonpath='{.spec.selector}' | jq
# 파드 라벨 확인
kubectl get pods -n catalog -l app.kubernetes.io/name=catalog -o jsonpath='{.items[0].metadata.labels}' | jq
# 서비스에 바인딩된 엔드포인트 확인
kubectl get endpoints catalog -n catalog1.2 Scenario 2: 리소스 제약 (Resource Constraints)
초기 상태 : Carts 서비스가 충분한 CPU 및 메모리 리소스를 갖고 정상적으로 동작함.
문제 유발 프롬프트:
# carts 디플로이먼트 추출
kubectl get deployment carts -n carts -o yaml > carts-deployment.yaml
# 리소스 제한을 극단적으로 낮게 설정
sed -i 's/memory: 1Gi/memory: 1Mi/g' carts-deployment.yaml
sed -i 's/cpu: 250m/cpu: 1m/g' carts-deployment.yaml
# 변경 적용
kubectl apply -f carts-deployment.yaml증상
carts 파드가 CrashLoopBackOff 상태로 반복 재시작됨
이벤트에 OOMKilled(메모리 부족으로 종료) 로그 발생
애플리케이션 응답 지연 또는 중단
실행 결과는 아래와 같습니다:
명령을 실행했고, carts 디플로이먼트의 리소스 제한을 극단적으로 낮게 설정했습니다. 그 결과 새로운 파드가 시작되지 못하고 있습니다.
## 실행 결과 분석
1. 리소스 제한 변경:
• 메모리 제한: 1Gi → 1Mi (1024MB에서 1MB로 감소)
• CPU 요청: 250m → 1m (250밀리코어에서 1밀리코어로 감소)
2. 디플로이먼트 상태:
• 롤링 업데이트 중: 새 ReplicaSet carts-bc5d58f66가 생성됨
• 이전 파드 carts-7c95cd549d-4mjjb는 여전히 실행 중
• 새 파드 carts-bc5d58f66-2bhsz는 Pending 상태
3. 새 파드 문제:
• 이벤트 로그에서 중요한 오류 발견:
Failed to create pod sandbox: rpc error: code = Unknown desc = failed to create containerd task:
failed to create shim task: OCI runtime create failed: runc create failed:
unable to start container process: container init was OOM-killed (memory limit too low?): unknown
## 문제 원인
새 파드가 시작되지 못하는 이유는 메모리 제한이 너무 낮기 때문입니다. 1Mi(1MB)는 Java 애플리케이션이 실행되기에 극단적으로 부족한 메모리입니다. 컨테이너 초기화 과
정에서 OOM(Out Of Memory) 오류가 발생하여 파드가 시작되지 못하고 있습니다.
이로 인해 롤링 업데이트가 완료되지 못하고, 이전 파드와 새 파드가 동시에 존재하는 상태가 되었습니다. 이전 파드는 여전히 정상 작동하지만, 새 파드는 시작되지 못하고
있습니다.
이러한 상황은 실제 환경에서 리소스 제한을 잘못 설정했을 때 발생할 수 있는 전형적인 문제입니다. 특히 Java 애플리케이션은 최소한의 메모리가 필요하며, 1MB는 JVM이
시작하기에도 부족한 양입니다.Amazon Q 프롬프트 예시 :
EKS 클러스터의 carts 파드가 계속 OOMKilled 오류로 크래시되고 있습니다.
파드 이벤트를 확인해보니 메모리 문제로 종료되고 있는 것으로 보입니다.
현재 설정된 리소스 제한을 확인하고, 적절한 값으로 업데이트하려면 어떻게 해야 하나요?실행 결과는 아래와 같습니다:
## ✅ Carts 파드 OOMKilled 오류 해결 완료!
EKS 클러스터의 carts 파드가 OOMKilled 오류로 크래시되는 문제를 성공적으로 해결했습니다.
### 🔍 발견된 문제
극도로 부족한 메모리 할당:
• **현재 설정**: 1Mi (1 메가바이트) ❌
• **Java 애플리케이션 최소 요구량**: ~300Mi
• **권장 설정**: 1Gi (1 기가바이트) ✅
### 🚨 OOMKilled 발생 원인
Failed to create pod sandbox: OCI runtime create failed:
runc create failed: unable to start container process:
container init was OOM-killed (memory limit too low?)
Java Spring Boot 애플리케이션이 JVM 초기화 과정에서 1Mi 메모리 제한을 초과하여 Linux OOM Killer에 의해 강제 종료되었습니다.
### 🛠️ 해결 과정
1. 문제 진단: 이벤트 로그에서 OOMKilled 오류 확인
2. 리소스 설정 확인: 현재 메모리 제한이 1Mi로 설정됨 발견
3. 원본 파일 확인: YAML 파일에는 올바른 1Gi 설정이 있음 확인
4. 설정 재적용: kubectl apply -k 명령어로 올바른 설정 적용
### 📊 수정 결과
✅ 업데이트된 리소스 설정:
json
{
"limits": {
"memory": "1Gi"
},
"requests": {
"cpu": "250m",
"memory": "1Gi"
}
}
✅ 현재 실제 사용량:
• **메모리**: 262Mi (할당량의 25.6%)
• **CPU**: 2m (할당량의 0.8%)
• **상태**: Running ✅
• **헬스 체크**: 200 OK ✅
### 🎯 주요 성과
| 지표 | 개선 전 | 개선 후 |
|------|---------|---------|
| 파드 시작 성공률 | 0% | 100% |
| 메모리 가용성 | 0Mi | 762Mi |
| 애플리케이션 응답 | 실패 | 200 OK |
| 시스템 안정성 | 불안정 | 안정 |
### 📋 Java 애플리케이션 리소스 권장사항
메모리 할당 가이드라인:
• **최소 요구량**: 512Mi
• **권장 설정**: 1Gi
• **JVM 힙 비율**: 75% (MaxRAMPercentage=75.0)
• **안전 마진**: 실제 사용량의 2-3배
📝 상세한 문제 해결 과정과 예방 조치는 ~/output/carts-oom-fix.md 파일에 저장되었습니다.
이제 carts 파드가 안정적으로 실행되며 충분한 메모리 여유를 확보했습니다! 🎉검증 명령어
# carts 네임스페이스 내 파드 상태 확인
kubectl get pods -n carts
# 현재 설정된 리소스 제한 확인
kubectl get deployment carts -n carts -o jsonpath='{.spec.template.spec.containers[0].resources}' | jq
# 파드 재시작 횟수 확인 (복구되었을 경우 낮아야 함)
kubectl get pods -n carts -o jsonpath='{.items[*].status.containerStatuses[0].restartCount}'결과 확인
NAME READY STATUS RESTARTS AGE
carts-7dc65cd8ff-lgl4z 1/1 Running 0 2m4s
carts-dynamodb-68bd8f6f6d-p7rmz 1/1 Running 0 25m
{
"limits": {
"memory": "1536Mi"
},
"requests": {
"cpu": "250m",
"memory": "1Gi"
}
}1.3 Scenario 3: 의존성 누락 (Missing Dependencies)
초기 상태
Orders 서비스는 RabbitMQ 서비스에 의존하여 메시지 큐 기능을 수행.
문제 유발
# rabbitmq checkout을 0으로 스케일 다운
kubectl -n checkout scale deployment checkout --replicas=0증상
checkout 서비스와 Redis연결 이슈 발생
Amazon Q 프롬프트 예시:
EKS 클러스터의 checkout 서비스에서 오류가 발생하고 있습니다.
checkout 파드가 실행 중인지 확인하고, 실행 중이 아니라면 어떻게 복구할 수 있을까요?실행 결과는 아래와 같습니다:
## ✅ Checkout 서비스 복구 완료!
EKS 클러스터의 checkout 서비스 오류를 성공적으로 진단하고 복구했습니다.
### 🔍 발견된 문제
Checkout 애플리케이션 파드 완전 중단:
• **디플로이먼트 상태**: 0/0 (파드 없음) ❌
• **서비스 엔드포인트**: <none> (연결 불가) ❌
• **근본 원인**: 레플리카 수가 3에서 0으로 의도치 않게 축소됨
### 🚨 서비스 중단 영향
• **사용자 경험**: 결제 기능 완전 중단
• **연결 테스트**: Exit Code 7 (Connection Failed)
• **비즈니스 영향**: 주문 완료 불가
### 🛠️ 복구 과정
1. 문제 진단: 파드 상태 → 디플로이먼트 상태 → 이벤트 로그 순차 확인
2. 원인 파악: 디플로이먼트가 2분 전에 3개에서 0개로 스케일 다운됨
3. 설정 복구: kubectl apply -k 명령어로 올바른 설정 재적용
4. 결과 검증: 모든 파드 Ready 상태 및 서비스 연결 확인
### 📊 복구 결과
✅ 완전 복구 달성:
NAME READY UP-TO-DATE AVAILABLE AGE
checkout 3/3 3 3 149m
✅ 파드 상태:
• 3개 checkout 파드 모두 Running 상태
• 3개의 서로 다른 워커 노드에 분산 배치
• Redis 캐시와 정상 연결
✅ 서비스 연결:
• 엔드포인트: 3개 파드 IP 모두 등록
• 헬스 체크: 200 OK 응답
• 복구 시간: 약 30초
### 🎯 주요 성과
| 지표 | 복구 전 | 복구 후 |
|------|---------|---------|
| 서비스 가용성 | 0% | 100% |
| 실행 중인 파드 | 0개 | 3개 |
| 응답 성공률 | 0% | 100% |
| 복구 시간 | N/A | 30초 |
### 📋 체계적인 진단 체크리스트
향후 유사한 문제 발생 시 사용할 수 있는 진단 절차:
1. 파드 상태 확인: kubectl get pods -n checkout
2. 디플로이먼트 상태 확인: kubectl get deployment -n checkout
3. 상세 정보 확인: kubectl describe deployment checkout -n checkout
4. 이벤트 로그 분석: kubectl get events -n checkout
5. 연결 테스트: curl 명령어로 실제 연결 확인
📝 상세한 복구 과정과 예방 조치는 ~/output/checkout-service-recovery.md 파일에 저장되었습니다.
이제 checkout 서비스가 3개 레플리카로 고가용성을 확보하며 정상적으로 운영되고 있습니다! 🎉검증 명령어:
# checkout 파드 상태 확인
kubectl get pods -n checkout
# 디플로이먼트 상태 확인
kubectl get deployment -n checkout
# 상세 정보 확인
kubectl describe deployment checkout -n checkout
# 이벤트 로그 분석
kubectl describe deployment checkout -n checkout | grep -A 20 "Events:"실행 결과는 아래와 같습니다:
$kubectl get pods -n checkout
NAME READY STATUS RESTARTS AGE
checkout-54c6cd5685-h4vbh 1/1 Running 0 6m19s
checkout-54c6cd5685-scc5g 1/1 Running 0 6m19s
checkout-54c6cd5685-wf9q9 1/1 Running 0 6m19s
checkout-redis-7fb554999b-rrs4q 1/1 Running 0 156m
$ kubectl get deployment -n checkout
NAME READY UP-TO-DATE AVAILABLE AGE
checkout 3/3 3 3 156m
checkout-redis 1/1 1 1 156m
$ kubectl describe deployment checkout -n checkout | grep -A 20 "Events:"
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal ScalingReplicaSet 12m deployment-controller Scaled down replica set checkout-54c6cd5685 to 0 from 3
Normal ScalingReplicaSet 9m41s deployment-controller Scaled up replica set checkout-54c6cd5685 to 3 from 0Last updated