Guia de atualização

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 Instalando o Midaz com 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

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.7.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.7.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.7.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 Fees Engine

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

Verificar pods do Fees Engine

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

Pix

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

​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

​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

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

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