Skip to content

Upgrade From Legacy 2025

This guide is for operators who already run IVAAP 2025.x on a single-node k3s host (installed with deploy-ivaap.sh or an equivalent manual Helm workflow) and want to move to IVAAP 2026.x using the 2026 ivaap delivery package.

The 2026 installer does not run an automated in-place upgrade on these hosts. It blocks ivaap install, ivaap install --resume, and ivaap install --upgrade when it detects a live deployment that was not completed by a v2 ivaap install. That guard protects your cluster and data from being overwritten by mistake.

What the 2026 binary does provide on legacy hosts:

  • manifest — inspect the embedded payload without extracting it
  • extract-payload — copy the chart, images, and connectors to a staging directory
  • extract-file — pull individual named files from the payload
  • license-check — probe your FlexNet license server before you cut over

Everything else in this guide — backups, FlexNet license migration, values changes, image import, Helm upgrade, and verification — is operator-owned and must be planned in a maintenance window.

Manual operator-owned upgrade

The 2026 installer does not run ivaap install, ivaap install --resume, or ivaap install --upgrade on legacy 2025.x hosts. Those commands are blocked to prevent overwriting a live deployment.

If the host already completed a v2 ivaap install at 2026.1 or newer, use Upgrade with IVAAP Binary instead.

Audience and scope

In scope Out of scope
Single-node k3s deployments under /opt/ivaap Greenfield install (ivaap install on an empty host)
Source 2025.1.x (Helm chart 1.1.x–1.2.x) Hosts that already completed ivaap install at 2026.1+
Target 2026.1+ (calendar chart version 2026.1.0-x) Multi-node AKS/EKS/OpenShift (use platform deployment guides)
Preserving PostgreSQL data and PVC/hostPath content where possible Skipping a major line in one step (for example 2025 → 2027 without an intermediate release)

If you prefer a clean environment with no migration of settings, the supported alternative is ivaap uninstall followed by ivaap install. That destroys the existing deployment, namespaces, and /opt/ivaap content except what you backed up externally.

Choose your path

Existing 2025.x deployment on k3s
        |
        +-- Keep data / settings -->  This guide (manual upgrade)
        |
        +-- Accept data loss     -->  ivaap uninstall
        |                              ivaap install
        |
        +-- Stay on 2025.x         -->  No action; do not run ivaap install

What changed between 2025.x and 2026.1

Review the full Helm Chart Release Notes before merging values. The table below summarizes the breaking items most legacy k3s hosts hit.

Area 2025.x (typical) 2026.1+ Action
Helm chart version 1.1.x – 1.2.x 2026.1.0-x Replace IVAAPHelmTemplate from the 2026 payload
FlexNet licensing Embedded FEATURE-line in license secret port@host FlexNet reference Stand up FlexNet; migrate LM_LICENSE_FILE (see License migration)
WITSML realtime Optional in 2025.x Scheduled tasks in 2026.1+ Set ivaapBackendNodes.realtimeEnabled: true if licensed; import WITSML task images
dataimportnode Optional under dataNodes Always on under coreNodes Remove stale dataNodes.dataimportnode from your operator values file
Image tags Often pinned in operator values Defaults in chart values.yaml Remove tag: / ad-hoc repoName: overrides unless SLB support directed a hotfix
Database schema 2025.x adminserver schema 2026.x schema migrations Two-step: first Helm cutover with IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'false', then enable migration in Phase 6
PostgreSQL cluster Often Spilo 15 on legacy hosts Fresh installs target 17 Do not reload the 2026 postgres seed on upgrade — keep the existing Zalando cluster
Disk requirements 2025 sizing Higher 2026.1 floors VM must meet Technical Data Sheet storage tiers before upgrade

Prerequisites

Confirm all of the following before extracting the payload or importing images.

Host and cluster

  • Root or sudo on the k3s host
  • kubectl and helm working against the cluster (k3s context)
  • Helm release ivaap in namespace ivaap
  • The 2026 ivaap binary for the target release (same package you would use for a new install)
  • Maintenance window — plan for image import, Helm rollout, and brief downtime

Disk and VM sizing (2026.1 standards)

IVAAP 2026.1 raises single-host storage expectations. Your VM must meet the current Technical Data Sheet — Single Host Deployment Guidelines before upgrade — do not rely on 2025-era sizing.

Path Minimum free space (low / medium usage) Why
/opt/ivaap ≥ 80 GB free Live tree, chart backup, and transient copies during cutover
/var/lib/rancher ≥ 60 GB free k3s containerd stores imported images; old and new layers coexist during upgrade
Staging filesystem (for example /var/tmp) ≥ 15 GB free beyond the ~12 GB payload Full extract-payload to a directory outside /opt/ivaap

Check free space:

df -h /opt/ivaap /var/lib/rancher /var/tmp

k3s image garbage collection under disk pressure

k3s uses the Kubernetes kubelet image garbage-collection thresholds (defaults: high 85%, low 80% disk usage on the image filesystem). When /var/lib/rancher fills, containerd may prune unused images while you are importing the 2026 package — which can leave pods unable to start after Helm rolls out.

Keep disk usage well below 80% on /var/lib/rancher before and during image import. If the host is tight, expand the VM disk or prune unused images only after you have verified backups and can re-import from the staged payload.

FlexNet license (required for 2026.1+)

  • An SLB FlexNet license server is running with 2026 IVAAP entitlements loaded
  • The server is reachable from the k3s host on the license port (default 27000)
  • You will migrate LM_LICENSE_FILE from a 2025 embedded FEATURE blob to a port@host reference before the Helm cutover

Verify from the directory containing the 2026 binary:

./ivaap license-check

Do not proceed if the probe fails or required features are missing.

Blocked installer commands

The 2026 binary refuses these on legacy hosts (by design):

ivaap install
ivaap install --resume
ivaap install --upgrade

If someone previously ran ivaap install and only /opt/ivaap/.installer/ exists with no successful deploy, remove that directory only:

sudo rm -rf /opt/ivaap/.installer

Do not run install --resume on a legacy host.

Phase 0 — Backup (required before any mutation)

Complete every step in this phase before extracting the payload, importing images, or replacing the chart.

0.1 PostgreSQL dump

Use the ivaap_pgdump helper (requires the adminserver pod to be Running and ivaap-helpers aliases loaded — see IVAAP Helpers — ivaap_pgdump):

ivaap_pgdump ivaap

The command writes a gzip-compressed dump to the current directory (for example ivaap-postgres-ivaap-2026-06-11_14-30-00.sql.gz) and validates it. Copy the file off-host.

This backup is mandatory before Phase 6: adminserver schema migrations are one-way. If migrations run and you must return to 2025.x, restore from this dump — Helm rollback will not revert the schema.

If ivaap_pgdump is unavailable, fall back to a direct pg_dump from the Spilo pod in namespace ivaap-postgres (see IVAAP Database Administration if installed).

0.2 Application configuration

BACKUP=~/ivaap-upgrade-backup-$(date +%Y%m%d)
mkdir -p "$BACKUP"

sudo cp -a /opt/ivaap/ivaap.values.yaml "$BACKUP/ivaap.values.yaml"
helm get values ivaap -n ivaap -o yaml > "$BACKUP/helm-values-ivaap.yaml"
sudo cp -a /opt/ivaap/IVAAPHelmTemplate "$BACKUP/IVAAPHelmTemplate"

Work from copies in "$BACKUP" when merging values in Phase 2.

0.3 Persistent and hostPath data

Back up directories your entitled datanodes use under /opt/ivaap/ivaap-volumes/ (for example geofiles, prosource, and any other licensed connector paths):

sudo tar -C /opt/ivaap -czf "$BACKUP/ivaap-volumes.tgz" ivaap-volumes/

0.4 Cluster state (optional but useful)

helm get manifest ivaap -n ivaap > "$BACKUP/ivaap-manifest.yaml"
kubectl get all,pvc,secret,ingress -n ivaap -o yaml > "$BACKUP/ivaap-ns.yaml"

Take a VM or volume snapshot at your hypervisor or cloud provider as a last-resort rollback anchor. Logical backups above remain the primary recovery path for PostgreSQL and configuration.

Do not regenerate Circle-of-Trust or database encryption secrets

Do not regenerate CoT keys or DB encryption material during upgrade unless you intend a full data reset. New keys make existing encrypted database content unreadable.

Phase 1 — Stage the 2026 payload

Use a staging directory outside the live tree. Do not run extract-payload --force directly on /opt/ivaap while the release is running unless you have tested restore from backup.

export STAGE=/var/tmp/ivaap-2026-payload
mkdir -p "$STAGE"
cd /path/to/extracted-2026-package

1.1 Inspect the embedded package

./ivaap manifest --summary

The first run computes a SHA-256 over the full embedded payload (typically 1–2 minutes on an ~11 GB package). Progress lines print to stderr; wait until the summary appears.

Confirm the Required components section lists IVAAPHelmTemplate/, ivaap-helpers/, and docker-images.tar.gz as PRESENT.

Confirm the target release:

./ivaap -v

1.2 Extract the full payload

./ivaap extract-payload --dest "$STAGE" --force

Verify the chart version after extract:

grep -E '^version:' "$STAGE/IVAAPHelmTemplate/Chart.yaml"

Phase 2 — Merge operator values

Work from your backup copy of /opt/ivaap/ivaap.values.yaml. Keep the live file until you are ready for the Helm cutover in Phase 5.

Open these references side by side:

  1. 2026 defaults: $STAGE/IVAAPHelmTemplate/values.yaml
  2. Your 2025 operator file: backup copy of ivaap.values.yaml

Produce a merged file that preserves your deployment choices (FQDN, enabled datanodes, PVC types/paths, TLS, authentication) while adopting 2026 structure and removing keys the 2026 chart no longer understands.

2.1 Required removals

Apply at minimum (full detail in Helm Chart Release Notes):

Remove stale dataimportnode under dataNodes:

# DELETE — dataimportnode is a core node in 2026; image is in docker-images.tar.gz
# ivaapBackendNodes:
#   dataNodes:
#     dataimportnode:
#       enabled: true

2.2 Remove image tag overrides

Remove tag: and ad-hoc repoName: overrides for core and datanode images in your operator values file unless SLB support explicitly directed a hotfix pin. The 2026 chart values.yaml (first -f file at Helm time) carries the correct image tags for the package you extracted.

Your operator file should keep site configuration — FQDN, enabled datanodes, PVC bindings, FlexNet reference, TLS, authentication — not image pins left over from 2025.

2.3 WITSML realtime (if licensed)

If your license includes IVAAPConnectorWITSML and you use realtime:

ivaapBackendNodes:
  realtimeEnabled: true

You will import WITSML scheduled-task tarballs separately in Phase 3 (in addition to the witsmlnode connector tarball).

Database schema migrations (two-phase approach)

IVAAP 2026.x adminserver applies required schema migrations to the existing ivaapdb database when IVAAP_SERVER_ADMIN_AUTO_MIGRATE is enabled. A 2025.x database is not fully compatible with 2026.x application code until those migrations run.

Recommended workflow — two Helm upgrades:

Step IVAAP_SERVER_ADMIN_AUTO_MIGRATE Purpose
Phase 5 — first cutover false (explicit) Roll out 2026 chart/images/values; confirm Helm and pods succeed without mutating the database
Phase 6 — migration cutover true Run required 2025 → 2026 schema migrations

For Phase 5, keep migration off in your merged operator values (or omit the key — the 2026 chart default is off):

configmap:
  adminserver:
    IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'false'

If your 2025 operator file already sets this to false, leave it unchanged for the first cutover. Do not enable migration until Phase 5 verification passes.

See Backend Environment Variable configuration — Adminserver and IVAAP Configuration — Database Migration.

Why two phases?

Separating chart rollout from schema migration preserves a safe rollback window. If the first Helm upgrade fails or the 2026 stack does not come up cleanly, --rollback-on-failure or a return to the 2025 chart/images leaves the existing database unchanged and compatible with 2025.x.

Schema migration is the point of no return — schedule Phase 6 only after Phase 5 looks good.

Schema migrations are one-way (Phase 6 onward)

Once the 2026 adminserver runs with IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'true', PostgreSQL schema is migrated forward for 2026.x.

Helm rollback, --rollback-on-failure, or redeploying 2025.x chart and images does not undo schema changes. A rolled-back 2025.x stack will not run correctly against a migrated database.

Before Phase 6: validated Phase 0 ivaap_pgdump off-host. After migrations run, restore ivaapdb from that dump before returning to 2025.x — do not rely on Helm rollback alone.

License migration (FlexNet)

IVAAP 2026.1+ requires runtime checkout from a FlexNet license server. The LM_LICENSE_FILE value is no longer an embedded FEATURE-line — it must be a port@host reference (for example 27000@flexnet.example.com).

Before cutover:

  1. Stand up or upgrade your FlexNet server with 2026 entitlements.
  2. Confirm connectivity and features with ./ivaap license-check from the 2026 package directory.
  3. Update your operator values under secrets.k8sSecrets.ivaap-license-secret:
secrets:
  k8sSecrets:
    ivaap-license-secret:
      LM_LICENSE_FILE: '27000@your-flex-server.example.com'

If your deployment uses secrets.base64EncodedValues: true, base64-encode the FlexNet reference (see General Helm Configuration — Secrets):

echo -n '27000@your-flex-server.example.com' | base64 -w 0 && echo

Put the encoded string in LM_LICENSE_FILE in values, or update the live Kubernetes secret if you manage secrets outside Helm values.

Loopback FlexNet on the same host

Do not write 127.0.0.1, localhost, or ::1 directly into LM_LICENSE_FILE. Pods cannot reach the host loopback interface. SLB recommends a separate FlexNet host. When same-host licensing is unavoidable, use the pod-facing hostname pattern documented in Helm Chart Release Notes (for example ivaap-flexnet.local with a matching host alias).

Keep existing secrets.envSecretRefs names for Circle of Trust, ActiveMQ, and database secrets unless you are deliberately rebuilding secrets.

Save the merged file (for example "$BACKUP/ivaap.values.yaml.merged") but do not copy it to /opt/ivaap until Phase 5.

Phase 3 — Load container images into k3s

Import from the staging directory before the Helm cutover. Paths assume $STAGE from Phase 1.

sudo k3s ctr images import "$STAGE/docker-images.tar.gz"

For each entitled connector (match your license and merged values):

sudo k3s ctr images import "$STAGE/connectors/<datanode>"-*.tar.gz

When WITSML realtime is enabled, import the task tarballs as well:

sudo k3s ctr images import "$STAGE/connectors/witsml"*task*.tar.gz

Confirm images exist:

sudo k3s ctr images ls | grep ivaap

Re-check disk usage on /var/lib/rancher after import:

df -h /var/lib/rancher

Phase 4 — Replace the Helm chart

IVAAPHelmTemplate is a drop-in replacement — do not edit files inside the chart tree. Site-specific configuration belongs in /opt/ivaap/ivaap.values.yaml only.

sudo mv /opt/ivaap/IVAAPHelmTemplate /opt/ivaap/IVAAPHelmTemplate.2025.bak
sudo cp -a "$STAGE/IVAAPHelmTemplate" /opt/ivaap/
sudo chown -R "$(id -u):$(id -g)" /opt/ivaap/IVAAPHelmTemplate

Verify:

grep -E '^version:' /opt/ivaap/IVAAPHelmTemplate/Chart.yaml

Phase 5 — First Helm cutover (without schema migration)

Install the merged operator values file. Confirm IVAAP_SERVER_ADMIN_AUTO_MIGRATE is false (see Phase 2) before copying:

sudo cp "$BACKUP/ivaap.values.yaml.merged" /opt/ivaap/ivaap.values.yaml
sudo chown "$(id -u):$(id -g)" /opt/ivaap/ivaap.values.yaml
grep AUTO_MIGRATE /opt/ivaap/ivaap.values.yaml || true   # expect false or absent

Run Helm with both values files (chart defaults + operator overlay):

helm upgrade --install ivaap /opt/ivaap/IVAAPHelmTemplate \
  -f /opt/ivaap/IVAAPHelmTemplate/values.yaml \
  -f /opt/ivaap/ivaap.values.yaml \
  --namespace ivaap \
  --rollback-on-failure \
  --wait --timeout 20m

--rollback-on-failure rolls the Helm release back if the upgrade fails or times out (this replaces the deprecated --atomic flag in current Helm 4). For this first cutover, rollback is database-safe — schema migrations have not run yet.

Verify before Phase 6

helm status ivaap -n ivaap
kubectl get pods -n ivaap
kubectl get pods -n ivaap-postgres

Pods should reach Running / Ready. Full 2026 application behavior (login, projects, connectors) may remain limited until schema migrations complete in Phase 6 — that is expected.

If this phase fails or the rollout is unhealthy, fix values/chart issues or roll back to 2025.x without database restore — the schema is still on the 2025.x baseline.

If you need to inspect a failed revision:

helm history ivaap -n ivaap
helm rollback ivaap <REVISION> -n ivaap

Phase 6 — Run schema migrations (second Helm upgrade)

Do not start this phase until Phase 5 is stable. This is the point of no return for the PostgreSQL application schema.

Keep the existing Zalando/Spilo cluster — this phase migrates ivaapdb in place, not a cluster reinstall.

6.1 Enable auto-migrate

Edit /opt/ivaap/ivaap.values.yaml:

configmap:
  adminserver:
    IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'true'

6.2 Apply migration cutover

helm upgrade --install ivaap /opt/ivaap/IVAAPHelmTemplate \
  -f /opt/ivaap/IVAAPHelmTemplate/values.yaml \
  -f /opt/ivaap/ivaap.values.yaml \
  --namespace ivaap \
  --rollback-on-failure \
  --wait --timeout 20m

When the adminserver pod (re)starts with migration enabled:

  1. Required 2025.x → 2026.x schema migrations run against ivaapdb.
  2. Inspect adminserver logs for migration success before declaring the upgrade complete.
kubectl logs -n ivaap -l app.kubernetes.io/component=adminserver --tail=200

Helm rollback does not revert database schema

--rollback-on-failure only rolls back the Helm release. If adminserver started and migrations ran before a later failure, recovery requires Phase 0 ivaap_pgdump restore — not Helm rollback alone.

One-way change — rollback implications

If this happened Safe to run 2025.x again? Recovery
Phase 5 failed; migration never enabled Yes Fix Helm/chart or restore 2025 chart/images/values
Phase 6 Helm failed before adminserver migrated Usually yes Retry Phase 6 or roll Helm back; confirm schema unchanged in adminserver logs
Adminserver started and migrations ran No Restore ivaapdb from Phase 0 ivaap_pgdump, then roll back chart/images/Helm to 2025.x
Migrations succeeded N/A (stay on 2026.x) Disable auto-migrate in Phase 7

Do not reload ivaap-postgres-*.sql from the 2026 package onto your existing cluster unless you are deliberately planning a major PostgreSQL version migration in a lab environment.

Phase 7 — Verification and disable auto-migrate

Cluster and release

helm status ivaap -n ivaap
kubectl get pods -n ivaap
kubectl get pods -n ivaap-postgres

All application pods should reach Running / Ready after Phase 6.

Health and UI

Use the FQDN configured in your values (and /etc/hosts if applicable):

  • Backend — ingress health URL (expect healthy JSON)
  • Adminserver — admin health URL

Sign in to the web UI and confirm entitled connectors (including WITSML if licensed).

WITSML realtime smoke test

If WITSML realtime is enabled:

kubectl get pods -n ivaap -l app.kubernetes.io/component=scheduledtask

Open a known project or datasource from the 2025 deployment to confirm data survived the upgrade.

Confirm adminserver logs show schema migrations completed in Phase 6.

Disable auto-migrate (third Helm upgrade)

Once verified, set auto-migrate back to false and re-run Helm. Leaving it enabled allows unintended migrations on future adminserver restarts.

configmap:
  adminserver:
    IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'false'

helm upgrade --install ivaap /opt/ivaap/IVAAPHelmTemplate \
  -f /opt/ivaap/IVAAPHelmTemplate/values.yaml \
  -f /opt/ivaap/ivaap.values.yaml \
  --namespace ivaap \
  --wait --timeout 20m

If PostgreSQL pods fail after any Helm upgrade, check logs in ivaap-postgres and confirm application pods still point at the same DB service name and secrets.

Rollback strategy

Layer Rollback approach
Helm release (Phase 5 only — migration not enabled) helm rollback or restore 2025 chart/images — database unchanged
Helm release (after Phase 6 migrations) helm rollback — workloads/config only; does not revert schema
Chart tree Restore IVAAPHelmTemplate.2025.bak to IVAAPHelmTemplate
Values Restore "$BACKUP/ivaap.values.yaml"
Images Previous images remain in containerd unless pruned; re-import 2025 tarballs if needed
Database (Phase 6 migrations ran) Required: restore ivaapdb from Phase 0 ivaap_pgdump before running 2025.x again
Database (Phase 5 only — migration never enabled) Restore from dump if needed; 2025.x still compatible with unmigrated schema
PVC data Restore from ivaap-volumes.tgz or hypervisor snapshot
Full host Hypervisor snapshot from Phase 0.5

Troubleshooting

Installer prints “Existing IVAAP deployment detected”

Expected on legacy hosts. Follow this guide; do not use ivaap install or ivaap install --upgrade.

manifest --summary appears hung

Wait for stderr progress lines. The installer hashes the full payload before listing components. Large packages routinely take 1–2 minutes.

license-check fails

Fix FlexNet reachability and entitlements before continuing. IVAAP 2026.1+ will not run correctly without runtime FlexNet checkout.

Helm upgrade fails on unknown values keys

Compare your merged file to /opt/ivaap/IVAAPHelmTemplate/values.yaml. Remove stale dataNodes.dataimportnode keys.

Datanode data empty after upgrade

Usually a hostPath / PVC name mismatch. Align datanodePVCs localPath / mountPath with directories on disk under /opt/ivaap/ivaap-volumes/.

WITSML realtime inactive

Confirm realtimeEnabled: true, WITSML is licensed, task images were imported, and scheduled-task pods are deployed.

Backend pods crash-loop after upgrade

Check image tags in the live Helm values match imported images (k3s ctr images ls). Confirm secrets still exist in namespace ivaap. Confirm LM_LICENSE_FILE uses port@host, not a 2025 FEATURE blob.

Rolled back to 2025.x but adminserver or UI fails

If the 2026 adminserver ran with IVAAP_SERVER_ADMIN_AUTO_MIGRATE: 'true' before rollback, the database schema may already be migrated. A 2025.x stack cannot use a forward-migrated ivaapdb. Restore from the Phase 0 ivaap_pgdump backup, then redeploy 2025.x.

Accidental ivaap install on a legacy host

Remove /opt/ivaap/.installer if created. Do not resume. Continue from Phase 0 if you need to verify backups.