Midaz Helm upgrade guide

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 Installing Midaz with Helm guide 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

Upgrading Midaz core

When upgrading Midaz or any plugin, always upgrade the corresponding Helm chart.Updating application versions without upgrading the Helm chart can lead to deployment failures or inconsistent environments.

1. Check available versions

List available chart versions from the OCI registry:

List available versions

helm search repo lerianstudio/midaz-helm --versions

or check GitHub tags:
- Visit https://github.com/LerianStudio/helm/tags
- Filter by “midaz-v” prefix

2. Review changes (optional)

Compare your current values with the new chart’s default values:

helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.7.0 > new-defaults.yaml

3. Run the upgrade

Upgrade to your target version:

Upgrade with existing values

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 5.7.0 \
  -n midaz \
  -f midaz-values-backup.yaml

Upgrade with new values

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 5.7.0 \
  -n midaz \
  -f my-custom-values.yaml

If you have custom values, always pass them with -f to avoid losing your configuration during the upgrade.

4. Verify the upgrade

Check release status

helm list -n midaz

Verify if the pods are running

kubectl get pods -n midaz

Check pod logs for errors

Ledger (v5.x)
Legacy (v4.x)

kubectl logs -n midaz deployment/midaz-ledger --tail=50
kubectl logs -n midaz deployment/midaz-crm --tail=50

kubectl logs -n midaz deployment/midaz-onboarding --tail=50
kubectl logs -n midaz deployment/midaz-transaction --tail=50

All pods should show Running status and READY state.

Upgrading plugins

Always upgrade Midaz Core before upgrading plugins. Plugins depend on Midaz Core APIs.

CRM

Starting from Midaz v5.x, CRM is integrated into the main Midaz Helm chart. The standalone plugin-crm chart is only needed for v4.x deployments.

Integrated (v5.x)
Standalone (v4.x)

CRM is included in the main Midaz chart. No separate upgrade needed.

Verify CRM pods

kubectl get pods -n midaz -l app=midaz-crm

Upgrade CRM plugin

helm upgrade plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
  --version 4.0.0 \
  -n midaz \
  -f plugin-crm-values-backup.yaml

Verify CRM pods

kubectl get pods -n midaz -l app=plugin-crm

Fees Engine

Upgrade Fees Engine

helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
  --version 4.1.2 \
  -n midaz \
  -f plugin-fees-values-backup.yaml

Verify Fees Engine pods

kubectl get pods -n midaz -l app=plugin-fees

Pix

Upgrade Pix plugin

helm upgrade plugin-pix oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd \
  --version 1.2.6 \
  -n midaz \
  -f plugin-pix-values-backup.yaml

Verify Pix pods

kubectl get pods -n midaz -l app=plugin-pix

​Quick start

​1. Check the prerequisites

​2. Identify your current version

​3. Run the upgrade command

​4. Verify the upgrade

​Version compatibility

​Upgrading Midaz core

​1. Check available versions

​2. Review changes (optional)

​3. Run the upgrade

​4. Verify the upgrade

​Upgrading plugins

​CRM

​Fees Engine

​Pix

Quick start

1. Check the prerequisites

2. Identify your current version

3. Run the upgrade command

4. Verify the upgrade

Version compatibility

Upgrading Midaz core

1. Check available versions

2. Review changes (optional)

3. Run the upgrade

4. Verify the upgrade

Upgrading plugins

CRM

Fees Engine

Pix