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

> Migre seu deploy Helm do Midaz da v3.x para a v4.x: trate as mudanças incompatíveis, os mapeamentos de configuração e a verificação depois do upgrade.

## 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 antes do upgrade.
  </Step>

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

## Mudanças incompatíveis na v4.x

### Mudança da dependência RabbitMQ para Groundhog2k

A dependência de chart do RabbitMQ mudou de Bitnami para [Groundhog2k](https://Groundhog2k.github.io/helm-charts).

<Danger>
  Essa mudança pode causar **perda de dados de PersistentVolumeClaim (PVC)** ao fazer upgrade de instalações existentes, porque o StatefulSet, os volume mounts e a configuração subjacentes são diferentes da dependência anterior.
</Danger>

**Notas importantes:**

* O chart Groundhog2k **exige um Erlang cookie válido**. Defina `rabbitmq.authentication.erlangCookie.value` como um texto imprimível de 32+ caracteres sem espaços. Se estiver ausente ou vazio, o RabbitMQ não inicia.
* Se você precisa preservar dados existentes, faça backup e planeje uma migração controlada dos PVCs e das definições antes do upgrade.

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

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

<Note>
  Essa mudança incompatível afeta apenas deploys que usam o RabbitMQ padrão do chart (`rabbitmq.enabled: true`). Se você roda um RabbitMQ externo ou gerenciado, não é afetado.
</Note>

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

O Midaz passa para a **v3.3.1**.

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

## Novos recursos na v4.x

### Imagens BitnamiSecure para os serviços de dados principais

As imagens padrão dos serviços de dados principais agora usam os repositórios BitnamiSecure com a tag `latest`:

| Serviço    | Origem da imagem | Tag    |
| :--------- | :--------------- | :----- |
| PostgreSQL | BitnamiSecure    | latest |
| MongoDB    | BitnamiSecure    | latest |
| Valkey     | BitnamiSecure    | latest |

Se você precisa fixar uma versão específica, sobrescreva a tag em `values.yaml`:

<CodeGroup>
  ```yaml values.yaml theme={null}
  postgresql:
    image:
      tag: "16.2.0"

  mongodb:
    image:
      tag: "7.0.5"

  valkey:
    image:
      tag: "7.2.4"
  ```
</CodeGroup>

### Imagem oficial do NGINX para os microfrontends

O chart substituiu a dependência NGINX da Bitnami por um template interno baseado na imagem `nginx` oficial.

<Note>
  Se você tinha customizado a configuração do NGINX baseada na Bitnami, revise os novos templates em `templates/console/` e ajuste seus values conforme necessário.
</Note>

## Por que mudamos as dependências Bitnami

Saímos das dependências Bitnami por causa de mudanças de política que afetam a estabilidade e a operação. Para mais contexto, consulte:

* [bitnami/charts#36215](https://github.com/bitnami/charts/issues/36215)
* [bitnami/containers#86191](https://github.com/bitnami/containers/issues/86191)
* [bitnami/containers#83267](https://github.com/bitnami/containers/issues/83267)

## Comando de upgrade

<CodeGroup>
  ```bash Shell theme={null}
  helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 4.0.0 -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
  ```
</CodeGroup>

<Warning>
  Por causa da mudança na dependência do RabbitMQ, o rollback pode exigir intervenção manual para restaurar PVCs e dados. Garanta que você tem backups antes do upgrade.
</Warning>

## 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. Exporte as definições do RabbitMQ antes do upgrade e restaure depois.

**Problemas de configuração do NGINX**

* Revise os novos templates do NGINX em `templates/console/` e atualize seus overrides.