Skip to main content

Upgrade to a New Version

How you upgrade Access Analyzer depends on how you installed it.

InstallHow it upgrades
Connected (the default)The upgrade downloads the new release's offline media from Netwrix, verifies it, and loads it into the cluster. Start it from the Settings page, let the version poller start it, or run dspm-installer upgrade --download on the host.
Air-gappedYou download the new media on a connected machine, copy it to the server, and run dspm-installer upgrade --bundle-dir.
Registry (a connected install made before media installs, or with DSPM_MEDIA_INSTALL=false)ArgoCD pulls new releases from the Netwrix registry. You tell it which version to run with dspmctl. Convert a registry install to downloaded media to upgrade the same way as any connected install.

Pick the tab that matches your install.

The installer installs dspmctl at /usr/local/bin/dspmctl. It's a small shell wrapper that runs kubectl exec into the dspmctl pod in the argocd namespace. That pod signs in to ArgoCD and runs argocd commands for you. You don't need the argocd command-line interface (CLI) on the host.

Run dspmctl and dspm-installer with sudo. Only root can read the default kubeconfig at /etc/rancher/k3s/k3s.yaml, so without sudo, kubectl falls back to localhost:8080 and fails with "connection refused."

note

On RHEL and similar distributions, /usr/local/bin usually isn't on the PATH, so dspm-installer and dspmctl can fail with command not found. Run them by their full paths instead, for example sudo /usr/local/bin/dspm-installer or sudo /usr/local/bin/dspmctl.

Check Which Version Is Running​

Start by checking which version is running:

sudo dspmctl version

Compare the output with the latest release Netwrix has announced. If they match, Access Analyzer is already up to date.

Choose an Upgrade Command​

Find your situation in the table and run its command on the server. Every command in the table runs dspm-installer upgrade.

You want toRun
Upgrade a connected install to the newest stable releasesudo dspm-installer upgrade --download
Upgrade a connected install to a specific releasesudo dspm-installer upgrade --download --target-revision <version>
Upgrade a connected install from media you copied to the serversudo dspm-installer upgrade --bundle-dir <path-to-archive>
Upgrade an air-gapped installsudo dspm-installer upgrade --bundle-dir <path-to-archive>
Convert a registry install to downloaded media and upgrade itsudo dspm-installer upgrade --download --migrate --target-revision <version>
Convert a registry install to downloaded media on the same releasesudo dspm-installer upgrade --download --migrate --target-revision <installed-version>
Connect an air-gapped installsudo --preserve-env=LICENSE_KEY dspm-installer upgrade --connect
Connect an air-gapped install and upgrade itRun upgrade --connect, then upgrade --download --target-revision <version> as a second command
Redeploy the installed release, or downgradeAdd --allow-downgrade to the upgrade command
Preview any of these without changing anythingAdd --dry-run

Without --target-revision, upgrade --download upgrades to the newest stable release. For converting and connecting, see Convert or connect an install.

These changes have no command:

  • Connected to air-gapped. --connect works in one direction only, so returning to air-gapped takes a reinstall. upgrade --bundle-dir works on a connected install, but the install stays connected: the version poller stays on and the license key stays saved.
  • Connect and upgrade in one run. --connect doesn't redeploy or change the release, so the upgrade is a second command.
  • Registry install straight to air-gapped media. --migrate requires --download, so convert the registry install while it's online first.
  • upgrade --download on an air-gapped install. The command refuses and exits with code 16. Run upgrade --connect first.

Upgrade​

All three ways to upgrade a connected install run the same upgrade. Only one upgrade can run at a time.

Upgrade from the Settings page​

You need the Administrator role.

  1. Go to Settings > System.
  2. Select the version and click Update. The confirmation says the app downloads the release media and is briefly unavailable.
  3. Watch the progress through these phases: Checking prerequisites, Downloading media, Deploying, and Waiting for services.
  4. When the upgrade finishes, reload the page.

If the upgrade fails, the page shows the reason and what to do next.

What you seeWhat it means
Check the licenseNetwrix rejected the license. Nothing changed.
The upgrade couldn't start, No release available, or Download failedNothing changed. For a download failure, free some disk space and click Retry.
Retry or contact supportThe installer couldn't load the media. Nothing changed.
The upgrade failed while applying, The new version didn't become healthy, or The new version failed to startThe cluster may have changed. Click Roll back to return to the previous version.
Contact supportThe installer couldn't apply the new version.

If another upgrade is already running, the page says so.

Upgrade automatically​

The version poller checks for new releases every 12 hours. When a newer release matches the install's version constraint and Netwrix has published its media, the poller starts the same upgrade the Settings page starts.

If an upgrade fails partway through deploying, the poller doesn't retry it. Fix the cause, then run sudo dspm-installer upgrade --download on the host.

Upgrade from the host​

Upgrade to the newest stable release:

sudo dspm-installer upgrade --download

Upgrade to a specific release:

sudo dspm-installer upgrade --download --target-revision 1.5.0

--download reads the license key from /etc/dspm/installer.yaml. On a host without a saved key, pass the key through the environment, as the install does:

read -rs LICENSE_KEY && export LICENSE_KEY
sudo --preserve-env=LICENSE_KEY dspm-installer upgrade --download

To upgrade a connected install from media you already copied to the server, pass the archive instead of --download:

sudo dspm-installer upgrade --bundle-dir /etc/dspm/media/dspm-airgap-media-v<version>-<arch>.tar.gz

The install stays connected afterwards. See Download the new release for how to get the archive.

If the cluster already runs the newest release, the command prints The cluster is already on the newest release (v<version>); nothing was changed. and exits 0. A scheduled run can use this to distinguish "nothing to do" from a failure.

Add --dry-run to check the preconditions and free space and print the upgrade plan without downloading anything.

What an upgrade does​

  1. Checks the preconditions: the cluster runs from offline media, the root application's automated sync is on, the release is newer than the installed one, and the server has enough disk space. If any check fails, the upgrade exits with code 16 and changes nothing.
  2. Downloads and checks the media, or reuses media already on disk.
  3. Pauses automated sync, so ArgoCD doesn't act on a half-loaded release.
  4. Removes images older than the previous release from the in-cluster registry. The registry keeps the current release and the one before it.
  5. Loads the new charts and images into the cluster and points the root application at the new version.
  6. Turns automated sync back on and waits for every application to become healthy.
  7. Deletes the downloaded media.

If something interrupts the upgrade (Ctrl-C, a dropped SSH session, or a stopped pod), the upgrade turns automated sync back on before it exits. Run the same command again to finish the upgrade.

Roll Back an Upgrade​

On a connected install, when an upgrade fails after it starts applying the new version, the Settings page offers Roll back. The button points the install back at the version the upgrade started from.

From the host, a rollback is a re-pin. The previous chart tag and images stay in the cluster, so you don't need the old media. The in-cluster registry keeps only the previous release's images, so a rollback works one release back. To roll back further, you need that release's media again.

For the precautions to take first and the full procedure, see Rolling back to a previous version. In short, read the previous version from the annotation, then run all three dspmctl commands. set-revision turns off automated sync so self-heal doesn't immediately re-sync the new version, sync applies it, and enable-auto turns automated sync back on. If you skip enable-auto, the netwrix app never syncs again, and the next dspm-installer upgrade refuses to run.

sudo kubectl -n argocd get application netwrix \
  -o jsonpath='{.metadata.annotations.dspm\.netwrix\.com/previous-target-revision}'
sudo dspmctl set-revision netwrix v<previous>
sudo dspmctl sync netwrix
sudo dspmctl enable-auto netwrix
sudo dspm-installer wait-for-apps
warning

A re-pin doesn't roll back database schema changes the new release made.

Upgrade Exit Codes​

CodeMeaningWhat to do
0The cluster runs the new release and every application is Synced and Healthy, or the cluster already runs the newest release.Nothing.
10Netwrix rejected the license key.Check the key, then run the command again.
15The command couldn't load or deploy the media, and the cluster is still on the previous release. With --migrate, the command also exits with this code when an agent node runs on a different CPU architecture from the server.Fix the cause and run the command again. The deploy is idempotent.
16A precondition failed, such as no cluster or root application, the install type doesn't match the command, the release isn't newer, automated sync is off, or the media volume lacks free space. Nothing changed.Read the message. For automated sync, run sudo dspmctl enable-auto netwrix first. For a same-version redeploy, add --allow-downgrade. For free space, free space on the media volume or use --tmp-dir.
17The command couldn't download, verify, or unpack the media. Nothing changed.Run the command again. It resumes the download.
20No release matches --target-revision, or the release has no media for this architecture.Check the release number.
60The command couldn't apply the new version, couldn't switch to the in-cluster source, or couldn't turn automated sync back on.Check /var/log/dspm-installer.log, run sudo dspmctl enable-auto netwrix, and run the command again.
70The new version applied, but ArgoCD didn't acknowledge it or the release didn't become healthy within --timeout. The new pin stays in place and ArgoCD keeps reconciling.Run sudo dspm-installer wait-for-apps to keep waiting, or roll back.
71A pod failed to start.Check the failing pod with sudo kubectl get pods -A, then roll back or fix the cause and run the command again.

Troubleshooting an Upgrade​

Automated sync is still off after a failed upgrade. Run the same upgrade command to finish it, or turn sync back on with sudo dspmctl enable-auto netwrix.

An upgrade exits with code 70, and running it again says the cluster is already on that version. The new version is in place but wasn't healthy in time. Run sudo dspm-installer wait-for-apps.

The upgrade stops with exit code 16 about free space. Free space on the media volume, or point the media elsewhere with --tmp-dir. The check counts media from other releases as free, because the upgrade deletes them, but it deletes nothing unless the check passes.

The progress bar shows garbled characters. Run with --progress ascii, or set DSPM_PROGRESS=ascii.

Checking the Result​

Wait one to five minutes for the pods to restart, then check the version again:

sudo dspmctl version

The output should show the version you set. Pod restarts take longer on a busy server, so if the version hasn't changed after five minutes, wait another two or three minutes and run the command again.

For a detailed view of the sync, ask ArgoCD directly:

sudo kubectl exec -n argocd -ti deploy/dspmctl -- argocd app get argocd/netwrix

Check TARGET REVISION and Sync Status. The netwrix app only manages the child Application resources; each child still has to sync on its own to roll new pods. A child with auto-sync enabled syncs shortly after the parent. Otherwise, sync it directly, for example:

sudo dspmctl sync netwrix.webapp
Troubleshooting: dspmctl hangs after a cancelled command

If you press Ctrl-C part-way through a dspmctl command (for example, after typing the wrong version), every later dspmctl call can hang at Logging in to ArgoCD ... and never return. Even argocd version --client, which needs no network at all, hangs, so the cause is local to the pod. Every dspmctl invocation runs inside the same long-lived dspmctl pod, and the interrupted run leaves the argocd binary in that pod unresponsive.

Restart that pod and re-run the upgrade:

sudo kubectl rollout restart deploy/dspmctl -n argocd
sudo kubectl rollout status deploy/dspmctl -n argocd
sudo kubectl exec -n argocd deploy/dspmctl -- argocd version --client   # should print instantly now
sudo dspmctl set-revision netwrix 1.1.2
sudo dspmctl sync netwrix

If argocd version --client still hangs after the restart, dspmctl isn't usable in that environment. Everything dspmctl does is an edit to the netwrix ArgoCD Application object, so make the same changes directly with kubectl from the host.

Pin the umbrella chart:

sudo kubectl patch application netwrix -n argocd --type merge \
  -p '{"spec":{"source":{"targetRevision":"1.1.2"}}}'

Set the Helm parameter that propagates the version to the child apps. List the parameters, find the 0-based position of config.spec.source.targetRevision, and use it as N:

sudo kubectl get application netwrix -n argocd \
  -o jsonpath='{range .spec.source.helm.parameters[*]}{.name}{"\n"}{end}'
sudo kubectl patch application netwrix -n argocd --type json \
  -p '[{"op":"replace","path":"/spec/source/helm/parameters/N/value","value":"1.1.2"}]'

Turn auto-sync back on and force an immediate refresh:

sudo kubectl patch application netwrix -n argocd --type merge \
  -p '{"spec":{"syncPolicy":{"automated":{"selfHeal":true,"prune":true}}}}'
sudo kubectl annotate application netwrix -n argocd argocd.argoproj.io/refresh=hard --overwrite
sudo kubectl get applications -n argocd -w