Skip to main content
Version: 0.10

Upgrade a sensor on Linux (Docker)

An upgrade is a new image tag and a container replacement. Because the sensor's identity lives in the mounted data directory rather than in the container, the upgraded sensor rejoins as the same sensor — same name, same history, same integration assignments. There is no re-enrolment and no new deployment token.

This assumes the layout from Install a sensor on Linux (Docker), where ./data/ and ./logs/ are mounted from the host. A sensor installed from an older version of that page may also mount a config.json, and its service may have a different name; both keep working, and neither needs to change for an upgrade.

Before you start​

Find the version to move to. The release notes list every Velum Edge release, newest first — the latest entry is the version you want, and its notes are where anything you need to know before upgrading is called out. Subscribe to the RSS or Atom feed if you would rather be told than remember to look.

Pick your moment. A task the sensor is running when the container stops is requeued when the sensor comes back rather than lost, but it does start again from the beginning. For a sensor that runs long active scans, upgrade between runs: Scan history shows what its integrations are running.

Do not disable a sensor to drain it

The console refuses every request from a disabled sensor, uploads included, so a scan that finishes while its sensor is disabled cannot deliver its result. See Disabling, revoking and deleting.

Note the version you are on. The sensor list shows it, and it is what you compare against afterwards.

Let the console tell you​

On the sensor's detail view, Update agent compares the version the sensor runs with the platform's own, and either says the agent is up to date or shows the image line to set and the command to run. It works for sensors whose Installation reads Docker. A sensor on an agent older than 0.9.1 does not report how it is installed, so the console answers "Unknown installation type": upgrade it by hand as below, and from then on it reports Docker.

The console cannot update a sensor itself. The container runs on your host, so the steps are always yours to run.

Update the image tag​

Set the tag to the version the console names, or the one you took from the release notes:

docker-compose.yml
image: ghcr.io/davydovvn/velumedge-agent:v0.9.1

Nothing else in the compose file changes. In particular, do not put a deployment token back — the sensor already has its own API token in ./data/.

Pull and recreate​

From the folder with docker-compose.yml:

sudo docker compose pull && sudo docker compose up -d

Confirm​

Within a poll interval the sensor's Version in the console shows the new build and its last-seen time is current.

If the version does not move, the container is probably still the old one: a docker compose up -d with an unchanged tag is a no-op. Check the tag, then the sensor's output (sudo docker compose logs) or its log in the mounted logs/ directory. A self-test after the upgrade confirms the new build has what it needs.

Rolling back​

Set the previous tag and repeat the pull-and-recreate. The data directory is forward- and backward-compatible in the ordinary case, so the sensor rejoins on the older build as the same sensor.

TODO

Document which sensor versions are safe to roll back to, and whether any release changes the on-disk data format in a way that prevents it.

What not to do​

Do not clear the data directory to fix an upgrade

Deleting ./data/, or starting with MODE: reset, throws away the API token. The host then enrols as a new sensor with a fresh identity, and the old entry stays in the console holding the integration assignments — which now point at a sensor that no longer exists. Recovering means reassigning every integration by hand.

Upgrade one sensor first

Upgrade a single, low-consequence sensor and let it run a full cycle before rolling the fleet. Mixed versions are expected and tolerated in the meantime; the sensor list's Version column is what tells you how far along you are.

See also​