Uptime Kuma の構築手順 | Docker で始める稼働監視
Docker で Uptime Kuma v2 を構築し、HTTP 監視、通知、ステータスページを設定します。アップグレード前の SQLite のバックアップ手順も解説します。
VPC 内で動く Uptime Kuma の画面では注文 API が正常でも、利用者は公開ゲートウェイでエラーに遭遇しているかもしれません。内側からの監視にも意味があります。正常だった経路を切り分けられるからです。設定を始める前に、どの障害をどのネットワークから検知するかを決めておきます。
Uptime Kuma はセルフホスト型の稼働監視ツールです。 定期チェックを実行して結果を通知し、選んだ監視項目をステータスページに公開できます。ここでは Docker に Uptime Kuma v2 を 1 台構成で入れ、そのインスタンスから HTTP チェックを実行します。
データはローカルのボリュームに置く
v2 イメージを実行できる Docker ホストを用意します。既定の SQLite を使う場合、/app/data には POSIX のファイルロックに対応したファイルシステムが必要です。ローカルのディレクトリかボリュームを使います。NFS では構成によってファイルロックに問題が起き、データベースが破損する可能性があります。公式インストールガイド(英語)
docker run -d --restart=unless-stopped \
-p 127.0.0.1:3001:3001 \
-v uptime-kuma:/app/data \
--name uptime-kuma \
louislam/uptime-kuma:2
コンテナを作り直しても、データはボリュームに残ります。再起動ポリシーは、ホストと Docker が動作している状態でコンテナが終了したときの復旧に使います。この例では 3001 番ポートをループバックにバインドしています。Docker Engine 28.0.0 より前のバージョンでは、同じレイヤー 2 ネットワークにある他のホストからループバックに公開したポートへ到達できる場合があります。Docker ホスト上で http://127.0.0.1:3001 を開き、管理者アカウントを作成します。別の端末から初期設定する場合は SSH トンネルを使います。HTTPS で公開する場合は、リバースプロキシが WebSocket のアップグレードを中継するよう設定します。Docker のポート公開(英語) · Kuma のリバースプロキシ設定(英語)
呼び出し元が必要とする応答を監視する
たとえば、読み取り専用の注文サービスの稼働確認用エンドポイントが、HTTP 200 と checkout-ready を返す仕様だとします。両方を確認するには HTTP(s) - Keyword を選びます。通常の HTTP 監視ではリクエストの成否と設定したステータスコードを確認します。Keyword では本文中の部分文字列も確認します。プロキシのエラーページには出ず、リリース後も変わらない目印を選びます。
| 監視タイプ | 成功時に確認できること |
|---|---|
| HTTP(s) / HTTP(s) - Keyword | 設定したステータス条件を満たした。Keyword では本文の条件も満たした。 |
| TCP Port | TCP 接続が確立した。データベースにログインしてクエリを実行できるかは別途確認する。 |
| Ping | このネットワークから送った ICMP に対象が応答した。ICMP を遮断するポリシーでもチェックは失敗する。 |
| DNS | 指定したリゾルバーが対象のレコードタイプに対して応答した。 |
| Docker Container | 設定した Docker ホストからコンテナの状態を取得でき、コンテナにヘルスチェックがある場合はその結果も判定に使われる。 |
Docker Container 監視には、設定した Docker エンドポイントへのアクセスが必要です。Docker デーモンへの接続はホスト上の強い権限につながるため、HTTP 監視とは分けてアクセス範囲を絞ります。v2.5.9 の監視実装 · Docker デーモンへのアクセス保護(英語)
障害と復旧の両方を通知させる
チェック間隔、リクエストのタイムアウト、リトライ回数と間隔を設定します。リトライを増やすと短時間の失敗は通知前に収まることがありますが、障害の検知も遅くなります。通常の HTTP 監視にリトライを設定すると、失敗後に Pending を経て Down と判定される場合があります。
通知先を設定してテストメッセージを送り、対象の監視項目でその通知先を有効にします。次にテスト用エンドポイントでステータスを失敗に変えるか、本文から目印を外して Down になるまで待ちます。正常応答に戻し、障害通知と復旧通知が意図した宛先に届くことを確認します。これで通知先への疎通に加え、監視項目から通知までの経路も確認できます。
ステータスページに載せる項目を選ぶ
利用者に公開したいサービスの監視項目を選び、運用チーム以外にも伝わる名前を付けます。共有する前に、ログアウトしたブラウザーでグループ、直近の履歴、インシデントの説明を確認します。同じ Kuma インスタンスが配信するステータスページは、そのインスタンスが停止すれば影響を受けます。
利用者が公開ゲートウェイを経由するなら、内部の Kuma 監視を残し、公開経路を別の地点から HTTP でチェックします。Guance の HTTP 合成監視では、公開のテストノードを選び、内部監視と同じステータスと目印を指定できます。外側だけ失敗したときは、DNS、TLS、ゲートウェイまでの経路を比べます。アプリケーションのログやトレースを別途収集しておくと、失敗したリクエストがどこまで届いたかを追えます。Kuma v2 には、外部の観測点を使える専用の Globalping 監視タイプもあります。この例で使う通常の HTTP と TCP の監視は、Kuma インスタンスから発信されます。
プライベートサービスを監視する場合は、対象に到達できるネットワークに Kuma を置きます。Kuma 自体の停止を検知するには、別のホストから到達可能な HTTPS ページか独立したハートビートを監視し、Kuma が停止しても届く通知経路を使います。ポートの TCP チェックで分かるのは接続できるかどうかです。稼働監視で分かること
アップグレード前にボリュームをバックアップする
上のようなローカルの SQLite 構成では、書き込み元のコンテナを停止し、データディレクトリ全体をアーカイブします。この間は監視と同じインスタンスが配信するステータスページが一時停止します。バックアップを書き込めるディレクトリで実行します。
docker stop uptime-kuma &&
docker run --rm \
-v uptime-kuma:/data:ro -v "$PWD:/backup" \
busybox:1 tar -czf /backup/kuma-backup.tar.gz -C /data . &&
tar -tzf kuma-backup.tar.gz &&
docker start uptime-kuma
アーカイブの作成や確認に失敗した場合は、docker start uptime-kuma を実行して監視を再開し、アップグレードの前にバックアップをやり直します。確認できたアーカイブは、Docker ホストとは別の場所にも保存します。外部データベースを使っている場合はそちらも別途バックアップします。v1 から v2 に移行する際は、バックアップ後も v1 を停止したまま、既存のボリュームを指定してコンテナを v2 で作り直し、移行ログを確認します。SQLite ボリュームに書き込むインスタンスは 1 台にします。元に戻す場合は移行前のアーカイブを別のボリュームに復元して旧バージョンを起動します。公式ガイドでは v1 からの初回移行に rootless イメージの使用を推奨していません。v1 から v2 への移行手順(英語)
