> ## 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 to v5.x — quick start, version-specific migration paths, breaking changes, and post-upgrade checks.

This guide walks you through upgrading your Midaz Helm deployment to the latest version (v5.x.x).

You'll find a quick start for experienced operators, followed by migration paths from older versions, detailed breaking changes, 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).
* **Kubernetes v1.20+** cluster running.
* **Backup** your existing installation.

### 2. Identify your current version

<CodeGroup>
  ```bash Shell theme={null}
  helm list -n midaz
  ```
</CodeGroup>

### 3. Run the upgrade command

<CodeGroup>
  ```bash Shell theme={null}
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.x.x -n midaz
  ```
</CodeGroup>

### 4. Verify the upgrade

<CodeGroup>
  ```bash Shell theme={null}
  helm list -n midaz
  kubectl get pods -n midaz
  ```
</CodeGroup>

## Version compatibility

***

| Component  | v3.x  | v4.x  | v5.x  |
| :--------- | :---- | :---- | :---- |
| Kubernetes | 1.20+ | 1.20+ | 1.20+ |
| Helm       | 3.8+  | 3.8+  | 3.8+  |
| PostgreSQL | 13+   | 13+   | 13+   |
| MongoDB    | 4.4+  | 4.4+  | 4.4+  |
| Valkey     | 7.x   | 7.x   | 7.x   |

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

List available chart versions from the OCI registry:

* **List available versions**

```bash theme={null}
helm search repo lerianstudio/midaz-helm --versions
```

* **or check GitHub tags:**
  * Visit [https://github.com/LerianStudio/helm/tags](https://github.com/LerianStudio/helm/tags)
  * Filter by "midaz-v" prefix

### 2. Review changes (optional)

Compare your current values with the new chart's default values:

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

### 3. Run the upgrade

Upgrade to your target version:

* **Upgrade with existing values**

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

* **Upgrade with new values**

```bash theme={null}
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 5.7.0 \
  -n midaz \
  -f my-custom-values.yaml
```

<Warning>
  If you have custom values, always pass them with `-f` to avoid losing your configuration during the upgrade.
</Warning>

### 4. Verify the upgrade

* **Check release status**

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

* **Verify if the pods are running**

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

* **Check pod logs for errors**

<Tabs>
  <Tab title="Ledger (v5.x)">
    ```bash theme={null}
    kubectl logs -n midaz deployment/midaz-ledger --tail=50
    kubectl logs -n midaz deployment/midaz-crm --tail=50
    ```
  </Tab>

  <Tab title="Legacy (v4.x)">
    ```bash theme={null}
    kubectl logs -n midaz deployment/midaz-onboarding --tail=50
    kubectl logs -n midaz deployment/midaz-transaction --tail=50
    ```
  </Tab>
</Tabs>

All pods should show `Running` status and `READY` state.

## Upgrading plugins

***

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

### CRM

<Note>
  Starting from Midaz v5.x, CRM is integrated into the main Midaz Helm chart. The standalone plugin-crm chart is only needed for v4.x deployments.
</Note>

<Tabs>
  <Tab title="Integrated (v5.x)">
    CRM is included in the main Midaz chart. No separate upgrade needed.

    * **Verify CRM pods**

    ```bash theme={null}
    kubectl get pods -n midaz -l app=midaz-crm
    ```
  </Tab>

  <Tab title="Standalone (v4.x)">
    * **Upgrade CRM plugin**

    ```bash theme={null}
    helm upgrade plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
      --version 4.0.0 \
      -n midaz \
      -f plugin-crm-values-backup.yaml
    ```

    * **Verify CRM pods**

    ```bash theme={null}
    kubectl get pods -n midaz -l app=plugin-crm
    ```
  </Tab>
</Tabs>

### Fees Engine

* **Upgrade Fees Engine plugin**

```bash theme={null}
helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
  --version 4.1.2 \
  -n midaz \
  -f plugin-fees-values-backup.yaml
```

* **Verify Fees Engine pods**

```bash theme={null}
kubectl get pods -n midaz -l app=plugin-fees
```

### Pix

<Warning>
  The Pix plugin is still under development.
</Warning>

* **Upgrade Pix plugin**

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

```bash theme={null}
kubectl get pods -n midaz -l app=plugin-pix
```