Add upgrade guide for Access Analyzer install

docs/accessanalyzer/26.1/install/index.md

@@ -5,13 +5,15 @@ 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.
 
 ## People You Need
 

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 <br> (/var/lib) | Designed for |
+| Size | CPU cores | RAM | Disk <br/> (/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. |

docs/accessanalyzer/26.1/install/upgrade-to-a-new-version.md

@@ -0,0 +1,95 @@
+---
+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, 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."
+
+## 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
+```
+
+<details>
+<summary>Troubleshooting: dspmctl hangs after a cancelled command</summary>
+
+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:
+
+```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
+```
+
+</details>