> ## 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.
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](/en/platform/deploy/midaz/midaz-installation) 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
```bash theme={null}
helm list -n midaz
```
The `CHART` column shows your chart version, as `midaz-helm-`.
### 3. Run the upgrade command
```bash theme={null}
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
--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 | 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](/en/platform/deploy/midaz/midaz-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](https://github.com/LerianStudio/helm/tree/main/charts/midaz/docs) (`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](/en/platform/deploy/midaz/midaz-migrating-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:
```bash theme={null}
helm show chart oci://registry-1.docker.io/lerianstudio/midaz-helm --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 > 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 \
-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 \
-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**
```bash theme={null}
helm list -n midaz
```
* **Verify the pod status**
```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 maintain the legacy CRM compatibility workload (`crm.enabled: true`):
```bash theme={null}
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](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:
```bash theme={null}
kubectl get pods -n midaz -l app.kubernetes.io/name=midaz-crm
```
### Fees
```bash theme={null}
helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
--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-helm \
--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
```
The chart labels every workload with the `app.kubernetes.io/*` label set. A selector like `-l app=midaz-crm` matches nothing.