Solução de problemas do Helm

​

Comandos gerais de diagnóstico

# 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

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

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

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

​

Timeout na instalação com Helm

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

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

• 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:
  kubectl get ingressclass
  
  Verifique também se o próprio pod do ingress controller está rodando:
  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:
  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:
  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:
  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. O cluster não tem uma StorageClass padrão.
  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.

​

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

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

• 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:
  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 fica em charts/midaz/files/rabbitmq/load_definitions.json no repositório Helm.
• O job de bootstrap falhou em silêncio. O job rodou, mas encontrou um erro (credenciais erradas, timeout de rede, porta errada).
  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: guia de instalação inicial
• Fazer upgrade do Midaz e dos plugins via Helm: procedimentos de upgrade e rollback
• Fazer upgrade do Helm: mudanças incompatíveis e caminhos de migração entre versões maiores
• Compatibilidade de versões do chart do Midaz: metadados atuais do chart e da aplicação
• Repositório Helm: código-fonte e notas de release