Skip to content

Upgrading QIE HA Node Instances

In this article a node instance is a running QIE engine in a high availability cluster. The term does not refer to the mapping, condition, or destination nodes that make up a channel.

Upgrading a QIE cluster running in containers means moving every node instance from one QIE image version to another. Because QIE runs schema migrations on startup, all node instances must run the same version at any given moment. An instance on the old version and an instance on the new version cannot share the same database mid-upgrade.

Upgrade procedure

  1. Snapshot the database. Take a full backup of the QIE back-end database (MySQL / MariaDB / MSSQL) before proceeding. The upgrade may run schema migrations that are not automatically reversible; a snapshot is the rollback path.
  2. Stop all QIE containers. Every node instance must be down before any new-version instance starts. Kubernetes handles this automatically when the deployment strategy is Recreate (see below).
  3. Update the image tag. Change qvera/qie:{version} in the deployment manifest or compose file to the new version.
  4. Start the cluster. Bring the containers back up. The first instance to start applies any Hibernate schema updates; the remaining instances join the already-updated schema one at a time.
  5. Verify. Confirm every instance's qieLauncher.log shows a clean startup and the login page reports the new build.

Kubernetes: use the Recreate strategy, not RollingUpdate

Set the deployment strategy to Recreate on any QIE Deployment:

spec:
  strategy:
    type: Recreate

RollingUpdate (Kubernetes' default) replaces pods one at a time, which leaves old-version and new-version node instances running against the same database simultaneously during the rollout. QIE's schema migration on startup does not tolerate that. The first new-version instance takes the schema-update mutex and applies its changes, every other instance is blocked from starting until it finishes, and any old-version instance still running is left working against a schema it was not built for.

Recreate stops every existing pod before starting any new pod, giving QIE exactly one version at a time on the shared database. The trade-off is a brief outage during the swap; plan the upgrade in a maintenance window.

The example Kubernetes YAML uses strategy: Recreate for this reason.

Rolling back

If the new version fails to start or smoke tests reveal a regression:

  1. Stop all QIE containers.
  2. Restore the pre-upgrade database snapshot.
  3. Update the image tag back to the previous qvera/qie:{version}.
  4. Start the cluster.

Restoring the DB snapshot rewinds any schema migrations the new version applied. Without the snapshot, the older image may fail to start against the migrated schema. See Rolling Back a QIE Upgrade for the equivalent procedure on non-container installs.