> ## 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.

# Solução de problemas do Helm

> Diagnostique e resolva problemas comuns ao implantar ou operar o Midaz no Kubernetes — falhas de pods, erros de ingress e conflitos de dependências.

Este guia ajuda você a diagnosticar e resolver os problemas mais comuns ao implantar ou operar o Midaz no Kubernetes com Helm. Cada seção cobre um sintoma específico, os comandos de diagnóstico para investigá-lo e os passos para resolvê-lo.

## Comandos gerais de diagnóstico

***

Comece com estes comandos para obter uma visão geral do estado do seu deployment antes de mergulhar em problemas específicos.

```bash theme={null}
# Listar todos os releases do Helm no namespace midaz
helm list -n midaz

# Verificar o status de um release específico
helm status midaz -n midaz

# Listar todos os pods e seu estado atual
kubectl get pods -n midaz

# Obter eventos do namespace (útil para identificar falhas recentes)
kubectl get events -n midaz --sort-by='.lastTimestamp'

# Descrever um pod específico (substitua <pod-name> pelo nome real)
kubectl describe pod <pod-name> -n midaz

# Ver os últimos logs de um pod
kubectl logs <pod-name> -n midaz --tail=100

# Acompanhar os logs em tempo real
kubectl logs <pod-name> -n midaz -f
```

***

## Pods travados em Pending

***

**Sintoma:** Um ou mais pods permanecem no estado `Pending` e nunca iniciam.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp'
kubectl top nodes
```

**Causas comuns e soluções:**

* **CPU ou memória insuficiente nos nós** — O scheduler não consegue encontrar um nó que satisfaça as solicitações de recursos do pod.

  Verifique a seção `Events` do `kubectl describe pod`. Procure mensagens como `Insufficient cpu` ou `Insufficient memory`. Reduza `resources.requests` no seu `values.yaml` ou adicione mais nós ao cluster.

* **PersistentVolumeClaim não vinculado** — Um PVC exigido por uma dependência (PostgreSQL, MongoDB, Valkey) está travado em `Pending`.

  ```bash theme={null}
  kubectl get pvc -n midaz
  kubectl describe pvc <pvc-name> -n midaz
  ```

  Verifique se existe um StorageClass disponível e configurado como padrão. Consulte [PVC travado em Pending](#pvc-travado-em-pending) abaixo.

* **Node selector ou affinity sem correspondência** — O pod exige um label de nó específico que nenhum nó do cluster possui.

  Verifique seu `values.yaml` para configurações de `nodeSelector` ou `affinity` e confirme que os nós têm os labels esperados:

  ```bash theme={null}
  kubectl get nodes --show-labels
  ```

***

## ImagePullBackOff

***

**Sintoma:** Os pods mostram o status `ImagePullBackOff` ou `ErrImagePull`.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp' | grep -i image
```

**Causas comuns e soluções:**

* **Tag de imagem incorreta** — A tag especificada não existe no registry. Verifique o valor de `image.tag` no seu `values.yaml` comparando com a [tabela de compatibilidade de versões](/pt/platform/helm/helm-version-compatibility).

* **Registry privado requer autenticação** — O cluster não consegue baixar as imagens sem credenciais.

  Crie um secret de pull de imagem e referencie-o no seu `values.yaml`:

  ```bash theme={null}
  kubectl create secret docker-registry regcred \
    --docker-server=<registry-url> \
    --docker-username=<username> \
    --docker-password=<password> \
    -n midaz
  ```

  ```yaml theme={null}
  ledger:
    imagePullSecrets:
      - name: regcred
  ```

* **`imagePullSecrets` não configurado** — O secret existe mas não está referenciado na configuração do componente. Certifique-se de que `imagePullSecrets` esteja configurado em todos os componentes afetados.

***

## CrashLoopBackOff

***

**Sintoma:** Os pods iniciam e caem imediatamente, reiniciando repetidamente.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get pods -n midaz
kubectl logs <pod-name> -n midaz --previous
kubectl describe pod <pod-name> -n midaz
```

<Tip>
  Use `--previous` para ver os logs da última instância do container que caiu, e não do que está reiniciando atualmente.
</Tip>

**Causas comuns e soluções:**

* **Variáveis de ambiente incorretas ou ausentes** — Uma chave de configuração necessária está ausente ou tem um valor incorreto. Verifique os logs buscando mensagens como `missing env var`, `invalid config` ou similares. Revise a seção `configmap` do seu `values.yaml`.

* **Secret do Kubernetes ausente** — O pod referencia um secret que não existe.

  ```bash theme={null}
  kubectl get secrets -n midaz
  kubectl describe secret <secret-name> -n midaz
  ```

  Se o secret não existe, crie-o manualmente ou execute novamente a instalação do Helm.

* **Credenciais de banco de dados incorretas** — O serviço não consegue autenticar com PostgreSQL, MongoDB ou Redis.

  Verifique os logs buscando `authentication failed`, `connection refused` ou `ECONNREFUSED`. Confirme a seção `secrets` no seu `values.yaml` e verifique se as credenciais correspondem às usadas ao provisionar os bancos de dados.

* **OOMKilled** — O container excedeu seu limite de memória e foi eliminado pelo kernel.

  ```bash theme={null}
  kubectl describe pod <pod-name> -n midaz | grep -A5 "Last State"
  ```

  Procure `OOMKilled` na seção `Last State`. Aumente `resources.limits.memory` no seu `values.yaml`. Consulte [Evicção de pod / OOMKilled](#evicção-de-pod--oomkilled) abaixo.

***

## Timeout no Helm install

***

**Sintoma:** `helm install` ou `helm upgrade` falha com erro de timeout antes de o release atingir o estado `deployed`.

**Comandos de diagnóstico:**

```bash theme={null}
helm status midaz -n midaz
kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp'
```

**Causas comuns e soluções:**

* **Download de imagens lento** — Imagens grandes em uma conexão lenta podem ultrapassar o timeout padrão. Aumente o timeout:

  ```bash theme={null}
  helm install midaz oci://registry-1.docker.io/lerianstudio/midaz-helm \
    --version <version> \
    -n midaz \
    --create-namespace \
    --timeout 15m
  ```

* **Init containers falhando** — Um init container (por exemplo, o job de bootstrap do banco de dados) está travado ou reiniciando. Verifique os logs do init container:

  ```bash theme={null}
  kubectl logs <pod-name> -n midaz -c <init-container-name>
  ```

* **Readiness probes falhando** — O pod está rodando mas não passa na verificação de readiness, então o Helm espera indefinidamente. Descreva o pod e verifique as seções `Conditions` e `Events`. Pode ser necessário aumentar `initialDelaySeconds` nas configurações do readiness probe, ou investigar por que o serviço não está saudável na inicialização.

***

## Serviços inacessíveis

***

**Sintoma:** As APIs do Midaz não são acessíveis de fora do cluster, ou os serviços não conseguem se comunicar internamente.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get ingress -n midaz
kubectl describe ingress <ingress-name> -n midaz
kubectl get svc -n midaz
kubectl get endpoints -n midaz
```

**Causas comuns e soluções:**

* **Configuração incorreta do Ingress** — O recurso Ingress existe mas o controller não está processando. Verifique se `ingress.className` corresponde à classe do seu ingress controller instalado:

  ```bash theme={null}
  kubectl get ingressclass
  ```

  Também verifique se o pod do ingress controller está rodando:

  ```bash theme={null}
  kubectl get pods -n ingress-nginx
  ```

* **DNS não aponta para o load balancer** — O hostname no seu Ingress não resolve para o IP externo do controller. Obtenha o IP externo e compare com seu registro DNS:

  ```bash theme={null}
  kubectl get svc -n ingress-nginx
  ```

* **Configuração TLS incorreta** — Um secret TLS ausente ou expirado faz o ingress falhar silenciosamente. Verifique se o secret existe e não está expirado:

  ```bash theme={null}
  kubectl get secret <tls-secret-name> -n midaz
  kubectl describe secret <tls-secret-name> -n midaz
  ```

  Se usar cert-manager, verifique o status do recurso Certificate:

  ```bash theme={null}
  kubectl get certificate -n midaz
  kubectl describe certificate <cert-name> -n midaz
  ```

***

## PVC travado em Pending

***

**Sintoma:** Um PersistentVolumeClaim permanece em estado `Pending` e o pod dependente não consegue iniciar.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get pvc -n midaz
kubectl describe pvc <pvc-name> -n midaz
kubectl get storageclass
```

**Causas comuns e soluções:**

* **Sem StorageClass padrão** — Nenhum StorageClass está marcado como padrão no cluster.

  ```bash theme={null}
  kubectl get storageclass
  ```

  Se nenhum mostrar `(default)`, crie um StorageClass ou configure um explicitamente no seu `values.yaml` para a dependência afetada (por exemplo, `postgresql.primary.persistence.storageClass`).

* **Modo de acesso incorreto** — O StorageClass não suporta o modo de acesso solicitado pelo PVC (por exemplo, `ReadWriteMany` em um driver de armazenamento que só suporta `ReadWriteOnce`).

  Verifique a seção `Events` do `kubectl describe pvc`. Ajuste `accessModes` no seu `values.yaml` para corresponder ao que seu StorageClass suporta.

* **Modo de binding do volume é `WaitForFirstConsumer`** — Alguns StorageClasses usam binding adiado. O PVC ficará em `Pending` até que um pod que o consume seja agendado. Este é um comportamento normal; aguarde o pod ser agendado.

***

## Evicção de pod / OOMKilled

***

**Sintoma:** Os pods são repetidamente evictados ou mostram `OOMKilled` em seu último estado.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz | grep -A10 "Last State"
kubectl top pods -n midaz
kubectl top nodes
```

**Causas comuns e soluções:**

* **Limites de memória muito baixos** — O `resources.limits.memory` do container está abaixo do que o serviço realmente precisa sob carga.

  Verifique o uso atual de memória com `kubectl top pods` e então aumente o limite no seu `values.yaml`:

  ```yaml theme={null}
  ledger:
    resources:
      requests:
        memory: "256Mi"
        cpu: "250m"
      limits:
        memory: "512Mi"
        cpu: "500m"
  ```

* **Nó sob pressão de memória** — O próprio nó está sob pressão e o kubelet está evictando pods de menor prioridade. Verifique as condições do nó:

  ```bash theme={null}
  kubectl describe node <node-name> | grep -A5 Conditions
  ```

  Considere adicionar nós ou habilitar o cluster autoscaler. Você também pode definir `PriorityClass` nos pods do Midaz para protegê-los de evicção.

***

## Definições do RabbitMQ não carregadas

***

**Sintoma:** Os serviços do Midaz iniciam mas as transações falham, filas estão ausentes, ou mensagens não estão sendo processadas. Os logs podem mostrar erros de conexão AMQP ou exchanges/filas ausentes.

**Comandos de diagnóstico:**

```bash theme={null}
kubectl get pods -n midaz | grep rabbit
kubectl logs <rabbitmq-pod-name> -n midaz --tail=100
# Verificar se o job de bootstrap foi executado
kubectl get jobs -n midaz
kubectl logs job/<bootstrap-job-name> -n midaz
```

**Causas comuns e soluções:**

* **RabbitMQ externo sem `load_definitions.json`** — Ao usar uma instância externa de RabbitMQ, as filas, exchanges e bindings necessários não estão presentes.

  Habilite o job de bootstrap no seu `values.yaml`:

  ```yaml theme={null}
  global:
    externalRabbitmqDefinitions:
      enabled: true
      connection:
        protocol: "http"
        host: "your-rabbitmq-host"
        port: "15672"
        portAmqp: "5672"
  ```

  Ou aplique as definições manualmente:

  ```bash theme={null}
  curl -u {user}:{pass} -X POST -H "Content-Type: application/json" \
    -d @load_definitions.json \
    http://{host}:{port}/api/definitions
  ```

  O arquivo `load_definitions.json` está em `charts/midaz/files/rabbitmq/load_definitions.json` no [repositório do Helm](https://github.com/LerianStudio/midaz-helm).

* **Job de bootstrap falhou silenciosamente** — O job foi executado mas encontrou um erro (credenciais erradas, timeout de rede, porta incorreta).

  ```bash theme={null}
  kubectl logs job/<bootstrap-job-name> -n midaz
  ```

  Verifique as credenciais de `rabbitmqAdminLogin` e confirme que a porta de gerenciamento (padrão `15672`) é acessível de dentro do cluster.

***

## Recursos relacionados

* [Implantar o Midaz com Helm](/pt/platform/helm/midaz/midaz-installation) — Guia de instalação inicial
* [Atualizar o Midaz e plugins via Helm](/pt/platform/helm/midaz/midaz-upgrade-guide) — Procedimentos de atualização e rollback
* [Atualização do Helm](/pt/platform/helm/midaz/midaz-upgrading-overview) — Alterações incompatíveis e caminhos de migração entre versões principais
* [Compatibilidade de versões](/pt/platform/helm/helm-version-compatibility) — Tabela de referência de versões
* [Repositório do Helm](https://github.com/LerianStudio/midaz-helm) — Código-fonte e notas de versão