Upgrading Nyxus

An upgrade is a Helm upgrade and two image tags. The awkward part is the two
image tags, and this page is mostly about not forgetting them.

Read the release notes first

Administration > System health > Release notes lists what is in each
version, and the portal tells you when a newer one exists. Read the notes for
every version between yours and the one you are going to, not just the newest

• a note about a value that changed meaning is no use if you skip past it.

The same page says how long your version is supported.

The chart

helm upgrade nyxus \
  oci://registry.nyxus.co.uk/nyxus-enterprise/charts/nyxus \
  --namespace nyxus --version <version> --reset-then-reuse-values --wait

--reset-then-reuse-values keeps what you set at install and still takes the new release’s own defaults. Do not use --reuse-values here: it takes the previous release’s computed values as the base and drops the new chart’s defaults underneath them, and because this chart pins its images by digest, the old digests survive. Helm reports success, helm list shows the new version, and the pods keep running the release before it — so check the version afterwards rather than trusting the success message. Leave the flag out altogether and every value
falls back to the chart's default, which is a quiet way to lose a log-store
URL.

The two things outside the chart

The scanner and discovery CronJobs are not in the chart. They are
yours, and they keep running the image tag you gave them - which means after a
chart upgrade they are still on the old version, indefinitely, with nothing
warning you.

Set them to the same version:

kubectl -n nyxus set image cronjob/nyxus-scanner \
  scanner=registry.nyxus.co.uk/nyxus-enterprise/scanner:<version>
kubectl -n nyxus set image cronjob/nyxus-discovery \
  discovery=registry.nyxus.co.uk/nyxus-enterprise/discovery:<version>

This is the step that gets missed, and the symptom is not an error. It is a
page that stays empty, or a source that stops reporting something a newer
collector learned to send. If something in a release is missing after an
upgrade, check these two tags before anything else.

Or from your own machine

nyxusctl does all of it with your own kubeconfig: it upgrades the release,
finds the CronJobs by their image, shows you the plan, waits for an owner to
approve in the portal, and reports progress back to System health.

pipx install --force ./nyxusctl-<version>

--force matters: pipx install does nothing at all when the command is already installed — it says so and exits successfully, which reads like it worked, and leaves you running the old one. Check with nyxusctl --version.

Download the wheel from the portal first, under System health > Updates >
Upgrade from your own machine, as an owner or an administrator of the
company hosting Nyxus. It needs Python 3.10 or newer and pipx on the machine
that runs it. A shell you opened before pipx ensurepath needs reopening
before the command is found.

--dry-run prints the plan and changes nothing.

The upgrade runs from your machine, with your credentials, on purpose. The
portal approves it; it never performs it. Nothing in the cluster gains a right
it did not already have, and the portal never holds one that could change the
cluster.

Your browser opens the portal to approve the request. Compare the code in
the browser with the one in your terminal before approving - that is what
makes the approval mean something.

Compose

Pin IMAGE_TAG in .env to the new version and bring it back up:

docker compose pull
docker compose up -d

The scanner and discovery are services in the same file, so they move with
everything else. Compose has the easier upgrade of the two.

Rolling back

helm rollback nyxus returns the release. The receiver's state volume is not
touched by an upgrade or a rollback, so accounts, enrolments and decisions
survive both.

The one thing that does not roll back cleanly is a schema the newer version
wrote. Release notes say when a version does that, which is the other reason
to read them in order.

Afterwards

Check the version line under System health, and then check something reported
recently: a collector, a scanner source, a page with a number on it. An
upgrade that finishes and then quietly stops collecting is the failure worth
catching in the first ten minutes rather than the first week.