Getting Started & Installation
Relevant source files
The following files were used as context for generating this wiki page:
Kuberhealthy is a Kubernetes operator designed for synthetic monitoring and continuous process verification. It functions by running synthetic tests (checks) within a cluster to replicate real-world workflows, ensuring that the cluster and its applications are performing as expected. Kuberhealthy provides health status through a JSON status page, Prometheus metrics at a /metrics endpoint, and supports InfluxDB metric forwarding.
The installation process primarily targets Kubernetes environments (v1.16+) and offers multiple deployment methods, including static YAML manifests and Helm charts. Post-installation, Kuberhealthy monitors configured KuberhealthyCheck (khcheck) resources and orchestrates checker pods to validate cluster state.
Sources: README.md:5-24, deploy/helm/kuberhealthy/README.md:1-12
Prerequisites
Before deploying Kuberhealthy, ensure the following requirements are met:
- Kubernetes Version: 1.16 or above is required.
- Namespace: A dedicated namespace, typically
kuberhealthy, must be created manually for most installation methods. - Permissions: Sufficient RBAC permissions to create Custom Resource Definitions (CRDs), Deployments, and ConfigMaps.
Sources: README.md:52, deploy/README.md:12
Deployment Methods
Kuberhealthy supports two primary deployment strategies: using flat YAML manifests for simple environments and Helm charts for more complex, configurable setups.
Static YAML Manifests
For users who prefer not to use Helm, static "flat" files are provided. These files are updated automatically to reflect the latest master branch changes.
| Manifest Type | Command |
|---|---|
| Default (No Prometheus) | kubectl apply -f https://raw.githubusercontent.com/kuberhealthy/kuberhealthy/master/deploy/kuberhealthy.yaml |
| Standard Prometheus | kubectl apply -f https://raw.githubusercontent.com/kuberhealthy/kuberhealthy/master/deploy/kuberhealthy-prometheus.yaml |
| Prometheus Operator | kubectl apply -f https://raw.githubusercontent.com/kuberhealthy/kuberhealthy/master/deploy/kuberhealthy-prometheus-operator.yaml |
Sources: README.md:54-72, deploy/README.md:3-33
Helm Installation
Helm is the recommended method for production environments as it allows for granular configuration of Prometheus integrations, resource limits, and specific checks.
# 1. Create the namespace
kubectl create namespace kuberhealthy
# 2. Add the repository
helm repo add kuberhealthy https://kuberhealthy.github.io/kuberhealthy/helm-repos
# 3. Install the chart
helm install kuberhealthy kuberhealthy/kuberhealthy -n kuberhealthy
Sources: README.md:74-78, helm-repos/README.md:10-17
Architecture and Workflow
Kuberhealthy operates as an operator that manages the lifecycle of synthetic tests. The following diagram illustrates the interaction between the Kuberhealthy operator, the Kubernetes API, and the ephemeral checker pods.
Visual representation of the Kuberhealthy check lifecycle and reporting flow.
Sources: README.md:113-132, deploy/helm/kuberhealthy/templates/deployment.yaml:1-12
Component Interaction
- Operator Observation: Kuberhealthy watches for
KuberhealthyCheckcustom resources. - Scheduling: When a check is due (based on
runInterval), a checker pod is created. - Execution: The checker pod performs the test (e.g., creating and deleting a DaemonSet) using the Kubernetes API.
- Reporting: The checker pod sends results back to the Kuberhealthy API.
- State Storage: Kuberhealthy stores the state and updates the JSON status page and Prometheus metrics.
Sources: README.md:113-132
Post-Installation Configuration
Exposing the Service
By default, the Kuberhealthy service is set to Type: ClusterIP and is only accessible within the cluster at kuberhealthy.kuberhealthy:80. To access the JSON status page externally, the service must be modified to Type: LoadBalancer or exposed via an Ingress.
Sources: README.md:92-95, deploy/helm/kuberhealthy/values.yaml:173-176
Configuration via ConfigMap
General settings are stored in a ConfigMap and are automatically reloaded by the Kuberhealthy pod when changed.
kubectl edit -n kuberhealthy configmap kuberhealthy
Sources: README.md:98-100, deploy/helm/kuberhealthy/templates/deployment.yaml:39-44
Helm Configuration Options
The Helm chart provides extensive variables for customizing the deployment.
| Variable | Default | Description |
|---|---|---|
prometheus.enabled | false | Deploys ServiceMonitor or PrometheusRule specs. |
deployment.replicas | 2 | Number of Kuberhealthy replicas (failover capacity). |
securityContext.runAsUser | 999 | User ID for the container process. |
check.daemonset.enabled | true | Enables the default DaemonSet health check. |
check.dnsInternal.enabled | true | Enables the internal DNS resolution check. |
Sources: deploy/helm/kuberhealthy/values.yaml:19-271, deploy/helm/kuberhealthy/README.md:30-84
Verifying the Installation
To verify that Kuberhealthy and its checks are running correctly, use the following commands:
- Check Resources:
kubectl -n kuberhealthy get khcheck(lists configured checks). - Check Status:
kubectl -n kuberhealthy get khstate(view current status of checks). - JSON Status: Access the service at port 80 via
curl. A healthy response includes"OK": trueand aCheckDetailsobject.
Sources: README.md:102-104, README.md:154-159
Summary
Setting up Kuberhealthy involves deploying the operator via YAML or Helm into a dedicated namespace. Once running, the operator automates the execution of synthetic checks, providing a robust verification layer for Kubernetes clusters. Configuration is handled through khcheck custom resources and a central ConfigMap, with results aggregated into a standardized JSON status and Prometheus metrics.