开源身份和访问管理方案之keycloak（三）keycloak健康检查（k8s）

news2025/4/7 19:06:35

开源身份和访问管理方案之keycloak（三）

官方文档：https://www.keycloak.org/observability/health

Keycloak 内置了对健康检查的支持。本指南介绍如何启用和使用 Keycloak 运行状况检查。默认情况下，Keycloak 运行状况检查在管理端口 9000 上公开。

以使用构建时选项 health-enabled 启用运行状况检查：

默认情况下，运行状况终端节点不会返回任何检查。

bin/kc.[sh|bat] build --health-enabled=true

在这里插入图片描述

bin/kc.sh start-dev --health-enabled=true

配置完成后，

# curl -fsS http://localhost:9000/health
{
    "status": "UP",
    "checks": [
    ]
}

Keycloak 公开了 4 个运行状况端点：

请参阅 Quarkus SmallRye Health 文档，了解有关每个端点含义的信息。

Keycloak 使用 Quarkus 构建，而健康检查功能由 Quarkus SmallRye Health 提供。

这意味着 Keycloak 并没有自己从头开始实现健康检查功能，而是使用了 Quarkus 提供的 SmallRye Health 组件。

建议通过外部 HTTP 请求来监控健康端点。由于安全措施，Keycloak 容器镜像中移除了 curl 等软件包，因此基于本地命令的监控将无法轻松实现。

如果将KeyCloak部署在容器中，则由于前面提到的安全措施，必须从外部运行此命令。例如：

curl --head -fsS http://localhost:9000/health/ready

定义一个 HTTP 探针，以便 Kubernetes 可以从外部监控健康端点。不要使用存活命令。

Kubernetes 探针是 Kubernetes 层面的健康检查机制。HEALTHCHECK 是 Docker 层面的健康检查机制。

HEALTHCHECK 指令定义了一个命令，这个命令会在容器运行时定期执行。目的是检查容器内部的应用程序是否健康运行。

keycloak 容器默认情况下没有安装任何命令行 HTTP 客户端工具（比如 curl）。这意味着你无法直接使用 HEALTHCHECK 指令来发送 HTTP 请求，从而检查 Keycloak 服务是否正常响应。

建议你安装 curl 这个工具。安装方法可以参考 Keycloak 官方提供的容器运行指南。

注意：安装额外的工具（比如 curl）可能会降低容器的安全性。你需要权衡一下便利性和安全性。

以下是一个简单的 HEALTHCHECK 示例，它使用 curl 命令检查容器内的 Web 服务是否正常运行：

HEALTHCHECK --interval=5s --timeout=3s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

在这个例子中：
每 5 秒执行一次健康检查。
如果 curl 命令在 3 秒内未完成，则视为超时。
如果连续 3 次检查失败，容器会被标记为不健康。
注意事项
命令返回值：健康检查命令必须返回 0（成功）或 1（失败），其他返回值会被视为失败。

指令解析

HEALTHCHECK：Dockerfile 中的指令，用于定义容器的健康检查机制。
–interval=5s：设置健康检查的时间间隔为 5 秒。Docker 会每 5 秒执行一次健康检查命令。
–timeout=3s：设置健康检查命令的超时时间为 3 秒。如果命令在 3 秒内未完成，则视为超时。
–retries=3：设置健康检查失败的重试次数为 3 次。如果连续 3 次检查失败，容器会被标记为不健康。
CMD curl -f http://localhost/ || exit 1：定义健康检查的命令。curl -f 会尝试访问 http://localhost/，如果请求失败（返回非 2xx 状态码），curl 会返回非零值，触发 exit 1，表示健康检查失败。
-f 是一个常用的选项，全称为 --fail。它的作用是让 curl 在 HTTP 请求失败时（即服务器返回的状态码为 400 或更高）返回一个非零的退出码，而不是正常返回。