Guia de upgrade do Midaz via Helm

As orientações de CRM e Fees marcadas como legado nesta página valem apenas para releases legados que já existem. O Midaz v4 faz o deploy do Ledger unificado e serve CRM e Fees em /v2.

O repositório Helm mantém uma carga de trabalho crm.enabled e o chart plugin-fees-helm para releases de aplicação mais antigos. Essas são superfícies de compatibilidade com o legado, não o modelo de deploy do Midaz v4. Este guia mostra como fazer o upgrade do seu deploy Helm do Midaz para a linha de chart atual.

Para relembrar como instalar o Midaz com Helm, veja o guia Instalando o Midaz com Helm antes de começar o seu upgrade.

Início rápido

1. Confira os pré-requisitos

Helm v3.8+ instalado e disponível (helm version), necessário para o suporte a registry OCI.
Backup dos seus bancos de dados e do seu arquivo de values.

2. Identifique a sua versão atual

helm list -n midaz

A coluna CHART mostra a sua versão de chart, no formato midaz-helm-<version>.

3. Rode o comando de upgrade

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

4. Verifique o upgrade

helm list -n midaz
kubectl get pods -n midaz

Compatibilidade de versões

Componente	Requisito
Kubernetes	Um release minor com suporte atual. O chart renderiza `autoscaling/v2` e `policy/v1`, então o cluster deve servir os dois.
Helm	3.8+ (suporte a OCI)
PostgreSQL	13+
MongoDB	4.4+
Valkey	7.x

O chart empacota PostgreSQL, MongoDB, RabbitMQ e Valkey como dependências de subchart. 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 quebra de compatibilidade que você deve considerar

Não pule várias versões maiores em um único helm upgrade. Leia cada nota de upgrade relevante no repositório do chart (UPGRADE-*.md) entre o seu chart atual e o seu destino.

Release do chart	O que mudou
v7.0.0	Os serviços `onboarding` e `transaction` foram removidos por completo. Toda a funcionalidade passou para o serviço único `ledger`. Os componentes Console e NGINX foram junto, e os helpers de template dos serviços antigos também.
v8.4.0	O subchart `otel-collector-lerian` não é mais instalado. A chave agora apenas injeta variáveis de ambiente OTEL, e o schema dela aceita apenas `enabled`. As chaves legadas (`external`, `extraEnvs`, `exporters`, `opentelemetry-collector`) falham na validação no momento do upgrade.

Se você ainda roda um chart v4.x ou v5.x, migre pelos caminhos em Visão geral da migração em vez de fazer upgrade direto para a linha atual.

Upgrade do Midaz core

Ao fazer upgrade do Midaz ou de qualquer plugin, faça sempre o upgrade do chart Helm correspondente.Atualizar as versões da aplicação sem fazer o upgrade do chart Helm pode levar a falhas de deploy ou a ambientes inconsistentes.

1. Confira as versões disponíveis

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

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

Ou navegue pelas tags de release:

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

2. Revise as mudanças antes do upgrade

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

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

Depois renderize o upgrade sem aplicá-lo:

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

Uma violação de schema (por exemplo uma chave legada otel-collector-lerian) falha aqui, e não no meio do upgrade.

3. Rode o upgrade

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

Sem argumentos de values, o Helm mantém por padrão os values armazenados do release. Passar -f (como acima) ou --set aplica esses novos overrides aos padrões do chart de destino, em vez de manter os values armazenados. Acrescente --reuse-values quando precisar mesclar novos overrides com os values armazenados do release. Use --reset-values para descartar os values armazenados e partir dos padrões do chart de destino.

4. Verifique o upgrade

Confira o status do release

helm list -n midaz

Verifique o status dos pods

kubectl get pods -n midaz

Confira os logs dos pods em busca de erros

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

Se você mantém a carga de trabalho legada de compatibilidade do CRM (crm.enabled: true):

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

Recomenda-se que todos os pods mostrem o status Running e uma contagem de containers 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 a partir do chart v7.0.0.

Upgrade dos plugins

Faça sempre o upgrade do Midaz Core antes de fazer o upgrade dos plugins. Os plugins dependem das APIs do Midaz Core.

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

CRM

O CRM é um módulo dentro do chart midaz-helm. Você o habilita com o bloco de values crm. Não existe chart de CRM. Quando você o habilita, verifique os pods dele depois do upgrade do core:

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

Fees

helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
  --version <target-version> \
  -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-helm \
  --version <target-version> \
  -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 carga de trabalho com o conjunto de labels app.kubernetes.io/*. Um seletor como -l app=midaz-crm não casa com nada.

Introdução

Midaz

Outros produtos

Guia de upgrade do Midaz via Helm

Início rápido

1. Confira os pré-requisitos

2. Identifique a sua versão atual

3. Rode o comando de upgrade

4. Verifique o upgrade

Compatibilidade de versões

Releases com quebra de compatibilidade que você deve considerar

Upgrade do Midaz core

1. Confira as versões disponíveis

2. Revise as mudanças antes do upgrade

3. Rode o upgrade

4. Verifique o upgrade

Upgrade dos plugins

CRM

Fees

Pix

​Início rápido

​1. Confira os pré-requisitos

​2. Identifique a sua versão atual

​3. Rode o comando de upgrade

​4. Verifique o upgrade

​Compatibilidade de versões

​Releases com quebra de compatibilidade que você deve considerar

​Upgrade do Midaz core

​1. Confira as versões disponíveis

​2. Revise as mudanças antes do upgrade

​3. Rode o upgrade

​4. Verifique o upgrade

​Upgrade dos plugins

​CRM

​Fees

​Pix

Início rápido

1. Confira os pré-requisitos

2. Identifique a sua versão atual

3. Rode o comando de upgrade

4. Verifique o upgrade

Compatibilidade de versões

Releases com quebra de compatibilidade que você deve considerar

Upgrade do Midaz core

1. Confira as versões disponíveis

2. Revise as mudanças antes do upgrade

3. Rode o upgrade

4. Verifique o upgrade

Upgrade dos plugins

CRM

Fees

Pix