📘

Note:

The upgrade process may take up to an hour. Plan a maintenance window accordingly.

Prerequisites

Before starting the upgrade, complete the general pre-upgrade checklist:

1. Review the release changelog for breaking changes and migration steps.
2. Take a database backup per the System Backup and Restore Process.
3. Confirm all services are healthy (kubectl get pods -n <namespace>).
4. Record the current Helm release revision for rollback:

   helm history <release-name> -n <namespace>

Upgrade procedure

1. Navigate to your Azure portal and open the cloud shell (the >_ symbol near the search bar).

2. Download and extract the updated bundles using the pre-signed URLs provided by Blockdaemon:

   cd clouddrive
   wget "<package-url>" -O - | tar -xz
   wget "<common-url>" -O - | tar -xz

3. Set the target environment:

   CUSTOMER_MPA_ENVIRONMENT=testnet make switch-to-testnet
   # or
   CUSTOMER_MPA_ENVIRONMENT=mainnet make switch-to-mainnet

4. Re-initialize the Terraform state, bootstrap, and plugins:

   make init-plugins

5. Push the new container images and deploy:

   make push-images
   make upgrade-wallet

   Terraform highlights changes in different colors: removed (red), changed (orange), added (green). Review the plan and answer "yes" to proceed.

⚠️

Warning:

Use make upgrade-wallet (not make deploy-wallet) when upgrading an existing installation. Using deploy-wallet against an existing Helm release will fail with "cannot re-use a name that is still in use."

Post-upgrade verification

After the upgrade completes:

1. Verify all pods are running:

   kubectl get pods -n <namespace>

2. Check the wallet health endpoint:

   curl -s https://<your-wallet-domain>/health

3. Confirm the wallet version matches the target release by checking the running image tags:

   kubectl get pods -n <namespace> -o jsonpath='{range .items[*]}{.metadata.name}{"\t"}{.spec.containers[*].image}{"\n"}{end}'

4. Perform a smoke test — verify you can list accounts and view balances in the UI or via API.

Rollback procedure

If the upgrade fails or the wallet is not healthy after deployment:

Option 1: Helm rollback (no schema migration issues)

helm rollback <release-name> <previous-revision> -n <namespace>

Wait for all pods to stabilize, then re-run the post-upgrade verification steps above against the previous version.

Option 2: Full rollback (schema migrations applied)

If the new version applied database migrations that are incompatible with the previous version:

1. Roll back the Helm release:

   helm rollback <release-name> <previous-revision> -n <namespace>

2. Restore the database from the pre-upgrade backup following the System Backup and Restore Process.

3. Restart all services in the correct order (NATS → Policy Nodes → Wallet).

4. Verify health and functionality.

📘

Note:

After a database restore, any transactions that occurred between the backup and the restore point will be lost. On-chain balances will reconcile automatically on the next indexer pass.

Troubleshooting

If you encounter issues during or after the upgrade, consult the Troubleshooting Guide for common error codes and resolutions.

For Terraform-specific errors, check that the init-plugins step completed without errors and that cloud shell has network access to the AKS cluster.