JSON Status Page
Relevant source files
The following files were used as context for generating this wiki page:
The Kuberhealthy JSON Status Page is a primary interface for monitoring the health of a Kubernetes cluster through synthetic tests. It provides a real-time, consolidated view of all check results, global cluster health status, and specific details for every configured check. This page serves as a lightweight alternative or supplement to Prometheus metrics for external monitoring systems and human operators.
Sources: README.md:15-18, deploy/helm/kuberhealthy/README.md:10-14
Architecture and Data Flow
Kuberhealthy acts as an aggregator for various synthetic checks. External checks or jobs report their success or failure status back to Kuberhealthy, which then persists this state and serves it via a central HTTP endpoint. The JSON status page is generated from the internal state of the Kuberhealthy operator.
The diagram shows how checker pods report results to the operator, which stores them in an internal state accessed by the web server to fulfill JSON status requests.
Sources: README.md:101-112, cmd/kuberhealthy/webserver_test.go:48-60
Endpoint and Access
By default, the JSON status page is accessible via the Kuberhealthy service within the cluster.
- Service Name:
kuberhealthy.kuberhealthy - Port: 80
- Path:
/
To access this page from outside the cluster, the service type must be modified to LoadBalancer or exposed via an Ingress.
Sources: README.md:73-77, README.md:148-150
Data Structure
The status page returns a JSON object containing global indicators and granular check details. The data is structured around the State object, which includes a boolean summary and detailed maps for checks and jobs.
JSON Field Definitions
| Field | Type | Description |
|---|---|---|
OK | Boolean | Global status. true if all checks are passing, false if any check has failed. |
Errors | Array (String) | A consolidated list of error messages from all failing checks. |
CheckDetails | Map (Object) | Key-value pairs where the key is the check name (e.g., kuberhealthy/dns-status-internal) and the value is a detail object. |
JobDetails | Map (Object) | Similar to CheckDetails, but specifically for Kuberhealthy jobs. |
CurrentMaster | String | The name of the Kuberhealthy pod currently acting as the leader/master. |
Sources: README.md:150-155, pkg/metrics/exporter.go:50-58, cmd/kuberhealthy/webserver_test.go:119-125
Check Detail Fields
Each entry within CheckDetails provides the following information:
| Field | Type | Description |
|---|---|---|
OK | Boolean | Individual status of the specific check. |
Errors | Array (String) | Error messages specific to this check instance. |
RunDuration | String | The duration of the last check execution (e.g., "22.512278967s"). |
Namespace | String | The namespace where the check is configured. |
LastRun | ISO8601 String | Timestamp of the last check completion. |
AuthoritativePod | String | The Kuberhealthy pod that processed this check result. |
uuid | String | Unique identifier for the specific check run. |
Sources: README.md:158-185, pkg/metrics/exporter.go:68-84
Implementation Details
The web server utilizes a healthCheckHandler to process requests. During testing, Kuberhealthy simulates requests to ensure the JSON output matches the expected cluster state.
The sequence diagram illustrates the internal processing of a status page request within the Kuberhealthy operator.
Sources: cmd/kuberhealthy/webserver_test.go:53-65, cmd/kuberhealthy/webserver_test.go:110-120
Reporting to the Status Page
External checks use a client (available in Go, JavaScript, etc.) to send results to Kuberhealthy. When a check fails, it calls ReportFailure, which adds error strings to the status page. When it succeeds, it calls ReportSuccess.
// Example of a Go check reporting failure to the status page
kh.ReportFailure([]string{"unable to retrieve a valid response from " + parsedUrl.Redacted()})
// Example of a Go check reporting success
kh.ReportSuccess()
Sources: cmd/http-check/main.go:167-175, cmd/http-content-check/main.go:88-92, clients/js/README.md:36-45
Conclusion
The JSON status page is a core component of Kuberhealthy that provides an immediate, machine-readable overview of Kubernetes cluster health. By centralizing results from various synthetic checks into a single structured response, it enables rapid debugging and easy integration with existing monitoring workflows.