# ヘルスチェック ## 概要 本ページでは、KeeperPAMゲートウェイに実装されたヘルスチェック機能について取り扱います。ヘルスチェックは、システムの状態を常に把握できるモニタリング手法であり、よくある運用上の課題を効果的に解決できます。 ヘルスチェックを有効にすることで、以下のようなメリットがあります。 * ロードバランサーと連携し、不健全なインスタンスを自動的に待機系から除外し、回復後に再追加することが可能になります。 * Prometheus、Nagios、Datadogなどの監視システムと統合することで、ゲートウェイの状態を可視化するダッシュボードや、自動アラート通知を構築できます。 * 自動監視スクリプトやオーケストレーションツールと連携し、障害発生時の検知と回復処理を人手を介さずに実行できます。 これにより、システム全体の可用性と運用効率が大幅に向上します。 {% hint style="warning" %} ヘルスチェックサービスは**デフォルトで無効**になっています。 使用するには、以降のセクションに記載の通り、サービスを有効にする必要があります。 {% endhint %} *** ## シンプルなヘルスチェックの設定 以下の設定を行うことで、バイナリ版およびDocker版の両方で、基本的なヘルスチェックサービスを有効にできます。より高度な設定については、[この後のセクション](#naherusuchekkuno)で詳しく取り扱います。 ### ヘルスチェックの有効化 - バイナリインストール方式 ヘルスチェック機能を有効にしてゲートウェイを起動します。 ``` 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 セクションを追加し、必要なチェック間隔を設定 ```yaml 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ファイルを変更したら、以下のコマンドで変更を反映してコンテナを再起動します。 ```bash docker compose up -d ``` コンテナ名が keeper-gateway の場合、サービスステータスを確認するための1行bashコマンドは以下のとおりです。 ```bash docker inspect --format='{{.State.Health.Status}}' keeper-gateway ``` コンテナ名が不明な場合は、以下のスクリプトで取得できます。 {% code overflow="wrap" %} ```bash docker ps --filter "status=running" --format "{{.Names}} {{.Image}}" | grep keeper-gateway | awk '{print $1}' ``` {% endcode %} 以下はbashコマンドでヘルスステータスを確認する例です。 ```bash $ docker inspect --format='{{.State.Health.Status}}' my-gateway-container healthy ``` 以下の完全なbashスクリプトをwatchdogサービスに追加することで、サービスステータスを監視し、異常時にコンテナを自動再起動できます。`/path/to/` を適切なパスに置き換えます。 ```bash #!/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に追加します。 ```bash crontab -e ``` 毎分監視を行うには、以下をcrontabに追加します。 ```bash * * * * * /path/to/watchdog.sh ``` *** ## 高度なヘルスチェック構成の例 以下では、異なる環境におけるヘルスチェックのカスタマイズ方法をご紹介します。 | 構成 | 起動コマンド | CLIヘルスチェック | Curlヘルスチェック | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ | | **基本的なHTTP** | gateway start --health-check | gateway health-check | curl | | **認証付きHTTP** | gateway start --health-check --health-check-auth-token mytoken | gateway health-check --token mytoken | curl -H "Authorization: Bearer mytoken" | | **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** | 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" | | **カスタムポート** | gateway start --health-check --health-check-port 8443 | gateway health-check --port 8443 | curl | | **カスタムホスト** | gateway start --health-check --health-check-host 0.0.0.0 | gateway health-check --host 0.0.0.0 | curl | | **本番環境のセットアップ** | 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)" | ### 出力形式の例 | 出力形式 | 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 | 接続成功または 「Connection refused」 | | **SSL接続の確認** | curl -k | SSLハンドシェイク成功またはSSLエラー | | **認証の確認** | curl -k -H "Authorization: Bearer wrongtoken" | {"error": "Invalid authentication token"} | | **サーバーバインディングの確認** | curl | バインドが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](https://bottlepy.org/docs/dev/)を使用して実装されています。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 ``` 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チェックが可能な任意の監視システム --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.keeper.io/jp/keeperpam/privileged-access-manager/getting-started/gateways/health-checks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.