Upgrade collectors

LinkMesh tracks the version each collector runs, tells you when a newer validated version is available, and upgrades your managed fleet safely. How the upgrade happens depends on the collector’s runtime.

Two runtimes, two upgrade paths

• Grafana Alloy (remotecfg) with a co-located agent — LinkMesh upgrades the binary in place. You click Upgrade (or roll it across a group); the agent on the host swaps the Alloy binary, restarts it, and watches it for about 30 seconds. If the new version doesn’t come back healthy, the agent rolls back to the previous binary automatically. Your config is untouched — Alloy re-fetches it over remotecfg after the restart.

• OpenTelemetry Collector (otelcol-contrib) over OpAMP — the upstream supervisor doesn’t apply remote binary updates, so LinkMesh can’t push the binary. Instead it shows you a ready-to-paste command that re-runs the installer pinned to the validated version, upgrading the collector and its supervisor together.

Which runtime am I on?

Open a collector’s detail page — the runtime is shown next to its name. If you followed Onboard Grafana Alloy you’re on remotecfg; Onboard otelcol-contrib is OpAMP.

See which collectors need attention

The Collectors list and each collector’s detail page show its running version with a badge:

• Update (amber) — a newer LinkMesh-validated version is available. Informational; upgrade when you’re ready.
• Unvalidated (red) — the collector is running a version LinkMesh hasn’t validated. This can happen after a manual install of an off-list version. Untested versions risk a supervisor/collector mismatch that can crash the collector on restart — re-pin to a validated version.

No badge means the collector is on the current validated version.

Permissions

Triggering an upgrade — single or rolling — requires the collectors:upgrade permission. Viewing versions and badges only needs read access. See Manage users, roles, and permissions to grant it.

Upgrade a single Alloy collector

1. Open the collector’s detail page and go to the Health tab.

2. If an update is available, an Upgrade button sits next to the version. Click it. LinkMesh dispatches the upgrade to the agent on that host, targeting the recommended version.

3. Watch the live stage next to the version: downloading → verifying → applying → health check → completed. The agent fetches the pinned build (or installs it from the host’s package manager), verifies it, swaps the binary, restarts Alloy, and health-checks it.

4. On completed, the version updates and the badge clears. Telemetry resumes after the brief restart.

If the upgrade fails

If the new binary doesn’t come back healthy within the health window, the agent restores the previous version automatically and the stage shows failed. The collector keeps running the version it had — nothing is left half-upgraded.

Roll out an upgrade across a group

For a Collector Group, upgrade the members a few at a time with a health gate between batches.

1. Open the group and go to the Upgrade tab.

2. Set a batch size — how many members upgrade at once. Start with 1 for the most cautious rollout.

3. Click Start rolling upgrade. LinkMesh upgrades the first batch, waits for every member to report healthy, then moves to the next.

4. The per-member table shows each collector’s stage live. If a member fails, the rollout halts — that member’s agent rolls it back, and the remaining collectors are left on their current version. Fix the issue and start the rollout again; members already on the target version are skipped.

Mixed groups

A group can hold both Alloy and OpAMP collectors. The rolling upgrade upgrades the Alloy members and marks the OpAMP members skipped — open a skipped member to get its re-pin command (below).

Upgrade an OpAMP collector (re-pin)

OpAMP collectors upgrade by re-running the installer with the validated version pinned. The collector’s detail page shows the exact command when an update is available.

1. Open the collector’s detail page. When an update is available you’ll see a re-pin panel with a copy-pasteable command.

2. Mint an enrollment token — the installer needs one.

3. Run the command on the collector’s host as root. It looks like:

   curl -fsSL https://your-linkmesh-server/install-opamp.sh | sudo bash -s -- \
     --token your-enrollment-token \
     --otelcol-version <version> --supervisor-version <version>

   This upgrades both the collector and its supervisor to the same version. The installer stops the service, swaps both binaries, and restarts.

4. The collector reconnects on the new version, LinkMesh re-pushes its config, and telemetry resumes.

Match the pair

Always upgrade otelcol-contrib and its supervisor to the same version. A version mismatch between them crashes the supervisor. The command LinkMesh shows you always pins both to the validated pair.

Roll out an OpAMP fleet

There’s no server-driven rolling upgrade for OpAMP collectors — upgrade them by re-pinning host by host. Do one host first, confirm it’s healthy and flowing telemetry, then roll the rest. For a group with OpAMP members, the rolling upgrade handles the Alloy members and points you at the re-pin for the rest.

---

Related:

• Onboard Grafana Alloy (remotecfg)
• Onboard otelcol-contrib (OpAMP)
• Collector · Collector Group
• Upgrade LinkMesh — the server itself