Ingress 트러블슈팅 플레이북 — 502/504/404부터 TLS까지

[클라이언트] → [DNS] → [LoadBalancer/노드] → [Ingress Controller] → [Service] → [Endpoints/Pod]
     1            2              3                      4                5              6

# Ingress 상태와 이벤트
kubectl describe ingress my-ingress -n my-namespace

# 컨트롤러 로그 실시간
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller -f

# 서비스가 가리키는 엔드포인트 확인 (가장 중요한 명령 중 하나)
kubectl get endpoints my-service -n my-namespace

# 컨트롤러 Pod 안에서 백엔드로 직접 요청
kubectl exec -n ingress-nginx deploy/ingress-nginx-controller -- \
  curl -s -o /dev/null -w "%{http_code}\n" http://my-service.my-namespace.svc:80/

# 외부에서 Host 헤더를 지정해 직접 테스트
curl -v -H "Host: app.example.com" http://<LB_IP>/

404 수신
   │
   ▼
1) ingressClassName이 설정/일치하는가?
   ├─ 없음/오타  → 컨트롤러가 이 Ingress를 무시함. spec.ingressClassName 추가
   └─ 일치       → 다음
   │
   ▼
2) host와 path가 요청과 매칭되는가?
   ├─ Host 헤더 불일치  → 와일드카드/정확 호스트 확인
   ├─ pathType 문제     → Prefix vs Exact 확인
   └─ 매칭됨            → 다음
   │
   ▼
3) describe ingress의 backend가 올바른 서비스/포트인가?
   ├─ 서비스명/포트 오타 → 수정
   └─ 정상              → 백엔드 앱 자체의 404 (라우팅은 정상)

# 이 Ingress가 어떤 클래스에 속하는지, 규칙이 어떻게 보이는지
kubectl get ingress my-ingress -o yaml | grep -A2 ingressClassName
kubectl describe ingress my-ingress

# 설치된 IngressClass 목록
kubectl get ingressclass

# Host 헤더를 정확히 지정해 매칭 확인
curl -v -H "Host: app.example.com" http://<LB_IP>/api/users

502 수신
   │
   ▼
1) endpoints가 존재하는가?
   ├─ 비어 있음  → Pod 미준비/셀렉터 불일치 (사실상 503에 가까움)
   └─ 존재       → 다음
   │
   ▼
2) 백엔드 포트/프로토콜이 맞는가?
   ├─ targetPort 불일치       → Service.targetPort 점검
   ├─ HTTPS 백엔드인데 HTTP로 → backend-protocol 어노테이션 HTTPS
   └─ 정상                    → 다음
   │
   ▼
3) 백엔드가 정상 응답하는가? (컨트롤러에서 직접 curl)
   ├─ 연결 거부/리셋  → 앱 크래시/리스닝 포트 다름
   ├─ 타임아웃        → 504 트리로 이동
   └─ 200            → 헤더/바디 크기, upstream keepalive 의심

# 백엔드 직접 호출 (포트/프로토콜 검증)
kubectl exec -n ingress-nginx deploy/ingress-nginx-controller -- \
  curl -sv http://my-service.my-namespace.svc:8080/healthz

# 컨트롤러 로그에서 502 라인과 upstream 정보
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller | grep " 502 "

metadata:
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

503 수신
   │
   ▼
kubectl get endpoints my-service
   ├─ <none>  → 1) Pod가 Ready인가? 2) Service selector가 Pod label과 일치하는가?
   │           3) readinessProbe가 실패해 트래픽에서 빠졌는가?
   └─ 주소 있음 → 컨트롤러-서비스 간 일시적 동기화 지연 또는 maxUnavailable 중

# 엔드포인트(가장 중요)
kubectl get endpoints my-service -n my-namespace

# Pod 상태와 readiness
kubectl get pods -n my-namespace -l app=my-app
kubectl describe pod <pod> -n my-namespace | grep -A5 Conditions

# 서비스 셀렉터와 Pod 라벨 비교
kubectl get service my-service -o jsonpath='{.spec.selector}'
kubectl get pods --show-labels -n my-namespace

504 수신
   │
   ▼
1) 백엔드 자체가 느린가? (직접 curl로 시간 측정)
   ├─ 느림  → 앱 성능 문제. DB/외부 호출 의심
   └─ 빠름  → 다음
   │
   ▼
2) 타임아웃 어노테이션이 너무 짧은가?
   └─ proxy-read-timeout/proxy-send-timeout 상향 검토
   │
   ▼
3) keepalive/커넥션 풀 고갈인가?
   └─ upstream-keepalive 설정, 동시성 점검

# 백엔드 응답 시간 측정
kubectl exec -n ingress-nginx deploy/ingress-nginx-controller -- \
  curl -s -o /dev/null -w "time_total=%{time_total}\n" http://my-service.my-namespace.svc:80/slow

# 현재 타임아웃 어노테이션 확인
kubectl get ingress my-ingress -o yaml | grep timeout

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
    nginx.ingress.kubernetes.io/proxy-send-timeout: "120"

TLS 오류
   │
   ▼
1) 어떤 인증서가 제공되는가? (openssl s_client)
   ├─ 기본/가짜 인증서  → Ingress의 tls.secretName 또는 SNI 매칭 문제
   ├─ 만료된 인증서      → cert-manager 갱신 실패 확인
   └─ 올바른 인증서      → 클라이언트 신뢰 체인 문제
   │
   ▼
2) Secret이 존재하고 형식이 맞는가?
   └─ kubernetes.io/tls 타입, tls.crt/tls.key 키 확인
   │
   ▼
3) host와 인증서 SAN이 일치하는가?
   └─ SNI/와일드카드 범위 점검

# 실제로 제공되는 인증서를 SNI 지정해 확인
openssl s_client -connect <LB_IP>:443 -servername app.example.com 2>/dev/null \
  | openssl x509 -noout -subject -issuer -dates

# TLS Secret 존재/형식
kubectl get secret my-tls -n my-namespace -o yaml | grep -E "tls.crt|tls.key|type"

# cert-manager Certificate 상태
kubectl describe certificate my-cert -n my-namespace

리다이렉트 루프
   │
   ▼
1) Ingress가 HTTPS 리다이렉트를 거는데 백엔드도 HTTP로 다시 리다이렉트?
   └─ 이중 리다이렉트. 한 곳에서만 처리
   │
   ▼
2) TLS 종료가 LB에서 일어나는데 백엔드가 X-Forwarded-Proto를 무시?
   └─ use-forwarded-headers 활성화, 앱이 헤더 신뢰하도록
   │
   ▼
3) force-ssl-redirect와 앱의 자체 리다이렉트가 충돌?
   └─ 한쪽 비활성화

# ConfigMap (컨트롤러 전역)
data:
  use-forwarded-headers: "true"
  compute-full-forwarded-for: "true"

# 컨트롤러 로그에서 413 / "client intended to send too large body"
kubectl logs -n ingress-nginx deploy/ingress-nginx-controller | grep "too large"

metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: "100m"