Guia de atualização do Helm para o Midaz

Este guia mostra como atualizar seu deployment Helm do Midaz para a linha atual do chart, v8.x. Você encontra um início rápido para operadores experientes, os releases com mudanças incompatíveis que não devem ser saltados às cegas, a atualização de plugins e as verificações posteriores.

Precisa revisar a instalação do Midaz com Helm? Confira o guia Instalando o Midaz com Helm antes de iniciar a atualização.

Início rápido

1. Verifique os pré-requisitos

Helm v3.8+ instalado e disponível (helm version) — necessário para suporte a registries OCI.
Cluster Kubernetes v1.20+ em execução.
Backup dos seus bancos de dados e do seu arquivo de values.

2. Identifique sua versão atual

helm list -n midaz

A coluna CHART mostra a versão do seu chart (por exemplo, midaz-helm-8.6.0).

3. Execute o comando de atualização

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <versao-alvo> \
  -n midaz \
  -f seus-values.yaml

4. Verifique a atualização

helm list -n midaz
kubectl get pods -n midaz

Compatibilidade de versões

Componente	Requisito
Kubernetes	1.20+
Helm	3.8+ (suporte OCI)
PostgreSQL	13+
MongoDB	4.4+
Valkey	7.x

O chart inclui PostgreSQL, MongoDB, RabbitMQ e Valkey como dependências de subcharts. Aponte o chart para as suas próprias instâncias gerenciadas desabilitando cada dependência (postgresql.enabled: false, e assim por diante) — veja Values de produção.

Releases com mudanças incompatíveis que você precisa considerar

Não salte várias versões maiores em um único helm upgrade. Leia a nota de atualização do release no repositório do chart (charts/midaz/docs/UPGRADE-*.md) para cada versão maior entre o seu chart atual e o seu alvo.

Release do chart	O que mudou
v5.0.0	Os componentes Console e NGINX foram removidos. Junto com eles saíram os templates da stack de observabilidade do Grafana.
v7.0.0	Os serviços `onboarding` e `transaction` foram removidos por completo — toda a funcionalidade foi consolidada no único serviço `ledger`. Os helpers de template dos serviços antigos não existem mais.
v8.4.0	O subchart `otel-collector-lerian` não é mais instalado. A chave apenas injeta variáveis de ambiente do OTEL e seu schema aceita somente `enabled`; chaves legadas (`external`, `extraEnvs`, `exporters`, `opentelemetry-collector`) agora falham na validação durante a atualização.

Se você ainda executa um chart v4.x ou v5.x, migre pelos caminhos em Visão geral das migrações em vez de atualizar direto para a v8.

Atualizando o core do Midaz

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

1. Consulte as versões disponíveis

Os charts são distribuídos apenas como artefatos OCI — não existe índice de repositório Helm para consultar, então helm search repo não funciona aqui. Explore as tags de release para descobrir versões e depois inspecione uma específica:

helm show chart oci://registry-1.docker.io/lerianstudio/midaz-helm --version <versao>

Ou navegue pelas tags de release:

Acesse https://github.com/LerianStudio/helm/tags
Filtre pelo prefixo midaz-v

2. Revise as mudanças antes de atualizar

Compare seus values atuais com os padrões do chart alvo:

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

Depois renderize a atualização sem aplicá-la:

helm template midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <versao-alvo> \
  -n midaz \
  -f seus-values.yaml

Uma violação de schema (por exemplo, uma chave legada de otel-collector-lerian) falha aqui, em vez de no meio da atualização.

3. Execute a atualização

helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
  --version <versao-alvo> \
  -n midaz \
  -f seus-values.yaml \
  --wait --timeout 10m

Passe sempre seus values com -f. Sem isso, o Helm não reaproveita nada da sua configuração anterior e o release volta aos padrões do chart.

4. Verifique a atualização

Verifique o status do release

helm list -n midaz

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

kubectl get pods -n midaz

Verifique os logs dos pods em busca de erros

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

Se você executa o CRM (crm.enabled: true — ele está desabilitado por padrão):

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

Todos os pods devem mostrar status Running e seus contêineres prontos.

midaz-ledger é o único Deployment de aplicação que o chart cria por padrão; midaz-crm é adicionado quando crm.enabled: true. midaz-onboarding e midaz-transaction não existem mais desde o chart v7.0.0.

Atualizando plugins

Atualize sempre o core do Midaz antes de atualizar os plugins. Os plugins dependem das APIs do core.

Os plugins são releases separados e são instalados no próprio namespace, midaz-plugins. Consulte as tags de release do próprio plugin em https://github.com/LerianStudio/helm/tags para saber a versão atual.

CRM

O CRM faz parte do chart do Midaz — não há um release de CRM separado para atualizar. Se você habilitá-lo (crm.enabled: true), verifique seus pods depois da atualização do core:

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

Fees Engine

helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
  --version <versao-alvo> \
  -n midaz-plugins \
  -f plugin-fees-values-backup.yaml

kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-fees

Pix

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

kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-br-pix-direct-jd

O chart rotula cada workload com o conjunto de labels app.kubernetes.io/*. Um seletor como -l app=midaz-crm não corresponde a nada.

Introdução

Midaz

Outros produtos

Guia de atualização do Helm para o Midaz

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

Releases com mudanças incompatíveis que você precisa considerar

Atualizando o core do Midaz

1. Consulte as versões disponíveis

2. Revise as mudanças antes de atualizar

3. Execute a atualização

4. Verifique a atualização

Atualizando plugins

CRM

Fees Engine

Pix

​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

​Releases com mudanças incompatíveis que você precisa considerar

​Atualizando o core do Midaz

​1. Consulte as versões disponíveis

​2. Revise as mudanças antes de atualizar

​3. Execute a atualização

​4. Verifique a atualização

​Atualizando plugins

​CRM

​Fees Engine

​Pix

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

Releases com mudanças incompatíveis que você precisa considerar

Atualizando o core do Midaz

1. Consulte as versões disponíveis

2. Revise as mudanças antes de atualizar

3. Execute a atualização

4. Verifique a atualização

Atualizando plugins

CRM

Fees Engine

Pix