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.

CRM and Fees guidance marked legacy on this page applies only to an existing legacy release. Midaz v4 deploys the unified Ledger and serves CRM and Fees on /v2.

This guide’s v3.x and v5.x labels refer to Helm chart releases, not Midaz application versions. The historical chart v5 line introduced the Ledger workload as an option. Midaz application v4 now uses the unified Ledger.

The Helm repository retains a crm.enabled workload and the plugin-fees-helm chart for older application releases. These are legacy compatibility surfaces, not the Midaz v4 deployment model.

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 for this historical chart migration: Choose the Ledger workload or the legacy Onboarding/Transaction workloads.

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>"

Helm chart v5.x: Ledger workload introduced

This section describes the historical chart v5 transition, when the Ledger workload was optional. Midaz application v4 now requires the unified Ledger. Do not use the legacy option for a new v4 deployment.

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

• Make sure that you set the Erlang cookie correctly (32+ printable characters, no spaces).

RabbitMQ PVC data loss

• Expect this after the v4.x dependency change from Bitnami to Groundhog2k. Export RabbitMQ definitions before upgrading and restore after.

Ledger service fails to start

• Make sure that you configure all module-specific environment variables and secrets with the new prefixes (DB_ONBOARDING_*, DB_TRANSACTION_*, etc.).

Ingress not routing to Ledger

• Set ledger.enabled: true. Do not set migration.allowAllServices 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 v7.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 the chart schema on newer versions rejects them.