MAQPNADocs

Uninstall

Remove MAQPNA from a cluster or a laptop, keep the evidence first, and decide what to keep for a reinstall.

maqpna uninstall removes the Helm release and, by default, keeps everything a reinstall needs: the CRDs and all custom resources, the tokens and identity key Secrets, and the agent namespaces. --purge deletes those too.

flowchart LR
  A[maqpna audit fetch ledger<br/>maqpna backup create] --> B[maqpna uninstall --dry-run]
  B --> C{Reinstall later?}
  C -->|yes| D[maqpna uninstall]
  C -->|no| E[maqpna uninstall --purge]
  D & E --> F[Remove agent-sandbox,<br/>RuntimeClasses, SCC grants]

Goal#

MAQPNA removed, with the audit ledger exported and kept as evidence.

Prerequisites#

  • Cluster-admin rights.
  • Admin or auditor access to the gateway, to export the ledger first.

Steps#

1. Keep the evidence#

The audit ledger is evidence that outlives the installation. Export it, with its signed checkpoints and the public keys that verify them, before you remove anything:

maqpna audit fetch ledger --gateway "$GW" --out ledger-final.jsonl
maqpna audit verify ledger-final.jsonl --jwks ledger-final.jsonl.jwks.json   # .jwks.json exists with signed checkpoints
maqpna backup create --out /backups/final --gateway "$GW" --seal-to recipient.pub

2. See what will be deleted#

maqpna uninstall --dry-run

3. Uninstall#

maqpna uninstall                 # asks for confirmation on a terminal
maqpna uninstall --purge --yes   # in a script: no prompt, everything deleted
maqpna uninstall maqpna uninstall --purge
Helm release (Deployments, Services, ConfigMaps, NetworkPolicies, RBAC) deleted deleted
maqpna.com CRDs and every Agent, AgentSession, ToolPolicy, … kept deleted
Tokens Secret and identity signing key (helm.sh/resource-policy: keep) kept deleted
Agent namespaces kept deleted

uninstall asks ...? [y/N] on a terminal. Without a terminal (scripts, CI) it never prompts: without --yes it exits 2 and prints the same command with --yes. --wait waits until the release's resources are deleted. Use --release and -n if you installed with other names.

4. Remove what the chart did not install#

  • The agent-sandbox controller: kubectl delete -f https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v1.0.4/sandbox-with-extensions.yaml
  • RuntimeClasses created by your platform (AKS, GKE) and node pools.
  • OpenShift SCC grants: oc adm policy remove-scc-from-user nonroot-v2 -z <service-account> -n maqpna-system.
  • Your own Secrets (PostgreSQL DSN, WORM credentials, licence) and the PostgreSQL schema, once you no longer need them.

Without the CLI (plain Helm)#

helm uninstall maqpna -n maqpna-system
# Only to purge:
kubectl get crd -o name | grep '\.maqpna\.com$' | xargs kubectl delete
kubectl -n maqpna-system delete secret maqpna-tokens maqpna-identity-key --ignore-not-found
kubectl delete namespace maqpna-agents --ignore-not-found

Stop a local MAQPNA#

On a laptop, maqpna dev down stops the identity broker, the gateway and the test servers, and keeps the state directory:

$ maqpna dev down
local MAQPNA stopped (state and ledger kept in /home/you/project/.maqpna)

Delete .maqpna/ when you no longer need the keys and the ledger.

Verification#

helm list -n maqpna-system
kubectl get crd | grep maqpna.com        # empty after --purge
kubectl get ns maqpna-agents             # NotFound after --purge

Troubleshooting#

Symptom Cause Fix
uninstall exits 2 in CI No terminal and no --yes Add --yes.
release maqpna in maqpna-system: Kubernetes cluster unreachable: Cannot reach http://localhost:8080: connection refused No kubeconfig is set, so the Helm client falls back to localhost:8080 Set KUBECONFIG, or pass --kube-context. The printed hint suggests curl …/healthz for a gateway; ignore it here, the address is the Kubernetes API.
Namespace stuck in Terminating after --purge Sessions carry a finalizer that the operator removes; with the operator gone, nothing removes it Delete the sessions (kubectl delete agentsessions --all -A) while the operator still runs, then purge.

Next steps#