> ## 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 fazer deploy ou operar o Midaz no Kubernetes: falhas de pod, erros de ingress e conflitos de dependências.

Este guia ajuda você a diagnosticar e resolver problemas comuns ao fazer deploy ou operar o Midaz no Kubernetes com Helm.

## Comandos gerais de diagnóstico

***

Comece por estes comandos para ter um panorama do estado do seu deploy.

```bash theme={null}
# List all Helm releases in the midaz namespace
helm list -n midaz

# Check the status of a specific release
helm status midaz -n midaz

# List all pods and their current state
kubectl get pods -n midaz

# Get events for the namespace (useful for spotting recent failures)
kubectl get events -n midaz --sort-by='.lastTimestamp'

# Describe a specific pod (replace <pod-name> with the actual name)
kubectl describe pod <pod-name> -n midaz

# Tail logs for a pod
kubectl logs <pod-name> -n midaz --tail=100

# Follow logs in real time
kubectl logs <pod-name> -n midaz -f
```

***

## Pods travados em Pending

***

**Sintoma:** um ou mais pods continuam 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 e soluções comuns:**

* **CPU ou memória insuficientes nos nós**. O scheduler não encontra um nó que satisfaça os requests 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 sem bind**. 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 uma StorageClass disponível e se ela é a padrão. Consulte [PVC travado em Pending](#pvc-stuck-in-pending) abaixo.

* **Seletor de nó ou afinidade incompatível**. O pod exige um label de nó específico que nenhum nó do cluster tem.

  Verifique as configurações `nodeSelector` ou `affinity` no seu `values.yaml` e confirme que seus 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 e soluções comuns:**

* **Tag de imagem errada**. A tag indicada não existe no registry. Inspecione o pacote do chart selecionado e compare `ledger.image.tag` com os metadados e os values dele. A [página de versões do chart do Midaz](/pt/platform/deploy/helm-version-compatibility) registra o padrão auditado.

* **O registry privado exige autenticação**. O cluster não consegue baixar 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` ausente**. O secret existe, mas a configuração do componente não faz referência a ele. Defina `imagePullSecrets` em todos os componentes afetados.

***

## CrashLoopBackOff

***

**Sintoma:** os pods iniciam e caem na hora, 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, não da que está reiniciando agora.
</Tip>

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

* **Variáveis de ambiente erradas ou ausentes**. Uma chave de configuração obrigatória está ausente ou tem um valor incorreto. Procure nos logs mensagens como `missing env var`, `invalid config` ou parecidas. Revise a seção `configmap` do seu `values.yaml`.

* **Secret do Kubernetes ausente**. O pod faz referência a 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 rode a instalação do Helm de novo.

* **Credenciais de banco de dados erradas**. O serviço não consegue se autenticar no PostgreSQL, no MongoDB ou no Redis.

  Procure nos logs `authentication failed` ou `connection refused`. Verifique a seção `secrets` do seu `values.yaml` e confirme que as credenciais são as mesmas que você usou ao provisionar os bancos de dados.

* **OOMKilled**. O container passou do limite de memória e o kernel o matou.

  ```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 [Eviction de pod / OOMKilled](#pod-eviction--oomkilled) abaixo.

***

## Timeout na instalação com Helm

***

**Sintoma:** o `helm install` ou o `helm upgrade` falha com erro de timeout antes de o release chegar ao 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 e soluções comuns:**

* **Download lento de imagens**. Imagens grandes em uma conexão lenta podem passar do 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) trava ou faz novas tentativas. Consulte os logs do init container:

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

* **Probes de readiness falhando**. O pod roda, mas não passa na verificação de readiness, então o Helm espera indefinidamente. Descreva o pod e olhe as seções `Conditions` e `Events`. Você pode precisar aumentar `initialDelaySeconds` nas configurações da probe de readiness ou investigar por que o serviço não fica saudável ao iniciar.

***

## Serviços inacessíveis

***

**Sintoma:** as APIs do Midaz ficam inacessí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 e soluções comuns:**

* **Ingress mal configurado**. O recurso Ingress existe, mas o controller não o assume. Verifique se `ingress.className` corresponde à classe do ingress controller que você instalou:

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

  Verifique também se o próprio 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 do seu Ingress não resolve para o IP externo do controller. Pegue o IP externo e compare com o seu registro DNS:

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

* **TLS mal configurado**. Um secret TLS ausente ou expirado faz o ingress falhar em silêncio. Verifique se o secret existe e se não expirou:

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

  Se você usa o cert-manager, verifique o status do recurso Certificate:

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

***

<h2 id="pvc-stuck-in-pending">
  PVC travado em Pending
</h2>

***

**Sintoma:** um PersistentVolumeClaim continua no 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 e soluções comuns:**

* **Sem StorageClass padrão**. O cluster não tem uma StorageClass padrão.

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

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

* **Modo de acesso errado**. A StorageClass não aceita o modo de acesso pedido pelo PVC (por exemplo, `ReadWriteMany` em um driver de armazenamento que aceita apenas `ReadWriteOnce`).

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

* **O modo de binding do volume é `WaitForFirstConsumer`**. Algumas StorageClasses usam binding tardio. O PVC fica em `Pending` até um pod que o consome ser agendado. Esse é o comportamento normal. Espere o pod ser agendado.

***

<h2 id="pod-eviction--oomkilled">
  Eviction de pod / OOMKilled
</h2>

***

**Sintoma:** os pods sofrem eviction repetidamente ou mostram `OOMKilled` no ú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 e soluções comuns:**

* **Limites de memória baixos demais**. O `resources.limits.memory` do container fica abaixo do que o serviço precisa sob carga.

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

  Os padrões do chart são `requests: 256Mi / 1500m` e `limits: 512Mi / 2000m`. Seu override **substitui** esses valores, então trate os padrões como a base de dimensionamento. Defina o limite de memória acima do padrão quando o container sofrer OOMKilled:

  ```yaml theme={null}
  ledger:
    resources:
      requests:
        memory: "512Mi"
        cpu: "1500m"
      limits:
        memory: "1Gi"
        cpu: "2000m"
  ```

* **Nó sob pressão de memória**. O próprio nó está sob pressão e o kubelet faz eviction dos pods de prioridade menor. Verifique as conditions 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 da eviction.

***

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

***

**Sintoma:** os serviços do Midaz iniciam, mas as transações falham, as filas não existem ou as mensagens ficam sem processamento. 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
# Check if the bootstrap job ran
kubectl get jobs -n midaz
kubectl logs job/midaz-bootstrap-rabbitmq -n midaz
```

<Note>
  Os nomes dos Jobs de bootstrap são `<release>-bootstrap-postgres`, `<release>-bootstrap-mongodb` e `<release>-bootstrap-rabbitmq`. Eles definem `ttlSecondsAfterFinished: 300`, então se excluem cinco minutos depois de terminar. Colete os logs deles logo, ou o comando retorna `NotFound`.
</Note>

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

* **RabbitMQ externo sem `load_definitions.json`**. Quando você usa uma instância externa de RabbitMQ, as filas, os exchanges e os 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` fica em `charts/midaz/files/rabbitmq/load_definitions.json` no [repositório Helm](https://github.com/LerianStudio/helm).

* **O job de bootstrap falhou em silêncio**. O job rodou, mas encontrou um erro (credenciais erradas, timeout de rede, porta errada).

  ```bash theme={null}
  kubectl logs job/midaz-bootstrap-rabbitmq -n midaz
  ```

  Verifique as credenciais `rabbitmqAdminLogin` e se a porta de gerenciamento (padrão `15672`) é alcançável de dentro do cluster.

***

## Recursos relacionados

* [Fazer deploy do Midaz com Helm](/pt/platform/deploy/midaz/midaz-installation): guia de instalação inicial
* [Fazer upgrade do Midaz e dos plugins via Helm](/pt/platform/deploy/midaz/midaz-upgrade-guide): procedimentos de upgrade e rollback
* [Fazer upgrade do Helm](/pt/platform/deploy/midaz/midaz-upgrading-overview): mudanças incompatíveis e caminhos de migração entre versões maiores
* [Compatibilidade de versões do chart do Midaz](/pt/platform/deploy/helm-version-compatibility): metadados atuais do chart e da aplicação
* [Repositório Helm](https://github.com/LerianStudio/helm): código-fonte e notas de release