📘

Note:

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

AWS production deployments run on Amazon ECS (not Kubernetes Helm). Roll back by redeploying a prior release bundle with the Makefile targets below, or restore RDS when schema migrations require it.

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 ECS services and Policy Node Nitro instances are healthy.
4. Retain the previous installer bundle (Makefile, customer-config.yml, bd-wallet.yml, and deployer version) so you can redeploy if rollback is needed.

Upgrade procedure

1. Sync the installer bundle for the target wallet release tag:

export CUSTOMER_SHARED_SEGMENT=<target-wallet-release-tag>
export DEPLOYER_VERSION=<target-deployer-version>
export MPA_IMAGE_TAG=<target-policy-node-enclave-tag>
export NAMESPACE=<your-namespace>
export ENV_PREFIX=<environment-name>
export AWS_REGION=<region>
export BACKEND_API_PATH=https://api.<env>.wallet.example.com
PULL_SYNC_MAKEFILE=1 make pull-customer-assets

2. Pull the deployer image:

make pull-deployer

3. Refresh deployment configuration for the new release:

   • Update customer-config.yml if Blockdaemon supplied changes, then run make generate-customer-assets, or
   • Merge release notes into your existing bd-wallet.yml and run make generate-conf-files.

4. Optional but recommended: create an RDS snapshot before applying CDK changes:

export RDS_DB_INSTANCE_IDENTIFIER=<your-db-cluster-id>
make backup-rds-snapshot

5. Run the upgrade targets (service images, conf refresh, wallet stack, Nitro, start):

make prepare-update
make update

prepare-update runs deploy-service-images and generate-conf-files (and attempts backup-rds-snapshot when RDS_DB_INSTANCE_IDENTIFIER is set). update runs deploy-baseline, generate-fe-env, deploy-wallet, deploy-nitro-nodes, and start-wallet.

6. When the upgrade changes Policy Node enclave artifacts, confirm MPA_IMAGE_TAG matches the EIF under s3://638663786504-prod-mpa-deployment-customer-artifacts/enclave/<MPA_IMAGE_TAG>/ before deploy-nitro-nodes.

📘

Note

Do not re-run populate-secrets-policy-node* on AWS unless Blockdaemon instructs you to rotate Policy Node crypto material. Re-running populate-secrets-wallet overwrites most wallet-partition secrets and can break a live environment.

Post-upgrade verification

After the upgrade completes:

1. Verify ECS services are running. In the AWS Console (ECS > Clusters > Services) or CLI:

aws ecs list-services --cluster <cluster-name>
aws ecs describe-services --cluster <cluster-name> --services <service-name>

2. Check the wallet health endpoint:

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

3. Confirm ECS task definition image tags match the target release.

4. Smoke test: list accounts and view balances in the UI or API.

Rollback procedure

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

Option 1: Redeploy previous version (no incompatible schema migration)

Restore the previous Makefile variables and bundle, then:

make pull-deployer
make prepare-update
make update

Wait for services to stabilize, then repeat post-upgrade verification.

Option 2: Full rollback (schema migrations applied)

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

1. Redeploy the previous application version as in Option 1.
2. Restore the database from the pre-upgrade backup per the System Backup and Restore Process.
3. Restart services in order: NATS, Policy Nodes, then wallet.
4. Verify health and functionality.

📘

Note

After a database restore, transactions between the backup time and restore time are lost. On-chain balances reconcile on the next indexer pass.

Configuration-only changes (no version bump)

When you change bd-wallet.yml without upgrading images:

make generate-conf-files
make deploy-wallet

Add make deploy-nitro-nodes when Policy Node configuration changed. See Step 14 in the AWS deployment process.

Troubleshooting

See Installation Troubleshooting and the general Troubleshooting Guide.