Midaz Helm upgrade guide

CRM and Fees guidance marked legacy on this page applies only to legacy releases that already exist. Midaz v4 deploys the unified Ledger and serves CRM and Fees on /v2.

The Helm repository retains a crm.enabled workload and the plugin-fees-helm chart for older application releases. These are legacy compatibility surfaces, not the Midaz v4 deployment model. This guide walks you through upgrading your Midaz Helm deployment to the current chart line.

For a refresher on installing Midaz with Helm, see the Installing Midaz with Helm guide before starting your upgrade.

Quick start

1. Check the prerequisites

Helm v3.8+ installed and available (helm version), required for OCI registry support.
Backup your databases and your values file.

2. Identify your current version

helm list -n midaz

The CHART column shows your chart version, as midaz-helm-<version>.

3. Run the upgrade command

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <target-version> \
  -n midaz \
  -f your-values.yaml

4. Verify the upgrade

helm list -n midaz
kubectl get pods -n midaz

Version compatibility

Component	Requirement
Kubernetes	A currently supported minor release. The chart renders `autoscaling/v2` and `policy/v1`, so the cluster must serve both.
Helm	3.8+ (OCI support)
PostgreSQL	13+
MongoDB	4.4+
Valkey	7.x

The chart bundles PostgreSQL, MongoDB, RabbitMQ, and Valkey as subchart dependencies. Point the chart at your own managed instances by disabling each dependency (postgresql.enabled: false, and so on). See Production values.

Breaking releases you must account for

Do not jump several major versions in one helm upgrade. Read every relevant upgrade note in the chart repository (UPGRADE-*.md) between your current chart and your target.

Chart release	What changed
v7.0.0	`onboarding` and `transaction` services removed entirely. All functionality moved into the single `ledger` service. The Console and NGINX components went with them, and so did the template helpers for the old services.
v8.4.0	The `otel-collector-lerian` subchart is no longer installed. The key now only injects OTEL env vars, and its schema accepts only `enabled`. The legacy keys (`external`, `extraEnvs`, `exporters`, `opentelemetry-collector`) fail validation at upgrade time.

If you still run a v4.x or v5.x chart, migrate through the paths in Migration overview rather than upgrading straight to the current line.

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

The charts are distributed as OCI artifacts only. There is no Helm repository index to search, so helm search repo does not work here. Browse the release tags to discover versions, then inspect a specific one:

helm show chart oci://registry-1.docker.io/lerianstudio/midaz-helm --version <version>

Or browse the release tags:

Visit https://github.com/LerianStudio/helm/tags
Filter by the midaz-v prefix

2. Review changes before upgrading

Compare your current values with the target chart’s defaults:

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

Then render the upgrade without applying it:

helm template midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <target-version> \
  -n midaz \
  -f your-values.yaml

A schema violation (for example a legacy otel-collector-lerian key) fails here rather than mid-upgrade.

3. Run the upgrade

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <target-version> \
  -n midaz \
  -f your-values.yaml \
  --wait --timeout 10m

With no value arguments, Helm carries forward the stored release values by default. Supplying -f (as above) or --set applies those new overrides to the target chart defaults instead of carrying forward the stored values. Add --reuse-values when you need to merge new overrides with the stored release values. Use --reset-values to discard the stored values and start from the target chart defaults.

4. Verify the upgrade

Check release status

helm list -n midaz

Verify the pod status

kubectl get pods -n midaz

Check pod logs for errors

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

If you maintain the legacy CRM compatibility workload (crm.enabled: true):

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

All pods should show Running status and a ready container count.

midaz-ledger is the only application Deployment the chart creates by default. midaz-crm is added when crm.enabled: true. midaz-onboarding and midaz-transaction no longer exist as of chart v7.0.0.

Upgrading plugins

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

Plugins are separate releases and install into their own namespace, midaz-plugins. Check the plugin’s own release tags at https://github.com/LerianStudio/helm/tags for the current version.

CRM

CRM is a module inside the midaz-helm chart. You enable it with the crm values block. No CRM chart exists. When you enable it, verify its pods after the core upgrade:

kubectl get pods -n midaz -l app.kubernetes.io/name=midaz-crm

Fees

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

kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-fees

Pix

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

kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-br-pix-direct-jd

The chart labels every workload with the app.kubernetes.io/* label set. A selector like -l app=midaz-crm matches nothing.

Introduction

Midaz

Other products

Midaz Helm upgrade guide

Quick start

1. Check the prerequisites

2. Identify your current version

3. Run the upgrade command

4. Verify the upgrade

Version compatibility

Breaking releases you must account for

Upgrading Midaz core

1. Check available versions

2. Review changes before upgrading

3. Run the upgrade

4. Verify the upgrade

Upgrading plugins

CRM

Fees

Pix

​Quick start

​1. Check the prerequisites

​2. Identify your current version

​3. Run the upgrade command

​4. Verify the upgrade

​Version compatibility

​Breaking releases you must account for

​Upgrading Midaz core

​1. Check available versions

​2. Review changes before upgrading

​3. Run the upgrade

​4. Verify the upgrade

​Upgrading plugins

​CRM

​Fees

​Pix

Quick start

1. Check the prerequisites

2. Identify your current version

3. Run the upgrade command

4. Verify the upgrade

Version compatibility

Breaking releases you must account for

Upgrading Midaz core

1. Check available versions

2. Review changes before upgrading

3. Run the upgrade

4. Verify the upgrade

Upgrading plugins

CRM

Fees

Pix