## Prerequisites

Before starting the upgrade, complete the general [pre-upgrade checklist](https://vault.docs.blockdaemon.com/docs/how-to-perform-wallet-upgrade#before-you-upgrade):

1. Review the [release changelog](https://vault.docs.blockdaemon.com/changelog) for breaking changes and migration steps.
2. Take a database backup per the [System Backup and Restore Process](https://vault.docs.blockdaemon.com/docs/wallet-state-backup-and-restore-process).
3. Confirm all services are healthy (`kubectl get pods -n <namespace>`).
4. Record the current Helm release revision for rollback:

```undefined
   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:

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

3. Set the target environment:

```undefined
   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:

```undefined
   make init-plugins
   ```

5. Push the new container images and deploy:

```undefined
   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.

## Post-upgrade verification

After the upgrade completes:

1. Verify all pods are running:

```undefined
   kubectl get pods -n <namespace>
   ```

2. Check the wallet health endpoint:

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

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

```undefined
   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)**

```undefined
   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:

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

2. Restore the database from the pre-upgrade backup following the [System Backup and Restore Process](https://vault.docs.blockdaemon.com/docs/wallet-state-backup-and-restore-process).
3. Restart all services in the correct order (NATS → Policy Nodes → Wallet).
4. Verify health and functionality.

## Troubleshooting

If you encounter issues during or after the upgrade, consult the [Troubleshooting Guide](https://vault.docs.blockdaemon.com/docs/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.