Pular para o conteúdo principal

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.

​
Migrando de v4.x para v5.x

​
Checklist pré-atualização

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

​
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.
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.
Valores padrão:
Configuraçãov4.x (antes)v5.x (depois)
ledger.enabledN/Afalse
onboarding.enabledtruetrue (desabilitado automaticamente quando ledger está habilitado)
transaction.enabledtruetrue (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.
Confira o changelog do app para a lista completa de mudanças.

​
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: 
ledger:
  enabled: false

onboarding:
  enabled: true

transaction:
  enabled: true
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: 
ledger:
  enabled: true

onboarding:
  enabled: true

transaction:
  enabled: true

migration:
  allowAllServices: true
Este modo é destinado apenas para teste e migração. Não use em produção a longo prazo.

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

Aceite a nova arquitetura e migre para o serviço Ledger unificado:
1
Antes de atualizar: Garanta que seus bancos de dados estejam prontos (mesmos bancos, novos nomes de variáveis de ambiente).
2
Atualizar secrets: Crie novos secrets com prefixos específicos de módulo (veja a Referência de Configuração).
3
Atualizar: Execute helm upgrade com a nova versão do chart.
4
Verificar: Confirme que o serviço Ledger está saudável e os ingresses estão funcionando.
ledger:
  enabled: true

onboarding:
  enabled: false

transaction:
  enabled: false

​
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: 
# Balance Sync Worker
BALANCE_SYNC_WORKER_ENABLED: "false"
BALANCE_SYNC_MAX_WORKERS: "5"
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.

​
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.enabledmigration.allowAllServicesonboarding ingress targettransaction ingress target
falsefalse (default)midaz-onboardingmidaz-transaction
truefalse (default)midaz-ledgermidaz-ledger
truetruemidaz-onboardingmidaz-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.
Para mais detalhes, consulte a Documentação do CRM.
Migração do plugin-crm:
1
Faça o deploy do novo CRM no namespace midaz:
crm:
  enabled: true
  configmap:
    MONGO_HOST: "midaz-mongodb"
    MONGO_NAME: "crm"
2
Migre seus dados do MongoDB antigo para o novo (se estiver usando bancos de dados separados).
3
Atualize seu ingress/DNS para apontar para o novo serviço CRM.
4
Remova o release antigo do plugin-crm do namespace midaz-plugins.

​
Comando de atualização

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

​
Procedimento de rollback

# 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

​
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