IVAAP Binary Advanced Operations

IVAAP Deployment Operations Guide
ivaap Binary — Advanced Operations

IVAAP 2026.1

Introduction

This is a supplement to the IVAAP All-in-one Binary reference. It documents advanced flags, recovery patterns, and internal state for operators who need to go beyond the standard install / upgrade flow — primarily resuming a failed install, rolling back a destructive step, re-running an upgrade from scratch, or driving the binary from a script.

Every flag described here is also available through ivaap <subcommand> --help on the installed binary. The help output is the authoritative source for the build you have on disk; this page exists to put the flags in operational context.

Installer state

ivaap install records progress in /opt/ivaap/.installer/state.json. The file captures three things:

• Inputs — values gathered from interactive prompts (FQDN, license host and port, PVC storage choices, root password hash, and so on).
• Derived values — anything the installer computed from inputs (licensed datanodes, resolved PVC configs, per-datanode image overrides).
• Step status — for each step in the install DAG: pending, running, completed, or failed, plus the most recent log excerpt.

State writes are atomic (temp file, fsync, rename) so a host crash mid-step cannot leave the file corrupt. A flock on /opt/ivaap/.installer/state.lock prevents two ivaap install processes from racing. Secrets (Circle of Trust keys, ActiveMQ password, encrypted database password) live in the Kubernetes secret installer-state-secrets, not in state.json — the JSON only references the secret by name.

To inspect state without running the installer:

ivaap status                          # human-readable summary
cat /opt/ivaap/.installer/state.json  # raw file (read-only inspection)

Install recovery

When ivaap install fails partway through a deployment, you have three recovery levers. Pick the one that matches what went wrong:

--resume

ivaap install --resume

Continues from the first step that is not marked completed. Use this when the failure was transient — a network blip pulling an image, a flaky DNS lookup, an in-cluster timeout that resolved on its own. The installer reloads state.json, re-runs the failed step, and proceeds. Inputs from the original run are reused; no re-prompting.

--rollback-to=<step_id>

ivaap install --rollback-to=load_images
ivaap install --rollback-to=postgres --accept-data-loss

Rolls back every step after the named checkpoint, then resumes from that checkpoint. Use this when an earlier step produced wrong output and later steps inherited the mistake — for example, a license probe pointed at the wrong FlexNet server.

Steps marked destructive require --accept-data-loss:

Step	Why destructive
namespace	Deletes the IVAAP namespace, all helm release artifacts, secrets, pods, and PVCs in it.
postgres	Deletes the postgres namespace and Zalando cluster — all database data is lost.
secrets	Regenerates Circle of Trust keys and the database encryption key — existing ciphertext (database passwords, persisted secrets) is no longer readable.
helm_deploy	helm uninstall removes workloads, services, configmaps, and ingress. PVCs survive depending on the reclaim policy.

If you --rollback-to past any of these without --accept-data-loss, the installer refuses and exits non-zero.

--skip=<step_id>

ivaap install --resume --skip=preflight

Marks a step completed without running it. Use this only when you have already done the step's work by hand and the installer's check phase cannot detect that — for example, you pre-installed k3s with a custom flag set and want the installer to leave it alone. Skipping a step on a fresh install rarely ends well; almost every legitimate use is paired with --resume.

--dry-run

ivaap install --dry-run

Prints the planned step sequence (and which steps would be skipped or rolled back, if combined with other flags) without changing anything on the host. Useful for confirming a --rollback-to target before you commit.

Upgrades

ivaap install --upgrade performs an in-place upgrade of an existing IVAAP deployment to the version in the new binary. The standard flow is documented in Upgrade With the IVAAP Binary; the flags below cover edge cases.

Same-build guard

--upgrade refuses to run if the binary version matches what is already deployed. This prevents the common mistake of pointing the upgrade flow at the same package that produced the running deployment, which would re-take a fresh PostgreSQL backup and snapshot for no functional gain.

# Override only when you have a real reason — for example, re-applying after
# a manual fix to /opt/ivaap/ivaap.values.yaml on the same build.
ivaap install --upgrade --reapply

--reapply

Forces the upgrade flow to run even when the binary version matches the deployed version. As part of the override, --reapply clears the recorded upgrade_pg_backup and upgrade_snapshot_dir values in state.json, so the upgrade steps that own those artifacts will take a fresh backup and snapshot rather than reusing the previous run's. This matters when you re-apply after editing values — the backup taken before the last attempt is no longer the right pre-change baseline.

--skip-backup

Skips the pre-upgrade pg_dump. The backup exists specifically to give you a recovery point if the upgrade corrupts the database. There is no scenario where skipping is recommended in production. The flag exists for development hosts where the database is disposable.

--accept-unsupported-upgrade

--upgrade enforces an N-1 major version policy — it will only upgrade from the immediately preceding major version. --accept-unsupported-upgrade overrides the policy check. Use this only when IVAAP support has confirmed your specific source-to-target jump is supported by the deployed images; the check exists because the database migration path is only validated for adjacent versions.

Diagnostic and inspection flags

ivaap manifest --summary

ivaap manifest --summary

Stream-walks the embedded payload's top-level entries (helm chart, helpers, connectors directory, db seed, docs zip) and prints sizes and SHA-256 hashes — typically completes in a few seconds. Without --summary, manifest enumerates every file in every connector tarball, which can take much longer on the full 12 GB payload.

ivaap license-check --host <addr> --port <n>

ivaap license-check --host license.example.com --port 27000

Pre-fills the FlexNet host and port instead of prompting interactively. The default port is 27000. Useful in scripted environments and as a fast pre-flight before scheduling an install. The probe writes a throwaway state file under /tmp and never touches /opt/ivaap/.installer/.

ivaap nodes --refresh

ivaap nodes --refresh

Re-probes the FlexNet license server before listing datanodes. Without --refresh, ivaap nodes reports against the license feature list cached at install time. Use --refresh after the license file on the server has changed (a new feature was granted, an expired feature was renewed) to confirm IVAAP sees the change without running a full install.

ivaap docs start options

ivaap docs start                                   # default: detached, auto-port
ivaap docs start --port 8080                      # explicit port
ivaap docs start --port 0                         # auto-pick a free port
ivaap docs start --foreground                     # block this shell; Ctrl-C stops
ivaap docs start --idle-timeout 30m               # shut down if no requests for 30 minutes
ivaap docs start --docs-zip /path/to/IVAAP_Documentation_2026.1.zip

docs start searches for the documentation zip in this order: --docs-zip flag, the IVAAP_DOCS_ZIP environment variable, /opt/ivaap/IVAAP_Documentation_*.zip, and finally the path the docs would land at if you had already run ivaap extract-payload. The default --idle-timeout exists so a forgotten doc server eventually frees its port; pass 0 to disable.

ivaap tls update-cert vs ivaap tls renew

The two commands serve different purposes and are easy to confuse:

• ivaap tls update-cert replaces the certificate material in the existing TLS secret. Use it when you are bringing your own certificate and need to rotate it — for example, an annual renewal from your corporate CA. Inputs are the new cert, key, and (optionally) CA bundle.
• ivaap tls renew re-issues the self-signed server certificate against the existing self-signed CA. Only applies when TLS was set up with the self-signed option. The CA stays the same; only the server certificate is refreshed.

If you are using Let's Encrypt, neither command is needed — cert-manager handles renewal automatically based on the issued certificate's lifetime.

When to give up and start over

ivaap uninstall exists for the case where state.json no longer reflects reality — a host was rebuilt under you, someone ran helm uninstall by hand, or a manual edit to /opt/ivaap/.installer/state.json left it inconsistent. Uninstall removes the helm release, the IVAAP namespaces, and the /opt/ivaap tree, then a fresh ivaap install starts from a known-good state. Pass --keep-state to uninstall to preserve state.json for support (everything else is still removed).

ivaap uninstall            # interactive confirmation
ivaap uninstall -y         # skip confirmation
ivaap uninstall --keep-state