Atualizando o Midaz e plugins via Helm

Este guia cobre como atualizar o Midaz e seus plugins usando Helm. Seja aplicando um patch, atualização minor ou migrando entre versões major, siga estes procedimentos para garantir uma atualização tranquila.

Atualizando entre versões major do Helm chart? Confira o guia Atualizando o Helm para breaking changes e passos de migração entre v3.x, v4.x e v5.x.

Pré-requisitos

Antes de iniciar qualquer atualização, certifique-se de ter:

Helm CLI v3.8+ instalado (guia de instalação)
kubectl configurado com acesso ao seu cluster
Cluster admin permissões ou roles RBAC apropriados
Acesso à tabela de compatibilidade de versões

A compatibilidade de versões entre Helm charts e aplicações é definida pela matriz de compatibilidade oficial mantida no Helm repository README.Esta matriz é atualizada automaticamente em cada release de aplicação e deve sempre ser consultada antes de atualizar.

Verifique suas ferramentas

Execute os seguintes comandos para verificar suas ferramentas:

Verificar versão do Helm

helm version

Verificar acesso ao kubectl

kubectl cluster-info

Checklist pré-atualização

Verificar versões atuais

Revise as versões do seu deployment atual:

Listar releases do Helm

helm list -n midaz

Verificar pods em execução

kubectl get pods -n midaz -o wide

Revisar compatibilidade da versão alvo

Consulte a tabela de compatibilidade de versões para garantir que a versão alvo é compatível com seus plugins e infraestrutura.

Backup dos valores atuais

Salve seus valores atuais do Helm para referência e possível rollback:

Backup dos valores do Midaz

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

Backup dos valores de plugins (exemplo: CRM)

helm get values plugin-crm -n midaz > plugin-crm-values-backup.yaml

Revisar notas de release

Confira o repositório Helm para notas de release e breaking changes na versão alvo.

Agendar janela de manutenção

Coordene com sua equipe e agende uma janela de manutenção apropriada para a atualização.

Garantir backups do banco de dados

Garantir backups do banco de dados are in place before upgrading, especially for major versions.

Em casos específicos, como determinados releases de hotfix, uma atualização do Helm chart pode não ser necessária.Sempre verifique as notas de release antes de pular uma atualização do Helm.

Atualizando o Midaz Core

Ao atualizar o Midaz ou qualquer plugin, sempre atualize o Helm chart correspondente.Atualizar versões de aplicação sem atualizar o Helm chart pode causar falhas no deployment ou ambientes inconsistentes.

1. Verificar versões disponíveis

Liste as versões de chart disponíveis no registro OCI:

Listar versões disponíveis

helm search repo lerianstudio/midaz-helm --versions

ou confira as tags no GitHub:
- Visit https://github.com/LerianStudio/helm/tags
- Filtre pelo prefixo “midaz-v”

2. Revisar mudanças (opcional)

Compare seus valores atuais com os valores padrão do novo chart:

helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.3.0 > new-defaults.yaml

3. Executar a atualização

Atualize para a versão alvo:

Atualizar com valores existentes

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 5.3.0 \
  -n midaz \
  -f midaz-values-backup.yaml

Atualizar com novos valores

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version 5.3.0 \
  -n midaz \
  -f my-custom-values.yaml

Se você tem valores customizados, sempre passe-os com -f para evitar perder sua configuração durante a atualização.

4. Verificar a atualização

Verificar status do release

helm list -n midaz

Verificar se os pods estão em execução

kubectl get pods -n midaz

Verificar logs dos pods por erros

Ledger (v5.x)
Legacy (v4.x)

kubectl logs -n midaz deployment/midaz-ledger --tail=50
kubectl logs -n midaz deployment/midaz-crm --tail=50

kubectl logs -n midaz deployment/midaz-onboarding --tail=50
kubectl logs -n midaz deployment/midaz-transaction --tail=50

Todos os pods devem mostrar status Running e estado READY.

Atualizando plugins

Sempre atualize o Midaz Core antes de atualizar plugins. Os plugins dependem das APIs do Midaz Core.

CRM

A partir do Midaz v5.x, o CRM está integrado ao Helm chart principal do Midaz. O chart standalone plugin-crm só é necessário para deployments v4.x.

Integrated (v5.x)
Standalone (v4.x)

O CRM está incluído no chart principal do Midaz. Nenhuma atualização separada é necessária.

Verificar pods do CRM

kubectl get pods -n midaz -l app=midaz-crm

Atualizar plugin CRM

helm upgrade plugin-crm oci://registry-1.docker.io/lerianstudio/plugin-crm \
  --version 4.0.0 \
  -n midaz \
  -f plugin-crm-values-backup.yaml

Verificar pods do CRM

kubectl get pods -n midaz -l app=plugin-crm

Fees Engine

Atualizar plugin Fees Engine

helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees \
  --version 3.5.1 \
  -n midaz \
  -f plugin-fees-values-backup.yaml

Verificar pods do Fees Engine

kubectl get pods -n midaz -l app=plugin-fees

Pix

O plugin Pix ainda está em desenvolvimento.

Atualizar plugin Pix

helm upgrade plugin-pix oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd \
  --version 1.2.6 \
  -n midaz \
  -f plugin-pix-values-backup.yaml

Verificar pods do Pix

kubectl get pods -n midaz -l app=plugin-pix

Boas práticas

Ordem de atualização

Sempre atualize nesta ordem:

Infraestrutura (se necessário)
Midaz Core
Plugins (um por vez)

Teste primeiro

Sempre teste atualizações em um ambiente de staging que espelhe produção antes de aplicar em produção.

Monitore de perto

Monitore logs e métricas de perto nos primeiros 15-30 minutos após uma atualização.

Mantenha backups

Mantenha backups dos seus valores do Helm e banco de dados antes de atualizações major.

Resumo do checklist de atualização

Passo	Comando	Verificado
Backup dos valores	`helm get values <release> -n midaz > backup.yaml`
Verificar compatibilidade	Revisar tabela de compatibilidade
Atualizar Midaz	`helm upgrade midaz ...`
Verificar pods do Midaz	`kubectl get pods -n midaz`
Atualizar plugins	`helm upgrade <plugin> ...`
Verificar pods dos plugins	`kubectl get pods -n midaz`
Verificar logs	`kubectl logs -n midaz deployment/<name>`

Procedimentos de rollback

Se algo der errado após uma atualização, você pode fazer rollback para uma versão anterior.

Quando fazer rollback

Considere fazer rollback se você observar:

Pods falhando ao iniciar ou em crash-loop
Erros de API ou indisponibilidade de serviços
Inconsistências de dados
Degradação de desempenho

Verificar histórico de releases

Visualize o histórico de revisões de um release:

helm history midaz -n midaz

Exemplo de saída:

REVISION  STATUS      CHART           APP VERSION  DESCRIPTION
1         superseded  midaz-4.4.8     3.4.7        Install complete
2         deployed    midaz-5.3.0     3.5.1        Upgrade complete

Executar rollback

Faça rollback para uma revisão específica:

Rollback do Midaz para revisão anterior

helm rollback midaz 1 -n midaz

Rollback de plugin (exemplo: CRM)

helm rollback plugin-crm 1 -n midaz

Verificar rollback

Verificar versão do release

helm list -n midaz

Verificar pods

kubectl get pods -n midaz

Verificar logs

Ledger (v5.x)
Legacy (v4.x)

kubectl logs -n midaz deployment/midaz-ledger --tail=50

kubectl logs -n midaz deployment/midaz-onboarding --tail=50

Rollbacks podem não reverter mudanças no schema do banco de dados. Se a atualização incluiu migrações de banco de dados, pode ser necessário restaurar a partir de um backup do banco.

Solução de problemas

Pods presos no estado Pending

Sintoma: Pods permanecem no status Pending após a atualização. Solução: Verifique restrições de recursos:

Descrever pod pendente

kubectl describe pod <pod-name> -n midaz

Verificar recursos dos nodes

kubectl top nodes

Erros de pull de imagem

Sintoma: Pods mostram ImagePullBackOff ou ErrImagePull. Solução: Verifique o acesso ao registro de imagens e credenciais:

Verificar eventos do pod

kubectl describe pod <pod-name> -n midaz | grep -A 10 Events

Verificar se a imagem existe

docker pull lerianstudio/midaz-ledger:3.5.1

Erros de configuração

Sintoma: Pods falham com erros relacionados a configuração nos logs. Solução: Compare seus valores com os padrões novos:

Visualizar valores atuais

helm get values midaz -n midaz

Visualizar padrões do chart

helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version 5.3.0

Problemas de conexão com banco de dados

Sintoma: Serviços falham ao conectar ao PostgreSQL ou MongoDB. Solução: Verifique a conectividade e credenciais do banco de dados:

Verificar pods do banco de dados

kubectl get pods -n midaz -l app.kubernetes.io/name=postgresql
kubectl get pods -n midaz -l app.kubernetes.io/name=mongodb

Verificar logs do serviço

Ledger (v5.x)
Legacy (v4.x)

kubectl logs -n midaz deployment/midaz-ledger | grep -i database

kubectl logs -n midaz deployment/midaz-onboarding | grep -i database

Recursos relacionados

Deploy do Midaz usando Helm - Guia de instalação inicial
Atualizando o Helm - Breaking changes e caminhos de migração entre versões major
Compatibilidade de versões - Referência de mapeamento de versões
Repositório Helm - Código-fonte e notas de release

Primeiros passos

Entendendo o Midaz

Instalação e implantação

Trabalhando com o Midaz

Boas práticas

SDKs e bibliotecas

Ajuda e suporte

Atualizando o Midaz e plugins via Helm

Pré-requisitos

Verifique suas ferramentas

Checklist pré-atualização

Atualizando o Midaz Core

1. Verificar versões disponíveis

2. Revisar mudanças (opcional)

3. Executar a atualização

4. Verificar a atualização

Atualizando plugins

CRM

Fees Engine

Pix

Boas práticas

Ordem de atualização

Teste primeiro

Monitore de perto

Mantenha backups

Resumo do checklist de atualização

Procedimentos de rollback

Quando fazer rollback

Verificar histórico de releases

Executar rollback

Verificar rollback

Solução de problemas

Pods presos no estado Pending

Erros de pull de imagem

Erros de configuração

Problemas de conexão com banco de dados

Recursos relacionados

Primeiros passos

Entendendo o Midaz

Instalação e implantação

Trabalhando com o Midaz

Boas práticas

SDKs e bibliotecas

Ajuda e suporte

​Pré-requisitos

​Verifique suas ferramentas

​Checklist pré-atualização

​Atualizando o Midaz Core

​1. Verificar versões disponíveis

​2. Revisar mudanças (opcional)

​3. Executar a atualização

​4. Verificar a atualização

​Atualizando plugins

​CRM

​Fees Engine

​Pix

​Boas práticas

​Ordem de atualização

​Teste primeiro

​Monitore de perto

​Mantenha backups

​Resumo do checklist de atualização

​Procedimentos de rollback

​Quando fazer rollback

​Verificar histórico de releases

​Executar rollback

​Verificar rollback

​Solução de problemas

​Pods presos no estado Pending

​Erros de pull de imagem

​Erros de configuração

​Problemas de conexão com banco de dados

​Recursos relacionados

Pré-requisitos

Verifique suas ferramentas

Checklist pré-atualização

Atualizando o Midaz Core

1. Verificar versões disponíveis

2. Revisar mudanças (opcional)

3. Executar a atualização

4. Verificar a atualização

Atualizando plugins

CRM

Fees Engine

Pix

Boas práticas

Ordem de atualização

Teste primeiro

Monitore de perto

Mantenha backups

Resumo do checklist de atualização

Procedimentos de rollback

Quando fazer rollback

Verificar histórico de releases

Executar rollback

Verificar rollback

Solução de problemas

Pods presos no estado Pending

Erros de pull de imagem

Erros de configuração

Problemas de conexão com banco de dados

Recursos relacionados