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

# Migração de v4.x para v5.x

> Migre seu deploy Helm do Midaz de v4.x para v5.x — siga o checklist prévio, execute migrações e valide o novo release.

## Checklist pré-atualização

<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 necessária**: Escolha sua estratégia de deployment (serviço Ledger ou legado Onboarding/Transaction).
  </Step>

  <Step>
    Se estiver migrando 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>

## Breaking changes no v5.x

### Novo serviço Ledger disponível

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

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

**Valores padrão:**

| Configuração        | v4.x (antes) | v5.x (depois)                                                     |
| :------------------ | :----------- | :---------------------------------------------------------------- |
| ledger.enabled      | N/A          | false                                                             |
| onboarding.enabled  | true         | true (desabilitado automaticamente quando ledger está habilitado) |
| transaction.enabled | true         | true (desabilitado automaticamente quando ledger está habilitado) |

**Impacto ao habilitar o Ledger:**

* Os deployments `midaz-onboarding` e `midaz-transaction` serão removidos.
* Um novo deployment `midaz-ledger` será criado.
* Os ingresses redirecionarão automaticamente para o serviço Ledger (compatibilidade DNS mantida).
* Mudanças na estrutura de variáveis de ambiente e secrets (prefixos específicos de módulo).

### Atualização da versão do app

O Midaz foi atualizado para **v3.5.3**.

<Note>
  Confira o [changelog do app](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 valores para manter o comportamento atual:

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

  onboarding:
    enabled: true

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

Isso permite que você atualize a versão do chart sem alterar sua infraestrutura.

### Opção 2: executar todos os serviços simultaneamente (período de teste/migração)

Use a flag oculta `migration.allowAllServices` para executar todos 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>
  Este modo é destinado apenas para teste e migração. Não use em produção a 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 de atualizar**: Garanta que seus bancos de dados estejam prontos (mesmos bancos, novos nomes de variáveis de ambiente).
  </Step>

  <Step>
    **Atualizar secrets**: Crie novos secrets com prefixos específicos de módulo (veja a [Referência de Configuração](/pt/platform/helm/midaz/midaz-configuration-reference)).
  </Step>

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

  <Step>
    **Verificar**: Confirme que o serviço Ledger está saudável e os ingresses estão funcionando.
  </Step>
</Steps>

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

  onboarding:
    enabled: false

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

## Novas funcionalidades no 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:**

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

**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>
  Essas variáveis de ambiente foram renomeadas em versões posteriores. Os nomes atuais das variáveis são: `BALANCE_SYNC_BATCH_SIZE`, `BALANCE_SYNC_FLUSH_TIMEOUT_MS` e `BALANCE_SYNC_POLL_INTERVAL_MS`. Consulte a Referência de Configuração para os valores padrão atuais.
</Note>

### Redirecionamento de Ingress para o Ledger

Quando o Ledger está habilitado, os ingresses existentes redirecionam automaticamente o tráfego para o serviço Ledger, mantendo compatibilidade DNS.

| ledger.enabled | migration.allowAllServices | onboarding ingress target | transaction ingress target |
| :------------- | :------------------------- | :------------------------ | :------------------------- |
| false          | false (default)            | midaz-onboarding          | midaz-transaction          |
| true           | false (default)            | midaz-ledger              | midaz-ledger               |
| true           | true                       | midaz-onboarding          | midaz-transaction          |

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

O serviço CRM agora está disponível como um componente integrado, movendo-se do namespace `midaz-plugins` para o namespace `midaz`.

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

**Migração do plugin-crm:**

<Steps>
  <Step>
    Faça o 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 estiver usando bancos de dados separados).
  </Step>

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

  <Step>
    Remova o release antigo do plugin-crm do namespace midaz-plugins.
  </Step>
</Steps>

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

## Procedimento de rollback

<CodeGroup>
  ```bash Shell theme={null}
  # Listar histórico de releases
  helm history midaz -n midaz

  # Rollback para versão anterior
  helm rollback midaz <REVISION> -n midaz

  # Ou desabilitar explicitamente o 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

**Serviço Ledger falha ao iniciar**

* Verifique se todas as variáveis de ambiente e secrets específicos de módulo estão configurados com os novos prefixos (`DB_ONBOARDING_*`, `DB_TRANSACTION_*`, etc.).

**Ingress não roteando para o Ledger**

* Garanta que `ledger.enabled: true` e `migration.allowAllServices` não esteja definido como `true`.

**Secrets faltando após 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`