Skip to main content

​
Pre-upgrade checklist

1
Backup existing Helm releases:
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 strongly recommend planning your migration to the Ledger service.
Default values: Impact when enabling Ledger:
  • The midaz-onboarding and midaz-transaction deployments will be removed.
  • A new midaz-ledger deployment will be created.
  • Ingresses will automatically redirect to the Ledger service (DNS compatibility maintained).
  • Environment variables and secrets structure changes (module-specific prefixes).

​
App version bump

Midaz has been bumped to v3.5.3.
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:
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:
This mode is intended for testing and migration only. Do not use in production long-term.
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 ingresses are working.

​
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:
These environment variables have been renamed in later versions. The current variable names are: BALANCE_SYNC_BATCH_SIZE, BALANCE_SYNC_FLUSH_TIMEOUT_MS, and BALANCE_SYNC_POLL_INTERVAL_MS. See the Configuration Reference for current defaults.

​
Ingress redirection to Ledger

When Ledger is enabled, existing ingresses automatically redirect traffic to the Ledger service, maintaining DNS compatibility.

​
CRM service integration

The CRM service is now available as an integrated component, moving from midaz-plugins to midaz namespace.
For more details, refer to the CRM Documentation.
Migration from plugin-crm:
1
Deploy the new CRM in the midaz namespace:
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 plugin-crm release from midaz-plugins namespace.

​
Upgrade command

​
Rollback procedure

​
Common issues

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