자주 발생하는 문제
GenD 운영에서 자주 발생하는 문제와 해결 방법입니다.
개요
대부분의 문제는 시크릿 미설정, 리소스 부족, 이미지 캐시 문제에서 발생합니다. 아래 목록을 순서대로 확인하세요.
Pod가 CrashLoopBackOff 상태
원인: 필수 환경 변수 미설정, 시크릿 누락, 의존 서비스 미기동
# 로그 확인
kubectl logs <POD> -n gend --previous
# 시크릿 존재 확인
kubectl get secret gend-pg-secret -n gend
kubectl get secret keycloak-admin-secret -n gend
해결: GEND_DATABASE_URL, GEND_ARANGODB_PASSWORD 등 필수 환경 변수가 설정되었는지 확인합니다.
Kind에서 이미지가 업데이트되지 않음
원인: 동일 태그(latest)로 이미지를 재빌드하면 Kind 노드에 캐시된 이미지를 사용
해결: 반드시 고유 태그를 사용하세요.
docker build -t gend/gend-api:0.2.1-$(date +%s) -f apps/api/Dockerfile apps/api
kind load docker-image gend/gend-api:0.2.1-<TIMESTAMP> --name gend-local
Vault가 sealed 상태
원인: Pod 재시작 후 자동 unseal 미구성
# 상태 확인
kubectl exec -n gend vault-0 -- vault status
# Unseal (3개 키 필요)
kubectl exec -n gend vault-0 -- vault operator unseal <KEY>
OpenSearch vm.max_map_count 에러
원인: 커널 파라미터 미설정
해결: OpenSearch initContainer가 자동으로 설정합니다. 권한 문제 시 노드에서 직접 설정:
docker exec gend-local-worker sysctl -w vm.max_map_count=262144
Trino 쿼리 실패 "Insufficient resources"
원인: 쿼리 메모리가 query.max-memory 초과
해결: infra/helm/trino/values.yaml에서 메모리 한도를 증가시킵니다.
make seed-demo 실패
원인: 의존 서비스(Trino, PostgreSQL, SeaweedFS) 미기동
해결: make demo-check로 서비스 상태를 먼저 확인합니다.
readOnlyRootFilesystem 관련 에러
원인: /tmp 디렉토리 쓰기 불가
해결: emptyDir 볼륨을 /tmp에 마운트합니다. GenD Dockerfile은 readOnlyRootFilesystem: true와 호환되도록 설계되어 있습니다.