Kubernetes agent
AtherOps monitors Kubernetes clusters with atherops-k8s-otel-agent, a DaemonSet that runs one
pod per node. It follows the same wrapper/proxy pattern as the Linux agent: it supervises
otelcol-contrib as a child process and routes all telemetry through a loopback HMAC auth-proxy
before anything leaves the node.
Status
atherops-k8s-otel-agent is the active Kubernetes agent. The original atherops-agent
DaemonSet is frozen (no new development) and should not be used for new deployments.
How it works
- Install token registration. On first boot the agent calls
POST /api/clusters/registerwith a one-time install token. The API mints an API key and writes it to a Kubernetes Secret. On subsequent restarts the agent reads the key from the Secret and skips registration. - Supervised collector. The wrapper renders the cluster's OTel Collector config,
starts
otelcol-contrib, and restarts it if it crashes. - Loopback proxy. The collector sends plaintext OTLP to
127.0.0.1:9599. The proxy signs each request with HMAC and forwards to the backend. - Heartbeat + key rotation. Periodic
POST /heartbeatkeeps the cluster marked online. WhenX-Key-Age-Dayscrosses the rotation threshold, the agent callsPOST /api/clusters/rotate-keyto mint a new key (5-minute overlap window).
What it collects
The agent collects the same signal types as the Linux agent:
| Signal | Source | Where it lands |
|---|---|---|
| Metrics | OTel host metrics receiver, kubelet/cAdvisor scrape | VictoriaMetrics |
| Logs | Kubernetes pod logs via OTel k8s log receiver | ClickHouse |
| Traces | OTLP spans from apps in the cluster | ClickHouse |
Multi-tenant isolation
org_id is always derived server-side from the API key. A cluster agent cannot
write into another tenant's data. See Multi-tenant isolation.
Comparison with the Linux agent
atherops-otel-agent (Linux) | atherops-k8s-otel-agent (K8s) | |
|---|---|---|
| Deploy target | Single Linux host | Kubernetes cluster (DaemonSet) |
| Identity table | hosts | clusters |
| Register endpoint | POST /api/v1/agents/register | POST /api/clusters/register |
| Heartbeat endpoint | POST /ingest/agents/heartbeat | POST /heartbeat |
| Key rotation | Not implemented | Automatic (age threshold) |
| Remote config | Yes (GET /api/v1/agents/{id}/config) | None |
| Credential store | /etc/atherops/credentials.json | Kubernetes Secret |