Keycloak 健康检查

当客户在其环境中运行跨站点设置时，他们应该能够将其监控指向特定的 URL，以查看一切是否按预期启动并运行。

此页面尝试概述此类 URL、Kubernetes 资源以及从 Keycloak 的跨站点设置派生的健康检查端点。

概述

主动监控策略，旨在在问题影响用户之前检测并警报问题，这对于高度弹性且高度可用的 Keycloak 应用程序至关重要。

跨各种架构组件（如应用程序健康状况、负载均衡、缓存和整体系统状态）的健康检查对于以下方面至关重要：

确保高可用性：通过验证所有站点和负载均衡器是否都在运行，它有助于保证即使一个站点宕机，系统也能处理请求。
维护性能：检查 Infinispan 缓存的健康状况和分布，确保 Keycloak 可以通过高效处理会话和其他临时数据来维持最佳性能。
运维弹性：通过持续监控 OpenShift 环境中 Keycloak 及其依赖项的健康状况，系统可以快速识别并可能自动修复问题，从而减少停机时间。

如何设置

先决条件

已安装并配置 Openshift CLI.
如果您的操作系统上尚不可用，请安装 jq。

关于特定健康检查的更多信息

Keycloak 负载均衡器和站点

通过其负载均衡器以及主站点和备份站点验证 Keycloak 应用程序的健康状况。这确保 Keycloak 可访问，并且负载均衡机制在不同地理位置或网络位置之间正常运行。

此命令返回 Keycloak 应用程序与其配置数据库的连接的健康状态，从而确认数据库连接的可靠性。这仅在管理端口上可用，并且无法从外部 URL 访问。在 Kubernetes 设置中，定期检查子状态 health/ready 以使 Pod 准备就绪。

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 集群中默认缓存管理器和各个缓存的健康状况。这对于 Keycloak 的性能和可靠性至关重要，因为 Infinispan 通常用于 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 服务的健康状态。此全面检查确保 Keycloak 部署的所有组件都在 OpenShift 环境中正常运行且配置正确。

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 的就绪状态

专门检查 Red Hat OpenShift 中 Keycloak 部署的就绪状态和滚动更新条件，确保 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