Upgrade an executor

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 — or let the Hub start it for you with automatic updates — 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; requested by hand, that one needs 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 on the Overview tab. It shows the Current version and, when there is one, the Available upgrade — the nearest newer release — with its release date. 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 needs major N first.

​

Upgrade from the UI

​

Cancel an upgrade

While an upgrade is pending, the panel offers Cancel upgrade. Cancelling is a request to the executor, not an instant stop, and what happens depends on how far the executor has got:

• Not yet applying — the executor abandons the upgrade and stays on its current version. For an Agent that means it is still downloading, verifying, or unpacking the new release into a staging area; for an Operator, it hasn’t yet written its new configuration or Deployment, or started a Helm Job.
• Already applying — the upgrade finishes. Nothing is rolled back.

The cancel request stays in place until the executor acknowledges it, for up to 6 hours (counted from the cancel request, or for an automatic update from when it started) — so an offline executor that reconnects later still sees it.

​

Automatic updates

Instead of requesting each upgrade by hand, you can let the Hub upgrade the executor for you. The Automatic updates card sits on the executor’s Overview tab, below Version & Updates, for both Agents and Operators. Its badge reads Enabled, Disabled, or Unavailable. With automatic updates enabled, the Hub moves the executor to the latest release when it becomes available. Only one executor per organization is upgraded at a time, and the Hub waits up to 6 hours for the executor to report the new version.

• Enable updates turns them on after a confirmation. An upgrade can restart the executor and affect the nodes it manages; node updates that follow can need a full resync.
• Once enabled, the card shows the maintenance window — for example 02:00–05:00 · Europe/London — or Any time. Its info tooltip gives the next time the window permits a start; that’s not a scheduled update, since an upgrade starts only when a newer release is available and no other executor in your organization is in an automatic upgrade.
• Edit schedule opens the window inline: switch on Maintenance window, then set a Start time, an End time, and a Time zone (an IANA name such as Europe/London), and Save. A window may cross midnight; equal start and end times permit no upgrades. With the window off, an upgrade may start at any time.
• Pause turns automatic updates off and keeps the window for next time. Pausing doesn’t stop an upgrade the executor is already applying; one that hasn’t got that far is cancelled, as with Cancel upgrade.

While an automatic upgrade runs, the card shows Automatic update to N started with the time, and offers Cancel pending update — the same request as Cancel upgrade: an upgrade already applying on the host may finish, and nothing is rolled back. A cancel doesn’t hold the release back: once the executor confirms it, the Hub requests the same release again right away, in the check-in that confirms the cancel, while automatic updates stay enabled — Pause to stop that. After a failure — including an upgrade that doesn’t report back within 6 hours — the card notes that automatic updates to N are blocked: the Hub won’t try that release again automatically, on this executor or on any other executor of the same backend in your organization. You can still request it by hand, and the block lifts once the executor reaches that version. Show history lists the executor’s automatic upgrades — Update started, Update completed, Update failed — newest first; Older events pages back and Latest returns to the newest. Owners and Admins manage automatic updates; Members see the card read-only. Changes are recorded in the audit log as executor.upgrade_policy.changed.

​

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. Release 0.1.18, for example, needs chart 0.1.13, which runs each pool’s gateway as a Deployment of its own and adds the RBAC for it — see Provision on Kubernetes. When you request such an upgrade by hand, the upgrade dialog shows a Helm chart upgrade required panel instead of the Request upgrade button:

• 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, so running it completes the upgrade (the Helm release is nvcl-operator in the nvcl-system namespace by default — adjust both if you installed under your own names).
• 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 — there’s nothing to run until that’s fixed.

An upgrade that reaches the Operator by other means — an automatic update, for instance — can apply the chart itself. With the chart value selfUpdate.enabled: true (the default), the Operator runs helm upgrade in a Kubernetes Job, using the Helm image in selfUpdate.helmImage (alpine/helm:4.2.3). With selfUpdate.enabled: false the Operator doesn’t update itself at all — not even an image-only release — so run the chart command yourself. A self-updating Operator that has no Helm image (a hand-written [self_update] section, for example) fails a release that needs a newer chart with an error such as operator cannot upgrade chart: Helm image is not configured instead of quietly updating only the image. An Operator that doesn’t know its installed chart version updates only its image and logs a warning, and automatic updates never pick a chart-changing release for such an Operator — they need it to report its installed chart version. Agent upgrades never need this — an Agent is a single binary the executor swaps itself.

​

Rollback

You rarely need to roll back by hand: a release that fails to start is reverted automatically. Moving an executor back to an earlier release isn’t offered in the console.

​

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.