kuberhealthy/kuberhealthy 是什么？

Kuberhealthy 是一个以 Kubernetes Operator 形态运行的合成监控工具，用 HealthCheck 自定义资源调度一次性检查 Pod，并把结果暴露给 Prometheus。它适合把监控逻辑当作代码和集群一起管理，但调度粒度粗，且需要自己维护检查镜像。

kuberhealthy/kuberhealthy 可以商用吗？

可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。

kuberhealthy/kuberhealthy 还在维护吗？

在维护。仓库最近一次提交在 2 天前。

kuberhealthy/kuberhealthy 是用什么编程语言写的？

主要是 Go（依据 GitHub 的语言统计）。

Kuberhealthy 评测：用 HealthCheck CRD 做 Kubernetes 合成监控

Q: kuberhealthy/kuberhealthy 还在维护吗？

在维护。仓库最近一次提交在 2 天前。

秒懂

它是什么？: Kuberhealthy 是一个以 Kubernetes Operator 形态运行的合成监控工具，用 HealthCheck 自定义资源调度一次性检查 Pod，并把结果暴露给 Prometheus。它适合把监控逻辑当作代码和集群一起管理，但调度粒度粗，且需要自己维护检查镜像。
适合谁用？: 如果你的团队已经用 Helm 或 Kustomize 管理集群资源，希望监控检查能随应用代码一起评审、发布和回滚，Kuberhealthy 值得一试。它把检查变成声明式清单，降低了进入门槛，而且 Go、Python、Rust 等客户端让不同技术栈的团队都能接入。
能商用吗？: 可以。Apache-2.0 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
还在维护吗？: 在维护。仓库最近一次提交在 2 天前。
用什么语言写的？: 主要是 Go（依据 GitHub 的语言统计）。

以上回答依据项目的 GitHub 数据（最近同步于 2026年9月14日）和我们的分析，不构成法律意见。

开源项目深度解析

Hysen Labs 编辑部 · 2026年8月8日 · kuberhealthy/kuberhealthy

它解决的是监控逻辑与集群配置脱节的问题

大多数监控系统把检查配置存在独立的 UI 或配置文件里，和 Kubernetes 集群的实际状态没有直接关系。Kuberhealthy 换了一种思路：它把合成监控定义成 Kubernetes 的 HealthCheck 自定义资源，检查逻辑本身就是一个容器镜像。这意味着监控检查可以像应用一样通过 kubectl apply 部署，进入 Git 仓库，参与代码评审。这个项目面向的是已经深度使用 Kubernetes 的团队，尤其是那些需要验证集群内部服务连通性、数据库可达性或者多步骤业务流程的运维和平台工程人员。它不解决基础设施指标采集，那是 Prometheus node exporter 或 cAdvisor 的领域。它专注于主动发起请求、执行操作并验证结果，属于合成监控和持续验证的范畴。

从 HealthCheck CRD 到检查 Pod 的调度链路

Kuberhealthy 的核心是一个控制器，它监听 HealthCheck 自定义资源。每个 HealthCheck 的 spec 里包含 runInterval、timeout 和 podSpec。控制器根据 runInterval 决定何时启动一个短期的检查 Pod，这个 Pod 运行你指定的镜像，执行验证逻辑。Pod 完成后通过 POST 请求回调控制器的 /check 端点，报告成功或失败。控制器汇总结果，暴露给内置状态 UI、JSON API 和 Prometheus 的 /metrics 端点。README 里的架构图显示，Prometheus 和浏览器都通过 Kuberhealthy Service 访问控制器，而控制器负责调度和接收回调。这个设计把检查的执行和结果收集解耦了，检查 Pod 不需要常驻，跑完就销毁，节省资源。但这也意味着每次检查都有 Pod 启动的开销，包括镜像拉取和调度延迟，所以它适合分钟级以上的检查频率，不适合高频探测。

安装与第一个检查：三个命令起步

安装方式有三种：Helm、Kustomize 和 ArgoCD。README 推荐 Helm，命令是 helm install kuberhealthy deploy/helm/kuberhealthy -n kuberhealthy --create-namespace。Kustomize 用户可以用 kubectl apply -k github.com/kuberhealthy/kuberhealthy/deploy/kustomize/base?ref=main，ArgoCD 用户直接应用 deploy/argocd/kuberhealthy.yaml。装完后需要端口转发才能看到 UI：kubectl -n kuberhealthy port-forward svc/kuberhealthy 8080:80，然后访问 localhost:8080。创建一个检查只需要一个 YAML 文件，比如内置的 deployment-check，它会在集群里创建一个测试 Deployment，滚动更新，然后删除。这个检查的 spec 里设置了 runInterval: 10m 和 timeout: 5m，并指定了检查镜像和两个环境变量：CHECK_DEPLOYMENT_REPLICAS 和 CHECK_DEPLOYMENT_ROLLING_UPDATE。你可以用 kubectl get healthcheck 或 kubectl get hc 查看状态，输出会显示 LAST RUN、AGE 和 OK 列。

检查结果如何进入 Prometheus 和 JSON API

Kuberhealthy 的指标暴露在 /metrics 端点，格式是标准的 Prometheus 文本格式。README 给出了几个示例指标：kuberhealthy_check 带 check、namespace 和 status 标签，status 为 1 表示成功，0 表示失败；kuberhealthy_check_duration_seconds 记录单次检查耗时；kuberhealthy_check_success_total 是累计成功次数。这些指标可以直接被 Prometheus 抓取，用于告警规则或 Grafana 面板。JSON API 在 /json 端点，返回一个包含 ok 字段和每个检查的详细信息的对象，包括 lastRun 和 runDuration。这个 API 适合外部系统轮询状态，但注意它只反映最近一次运行的结果，没有历史趋势。如果你需要长期历史，应该依赖 Prometheus 的指标。

用任何语言写检查：客户端库与回调机制

Kuberhealthy 不限定检查语言的实现方式。它提供了 Go、Python、TypeScript、JavaScript、Rust、Ruby、Java 和 Bash 的客户端库，但核心机制是统一的：检查 Pod 通过环境变量 KH_REPORTING_URL 和 KH_RUN_UUID 获得回调地址和运行 ID，然后调用客户端库的 ReportSuccess 或 ReportFailure 方法。以 Go 为例，你只需要引入 github.com/kuberhealthy/kuberhealthy/v3/pkg/checkclient，在 main 函数里发起 HTTP 请求，根据响应状态调用 checkclient.ReportFailure 或 ReportSuccess。客户端库会自动处理报告 URL 和截止时间。这意味着你可以把现有的测试脚本容器化，包装成检查镜像，而不需要学习新的 DSL。但要注意，检查镜像需要自己构建和推送到镜像仓库，Kuberhealthy 只负责调度和收集结果，不负责镜像的版本管理。

一个真实的失败模式：检查 Pod 的资源与权限

Kuberhealthy 的检查 Pod 默认运行在集群内部，这意味着它们可以访问集群内的服务，但也意味着它们继承集群的安全上下文。如果检查需要创建或删除资源，比如 deployment-check 那样，它需要相应的 RBAC 权限。README 的例子没有展示 ServiceAccount 配置，但实际使用中你需要确保检查 Pod 的 ServiceAccount 有足够的权限，否则检查会因权限不足而失败。另一个失败模式是资源限制：检查 Pod 的 spec 里可以设置 requests 和 limits，但如果设置不当，比如 limits 太小，检查可能因 OOM 被杀死，导致误报。此外，runInterval 和 timeout 的配置需要权衡，timeout 必须大于检查实际执行时间，否则检查会被强制终止并标记为失败。这些都需要在编写检查时仔细测试。

与替代方案的差异：Argo Rollouts 或自定义 CronJob

一个常见的替代方案是直接使用 Kubernetes CronJob 来运行检查脚本，配合 Prometheus Pushgateway 或自定义指标端点。这种方式更灵活，但你需要自己处理调度、超时、重试和结果上报逻辑。Kuberhealthy 把这些封装成了控制器和客户端库，减少了重复工作。另一个替代是 Argo Rollouts 的 analysis 功能，它专注于发布过程中的渐进式验证，而不是持续的合成监控。Kuberhealthy 更适合持续运行，Argo Rollouts 则适合在部署时触发验证。如果你只需要简单的定时请求，CronJob 加一个 curl 脚本可能更轻量，但你会失去 Kuberhealthy 提供的状态 UI、JSON API 和统一的指标格式。Kuberhealthy 的价值在于标准化，而不是功能独特性。

维护成本与许可证考量

Kuberhealthy 使用 Apache-2.0 许可证，这意味着你可以自由使用和修改，但需要保留版权声明。项目最近发布了 v3.0.14，显示活跃的发布节奏，但维护成本主要在检查镜像上。每个检查都是一个独立的镜像，你需要跟踪上游更新、修复安全漏洞、重新构建和推送。Kuberhealthy 本身作为 Operator 部署在集群中，升级时需要关注 CRD 版本兼容性，比如示例中 apiVersion 是 kuberhealthy.github.io/v2，升级到新版本可能涉及 CRD 迁移。文档提到有 ADOPTERS.md 列出生产用户，但没有给出具体的升级指南，所以升级前需要自己查看 release notes。如果你不想维护一堆检查镜像，可以考虑使用官方提供的预构建检查，但定制化需求最终会落到自己写镜像上。

编辑结论

如果你的团队已经用 Helm 或 Kustomize 管理集群资源，希望监控检查能随应用代码一起评审、发布和回滚，Kuberhealthy 值得一试。它把检查变成声明式清单，降低了进入门槛，而且 Go、Python、Rust 等客户端让不同技术栈的团队都能接入。但你不应该用它来做秒级或毫秒级的实时探测，runInterval 和 timeout 的最小粒度决定了它只适合分钟级以上的周期验证。在决定采用之前，先确认两件事：一是你的集群有足够的资源余量来运行周期性 Pod，二是你愿意维护检查镜像的构建和版本更新。Kuberhealthy 的 GitHub 仓库显示其默认分支为 main，最近一次推送在 2026 年 8 月，说明项目仍在活跃维护，但具体问题响应速度需要你自己在 issue 区验证。

官方来源

社区笔记