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.
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
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:
helm search repo lerianstudio/midaz-helm --versions
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
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
- 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
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.kubectl get pods -n midaz -l app=midaz-crm
helm upgrade plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
--version 4.0.0 \
-n midaz \
-f plugin-crm-values-backup.yaml
kubectl get pods -n midaz -l app=plugin-crm
Fees Engine
- Upgrade Fees Engine plugin
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
kubectl get pods -n midaz -l app=plugin-fees
Pix
The Pix plugin is still under development.
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
kubectl get pods -n midaz -l app=plugin-pix
