Skip to main content
Upgrading an executor moves it to a newer Novacula release — a new binary for an Agent, a new container image for an Operator. You start the upgrade from the UI, and the executor applies it on its own: for an Agent, and for most Operator releases, you don’t run anything by hand on the host or cluster. Once in a while an Operator release also changes the Helm chart, and that one does need a helm upgrade you run in the cluster — it’s uncommon, and when it comes up the UI shows the exact command to run (see Operator chart upgrades). Upgrading also unlocks newer support: once an executor is on a newer release, any chains, clients, or versions it now declares become available in the deploy wizard.

​
Prerequisites

  • A role that can manage executors: owner or admin.
  • An upgrade target offered for your executor (see How upgrades are offered).
The executor does not have to be online to receive an upgrade. If it’s offline, Novacula queues the upgrade and the executor applies it on its next check-in after it reconnects.

​
How upgrades are offered

In the sidebar, open Executors, pick your row, and find the Version & Updates panel. It shows the current version and any available upgrades and downgrades. Only releases one major version away can be applied directly. If you’re more than one major behind, the upgrade happens in two hops: upgrade to the next reachable major first, then to your target. Releases that are too far ahead still appear in the picker, but they’re disabled and labelled requires upgrade to N.x first.

​
Upgrade from the UI

1

Open the executor

In the sidebar, open Executors and pick your row. The Version & Updates panel lists the current version and what you can move to.
2

Choose a release

Click Update to the latest version for a one-click jump, or Upgrade… to pick a specific release. Each candidate shows its version; a target that’s too far ahead is disabled and labelled requires upgrade to N.x first.
3

Confirm

Novacula queues the upgrade on the executor. The panel shows a pending banner with the target version while the job is in flight.
4

Wait for the executor to apply

On its next check-in the executor downloads and applies the new version, then reports back; the row shows the new version. If the new version fails to start, the executor rolls back automatically to the version it was running.If the executor never picks the job up, the pending banner times out and offers Retry. You can also Cancel a pending upgrade at any time.

​
Operator chart upgrades

Most Operator upgrades are just a new container image, applied in-cluster with nothing for you to run. Some releases also change the Operator’s Helm chart — new RBAC, CRDs, or wiring the running image can’t grant itself. When the target release needs that, the upgrade dialog shows a Helm chart upgrade required panel:
  • It gives you the exact command to run with Helm 4.0+, in that executor’s Kubernetes cluster. The command applies the release’s chart version and pins the Operator and Gateway images to it (the Helm release is nvcl-operator in the nvcl-system namespace by default — adjust both if you installed under your own names).
  • The panel is guidance, not a gate: you can still start the upgrade from the dialog, and the running Operator will swap its own image. What it can’t do is grant itself the chart’s changes, so run the command to finish the job — otherwise the new Operator runs without the RBAC or CRDs its release expects, and Helm’s stored values still name the old image tag.
  • If the release catalog is missing the chart reference or exact version, the panel instead reports the upgrade is blocked until the release catalog is corrected, and the dialog won’t let you submit — there’s nothing to run until that’s fixed.
Agent upgrades never need this — an Agent is a single binary the executor swaps itself.

​
Downgrades and rollback

To move back to an earlier release — for example while you investigate a regression — use Downgrade… in the same Version & Updates panel and pick an older version. The same one-major-version reachability applies.
Older executors don’t know about clients or versions introduced later. Before downgrading, confirm your nodes’ chains and client versions are still supported by the target release.
You rarely need to roll back by hand: a release that fails to start is reverted automatically. A downgrade is for stepping back to a version that runs fine but that you no longer want.

​
Staying current

An executor that falls behind keeps working — your nodes and data stay reachable regardless of how old it is. Nothing is blocked when a release ages out; keeping the executor current just unlocks newer chains, clients, and versions in the deploy wizard.