> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Guia de upgrade do Midaz via Helm
> Faça o upgrade do seu deploy Helm do Midaz: início rápido, os releases com quebra de compatibilidade entre a v5 e a v8, o upgrade dos plugins e as verificações posteriores.
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](/pt/platform/deploy/midaz/midaz-installation) 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
```bash theme={null}
helm list -n midaz
```
A coluna `CHART` mostra a sua versão de chart, no formato `midaz-helm-`.
### 3. Rode o comando de upgrade
```bash theme={null}
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
--version \
-n midaz \
-f your-values.yaml
```
### 4. Verifique o upgrade
```bash theme={null}
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](/pt/platform/deploy/midaz/midaz-production-values).
## 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](https://github.com/LerianStudio/helm/tree/main/charts/midaz/docs) (`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](/pt/platform/deploy/midaz/midaz-migrating-overview) 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:
```bash theme={null}
helm show chart oci://registry-1.docker.io/lerianstudio/midaz-helm --version
```
Ou navegue pelas tags de release:
* Acesse [https://github.com/LerianStudio/helm/tags](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:
```bash theme={null}
helm show values oci://registry-1.docker.io/lerianstudio/midaz-helm --version > new-defaults.yaml
```
Depois renderize o upgrade sem aplicá-lo:
```bash theme={null}
helm template midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
--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
```bash theme={null}
helm upgrade midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
--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**
```bash theme={null}
helm list -n midaz
```
* **Verifique o status dos pods**
```bash theme={null}
kubectl get pods -n midaz
```
* **Confira os logs dos pods em busca de erros**
```bash theme={null}
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`):
```bash theme={null}
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](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:
```bash theme={null}
kubectl get pods -n midaz -l app.kubernetes.io/name=midaz-crm
```
### Fees
```bash theme={null}
helm upgrade plugin-fees oci://registry-1.docker.io/lerianstudio/plugin-fees-helm \
--version \
-n midaz-plugins \
-f plugin-fees-values-backup.yaml
```
```bash theme={null}
kubectl get pods -n midaz-plugins -l app.kubernetes.io/instance=plugin-fees
```
### Pix
```bash theme={null}
helm upgrade plugin-br-pix-direct-jd \
oci://registry-1.docker.io/lerianstudio/plugin-br-pix-direct-jd-helm \
--version \
-n midaz-plugins \
-f plugin-pix-values-backup.yaml
```
```bash theme={null}
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.