Upgrade and rollback

Upgrade MAQPNA one minor version at a time with upgrade check and a dry-run diff, and roll back safely when CRDs and schemas stay newer.

maqpna upgrade applies the new chart's CRDs first, then upgrades the Helm release with your deployed values. maqpna upgrade check tells you beforehand whether it is safe, and maqpna rollback returns to an earlier revision without orphaning objects stored in a newer CRD version.

flowchart LR
  A[maqpna version --check] --> B[maqpna upgrade check --to V]
  B -->|exit 0| C[maqpna upgrade --to V --dry-run]
  B -->|exit 3| X[Fix the blocking item]
  C --> D[maqpna upgrade --to V --wait --atomic]
  D --> E[maqpna doctor<br/>helm test]
  D -->|failed| F[maqpna rollback --wait]

Goal#

Move an installation to the next minor or patch release without downtime, with a plan you can read before anything changes, and a known way back.

Prerequisites#

• An installation made with maqpna install or Helm (release maqpna in maqpna-system by default).
• The maqpna CLI and its maqpna-install plugin from the target release. Lifecycle commands run the plugin; use the plugin from the same release as maqpna.
• Cluster-admin rights (the upgrade applies CRDs).
• A recent backup: maqpna backup create (Backup, restore and DR).

What is different about upgrading MAQPNA#

• Helm never upgrades CRDs. It installs crds/ on the first install only. maqpna upgrade server-side-applies the chart's CRDs (field manager maqpna) and waits until they are Established before it runs the Helm upgrade.
• CRDs never roll back. One CRD serves every revision. maqpna rollback keeps the newer CRDs and refuses to roll back when an installed CRD stores a version that the target revision does not define.
• PostgreSQL schema migrations do not roll back. With state.backend=postgres, the gateway migrates the schema at start under an advisory lock. The migrations are additive, so an older gateway keeps working on a newer schema. Test the rollback in staging first.
• One minor version at a time. Upgrade 0.2 to 0.3 to 0.4, not 0.2 to 0.4. upgrade check blocks skipped minors and downgrades.
• Deployed values are reused under the new chart's defaults (helm --reset-then-reuse-values). -f, --set and --profile apply on top; --reset-values starts from the chart defaults instead.

Version skew#

Check it before and after every upgrade:

maqpna version --check

It reads GET /version from every component and the operator's Deployment, and exits 3 on unsupported skew. Development builds (dev) are reported but not compared. Real output against a local MAQPNA:

$ maqpna version --gateway "$MAQPNA_GATEWAY_URL" --identity "$MAQPNA_BROKER_URL" --no-kube --check
COMPONENT  VERSION  COMMIT        STATUS          SOURCE
client     dev      82eb1393fd33  ok              local
gateway    dev      82eb1393fd33  ok              http://127.0.0.1:58080/version
identity   dev      82eb1393fd33  ok              http://127.0.0.1:58081/version
attest     -        -             not-configured  -
operator   -        -             not-configured  -

WARNING gateway: version "dev" is a development build; skew not checked
WARNING identity: version "dev" is a development build; skew not checked

version skew: OK

Steps#

1. Install the new CLI and plugin#

curl -fsSL https://maqpna.com/install.sh | sh -s -- --version v0.2.0
maqpna version            # the CLI
maqpna-install version    # the plugin: must print the same version

2. Check whether the upgrade is safe#

V=0.2.0
maqpna upgrade check --to "$V"

It exits 3 when a blocking item is found. -o json gives the same report for CI.

3. Read the plan#

maqpna upgrade --to "$V" --dry-run

The dry run renders the upgrade on the API server and prints the CRD diff and a per-resource manifest diff. Secret values are redacted. Nothing changes.

4. Upgrade#

maqpna upgrade --to "$V" --wait --atomic

--atomic rolls the release back when the upgrade fails (it implies --wait). --timeout (default 10m) bounds the CRD wait and the rollout. For a mirrored or local chart, pass --chart oci://registry.internal/maqpna/charts/maqpna or --chart ./maqpna-0.2.0/maqpna.

5. Verify#

maqpna version --check
maqpna doctor
helm test maqpna -n maqpna-system

Upgrade with plain Helm (GitOps)#

Apply the CRDs first, then upgrade the chart (REGISTRY is the release registry listed on maqpna.com/download):

V=0.2.0
helm pull "oci://$REGISTRY/charts/maqpna" --version "$V" --untar
kubectl apply --server-side --force-conflicts --field-manager=maqpna -f maqpna/crds/
kubectl wait --for=condition=Established -f maqpna/crds/ --timeout=2m
helm upgrade maqpna ./maqpna -n maqpna-system --reset-then-reuse-values --wait --atomic
helm test maqpna -n maqpna-system

In Argo CD, use ServerSideApply=true and not Replace=true. In Flux, set install.crds: CreateReplace and upgrade.crds: CreateReplace. Run maqpna upgrade check --chart ./maqpna against the cluster before you merge the version bump.

Roll back#

maqpna status                      # current revision and history
maqpna rollback --dry-run          # previous revision; prints which CRDs stay at the newer schema
maqpna rollback 4 --wait           # a specific revision
maqpna doctor

REVISION defaults to the previous one. The rollback is refused when an installed CRD stores a version that the target revision does not define, because the old operator could not read those objects. --force overrides it; use it only after you have migrated those objects back.

Troubleshooting#

When an upgrade fails:

1. maqpna status: release status (failed, pending-upgrade) and unready workloads.
2. maqpna doctor -o json: /readyz problems, CRD drift and posture checks.
3. maqpna support-bundle: a redacted archive with versions, the doctor report, release history, objects, events and logs.
4. maqpna rollback --wait (with --atomic, the upgrade has already rolled back).

Next steps#

• Backup, restore and DR: run maqpna dr drill after each upgrade.
• Air-gapped install: upgrade from a new bundle.
• Command reference: maqpna upgrade, maqpna upgrade check, maqpna rollback, maqpna version.