Migrating from v4.x to v5.x

Migrate your Midaz Helm deployment from v4.x to v5.x: follow the pre-upgrade checklist, run migrations, and validate the new release.

This v4.x → v5.x chart migration is historical. Preserve it for existing legacy releases. It is not Midaz v4 deployment guidance.

Pre-upgrade checklist

---

1. Backup existing Helm releases:

   Shell

   helm get values -n midaz midaz > midaz-v4-backup.yaml
   
2. Decision required: Choose your deployment strategy (Ledger service or legacy Onboarding/Transaction).

3. If migrating to Ledger service, prepare new secrets with module-specific prefixes.

4. Schedule a maintenance window.

Breaking changes in v5.x

---

New Ledger service available

Starting from version 5.0, the Ledger service is available (ledger.enabled: false by default). When enabled, this service combines the functionality of both onboarding and transaction modules into a single deployment.

The separate onboarding and transaction services will become legacy in a future release. The unified Ledger service will become mandatory. We recommend planning your migration to the Ledger service.

Default values:

Setting	v4.x (before)	v5.x (after)
ledger.enabled	not available	false
onboarding.enabled	true	true (auto-disabled when ledger is enabled)
transaction.enabled	true	true (auto-disabled when ledger is enabled)

Impact when enabling Ledger:

• The chart removes the midaz-onboarding and midaz-transaction deployments.
• The chart creates a new midaz-ledger deployment.
• Ingresses will automatically redirect to the Ledger service (DNS compatibility maintained).
• Environment variables and secrets structure changes (module-specific prefixes).

App version bump

Later v5.x patches raise the app version. Check the Chart.yaml of the exact chart version you target.

Check the app changelog for the complete list of changes.

Migration options

---

Option 1: keep using Onboarding and Transaction (gradual migration)

Add the following to your values override to maintain the current behavior:

values.yaml

ledger:
  enabled: false

onboarding:
  enabled: true

transaction:
  enabled: true

This allows you to upgrade the chart version without changing your infrastructure.

Option 2: run all services simultaneously (testing/migration period)

Use the hidden migration.allowAllServices flag to run all three services during the migration:

values.yaml

ledger:
  enabled: true

onboarding:
  enabled: true

transaction:
  enabled: true

migration:
  allowAllServices: true

Use this mode for testing and migration only. Do not use it in production long-term.

Option 3: migrate to Ledger (recommended)

Accept the new architecture and migrate to the unified Ledger service:

1. Before upgrading: Ensure your databases are ready (same databases, new environment variable names).

2. Update secrets: Create new secrets with module-specific prefixes (see Configuration reference).

3. Upgrade: Run helm upgrade with the new chart version.

4. Verify: Check that the Ledger service is healthy and the ingresses work.

values.yaml

ledger:
  enabled: true

onboarding:
  enabled: false

transaction:
  enabled: false

New features in v5.x

---

Unified Ledger service

A new Ledger service that combines onboarding and transaction modules into a single deployment.

Key characteristics:

• Single HTTP endpoint (port 3000 by default)
• Separate database configurations for each module
• Shared Redis and RabbitMQ connections
• New Balance Sync Worker for background processing

New environment variables:

values.yaml

# Balance Sync Worker
BALANCE_SYNC_WORKER_ENABLED: "false"
BALANCE_SYNC_MAX_WORKERS: "5"

BALANCE_SYNC_WORKER_ENABLED and BALANCE_SYNC_MAX_WORKERS are still the current names. Do not remove them. Later chart versions add three more keys: BALANCE_SYNC_BATCH_SIZE (default 50), BALANCE_SYNC_FLUSH_TIMEOUT_MS (default 500), and BALANCE_SYNC_POLL_INTERVAL_MS (default 50).

Ingress redirection to Ledger

When you enable Ledger, existing ingresses automatically redirect traffic to the Ledger service and maintain DNS compatibility.

ledger.enabled	migration.allowAllServices	onboarding ingress target	transaction ingress target
false	false (default)	midaz-onboarding	midaz-transaction
true	false (default)	midaz-ledger	midaz-ledger
true	true	midaz-onboarding	midaz-transaction

CRM service integration

The chart deploys CRM in the midaz namespace, not in midaz-plugins.

For more details, refer to the CRM Documentation.

Migration from a standalone CRM release:

1. Deploy the new CRM in the midaz namespace:

   values.yaml

   crm:
     enabled: true
     configmap:
       MONGO_HOST: "midaz-mongodb"
       MONGO_NAME: "crm"
   
2. Migrate your data from the old MongoDB to the new one (if using separate databases).

3. Update your ingress/DNS to point to the new CRM service.

4. Remove the old CRM release from midaz-plugins.

Upgrade command

---

Shell

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

Rollback procedure

---

Shell

# List release history
helm history midaz -n midaz

# Rollback to previous version
helm rollback midaz <REVISION> -n midaz

# Or explicitly disable ledger
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --set ledger.enabled=false \
  --set onboarding.enabled=true \
  --set transaction.enabled=true \
  -n midaz

Common issues

---

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