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

> Migre seu deploy Helm do Midaz de v3.x para v4.x — trate breaking changes, mapeamentos de configuração e verificação pós-upgrade.

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

  <Step>
    **Crítico**: Faça backup dos dados e definições do RabbitMQ antes de atualizar.
  </Step>

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

## Breaking changes no v4.x

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

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

<Danger>
  Esta mudança pode levar à **perda de dados do PersistentVolumeClaim (PVC)** ao atualizar instalações existentes porque o StatefulSet subjacente, montagens de volume e configuração diferem da dependência anterior.
</Danger>

**Notas importantes:**

* O chart Groundhog2k **requer um cookie Erlang válido**. Defina `rabbitmq.authentication.erlangCookie.value` para uma string imprimível de 32+ caracteres sem espaços. Se estiver ausente ou vazio, o RabbitMQ falhará ao iniciar.
* Se você precisa preservar dados existentes, faça backup e planeje uma migração controlada de PVCs e definições antes de atualizar.

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

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

<Note>
  Esta breaking change afeta apenas deployments que usam o RabbitMQ padrão do chart (`rabbitmq.enabled: true`). Se você usa um RabbitMQ externo ou gerenciado, não é afetado.
</Note>

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

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

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

## Novas funcionalidades no v4.x

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

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

| Service    | Fonte da Imagem | Tag    |
| :--------- | :-------------- | :----- |
| PostgreSQL | BitnamiSecure   | latest |
| MongoDB    | BitnamiSecure   | latest |
| Valkey     | BitnamiSecure   | latest |

Se você precisa fixar uma versão específica, sobrescreva a tag no `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 NGINX para microfrontends

A dependência anterior do Bitnami NGINX foi substituída por um template interno baseado na imagem oficial `nginx`.

<Note>
  Se você personalizou anteriormente a configuração NGINX baseada em Bitnami, revise os novos templates em `templates/console/` e ajuste seus valores adequadamente.
</Note>

## Por que mudamos as dependências do Bitnami

Nos afastamos das dependências do Bitnami devido a mudanças de política que impactavam estabilidade e operações. Para mais contexto, veja:

* [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 atualização

<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}
  # Listar histórico de releases
  helm history midaz -n midaz

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

<Warning>
  Devido à mudança de dependência do RabbitMQ, o rollback pode exigir intervenção manual para restaurar PVCs e dados. Garanta que você tenha backups antes de atualizar.
</Warning>

## Problemas comuns

**RabbitMQ falha ao iniciar**

* Garanta que o cookie Erlang esteja configurado corretamente (32+ caracteres imprimíveis, sem espaços).

**Perda de dados PVC do RabbitMQ**

* Isso é esperado devido à mudança de dependência. Exporte as definições do RabbitMQ antes de atualizar e restaure depois.

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

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