Midaz Helm upgrade guide

Upgrade your Midaz Helm deployment — quick start, the breaking releases between v5 and v8, plugin upgrades, and post-upgrade checks.

This guide walks you through upgrading your Midaz Helm deployment to the current chart line, v8.x.

You’ll find a quick start for experienced operators, the breaking releases you must not skip past blindly, plugin upgrades, 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) — required for OCI registry support.
• Kubernetes v1.20+ cluster running.
• Backup your databases and your values file.

2. Identify your current version

helm list -n midaz

The CHART column shows your chart version (for example midaz-helm-8.6.0).

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	1.20+
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 the release’s upgrade note in the chart repository (charts/midaz/docs/UPGRADE-*.md) for every major version between your current chart and your target.

Chart release	What changed
v5.0.0	Console and NGINX components removed. The bundled Grafana observability templates were removed with them.
v7.0.0	onboarding and transaction services removed entirely — all functionality consolidated into the single ledger service. Template helpers for the old services are gone.
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 — legacy keys (external, extraEnvs, exporters, opentelemetry-collector) now 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 v8.

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

Always pass your values with -f. Without it, Helm reuses nothing from your previous configuration and the release falls back to chart defaults.

4. Verify the upgrade

• Check release status

helm list -n midaz

• Verify the pods are running

kubectl get pods -n midaz

• Check pod logs for errors

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

If you run CRM (crm.enabled: true — it is off by default):

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 part of the Midaz chart — there is no separate CRM release to upgrade. If you enable it (crm.enabled: true), verify its pods after the core upgrade:

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

Fees Engine

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 \
  --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.