Skip to content

Agent on Kubernetes

In a Kubernetes cluster, the Hexcovery agent runs as a DaemonSet — one pod on every node — installed with a Helm chart. It collects node, pod, container, and cluster metrics, watches cluster state and events, and tails container logs, shipping everything to Hexcovery over gRPC.

For a standalone Linux server, see Agent on Linux. For the full config reference, see Configuring the agent.

What it collects

The agent talks to the Kubernetes API (and the Metrics API where available) to collect:

Collector Metrics
Node Capacity / allocatable / usage (CPU, memory, pods), conditions
Namespace Pod counts by phase, container counts, aggregated resource requests/limits/usage
Pod Phase, QoS class, workload ownership, container counts, restarts, resource requests/limits/usage
Container State, readiness, restarts, resource requests/limits/usage, last termination reason / exit code
Workload Deployments, StatefulSets, DaemonSets: replicas, generation, conditions
Job Jobs and CronJobs: active/succeeded/failed pods, parallelism, completions, duration
HPA Target, min/max/current/desired replicas, CPU/memory current vs target, scaling status
PVC PV name, storage class, capacity, phase
Events Kubernetes events, streamed from the watch API and de-duplicated

It also collects container logs by reading the node's pod log directory and parsing the CRI (Container Runtime Interface) format. Logs are enriched with namespace, pod, and container, and attributed to a service and Project from pod annotations (see below).

These metrics power the Kubernetes dashboard page and are queryable in OQL.

Cluster name auto-detection

The agent detects the cluster name from common environment variables (CLUSTER_NAME, EKS_CLUSTER_NAME, GKE_CLUSTER_NAME, AKS_CLUSTER_NAME, …). You can also set it explicitly — see profiles and intervals.

Prerequisites

  • A Kubernetes cluster and Helm installed locally.
  • An API key for your organization (see API keys).
  • For pod/container/node CPU and memory usage metrics, a running metrics-server. The agent degrades gracefully without it (state metrics still flow; usage metrics are skipped).

Install

Install the chart, pointing it at your ingest endpoint and API key, and selecting a profile that matches your cluster type:

helm install hexcovery-agent ./deploy/helm/hexcovery-agent \
  --namespace hexcovery \
  --set server.endpoint=ingest.hexcovery.com:4317 \
  --set server.apiKey=YOUR_API_KEY \
  --set profile=eks

Profiles for managed Kubernetes (eks, gke, aks) enable the Kubernetes collectors and disable the host-level system collectors; bare-metal enables both. See profiles.

Exact chart location and endpoint

The chart's repository or location and your organization's exact ingest endpoint are shown in the dashboard. Use the values from your account rather than the placeholders above.

The agent reads its configuration from a ConfigMap and is granted the RBAC permissions it needs to read the Kubernetes API.

Log attribution

Container logs are attributed to a service and Project from pod metadata:

  • Set the hexcovery.com/service-namespace annotation on a pod (or its workload template) to assign it to a Project (service.namespace).
  • The service name falls back to the pod's app label.

Pods without attribution are still collected, but their logs land unattributed and won't appear on the Projects page. See Services and Projects for the model.

Security

In Kubernetes mode the agent runs with zero host privileges: no hostNetwork, no hostPID, no SYS_PTRACE capability. Container logs are read read-only from the mounted pod log directory via the CRI parser, and the container runs as a non-root user on a read-only root filesystem.

Next