Interfaces

April 15, 2026 · View on GitHub

Three primary surfaces: the Kubernetes API, HTTP endpoints served from the controller pod, and environment variables.

Kubernetes API

  • HealthCheck Custom Resource (pkg/api)
    • Inputs: desired run interval, timeout, target PodSpec, optional labels, and optional annotations.
    • Outputs: status block populated with ok, errors, run timing, counters, and run UUID state.
  • Pods
    • Created by the controller for each check run using the embedded PodSpec.
    • Annotated with labels defined in internal/kuberhealthy to link the pod to the originating check and run.
  • Events
    • The controller publishes Kubernetes events to describe failures and status transitions for each check.

HTTP Endpoints

The HTTP server configured in cmd/kuberhealthy/webserver.go exposes:

  • GET /json – JSON summary of all checks. Supports namespace query filtering.
  • GET /metrics – Prometheus metrics generated by internal/metrics.
  • GET /healthz – Liveness probe that verifies basic process health.
  • POST /check – Reporting endpoint for check pods. Payload must include the run UUID and status information defined in pkg/api.
  • POST /api/run – Triggers an immediate run of a specific check using healthcheck and namespace query parameters. Only the leader accepts this action when leader election is enabled.
  • GET /api/events – Lists Kubernetes events for a HealthCheck.
  • GET /api/logs and GET /api/logs/stream – Fetches or streams pod logs for a particular check run.
  • GET /openapi.yaml and GET /openapi.json – Serves the OpenAPI schema in YAML and JSON respectively.

Static assets for the status UI are served from /static/ and the root path / returns the HTML interface for GET requests.

Environment Variables

The Config struct in cmd/kuberhealthy/config.go loads several environment variables that tune runtime behavior. Notable entries include:

  • KH_LISTEN_ADDRESS and KH_LISTEN_ADDRESS_TLS – Bind addresses for HTTP and HTTPS listeners.
  • KH_CHECK_REPORT_URL – Base URL advertised to checker pods as the reporting endpoint.
  • KH_DEFAULT_RUN_INTERVAL and KH_DEFAULT_CHECK_TIMEOUT – Defaults applied to checks when their manifests omit values.
  • KH_MAX_* variables – Retention policies for checker pods.
  • KH_PROM_* variables – Feature flags for Prometheus metrics labeling.
  • KH_LEADER_ELECTION_* variables – Configure Lease-based leader election for running scheduling and reaping tasks.

Pods also rely on POD_NAME and POD_NAMESPACE for self-identification.