ヘルスチェックと readiness

オーケストレータが知りたいことは 2 つあり、それは別々の問いです。このプロセスは生きているか、殺して置き換えるべきか。 そしてこのプロセスはいまトラフィックを受けられるか。 ローリングデプロイの最中には答えが食い違います。だからエンドポイントも 2 つです。

[server]
health = "/healthz"
readiness = "/readyz"

どちらのキーにも既定値がありません。/healthz で応答するアプリケーションは、その事実を設定を読む運用者の目に入る場所に書くべきです。既定値があると、リポジトリのどのファイルにも書かれていないエンドポイントが動き続けることになります。キーを設定しなければ、ルートはまったく登録されません。

pw init は両方を config.dev.toml に書きます。生成直後のプロジェクトは開発環境ではこれらを持ち、他の環境については明示的に宣言することになります。

それぞれが答えること

health は liveness です。 何も検査せず、何にも依存しません。プロセスが接続を受け付けてハンドラを実行できるなら 200 を返します。これが正しい定義です。依存先の障害はアプリケーションを殺して再起動する理由にはなりませんし、データベースが落ちたときに失敗する liveness プローブは、ひとつの障害を再起動ループに変えてしまいます。

readiness は設定されたデータベースプールすべてに ping します。 グループ集合の各接続、あるいは単一のプールに対して、検査全体で 1 秒の上限を設けて実行します。応答しないプールがひとつでもあればこのエンドポイントは 503 になり、オーケストレータは回復するまでこのインスタンスへのルーティングをやめます。

それ以外の挙動は共通です。


メソッド	`GET` と `HEAD`。それ以外は `Allow` 付きの `405`
成功	`200`、ボディは `ok`
失敗	`503`、ボディは `unavailable`
Content-Type	`text/plain; charset=utf-8`
Cache-Control	`no-store`

ボディが一語なのは意図的です。これらのエンドポイントはセッションと認証を迂回するので、ポートに到達できるものなら何でも到達できます。だから返すのは状態だけであり、DSN も、バックエンド名も、スタックトレースも、設定値も返しません。認証されていない相手にインフラの形を漏らすプローブは、それが検出するために追加された問題より悪い問題です。

シェルの無いコンテナからのプローブ

Docker の HEALTHCHECK はコンテナ内でコマンドを実行します。よく使われるコマンドは curl です。ところが distroless や scratch のイメージ——Go バイナリの正しい配布形——には curl も、それを起動するシェルもありません。命令に呼ぶものが無いのです。その役はアプリケーションのバイナリ自身が務めます。

HEALTHCHECK CMD ["/myapp", "healthcheck"]

このサブコマンドはサーバと同じ設定ソース——TOML ファイル、環境変数、PORT——を読みます。だからポートと health のパスを Dockerfile に書き直す必要はありません。ループバックに GET を 1 回発行し、2xx なら終了コード 0。それ以外——別のステータス、接続拒否、タイムアウト——は 1 で終了し、Docker はこれを unhealthy と数えます。終了コード 2 は使いません。Docker が予約しているからです。

プローブを調整するオプションは 2 つです。--ready は代わりに readiness のパスを叩きます。判定にデータベースプールが含まれるようになるので、依存サービスにデータベース接続済みのインスタンスを待たせたい場面には適切で、再起動ポリシーには厳しすぎます。データベースの障害が再起動ループに変わってしまうからです。--timeout はプローブ全体を制限し、既定は 3s。Docker 自身の既定である 30 秒より十分内側なので、固まったリスナは「プローブごと殺されて何も報告されない」のではなく unhealthy として報告されます。

プローブには、その環境の設定に server.health(--ready なら server.readiness)と固定の server.port が必要です。パスが未設定、あるいはポートが 0 なら、キーの名前を挙げたメッセージとともに失敗します。サブコマンド名は予約されています。アプリケーションが healthcheck という名前を独自コマンドに使おうとすると、 pw.RegisterSubCommand は起動時にパニックします。

Dockerfile

プローブはイメージがすでに載せているバイナリそのものです。だから命令は exec 形式のまま書けて、シェルを要求しません。

HEALTHCHECK --interval=30s --timeout=5s --start-period=5s \
  CMD ["/app/myapp", "healthcheck"]

Docker の --timeout=5s はコマンド全体を待つ時間です。プローブ自身の既定 3s はその内側で終わるので、判定はつねにプローブの終了コードであり、kill されることはありません。その環境の設定には server.health が必要です。キーが無ければプローブはその名前を挙げて失敗するので、設定ミスは「永遠に気づかない」のではなく最初のインターバルで表面化します。

pw init はこの行を含む Dockerfile を、キーを設定した config.prod.toml と一緒に書きます。そのファイルの残りの部分 — Popcorn Web のイメージが COPY と go build では作れない理由を含めて — はコンテナイメージにあります。

Compose

Compose の healthcheck.test にも同じ exec 形式を書きます。そして --ready が本領を発揮するのはここです。depends_on の service_healthy は依存サービスを待たせますが、「背後のデータベースが応答する」ことを意味すべきゲートは liveness ではなく readiness のパスです。

services:
  app:
    image: myapp:latest
    environment:
      PORT: "8080"
    healthcheck:
      test: ["CMD", "/myapp", "healthcheck", "--ready"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 10s
  importer:
    image: myapp:latest
    command: ["import", "/data/users.csv"]
    depends_on:
      app:
        condition: service_healthy

ここで宣言した healthcheck はイメージの HEALTHCHECK 行を上書きします。イメージは docker run 向けに素の liveness プローブを持ったまま、Compose は依存グラフが必要とする、より厳しい問いを投げられます。

Kubernetes

Kubernetes は HEALTHCHECK を完全に無視し、コンテナの外側から HTTP でプローブします。だからマニフェストにサブコマンドは登場しません。プローブをエンドポイントそのものに向けてください。

containers:
  - name: app
    image: myapp:latest
    ports:
      - containerPort: 8080
    env:
      - name: APP_ENV
        value: prod
    livenessProbe:
      httpGet:
        path: /healthz
        port: 8080
    readinessProbe:
      httpGet:
        path: /readyz
        port: 8080

対応は 1 対 1 です。health に向けた livenessProbe はプロセス自身が応答しなくなったときだけ Pod を再起動し、readiness に向けた readinessProbe はプールが応答するまで Pod を Service から外します。HEALTHCHECK 行を持つイメージをここで使っても害はありません。単に実行されないだけです。

OpenAPI エンドポイント

[server]
openapi = "/openapi.json"
api_doc = "scalar"
api_doc_path = "/docs"

同じリスナが、生成された OpenAPI 文書とその上の UI も配信できます。どちらもプローブと同じ規則に従います——既定のパスは無く、キーを設定しなければ何も配信しません。api_doc はさらに openapi を必要とします。誰も配信していない文書の UI には、描くものがありません。

違うのはアクセスです。プローブはあらゆる拡張より上で応答します。だから構造上、認証を通りません。一方でドキュメントのエンドポイントは拡張チェインの内側にあり、セッションと認証ガードは、アプリケーションのルートに届くのとまったく同じようにそこへ届きます。

[auth.protection]
include = ["/openapi.json", "/docs"]

保護はオプトインなので、列挙していないパスは公開のままです。ただし認証するテストは、自分のルートを読むのと同じやり方でこの文書を読めるようになりますし、閉じたデプロイは API の記述をプライマリリスナから動かすことなくログインの後ろに置けます。

それでも環境ごとに設定する価値はあります。pw init が api_doc = "scalar" を書くのは config.dev.toml だけで、既定値は空です。ステージングや本番の設定が意図的に有効化するまで、リファレンスは非公開のままになります。API ドキュメントと、公開されたドキュメントエンドポイントをデプロイ環境向けの readiness の指摘として報告する pw doctor を参照してください。

衝突は起動時に失敗する

すべての運用エンドポイントのパスは、リスナが開く前にアプリケーションのルートと突き合わせて検証されます。有効なエンドポイントと衝突するルートは、黙って覆い隠されるのではなく起動エラーになります。誤ったハンドラを見ていたプローブから知るのではなく、デプロイの時点で分かります。

停止するとき

SIGINT または SIGTERM を受けると、サーバは新しい接続の受け付けをやめ、処理中のリクエストを終わらせます。上限はこれです。

[server]
shutdown_timeout = "10s"

その後、ランタイムのリソース——データベースプールと、クリーンアップに登録されたその他のもの——が同じ上限のもとで閉じられます。

タイムアウト時点でまだ処理中のリクエストは打ち切られます。値は通常のリクエストのうち最も遅いものに合わせてください。そしてストリームは、それよりはるかに長く開いたままでいるよう設計されていることを思い出してください。長時間のストリームは停止によって終了させられ、クライアント側が再接続する前提です。

readiness エンドポイントは、停止が始まっても失敗し始めるわけではありません。ドレインはオーケストレーターが、トラフィックを止めてからシグナルを送ります。シグナルが届く頃には、リスナはすでに閉じ始めています。