cilium-health

Active contributors: aanm, christarazi

Purpose

cilium-health is a small per-node binary that runs alongside the agent and probes connectivity to every other node and to every host's pod IP. It feeds the Connectivity Health panel in cilium status and the cilium-health Prometheus metrics.

It exists because relying solely on Kubernetes node-readiness misses many failure modes — for example, two nodes might both be Ready but unable to forward pod traffic to each other due to a misconfigured route, missing IPSec key, or tunnel MTU issue.

Directory layout

cilium-health/
├── main.go            # entry point
├── cmd/               # cobra commands (probe, status, etc.)
└── launch/            # how the agent launches the health endpoint

How it works

The health daemon runs in two modes:

• Server mode — listens on the node's "cilium_health" interface (a Cilium-managed veth) for ICMP and HTTP probes from peer nodes.
• Client mode — sends probes to every other node's health interface and records latency / success rates.

The agent launches the health endpoint via pkg/health/ cells. Results are exposed through the agent's REST API at /cluster/nodes and rendered by cilium status.

Integration points

• Uses pkg/health/server/ and pkg/health/client/.
• Reports through pkg/metrics/ (cilium_health_*).
• The probe traffic goes through the standard Cilium dataplane, so a failed probe means a real connectivity problem.

Key source files

File	Purpose
cilium-health/main.go	Entry point.
cilium-health/cmd/	Subcommands.
cilium-health/launch/	Helper that the agent uses to spawn the health endpoint.
pkg/health/	Server, client, and probe logic.