ヘルスチェック

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

概要

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

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

• ロードバランサーと連携し、不健全なインスタンスを自動的に待機系から除外し、回復後に再追加することが可能になります。
• Prometheus、Nagios、Datadogなどの監視システムと統合することで、ゲートウェイの状態を可視化するダッシュボードや、自動アラート通知を構築できます。
• 自動監視スクリプトやオーケストレーションツールと連携し、障害発生時の検知と回復処理を人手を介さずに実行できます。

ネイティブインストール (Windows、Linux) では、ヘルスチェックサービスはデフォルトで無効です。以降のセクションに記載のとおり、サービスを有効にする必要があります。

---

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

以下の設定を行うことで、バイナリ版およびDocker版の両方で、基本的なヘルスチェックサービスを有効にできます。より高度な設定については、高度な構成もご参照ください。

ヘルスチェックの有効化

ゲートウェイでヘルスチェックサービスを有効にするには、以下のCLIプロパティ / 環境変数を追加します。

ENV

KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: 'true'

ゲートウェイ環境変数の構成方法をご参照ください。

Docker Composeファイルでは、合わせて 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

CLI

--health-check

ゲートウェイCLI引数の構成方法をご参照ください。

---

ヘルスチェックの確認

有効化後、ゲートウェイのヘルスチェックを確認します。

CLI

ネイティブのWindowsおよびLinuxインストールでは、ゲートウェイCLIでヘルスチェックを確認できます。

gateway health-check
>> OK: Gateway is running and connected

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

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

Docker

Dockerインストールでは、Dockerの inspect メソッドでヘルスチェックを取得できます。

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

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

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

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/ を適切なパスに置き換えます。

watchdog.sh

#!/bin/bash

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

# Find running container matching 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): No running keeper-gateway container found." >> "$LOGFILE"
else
  # Get health status
  HEALTH=$(docker inspect --format='{{.State.Health.Status}}' "$CONTAINER_NAME")

  if [ "$HEALTH" != "healthy" ]; then
    echo "$(date): $CONTAINER_NAME is $HEALTH. Restarting..." >> "$LOGFILE"
    docker restart "$CONTAINER_NAME"
  else
    echo "$(date): $CONTAINER_NAME is healthy." >> "$LOGFILE"
  fi
fi

# Trim log file to last 100 lines
tail -n 100 "$LOGFILE" > "$LOGFILE.tmp" && mv "$LOGFILE.tmp" "$LOGFILE"

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

crontab -e

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

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

---

高度な構成

以下では、異なる環境におけるヘルスチェックのカスタマイズ方法について詳しく取り扱います。

ヘルスチェックの有効化

ENV

構成	起動コマンド
基本的なHTTP	KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true
認証付きHTTP	KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN: mytoken
HTTPS (SSL)	KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL: true KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT: /path/cert.pem KEEPER_GATEWAY_SSL_KEY: /path/key.pem
認証付きHTTPS	KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL: true KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT: /path/cert.pem KEEPER_GATEWAY_SSL_KEY: /path/key.pem KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN: mytoken
カスタムポート	KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true KEEPER_GATEWAY_HEALTH_CHECK_PORT: 8443
カスタムホスト	KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true KEEPER_GATEWAY_HEALTH_CHECK_HOST: 0.0.0.0
本番環境のセットアップ	KEEPER_GATEWAY_HEALTH_CHECK_ENABLED: true KEEPER_GATEWAY_HEALTH_CHECK_USE_SSL: true KEEPER_GATEWAY_HEALTH_CHECK_SSL_CERT: /path/cert.pem KEEPER_GATEWAY_SSL_KEY: /path/key.pem KEEPER_GATEWAY_HEALTH_CHECK_HOST: 0.0.0.0 KEEPER_GATEWAY_HEALTH_CHECK_PORT: 8443 KEEPER_GATEWAY_HEALTH_CHECK_AUTH_TOKEN: $(cat /etc/secrets/token)

CLI

構成	起動コマンド
基本的なHTTP	gateway start \ --health-check
認証付きHTTP	gateway start \ --health-check \ --health-check-auth-token mytoken
HTTPS (SSL)	gateway start \ --health-check \ --health-check-ssl \ --health-check-ssl-cert /path/cert.pem \ --health-check-ssl-key /path/key.pem
認証付き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 start \ --health-check \ --health-check-port 8443
カスタムホスト	gateway start \ --health-check \ --health-check-host 0.0.0.0
本番環境のセットアップ	gateway start \ --health-check \ --health-check-ssl \ --health-check-ssl-cert /path/cert.pem \ --health-check-ssl-key /path/key.pem \ --health-check-host 0.0.0.0 \ --health-check-port 8443 \ --health-check-auth-token $(cat /etc/secrets/token)

これらのプロパティのデフォルト定義について詳しくは、ゲートウェイ環境変数のドキュメントをご参照ください。

ヘルスチェックの確認

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

出力形式の例

出力形式	CLIコマンド	説明
ステータスのみ	gateway health-check \ --token mytoken	戻り値: OK: Gateway is running and connected CRITICAL: ...
詳細情報	gateway health-check \ --token mytoken \ --info	戻り値: 監視スクリプト向けのKey=valueペア
JSON形式	gateway health-check \ --token mytoken \ --json	戻り値: HTTPエンドポイントと一致する完全なJSONレスポンス

---

HTTPヘルスチェック

上記のヘルスチェック機能を使用して、ゲートウェイのHTTPヘルスチェックを有効にできます。

使用方法

有効にすると、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": 1784637354,
    "version": 2,
    "hostname": "localhost.localdomain",
    "instance_id": "IMJUOZ",
    "gateway_version": "1.8.6",
    "resources": {
      "memory": {
        "available_mb": 10200,
        "total_mb": 10939,
        "used_percent": 6.76,
        "headroom_percent": 93.24,
        "container_limit_mb": null
      },
      "connections": {
        "total": 0,
        "by_type": {}
      },
      "pressure": {
        "under_pressure": false,
        "can_accept_rbi": true
      }
    },
    "rotations": {
      "active": 0,
      "pool_active": 0,
      "pool_limit": 1,
      "pool_load_percentage": 0,
      "can_accept": true,
      "suggested_delay_ms": 0,
      "total": 0,
      "failed": 0,
      "failure_rate_percent": null,
      "failure_rate_10min_percent": null,
      "failure_rate_10min_count": 0,
      "failure_rate_jobs_percent": null,
      "failure_rate_jobs_count": 0
    },
    "discoveries": {
      "active": 0,
      "pool_active": 0,
      "pool_limit": 1,
      "pool_load_percentage": 0,
      "can_accept": true,
      "suggested_delay_ms": 0,
      "total": 0,
      "failed": 0,
      "failure_rate_percent": null,
      "failure_rate_10min_percent": null,
      "failure_rate_10min_count": 0,
      "failure_rate_jobs_percent": null,
      "failure_rate_jobs_count": 0
    },
    "tubes": {
      "can_accept_more": true,
      "active_creates": 0,
      "max_concurrent": 100,
      "queue_depth": 0,
      "avg_create_time_ms": 0,
      "total_creates": 0,
      "total_failures": 0,
      "load_percentage": 0,
      "suggested_delay_ms": 0
    },
    "overall_capacity": {
      "can_accept_work": true,
      "suggested_delay_ms": 0,
      "bottleneck": "none"
    },
    "connection_status": "connected",
    "websocket": {
      "uptime_seconds": 6014,
      "uptime_human": "1h 40m 14s",
      "last_ping_received_seconds_ago": 7,
      "latency_ms": 92,
      "last_ping_sent_timestamp": 1784637340,
      "last_pong_received_timestamp": 1784637340,
      "reconnect_count": 0
    }
  }
}

正常でないゲートウェイの例:

{
  "status": "unhealthy",
  "message": "Gateway is not properly connected (status: disconnected)",
  "details": {
    "timestamp": 1784637802,
    "version": 2,
    "hostname": "localhost.localdomain",
    "instance_id": "HTLGDB",
    "gateway_version": "1.8.6",
    "resources": {
      "memory": {
        "available_mb": 10341,
        "total_mb": 10939,
        "used_percent": 5.47,
        "headroom_percent": 94.53,
        "container_limit_mb": null
      },
      "connections": {
        "total": 0,
        "by_type": {}
      },
      "pressure": {
        "under_pressure": false,
        "can_accept_rbi": true
      }
    },
    "rotations": {
      "active": 0,
      "pool_active": 0,
      "pool_limit": 1,
      "pool_load_percentage": 0,
      "can_accept": true,
      "suggested_delay_ms": 0,
      "total": 0,
      "failed": 0,
      "failure_rate_percent": null,
      "failure_rate_10min_percent": null,
      "failure_rate_10min_count": 0,
      "failure_rate_jobs_percent": null,
      "failure_rate_jobs_count": 0
    },
    "discoveries": {
      "active": 0,
      "pool_active": 0,
      "pool_limit": 1,
      "pool_load_percentage": 0,
      "can_accept": true,
      "suggested_delay_ms": 0,
      "total": 0,
      "failed": 0,
      "failure_rate_percent": null,
      "failure_rate_10min_percent": null,
      "failure_rate_10min_count": 0,
      "failure_rate_jobs_percent": null,
      "failure_rate_jobs_count": 0
    },
    "tubes": {
      "can_accept_more": true,
      "active_creates": 0,
      "max_concurrent": 100,
      "queue_depth": 0,
      "avg_create_time_ms": 0,
      "total_creates": 0,
      "total_failures": 0,
      "load_percentage": 0,
      "suggested_delay_ms": 0
    },
    "overall_capacity": {
      "can_accept_work": true,
      "suggested_delay_ms": 0,
      "bottleneck": "none"
    },
    "connection_status": "disconnected"
  }
}

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 を使用する場合、ヘルスチェックデータを保護するため、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チェックが可能な任意の監視システム

トラブルシューティング

---

問題	テストコマンド	期待される結果
サーバーが実行中か確認	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サーバーよりも強化されたセキュリティ
• 適切なリクエストのルーティングと処理
• 優れたエラーマネジメント
• スレッドセーフ
• 最小限のオーバーヘッドで本番環境に対応