Pular para o conteúdo principal

​
Migrando de v3.x para v5.x (pulando v4.x)

Se você está atualizando diretamente de v3.x para v5.x, precisa lidar com as breaking changes de ambas as versões.

​
Checklist pré-atualização

1
Faça backup dos releases Helm existentes:
helm get values -n midaz midaz > midaz-v3-backup.yaml
2
Crítico: Faça backup dos dados e definições do RabbitMQ (breaking change do v4.x).
3
Decisão necessária: Escolha sua estratégia de deployment - serviço Ledger ou legado Onboarding/Transaction (breaking change do v5.x).
4
Se estiver migrando para o serviço Ledger, prepare novos secrets com prefixos específicos de módulo.
5
Agende uma janela de manutenção.

​
Breaking changes a serem tratadas

​
Do v4.x: mudança da dependência do RabbitMQ

A dependência do chart RabbitMQ mudou de Bitnami para Groundhog2k. Isso pode levar à perda de dados PVC. Faça backup dos dados do RabbitMQ antes de atualizar.
Configuração obrigatória: 
rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ printable characters without spaces>"

​
Do v5.x: novo serviço Ledger

O serviço Ledger unificado está disponível e se tornará obrigatório em um release futuro. Planeje sua estratégia de migração.
Escolha uma destas configurações: Opção A: Manter serviços legado (migração gradual) 
ledger:
  enabled: false

onboarding:
  enabled: true

transaction:
  enabled: true

rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ printable characters>"
Opção B: Migrar para o Ledger (recomendado) 
ledger:
  enabled: true

onboarding:
  enabled: false

transaction:
  enabled: false

rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ printable characters>"
Se estiver usando 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 atualização

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.x.x -n midaz

​
O que muda a partir do v3.x

MudançaVersão de OrigemImpacto
RabbitMQ Groundhog2kv4.xRequer cookie Erlang, possível perda de dados PVC
BitnamiSecure imagesv4.xPostgreSQL, MongoDB, Valkey usam imagens hardened
Official NGINXv4.xRevisar configurações NGINX customizadas
Ledger servicev5.xNovo serviço unificado (opcional mas recomendado)
CRM integrationv5.xMove do namespace midaz-plugins para midaz

​
Problemas comuns

RabbitMQ falha ao iniciar
  • Certifique-se de 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 da v4.x de Bitnami para Groundhog2k. Exporte as definições do RabbitMQ antes de atualizar e restaure depois.
O serviço Ledger falha ao iniciar
  • Verifique se todas as variáveis de ambiente e secrets específicas de módulo estão configuradas com os novos prefixos (DB_ONBOARDING_*, DB_TRANSACTION_*, etc.).
Ingress não roteando para o Ledger
  • Certifique-se de 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
Problemas de configuração do NGINX
  • A atualização da v4.x substituiu o Bitnami NGINX por templates oficiais do NGINX. Revise os novos templates em templates/console/ e atualize seus overrides.