Skip to main content
This guide covers how to upgrade Midaz and its plugins using Helm. Whether you’re applying a patch, minor update, or moving between major versions, follow these procedures to ensure a smooth upgrade.
Upgrading from Helm v2.x to v3.x? Check the dedicated Helm v3 upgrade guide for breaking changes and migration steps.

​
Prerequisites

Before starting any upgrade, ensure you have:
Version compatibility between Helm charts and applications is defined by the official compatibility matrix maintained in the Helm repository README.This matrix is automatically updated on every application release and should always be checked before upgrading.

​
Verify your tools

Run the following commands to verify your tools:
  • Check Helm version
helm version
  • Check kubectl access
kubectl cluster-info

​
Pre-upgrade checklist

1

Check current versions

Review your current deployment versions:
  • List Helm releases
helm list -n midaz
  • Check running pods
kubectl get pods -n midaz -o wide
2

Review target version compatibility

Check the version compatibility table to ensure your target version is compatible with your plugins and infrastructure.
3

Backup current values

Save your current Helm values for reference and potential rollback:
  • Backup Midaz values
helm get values midaz -n midaz > midaz-values-backup.yaml
  • Backup plugin values (example: CRM)
helm get values plugin-crm -n midaz > plugin-crm-values-backup.yaml
4

Review release notes

Check the Helm repository for release notes and breaking changes in your target version.
5

Schedule maintenance window

Coordinate with your team and schedule an appropriate maintenance window for the upgrade.
6

Ensure database backups

Ensure database backups are in place before upgrading, especially for major versions.
In specific cases, such as certain hotfix releases, a Helm chart upgrade may not be required.Always check the release notes before skipping a Helm upgrade.

​
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

​
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 4.4.8 > 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 4.4.8 \
  -n midaz \
  -f midaz-values-backup.yaml
  • Upgrade with new values
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 4.4.8 \
  -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
kubectl logs -n midaz deployment/midaz-console --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

  • Upgrade CRM plugin
helm upgrade plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
  --version 3.2.1 \
  -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 plugin
helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees \
  --version 3.4.7 \
  -n midaz \
  -f plugin-fees-values-backup.yaml
  • Verify Fees Engine pods
kubectl get pods -n midaz -l app=plugin-fees

​
Pix

The Pix plugin is still under development.
  • 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

​
Best practices

​
Upgrade order

Always upgrade in this order:
  1. Infrastructure (if needed)
  2. Midaz Core
  3. Plugins (one at a time)

​
Test first

Always test upgrades in a staging environment that mirrors production before applying to production.

​
Monitor closely

Monitor logs and metrics closely for the first 15-30 minutes after an upgrade.

​
Keep backups

Maintain backups of your Helm values and database before major upgrades.

​
Upgrade checklist summary

StepCommandVerified
Backup valueshelm get values <release> -n midaz > backup.yaml
Check compatibilityReview compatibility table
Upgrade Midazhelm upgrade midaz ...
Verify Midaz podskubectl get pods -n midaz
Upgrade pluginshelm upgrade <plugin> ...
Verify plugin podskubectl get pods -n midaz
Check logskubectl logs -n midaz deployment/<name>

​
Rollback procedures

If something goes wrong after an upgrade, you can rollback to a previous version.

​
When to rollback

Consider rolling back if you observe:
  • Pods failing to start or crash-looping
  • API errors or service unavailability
  • Data inconsistencies
  • Performance degradation

​
Check release history

View the revision history for a release: 
helm history midaz -n midaz
Example output: 
REVISION  STATUS      CHART           APP VERSION  DESCRIPTION
1         superseded  midaz-4.3.4     3.4.6        Install complete
2         deployed    midaz-4.4.8     3.4.7        Upgrade complete

​
Execute rollback

Rollback to a specific revision:
  • Rollback Midaz to previous revision
helm rollback midaz 1 -n midaz
  • Rollback plugin (example: CRM)
helm rollback plugin-crm 1 -n midaz

​
Verify rollback

  • Verify release version
helm list -n midaz
  • Verify pods
kubectl get pods -n midaz
  • Check logs
kubectl logs -n midaz deployment/midaz-console --tail=50
Rollbacks may not revert database schema changes. If the upgrade included database migrations, you may need to restore from a database backup.

​
Troubleshooting

​
Pods stuck in Pending state

Symptom: Pods remain in Pending status after upgrade. Solution: Check for resource constraints:
  • Describe pending pod
kubectl describe pod <pod-name> -n midaz
  • Check node resources
kubectl top nodes

​
Image pull errors

Symptom: Pods show ImagePullBackOff or ErrImagePull. Solution: Verify image registry access and credentials:
  • Check pod events
kubectl describe pod <pod-name> -n midaz | grep -A 10 Events
  • Verify image exists
docker pull lerianstudio/midaz-console:3.4.6

​
Configuration errors

Symptom: Pods crash with configuration-related errors in logs. Solution: Compare your values with the new defaults:
  • View current values
helm get values midaz -n midaz
  • View chart defaults
helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version 4.4.8

​
Database connection issues

Symptom: Services fail to connect to PostgreSQL or MongoDB. Solution: Verify database connectivity and credentials:
  • Check database pods
kubectl get pods -n midaz -l app.kubernetes.io/name=postgresql
kubectl get pods -n midaz -l app.kubernetes.io/name=mongodb
  • Check service logs
kubectl logs -n midaz deployment/midaz-onboarding | grep -i database