Kubernetes SysAdmin: Guía Práctica de Troubleshooting Diario

La primera vez que me encontré ante un clúster de Kubernetes en producción, la impresión fue la de un sistema alienígena. 40 namespaces, 300 pods, ninguna documentación clara. El pánico fue mi primer compañero de viaje. Luego entendí: Kubernetes no es un monstruo, sino un ecosistema con sus propias reglas. Y la buena noticia es que el 70% de los problemas se resuelven con kubectl describe y el resto leyendo atentamente los logs. Kubernetes no es complicado, solo es verboso. Esta guía es el fruto de años dedicados a desenredar pods en CrashLoopBackOff y servicios inalcanzables, condensando la experiencia en conceptos esenciales y comandos prácticos para todo SysAdmin que se adentra en este mundo.

En 2026, la adopción de Kubernetes es casi un estándar de facto para las aplicaciones cloud-native. Según la encuesta de la Cloud Native Computing Foundation (CNCF) de 2025, más del 90% de las organizaciones utilizan contenedores en producción, y Kubernetes es la plataforma de orquestación dominante. Ya no es una elección, sino a menudo una necesidad. Para un SysAdmin, comprender las bases de Kubernetes no es solo una ventaja, sino una competencia crítica para la gestión de la infraestructura moderna, ya sea on-premise sobre Proxmox o en la nube OCI.

Requisitos Previos / Entorno de Prueba

Para seguir esta guía, necesitarás acceso a un clúster de Kubernetes funcionando. Puedes utilizar un entorno de desarrollo como Minikube o Kind en tu portátil Linux, o un servicio de clúster gestionado en la nube (GKE, AKS, EKS). Asegúrate de tener kubectl configurado y autenticado con tu clúster. Usaremos un entorno Linux, pero los comandos kubectl son multiplataforma.

Kubernetes vs Docker: el cambio de paradigma

A menudo se confunde Kubernetes con Docker, pero son dos herramientas con propósitos diferentes y complementarios. Docker es un conjunto de herramientas para construir, ejecutar y gestionar contenedores individuales. Piensa en Docker como el motor de un coche. Kubernetes, en cambio, es un sistema de orquestación que gestiona un parque automovilístico completo. Se encarga de cómo los contenedores (los coches) se distribuyen, escalan, actualizan y cómo se comunican entre sí dentro de un clúster de máquinas (los nodos). Mientras Docker resuelve el problema del empaquetado de aplicaciones, Kubernetes resuelve el problema de la gestión de cientos o miles de instancias de estos paquetes en un entorno dinámico. Este cambio de paradigma es fundamental para abordar arquitecturas de microservicios y garantizar alta disponibilidad.

Arquitectura: control plane, worker node, etcd

Un clúster de Kubernetes está compuesto por dos tipos principales de nodos:

• Control Plane (Master Node): El cerebro del clúster. Contiene los componentes que toman las decisiones globales (scheduler, controller manager, API server) y el estado del clúster (etcd).
• Worker Nodes: Los músculos del clúster. Ejecutan las cargas de trabajo (tus pods) y contienen el Kubelet (agente que se comunica con el Control Plane) y un runtime de contenedores (ej. containerd, Docker).
• etcd: Una base de datos distribuida clave-valor que almacena el estado de configuración del clúster de Kubernetes, sus recursos y los datos. Es crítico para la estabilidad y la consistencia del clúster. Un etcd corrupto significa un clúster inutilizable. Su gestión requiere una atención particular, especialmente para las copias de seguridad y la resiliencia.

Para tener una visión general de los recursos del clúster, puedes usar:

kubectl get nodes -o wide
kubectl top nodes

El primer comando te dará una lista detallada de los nodos, el segundo te mostrará el uso de CPU y memoria para cada nodo, útil para identificar cuellos de botella o nodos sobrecargados.

Kubectl: los 20 comandos que usas cada día

kubectl es la CLI estándar para interactuar con un clúster de Kubernetes. Aquí tienes algunos de los comandos más útiles que todo SysAdmin debería conocer:

• kubectl get : Visualiza los recursos (ej. pod, deployment, service, node).
• kubectl describe : Muestra información detallada sobre un recurso específico. Es tu comando de troubleshooting por excelencia.
• kubectl logs : Visualiza los logs de un pod.
• kubectl exec -it -- : Ejecuta un comando dentro de un contenedor de un pod.
• kubectl apply -f : Aplica una configuración definida en un archivo YAML.
• kubectl delete : Elimina un recurso.
• kubectl scale deployment --replicas=: Escala un deployment.
• kubectl top pod: Muestra el uso de recursos de los pods.
• kubectl get events: Visualiza los eventos del clúster, útil para entender qué está sucediendo.

Para el troubleshooting, los siguientes comandos son oro:

# Troubleshooting pod
kubectl describe pod <nombre> -n <namespace>
kubectl logs <pod> --previous --tail=100
kubectl get events --sort-by=lastTimestamp

kubectl describe te dará información sobre el pod: eventos, estado, volúmenes, contenedores, límites de recursos. kubectl logs --previous es fundamental para ver los logs de la instancia anterior de un contenedor que ha fallado, mientras que kubectl get events te muestra lo que ha sucedido a nivel de clúster, útil para entender por qué un pod no ha sido programado o ha sido terminado. Según un informe de Red Hat de 2024, el 65% de los problemas de rendimiento en Kubernetes están relacionados con una configuración errónea de recursos o un registro insuficiente.

Pod, Deployment, Service, Ingress — relaciones prácticas

Estos son los bloques de construcción de Kubernetes:

• Pod: La unidad más pequeña y fundamental. Contiene uno o más contenedores que comparten red y almacenamiento. Los pods son efímeros y no deberían gestionarse directamente en producción.
• Deployment: Gestiona un conjunto de réplicas de pods. Asegura que un cierto número de pods esté siempre en ejecución y gestiona las actualizaciones de forma controlada (rolling update, rollback). Es el recurso que más usarás para tus aplicaciones.
• Service: Una forma de exponer un conjunto de pods como un servicio de red estable. Proporciona una IP y un nombre DNS que no cambian, incluso si los pods subyacentes se recrean. Existen varios tipos (ClusterIP, NodePort, LoadBalancer).
• Ingress: Gestiona el acceso externo a los servicios HTTP/HTTPS dentro del clúster. Funciona como un router inteligente, dirigiendo el tráfico según el nombre de host y la ruta URL. Sin Ingress, exponer múltiples servicios en la misma IP sería una pesadilla.

Esta jerarquía permite gestionar aplicaciones complejas de forma robusta y escalable. Una aplicación típica será un Deployment que gestiona los Pods, expuesta a través de un Service, y accesible desde el exterior a través de un Ingress.

Troubleshooting: pod en CrashLoopBackOff, Pending, OOMKilled

Estos son algunos de los estados más comunes y frustrantes en los que un pod puede encontrarse:

• CrashLoopBackOff: El contenedor en el pod está fallando repetidamente y Kubernetes está intentando reiniciarlo. Las causas pueden ser múltiples: error en la aplicación, configuración errónea, problemas de dependencias. Usa kubectl describe pod para ver los eventos y kubectl logs --previous para los logs del fallo.
• Pending: El pod no ha sido programado en ningún nodo. A menudo se debe a recursos insuficientes (CPU, memoria) en los nodos, o a node selectors/tolerations que impiden la programación. kubectl describe pod te dirá el motivo preciso en la sección ‘Events’.
• OOMKilled (Out Of Memory Killed): El contenedor ha superado los límites de memoria asignados y el kernel de Linux lo ha terminado. Esto es una señal de que los resource limits son demasiado bajos o la aplicación tiene una fuga de memoria. Comprueba kubectl describe pod y los logs de la aplicación.

Otro comando útil para interactuar directamente con un contenedor para la depuración es:

# Ejecutar en contenedor
kubectl exec -it <pod> -- /bin/bash

Esto te permite entrar en el contenedor e investigar como lo harías en una VM, comprobando archivos, variables de entorno, etc.

Resource limits y requests: el fundamental ignorado

Una de las causas más comunes de inestabilidad en los clústeres de Kubernetes es la falta o la configuración errónea de los resource limits y requests para CPU y memoria. Las requests indican la cantidad mínima de recursos que el pod solicita y que el scheduler intentará garantizar. Los limits indican la cantidad máxima de recursos que un pod puede consumir. Si un pod supera sus límites de memoria, se termina (OOMKilled). Si supera los límites de CPU, se ralentiza.

Ignorar estos parámetros puede llevar a:

• Inestabilidad: Pods que fallan sin motivo aparente.
• Rendimiento impredecible: Aplicaciones lentas o que no responden.
• Agotamiento de los recursos del nodo: Un solo pod codicioso puede monopolizar los recursos y causar problemas a otros pods en el mismo nodo.

Definir estos valores es un ejercicio de optimización continuo, pero es una inversión que paga en estabilidad y previsibilidad. Un buen punto de partida es monitorear el uso efectivo de los recursos con kubectl top pods y kubectl top nodes y luego establecer los límites ligeramente por encima del pico de uso normal. Un estudio de DORA (DevOps Research and Assessment) de 2023 demostró que los equipos con una gestión precisa de los recursos de Kubernetes tienen un 40% menos de incidentes en producción.

# Encontrar pods con más recursos
kubectl top pods --all-namespaces --sort-by=memory

Este comando es un salvavidas para identificar rápidamente los pods que están consumiendo más recursos y podrían ser la causa de problemas.

Logs agregados: kubectl logs + stern

Gestionar los logs en Kubernetes puede ser complejo, especialmente en un entorno con cientos de pods que generan flujos de datos. kubectl logs es el punto de partida, pero para un análisis más profundo, existen herramientas como stern (un wrapper para kubectl logs) que permiten agregar los logs de múltiples pods o contenedores simultáneamente, con filtros y coloreado para facilitar la lectura. Implementar una solución de logging centralizada (ej. Fluentd/Fluent Bit con Elasticsearch/Loki) es crucial para el troubleshooting y el análisis forense en producción. Sin logs agregados y fácilmente consultables, diagnosticar un problema en un entorno distribuido se convierte en una tarea titánica.

Namespaces y RBAC: aislamiento básico

• Namespaces: Una forma de dividir lógicamente un clúster de Kubernetes en ‘clústeres virtuales’. Útiles para aislar entornos (dev, staging, prod) o equipos diferentes. Cada recurso vive dentro de un namespace. Esto evita colisiones de nombres y permite aplicar políticas de forma granular. Un clúster con 40 namespaces, como el que me encontré, es un buen ejemplo de cómo la separación lógica puede ayudar a mantener el orden.
• RBAC (Role-Based Access Control): El mecanismo de autorización en Kubernetes. Define quién (User, ServiceAccount) puede hacer qué (verbo: get, list, create, delete, update) sobre qué recursos (Pod, Deployment, Service) y en qué namespaces. Implementar un RBAC robusto es fundamental para la seguridad del clúster, siguiendo el principio del mínimo privilegio. Sin RBAC, un error de configuración puede exponer todo el clúster a riesgos significativos.

Errores Comunes y Resolución de Problemas

• Imágenes no encontradas (ImagePullBackOff): Comprueba el nombre de la imagen, la etiqueta y las credenciales del registro (si es privado). Asegúrate de que el pull secret esté configurado correctamente.
• Problemas de conectividad (network policies): Si los pods no pueden comunicarse, verifica las Network Policies. Pueden bloquear el tráfico de entrada o salida de forma inesperada. Una configuración errónea de las VLAN en entornos tradicionales puede tener un paralelo similar.
• Volúmenes persistentes (PV/PVC): Si un pod no puede montar un volumen, comprueba el estado del PersistentVolumeClaim y del PersistentVolume. Asegúrate de que el backend de almacenamiento sea accesible y funcione.
• API server no accesible: Si kubectl no responde, el problema probablemente esté en el Control Plane. Comprueba el estado de los componentes del Control Plane y la conectividad de red al clúster. Para más detalles sobre cómo funciona el API server de Kubernetes, consulta la documentación oficial de Kubernetes: https://kubernetes.io/docs/concepts/overview/components/#kube-apiserver

Conclusiones con Puntos Clave Operativos

Kubernetes, a pesar de la aparente complejidad, es una herramienta potente e indispensable para la gestión de las infraestructuras modernas. Para un SysAdmin, el mejor enfoque es concentrarse en los conceptos fundamentales y dominar los comandos esenciales de kubectl para el monitoreo y el troubleshooting. Recuerda: kubectl describe es tu mejor amigo, los logs son tu fuente de verdad, y una correcta definición de los resource limits te ahorrará noches de insomnio. No tengas miedo de experimentar en un entorno de prueba; es la forma más eficaz de familiarizarte y transformar el pánico inicial en control.

Lee también: Lynis Audit Linux: Guía Práctica de Hardening 2026