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"