KuberhealthyでKubernetesの合成チェックをPod化する

コントローラーが短命Podを起動する

Kuberhealthyは合成モニタリングと継続的検証のためのKubernetesオペレーターです。HealthCheckカスタムリソースを監視し、指定された間隔でチェッカーPodを起動します。Podが検証ロジックを実行して結果をKuberhealthyへ報告し、ステータスUI、JSON API、Prometheusメトリクスで読める流れです。

チェックが成功することだけでなく、短命Podが作られ、完了し、次の実行で再利用されないことを確認します。チェック用コンテナがアクセスするnamespace、Secret、サービス、外部APIを洗い出し、監視対象への書き込みを必要最小限にします。

HelmとKustomizeから選ぶ

READMEはHelm、Kustomize、ArgoCDによる導入を案内します。Helmなら`helm install kuberhealthy deploy/helm/kuberhealthy -n kuberhealthy --create-namespace`、Kustomizeなら`kubectl apply -k github.com/kuberhealthy/kuberhealthy/deploy/kustomize/base?ref=main`を使います。ArgoCD向けには`kubectl apply -f deploy/argocd/kuberhealthy.yaml`があります。

導入後は`kubectl -n kuberhealthy port-forward svc/kuberhealthy 8080:80`でUIを開きます。適用したマニフェストの版、namespace、Service、RBACを保存し、削除と再適用でHealthCheck定義や結果の扱いがどう変わるかを検証します。

HealthCheckの周期とPod仕様

HealthCheckのspecには`runInterval`、`timeout`、`podSpec`があります。READMEのdeployment check例はテスト用Deploymentを作成し、ロールアウトを待ち、最後に破棄します。イメージは`docker.io/kuberhealthy/deployment-check:v0.1.1`で、レプリカ数やローリング更新を環境変数で指定します。

`kubectl get healthcheck`または`kubectl get hc`で登録状態を確認できます。周期を短くするほど対象サービスとクラスターへの操作が増えるため、チェックの実行時間、タイムアウト、リソースrequestsとlimitsを合わせて決めます。失敗時に作成途中のリソースが残らないかも観察します。

JSONとPrometheusで結果を読む

`/metrics`はPrometheus向けの形式で、check、namespace、statusなどのラベルを含みます。READMEの例には`kuberhealthy_check`と`kuberhealthy_check_duration_seconds`があり、成功状態と実行時間を別々に扱えます。`/json`は`ok`、`lastRun`、`runDuration`を含むchecksマップを返します。

導入確認ではUIの色だけを判断材料にせず、同じチェックをJSONとメトリクスで照合します。意図的な失敗を作り、statusが変わること、実行時間が記録されること、復旧後に状態が戻ることを確認します。Prometheusのラベル数が増えすぎないcheck名とnamespace設計も必要です。

任意の言語で独自チェックを書く

チェックはコンテナなので、コンテナに収まる言語で記述できます。READMEはGo、Python、Rust、bashなどを例に挙げ、Goでは`github.com/kuberhealthy/kuberhealthy/v3/pkg/checkclient`で成功または失敗を報告します。クライアントは`KH_REPORTING_URL`と`KH_RUN_UUID`を使い、期限も扱います。

作成手順は`docs/CHECK_CREATION.md`と`docs/CHECKS_REGISTRY.md`に委ねられています。独自チェックでは入力、認証、クリーンアップ、タイムアウトを明確にし、成功時だけでなく途中失敗時にも報告が送られるかを試します。コンテナイメージの版を固定して再現性を保ちます。

Apache 2.0と運用上の境界

KuberhealthyはApache 2.0ライセンスです。READMEはドキュメント索引、採用者、貢献ガイド、Slack、月例会議への入口を示しますが、具体的な本番性能、SLA、セキュリティ保証は記載していません。採用者の存在を自分のクラスターとの互換性の証拠にしてはいけません。

向くのは、Kubernetesマニフェストとコンテナを管理でき、実際の利用操作を定期確認したいチームです。最初に一つのHealthCheckでPod生成、レポート、Prometheus取得、失敗復旧を確かめ、次に外部APIやデータ変更を伴うチェックへ広げます。

失敗するチェックを安全に作る

専用namespaceへKuberhealthyを導入し、deployment checkを一つ登録します。`kubectl get hc`でHealthCheckを確認し、短命Podの生成、完了、結果報告を追います。`kubectl -n kuberhealthy port-forward svc/kuberhealthy 8080:80`を使い、UI、`/json`、`/metrics`で同じ実行を照合します。

存在しないDeploymentを指定してtimeoutと失敗メトリクスを確認し、復旧後に状態が戻るかを調べます。独自チェックは`KH_REPORTING_URL`と`KH_RUN_UUID`をテスト用値で渡し、報告先停止やコンテナ終了でも正しい失敗になることを確かめてから本番namespaceへ移します。

チェックの副作用を消してから広げる

ログインやレコード作成を含むチェックは、テスト用アカウントとnamespaceを使い、成功時だけでなくタイムアウト時にもクリーンアップが走るかを確認します。Podのrequestsとlimits、runInterval、timeoutを記録し、短い周期で同じ外部操作が重ならないことを見ます。Prometheusのcheckとnamespaceラベル、JSONのlastRunを保存し、通知が復旧後に解消することを確認してから本番データへ近づけます。 導入前には、テスト用Podの作成、失敗、復旧を繰り返し、メトリクスとJSONの時刻を照合します。 チェック用Podの削除後にHealthCheckが次の実行を作ることも確認します。 さらに、チェックが複数namespaceへ広がった場合のラベル、リソース上限、通知の重複も確認します。 実行間隔を変えたときのPod数とPrometheusの時系列を照合し、Kubernetesのアップグレード後にも同じHealthCheckが動くことを確認します。 本番へ広げる前に、チェック用ServiceAccountの権限、Podの終了後に残るイベント、失敗通知の遅延、復旧通知の条件を確認します。チェック自体が監視対象へ負荷を与えない周期を選び、変更したマニフェストとイメージ版を保存します。を確認し、記録します。

編集部の結論

Kubernetes上のログイン、API、デプロイ、クリーンアップなどを実際の操作に近いチェックとして定期実行したいチームに向きます。単なるPodの死活監視とは違い、短命Podの権限と外部サービスへの影響を設計する必要があります。まず専用namespaceでHealthCheckを一つ動かし、`/json`、`/metrics`、Podログ、タイムアウト、失敗後の再実行を確認してください。

公式情報源

1. Official documentation
2. Official README
3. Project repository
4. Release notes