Open-Source Observability · kuberhealthy

kuberhealthy

Kuberhealthy is a Kubernetes operator that runs synthetic health checks as scheduled pods and ships results to Prometheus. It allows you to define monitoring logic as Kubernetes manifests, supporting multi-step workflows in any container-compatible language and integrating with existing monitoring stacks.

Talk to DEV.co Discuss Implementation

Source: GitHub — github.com/kuberhealthy/kuberhealthy

2.3k

GitHub stars

290

Forks

Primary language

Apache-2.0

License (OSI-approved)

Key facts

Objective fields from the source. Values we can't verify are shown as “Unknown” rather than guessed.

Field	Value
Repository	kuberhealthy/kuberhealthy
Owner	kuberhealthy
Primary language	Go
License	Apache-2.0 — OSI-approved
Stars	2.3k
Forks	290
Open issues	8
Latest release	v3.0.6 (2026-06-29)
Last updated	2026-07-03
Source	https://github.com/kuberhealthy/kuberhealthy

What kuberhealthy is

A Go-based Kubernetes operator that manages HealthCheck CRDs, schedules checker pods on a configurable interval, collects results via HTTP POST callbacks, and exposes metrics in Prometheus format plus a JSON API and web UI. Supports multi-language check clients (Go, Python, TypeScript, Rust, Bash, etc.) and works with Helm, Kustomize, and ArgoCD for deployment.

Quickstart

Get the kuberhealthy source

Clone the repository and explore it locally.

terminalbash

1git clone https://github.com/kuberhealthy/kuberhealthy.git2cd kuberhealthy3# follow the project's README for install & configuration

Need it deployed, integrated, or customized instead? DEV.co ships production installs.

Best use cases

API and service health validation

Run periodic synthetic tests against internal APIs and microservices to catch degradation before users do. Example: multi-step login, transaction, and cleanup workflows.

Kubernetes cluster validation

Built-in checks for deployment rollouts, pod scheduling, and infrastructure health. Package validation logic as code alongside application manifests in GitOps workflows.

Continuous compliance and integration testing

Schedule checks that verify database connectivity, third-party integrations, and business logic; feed pass/fail status directly to Prometheus alerting rules.

Implementation considerations

Define a naming and organizational convention for HealthCheck manifests early; treat checks as first-class application code with versioning and code review.
Plan RBAC and ServiceAccount permissions for checker pods; each check may need different cluster access (e.g., deployment check requires create/delete permissions).
Establish a base image and check client dependency strategy per language; standardize on one client library version to reduce maintenance drift.
Configure appropriate runInterval and timeout values based on SLA targets and infrastructure capacity; excessively frequent checks can overload the cluster.
Integrate with existing Prometheus scrape configs and alerting rules early; plan how check failures will trigger incidents.

When to avoid it — and what to weigh

Real-time alerting is the primary need — Kuberhealthy is designed for periodic synthetic checks (intervals measured in minutes). Not suitable for sub-second event streaming or continuous monitoring of high-frequency metrics.
Non-Kubernetes environments — Kuberhealthy is a Kubernetes operator and requires a running cluster. Not applicable for standalone VMs, serverless, or on-prem bare-metal without Kubernetes.
Minimal operational overhead desired — Running an operator, managing CRDs, and maintaining custom check code adds operational burden. Simpler use cases may benefit from off-the-shelf SaaS monitoring tools.
Proprietary or sensitive check logic — Checks run as pods in your cluster and require container images. If logic must never leave your infrastructure, custom deployment patterns may be needed.

License & commercial use

Apache License 2.0 (Apache-2.0). Permissive OSI-approved license allowing modification, distribution, and private use with attribution and patent protection.

Apache-2.0 is permissive and allows commercial use. However, review your organization's open-source policies and ensure compliance with any downstream dependencies bundled in Kuberhealthy and check client libraries. No warranty or indemnification is provided by the license; support and SLAs are community-driven.

DEV.co evaluation signals

Editorial assessment — not user reviews. Directional, with an explicit confidence level.

Signal	Assessment
Maintenance	Active
Documentation	Strong
License clarity	Clear
Deployment complexity	Low
DEV.co fit	Good
Assessment confidence	High

Security considerations

Kuberhealthy controller runs as a pod and watches HealthCheck CRDs; verify RBAC restricts who can create/edit HealthChecks to prevent arbitrary pod execution. Checker pods inherit the ServiceAccount specified in the HealthCheck; grant minimal required permissions per check. No explicit security audit data provided; review code and dependencies for your threat model. Secrets passed via environment variables should use Kubernetes Secrets, not inline values. Network policies should restrict checker pod egress to intended targets.

Alternatives to consider

Prometheus AlertManager + Blackbox Exporter

Simpler for basic HTTP/TCP endpoint probing; no custom code needed. Lacks multi-step workflow and Kubernetes-native manifest integration.

Datadog / New Relic Synthetic Monitoring

SaaS offering with built-in analytics, alerting, and support; no self-hosted operational overhead. Requires external account and ongoing cost; less control over check logic.

CronJob-based checks with custom webhook

Lightweight alternative using native Kubernetes primitives; minimal operator overhead. Requires manual result collection and Prometheus integration; no built-in UI or check client libraries.

Software development agency

Build on kuberhealthy with DEV.co software developers

Kuberhealthy is best suited for teams already invested in Kubernetes and Prometheus who need declarative, multi-step synthetic validation at scale. Start with a single HealthCheck on your cluster and integrate with your monitoring stack. Review the CHECK_CREATION.md guide and join the community Slack for implementation questions.

Talk to DEV.co

Related open-source tools

Surfaced by semantic similarity across the DEV.co open-source index.

kubeeye prometheus-operator prometheus

Related on DEV.co

Explore the category and the services that help you build with it.

Open-Source Observability DevOps & Kubernetes Monitoring API Development & Testing Talk to DEV.co

kuberhealthy FAQ

Do I need Prometheus to use Kuberhealthy?

No. Kuberhealthy exposes a `/json` API and web UI that work standalone. Prometheus integration is optional but recommended for alerting and historical trend analysis.

Can I write checks in languages other than Go?

Yes. Kuberhealthy provides check client libraries for Python, TypeScript, Rust, Ruby, Java, and Bash. Any language that runs in a container and can make HTTP POST calls to the controller works.

What happens if a check pod fails to report before timeout?

The check is marked as failed. Timeout duration is configurable per HealthCheck; the controller enforces a deadline and does not retry automatically.

Does Kuberhealthy support multi-cluster deployments?

Unknown. The provided documentation focuses on single-cluster installation. Multi-cluster setups would require custom integration or aggregation of metrics from multiple Kuberhealthy instances; consult the community or open an issue for guidance.

Software development & web development with DEV.co

Need help beyond evaluating kuberhealthy? DEV.co is a software development agency offering software development services and web development for teams of every size. Our software developers and web developers build custom software, web applications, APIs, and open-source observability integrations — and maintain them long-term.

Evaluate Kuberhealthy for Your Kubernetes Monitoring

Talk to DEV.co Schedule a Consultation