> ## 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 v4.x para a v5.x

> Migre seu deploy Helm do Midaz da v4.x para a v5.x: siga o checklist antes do upgrade, rode as migrations e valide o novo release.

<Warning>
  Esta migração de chart da v4.x → v5.x é histórica. Mantenha-a para releases legados existentes. Ela não é orientação de deploy do Midaz v4.
</Warning>

## 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-v4-backup.yaml
      ```
    </CodeGroup>
  </Step>

  <Step>
    **Decisão obrigatória**: escolha sua estratégia de deploy (serviço Ledger ou Onboarding/Transaction legados).
  </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 na v5.x

***

### Novo serviço Ledger disponível

A partir da versão 5.0, o **serviço Ledger** fica disponível (`ledger.enabled: false` por padrão). Quando habilitado, esse serviço combina a funcionalidade dos módulos `onboarding` e `transaction` em um único deployment.

<Warning>
  Os serviços separados `onboarding` e `transaction` vão se tornar legados em um release futuro. O serviço Ledger unificado vai se tornar obrigatório. Recomendamos planejar sua migração para o serviço Ledger.
</Warning>

**Valores padrão:**

| Configuração        | v4.x (antes)   | v5.x (depois)                                                    |
| :------------------ | :------------- | :--------------------------------------------------------------- |
| ledger.enabled      | não disponível | false                                                            |
| onboarding.enabled  | true           | true (desabilitado automaticamente quando o ledger é habilitado) |
| transaction.enabled | true           | true (desabilitado automaticamente quando o ledger é habilitado) |

**Impacto ao habilitar o Ledger:**

* O chart remove os deployments `midaz-onboarding` e `midaz-transaction`.
* O chart cria um novo deployment `midaz-ledger`.
* Os ingresses redirecionam automaticamente para o serviço Ledger (a compatibilidade de DNS é mantida).
* A estrutura de variáveis de ambiente e de secrets muda (prefixos específicos de módulo).

### Aumento da versão da aplicação

Patches posteriores da v5.x aumentam a versão da aplicação. Verifique o `Chart.yaml` da versão exata do chart que você pretende usar.

<Note>
  Consulte o [changelog da aplicação](https://github.com/LerianStudio/midaz/blob/main/CHANGELOG.md) para a lista completa de mudanças.
</Note>

## Opções de migração

***

### Opção 1: continuar usando Onboarding e Transaction (migração gradual)

Adicione o seguinte ao seu override de values para manter o comportamento atual:

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

  onboarding:
    enabled: true

  transaction:
    enabled: true
  ```
</CodeGroup>

Isso permite fazer upgrade da versão do chart sem mudar sua infraestrutura.

### Opção 2: rodar todos os serviços ao mesmo tempo (período de teste/migração)

Use a flag oculta `migration.allowAllServices` para rodar os três serviços durante a migração:

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

  onboarding:
    enabled: true

  transaction:
    enabled: true

  migration:
    allowAllServices: true
  ```
</CodeGroup>

<Warning>
  Use este modo apenas para teste e migração. Não o use em produção por longo prazo.
</Warning>

### Opção 3: migrar para o Ledger (recomendado)

Aceite a nova arquitetura e migre para o serviço Ledger unificado:

<Steps>
  <Step>
    **Antes do upgrade**: garanta que seus bancos de dados estão prontos (mesmos bancos, novos nomes de variáveis de ambiente).
  </Step>

  <Step>
    **Atualize os secrets**: crie novos secrets com prefixos específicos de módulo (consulte a [Referência de configuração](/pt/platform/deploy/midaz/midaz-configuration-reference)).
  </Step>

  <Step>
    **Upgrade**: rode o helm upgrade com a nova versão do chart.
  </Step>

  <Step>
    **Verifique**: confirme que o serviço Ledger está saudável e que os ingresses funcionam.
  </Step>
</Steps>

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

  onboarding:
    enabled: false

  transaction:
    enabled: false
  ```
</CodeGroup>

## Novos recursos na v5.x

***

### Serviço Ledger unificado

Um novo serviço Ledger que combina os módulos `onboarding` e `transaction` em um único deployment.

**Características principais:**

* Um único endpoint HTTP (porta 3000 por padrão)
* Configurações de banco de dados separadas para cada módulo
* Conexões de Redis e RabbitMQ compartilhadas
* Novo Balance Sync Worker para processamento em segundo plano

**Novas variáveis de ambiente:**

<CodeGroup>
  ```yaml values.yaml theme={null}
  # Balance Sync Worker
  BALANCE_SYNC_WORKER_ENABLED: "false"
  BALANCE_SYNC_MAX_WORKERS: "5"
  ```
</CodeGroup>

<Note>
  `BALANCE_SYNC_WORKER_ENABLED` e `BALANCE_SYNC_MAX_WORKERS` continuam sendo os nomes atuais. Não os remova. Versões posteriores do chart **adicionam** mais três chaves: `BALANCE_SYNC_BATCH_SIZE` (padrão `50`), `BALANCE_SYNC_FLUSH_TIMEOUT_MS` (padrão `500`) e `BALANCE_SYNC_POLL_INTERVAL_MS` (padrão `50`).
</Note>

### Redirecionamento de ingress para o Ledger

Quando você habilita o Ledger, os ingresses existentes redirecionam o tráfego automaticamente para o serviço Ledger e mantêm a compatibilidade de DNS.

| ledger.enabled | migration.allowAllServices | alvo do ingress de onboarding | alvo do ingress de transaction |
| :------------- | :------------------------- | :---------------------------- | :----------------------------- |
| false          | false (padrão)             | midaz-onboarding              | midaz-transaction              |
| true           | false (padrão)             | midaz-ledger                  | midaz-ledger                   |
| true           | true                       | midaz-onboarding              | midaz-transaction              |

### Integração do serviço CRM

O chart faz deploy do CRM no namespace `midaz`, não em `midaz-plugins`.

<Tip>
  Para mais detalhes, consulte a [documentação do CRM](/pt/products/midaz/crm/crm-overview).
</Tip>

**Migração de um release de CRM independente:**

<Steps>
  <Step>
    Faça deploy do novo CRM no namespace midaz:

    <CodeGroup>
      ```yaml values.yaml theme={null}
      crm:
        enabled: true
        configmap:
          MONGO_HOST: "midaz-mongodb"
          MONGO_NAME: "crm"
      ```
    </CodeGroup>
  </Step>

  <Step>
    Migre seus dados do MongoDB antigo para o novo (se você usa bancos separados).
  </Step>

  <Step>
    Atualize seu ingress/DNS para apontar para o novo serviço CRM.
  </Step>

  <Step>
    Remova o release antigo de CRM de `midaz-plugins`.
  </Step>
</Steps>

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

## Procedimento de rollback

***

<CodeGroup>
  ```bash Shell theme={null}
  # List release history
  helm history midaz -n midaz

  # Rollback to previous version
  helm rollback midaz <REVISION> -n midaz

  # Or explicitly disable ledger
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
    --set ledger.enabled=false \
    --set onboarding.enabled=true \
    --set transaction.enabled=true \
    -n midaz
  ```
</CodeGroup>

## Problemas comuns

***

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