Upgrade LinkMesh

A LinkMesh deployment has parts that version independently: the server (with its embedded UI), the collector runtime on each managed host (otelcol-contrib supervised by opampsupervisor, or Grafana Alloy), the optional agent on hosts where you run one for onboarding, and the server’s stored state (its database and its internal certificate authority). This page covers how to move all of them from one version to the next without interrupting the fleet.

The good news up front: telemetry never travels through the server, so even while the server is being upgraded your collectors keep running and your data keeps flowing. What an upgrade briefly affects is the control plane — the UI, the API, config push, and fleet status.

When the server comes back, every collector reconnects its control channel on its own within a short backoff — the enrollment token each host holds is a durable reconnect credential, so a restart or upgrade needs no manual re-enrollment. You’ll see the fleet flip from offline back to healthy within a minute or two of the server reporting healthy.

The one rule: preserve the state

Carry the state volume across an upgrade

All of LinkMesh’s state — collectors, pipeline config, users, roles, and enrollment tokens — lives in its datastore. Carry it across every upgrade: on Kubernetes that’s the PersistentVolumeClaim (and your MongoDB, if external); on a package install it’s the server’s data directory. An upgrade that starts against empty storage comes up as a fresh install.

If you ever move the server to fresh storage, restore the state first. There is no separate secret to keep in sync — authentication is Bearer-over-TLS and the server holds no private certificate authority.

Upgrade order: server first

Always upgrade in this order:

1. Server — first, on its own. A newer server understands older collectors and agents, but an older server does not understand newer ones. Upgrading the server first is the only safe direction.

2. Collector runtimes — next, and whenever convenient. Their configuration is delivered by the server through each runtime’s own channel (Alloy over remotecfg, otelcol-contrib over OpAMP), so the runtime binary and its config move independently — there is no coordinated step.

3. Agents (where you run one) — last, at your own pace. The agent is the optional onboarding edge connector, not every host has one; where present it may lag the server by one minor version and keep working normally. The fleet UI flags any agent that has drifted further behind so you know which hosts to attend to.

Upgrade the server

1. Take a state backup. Snapshot the database (or the BoltDB data directory). This backup is your only way back across a release that changes the data format — see Rollback below.

2. Roll the new version. On Kubernetes, point the deployment at the new image tag and let it roll. On a package install, run your package manager’s upgrade (apt upgrade linkmesh-server / yum update linkmesh-server) and restart the service.

3. Watch the first boot. On startup the server applies any forward data migrations the new version needs and records the new version. Confirm the server reports healthy and the UI loads.

Note

Migrations only run forward. A server will refuse to start against a database written by a newer version than itself, which is what makes a careless downgrade safe-by-default rather than silently destructive.

Upgrade the agents

On hosts where you run the optional onboarding agent, it’s upgraded by the operator on that host — there is no remote “upgrade” button, by design. Use whichever you installed with:

• Package install: apt upgrade linkmesh-agent or yum update linkmesh-agent, then restart the service.
• Install script: re-run the same install one-liner you used to enrol the host; it installs the current version in place. Existing enrollment (the durable token) is preserved.

You don’t need to do every host at once. Within the one-minor skew window the fleet runs mixed versions happily; work through the hosts the collector list flags as out-of-date first.

Upgrade the collector runtimes

Because the server delivers collector configuration, the runtime upgrades on its own track:

• otelcol-contrib (OpAMP): re-run the install-opamp.sh one-liner on the host. It installs the runtime version LinkMesh currently pins and re-applies the supervised setup; the server keeps driving config across the change.
• Grafana Alloy (remotecfg): upgrade Alloy from its own repository (apt upgrade alloy) and restart it. Its remotecfg block keeps pulling configuration from the server unchanged.

No server-side step is required for either.

Rollback

Server rollback is a version pin: point back at the previous image tag, or downgrade the package, and restart.

Rollback only within the same data version

A rollback is safe only if the previous version reads the same data format. If the upgrade you are undoing changed the data format, the older server will refuse to start against the newer database (the downgrade guard above). In that case the way back is to restore the pre-upgrade backup you took in step 1 — which is why that step is not optional.

Agents and collector runtimes roll back the same way you rolled them forward: install the previous package version, or re-run an installer pinned to the prior version.

Pre-upgrade checklist

1. The server’s state volume (database / data directory) carries over, or you have a fresh backup of it.

2. You’re upgrading the server first, agents and collectors after.

3. You’ve noted the current version so you know what to pin back to if you need to roll back.