Configuration Options
Relevant source files
The following files were used as context for generating this wiki page:
Kuberhealthy configuration provides the operational parameters for the Kubernetes operator, defining how it manages synthetic checks, reaps resources, and exports metrics. The configuration is primarily managed through a YAML file, often injected into the application pod via a Kubernetes ConfigMap, or through Helm chart values during deployment.
The architecture relies on a central configuration object that dictates the behavior of the Check Reaper, the internal web server for health reporting, and the various metric exporters including Prometheus and InfluxDB.
Sources: README.md, deploy/helm/kuberhealthy/templates/configmap.yaml:7-25
Global Operator Configuration
The core application configuration governs the basic networking and operational mode of the Kuberhealthy operator. These settings are typically defined in a file named kuberhealthy.yaml which is read upon application startup.
Core Networking and Operations
The operator exposes a web interface for status reporting and metric scraping. The behavior of this interface and the master election logic (when running multiple replicas) can be configured to suit specific environment requirements.
This diagram represents the flow of core configuration parameters from the Kubernetes environment into the operator components.
Sources: deploy/helm/kuberhealthy/templates/configmap.yaml:12-14, README.md
| Option | Type | Default | Description |
|---|---|---|---|
listenAddress | string | :8080 | The address and port Kuberhealthy listens on for status and metrics requests. |
enableForceMaster | boolean | false | When true, bypasses standard master election to force the instance into master mode. |
logLevel | string | debug | Sets the verbosity of logs (e.g., info, warn, error). |
Sources: deploy/helm/kuberhealthy/templates/configmap.yaml:12-14
Check Reaper Settings
The Check Reaper is a internal maintenance system responsible for cleaning up old KuberhealthyJob resources and finished checker pods. Proper configuration ensures that the cluster is not cluttered with historical job data or orphaned pods while maintaining enough history for troubleshooting.
Reaper Logic Flow
The Reaper evaluates resources based on their age and the count of existing resources for each specific check.
This diagram illustrates the logic used by the reaper to maintain a clean environment based on the configured age and count limits.
Sources: deploy/helm/kuberhealthy/values.yaml:8-12, deploy/helm/kuberhealthy/templates/configmap.yaml:20-23
reaper Configuration Options
| Field | Type | Default | Description |
|---|---|---|---|
maxKHJobAge | Duration | 15m | Maximum age of a khjob custom resource before deletion. |
maxCheckPodAge | Duration | 72h | Maximum age of checker pods before deletion. |
maxCompletedPodCount | integer | 4 | Number of pods in Completed state to retain per check. |
maxErrorPodCount | integer | 4 | Number of pods in Error state to retain per check. |
Sources: deploy/helm/kuberhealthy/values.yaml:8-12
Metrics and Observability
Kuberhealthy supports multiple avenues for observability, primarily through Prometheus and InfluxDB. Configuration options for metrics control how data is formatted and where it is sent.
Prometheus Metric Exporting
The Prometheus exporter can be tuned to handle specific label requirements, such as error string length, which is crucial for systems with strict cardinality or storage limits.
type PromMetricsConfig struct {
SuppressErrorLabel bool `yaml:"suppressErrorLabel,omitempty"` // do we want to supress error label in metrics output(default: false)
ErrorLabelMaxLength int `yaml:"errorLabelMaxLength,omitempty"` // if not suppress, then bound the error label value length to a number of bytes
}
Sources: pkg/metrics/exporter.go:14-17
InfluxDB Metric Forwarding
InfluxDB integration allows pushing metric data to an external database. This is configured via several key fields:
enableInflux: Boolean to toggle the feature.influxURL: The destination address.influxDB: The database name (defaults tohttp://localhost:8086).influxUsername/influxPassword: Credentials for authentication.
Sources: deploy/helm/kuberhealthy/templates/configmap.yaml:15-19
External Check and Job Configuration
Checks in Kuberhealthy are defined using Custom Resource Definitions (CRDs), specifically KuberhealthyCheck and KuberhealthyJob. These resources allow for fine-grained configuration of the synthetic tests themselves.
KuberhealthyJob Specification
A KuberhealthyJob configuration defines a specific run of a check, including the container image, resource limits, and execution timeouts.
| Spec Field | Description |
|---|---|
podSpec | A full Kubernetes PodSpec defining the checker container and its environment. |
timeout | Duration string defining how long the job is allowed to run before failing. |
extraAnnotations | Key-value pairs added to the metadata of the job execution. |
extraLabels | Labels applied to the resulting pods and job resources. |
Sources: scripts/generated/comcast.github.io_khjobs.yaml:37-67
Summary
The configuration landscape of Kuberhealthy is divided between operator-level settings (controlled via kuberhealthy.yaml and Helm values) and check-level settings (controlled via CRDs). The operator configuration focuses on lifecycle management (Reaper) and data export (Prometheus/InfluxDB), while the CRD specifications define the actual behavior and requirements of individual synthetic tests. This separation allows for global policy enforcement while maintaining flexibility for diverse monitoring scenarios.