From afed9bdd03f097640e2ed2d6d7b04af8acd449fb Mon Sep 17 00:00:00 2001 From: thobed <10742470+thobed@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:21:09 -0400 Subject: [PATCH 1/4] Add upgrade guide for Access Analyzer install Adds a new page documenting how dspmctl handles upgrades: when auto-tracking already covers it, the steps to pin and roll out a specific version, and how to verify a sync completed. Also fixes an unclosed
tag in requirements.md that was breaking the MDX build. Generated with AI Co-Authored-By: Claude Code --- docs/accessanalyzer/26.1/install/index.md | 2 + .../26.1/install/requirements.md | 2 +- .../26.1/install/upgrade-to-a-new-version.md | 51 +++++++++++++++++++ 3 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md diff --git a/docs/accessanalyzer/26.1/install/index.md b/docs/accessanalyzer/26.1/install/index.md index 7054502a4c..54f216def5 100644 --- a/docs/accessanalyzer/26.1/install/index.md +++ b/docs/accessanalyzer/26.1/install/index.md @@ -13,6 +13,8 @@ An installation takes three steps, each covered on its own page. After the first sign-in, the [Guides](../guides/index.md) walk you through scanning your first source. +After you're running, see [Upgrade to a new version](upgrade-to-a-new-version.md) for how new releases roll out and when you need to act. + ## People You Need You need an administrator with root access to the Linux server, either signed in as root or using `sudo`. The installer writes to `/etc/dspm`, `/var/log`, and `/usr/local/bin`, so a non-root account can't complete it. diff --git a/docs/accessanalyzer/26.1/install/requirements.md b/docs/accessanalyzer/26.1/install/requirements.md index 76ecaa0ac0..711d0b6b1b 100644 --- a/docs/accessanalyzer/26.1/install/requirements.md +++ b/docs/accessanalyzer/26.1/install/requirements.md @@ -23,7 +23,7 @@ On a distribution the installer doesn't recognize, the preflight check reports a You pick a size when you install. The size sets the CPU and RAM the installer requires, the disk it recommends, and how much capacity Access Analyzer reserves for itself. _The default is **medium**_. -| Size | CPU cores | RAM | Disk
(/var/lib) | Designed for | +| Size | CPU cores | RAM | Disk
(/var/lib) | Designed for | |---|---|---|---|---| | small | 8 | 32 GB | 400 GB | Up to about 25 million objects and fewer than 5,000 identities. | | medium | 16 | 64 GB | 1,000 GB | Up to about 200 million objects and 5,000 to 25,000 identities. | diff --git a/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md b/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md new file mode 100644 index 0000000000..33ccbcb909 --- /dev/null +++ b/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md @@ -0,0 +1,51 @@ +--- +title: Upgrade to a New Version +description: How dspmctl upgrades Access Analyzer, when you need to run it, and how to check that an upgrade finished. +sidebar_position: 4 +--- + +You upgrade Access Analyzer with `dspmctl` on the install host. `dspmctl` is a small shell wrapper the installer drops at `/usr/local/bin/dspmctl`. It runs `kubectl exec` into the `dspmctl` pod in the `argocd` namespace, which signs in to ArgoCD and runs `argocd` commands for you. You don't need the `argocd` command-line interface (CLI) on the host. + +Run it with `sudo`. The default kubeconfig at `/etc/rancher/k3s/k3s.yaml` is readable only by root, so without `sudo`, kubectl falls back to `localhost:8080` and fails with "connection refused." + +## Check Whether You Need to Act + +Check how you installed the app. The installer's default `--target-revision` is `1.*`, a wildcard. If nobody pinned a specific version at install time, ArgoCD already tracks the newest stable 1.x tag and picks up new releases on its next sync. You don't need any `dspmctl` steps. + +If you pinned a specific version at install time, or want to pin one now, follow these steps. + +## Steps + +1. Point the umbrella app at the new version. + + ```bash + sudo dspmctl set-revision netwrix 1.1.2 + ``` + + For the `netwrix` app, this does three things: turns off automated sync and self-heal, sets `targetRevision` to `1.1.2`, and sets the Helm parameter `config.spec.source.targetRevision=1.1.2` so every child application (webapp, core-api, and so on) gets the same version. + +2. Trigger the sync. `set-revision` disables auto-sync, so nothing deploys until you run this command. + + ```bash + sudo dspmctl sync netwrix + ``` + +3. Turn auto-sync back on so later releases in the pinned range deploy without manual steps. + + ```bash + sudo dspmctl enable-auto netwrix + ``` + + `enable-auto` only changes the sync policy. It doesn't force a reconcile, and the ArgoCD controller polls roughly every 3 minutes. If you ran only `enable-auto` and nothing changed yet, run `sync`. + +## Checking the Result + +```bash +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: + +```bash +sudo dspmctl sync netwrix.webapp +``` From 1ebd37587a7ac8f31a5e5fd851fd6e410de81ae4 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 20:24:31 +0000 Subject: [PATCH 2/4] fix(vale): auto-fix style issues (Vale + Dale) --- docs/accessanalyzer/26.1/install/index.md | 4 ++-- docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/accessanalyzer/26.1/install/index.md b/docs/accessanalyzer/26.1/install/index.md index 54f216def5..b45f667958 100644 --- a/docs/accessanalyzer/26.1/install/index.md +++ b/docs/accessanalyzer/26.1/install/index.md @@ -5,13 +5,13 @@ description: How to prepare a Linux server, run the Access Analyzer installer, a Access Analyzer runs on a single Linux server that you own. You download one installer binary, run it as root, and answer a few prompts. The installer checks the server, sets up every service, and prints the address and credentials you use to sign in. -An installation takes three steps, each covered on its own page. +An installation takes three steps, each on its own page. 1. [Requirements](requirements.md)—pick a size, confirm the server has enough CPU, RAM, and disk, and gather the license key, hostname, TLS certificate, and first administrator's email address before you start. 2. [Install Access Analyzer](run-the-installer.md)—copy the certificate to the server and run `dspm-installer`, either answering the prompts or passing everything as flags. 3. [Sign in for the first time](first-sign-in.md)—open the web application, change the first administrator's one-time password, and either connect Active Directory or Entra ID or skip that step for later. -After the first sign-in, the [Guides](../guides/index.md) walk you through scanning your first source. +After the first sign-in, the [Guides](../guides/index.md) show you how to scan your first source. After you're running, see [Upgrade to a new version](upgrade-to-a-new-version.md) for how new releases roll out and when you need to act. diff --git a/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md b/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md index 33ccbcb909..c9aa781689 100644 --- a/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md +++ b/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md @@ -4,7 +4,7 @@ description: How dspmctl upgrades Access Analyzer, when you need to run it, and sidebar_position: 4 --- -You upgrade Access Analyzer with `dspmctl` on the install host. `dspmctl` is a small shell wrapper the installer drops at `/usr/local/bin/dspmctl`. It runs `kubectl exec` into the `dspmctl` pod in the `argocd` namespace, which signs in to ArgoCD and runs `argocd` commands for you. You don't need the `argocd` command-line interface (CLI) on the host. +You upgrade Access Analyzer with `dspmctl` on the install host. `dspmctl` is a small shell wrapper the installer drops at `/usr/local/bin/dspmctl`. It runs `kubectl exec` into the `dspmctl` pod in the `argocd` namespace, and 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 it with `sudo`. The default kubeconfig at `/etc/rancher/k3s/k3s.yaml` is readable only by root, so without `sudo`, kubectl falls back to `localhost:8080` and fails with "connection refused." From 0080b6141706b647fc011ba78a460ce96d4b3daf Mon Sep 17 00:00:00 2001 From: thobed <10742470+thobed@users.noreply.github.com> Date: Tue, 8 Sep 2026 16:24:39 -0400 Subject: [PATCH 3/4] Add collapsed troubleshooting section for dspmctl hang after a cancelled command Matches the ArgoCD note pattern from the install page: collapsed by default so it doesn't clutter the main upgrade flow, covering the wedged-pod restart fix and a kubectl-only fallback when dspmctl itself is unusable. Generated with AI Co-Authored-By: Claude Code --- .../26.1/install/upgrade-to-a-new-version.md | 44 +++++++++++++++++++ 1 file changed, 44 insertions(+) diff --git a/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md b/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md index c9aa781689..69a9d88a49 100644 --- a/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md +++ b/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md @@ -49,3 +49,47 @@ Check `TARGET REVISION` and `Sync Status`. The `netwrix` app only manages the ch ```bash sudo dspmctl sync netwrix.webapp ``` + +
+Troubleshooting: dspmctl hangs after a cancelled command + +If you press Ctrl-C during a `dspmctl` command part-way through (for example, after typing the wrong version), every later `dspmctl` call can hang at `Logging in to ArgoCD ...` and never return. This isn't an ArgoCD or network problem: `argocd version --client`, which needs no network at all, hangs too. Every `dspmctl` invocation runs inside the same long-lived `dspmctl` pod, and the interrupted run leaves the `argocd` binary in that pod in a wedged state. + +Restart that pod and re-run the upgrade: + +```bash +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: + +```bash +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`: + +```bash +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: + +```bash +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 +``` + +
From 9839964be5a8f8b217de7d09495f499fa3349829 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <41898282+claude[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 20:28:19 +0000 Subject: [PATCH 4/4] fix(vale): auto-fix style issues (Vale + Dale) --- docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md b/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md index 69a9d88a49..d0e105d409 100644 --- a/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md +++ b/docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md @@ -53,7 +53,7 @@ sudo dspmctl sync netwrix.webapp
Troubleshooting: dspmctl hangs after a cancelled command -If you press Ctrl-C during a `dspmctl` command part-way through (for example, after typing the wrong version), every later `dspmctl` call can hang at `Logging in to ArgoCD ...` and never return. This isn't an ArgoCD or network problem: `argocd version --client`, which needs no network at all, hangs too. Every `dspmctl` invocation runs inside the same long-lived `dspmctl` pod, and the interrupted run leaves the `argocd` binary in that pod in a wedged state. +If you press Ctrl-C during a `dspmctl` command part-way through (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: