Solução de problemas do Helm

​

Comandos gerais de diagnóstico

# 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

kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp'
kubectl top nodes

• 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.
  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 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:
  kubectl get nodes --show-labels
  

​

ImagePullBackOff

kubectl describe pod <pod-name> -n midaz
kubectl get events -n midaz --sort-by='.lastTimestamp' | grep -i image

• 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.
• 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:
  kubectl create secret docker-registry regcred \
    --docker-server=<registry-url> \
    --docker-username=<username> \
    --docker-password=<password> \
    -n midaz
  
  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

kubectl get pods -n midaz
kubectl logs <pod-name> -n midaz --previous
kubectl describe pod <pod-name> -n midaz

• 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.
  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.
  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 abaixo.

​

Timeout no Helm install

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'

• Download de imagens lento — Imagens grandes em uma conexão lenta podem ultrapassar o timeout padrão. Aumente o timeout:
  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:
  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

kubectl get ingress -n midaz
kubectl describe ingress <ingress-name> -n midaz
kubectl get svc -n midaz
kubectl get endpoints -n midaz

• 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:
  kubectl get ingressclass
  
  Também verifique se o pod do ingress controller está rodando:
  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:
  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:
  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:
  kubectl get certificate -n midaz
  kubectl describe certificate <cert-name> -n midaz
  

​

PVC travado em Pending

kubectl get pvc -n midaz
kubectl describe pvc <pvc-name> -n midaz
kubectl get storageclass

• Sem StorageClass padrão — Nenhum StorageClass está marcado como padrão no cluster.
  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

kubectl get pods -n midaz
kubectl describe pod <pod-name> -n midaz | grep -A10 "Last State"
kubectl top pods -n midaz
kubectl top nodes

• 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:
  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ó:
  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

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

• 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:
  global:
    externalRabbitmqDefinitions:
      enabled: true
      connection:
        protocol: "http"
        host: "your-rabbitmq-host"
        port: "15672"
        portAmqp: "5672"
  
  Ou aplique as definições manualmente:
  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.
• Job de bootstrap falhou silenciosamente — O job foi executado mas encontrou um erro (credenciais erradas, timeout de rede, porta incorreta).
  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 — Guia de instalação inicial
• Atualizar o Midaz e plugins via Helm — Procedimentos de atualização e rollback
• Atualização do Helm — Alterações incompatíveis e caminhos de migração entre versões principais
• Compatibilidade de versões — Tabela de referência de versões
• Repositório do Helm — Código-fonte e notas de versão