Saltar a contenido

Troubleshooting - Control Plane y Worker Nodes

Troubleshooting de un Control Plane Node (Master)

El Diagnóstico Inicial: ¿Funciona kubectl?

El primer paso siempre es probar si la "puerta principal" (el kube-apiserver) está abierta.

  • Escenario A (kubectl SÍ responde): Si puedes ejecutar comandos, el problema está en otro componente (Scheduler, Controller Manager o red).

    • Ejecuta: kubectl get pods -n kube-system
    • Busca cualquier Pod central que esté en CrashLoopBackOff, Pending o Error. Revisa sus logs con kubectl logs -n kube-system <nombre-del-pod>.

  • Escenario B (kubectl NO responde):

    Si recibes el terrorífico error: The connection to the server <IP>:6443 was refused..., significa que tu API Server ha muerto. Ya no puedes usar kubectl. Debes entrar por SSH al nodo Master inmediatamente.

El Secreto del Control Plane: Los Pods Estáticos

En un clúster estándar creado con kubeadm, los componentes del cerebro (kube-apiserver, etcd, kube-scheduler, kube-controller-manager) NO son gestionados por Kubernetes como Deployments normales. Son Pods Estáticos.

  • El Kubelet del nodo Master lee directamente una carpeta física en el disco y arranca los contenedores que encuentre ahí.

  • La Carpeta Mágica (¡Memorízala para el CKA!): /etc/kubernetes/manifests/

  • Regla de Oro: Si modificas un YAML en esta carpeta y cometes un error de sintaxis (un espacio de más, un flag mal escrito), el Kubelet matará el componente y no lo volverá a levantar hasta que arregles el archivo.

Herramientas de Supervivencia (Cuando el API Server cae)

Si kubectl está muerto, dependes de las herramientas nativas del sistema operativo y del motor de contenedores:

  • A. Revisar el Kubelet: Al igual que en un Worker, el Kubelet es quien mantiene vivos los pods estáticos.

    • systemctl status kubelet
    • journalctl -u kubelet -n 50 (Busca errores de lectura de manifiestos).

  • B. Usar crictl (Tu salvavidas en el examen): crictl es la CLI para hablar directamente con containerd sin usar Kubernetes.

    • Ver qué contenedores están corriendo a bajo nivel: crictl ps
    • Ver todos los contenedores (incluso los muertos): crictl ps -a
    • Ver los logs del API Server o etcd que está fallando: crictl logs <container-id>

Causas Más Comunes de Falla en el Control Plane

  1. Errores de configuración humana (Typos): Alguien editó /etc/kubernetes/manifests/kube-apiserver.yaml para agregar un flag de seguridad (muy común en el CKS) y se equivocó en una letra.

  2. Certificados Expirados: Los componentes internos usan certificados para hablar entre ellos. Si expiran, el clúster se paraliza.

    • Comando de diagnóstico: kubeadm certs check-expiration

  3. Etcd sin espacio: Si la máquina virtual del Master se queda sin espacio en disco (df -h), la base de datos etcd se corrompe o se detiene para protegerse. Si etcd cae, el API Server también lo hará.

Tips de Velocidad (Modo Examen CKA/CKS)

  • Haz Backups antes de tocar: Si el examen te pide modificar un Pod estático del Control Plane, NUNCA edites el YAML original directamente. Cópialo a otro lado primero:
    cp /etc/kubernetes/manifests/kube-apiserver.yaml /root/kube-apiserver.yaml.backup

  • No reinicies el servidor: Si arreglas un manifiesto en /etc/kubernetes/manifests/, no necesitas reiniciar el servicio Kubelet. El Kubelet detecta el cambio en el archivo y reinicia el Pod automáticamente en unos 20-30 segundos.

Troubleshooting de un Worker Node

El Diagnóstico Inicial (Desde el Control Plane)

Antes de saltar al nodo defectuoso, pregúntale al clúster qué es lo que ve. Todo empieza desde tu terminal con acceso a kubectl.

  • Identificar el estado: kubectl get nodes (Buscas el nodo que diga NotReady).

  • Inspeccionar los eventos del Nodo:

    kubectl describe node <nombre-del-nodo>
    ¿Qué buscar aquí? Ve directo a la sección Conditions. Debes revisar si hay MemoryPressure, DiskPressure, PIDPressure o si el estatus de Ready dice False o Unknown. Al final de la salida, mira la sección Events para ver si el API Server perdió comunicación con el nodo.

La Conexión (El salto al problema)

Si el nodo está NotReady, kubectl ya no te servirá para arreglarlo internamente. Tienes que entrar a la máquina física o virtual.

  • ssh <usuario>@<ip-del-worker-node>

La Santísima Trinidad del Worker Node

Una vez dentro del nodo defectuoso, debes revisar los tres componentes que lo mantienen vivo. Si uno falla, el nodo cae.

A. El Kubelet (El Capitán del Nodo)

Es el agente que habla con el API Server. El 90% de las veces, el problema está aquí.

  • Ver si está corriendo: systemctl status kubelet

  • Si está fallando (rojo/dead), LEE LOS LOGS (Comando de oro para el CKA):
    journalctl -u kubelet -f

  • Problemas comunes del Kubelet:

  • El archivo de configuración /var/lib/kubelet/config.yaml tiene un error de sintaxis.
  • Los certificados /var/lib/kubelet/pki/ expiraron y no puede autenticarse.

B. El Container Runtime (El Motor)

Kubernetes no corre contenedores, se lo pide a containerd (o CRI-O). Si el motor está apagado, el Kubelet entra en pánico.

  • Ver si está corriendo: systemctl status containerd
  • Revisar logs: journalctl -u containerd

C. El Sistema Operativo (El Entorno)

Kubernetes es muy estricto con el entorno Linux.

  • Swap: Si alguien activó la memoria Swap por error, el Kubelet se negará a arrancar.

  • Revisar: free -h o swapon --show.

  • Solucionar temporalmente: swapoff -a.

  • Puertos ocupados: Asegúrate de que los puertos requeridos (ej. 10250 para Kubelet) no estén siendo bloqueados por un firewall u ocupados por otro proceso.

  • Espacio en disco lleno: df -h (Si el disco llega al 100%, el nodo expulsará Pods o morirá).

Problemas de Red (El CNI Plugin)

A veces el nodo dice Ready, pero los Pods dentro de él se quedan estancados en ContainerCreating.

  • Esto suele indicar que el plugin de red (Calico, Flannel, Weave) falló en ese nodo.
  • Revisión rápida: Verifica si existe configuración de red en /etc/cni/net.d/. Si la carpeta está vacía o el archivo está corrupto, el nodo no podrá asignar IPs a los Pods.

Tips de Velocidad (Modo Examen CKA)

  1. Grep es tu mejor amigo: Cuando uses journalctl -u kubelet, la salida será gigantesca. Filtra los errores para ir rápido:
    journalctl -u kubelet | grep -i error

  2. Reinicia el servicio: Si haces un cambio en la configuración del Kubelet, ¡no olvides reiniciarlo! Si no lo haces, seguirás viendo el error y perderás tiempo:
    systemctl daemon-reload
    systemctl restart kubelet

  3. Permisos: Asegúrate de ejecutar systemctl y journalctl con sudo o como usuario root dentro del worker node.