트러블슈팅
GenD 플랫폼 운영 중 발생할 수 있는 문제의 진단 및 해결 가이드입니다.
개요
트러블슈팅은 증상별로 분류됩니다. 먼저 공통 문제를 확인하고, 해당하지 않으면 세부 카테고리(연결, 성능)를 참조하세요.
진단 기본 절차
1. Pod 상태 확인
kubectl get pods -n gend
kubectl describe pod <POD_NAME> -n gend
kubectl logs <POD_NAME> -n gend --tail=100
2. 서비스 연결 확인
# API 헬스체크 (gend-api 는 ClusterIP — port-forward 필요)
kubectl port-forward svc/gend-api 8000:8000 -n gend &
curl http://localhost:8000/health
# 클러스터 내부 DNS 확인
kubectl run -it --rm dns-test --image=busybox -n gend -- nslookup trino
3. 리소스 상태 확인
kubectl top nodes
kubectl top pods -n gend
kubectl get events -n gend --sort-by='.lastTimestamp'
빠른 진단 체크리스트
| 증상 | 확인 사항 | 참조 |
|---|---|---|
| Pod CrashLoopBackOff | 로그 확인, 리소스 제한, 시크릿 누락 | 자주 발생하는 문제 |
| API 401 에러 | Keycloak 연결, 토큰 만료, issuer URL | 연결 문제 |
| 쿼리 느림 | Trino 리소스, 워커 수, 메모리 설정 | 성능 튜닝 |
| 서비스 접속 불가 | NodePort 매핑, 포트 충돌, 네트워크 정책 | 연결 문제 |
로그 수집
# 전체 gend 네임스페이스 로그 수집
kubectl logs -n gend -l app=gend-api --tail=500 > gend-api.log
kubectl logs -n gend -l app=trino-coordinator --tail=500 > trino.log
kubectl logs -n gend -l app=keycloak --tail=500 > keycloak.log
긴급 복구
# Pod 강제 재시작
kubectl rollout restart deployment/gend-api -n gend
# Vault re-unseal
kubectl exec -n gend vault-0 -- vault operator unseal <KEY>