Install the Kubernetes agent

Use the wizard (recommended)

The easiest way to connect a cluster is the in-app wizard: open the Kubernetes page and click Connect a cluster. It guides you step-by-step — create or choose an API key, pick the VerOps agent or OpenTelemetry, copy a personalized config — and detects automatically when your cluster's first data arrives.

The manual steps below produce exactly the same result as the wizard — use them for GitOps, scripted installs, or when you want to see every moving part.

Before you start

1. A cluster you have admin access to (kubectl auth can-i create clusterrole should answer yes) and a working kubectl/helm pointed at it — check with kubectl config current-context.
2. An API key: in app.verops.io go to Settings → API Keys → Create API Key. Copy it when shown — it starts with ta_live_ and is displayed only once (the platform stores a hash).
3. A cluster name humans recognise, e.g. prod-east or staging-eu.

Watch out: the cluster name is what shows up in alerts and the cluster selector. prod-east paged at 3am tells you everything; cluster1 tells you almost nothing.

Choose your install path

VerOps supports two ways to monitor a cluster. Both feed the same platform (dashboards, alerts, Data Explorer); they differ in how much of the Kubernetes page they light up:

	VerOps Kubernetes agent	OpenTelemetry collector
Setup effort	One Helm install	Collector deployment + RBAC + kube-state-metrics + several receivers to configure
Cluster inventory	Full object detail, watched live from the Kubernetes API — node conditions, pod restarts, service ports and selectors, PVC status, labels	Aggregated metric series only; detail drawers show what the metrics carry
Node and pod usage	Kubelet stats via the bundled node DaemonSet	Kubeletstats receiver (you configure it)
Events	Native Kubernetes Event objects with reason, message and count	Requires the additional k8sobjects receiver; reduced detail
Agent health	Live heartbeats — the platform marks the agent offline within ~90 seconds	No heartbeat; you infer collector health from data flow
Dashboards, alerts, Data Explorer on k8s metrics	Yes	Yes
Version sensitivity	Matched to the platform	Kubernetes metric names vary across collector versions and can miss the platform's expected names
Reuse an existing pipeline	—	Yes — if you already run an OTel collector fleet, add one exporter

Recommendation: install the VerOps agent unless you already operate an OpenTelemetry pipeline. It is the only path that gives the Kubernetes page its full object inventory, native events and offline detection — and it's one command. Running both is safe: the platform merges the two sources and prefers the agent's richer record for a cluster reporting via both.

Install with Helm

helm repo add verops https://charts.verops.io
helm repo update
helm install verops-agent verops/verops-k8s-agent \
  -n verops --create-namespace \
  --set apiKey=<your ta_live_ key> \
  --set backendUrl=https://app.verops.io \
  --set clusterName=prod-east

This installs, in the verops namespace: a one-replica Deployment (cluster mode — watches nodes, workloads, services, storage and events via the Kubernetes API), a DaemonSet (node mode — reads real CPU/memory from each kubelet), a read-only ClusterRole, and a Secret holding your API key.

Configuration values

Value	Default	What it does
apiKey	required	Your ta_live_ ingest key; stored in a chart-managed Secret. Use existingSecret (+ apiKeySecretKey) to reference a Secret you manage instead.
backendUrl	https://app.verops.io	Where the agent ships data. Set endpoint instead if your deployment has a dedicated ingest URL — it takes precedence.
clusterName	default	Name shown in the cluster selector and stamped on every event. Set it whenever you run more than one cluster.
resources	50m/64Mi req, 500m/256Mi lim	Applied to both workloads; override per workload with clusterAgent.resources / nodeAgent.resources.
clusterAgent.enabled / nodeAgent.enabled	true	Turn off cluster inventory or per-node kubelet stats independently.
heartbeatSeconds	30	Heartbeat interval; the platform marks the agent offline after ~3 missed beats.

Upgrade and uninstall

# upgrade to the latest chart, keeping your settings
helm repo update
helm upgrade verops-agent verops/verops-k8s-agent -n verops --reuse-values

# remove the agent (your data on VerOps is kept)
helm uninstall verops-agent -n verops

Verify it works

1. Pods are running — expect one cluster-agent pod plus one node-agent pod per node:

$ kubectl get pods -n verops
NAME                              READY   STATUS    RESTARTS   AGE
verops-agent-cluster-...          1/1     Running   0          1m
verops-agent-node-...             1/1     Running   0          1m

2. Open Kubernetes in the app. Within about a minute a cluster card appears with your cluster name and a VerOps Agent source chip (the page auto-refreshes every 20 seconds — there's also a Check now button on the onboarding screen).
3. Click the cluster: Nodes and Pods & Workloads populate first; CPU/memory usage fills in as kubelet stats start flowing from the node agents.

Alternative: OpenTelemetry collector

If you already run an OpenTelemetry collector fleet — or need a vendor-neutral pipeline — point it at VerOps instead. Your cluster appears on the same Kubernetes page with an OTel source chip and aggregated metrics.

• Receivers: k8s_cluster (cluster state), kubeletstats (node/pod usage), a prometheus scrape of kube-state-metrics (services, deployments), and optionally k8sobjects (events).
• Exporter: otlphttp to https://ingest.verops.io with header Authorization: Bearer <your ta_live_ key>.
• OTLP traces, metrics and logs from the same collector are equally welcome — they power APM, dashboards and the Data Explorer regardless of which Kubernetes path you choose.

Prerequisite: the collector config's prometheus scrape expects kube-state-metrics to be running in the cluster — if you don't already have it, install it from the prometheus-community Helm chart (for example into a metrics namespace). Without it, the pod and deployment metrics that come from kube-state-metrics never arrive (the k8s_cluster and k8sobjects receivers still work, so the cluster appears but some views stay thin). Verified in a live end-to-end install.

Tip: whichever path you choose, first data appears about a minute after install, and the cluster card then shows a source chip (VerOps Agent or OTel) telling you which source feeds it.

Watch out: Kubernetes metric names changed across OTel collector versions (e.g. k8s.pod.cpu.usage vs older ...utilization). VerOps expects the current semantic conventions; if tabs stay empty on an OTel-sourced cluster, check your collector version and receiver config first.