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

# Migrar da v3.x para a v5.x

> Faça upgrade do seu deploy Helm do Midaz direto da v3.x para a v5.x: trate as mudanças incompatíveis das duas versões maiores em uma única migração.

<Warning>
  As orientações de CRM e Fees marcadas como legado nesta página valem apenas para um release legado existente. O Midaz v4 faz deploy do Ledger unificado e serve CRM e Fees em `/v2`.
</Warning>

<Note>
  Os rótulos v3.x e v5.x deste guia referem-se a **releases do Helm chart**, não a versões da aplicação Midaz. A linha histórica do chart v5 introduziu a carga de trabalho do Ledger como opção. A aplicação Midaz v4 agora usa o Ledger unificado.
</Note>

O repositório Helm mantém uma carga de trabalho `crm.enabled` e o chart `plugin-fees-helm` para releases de aplicação mais antigos. Essas são superfícies de compatibilidade legadas, não o modelo de deploy do Midaz v4.

Se você está fazendo upgrade direto da v3.x para a v5.x, precisa tratar as mudanças incompatíveis das duas versões.

## Checklist antes do upgrade

***

<Steps>
  <Step>
    Faça backup dos releases Helm existentes:

    <CodeGroup>
      ```bash Shell theme={null}
      helm get values -n midaz midaz > midaz-v3-backup.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Crítico**: faça backup dos dados e das definições do RabbitMQ (mudança incompatível da v4.x).
  </Step>

  <Step>
    **Decisão obrigatória para esta migração histórica de chart**: escolha a carga de trabalho do Ledger ou as cargas de trabalho legadas de Onboarding/Transaction.
  </Step>

  <Step>
    Se você migrar para o serviço Ledger, prepare novos secrets com prefixos específicos de módulo.
  </Step>

  <Step>
    Agende uma janela de manutenção.
  </Step>
</Steps>

## Mudanças incompatíveis a tratar

***

### Da v4.x: mudança da dependência RabbitMQ

<Danger>
  A dependência de chart do RabbitMQ mudou de Bitnami para Groundhog2k. Isso pode causar **perda de dados de PVC**. Faça backup dos dados do RabbitMQ antes do upgrade.
</Danger>

**Configuração obrigatória:**

<CodeGroup>
  ```yaml values.yaml theme={null}
  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters without spaces>"
  ```
</CodeGroup>

### Helm chart v5.x: carga de trabalho do Ledger introduzida

<Warning>
  Esta seção descreve a transição histórica do chart v5, quando a carga de trabalho do Ledger era opcional. A aplicação Midaz v4 agora exige o Ledger unificado. Não use a opção legada para um novo deploy da v4.
</Warning>

**Escolha uma destas configurações:**

**Opção A: manter os serviços legados (migração gradual)**

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: false

  onboarding:
    enabled: true

  transaction:
    enabled: true

  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters>"
  ```
</CodeGroup>

**Opção B: migrar para o Ledger (recomendado)**

<CodeGroup>
  ```yaml values.yaml theme={null}
  ledger:
    enabled: true

  onboarding:
    enabled: false

  transaction:
    enabled: false

  rabbitmq:
    authentication:
      erlangCookie:
        value: "<32+ printable characters>"
  ```
</CodeGroup>

Se usar a Opção B, crie novos secrets com prefixos específicos de módulo:

* `DB_ONBOARDING_PASSWORD`, `DB_TRANSACTION_PASSWORD`
* `MONGO_ONBOARDING_PASSWORD`, `MONGO_TRANSACTION_PASSWORD`

## Comando de upgrade

***

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

## O que muda em relação à v3.x

***

| Mudança               | Versão de origem | Impacto                                                          |
| :-------------------- | :--------------- | :--------------------------------------------------------------- |
| RabbitMQ Groundhog2k  | v4.x             | Exige Erlang cookie, possível perda de dados de PVC              |
| Imagens BitnamiSecure | v4.x             | PostgreSQL, MongoDB, Valkey usam imagens com segurança reforçada |
| NGINX oficial         | v4.x             | Revise as configurações customizadas do NGINX                    |
| Serviço Ledger        | v5.x             | Novo serviço unificado (opcional, mas recomendado)               |
| Integração do CRM     | v5.x             | Sai de midaz-plugins para o namespace midaz                      |

## Problemas comuns

***

**O RabbitMQ não inicia**

* Confirme que você definiu o Erlang cookie corretamente (32+ caracteres imprimíveis, sem espaços).

**Perda de dados do PVC do RabbitMQ**

* Espere isso depois da mudança de dependência da v4.x, de Bitnami para Groundhog2k. Exporte as definições do RabbitMQ antes do upgrade e restaure depois.

**O serviço Ledger não inicia**

* Confirme que você configurou todas as variáveis de ambiente e secrets específicos de módulo com os novos prefixos (`DB_ONBOARDING_*`, `DB_TRANSACTION_*`, etc.).

**Ingress não roteia para o Ledger**

* Defina `ledger.enabled: true`. Não defina `migration.allowAllServices` como `true`.

**Secrets ausentes depois de habilitar o Ledger**

* Crie novos secrets com prefixos de módulo:
  * `DB_ONBOARDING_PASSWORD` em vez de `DB_PASSWORD`
  * `DB_TRANSACTION_PASSWORD` em vez de `DB_PASSWORD`
  * `MONGO_ONBOARDING_PASSWORD` em vez de `MONGO_PASSWORD`
  * `MONGO_TRANSACTION_PASSWORD` em vez de `MONGO_PASSWORD`

**Overrides de Console e NGINX não valem mais**

* O chart v7.0.0 removeu por completo os componentes Console e NGINX. `templates/console/` não existe mais. Remova do seu arquivo de values qualquer override `console.*` ou de NGINX. Eles são inertes, e o schema do chart nas versões mais novas os rejeita.