Skip to content

Upgrade With IVAAP Binary

This guide is for operators who run IVAAP on a single-node k3s host that was deployed with a completed ivaap install, and who want to upgrade in place by running ivaap install --upgrade from a newer IVAAP Binary package. The installer supports same-major and N-1 major jumps (for example 2026.x → 2027.x).

Installer-managed hosts only

ivaap install --upgrade works only when a prior ivaap install completed successfully on this host (installer state under /opt/ivaap/.installer/, Helm release ivaap in namespace ivaap, source version 2026.1 or newer).

If the host was deployed with 2025.x deploy-ivaap.sh or manual Helm without a completed v2 install, do not use this guide — use Upgrade from IVAAP 2025.x instead. The installer blocks --upgrade on those hosts.

Audience and scope

In scope Out of scope
Single-node k3s hosts with a completed ivaap install (2026.1 minimum) Fresh install (ivaap install on an empty host)
Upgrade via ivaap install --upgrade from a newer IVAAP Binary Legacy 2025.x deployments (manual path)
Preserving PostgreSQL data, PVC/hostPath bindings, and operator ivaap.values.yaml Multi-node AKS/EKS/OpenShift (BYO-cluster workflows)
Same-host in-place chart/image refresh + Helm rollout Blue-green or zero-downtime upgrades

To replace the deployment entirely, use ivaap uninstall followed by ivaap install. That destroys existing data unless restored from external backups.

Prerequisites

Confirm all of the following before running --upgrade:

  • Prior ivaap install finished successfully (ivaap status shows all install steps complete)
  • Installed IVAAP version is 2026.1 or newer (ivaap -v or state.json / chart Chart.yaml)
  • New delivery zip downloaded; new IVAAP Binary extracted on the host
  • Maintenance window — brief downtime during Helm rollout and health checks
  • Disk headroom per Technical Data Sheet (especially /var/lib/rancher for image import)
  • Helm Chart Release Notes reviewed for breaking values or database schema migration requirements
  • FlexNet license server reachable with entitlements for the target release (./ivaap license-check from the new package directory)

Run the new package binary

Invoke upgrade from the new extracted package (or after ivaap activate), not an older copy on PATH:

cd /path/to/new-package
./ivaap -v
./ivaap install --upgrade

The command computes payload integrity hashes first (typically 1–2 minutes of silence on large packages).

Refresh payload files when images change

The upgrade path replaces IVAAPHelmTemplate from the embedded payload and re-imports images from /opt/ivaap/docker-images.tar.gz and entitled connector tarballs under /opt/ivaap/connectors/. It does not automatically overwrite those tarballs from the new binary.

When Helm Chart Release Notes or ivaap manifest --summary indicate new core or connector images, refresh on-disk artifacts before --upgrade:

cd /path/to/new-package
./ivaap extract-file docker-images.tar.gz /opt/ivaap/docker-images.tar.gz
# Repeat for each entitled connector tarball under /opt/ivaap/connectors/ as needed

Or extract the full payload to a staging directory and copy the required files into /opt/ivaap/ (see Upgrade from IVAAP 2025.x — Phase 1 for the staging pattern).

Version policy

The installer enforces an N-1 major upgrade policy:

Path Supported
Same major, any minor/patch (for example 2026.1 → 2026.2) Yes
N-1 major (for example 2026.x → 2027.x) Yes
Downgrade (for example 2027.x → 2026.x) Blocked
Skip more than one major (for example 2026.x → 2028.x) Blocked unless --accept-unsupported-upgrade

If the deployed version and payload already match the new binary, --upgrade exits with a no-op error. Use --reapply only when you intentionally need to re-run the upgrade DAG (see Flags).

Procedure

cd /path/to/new-package

# Optional — confirm entitlements and bundled version
./ivaap license-check
./ivaap -v

# Optional — refresh docker-images.tar.gz / connector tarballs (see above)

# Run the upgrade
./ivaap install --upgrade

On success, the installer prints the upgraded version and may offer to register the new package on PATH (ivaap activate).

Verify afterward:

ivaap status
ivaap -v
kubectl get pods -n ivaap

What install --upgrade does

The installer runs a dedicated upgrade DAG (separate from the fresh-install steps). Order:

Step ID Action
upgrade_preflight CPU/RAM/disk checks (stricter on /var/lib/rancher than fresh install) + cluster/Helm sanity
upgrade_detect Record from/to versions in installer state
upgrade_pg_backup pg_dump of ivaapdb to /opt/ivaap/.installer/backups/<timestamp>/ivaapdb.sql (unless --skip-backup)
upgrade_snapshot Copy state.json, ivaap.values.yaml, Helm values/history into backup dir
upgrade_chart_swap Backup prior chart tree; extract new IVAAPHelmTemplate from embedded payload
upgrade_load_images k3s ctr images import from /opt/ivaap/docker-images.tar.gz + entitled connectors
upgrade_migrate Chart migration hook step (values patches when defined; default no-op)
upgrade_helm helm upgrade --install with --rollback-on-failure and --wait (20m timeout)
upgrade_health_backend Backend ingress health probe
upgrade_health_admin Adminserver ingress health probe

The upgrade path does not re-run fresh-install prompts (license, FQDN, PVC selection). It preserves /opt/ivaap/ivaap.values.yaml and existing PVC bindings. It never invokes ivaap uninstall.

Backups are written under /opt/ivaap/.installer/backups/. Paths to the latest pg_dump and snapshot are recorded in installer state (ivaap status / state.json derived keys).

Database schema migrations

Schema changes run when adminserver starts with IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'true' in /opt/ivaap/ivaap.values.yaml. install --upgrade does not edit that file — Helm deploys whatever value is already on disk.

A completed ivaap install typically leaves this flag true (set during initial values rendering). Many point-release upgrades therefore apply schema migrations during the upgrade Helm step — that is normal when release notes do not call for a staged cutover.

When Helm Chart Release Notes describe one-way or high-risk migrations, or you want a rollback-safe chart rollout first, use the two-phase pattern from Upgrade from IVAAP 2025.x:

  1. Set IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'false' in ivaap.values.yaml.
  2. Run ./ivaap install --upgrade — new chart/images deploy; database unchanged.
  3. Verify pods and ingress health.
  4. Set IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'true' and run a manual Helm upgrade, or install --upgrade --reapply after saving values (forces fresh pg_dump and full DAG). Since this is only an environment variable change, the adminserver pod will not be automatically recreated. Delete the pod after manual helm upgrade with ki ivaap delete pod -l app=adminserver.
  5. After migrations succeed, set the flag back to false and apply with Helm again.

Schema migrations are one-way

Once adminserver runs with IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'true', PostgreSQL schema moves forward for that release line.

helm rollback, --rollback-on-failure, and re-deploying an older chart do not undo schema changes. The pre-upgrade pg_dump from the upgrade DAG (or an ivaap_pgdump you took manually) is the recovery anchor.

Flags reference

Verified flags on ivaap install --upgrade (see also IVAAP Binary):

Flag Purpose
--upgrade Run the upgrade DAG instead of fresh install
--skip-backup Skip mandatory pg_dump before upgrade (dangerous)
--accept-unsupported-upgrade Allow upgrade paths beyond N-1 major version policy
--reapply Re-run the full upgrade DAG when version + payload unchanged; prompts for confirmation; forces fresh pg_dump and snapshot

Mutually exclusive with --upgrade: --resume, --rollback-to.

Not used by --upgrade: --accept-data-loss (applies to destructive install rollbacks only: postgres, namespace, secrets, helm_deploy).

Does not apply today: install --upgrade --dry-run runs the fresh-install dry-run plan, not the upgrade DAG — do not rely on it for upgrade planning.

--reapply

Use when the same package is already deployed but you need to force another pass (for example after hand-editing ivaap.values.yaml, refreshing images, or enabling schema migration). Requires interactive confirmation. Clears cached backup derived keys so pg_dump and snapshot steps run again.

Failure recovery

Situation Action
Upgrade step failed mid-DAG Fix underlying issue; re-run ./ivaap install --upgrade from the same new binary (completed backup steps may be skipped if recorded in state — use --reapply for a fresh pg_dump)
Helm failed before adminserver schema migration --rollback-on-failure may revert the Helm release; database usually unchanged if AUTO_MIGRATE was false
Schema migrated, need to return to older release Restore ivaapdb from upgrade pg_dump or pre-upgrade ivaap_pgdump — not Helm rollback alone
Wrong upgrade attempted Do not use ivaap uninstall unless destroying the deployment is acceptable

Collect support artifacts:

ivaap status
ivaap -v
# Attach /opt/ivaap/.installer/state.json

See Troubleshooting.