본문으로 건너뛰기

연결 문제

GenD 서비스 간 연결 장애 진단 및 해결 방법입니다.

개요​

GenD는 다수의 마이크로서비스가 K8s 내부 DNS로 통신합니다. 연결 문제의 대부분은 서비스 DNS, 포트 매핑, 인증 설정에서 발생합니다.

API -> Trino 연결 실패​

증상: 쿼리 실행 시 "Connection refused" 또는 타임아웃

# Trino 서비스 확인
kubectl get svc trino -n gend
kubectl get pods -l app=trino-coordinator -n gend

# API Pod에서 Trino 연결 테스트
kubectl exec -n gend deploy/gend-api -- \
  python -c "import socket; socket.create_connection(('trino', 8080), 5); print('OK')"

해결: Trino 서비스명은 trino입니다 (trino-coordinator가 아닙니다). GEND_TRINO_HOST=trino, GEND_TRINO_PORT=8080을 확인하세요.

API -> Keycloak 연결 실패​

증상: JWT 검증 실패, JWKS 가져오기 에러

# JWKS 엔드포인트 직접 확인
kubectl exec -n gend deploy/gend-api -- \
  curl -s http://keycloak:8080/auth/realms/gend/protocol/openid-connect/certs | head -20

해결:

  • GEND_KEYCLOAK_URL이 내부 URL(http://keycloak:8080/auth)인지 확인
  • 외부에서 발급된 토큰이면 GEND_KEYCLOAK_ISSUER_URL을 외부 URL로 설정

API -> PostgreSQL 연결 실패​

증상: "Connection refused" 또는 인증 실패

kubectl get svc postgresql -n gend
kubectl exec -n gend deploy/gend-api -- \
  python -c "import asyncpg; print('driver OK')"

해결: GEND_DATABASE_URL 형식 확인: postgresql+asyncpg://gend:<PASSWORD>@postgresql:5432/gend

NodePort 접근 불가​

증상: localhost:31080 (Trino NodePort) 접속 실패

# NodePort 서비스 확인
kubectl get svc -n gend -o wide | grep NodePort

# 포트 충돌 확인 (macOS)
lsof -i :31080

# Kind 포트 매핑 확인
docker port gend-local-control-plane

해결: Kind 클러스터 설정(infra/kind/gend-cluster.yaml)에 해당 NodePort가 extraPortMappings에 포함되어 있는지 확인합니다.

DMZ Relay 연결 실패​

증상: HMAC 서명 검증 실패

해결: API와 Relay의 GEND_DMZ_HMAC_SECRET 값이 동일한지 확인합니다. Query string을 포함한 전체 URL이 서명 대상입니다.

DNS 해결 실패​

# 클러스터 DNS 테스트
kubectl run -it --rm dns-test --image=busybox -n gend -- nslookup trino.gend.svc.cluster.local

관련 문서​