Post

Guia Completo de Troubleshooting para Kubernetes

Posted
By Gean Martins
22 min read
Guia Completo de Troubleshooting para Kubernetes

Guia de Troubleshooting para Kubernetes

Este guia fornece uma coleção organizada de comandos e técnicas para diagnosticar e resolver problemas comuns no Kubernetes. A estrutura segue uma lógica de causa e efeito, apresentando um problema (o efeito) e, em seguida, os comandos para investigar e identificar a causa.

Fluxo de Troubleshooting Estruturado (Checklist Inicial)

Antes de mergulhar em diagnósticos profundos, comece com este checklist para os problemas mais comuns. Ele serve como um ponto de partida rápido para identificar a área geral do problema.

  1. POD não inicia
    • Causa provável: Imagem não encontrada, erro de configuração, falta de recursos, falha no pull da imagem.
    • Diagnóstico:
      • kubectl describe pod <NOME_DO_POD> para ver detalhes e eventos.
      • kubectl logs --previous <NOME_DO_POD> para verificar logs de containers que reiniciaram.
      • Verificar eventos do namespace: kubectl get events -n <NAMESPACE>.
      • Checar imagePullSecrets se a imagem for de um registro privado.
  2. POD em Crash (CrashLoopBackOff)
    • Causa provável: Erro na aplicação, configuração incorreta de probes (liveness/readiness), falta de memória ou CPU.
    • Diagnóstico:
      • kubectl logs <NOME_DO_POD> para ver a saída do container.
      • Verificar a configuração das readiness/liveness probes no manifesto do pod.
      • Checar o consumo de recursos: kubectl top pod <NOME_DO_POD>.
  3. Problemas de Rede
    • Causa provável: Problema de DNS, NetworkPolicy bloqueando tráfego, serviço mal configurado.
    • Diagnóstico:
      • Testar resolução de DNS interno a partir de um pod de debug.
      • Verificar NetworkPolicies: kubectl get networkpolicies -A.
      • Checar os endpoints do serviço: kubectl get endpoints <NOME_DO_SERVICO>.
  4. Armazenamento não Monta
    • Causa provável: StorageClass incorreta, problema no provisionador de volume, PersistentVolumeClaim (PVC) não consegue se vincular a um PersistentVolume (PV).
    • Diagnóstico:
      • kubectl describe pvc <NOME_DO_PVC> para obter detalhes sobre o erro.
      • Verificar a StorageClass e seu provisionador.
      • Checar eventos relacionados ao PV e PVC: kubectl get events | grep -i pvc.

Diagnóstico de Componentes do Cluster

Quando o problema não é óbvio a partir do checklist inicial, o próximo passo é investigar a saúde dos componentes fundamentais do cluster.

1. Diagnóstico de Nós (Nodes)

Efeito: Um ou mais nós não estão se comportando como esperado (ex: NotReady, sobrecarregado).

Causa: Problemas de rede no nó, kubelet parado, falta de recursos (CPU, memória, disco).

1
2
3
4
5
6
7
8
9
10
11

# Listar todos os nós e seu status
kubectl get nodes -o wide

# Obter informações detalhadas sobre um nó específico
kubectl describe node <NOME_DO_NO>

# Verificar o consumo de CPU e memória dos nós
kubectl top nodes

# Verificar rapidamente se todos os nós estão com status "Ready"
kubectl get nodes -o jsonpath='{.items[*].status.conditions[?(@.type=="Ready")].status}'

2. Diagnóstico de Pods

Efeito: O pod está em um estado inesperado (Pending, CrashLoopBackOff, ImagePullBackOff).

Causa: Falta de recursos para agendamento, erro na imagem, erro na aplicação dentro do container.

1
2
3
4
5
6
7
8
9
10
11

# Listar todos os pods em todos os namespaces
kubectl get pods --all-namespaces -o wide

# Descrever um pod para ver eventos e configurações detalhadas
kubectl describe pod <NOME_DO_POD> -n <NAMESPACE>

# Verificar o consumo de CPU e memória dos pods em um namespace
kubectl top pods -n <NAMESPACE>

# Obter eventos associados a um pod específico
kubectl get events --field-selector involvedObject.name=<NOME_DO_POD>

3. Análise de Logs

Efeito: A aplicação dentro do pod não funciona corretamente.

Causa: Erros de código, problemas de configuração, falhas de conexão, que são geralmente registrados nos logs.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# Ver logs de um pod (se houver múltiplos containers, especifique com -c)
kubectl logs <NOME_DO_POD> -c <NOME_DO_CONTAINER>

# Ver logs de todos os containers em um pod
kubectl logs <NOME_DO_POD> --all-containers

# Ver logs de uma execução anterior de um container que reiniciou
kubectl logs --previous <NOME_DO_POD>

# Adicionar timestamps aos logs
kubectl logs <NOME_DO_POD> --timestamps

# Seguir os logs de múltiplos pods com um label específico (ex: app=meu-app)
kubectl logs -f -l app=<VALOR_DO_LABEL>

# Ver logs desde um tempo específico (ex: última hora)
kubectl logs <NOME_DO_POD> --since=1h

Troubleshooting de Rede

Problemas de rede são uma das causas mais comuns de falhas em aplicações distribuídas. A investigação deve seguir uma abordagem passo a passo, da camada de serviço até a conectividade básica.

1. Diagnóstico de Serviços (Services) e Endpoints

Efeito: Uma aplicação não consegue se conectar a outra através de um Service.

Causa: O Service não está selecionando nenhum pod, os Endpoints não foram criados, ou uma NetworkPolicy está bloqueando o tráfego.

1
2
3
4
5
6
7
8

# Verificar se o Service tem Endpoints (pods) associados a ele
kubectl get endpoints <NOME_DO_SERVICO>

# Descrever o Service para verificar o seletor e as portas
kubectl describe service <NOME_DO_SERVICO>

# Listar todas as políticas de rede para verificar se há bloqueios
kubectl get networkpolicies -A

2. Testes de Conectividade e DNS

Efeito: Falha na resolução de nomes ou na conexão com um serviço.

Causa: Problema no CoreDNS, configuração de DNS incorreta no pod, ou falha de rede básica.

1
2
3
4
5
6
7
8
9
10
11
12

# Criar um pod de debug para testar a rede de dentro do cluster
kubectl run multitool --image=praqma/network-multitool --rm -it --restart=Never -- bash

# Dentro do pod de debug, testar a resolução de DNS
nslookup <NOME_DO_SERVICO>.<NAMESPACE>.svc.cluster.local

# Testar a conectividade com a porta de um serviço
nc -zv <NOME_DO_SERVICO> <PORTA>

# Usar o port-forward para expor um pod ou serviço localmente e debugá-lo
kubectl port-forward <NOME_DO_POD> <PORTA_LOCAL>:<PORTA_DO_POD>
kubectl port-forward service/<NOME_DO_SERVICO> <PORTA_LOCAL>:<PORTA_DO_SERVICO>

3. Diagnóstico de Ingress

Efeito: O tráfego externo não chega ao serviço.

Causa: Configuração incorreta do Ingress, problema no Ingress Controller, ou erro de certificado TLS.

1
2
3
4
5
6
7
8

# Listar todos os Ingress no cluster
kubectl get ingress -A

# Descrever o Ingress para ver as regras, backends e eventos
kubectl describe ingress <NOME_DO_INGRESS> -n <NAMESPACE>

# Obter a configuração completa do Ingress em formato YAML
kubectl get ingress <NOME_DO_INGRESS> -o yaml -n <NAMESPACE>

Troubleshooting de Armazenamento

Efeito: O pod não consegue iniciar porque um volume não pode ser montado.

Causa: PersistentVolumeClaim (PVC) não consegue se vincular a um PersistentVolume (PV), a StorageClass não existe ou está mal configurada, ou há um problema com o provisionador de armazenamento subjacente.

1
2
3
4
5
6
7
8

# Listar todos os PVs, PVCs e StorageClasses
kubectl get pv,pvc,storageclass -A

# Descrever o PVC para entender por que ele está em estado "Pending" ou com erro
kubectl describe pvc <NOME_DO_PVC> -n <NAMESPACE>

# Filtrar eventos do cluster para encontrar problemas relacionados a PVCs
kubectl get events | grep -i pvc

Troubleshooting de Acesso a Compartilhamentos NFS e SMB/CIFS

Compartilhamentos de rede como NFS (Network File System) e SMB/CIFS (Common Internet File System) são frequentemente utilizados em ambientes Kubernetes para persistência de dados. Problemas de conectividade, permissões e configuração podem impedir que os pods acessem esses recursos corretamente.

1. Testes Básicos de Conectividade NFS

Efeito: Os pods não conseguem montar volumes NFS ou a montagem falha intermitentemente.

Causa: Problema de conectividade de rede, portas bloqueadas, servidor NFS inacessível ou versão do NFS incompatível.

Verificar Portas NFS

O NFS utiliza múltiplas portas que precisam estar acessíveis. As principais são:

  • Porta 111 (rpcbind): Serviço de mapeamento RPC
  • Porta 2049 (nfs): Serviço NFS principal
  • Porta 20048 (mountd): Serviço de montagem
1
2
3
4
5

# Testar conectividade com servidor NFS em uma porta específica
kubectl run test-nfs-connect --rm -it --image=alpine --restart=Never -- nc -zv nfs-server.example.com 2049

# Testar múltiplas portas NFS simultaneamente
kubectl exec -it multitool -- bash -c "nc -zv nfs-server 111; nc -zv nfs-server 2049; nc -zv nfs-server 20048"

Testar Montagem NFS Básica

O pod a seguir tenta montar um compartilhamento NFS e executar testes básicos de leitura e escrita:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

apiVersion: v1
kind: Pod
metadata:
  name: nfs-test-basic
spec:
  containers:
  - name: nfs-tester
    image: alpine:latest
    command: ["sh", "-c"]
    args:
      - |
        apk add --no-cache nfs-utils
        mkdir -p /mnt/nfs
        echo "Tentando montar NFS..."
        mount -t nfs -o nfsvers=4 nfs-server.example.com:/export/path /mnt/nfs
        if mountpoint -q /mnt/nfs; then
          echo "Montagem NFS bem-sucedida"
          df -h /mnt/nfs
          ls -la /mnt/nfs
          # Testar escrita
          echo "teste_$(date)" > /mnt/nfs/testfile.txt
          cat /mnt/nfs/testfile.txt
          umount /mnt/nfs
        else
          echo "Falha na montagem NFS"
          exit 1
        fi
    securityContext:
      privileged: true
  restartPolicy: Never

2. Pod de Diagnóstico NFS Completo

Para um diagnóstico mais aprofundado, este ConfigMap contém um script que testa conectividade, portas, exports do servidor e diferentes versões do NFS:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62

apiVersion: v1
kind: ConfigMap
metadata:
  name: nfs-diagnostic-script
data:
  test-nfs.sh: |
    #!/bin/bash
    set -e
    
    echo "=== Diagnóstico NFS ==="
    echo "Servidor NFS: ${NFS_SERVER}"
    echo "Caminho: ${NFS_PATH}"
    
    # Instalar dependências
    echo "1. Instalando nfs-utils..."
    apk add --no-cache nfs-utils
    
    # Testar portas
    echo -e "\n2. Testando conectividade nas portas NFS:"
    for port in 111 2049 20048; do
      if nc -z -w5 ${NFS_SERVER} ${port}; then
        echo "Porta ${port} acessível"
      else
        echo "Porta ${port} inacessível"
      fi
    done
    
    # Mostrar exports do servidor
    echo -e "\n3. Listando exports do servidor:"
    showmount -e ${NFS_SERVER} || echo "showmount falhou"
    
    # Testar montagem NFSv3
    echo -e "\n4. Testando montagem NFSv3:"
    mkdir -p /mnt/nfs-test
    if mount -t nfs -o nfsvers=3 ${NFS_SERVER}:${NFS_PATH} /mnt/nfs-test; then
      echo "NFSv3 montado com sucesso"
      df -h /mnt/nfs-test
      umount /mnt/nfs-test
    else
      echo "Falha na montagem NFSv3"
    fi
    
    # Testar montagem NFSv4
    echo -e "\n5. Testando montagem NFSv4:"
    if mount -t nfs -o nfsvers=4 ${NFS_SERVER}:${NFS_PATH} /mnt/nfs-test; then
      echo "NFSv4 montado com sucesso"
      ls -la /mnt/nfs-test
      # Testar escrita
      TEST_FILE="/mnt/nfs-test/test_write_$(hostname).txt"
      echo "Teste de escrita $(date)" > ${TEST_FILE}
      echo "Conteúdo escrito: $(cat ${TEST_FILE})"
      rm ${TEST_FILE}
      umount /mnt/nfs-test
    else
      echo "Falha na montagem NFSv4"
    fi
    
    # Verificar estatísticas RPC
    echo -e "\n6. Estatísticas RPC:"
    rpcinfo -p ${NFS_SERVER} || echo "rpcinfo falhou"
    
    echo -e "\n=== Diagnóstico completo ==="

Para executar este script:

1
2
3
4
5
6

kubectl run nfs-diagnostic --rm -it --image=alpine \
  --env="NFS_SERVER=nfs-server.example.com" \
  --env="NFS_PATH=/export/data" \
  --restart=Never -- sh -c "
  apk add --no-cache curl
  curl -s https://raw.githubusercontent.com/seu-repo/nfs-test.sh | sh"

3. Testes de Conectividade SMB/CIFS

Efeito: Os pods não conseguem montar compartilhamentos SMB ou a autenticação falha.

Causa: Portas bloqueadas, credenciais incorretas, versão do SMB incompatível ou problemas de domínio.

Testar Portas SMB

O SMB utiliza as seguintes portas:

  • Porta 139 (NetBIOS): Comunicação NetBIOS
  • Porta 445 (SMB): SMB direto (recomendado)
1
2
3
4
5
6

# Testar portas SMB
kubectl run test-smb-ports --rm -it --image=alpine --restart=Never -- \
  sh -c "nc -zv smb-server 139; nc -zv smb-server 445"

# Usando multitool com nmap para scan mais detalhado
kubectl exec -it multitool -- nmap -p 139,445 smb-server.example.com

Pod de Teste SMB/CIFS Básico

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

apiVersion: v1
kind: Pod
metadata:
  name: smb-test-basic
spec:
  containers:
  - name: smb-tester
    image: alpine:latest
    command: ["sh", "-c"]
    args:
      - |
        apk add --no-cache cifs-utils samba-client
        mkdir -p /mnt/smb
        
        echo "Testando lista de compartilhamentos..."
        smbclient -L //smb-server.example.com -U ${SMB_USER}%${SMB_PASSWORD} || \
        smbclient -L //smb-server.example.com -N
        
        echo "Tentando montar SMB..."
        mount -t cifs //smb-server.example.com/share /mnt/smb \
          -o username=${SMB_USER},password=${SMB_PASSWORD},vers=3.0
        
        if mountpoint -q /mnt/smb; then
          echo "SMB montado com sucesso"
          df -h /mnt/smb
          ls -la /mnt/smb
          # Testar escrita
          echo "teste_$(date)" > /mnt/smb/testfile.txt
          cat /mnt/smb/testfile.txt
          umount /mnt/smb
        else
          echo "Falha na montagem SMB"
        fi
    env:
    - name: SMB_USER
      value: "usuario"
    - name: SMB_PASSWORD
      value: "senha"
    securityContext:
      privileged: true
  restartPolicy: Never

4. Pod Avançado de Diagnóstico SMB

Este pod executa testes completos incluindo diferentes versões do SMB, testes de IO e performance:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98

apiVersion: v1
kind: Pod
metadata:
  name: smb-diagnostic
spec:
  containers:
  - name: diagnostic
    image: ubuntu:latest
    command: ["bash", "-c"]
    args:
      - |
        apt-get update && apt-get install -y cifs-utils smbclient curl netcat
        
        echo "=== Diagnóstico SMB/CIFS ==="
        echo "Servidor: ${SMB_SERVER}"
        echo "Compartilhamento: ${SMB_SHARE}"
        
        # Testar portas
        echo -e "\n1. Testando portas:"
        timeout 5 nc -zv ${SMB_SERVER} 139 && echo "Porta 139 (NetBIOS) acessível"
        timeout 5 nc -zv ${SMB_SERVER} 445 && echo "Porta 445 (SMB) acessível"
        
        # Listar compartilhamentos
        echo -e "\n2. Listando compartilhamentos disponíveis:"
        if [ -n "${SMB_USER}" ] && [ -n "${SMB_PASSWORD}" ]; then
          smbclient -L //${SMB_SERVER} -U ${SMB_USER}%${SMB_PASSWORD} || true
        else
          smbclient -L //${SMB_SERVER} -N || true
        fi
        
        # Testar diferentes versões do SMB
        echo -e "\n3. Testando diferentes versões SMB:"
        for vers in 1.0 2.0 2.1 3.0 3.1.1; do
          mkdir -p /mnt/smb-test-${vers}
          echo -n "SMB versão ${vers}: "
          if mount -t cifs //${SMB_SERVER}/${SMB_SHARE} /mnt/smb-test-${vers} \
            -o username=${SMB_USER},password=${SMB_PASSWORD},vers=${vers},ro 2>/dev/null; then
            echo "Suporte disponível"
            umount /mnt/smb-test-${vers}
          else
            echo "Não suportado"
          fi
          rmdir /mnt/smb-test-${vers}
        done
        
        # Montagem completa e teste de IO
        echo -e "\n4. Teste completo de montagem e IO:"
        mkdir -p /mnt/smb-final
        MOUNT_OPTS="username=${SMB_USER},password=${SMB_PASSWORD},vers=3.0"
        
        if mount -t cifs //${SMB_SERVER}/${SMB_SHARE} /mnt/smb-final -o ${MOUNT_OPTS}; then
          echo "Montagem bem-sucedida"
          
          # Informações do sistema de arquivos
          echo -e "\nInformações do sistema de arquivos:"
          df -h /mnt/smb-final
          mount | grep /mnt/smb-final
          
          # Teste de leitura
          echo -e "\nTestando leitura:"
          ls -la /mnt/smb-final | head -20
          
          # Teste de escrita (se não for readonly)
          echo -e "\nTestando escrita:"
          TEST_FILE="/mnt/smb-final/test_k8s_$(hostname)_$(date +%s).txt"
          if touch ${TEST_FILE} 2>/dev/null; then
            echo "Teste de escrita $(date)" > ${TEST_FILE}
            echo "Escrita bem-sucedida. Conteúdo:"
            cat ${TEST_FILE}
            rm ${TEST_FILE}
          else
            echo "Escrita não permitida (pode ser normal para compartilhamentos readonly)"
          fi
          
          # Teste de performance básico
          echo -e "\nTeste de performance (dd):"
          time dd if=/dev/zero of=/mnt/smb-final/test_dd bs=1M count=10 status=none 2>&1 || \
            echo "dd falhou - possivelmente sem permissão de escrita"
          
          # Limpeza
          umount /mnt/smb-final
          echo -e "\nTestes concluídos"
        else
          echo "Falha na montagem final"
          exit 1
        fi
    env:
    - name: SMB_SERVER
      value: "smb-server.example.com"
    - name: SMB_SHARE
      value: "compartilhamento"
    - name: SMB_USER
      value: "usuario"
    - name: SMB_PASSWORD
      value: "senha"
    securityContext:
      privileged: true
  restartPolicy: Never

5. Usando Secrets para Credenciais SMB

Ao trabalhar com credenciais sensíveis, é recomendado utilizar Kubernetes Secrets em vez de variáveis de ambiente em texto plano:

1
2
3
4
5
6
7
8
9

# Secret para credenciais SMB
apiVersion: v1
kind: Secret
metadata:
  name: smb-credentials
type: Opaque
stringData:
  username: "dominio\\usuario"
  password: "senha-secreta"

Pod que utiliza o Secret:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

apiVersion: v1
kind: Pod
metadata:
  name: smb-with-secret
spec:
  containers:
  - name: smb-mount
    image: alpine:latest
    command: ["sh", "-c"]
    args:
      - |
        apk add --no-cache cifs-utils
        mkdir -p /mnt/smb
        
        mount -t cifs //smb-server/share /mnt/smb \
          -o username=${SMB_USER},password=${SMB_PASS},domain=${SMB_DOMAIN}
        
        if mountpoint -q /mnt/smb; then
          echo "Montagem bem-sucedida"
          ls -la /mnt/smb
        fi
        sleep 3600
    env:
    - name: SMB_USER
      valueFrom:
        secretKeyRef:
          name: smb-credentials
          key: username
    - name: SMB_PASS
      valueFrom:
        secretKeyRef:
          name: smb-credentials
          key: password
    - name: SMB_DOMAIN
      value: "MEUDOMINIO"
    securityContext:
      privileged: true

6. Testes de PersistentVolume com NFS/SMB

Verificar PVs e PVCs Existentes

1
2
3
4
5
6
7
8

# Listar todos os PVs e PVCs
kubectl get pv,pvc -A

# Descrever um PV específico para ver detalhes de configuração
kubectl describe pv <nome-do-pv-nfs>

# Verificar eventos relacionados ao volume
kubectl get events --field-selector involvedObject.kind=PersistentVolumeClaim

Testar Montagem de PV NFS

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

apiVersion: v1
kind: Pod
metadata:
  name: test-pv-nfs
spec:
  containers:
  - name: test-container
    image: alpine:latest
    command: ["sleep", "3600"]
    volumeMounts:
    - name: nfs-volume
      mountPath: /data
  volumes:
  - name: nfs-volume
    persistentVolumeClaim:
      claimName: meu-pvc-nfs

Diagnóstico de Problemas de Montagem

1
2
3
4
5
6
7
8
9

# Verificar se o pod consegue montar o volume
kubectl describe pod test-pv-nfs | grep -A 10 -B 5 "MountVolume"

# Verificar logs do kubelet (se possível)
journalctl -u kubelet | grep -i nfs

# Executar dentro do pod para testar o volume
kubectl exec -it test-pv-nfs -- df -h /data
kubectl exec -it test-pv-nfs -- touch /data/testfile

7. Ferramentas Especializadas

Usando Imagem com Ferramentas SMB/NFS Completas

1
2
3
4
5
6
7
8

# Imagem com todas as ferramentas de diagnóstico
kubectl run storage-tools --rm -it --image=instrumentisto/nmap-smb-nfs \
  --restart=Never -- bash

# Dentro do container, você pode executar:
# nmap -sV --script smb-protocols,smb-security-mode,nfs-showmount <servidor>
# smbclient //server/share
# showmount -e nfs-server

Script de Diagnóstico Automático

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

#!/bin/bash
# diagnose-storage.sh
echo "=== Diagnóstico de Armazenamento ==="

# Testar DNS
echo "1. Resolução DNS:"
nslookup $NFS_SERVER
nslookup $SMB_SERVER

# Testar portas NFS
echo -e "\n2. Portas NFS:"
nmap -p 111,2049,20048 $NFS_SERVER | grep open

# Testar portas SMB
echo -e "\n3. Portas SMB:"
nmap -p 139,445 $SMB_SERVER | grep open

# Testar exports NFS
echo -e "\n4. Exports NFS:"
showmount -e $NFS_SERVER 2>/dev/null || echo "showmount falhou"

# Testar compartilhamentos SMB
echo -e "\n5. Compartilhamentos SMB:"
smbclient -L //$SMB_SERVER -N 2>/dev/null | grep -E "^\s+[A-Z]" || echo "smbclient falhou"

8. Solução de Problemas Comuns

Problemas Comuns de NFS

ProblemaSolução
Timeout na montagemTentar com versão específica do NFS: mount -t nfs -o nfsvers=4.1,timeo=300,retrans=5 server:/path /mnt
Problemas de permissãoVerificar UID/GID no servidor NFS: kubectl exec -it pod-nfs -- id e montar com: mount -t nfs -o uid=1000,gid=1000 server:/path /mnt
Stale file handlesRemontar o volume: umount -l /mnt/nfs seguido de mount -t nfs server:/path /mnt/nfs

Problemas Comuns de SMB

ProblemaSolução
Protocolo incompatívelForçar versão específica: mount -t cifs -o vers=2.0 //server/share /mnt
Problemas de encodingEspecificar charset: mount -t cifs -o iocharset=utf8,codepage=cp850 //server/share /mnt
Problemas de domínioIncluir domínio na montagem: mount -t cifs -o domain=MEUDOMINIO //server/share /mnt

9. Comandos Rápidos para Troubleshooting

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Verificar se o serviço NFS está rodando no servidor
kubectl exec -it multitool -- rpcinfo -p nfs-server | grep nfs

# Verificar estatísticas NFS
kubectl exec -it multitool -- nfsstat -m

# Testar performance básica com dd
kubectl exec -it pod-com-nfs -- dd if=/dev/zero of=/mnt/nfs/testfile bs=1M count=100

# Verificar latência do servidor
kubectl exec -it multitool -- ping -c 5 nfs-server

# Capturar pacotes (se tiver permissão)
kubectl exec -it multitool -- tcpdump -i any port 2049 -c 10

10. Job para Teste Contínuo de Armazenamento

Para monitoramento contínuo da saúde dos compartilhamentos, este CronJob executa testes periodicamente:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41

apiVersion: batch/v1
kind: CronJob
metadata:
  name: storage-health-check
spec:
  schedule: "*/15 * * * *"
  jobTemplate:
    spec:
      template:
        spec:
          containers:
          - name: checker
            image: alpine:latest
            command: ["sh", "-c"]
            args:
              - |
                apk add --no-cache nfs-utils cifs-utils
                
                # Testar NFS
                mkdir -p /mnt/nfs-test
                if mount -t nfs nfs-server:/share /mnt/nfs-test; then
                  echo "$(date) - NFS OK" >> /tmp/health.log
                  echo "test" > /mnt/nfs-test/healthcheck.txt
                  umount /mnt/nfs-test
                else
                  echo "$(date) - NFS FAILED" >> /tmp/health.log
                fi
                
                # Testar SMB
                mkdir -p /mnt/smb-test
                if mount -t cifs //smb-server/share /mnt/smb-test -o username=user,password=pass; then
                  echo "$(date) - SMB OK" >> /tmp/health.log
                  umount /mnt/smb-test
                else
                  echo "$(date) - SMB FAILED" >> /tmp/health.log
                fi
                
                cat /tmp/health.log
            securityContext:
              privileged: true
          restartPolicy: OnFailure

Troubleshooting de Configuração e Debug

Erros de configuração são sutis e podem levar a comportamentos inesperados. O debug direto nos containers é uma ferramenta poderosa para investigações em tempo real.

1. Verificação de ConfigMaps e Secrets

Efeito: A aplicação se comporta de forma inesperada ou não consegue iniciar devido a configurações ou credenciais ausentes/incorretas.

Causa: ConfigMap ou Secret não montado corretamente, dados incorretos ou erro de codificação (para Secrets).

1
2
3
4
5
6
7
8

# Validar um manifesto antes de aplicá-lo (dry-run no lado do cliente)
kubectl apply --dry-run=client -f seu-manifesto.yaml

# Ver o conteúdo de um ConfigMap
kubectl get configmap <NOME_DO_CONFIGMAP> -o yaml

# Decodificar e ver o conteúdo de um Secret
kubectl get secret <NOME_DO_SECRET> -o jsonpath='{.data}' | base64 -d

2. Debug Interativo de Containers

Efeito: Necessidade de investigar o ambiente de um container em execução ou executar comandos de diagnóstico dentro dele.

Causa: O problema só é reproduzível dentro do ambiente do container.

1
2
3
4
5
6
7
8
9
10

# Acessar um shell dentro de um container em execução
kubectl exec -it <NOME_DO_POD> -c <NOME_DO_CONTAINER> -- sh

# Usar um container efêmero para debug (Kubernetes 1.18+)
# Isso anexa um novo container com ferramentas de debug a um pod existente
kubectl debug <NOME_DO_POD> -it --image=busybox --target=<NOME_DO_CONTAINER>

# Copiar arquivos entre o pod e a máquina local
kubectl cp <NOME_DO_POD>:/caminho/no/pod ./arquivo-local
kubectl cp ./arquivo-local <NOME_DO_POD>:/caminho/no/pod

Validação de Conexão com Banco de Dados

Efeito: A aplicação não consegue se conectar ao banco de dados.

Causa: Problema de rede, credenciais incorretas, erro de DNS ou o serviço do banco de dados não está acessível.

1. Teste Básico de Conectividade

1
2
3
4
5
6

# Criar um pod temporário com o cliente do banco de dados (ex: MySQL)
kubectl run mysql-test --rm -it --image=mysql:8.0 --restart=Never -- bash

# Dentro do container, tente se conectar ao serviço do banco de dados
# O nome do serviço deve ser o FQDN (Fully Qualified Domain Name)
mysql -h <NOME_DO_SERVICO>.<NAMESPACE>.svc.cluster.local -u <USUARIO> -p

2. Teste de Porta com Netcat

1
2

# Use um pod com netcat para verificar se a porta do banco de dados está aberta
kubectl run netcat-test --rm -it --image=alpine --restart=Never -- nc -zv <NOME_DO_SERVICO_DB> <PORTA_DO_DB>

3. Script Completo de Diagnóstico (Exemplo para MySQL)

Crie um ConfigMap com um script de diagnóstico e execute-o a partir de um pod para um teste automatizado e completo.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# configmap-diagnostic.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: mysql-diagnostic-script
data:
  diagnostic.sh: |
    #!/bin/bash
    echo "=== Testando Conexão com MySQL: $MYSQL_HOST ==="
    echo "1. Resolução de DNS:"
    nslookup $MYSQL_HOST
    echo -e "\n2. Acessibilidade da Porta 3306:"
    nc -zv $MYSQL_HOST 3306
    echo -e "\n3. Teste de Conexão MySQL:"
    mysql -h $MYSQL_HOST -u $MYSQL_USER -p$MYSQL_PASSWORD -e "SELECT @@version;"

Ferramentas Externas Úteis

Além do kubectl, o ecossistema Kubernetes oferece várias ferramentas de linha de comando que podem acelerar e simplificar o troubleshooting.

  • k9s: Uma UI de terminal completa para gerenciar e observar seu cluster, permitindo navegação rápida entre recursos.
  • stern: Permite visualizar logs de múltiplos pods e containers de forma agregada e com cores, facilitando o rastreamento de problemas em aplicações distribuídas.
  • kubectx / kubens: Utilitários para trocar de contexto (cluster) e namespace de forma rápida e eficiente.
  • popeye: Uma ferramenta que escaneia clusters Kubernetes em busca de possíveis problemas e configurações incorretas, gerando um relatório de “saúde”.
  • kube-score: Realiza uma análise estática de seus manifestos YAML e fornece sugestões de melhoria e boas práticas.

Comandos de Contexto e Configuração

Gerenciar a configuração do kubectl é fundamental, especialmente ao trabalhar com múltiplos clusters.

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# Listar todos os contextos de cluster configurados
kubectl config get-contexts

# Trocar para um contexto diferente
kubectl config use-context <NOME_DO_CONTEXTO>

# Exibir a configuração atual do kubectl
kubectl config view

# Exibir informações sobre o cluster (endpoints do master e serviços)
kubectl cluster-info

# Verificar a versão do cliente e do servidor Kubernetes
kubectl version
Kubernetes
Kubernetes Troubleshooting
This post is licensed under CC BY 4.0 by the author.