Atualizando o Helm

Este guia orienta você na atualização do seu deployment Midaz via Helm para a versão mais recente (v5.x.x). Você encontrará um início rápido para operadores experientes, seguido de caminhos de migração a partir de versões anteriores, breaking changes detalhadas e verificações pós-atualização.

Precisa revisar a instalação do Midaz com Helm? Confira o guia Usando o Helm em Estratégias de deployment antes de iniciar sua atualização.

Início Rápido

1. Verifique os pré-requisitos

Helm v3.8+ instalado e disponível (helm version).
Kubernetes v1.20+ cluster em execução.
Backup sua instalação existente.

2. Identifique sua versão atual

helm list -n midaz

3. Execute o comando de atualização

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

4. Verifique a atualização

helm list -n midaz
kubectl get pods -n midaz

Compatibilidade de Versões

Component	v3.x	v4.x	v5.x
Kubernetes	1.20+	1.20+	1.20+
Helm	3.8+	3.8+	3.8+
PostgreSQL	13+	13+	13+
MongoDB	4.4+	4.4+	4.4+
Valkey	7.x	7.x	7.x

Escolha seu caminho de migração

Selecione a versão atual do seu Helm chart para ver os passos de migração relevantes:

v4.x → v5.x
v3.x → v4.x
v3.x → v5.x

Migrando de v4.x para v5.x

Checklist pré-atualização

Faça backup dos releases Helm existentes:

helm get values -n midaz midaz > midaz-v4-backup.yaml

Decisão necessária: Escolha sua estratégia de deployment (serviço Ledger ou legado Onboarding/Transaction).

Se estiver migrando para o serviço Ledger, prepare novos secrets com prefixos específicos de módulo.

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çã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.1.

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:

Antes de atualizar: Garanta que seus bancos de dados estejam prontos (mesmos bancos, novos nomes de variáveis de ambiente).

Atualizar secrets: Crie novos secrets com prefixos específicos de módulo (veja a Referência de Configuração do Ledger abaixo).

Atualizar: Execute helm upgrade com a nova versão do chart.

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"

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.

Para mais detalhes, consulte a Documentação do CRM.

Migração do plugin-crm:

Faça o deploy do novo CRM no namespace midaz:

crm:
  enabled: true
  configmap:
    MONGO_HOST: "midaz-mongodb"
    MONGO_NAME: "crm"

Migre seus dados do MongoDB antigo para o novo (se estiver usando bancos de dados separados).

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

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

Migrando de v3.x para v4.x

Checklist pré-atualização

Faça backup dos releases Helm existentes:

helm get values -n midaz midaz > midaz-v3-backup.yaml

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

Agende uma janela de manutenção.

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.

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.

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:

rabbitmq:
  authentication:
    erlangCookie:
      value: "<32+ printable characters without spaces>"

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.

Atualização da versão do app

O Midaz foi atualizado para v3.3.1.

Confira o changelog do app para a lista completa de mudanças.

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:

postgresql:
  image:
    tag: "16.2.0"

mongodb:
  image:
    tag: "7.0.5"

valkey:
  image:
    tag: "7.2.4"

Imagem oficial NGINX para Microfrontends

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

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

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:

Comando de atualização

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm --version 4.0.0 -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

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.

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.

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

Faça backup dos releases Helm existentes:

helm get values -n midaz midaz > midaz-v3-backup.yaml

Crítico: Faça backup dos dados e definições do RabbitMQ (breaking change do v4.x).

Decisão necessária: Escolha sua estratégia de deployment - serviço Ledger ou legado Onboarding/Transaction (breaking change do v5.x).

Se estiver migrando para o serviço Ledger, prepare novos secrets com prefixos específicos de módulo.

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ça	Versão de Origem	Impacto
RabbitMQ Groundhog2k	v4.x	Requer cookie Erlang, possível perda de dados PVC
BitnamiSecure images	v4.x	PostgreSQL, MongoDB, Valkey usam imagens hardened
Official NGINX	v4.x	Revisar configurações NGINX customizadas
Ledger service	v5.x	Novo serviço unificado (opcional mas recomendado)
CRM integration	v5.x	Move do namespace midaz-plugins para midaz

Referência de configuração do serviço Ledger

O serviço Ledger usa configurações de banco de dados específicas por módulo:

ledger:
  enabled: false
  name: "ledger"
  replicaCount: 1

  image:
    repository: lerianstudio/midaz-ledger
    tag: ""  # Defaults to Chart.AppVersion
    pullPolicy: IfNotPresent

  configmap:
    # App Configuration
    ENV_NAME: "production"
    LOG_LEVEL: "debug"
    SERVER_PORT: "3000"
    SERVER_ADDRESS: ":3000"

    # Auth Configuration
    PLUGIN_AUTH_ENABLED: "false"
    PLUGIN_AUTH_HOST: ""

    # Accounting Configuration
    ACCOUNT_TYPE_VALIDATION: ""
    TRANSACTION_ROUTE_VALIDATION: ""

    # PostgreSQL - Onboarding Module
    DB_ONBOARDING_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_ONBOARDING_USER: "midaz"
    DB_ONBOARDING_NAME: "onboarding"
    DB_ONBOARDING_PORT: "5432"
    DB_ONBOARDING_SSLMODE: "disable"
    DB_ONBOARDING_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # PostgreSQL - Transaction Module
    DB_TRANSACTION_HOST: "midaz-postgresql-primary.midaz.svc.cluster.local."
    DB_TRANSACTION_USER: "midaz"
    DB_TRANSACTION_NAME: "transaction"
    DB_TRANSACTION_PORT: "5432"
    DB_TRANSACTION_SSLMODE: "disable"
    DB_TRANSACTION_REPLICA_HOST: "midaz-postgresql-replication.midaz.svc.cluster.local."

    # MongoDB - Onboarding Module
    MONGO_ONBOARDING_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_ONBOARDING_NAME: "onboarding"
    MONGO_ONBOARDING_USER: "midaz"
    MONGO_ONBOARDING_PORT: "27017"

    # MongoDB - Transaction Module
    MONGO_TRANSACTION_HOST: "midaz-mongodb.midaz.svc.cluster.local."
    MONGO_TRANSACTION_NAME: "transaction"
    MONGO_TRANSACTION_USER: "midaz"
    MONGO_TRANSACTION_PORT: "27017"

    # Redis (shared)
    REDIS_HOST: "midaz-valkey-primary.midaz.svc.cluster.local.:6379"

    # RabbitMQ (shared)
    RABBITMQ_HOST: "midaz-rabbitmq.midaz.svc.cluster.local."

    # Balance Sync Worker
    BALANCE_SYNC_WORKER_ENABLED: "false"
    BALANCE_SYNC_MAX_WORKERS: "5"

  secrets:
    # Onboarding Module
    DB_ONBOARDING_PASSWORD: ""
    DB_ONBOARDING_REPLICA_PASSWORD: ""
    MONGO_ONBOARDING_PASSWORD: ""

    # Transaction Module
    DB_TRANSACTION_PASSWORD: ""
    DB_TRANSACTION_REPLICA_PASSWORD: ""
    MONGO_TRANSACTION_PASSWORD: ""

    # Shared
    REDIS_PASSWORD: ""
    RABBITMQ_DEFAULT_PASS: ""
    RABBITMQ_CONSUMER_PASS: ""

Suporte a secrets externos

ledger:
  useExistingSecret: true
  existingSecretName: <existing-secret-name>

Referência de flags de deployment

Flag	Padrão	Descrição
ledger.enabled	false	Habilita o serviço Ledger unificado
onboarding.enabled	true	Enables onboarding (desabilitado automaticamente quando ledger está habilitado)
transaction.enabled	true	Enables transaction (desabilitado automaticamente quando ledger está habilitado)
migration.allowAllServices	false	Flag oculta para permitir todos os serviços simultaneamente

Recomendação para produção

Não recomendamos usar as dependências padrão do Helm chart do Midaz (bancos de dados, cache e message broker) em ambientes de produção. Para deployments de nível produtivo, siga nossas boas práticas para operar essas dependências com segurança adequada, observabilidade, backups, recuperação de desastres e SLOs.

Verificação pós-atualização

1. Verificar status dos pods

kubectl get pods -n midaz

Todos os pods devem estar Running e READY.

2. Verificar serviços

kubectl get svc -n midaz

3. Verificar os logs

# Se estiver usando o serviço Ledger (v5.x)
kubectl logs -n midaz deployment/midaz-ledger

# Se estiver usando serviços legado
kubectl logs -n midaz deployment/midaz-onboarding
kubectl logs -n midaz deployment/midaz-transaction

# Verificar logs do RabbitMQ (importante para atualizações v4.x+)
kubectl logs -n midaz statefulset/midaz-rabbitmq

# Verificar logs do CRM (se habilitado)
kubectl logs -n midaz deployment/midaz-crm

4. Verificar roteamento de ingress (v5.x com Ledger)

kubectl get ingress -n midaz
kubectl describe ingress midaz-onboarding -n midaz
kubectl describe ingress midaz-transaction -n midaz

Procedimento geral de rollback

Se encontrar problemas após qualquer atualização:

# Listar histórico de releases
helm history midaz -n midaz

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

# Verificar rollback
helm list -n midaz
kubectl get pods -n midaz

Primeiros passos

Entendendo o Midaz

Instalação e implantação

Trabalhando com o Midaz

Boas práticas

SDKs e bibliotecas

Ajuda e suporte

​Início Rápido

​1. Verifique os pré-requisitos

​2. Identifique sua versão atual

​3. Execute o comando de atualização

​4. Verifique a atualização

​Compatibilidade de Versões

​Escolha seu caminho de migração

​Migrando de v4.x para v5.x

​Checklist pré-atualização

​Breaking changes no v5.x

​Novo serviço Ledger disponível

​Atualização da versão do app

​Opções de migração

​Opção 1: Continuar usando Onboarding e Transaction (migração gradual)

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

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

​Novas funcionalidades no v5.x

​Serviço Ledger unificado

​Redirecionamento de Ingress para o Ledger

​Integração do serviço CRM

​Comando de atualização

​Procedimento de rollback

​Problemas comuns

​Migrando de v3.x para v4.x

​Checklist pré-atualização

​Breaking changes no v4.x

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

​Atualização da versão do app

​Novas funcionalidades no v4.x

​Imagens BitnamiSecure para serviços de dados core

​Imagem oficial NGINX para Microfrontends

​Por que mudamos as dependências do Bitnami

​Comando de atualização

​Procedimento de rollback

​Problemas comuns

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

​Checklist pré-atualização

​Breaking changes a serem tratadas

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

​Do v5.x: Novo serviço Ledger

​Comando de atualização

​O que muda a partir do v3.x

​Referência de configuração do serviço Ledger

​Suporte a secrets externos

​Referência de flags de deployment

​Recomendação para produção

​Verificação pós-atualização

​1. Verificar status dos pods

​2. Verificar serviços

​3. Verificar os logs

​4. Verificar roteamento de ingress (v5.x com Ledger)

​Procedimento geral de rollback

Início Rápido

1. Verifique os pré-requisitos

2. Identifique sua versão atual

3. Execute o comando de atualização

4. Verifique a atualização

Compatibilidade de Versões

Escolha seu caminho de migração

Migrando de v4.x para v5.x

Checklist pré-atualização

Breaking changes no v5.x

Novo serviço Ledger disponível

Atualização da versão do app

Opções de migração

Opção 1: Continuar usando Onboarding e Transaction (migração gradual)

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

Opção 3: Migrar para o Ledger (recomendado)

Novas funcionalidades no v5.x

Serviço Ledger unificado

Redirecionamento de Ingress para o Ledger

Integração do serviço CRM

Comando de atualização

Procedimento de rollback

Problemas comuns

Migrando de v3.x para v4.x

Checklist pré-atualização

Breaking changes no v4.x

Mudança da dependência do RabbitMQ para Groundhog2k

Atualização da versão do app

Novas funcionalidades no v4.x

Imagens BitnamiSecure para serviços de dados core

Imagem oficial NGINX para Microfrontends

Por que mudamos as dependências do Bitnami

Comando de atualização

Procedimento de rollback

Problemas comuns

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

Checklist pré-atualização

Breaking changes a serem tratadas

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

Do v5.x: Novo serviço Ledger

Comando de atualização

O que muda a partir do v3.x

Referência de configuração do serviço Ledger

Suporte a secrets externos

Referência de flags de deployment

Recomendação para produção

Verificação pós-atualização

1. Verificar status dos pods

2. Verificar serviços

3. Verificar os logs

4. Verificar roteamento de ingress (v5.x com Ledger)

Procedimento geral de rollback