Kubernetesで504 Gateway Timeoutが出た時の調査方法覚書

Kubernetesにデプロイした認証フローで504 Gateway Timeoutが出た時に、Podの一覧、ログ、describeの順に調べて、frontendのInitコンテナの失敗にたどり着くまでの手順をまとめました。

GitHub OAuthを使った認証フローをKubernetesクラスターにデプロイして試したところ、504 Gateway Timeoutが返ってきました。エラーメッセージだけでは原因が分からなかったので、kubectlで順番に調べていきました。

遭遇した現象

GitHubの認証ページで許可するとコールバックURLに戻り、authentication-svcが処理を受けて、frontendの内部APIを呼ぶ流れです。504が返ったのは、このfrontendを呼ぶ段階でした。

HTTP 504 Gateway Timeout

Podの状態を確認する

まずは名前空間内のPodを一覧します。

kubectl get pods -n hidetaka-k8s-namespace

NAME                                                  READY   STATUS                  RESTARTS   AGE
authentication-svc-loginapi-7bcff887fc-qf6sb          1/1     Running                 0          21h
authentication-svc-profileapi-777c76bbb4-j8xvc        1/1     Running                 0          21h
authentication-svc-tokenapi-5c9c5c8b9d-8n5zx          1/1     Running                 0          21h
business-svc-resourceapi-6d8f7c9d9f-k7m8n            1/1     Running                 0          21h
db-postgres-0                                         1/1     Running                 0          21h
frontend-68ff8c7d9c-plrkk                             0/1     Init:CrashLoopBackOff   204        17h
messaging-svc-notificationapi-6b9d8c7f8d-m9n7p       1/1     Running                 0          21h

認証関連のPodはRunningですが、frontendだけがInit:CrashLoopBackOffになっていました。READYは0/1、RESTARTSは204です。

認証サービスのログを見る

frontendが落ちていることが504の原因なのか、authentication-svcのログで確認します。

kubectl logs -n hidetaka-k8s-namespace authentication-svc-loginapi-7bcff887fc-qf6sb --tail=50

{
  "time": "2025-12-16T03:15:23Z",
  "level_name": "warning",
  "msg": "POST /internal/auth/github",
  "error.detail": "httpclient do: dial tcp 172.20.160.22:8080: connect: connection refused",
  "error.type": "connection_refused",
  "http.attempt": 1,
  "http.url": "http://frontend.hidetaka-k8s-namespace.svc.cluster.local:8080/internal/auth/github"
}

接続先はfrontendで、connection refusedになっています。ログを追うと15回までリトライしていました。frontendのPodが起動していないため、接続を受けるプロセスがない様子です。

Initコンテナの失敗を見つける

Init:CrashLoopBackOffは、Initコンテナが失敗し続けている状態です。Initコンテナがすべて成功するまでメインコンテナは起動しません。詳細をdescribeで見てみます。

kubectl describe pod -n hidetaka-k8s-namespace frontend-68ff8c7d9c-plrkk

出力のうち、Init ContainersとEventsを抜粋します。

Init Containers:
  license:
    Image:         myregistry/license-checker:v1.0
    State:         Terminated
      Reason:      Error
      Exit Code:   1
      Started:     Mon, 16 Dec 2025 02:13:05 UTC
      Finished:    Mon, 16 Dec 2025 02:13:05 UTC
    Last State:    Terminated
      Reason:      Error
      Exit Code:   1

Events:
  Type     Reason   Age                    From     Message
  ----     ------   ----                   ----     -------
  Normal   Pulled   97s (x205 over 17h)    kubelet  Container image "..." already present
  Warning  BackOff  49s (x4694 over 17h)   kubelet  Back-off restarting failed container license

licenseという名前のInitコンテナがExit Code 1で終了し、17時間再起動を繰り返していました。frontendが起動しなかったのは、このコンテナが原因です。

Initコンテナのログを見る

Podの中にコンテナが複数あるため、-cでコンテナ名を指定してログを見ます。

kubectl logs -n hidetaka-k8s-namespace frontend-68ff8c7d9c-plrkk -c license

2025/12/16 02:13:05 Starting license validation...
2025/12/16 02:13:05 Reading license file: /config/license.json
2025/12/16 02:13:05 [json] - invalid character 'c' after top-level value
2025/12/16 02:13:05 License validation failed

/config/license.jsonを読み込んだところで、JSONのパースエラーになっていました。/config配下のファイルなので、ConfigMapかSecretからマウントされたものでしょう。

Endpointsを確認する

念のため、frontendのServiceに接続できるPodがないことも確認しました。

kubectl get endpoints frontend -n hidetaka-k8s-namespace

NAME       ENDPOINTS   AGE
frontend               21h

ENDPOINTSが空になっています。

まとめ

license.jsonの形式エラーでInitコンテナが失敗し、frontendのPodが起動しません。そのためServiceに接続先がなくなり、authentication-svcからの接続がconnection refusedで失敗して、504が返っていました。

504はあくまで症状なので、Podの一覧、ログ、describeと順に絞り込んでいく進め方で原因までたどり着けました。