Upgrading the Agent

How to upgrade the agent, what to expect, and how long each version is supported.

How to upgrade the agent running in your Kubernetes cluster, what to expect during an upgrade, and how long each version is supported.

TL;DR

One command. The dashboard pre-fills it for you on the cluster detail page.
Nothing breaks. Identity, cluster, incidents, history, and credentials are all preserved.
Seconds of downtime. A rolling update — old pod drains, new pod reconnects.
Old agents always connect. Versions are supported for 6 months, deprecated through 12, beyond that unsupported — but never refused.

What an upgrade does NOT do

Re-register your agent. The hub identifies it by certificate fingerprint, not by pod identity.
Require a new auth token or credentials. The token is only used at first install.
Touch your mTLS certificate. It lives in a Kubernetes Secret that helm upgrade doesn’t replace.
Lose any incidents, cluster association, or history. Everything is tied to the agent’s stable identity.
Require manual steps after the helm command runs. The agent reconnects on its own.

Upgrade procedure

Find the command in the dashboard

When a newer agent version is available, the dashboard tells you in two places:

Clusters list — the version column shows a coloured badge with an up-arrow and a tooltip: “Upgrade available: <current> → <latest>”.
Cluster detail — an Upgrade available banner. Expand it to see the version change, a View changelog link, and a pre-filled helm upgrade command with a copy button.

The pre-filled command already contains the correct chart version, your cluster name, and the hub address. Copying it from the banner is the recommended path — you don’t have to assemble it by hand.

Custom values.yaml? Click View changelog before upgrading — any chart-level restructures (renamed keys, removed values) are flagged there, so your overrides are never silently broken.

Run the upgrade

The dashboard’s pre-filled command is the recommended path. The snippet below is for reference:

helm upgrade --install dataagent oci://ghcr.io/data-agent-co/dataagent-chart \
  --version '<new-version>' -n dataagent \
  --reset-then-reuse-values

Requires Helm ≥ 3.14. --reset-then-reuse-values was added in Helm 3.14 (January 2024). Check yours with helm version; on an older Helm, upgrade Helm first.

--reset-then-reuse-values resets to the new chart version’s defaults and then re-applies every setting you supplied at install — so new chart features come in with their defaults while your customizations are preserved. The auth token isn’t needed for upgrades — the agent identifies itself via its mTLS certificate, not the token, which is only used at first registration.

--install keeps the command idempotent: it works whether the release currently exists or was previously uninstalled (e.g. after a rollback that removed the release).

Verify it worked

The agent reconnects within seconds and its next heartbeat reports the new version. You’ll see the upgrade reflected in the dashboard automatically:

The cluster-list badge updates to the new version (the up-arrow disappears once you’re on the latest release).
The Upgrade available banner on the cluster detail page clears on its own.

You can also confirm locally:

helm list -n dataagent          # shows the deployed chart version
kubectl get pods -n dataagent    # new pod Running

From your monitoring side, the only signal of an upgrade is one pod restart and a brief reconnect on the tunnel — nothing else changes.

Running multiple clusters?

Upgrade one cluster first. Wait until the upgrade banner clears and the version badge updates on its cluster detail page, then proceed with the rest. The hub treats each cluster’s agent independently — there’s no global rollout coupling.

What happens during an upgrade

Concern	What happens
Downtime	Seconds. Rolling update.
Identity	Preserved. The mTLS certificate Secret survives pod replacement, so the new pod reconnects as the same agent.
Credentials	No new credentials needed. The auth token is only used at first registration.
Cluster, incidents, history	Preserved. Everything is tied to the agent’s stable identity, not the pod.
Data in flight	No loss. On reconnect the agent re-sends its current cluster state.

How the rolling update flows

For the curious — the full sequence the hub sees during an upgrade:

sequenceDiagram
    participant Op as You
    participant K8s as Your cluster
    participant Agent as Agent pod
    participant Hub as DataAgent hub
    Op->>K8s: helm upgrade --install dataagent --version X.Y.Z
    K8s->>Agent: Rolling update (old pod drains, new pod starts)
    Agent->>Agent: Mount existing mTLS cert from Secret
    Agent->>Hub: Reconnect with same certificate
    Hub->>Hub: Match cert fingerprint → same agent, same cluster
    Agent->>Hub: Heartbeat reports new version
    Hub->>Op: Upgrade banner clears

Version support policy

Your agent always connects, regardless of version age. Older agents may miss newer hub-driven features, but the connection is never refused. The classification below drives dashboard warnings — nothing more.

Agent age	Status	What you see
Latest release	Supported	No badge — you’re current.
Under 6 months	Supported	Info badge: “Upgrade available”.
6–12 months	Deprecated	Prominent warning badge and banner.
Over 12 months	Unsupported	Warning badge with an “unsupported” label.

Support is time-based, measured from each release’s publish date — not by how many newer versions exist. We recommend staying within the supported window. Deprecated and unsupported agents should be upgraded at your earliest convenience.

Rollback

Rolling back is a normal, supported operation — same identity persistence as an upgrade, same seconds-long reconnect, no special steps.

To see the revisions Helm has on file:

helm history dataagent -n dataagent

To roll back to the previous revision:

helm rollback dataagent -n dataagent

This reverts the chart revision. Identity is preserved exactly as in an upgrade — the mTLS certificate is untouched, so the agent reconnects as the same agent with the same cluster association.

FAQ

Do I need a new auth token to upgrade? No — see Credentials in the table above. The token is only used the first time an agent registers; subsequent connections use the long-lived mTLS certificate.

Will I lose my incidents or cluster history? No — see Cluster, incidents, history above. They’re tied to the agent’s stable identity, not the pod.

Can I skip versions — e.g. upgrade from an old release straight to the latest? Yes. Upgrade directly to the latest version. There’s no need to step through intermediate releases.

What if the upgrade fails? Run helm rollback dataagent -n dataagent to return to the previous version. Your agent reconnects with the same identity. Then check the new version’s changelog (linked from the upgrade banner) before retrying.

How do I check which version I’m running? The version is shown on the clusters list and cluster detail pages in the dashboard. Locally, run helm list -n dataagent.

Where do I see what changed between versions? The View changelog link in the upgrade banner points to the release notes for the target version.

Installing the DataAgent Agent on Amazon EKS — first-time install + requirements.
Agent Permissions & Security Posture — every RBAC rule, with rationale.