Skip to main content

Agent updates

Host agents can replace their own binary with a newer release. The server only offers releases it can verify, and an administrator decides whether updates are automatic or requested one host at a time.

Where the releases come from​

The continuous integration of the project publishes every Linux, Windows and macOS agent build to the release bucket, and writes releases.json next to them. The file lists the versions with the URL, SHA-256 checksum and size of each binary.

The server reads that file from RELEASE_MANIFEST_URL. It defaults to the project's public release bucket. Set the variable to an empty value to turn managed updates off, or point it at your own bucket.

The Published versions table on the Agents page lists the versions of that file. When an administrator asks for one of them, the server downloads it, checks its SHA-256 checksum, and stores it on the server. The agent then gets the update.

Your own releases can also be uploaded: select Upload a release on the Agents page, and choose the operating system, the architecture, notes and the binary. Uploaded releases appear under Agent releases.

Update automatically​

On the Settings page, under Agent updates, select Update host agents automatically. When it is on, each enabled host agent that is behind the latest published release is moved to it within ten minutes. The agent picks up the update on its next heartbeat, replaces its own binary, and reports the new version.

This setting is off by default.

Update one host, or all hosts​

  • Update on a row moves that agent to a version you choose.
  • Update all hosts moves every enabled host agent to a version you choose, once.

The agent's Update column shows whether it is up to date, behind, or waiting for its next heartbeat.

Which agents cannot update​

  • Container agents are updated by rolling out a new image. The agent detects that it runs in a container and ignores updates, and the server refuses to offer one.
  • Kubernetes node agents follow the same rule: roll out a new chart or image.
  • Hosts with VOP_MANAGED_UPDATES=false keep their binary until someone changes it.

Bucket permissions​

The bucket must allow public reads of releases.json and of the binaries, because the installers and the agents download them without credentials. Only the continuous integration credentials should be able to write to it.