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

# Guia de atualização

> Atualize seu deploy Helm do Midaz para v5.x — quick start, caminhos de migração por versão, breaking changes e verificações pós-upgrade.

Este guia orienta você na atualização do seu deployment Midaz via Helm para a versão mais recente (v5.x.x).

Você encontrará um início rápido para operadores experientes, seguido de caminhos de migração a partir de versões anteriores, breaking changes detalhadas e verificações pós-atualização.

<Tip>
  Precisa revisar a instalação do Midaz com Helm? Confira o guia [Instalando o Midaz com Helm](/pt/platform/helm/midaz/midaz-installation) em **Estratégias de deployment** antes de iniciar sua atualização.
</Tip>

## Início rápido

***

### 1. Verifique os pré-requisitos

* **Helm v3.8+** instalado e disponível (helm version).
* **Kubernetes v1.20+** cluster em execução.
* **Backup** sua instalação existente.

### 2. Identifique sua versão atual

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

### 3. Execute o comando de atualização

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

### 4. Verifique a atualização

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

## Compatibilidade de versões

***

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

## Atualizando o Midaz core

***

<Warning>
  Ao atualizar o Midaz ou qualquer plugin, sempre atualize o Helm chart correspondente.

  Atualizar versões de aplicação sem atualizar o Helm chart pode causar falhas no deployment ou ambientes inconsistentes.
</Warning>

### 1. Verificar versões disponíveis

Liste as versões de chart disponíveis no registro OCI:

* **Listar versões disponíveis**

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

* **ou confira as tags no GitHub:**
  * Visit [https://github.com/LerianStudio/helm/tags](https://github.com/LerianStudio/helm/tags)
  * Filtre pelo prefixo "midaz-v"

### 2. Revisar mudanças (opcional)

Compare seus valores atuais com os valores padrão do novo chart:

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

### 3. Executar a atualização

Atualize para a versão alvo:

* **Atualizar com valores existentes**

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

* **Atualizar com novos valores**

```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>
  Se você tem valores customizados, sempre passe-os com `-f` para evitar perder sua configuração durante a atualização.
</Warning>

### 4. Verificar a atualização

* **Verificar status do release**

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

* **Verificar se os pods estão em execução**

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

* **Verificar logs dos pods por erros**

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

Todos os pods devem mostrar status `Running` e estado `READY`.

## Atualizando plugins

***

<Note>
  Sempre atualize o Midaz Core **antes** de atualizar plugins. Os plugins dependem das APIs do Midaz Core.
</Note>

### CRM

<Note>
  A partir do Midaz v5.x, o CRM está integrado ao Helm chart principal do Midaz. O chart standalone plugin-crm só é necessário para deployments v4.x.
</Note>

<Tabs>
  <Tab title="Integrated (v5.x)">
    O CRM está incluído no chart principal do Midaz. Nenhuma atualização separada é necessária.

    * **Verificar pods do CRM**

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

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

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

    * **Verificar pods do CRM**

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

### Fees Engine

* **Atualizar Fees Engine**

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

* **Verificar pods do Fees Engine**

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

### Pix

* **Atualizar plugin Pix**

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

* **Verificar pods do Pix**

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