Migrating from v3.x to v5.x

Upgrade your Midaz Helm deployment directly from v3.x to v5.x — address breaking changes from both major versions in a single migration.

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:

   Shell

   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:

values.yaml

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)

values.yaml

ledger:
  enabled: false

onboarding:
  enabled: true

transaction:
  enabled: true

rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ printable characters>"

Option B: Migrate to Ledger (recommended)

values.yaml

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

Shell

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

What changes from v3.x

Change	Source Version	Impact
RabbitMQ Groundhog2k	v4.x	Requires Erlang cookie, possible PVC data loss
BitnamiSecure images	v4.x	PostgreSQL, MongoDB, Valkey use hardened images
Official NGINX	v4.x	Review custom NGINX configs
Ledger service	v5.x	New unified service (optional but recommended)
CRM integration	v5.x	Moves 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

Console and NGINX overrides no longer apply

• Chart v5.0.0 removed the Console and NGINX components entirely — templates/console/ no longer exists. Drop any console.* or NGINX overrides from your values file; they are inert and will be rejected by the chart schema on newer versions.