Skip to main content
If you’re upgrading directly from v3.x to v5.x, you need to address breaking changes from both versions.

​
Pre-upgrade checklist

1
Backup existing Helm releases:
helm get values -n midaz midaz > midaz-v3-backup.yaml
2
Critical: Backup RabbitMQ data and definitions (v4.x breaking change).
3
Decision required: Choose your deployment strategy - Ledger service or legacy Onboarding/Transaction (v5.x breaking change).
4
If migrating to Ledger service, prepare new secrets with module-specific prefixes.
5
Schedule a maintenance window.

​
Breaking changes to address

​
From v4.x: RabbitMQ dependency change

The RabbitMQ chart dependency changed from Bitnami to Groundhog2k. This may lead to PVC data loss. Back up RabbitMQ data before upgrading.
Required configuration: 
rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ printable characters without spaces>"

​
From v5.x: new Ledger service

The unified Ledger service is available and will become mandatory in a future release. Plan your migration strategy.
Choose one of these configurations: Option A: Keep legacy services (gradual migration) 
ledger:
  enabled: false

onboarding:
  enabled: true

transaction:
  enabled: true

rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ printable characters>"
Option B: Migrate to Ledger (recommended) 
ledger:
  enabled: true

onboarding:
  enabled: false

transaction:
  enabled: false

rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ printable characters>"
If using Option B, create new secrets with module-specific prefixes:
  • DB_ONBOARDING_PASSWORD, DB_TRANSACTION_PASSWORD
  • MONGO_ONBOARDING_PASSWORD, MONGO_TRANSACTION_PASSWORD

​
Upgrade command

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.x.x -n midaz

​
What changes from v3.x

ChangeSource VersionImpact
RabbitMQ Groundhog2kv4.xRequires Erlang cookie, possible PVC data loss
BitnamiSecure imagesv4.xPostgreSQL, MongoDB, Valkey use hardened images
Official NGINXv4.xReview custom NGINX configs
Ledger servicev5.xNew unified service (optional but recommended)
CRM integrationv5.xMoves from midaz-plugins to midaz namespace

​
Common issues

RabbitMQ fails to start
  • Ensure the Erlang cookie is set correctly (32+ printable characters, no spaces).
RabbitMQ PVC data loss
  • This is expected due to the v4.x dependency change from Bitnami to Groundhog2k. Export RabbitMQ definitions before upgrading and restore after.
Ledger service fails to start
  • Verify that all module-specific environment variables and secrets are configured with the new prefixes (DB_ONBOARDING_*, DB_TRANSACTION_*, etc.).
Ingress not routing to Ledger
  • Ensure ledger.enabled: true and migration.allowAllServices is not set to true.
Missing secrets after enabling Ledger
  • Create new secrets with module prefixes:
    • DB_ONBOARDING_PASSWORD instead of DB_PASSWORD
    • DB_TRANSACTION_PASSWORD instead of DB_PASSWORD
    • MONGO_ONBOARDING_PASSWORD instead of MONGO_PASSWORD
    • MONGO_TRANSACTION_PASSWORD instead of MONGO_PASSWORD
NGINX configuration issues
  • The v4.x upgrade replaced Bitnami NGINX with official NGINX templates. Review the new templates under templates/console/ and update your overrides.