Keycloak のヘルスチェック

お客様が自身の環境でクロスサイトセットアップを実行する場合、すべてが期待どおりに稼働しているかを確認するために、特定の URL に監視を向けることができる必要があります。

このページでは、Keycloak のクロスサイトセットアップから派生した、そのような URL、Kubernetes リソース、およびヘルスチェックエンドポイントの概要を提供することを試みます。

概要

ユーザーに影響を与える前に問題を検出し、アラートを発することを目的としたプロアクティブな監視戦略は、高レジリエンスで高可用性な Keycloak アプリケーションにとって重要です。

さまざまなアーキテクチャコンポーネント（アプリケーションのヘルス、ロードバランシング、キャッシング、システム全体のステータスなど）にわたるヘルスチェックは、以下にとって重要です。

  • 高可用性の確保：すべてのサイトとロードバランサーが稼働していることを検証することにより、1 つのサイトがダウンした場合でもシステムがリクエストを処理できることを保証するのに役立ちます。

  • パフォーマンスの維持：Infinispan キャッシュのヘルスと分散をチェックすることで、Keycloak がセッションやその他の一時データを効率的に処理することにより、最適なパフォーマンスを維持できるようにします。

  • 運用上のレジリエンス：OpenShift 環境内の Keycloak とその依存関係の両方のヘルスを継続的に監視することにより、システムは問題を迅速に特定し、場合によっては自動的に修復して、ダウンタイムを削減できます。

設定方法

前提条件

  1. Openshift CLI がインストールおよび構成されていること.

  2. OS にまだインストールされていない場合は、jq をインストールします。

特定のヘルスチェックの詳細

Keycloak ロードバランサーとサイト

ロードバランサーおよびプライマリサイトとバックアップサイトの両方を介して Keycloak アプリケーションのヘルスを検証します。これにより、Keycloak にアクセス可能であり、ロードバランシングメカニズムがさまざまな地理的またはネットワークロケーション間で正しく機能していることが保証されます。

このコマンドは、Keycloak アプリケーションが構成されたデータベースへの接続のヘルスステータスを返し、DB 接続の信頼性を確認します。これは管理ポートでのみ利用可能であり、外部 URL からは利用できません。Kubernetes セットアップでは、サブステータス health/ready が Pod を ready にするために定期的にチェックされます。

curl -s https://keycloak:managementport/health

このコマンドは、ロードバランサーの lb-check エンドポイントを検証し、Keycloak アプリケーションクラスターが起動して実行されていることを確認します。

curl -s https://keycloak-load-balancer-url/lb-check

これらのコマンドは、クロスサイトセットアップ（アクティブ/パッシブまたはアクティブ/アクティブ）における Keycloak のサイト A およびサイト B の実行ステータスを返します。

curl -s https://keycloak_site_a_url/lb-check
curl -s https://keycloak_site_b_url/lb-check

Infinispan キャッシュヘルス

外部 Infinispan クラスター内のデフォルトのキャッシュマネージャーと個々のキャッシュのヘルスをチェックします。Infinispan は Keycloak デプロイメントで分散キャッシングとセッションクラスタリングによく使用されるため、これは Keycloak のパフォーマンスと信頼性にとって非常に重要です。

このコマンドは、Infinispan キャッシュマネージャーの全体的なヘルスを返します。これは、管理者ユーザーがヘルスステータスを取得するためにユーザー資格情報を提供する必要がないため便利です。

curl -s https://infinispan_rest_url/rest/v2/cache-managers/default/health/status

一方、これらのヘルスチェックでは、管理者ユーザーは外部 Infinispan クラスターキャッシュの全体的なヘルスを覗き込むリクエストの一部として、infinispan ユーザー資格情報を提供する必要があります。

curl -u <infinispan_user>:<infinispan_pwd> -s https://infinispan_rest_url/rest/v2/cache-managers/default/health \
 | jq 'if .cluster_health.health_status == "HEALTHY" and (all(.cache_health[].status; . == "HEALTHY")) then "HEALTHY" else "UNHEALTHY" end'

オプションで、jq フィルター 'if .cluster_health.health_status == "HEALTHY" and (all(.cache_health[].status; . == "HEALTHY")) then "HEALTHY" else "UNHEALTHY" end' なしで上記のコマンドを実行して、詳細全体を確認できます。このフィルターは、個々のキャッシュヘルスに基づいて全体的なヘルスを計算するのに便利なものです。

Infinispan クラスタ分散

Infinispan クラスターの分散ヘルスを評価し、クラスターのノードがデータを正しく分散していることを確認します。この手順は、キャッシングレイヤーのスケーラビリティとフォールトトレランスに不可欠です。

expectedCount 3 引数をクラスター内の合計ノード数に合わせて変更し、それらが正常であるかどうかを検証できます。

curl <infinispan_user>:<infinispan_pwd> -s https://infinispan_rest_url/rest/v2/cluster\?action\=distribution \
 | jq --argjson expectedCount 3 'if map(select(.node_addresses | length > 0)) | length == $expectedCount then "HEALTHY" else "UNHEALTHY" end'

Infinispan システム全体のヘルス

OpenShift の CLI ツールを使用して、指定された名前空間内の Infinispan クラスターと Keycloak サービスのヘルスステータスをクエリします。この包括的なチェックにより、OpenShift 環境内の Keycloak デプロイメントのすべてのコンポーネントが稼働しており、正しく構成されていることが保証されます。

oc get infinispan -n <NAMESPACE> -o json  \
| jq '.items[].status.conditions' \
| jq 'map({(.type): .status})' \
| jq 'reduce .[] as $item ([]; . + [keys[] | select($item[.] != "True")]) | if length == 0 then "HEALTHY" else "UNHEALTHY: " + (join(", ")) end'

Openshift での Keycloak の Readiness

具体的には、Red Hat OpenShift での Keycloak デプロイメントの Readiness およびローリングアップデートの条件をチェックし、Keycloak インスタンスが完全に稼働しており、可用性に影響を与える可能性のあるアップデートが行われていないことを保証します。

oc wait --for=condition=Ready --timeout=10s keycloaks.k8s.keycloak.org/keycloak -n <NAMESPACE>
oc wait --for=condition=RollingUpdate=False --timeout=10s keycloaks.k8s.keycloak.org/keycloak -n <NAMESPACE>

オプションの Bash スクリプト

cross-site-health-checks.sh スクリプトを使用し、それを拡張して必要なチェックを実行し、これを監視アーキテクチャに統合できます。

スクリプトを実行するには、前提条件として、コマンドを使用してターミナルからターゲット OCP クラスターへのセッションを確立する必要があります。

oc login --token=sha256~masked-key --server=https://api.gh-keycloak-a.masked.openshiftapps.com:6443

また、クラスターグループ内のすべてのクラスターに対してこのスクリプトを実行する必要があることに注意してください。したがって、管理者は上記の oc ログインコマンドをすべてのクラスターに対して繰り返す必要があります。これは自動化できます。

アクティブな oc セッションがある場合にスクリプト自体を実行するには、以下に使用例を示します。

./cross-site-health-checks.sh \
-n runner-keycloak \
-l <KEYCLOAK_LB_URL> \
-k <KEYCLOAK_SITE_URL> \
-i <KEYCLOAK_ISPN_REST_URL> \
-u developer \
-p <ISPN_REST_URL_PWD> \
-c 3

Verify the Keycloak Load Balancer health check
Checking health for: KEYCLOAK_LB_URL/lb-check
"HEALTHY"

Verify the Load Balancer health check on the Site
Checking health for: KEYCLOAK_SITE_URL/lb-check
"HEALTHY"

Verify the default cache manager health in external ISPN
Checking health for: KEYCLOAK_ISPN_REST_URL/rest/v2/cache-managers/default/health/status
"HEALTHY"

Verify individual cache health
"HEALTHY"

ISPN Cluster Distribution
"HEALTHY"

ISPN Overall Status
"HEALTHY"

Verify for Keycloak condition in ROSA cluster
keycloak.k8s.keycloak.org/keycloak condition met
keycloak.k8s.keycloak.org/keycloak condition met

さまざまなオプションに関する詳細を含むスクリプトの使用法

Usage: [-n namespace] [-l keycloak_lb_url] [-k keycloak_site_url]
[-i infinispan_rest_url] [-u infinispan_user] [-p infinispan_pwd]
[-c expected_ispn_count]

  -n namespace: Kubernetes namespace
  -l keycloak_lb_url: Keycloak Load Balancer URL
  -k keycloak_site_url: Keycloak Site URL
  -i infinispan_rest_url: Infinispan REST URL
  -u infinispan_user: Infinispan user
  -p infinispan_pwd: Infinispan password
  -c expected_ispn_count: Expected Node Count in the Infinispan cluster