Institutional Vault upgrades replace the full deployment artifact set — infrastructure definitions, command-line tooling, and application containers. Do not upgrade by swapping container images alone.

Before you upgrade

Every upgrade must begin with these steps, regardless of infrastructure provider:

1. Review the release changelog. Check the Institutional Vault Release Notes for the target version. Pay close attention to the Breaking changes and migrations section — it lists API changes, field renames, and required configuration updates.

2. Take a database backup. Follow the System Backup and Restore Process to create a point-in-time backup before starting. This is your rollback safety net.

3. Verify current version health. Confirm all services are running and healthy before beginning the upgrade. All services expose /health endpoints that your orchestrator or scheduler should already be probing — confirm they report healthy before proceeding.

4. Confirm the target version. Ensure the release bundle version matches the version documented in the changelog. The ## Versions section of each release note lists the exact image tags for all components.

5. Plan a maintenance window. Upgrades are performed as rolling updates with minimal service impact. Notify stakeholders of the scheduled upgrade window and expected completion time.

Rollback strategy

If the upgrade fails or introduces a critical issue, the rollback approach depends on whether database schema migrations were applied during the upgrade.

Patch upgrades (no schema migrations)

For patch releases that only update application binaries without database changes, redeploy the previous version using your infrastructure tooling:

• Azure (Helm): helm rollback <release-name> <previous-revision> -n <namespace>
• AWS (CDK/CloudFormation): Redeploy the previous release bundle with make update using the prior Makefile and deployer artifacts.

Upgrades with schema migrations

Policy Nodes use a forward-only data generation model — once the database has been migrated to a newer schema version, the previous application binaries cannot operate against the updated database. In this case:

1. Redeploy the previous application version using your infrastructure tooling (Helm rollback, CDK redeploy, etc.).
2. Restore the database from the pre-upgrade backup. See the System Backup and Restore Process. This is required because the previous application version is not compatible with the migrated schema.
3. Restart all services in dependency order (NATS → Policy Nodes → Wallet).

After rollback

Confirm all services are healthy and the wallet API is responding. Verify the /health endpoints report healthy and that a test operation completes end-to-end.

⚠️

Warning:

The pre-upgrade database backup is the only rollback path when schema migrations have been applied. Always confirm you have a verified backup before proceeding. After a database restore, any transactions that occurred between the backup and the restore point will be lost — on-chain balances will reconcile automatically.

Cloud-specific procedures

Select your deployment platform for step-by-step upgrade instructions:

• Azure Wallet Upgrade
• AWS Wallet Upgrade