ヘルスチェック

ヘルスチェックを使用したKeeperゲートウェイの監視

概要

本ページでは、KeeperPAMゲートウェイに実装されたヘルスチェック機能について取り扱います。ヘルスチェックは、システムの状態を常に把握できるモニタリング手法であり、よくある運用上の課題を効果的に解決できます。

ヘルスチェックを有効にすることで、以下のようなメリットがあります。

• ロードバランサーと連携し、不健全なインスタンスを自動的に待機系から除外し、回復後に再追加することが可能になります。

• Prometheus、Nagios、Datadogなどの監視システムと統合することで、ゲートウェイの状態を可視化するダッシュボードや、自動アラート通知を構築できます。

• 自動監視スクリプトやオーケストレーションツールと連携し、障害発生時の検知と回復処理を人手を介さずに実行できます。

これにより、システム全体の可用性と運用効率が大幅に向上します。

ヘルスチェックサービスはデフォルトで無効になっています。

使用するには、以降のセクションに記載の通り、サービスを有効にする必要があります。

---

シンプルなヘルスチェックの設定

以下の設定を行うことで、バイナリ版およびDocker版の両方で、基本的なヘルスチェックサービスを有効にできます。より高度な設定については、この後のセクションで詳しく取り扱います。

ヘルスチェックの有効化 - バイナリインストール方式

ヘルスチェック機能を有効にしてゲートウェイを起動します。

gateway start --health-check

ゲートウェイがヘルスチェックを有効にして起動した後、ゲートウェイの状態を確認できます。

gateway health-check

「Could not connect to health check server」というエラーが表示された場合、適切にヘルスチェックを有効にしなかったことを意味します。

「Exception No such command 'keeper-gateway.exe'」というエラーが表示された場合、コマンドの構文が間違っている可能性があります。コマンド名は常にgatewayを使用してください。

---

ヘルスチェックの有効化 – Dockerインストール方式

Dockerインストール方式でヘルスチェックを有効化するには、docker-compose.yml ファイルを以下のように修正します。

• KEEPER_GATEWAY_HEALTH_CHECK_ENABLED を追加

• healthcheck セクションを追加し、必要なチェック間隔を設定

keeper-gateway:
  ...
  environment:
    ...
    KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: 'true'
  healthcheck:
    test:
      - CMD
      - /usr/local/bin/keeper-gateway
      - health-check
    interval: 30s
    timeout: 10s
    retries: 3
    start_period: 60s
  ...
  restart: unless-stopped

docker-composeファイルを変更したら、以下のコマンドで変更を反映してコンテナを再起動します。

docker compose up -d

コンテナ名が keeper-gateway の場合、サービスステータスを確認するための1行bashコマンドは以下のとおりです。

docker inspect --format='{{.State.Health.Status}}' keeper-gateway

コンテナ名が不明な場合は、以下のスクリプトで取得できます。

docker ps --filter "status=running" --format "{{.Names}} {{.Image}}" | grep keeper-gateway | awk '{print $1}'

以下はbashコマンドでヘルスステータスを確認する例です。

$ docker inspect --format='{{.State.Health.Status}}' my-gateway-container
healthy

以下の完全なbashスクリプトをwatchdogサービスに追加することで、サービスステータスを監視し、異常時にコンテナを自動再起動できます。/path/to/ を適切なパスに置き換えます。

#!/bin/bash

LOGFILE="/path/to/keeper-watchdog.log"

# 実行中の keeper-gateway コンテナを検索
CONTAINER_NAME=$(docker ps --filter "status=running" --format "{{.Names}} {{.Image}}" | grep keeper-gateway | awk '{print $1}')

if [ -z "$CONTAINER_NAME" ]; then
  echo "$(date): 実行中の keeper-gateway コンテナが見つかりません。" >> "$LOGFILE"
else
  # ヘルスステータスを取得
  HEALTH=$(docker inspect --format='{{.State.Health.Status}}' "$CONTAINER_NAME")

  if [ "$HEALTH" != "healthy" ]; then
    echo "$(date): $CONTAINER_NAME の状態は $HEALTH です。再起動します..." >> "$LOGFILE"
    docker restart "$CONTAINER_NAME"
  else
    echo "$(date): $CONTAINER_NAME は正常です。" >> "$LOGFILE"
  fi
fi

# ログファイルを最新の100行にトリミング
tail -n 100 "$LOGFILE" > "$LOGFILE.tmp" && mv "$LOGFILE.tmp" "$LOGFILE"

このヘルスチェックをLinuxシステムでスケジュールするには、cronに追加します。

crontab -e

毎分監視を行うには、以下をcrontabに追加します。

* * * * * /path/to/watchdog.sh

---

高度なヘルスチェック構成の例

以下では、異なる環境におけるヘルスチェックのカスタマイズ方法をご紹介します。

構成	起動コマンド	CLIヘルスチェック	Curlヘルスチェック
基本的なHTTP	gateway start --health-check	gateway health-check	curl http://127.0.0.1:8099/health
認証付きHTTP	gateway start --health-check --health-check-auth-token mytoken	gateway health-check --token mytoken	curl -H "Authorization: Bearer mytoken" http://127.0.0.1:8099/health
HTTPS (SSL)	gateway start --health-check --health-check-ssl --health-check-ssl-cert /path/cert.pem --health-check-ssl-key /path/key.pem	gateway health-check --ssl	curl -k https://127.0.0.1:8099/health
認証付きHTTPS	gateway start --health-check --health-check-ssl --health-check-ssl-cert /path/cert.pem --health-check-ssl-key /path/key.pem --health-check-auth-token mytoken	gateway health-check --ssl --token mytoken	curl -k -H "Authorization: Bearer mytoken" https://127.0.0.1:8099/health
カスタムポート	gateway start --health-check --health-check-port 8443	gateway health-check --port 8443	curl http://127.0.0.1:8443/health
カスタムホスト	gateway start --health-check --health-check-host 0.0.0.0	gateway health-check --host 0.0.0.0	curl http://0.0.0.0:8099/health
本番環境のセットアップ	gateway start --health-check --health-check-host 0.0.0.0 --health-check-port 8443 --health-check-ssl --health-check-ssl-cert /etc/ssl/cert.pem --health-check-ssl-key /etc/ssl/key.pem --health-check-auth-token $(cat /etc/secrets/token)	gateway health-check --host 0.0.0.0 --port 8443 --ssl --token $(cat /etc/secrets/token)	curl -k -H "Authorization: Bearer $(cat /etc/secrets/token)" https://0.0.0.0:8443/health

出力形式の例

出力形式	CLIコマンド	説明
ステータスのみ	gateway health-check --ssl --token mytoken	ゲートウェイが実行中で接続されている場合は「OK」（終了コード0）、異常がある場合は「CRITICAL: ...」（終了コード1) を返します。
詳細情報	gateway health-check --ssl --token mytoken --info	監視スクリプトに適したkey=valueのペアを返します。
JSON形式	gateway health-check --ssl --token mytoken --json	HTTPエンドポイントに一致する完全なJSONレスポンスを返します。

トラブルシューティングコマンド

問題	テストコマンド	期待される結果
サーバーが実行中か確認	curl http://127.0.0.1:8099/health	接続成功または 「Connection refused」
SSL接続の確認	curl -k https://127.0.0.1:8099/health	SSLハンドシェイク成功またはSSLエラー
認証の確認	curl -k -H "Authorization: Bearer wrongtoken" https://127.0.0.1:8099/health	{"error": "Invalid authentication token"}
サーバーバインディングの確認	curl http://0.0.0.0:8099/health	バインドが0.0.0.0の場合は成功、127.0.0.1の場合は失敗

エラーメッセージとトラブルシューティング

CLIヘルスチェックを使用すると、問題を診断するための詳細なエラーメッセージが表示されます。

認証エラー (HTTP 401)

CRITICAL: Authentication failed when connecting to https://127.0.0.1:8099/health
ERROR: Invalid or missing authentication token.

Possible fixes:
1. Check if auth token is required:
   curl -k https://127.0.0.1:8099/health
2. Provide the correct auth token:
   gateway health-check --ssl --token YOUR_TOKEN
3. Check gateway startup logs for the configured token

接続エラー

CRITICAL: Could not connect to health check server at http://127.0.0.1:8099/health
ERROR: Connection failed.

Possible causes:
1. Health check server is not running
2. Wrong host/port combination
3. Network connectivity issues
4. SSL/non-SSL mismatch

Troubleshooting steps:
1. Verify gateway is running with health check enabled:
   gateway start --health-check
2. Check if server is using SSL:
   gateway health-check --ssl
3. Verify host and port:
   Current: 127.0.0.1:8099
4. Test with curl:
   curl http://127.0.0.1:8099/health

SSL証明書エラー

CRITICAL: SSL error connecting to health check server at https://127.0.0.1:8099/health
ERROR: SSL certificate validation failed.

Possible causes:
- Self-signed certificate (try curl with -k flag)
- Invalid certificate path
- Certificate expired

実装

ゲートウェイのヘルスチェックは、Bottleを使用して実装されています。Bottleは、Python用の軽量なWSGIマイクロウェブフレームワークです。以下の利点によりBottleが選ばれました。

• 最小限の依存関係 (単一ファイル、サイズは約60KB)

• Pythonの組み込みHTTPサーバーよりも強化されたセキュリティ

• 適切なリクエストのルーティングと処理

• 優れたエラーマネジメント

• スレッドセーフ

• 最小限のオーバーヘッドで本番環境に対応

CLIヘルスチェック

コマンドラインからゲートウェイのヘルスチェックを実行できます。

gateway health-check

このコマンドは次のような結果を返します。

• 終了コード0: ゲートウェイが正常な場合

• 終了コード1: ゲートウェイが実行中でない、または正常でない場合

• ステータスを示すテキスト (OK/CRITICAL/WARNING)

機械可読形式の詳細な出力 (1行につき1組のkey=value)

gateway health-check -i

JSON形式の出力 (HTTPエンドポイント形式と同等の構造)

gateway health-check -j

ヘルスチェックサーバーがSSLを使用している場合

gateway health-check --ssl

ヘルスチェックサーバーに認証が必要な場合

gateway health-check --ssl --token your_auth_token

ヘルスチェックサーバーがデフォルトのポート以外で動作している場合

gateway health-check --port 8123

ヘルスチェックサーバーが異なるホストで動作している場合

gateway health-check --host 10.0.0.5

詳細な出力に含まれる情報

• ゲートウェイのバージョン

• 接続状態

• WebSocketメトリクス (利用可能な場合)

• プロセス情報 (バックグラウンドモードの場合)

これにより、監視スクリプトやcronジョブに適した形式となります。

CLIヘルスチェックコマンドを使用するには、HTTPヘルスチェックサーバーを起動している必要があります。ヘルスチェックサーバーが起動していない場合はエラーメッセージが表示され、ヘルスチェックサーバーを有効にするよう案内されます。

---

HTTPヘルスチェック

ゲートウェイには、HTTPヘルスチェックエンドポイントが組み込まれており、環境変数またはコマンドライン引数を使って有効にできます。

設定

ヘルスチェックサーバーは、環境変数またはコマンドライン引数を使用して設定できます。

環境変数

環境変数	目的	デフォルト
KEEPER_GATEWAY_HEALTH_CHECK_ENABLED	HTTPヘルスチェックの有効化 (1、true、yesで有効)	無効
KEEPER_GATEWAY_HEALTH_CHECK_PORT	HTTPサーバーのポート	8099
KEEPER_GATEWAY_HEALTH_CHECK_HOST	バインドするホストアドレス	127.0.0.1
KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN	リクエスト用の認証トークン	なし
KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL	SSLの有効化 (1、true、yesで有効)	無効
KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT	SSL証明書のパス	なし
KEEPER_GATEWAY_HEALTH_CHECK_SSL_KEY	SSL秘密鍵のパス	なし

コマンドライン引数

ゲートウェイを起動する際、以下のコマンドライン引数も使用できます。

--health-check               Enable the health check server
--health-check-port INT      Port for the health check server (default: 8099)
--health-check-host STRING   Host address to bind to (default: 127.0.0.1)
--health-check-auth-token    Auth token for the health check server
--health-check-ssl           Enable SSL for the health check server
--health-check-ssl-cert      Path to SSL certificate
--health-check-ssl-key       Path to SSL private key

同じ設定が環境変数にも定義されている場合、コマンドライン引数が優先されます。

コマンド例

デフォルト設定での基本的なヘルスチェック

gateway start --health-check

カスタムポートと認証トークンを指定する場合

gateway start --health-check --health-check-port 9000 --health-check-auth-token mysecrettoken

すべてのインターフェースにバインド (安全が確保された環境でのみ推奨)

gateway start --health-check --health-check-host 0.0.0.0

SSLを有効にし、証明書と秘密鍵を指定する場合

gateway start --health-check --health-check-ssl --health-check-ssl-cert /path/to/cert.pem --health-check-ssl-key /path/to/key.pem

すべてのオプションを使用した完全な例

gateway start --health-check --health-check-port 8443 --health-check-host 10.0.0.5 --health-check-auth-token mysecrettoken --health-check-ssl --health-check-ssl-cert /path/to/cert.pem --health-check-ssl-key /path/to/key.pem

使用方法

ヘルスチェック機能を有効にすると、HTTPヘルスチェックエンドポイントは以下の場所で利用可能になります。

http://localhost:8099/health

SSLを使用した場合

https://localhost:8099/health

レスポンス形式

エンドポイントは次のようなレスポンスを返します。

• HTTP 200: ゲートウェイが正常な場合

• HTTP 503: ゲートウェイが正常でない場合

• 詳細な情報を含むJSONレスポンス

{
  "status": "healthy",
  "message": "Gateway is running and connected",
  "details": {
    "timestamp": 1742849941,
    "version": 1,
    "connection_status": "connected",
    "websocket": {
      "uptime_seconds": 85,
      "uptime_human": "1m 25s",
      "last_ping_received_seconds_ago": 10,
      "latency_ms": 75,
      "last_ping_sent_timestamp": 1742850455,
      "last_pong_received_timestamp": 1742850455
    }
  }
}

レスポンスに含まれる情報

• status: ゲートウェイの全体的な状態 (「healthy (正常)」または「unhealthy (異常)」)

• message: 状態を説明する簡潔な文章

• details: ゲートウェイに関する詳細情報

  • timestamp: レスポンス生成時のサーバーのタイムスタンプ

  • version: APIバージョン

  • connection_status: 接続状態 (「connected (接続済み)」、「disconnected (未接続)」など)

  • websocket: WebSocket接続のメトリクス

    • uptime_seconds: WebSocket接続の稼働時間 (秒単位)

    • uptime_human: 人間が読める形式の稼働時間 (「1m 25s」など)

    • last_ping_received_seconds_ago: 前回のping受信からの経過時間 (秒単位)

    • latency_ms: 最後のping-pongの往復遅延時間 (ミリ秒単位)

    • last_ping_sent_timestamp: 前回のping送信時刻 (Unixタイムスタンプ)

    • last_pong_received_timestamp: 前回のpong受信時刻 (Unixタイムスタンプ)

レスポンス例

正常なゲートウェイ

{
  "status": "healthy",
  "message": "Gateway is running and connected",
  "details": {
    "timestamp": 1742849941,
    "version": 1,
    "connection_status": "connected",
    "websocket": {
      "uptime_seconds": 85,
      "uptime_human": "1m 25s",
      "last_ping_received_seconds_ago": 10,
      "latency_ms": 75,
      "last_ping_sent_timestamp": 1742850455,
      "last_pong_received_timestamp": 1742850455
    }
  }
}

正常でないゲートウェイ

{
  "status": "unhealthy",
  "message": "Gateway is not properly connected (status: reconnecting)",
  "details": {
    "timestamp": 1742850874,
    "version": 1,
    "connection_status": "reconnecting",
    "websocket": {
      "uptime_seconds": 1018,
      "uptime_human": "16m 58s",
      "last_ping_received_seconds_ago": 324,
      "latency_ms": 77
    }
  }
}

latency_ms、last_ping_sent_timestamp、last_pong_received_timestamp などのメトリクスは、レスポンスに常に含まれるとは限りません。これらのメトリクスは、現在のWebSocket接続の状態やping/pongメッセージの送受信のタイミングによって異なります。

ステータス更新の遅延について

ヘルスチェックはWebSocket接続の現在の状態を反映しますが、ステータス更新に遅延が生じる場合があります。

ステータス更新の遅延例

接続が失われた場合、ゲートウェイが再接続を試みるため、ヘルスチェックが「unhealthy (異常)」 ステータスを報告するまで最大で2分かかることがあります。同様に接続が回復した場合でも、ヘルスチェックが「healthy (正常)」 ステータスを反映するまで最大で2分かかることがあります。

この遅延は、一時的な接続不良を即座に異常と判断しないための仕組みです。ゲートウェイが自動的に回復するための猶予を確保する目的で、意図的に設けられています。

セキュリティ

HTTPヘルスチェックを利用することで、以下のセキュリティ機能が適用されます。

1. 認証: KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN が設定されている場合、リクエストには Authorization ヘッダーにトークンを含める必要があります。

   Authorization: Bearer <token>

2. SSL/TLS: SSLが有効になっている場合、すべての通信は暗号化されます。有効な証明書と秘密鍵を提供する必要があります。

3. ローカルホストバインディング: サーバーはデフォルトでローカルホストにバインドされ、ネットワーク経由でエンドポイントは公開されません。

4. セキュリティヘッダー: ヘルスチェックサーバーからのレスポンスには、以下のセキュリティヘッダーが追加されます。

   • X-Content-Type-Options: nosniff

   • X-Frame-Options: DENY

   • Content-Security-Policy: default-src 'none'

5. レート制限: ローカルホスト以外の接続には自動的にレート制限が適用されます (1分あたり60リクエスト/IP）。

6. 情報保護: サーバーが非ローカルホストアドレスにバインドされている場合、機密情報はレスポンスから自動的に削除されます。

7. 強制SSL: 非ローカルホストインターフェースにバインドされると、SSLが自動的に強制されます。

TLSの互換性

ヘルスチェックサーバーは、さまざまなクライアントに対応できるよう、以下のように構成されています。

• TLS 1.2以上の安全なTLSデフォルト設定を使用し、セキュリティを最大限に確保

• 強力な暗号化を実現する最新の暗号スイートに対応

• HTTPおよびHTTPSのプロトコル交渉を自動的に処理

最新のTLSバージョンに対応したクライアントについては、以下のような標準的なcurlコマンドを使用できます。

curl -k -H "Authorization: Bearer your_token" https://localhost:8099/health

---

Docker特有の構成要件

KeeperゲートウェイをDocker内で実行する場合、ヘルスチェックをホストや外部システムから利用できるようにするには、以下の特別な設定が必要な場合があります。

0.0.0.0へのバインド

• ヘルスチェックサーバーをコンテナ外部からアクセス可能にするには、0.0.0.0にバインドする必要があります。

• 127.0.0.1にバインドした場合、アクセスはコンテナ内部のみに制限されます。

SSLの強制

• 0.0.0.0を使用する場合、Keeperゲートウェイはヘルスチェックデータを保護するためにSSLを強制します。

• 有効な証明書と秘密鍵を提供しない場合、サーバーは起動しません。

認証の必要性

• 0.0.0.0にバインドする場合、エンドポイントを保護するために、AUTH_TOKENを指定する必要があります。

Docker Composeの例

services:
  keeper-gateway:
    image: keeper/gateway:latest
    ports:
      - "8099:8099"
    volumes:
      - ./certs:/certs:ro
    environment:
      KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true
      KEEPER_GATEWAY_HEALTH_CHECK_HOST: "0.0.0.0"
      KEEPER_GATEWAY_HEALTH_CHECK_PORT: 8099
      KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL: true
      KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT: /certs/healthcheck.crt
      KEEPER_GATEWAY_HEALTH_CHECK_SSL_KEY: /certs/healthcheck.key
      KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN: mysecrettoken

自己署名証明書の作成

mkdir -p certs
openssl req -x509 -nodes -days 365 \
  -newkey rsa:2048 \
  -keyout certs/healthcheck.key \
  -out certs/healthcheck.crt \
  -subj "/CN=localhost"

ホストからエンドポイントをテスト

curl -k -H "Authorization: Bearer mysecrettoken" https://localhost:8099/health

---

Linux環境での構成例

# Enable HTTP health check
export KEEPER_GATEWAY_HEALTH_CHECK_ENABLED=true
export KEEPER_GATEWAY_HEALTH_CHECK_PORT=8099
export KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN=mysecrettoken

# Start the gateway
gateway start

コマンドライン引数を使用する場合

gateway start --health-check --health-check-port 8099 --health-check-auth-token mysecrettoken

自己署名SSL証明書の使用

テスト環境や内部利用の場合、自己署名証明書を生成してSSL/TLS暗号化を有効にすることができます。

# Generate a private key
openssl genrsa -out healthcheck.key 2048

# Generate a certificate signing request (CSR)
openssl req -new -key healthcheck.key -out healthcheck.csr -subj "/CN=localhost"

# Generate a self-signed certificate (valid for 365 days)
openssl x509 -req -days 365 -in healthcheck.csr -signkey healthcheck.key -out healthcheck.crt

# Set the environment variables
export KEEPER_GATEWAY_HEALTH_CHECK_ENABLED=true
export KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL=true
export KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT=/path/to/healthcheck.crt
export KEEPER_GATEWAY_HEALTH_CHECK_SSL_KEY=/path/to/healthcheck.key
export KEEPER_GATEWAY_HEALTH_CHECK_PORT=8443  # Typical HTTPS port
export KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN=mysecrettoken

# Start the gateway
gateway start

コマンドライン引数を使用する場合

gateway --health-check --health-check-port 8443 --health-check-ssl --health-check-ssl-cert /path/to/healthcheck.crt --health-check-ssl-key /path/to/healthcheck.key --health-check-auth-token mysecrettoken start

自己署名証明書を使用する場合、HTTPクライアントは証明書を信頼するように設定するか、SSL検証を無視するように設定する必要があります (本番環境では推奨されません）。

監視システムとの統合

このエンドポイントは、次のような監視システムと連携して使用できます。

• Prometheus (Blackbox exporter経由)

• Nagios/Icinga

• Zabbix

• Datadog

• AWS CloudWatch

• HTTPチェックが可能な任意の監視システム