> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Tip>
  Need a refresher on installing Midaz with Helm? Check the [Installing Midaz with Helm](/en/platform/helm/midaz/midaz-installation) guide before starting your upgrade.
</Tip>

## 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

```bash theme={null}
helm list -n midaz
```

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

### 3. Run the upgrade command

```bash theme={null}
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <target-version> \
  -n midaz \
  -f your-values.yaml
```

### 4. Verify the upgrade

```bash theme={null}
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](/en/platform/helm/midaz/midaz-production-values).

## Breaking releases you must account for

***

<Warning>
  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.
</Warning>

| 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](/en/platform/helm/midaz/midaz-migrating-overview) rather than upgrading straight to v8.

## Upgrading Midaz core

***

<Warning>
  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.
</Warning>

### 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:

```bash theme={null}
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](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:

```bash theme={null}
helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version <target-version> > new-defaults.yaml
```

Then render the upgrade without applying it:

```bash theme={null}
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

```bash theme={null}
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <target-version> \
  -n midaz \
  -f your-values.yaml \
  --wait --timeout 10m
```

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

### 4. Verify the upgrade

* **Check release status**

```bash theme={null}
helm list -n midaz
```

* **Verify the pods are running**

```bash theme={null}
kubectl get pods -n midaz
```

* **Check pod logs for errors**

```bash theme={null}
kubectl logs -n midaz deployment/midaz-ledger --tail=50
```

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

```bash theme={null}
kubectl logs -n midaz deployment/midaz-crm --tail=50
```

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

<Note>
  `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.
</Note>

## Upgrading plugins

***

<Note>
  Always upgrade Midaz Core **before** upgrading plugins. Plugins depend on Midaz Core APIs.
</Note>

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](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:

```bash theme={null}
kubectl get pods -n midaz -l app.kubernetes.io/name=midaz-crm
```

### Fees Engine

```bash theme={null}
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
```

```bash theme={null}
kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-fees
```

### Pix

```bash theme={null}
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
```

```bash theme={null}
kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-br-pix-direct-jd
```

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