Kubernetes のヘルスチェック:liveness・readiness・startup プローブ

Kubernetes の3種類のプローブを使い分け、監視先と判定間隔を設定します。Pod のイベントと終了理由から再起動の原因を絞ります。

ベストプラクティス
クラスターとワークロードの接続を表すイラスト

決済サービスをロールアウトすると、新しい Pod のプロセスは立ち上がっても、キャッシュの準備が済んでいないことがあります。この段階でリクエストを送ればエラーになりかねません。再起動すれば準備を中断することになります。Kubernetes では、この二つの判断を別々のプローブで扱います。

readiness はリクエストを処理できるか、liveness は再起動で回復できる障害があるかを見ます。起動に時間がかかるコンテナには、startup で別の猶予を設けます。以下の設定は spec.containers[] の同じコンテナに記述する断片です。アプリケーションは 8080 番ポートで /healthz と /ready を提供するものとします。

失敗したときに何を起こすか

liveness は、動いているように見えて処理が先へ進まないプロセスを検出します。 連続失敗がしきい値に達すると、kubelet はコンテナを停止し、適用される再起動ポリシーに従います。/healthz はローカルの処理が進むかを確かめる軽いチェックにします。共有データベースが止まったときに全レプリカを再起動すると、データベースは復旧せず、再起動直後の負荷と再接続が重なります。

livenessProbe:
  httpGet:
    path: /healthz
    port: 8080
  initialDelaySeconds: 10
  periodSeconds: 10
  failureThreshold: 3

readiness は、通常の Service トラフィックを受けられるかを判定します。 連続失敗がしきい値に達すると、kubelet はコンテナを未準備と判定します。Pod の Ready 条件にはコンテナの状態と設定済みの readiness gate が反映されます。セレクターを使う通常の Service では、EndpointSlice にエンドポイントが残り、ready: false になることがあります。ルーティングへの反映には時間差があり、既存の接続をプローブが切断するわけではありません。Pod に直接接続する通信も別経路です。準備完了前のアドレスを公開する Service では publishNotReadyAddresses の設定を確認します。EndpointSlice の条件(英語)

readinessProbe:
  httpGet:
    path: /ready
    port: 8080
  periodSeconds: 5
  failureThreshold: 2

readiness には、そのレプリカが実際に提供できる処理を反映します。必須の依存先が使えず、リクエストを処理できないなら、未準備と判定する理由になります。一方、障害時にも全レプリカがキャッシュから結果を返せるなら、すべてを経路から外すと使える代替手段まで失われます。定期的なチェック自体も軽く保ちます。

startup が成功するまで、kubelet は同じコンテナの liveness と readiness を実行しません。 起動プローブを実行するのはコンテナの起動時です。連続失敗がしきい値に達した場合はコンテナを停止し、再起動ポリシーを適用します。10 秒間隔で失敗しきい値が 30 回なら、起動におよそ 5 分を見込めます。初回チェックの時刻、スケジューリング、チェック自体の所要時間で実際のタイミングは変わります。

startupProbe:
  httpGet:
    path: /healthz
    port: 8080
  periodSeconds: 10
  failureThreshold: 30

何を確認できるプローブかを選ぶ

方式 成功の条件 注意点
HTTP GET ステータスコードが 200–399 通常、kubelet は Pod IP に接続します。ヘルスチェックのパスから直接応答を返します。HTTPS でも証明書は検証しません。
TCP 接続を確立できる アプリケーションがすぐに切断しても成功します。kubelet がノードから接続するため、クライアント Pod からのリクエストとは経路が異なります。
Exec コマンドの終了コードが 0 軽いコマンドを使い、パイプやリダイレクトが必要ならシェルを明示します。Pod が多いと、頻繁なプロセス起動が負荷になります。
gRPC ヘルスサービスが SERVING を返す gRPC Health Checking Protocol を実装します。組み込みプローブは数値ポートを使い、既定では平文で接続します。チェックを区別する場合は任意の service を指定できます。

HTTP と TCP では名前付きのコンテナポートを使えます。組み込み gRPC プローブは Kubernetes v1.27 から安定版です。v1.37 では TLS がアルファ機能として追加されました。使うには既定で無効な GRPCContainerProbeTLS を有効にします。このモードではサーバー証明書の検証は行われません。gRPC プローブの TLS(英語)

HTTP のヘルスチェックは小さなレスポンスを返し、リダイレクトを避けます。別ホストへのリダイレクトは追跡されず、警告付きで成功扱いになることがあります。Kubernetes のプローブ設定(英語)

検出の速さと誤判定のバランスを取る

既定値は initialDelaySeconds: 0、periodSeconds: 10、timeoutSeconds: 1、failureThreshold: 3、successThreshold: 1 です。liveness と startup の successThreshold は 1 が必須です。準備ができていない間は、設定した間隔を待たず readiness が実行されることがあります。startup による待機と初期遅延はどちらも関係します。Kubernetes v1.36.0 の worker はコンテナが Running になった時刻から初期遅延を測るため、startup の成功時にその計時が始まるとは限りません。プローブの既定値(英語) · Kubelet v1.36.0 のソース

ピーク時に /healthz がときどき 1 秒を超えるなら、設定を変える前に応答時間を測ります。以下はチェックごとに 3 秒を許容し、3 回連続で失敗したときに停止を指示する設定です。復旧時間の要件に合えば、先の liveness の断片と置き換えます。チェックの所要時間、実行間隔、終了猶予期間も、新しいコンテナが動き出すまでの時間に影響します。

livenessProbe:
  httpGet: {path: /healthz, port: 8080}
  periodSeconds: 15
  timeoutSeconds: 3
  failureThreshold: 3

再起動とルーティングの症状を切り分ける

CrashLoopBackOff は再起動を待っている状態です。原因を調べるには、以下の読み取り専用コマンドの名前空間、Pod、コンテナ名を実際の値に替えます。対象コンテナの Last State、終了理由、時刻を一つ前のコンテナログと照合し、同じ時間帯の Pod イベントを確認します。

NS=shop
POD=checkout-abc
CONTAINER=checkout

kubectl -n "$NS" describe pod "$POD"
kubectl -n "$NS" logs "$POD" -c "$CONTAINER" --previous
kubectl -n "$NS" get events --field-selector "involvedObject.kind=Pod,involvedObject.name=$POD" --sort-by=.metadata.creationTimestamp

startup または liveness の失敗直後にコンテナが停止していれば、プローブによる終了が疑われます。終了理由が OOMKilled ならメモリを調べます。readiness の失敗でも Unhealthy イベントが出るため、イベントの理由だけでは区別できません。Pod が動き続けているのに通常の経路から外れた場合は、readiness と Service の EndpointSlice を見ます。

kubectl -n shop get endpointslice -l kubernetes.io/service-name=checkout -o yaml

API サーバーの --event-ttl は既定で 1 時間です。保持期間はクラスターの設定に従います。長い時間軸で追う必要があれば、DataKit の Kubernetes イベント収集(英語)を有効にし、対象の名前空間を読み取れるか確認します。involved_namespace、involved_name、イベント時刻を対象コンテナのログや状態と突き合わせます。これで、直近の readiness の揺れを以前の再起動の原因と取り違えにくくなります。Pod のライフサイクル(英語) · API サーバー設定(英語)

関連記事 · Kubernetes のアーキテクチャ · Helm で Kubernetes に Prometheus を導入する

最適なプランを相談する

お問い合わせ

コミュニティに参加

WeChatでスキャンして
コミュニティに参加

Guanceを試す

オンラインですぐに始めて、使った分だけお支払いください。

利用を開始

Guanceのプランを選択

コードリポジトリ