Upgrading Helm

This guide walks you through upgrading your Midaz Helm deployment to the latest version (v5.x.x). You’ll find a quick start for experienced operators, followed by migration paths from older versions, detailed breaking changes, and post-upgrade checks.

Need a refresher on installing Midaz with Helm? Check the Using Helm guide in Deployment strategies before starting your upgrade.

Quick Start

1. Check the prerequisites

Helm v3.8+ installed and available (helm version).
Kubernetes v1.20+ cluster running.
Backup your existing installation.

2. Identify your current version

helm list -n midaz

3. Run the upgrade command

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

4. Verify the upgrade

helm list -n midaz
kubectl get pods -n midaz

Version Compatibility

Component	v3.x	v4.x	v5.x
Kubernetes	1.20+	1.20+	1.20+
Helm	3.8+	3.8+	3.8+
PostgreSQL	13+	13+	13+
MongoDB	4.4+	4.4+	4.4+
Valkey	7.x	7.x	7.x

Choose your migration path

Select your current Helm chart version to see the relevant migration steps:

v4.x → v5.x
v3.x → v4.x
v3.x → v5.x

Migrating from v4.x to v5.x

Pre-upgrade checklist

Backup existing Helm releases:

helm get values -n midaz midaz > midaz-v4-backup.yaml

Decision required: Choose your deployment strategy (Ledger service or legacy Onboarding/Transaction).

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

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:

Setting	v4.x (before)	v5.x (after)
ledger.enabled	N/A	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 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.1.

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:

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:

ledger:
  enabled: true

onboarding:
  enabled: true

transaction:
  enabled: true

migration:
  allowAllServices: true

This mode is intended for testing and migration only. Do not use in production long-term.

Option 3: Migrate to Ledger (recommended)

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

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

Update secrets: Create new secrets with module-specific prefixes (see Ledger Configuration Reference below).

Upgrade: Run helm upgrade with the new chart version.

Verify: Check that the Ledger service is healthy and ingresses are working.

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:

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

Ingress redirection to Ledger

When Ledger is enabled, existing ingresses automatically redirect traffic to the Ledger service, maintaining 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 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:

Deploy the new CRM in the midaz namespace:

crm:
  enabled: true
  configmap:
    MONGO_HOST: "midaz-mongodb"
    MONGO_NAME: "crm"

Migrate your data from the old MongoDB to the new one (if using separate databases).

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

Remove the old plugin-crm release from midaz-plugins namespace.

Upgrade command

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

Rollback procedure

# 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

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

Migrating from v3.x to v4.x

Pre-upgrade checklist

Backup existing Helm releases:

helm get values -n midaz midaz > midaz-v3-backup.yaml

Critical: Backup RabbitMQ data and definitions before upgrading.

Schedule a maintenance window.

Breaking changes in v4.x

RabbitMQ dependency change to Groundhog2k

The RabbitMQ chart dependency has been replaced from Bitnami to Groundhog2k.

This change may lead to PersistentVolumeClaim (PVC) data loss when upgrading existing installations because the underlying StatefulSet, volume mounts, and configuration differ from the previous dependency.

Important notes:

The Groundhog2k chart requires a valid Erlang cookie. Set rabbitmq.authentication.erlangCookie.value to a 32+ character printable string with no spaces. If missing or empty, RabbitMQ will fail to start.
If you need to preserve existing data, back up and plan a controlled migration of PVCs and definitions before upgrading.

Required configuration:

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

This breaking change only impacts deployments that use the chart’s default RabbitMQ (rabbitmq.enabled: true). If you run an external or managed RabbitMQ, you are not affected.

App version bump

Midaz has been bumped to v3.3.1.

Check the app changelog for the complete list of changes.

New features in v4.x

BitnamiSecure images for core data services

The default images for core data services now use the BitnamiSecure repositories with the latest tag:

Service	Image Source	Tag
PostgreSQL	BitnamiSecure	latest
MongoDB	BitnamiSecure	latest
Valkey	BitnamiSecure	latest

If you require pinning to a specific version, override the tag in values.yaml:

postgresql:
  image:
    tag: "16.2.0"

mongodb:
  image:
    tag: "7.0.5"

valkey:
  image:
    tag: "7.2.4"

Official NGINX image for Microfrontends

The previous Bitnami NGINX dependency was replaced with an internal template based on the official nginx image.

If you previously customized the Bitnami-based NGINX configuration, review the new templates under templates/console/ and adjust your values accordingly.

Why we changed Bitnami dependencies

We moved away from Bitnami dependencies due to policy changes impacting stability and operations. For more context, see:

Upgrade command

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

Rollback procedure

# List release history
helm history midaz -n midaz

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

Due to the RabbitMQ dependency change, rolling back may require manual intervention to restore PVCs and data. Ensure you have backups before upgrading.

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 dependency change. Export RabbitMQ definitions before upgrading and restore after.

NGINX configuration issues

Review the new NGINX templates under templates/console/ and update your overrides.

Migrating from v3.x to v5.x (skip v4.x)

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

Pre-upgrade checklist

Backup existing Helm releases:

helm get values -n midaz midaz > midaz-v3-backup.yaml

Critical: Backup RabbitMQ data and definitions (v4.x breaking change).

Decision required: Choose your deployment strategy - Ledger service or legacy Onboarding/Transaction (v5.x breaking change).

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

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

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

Ledger service configuration reference

The Ledger service uses module-specific database configurations:

ledger:
  enabled: false
  name: "ledger"
  replicaCount: 1

  image:
    repository: lerianstudio/midaz-ledger
    tag: ""  # Defaults to Chart.AppVersion
    pullPolicy: IfNotPresent

  configmap:
    # App Configuration
    ENV_NAME: "production"
    LOG_LEVEL: "debug"
    SERVER_PORT: "3000"
    SERVER_ADDRESS: ":3000"

    # Auth Configuration
    PLUGIN_AUTH_ENABLED: "false"
    PLUGIN_AUTH_HOST: ""

    # Accounting Configuration
    ACCOUNT_TYPE_VALIDATION: ""
    TRANSACTION_ROUTE_VALIDATION: ""

    # PostgreSQL - Onboarding Module
    DB_ONBOARDING_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_ONBOARDING_USER: "midaz"
    DB_ONBOARDING_NAME: "onboarding"
    DB_ONBOARDING_PORT: "5432"
    DB_ONBOARDING_SSLMODE: "disable"
    DB_ONBOARDING_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # PostgreSQL - Transaction Module
    DB_TRANSACTION_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_TRANSACTION_USER: "midaz"
    DB_TRANSACTION_NAME: "transaction"
    DB_TRANSACTION_PORT: "5432"
    DB_TRANSACTION_SSLMODE: "disable"
    DB_TRANSACTION_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # MongoDB - Onboarding Module
    MONGO_ONBOARDING_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_ONBOARDING_NAME: "onboarding"
    MONGO_ONBOARDING_USER: "midaz"
    MONGO_ONBOARDING_PORT: "27017"

    # MongoDB - Transaction Module
    MONGO_TRANSACTION_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_TRANSACTION_NAME: "transaction"
    MONGO_TRANSACTION_USER: "midaz"
    MONGO_TRANSACTION_PORT: "27017"

    # Redis (shared)
    REDIS_HOST: "midaz-valkey-primary.midaz.svc.cluster.local.:6379"

    # RabbitMQ (shared)
    RABBITMQ_HOST: "midaz-rabbitmq.midaz.svc.cluster.local."

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

  secrets:
    # Onboarding Module
    DB_ONBOARDING_PASSWORD: ""
    DB_ONBOARDING_REPLICA_PASSWORD: ""
    MONGO_ONBOARDING_PASSWORD: ""

    # Transaction Module
    DB_TRANSACTION_PASSWORD: ""
    DB_TRANSACTION_REPLICA_PASSWORD: ""
    MONGO_TRANSACTION_PASSWORD: ""

    # Shared
    REDIS_PASSWORD: ""
    RABBITMQ_DEFAULT_PASS: ""
    RABBITMQ_CONSUMER_PASS: ""

External secrets support

ledger:
  useExistingSecret: true
  existingSecretName: <existing-secret-name>

Deployment flags reference

Flag	Default	Description
ledger.enabled	false	Enables the unified Ledger service
onboarding.enabled	true	Enables onboarding (auto-disabled when ledger is enabled)
transaction.enabled	true	Enables transaction (auto-disabled when ledger is enabled)
migration.allowAllServices	false	Hidden flag to allow all services simultaneously

Production recommendation

We do not recommend using the Midaz Helm chart’s default dependencies (databases, cache, and message broker) in production environments. For production-grade deployments, follow our best practices to operate these dependencies with proper security, observability, backups, disaster recovery, and SLOs.

Post-upgrade verification

1. Check pod status

kubectl get pods -n midaz

All pods should be Running and READY.

2. Verify services

kubectl get svc -n midaz

3. Check the logs

# If using Ledger service (v5.x)
kubectl logs -n midaz deployment/midaz-ledger

# If using legacy services
kubectl logs -n midaz deployment/midaz-onboarding
kubectl logs -n midaz deployment/midaz-transaction

# Check RabbitMQ logs (important for v4.x+ upgrades)
kubectl logs -n midaz statefulset/midaz-rabbitmq

# Check CRM logs (if enabled)
kubectl logs -n midaz deployment/midaz-crm

4. Verify ingress routing (v5.x with Ledger)

kubectl get ingress -n midaz
kubectl describe ingress midaz-onboarding -n midaz
kubectl describe ingress midaz-transaction -n midaz

General rollback procedure

If you encounter issues after any upgrade:

# List release history
helm history midaz -n midaz

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

# Verify rollback
helm list -n midaz
kubectl get pods -n midaz

Getting started

Understanding Midaz

Installing & deploying

Use cases

Core entities

Best practices

Midaz SDKs & libs

​Quick Start

​1. Check the prerequisites

​2. Identify your current version

​3. Run the upgrade command

​4. Verify the upgrade

​Version Compatibility

​Choose your migration path

​Migrating from v4.x to v5.x

​Pre-upgrade checklist

​Breaking changes in v5.x

​New Ledger service available

​App version bump

​Migration options

​Option 1: Keep using Onboarding and Transaction (gradual migration)

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

​Option 3: Migrate to Ledger (recommended)

​New features in v5.x

​Unified Ledger service

​Ingress redirection to Ledger

​CRM service integration

​Upgrade command

​Rollback procedure

​Common issues

​Migrating from v3.x to v4.x

​Pre-upgrade checklist

​Breaking changes in v4.x

​RabbitMQ dependency change to Groundhog2k

​App version bump

​New features in v4.x

​BitnamiSecure images for core data services

​Official NGINX image for Microfrontends

​Why we changed Bitnami dependencies

​Upgrade command

​Rollback procedure

​Common issues

​Migrating from v3.x to v5.x (skip v4.x)

​Pre-upgrade checklist

​Breaking changes to address

​From v4.x: RabbitMQ dependency change

​From v5.x: New Ledger service

​Upgrade command

​What changes from v3.x

​Ledger service configuration reference

​External secrets support

​Deployment flags reference

​Production recommendation

​Post-upgrade verification

​1. Check pod status

​2. Verify services

​3. Check the logs

​4. Verify ingress routing (v5.x with Ledger)

​General rollback procedure

Quick Start

1. Check the prerequisites

2. Identify your current version

3. Run the upgrade command

4. Verify the upgrade

Version Compatibility

Choose your migration path

Migrating from v4.x to v5.x

Pre-upgrade checklist

Breaking changes in v5.x

New Ledger service available

App version bump

Migration options

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

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

Option 3: Migrate to Ledger (recommended)

New features in v5.x

Unified Ledger service

Ingress redirection to Ledger

CRM service integration

Upgrade command

Rollback procedure

Common issues

Migrating from v3.x to v4.x

Pre-upgrade checklist

Breaking changes in v4.x

RabbitMQ dependency change to Groundhog2k

App version bump

New features in v4.x

BitnamiSecure images for core data services

Official NGINX image for Microfrontends

Why we changed Bitnami dependencies

Upgrade command

Rollback procedure

Common issues

Migrating from v3.x to v5.x (skip v4.x)

Pre-upgrade checklist

Breaking changes to address

From v4.x: RabbitMQ dependency change

From v5.x: New Ledger service

Upgrade command

What changes from v3.x

Ledger service configuration reference

External secrets support

Deployment flags reference

Production recommendation

Post-upgrade verification

1. Check pod status

2. Verify services

3. Check the logs

4. Verify ingress routing (v5.x with Ledger)

General rollback procedure