Marcio Cunha

Pods bloqueados en Terminating? Cómo forzar su eliminación

Tus pods se han quedado atascados en estado Terminating? Entiende por qué ocurre esto y cómo usar flags de bypass para limpiar el cluster.

Marcio Cunha•2 min
También disponible en:EnglishPortuguês
Resumen
  • Los pods atascados en estado Terminating generalmente ocurren por finalizadores pendientes de controladores externos.
  • La API de Kubernetes bloquea la eliminación del objeto hasta que todos sus finalizadores sean procesados.
  • El uso de la flag --force permite ignorar la espera por el procesamiento de los finalizadores pendientes.
  • Identificar la causa raíz en el nivel del namespace o de los CRDs evita reincidencias en el cluster.
  • Eliminar pods a la fuerza debe ser la última alternativa tras garantizar que no haya procesos de I/O críticos.

Por qué los pods se bloquean en el estado Terminating?

Quien trabaja con Kubernetes seguramente ha pasado por la frustración de borrar un pod y verlo permanecer en estado Terminating indefinidamente. En la práctica, esto sucede porque Kubernetes posee un mecanismo de seguridad llamado finalizadores (finalizers). Son llaves que impiden que un recurso sea eliminado antes de que ciertas tareas de limpieza se completen, como el desmontaje de un volumen de red o la eliminación de registros en una base de datos.

Cuando un controlador externo falla al limpiar estos recursos, el pod queda esperando eternamente por una señal que nunca llegará. Es el equivalente a tener un proceso bloqueado en Windows esperando una respuesta de una unidad de red desconectada. Si ya intentaste comandos comunes sin éxito, debes saber que es un bloqueo de protección y no solo un error aleatorio del cluster.

El papel de los finalizadores en el ciclo de vida

Los finalizadores son piezas esenciales para la integridad de sistemas distribuidos. Garantizan que, al eliminar una aplicación, todos los recursos dependientes sean debidamente liberados, evitando basura o corrupción de datos. Sin embargo, en escenarios de alta complejidad, un CRD (Custom Resource Definition) o un agente de red mal configurado puede mantener este bloqueo activo.

Antes de forzar la eliminación, es vital investigar qué está reteniendo el recurso. Muchas veces, un pod bloqueado es solo el síntoma de una falla de comunicación entre el plano de control de Kubernetes y los nodos, algo similar a lo que discutimos en nuestra guía sobre cómo debuguear el CNI en Kubernetes. Si el nodo no responde, el kubelet no puede confirmar la finalización.

Cómo forzar la eliminación de un pod vía kubectl

Cuando la intervención manual es inevitable, Kubernetes ofrece una forma de bypass. El siguiente comando fuerza la eliminación inmediata, ignorando el tiempo de espera estándar y la verificación de los finalizadores pendientes. Recuerda reemplazar los nombres según tu entorno actual:

kubectl delete pod <nombre-del-pod> --namespace <nombre-del-namespace> --force --grace-period=0

La flag --force junto con --grace-period=0 instruye al cluster a eliminar el objeto de la memoria de etcd inmediatamente, sin esperar el proceso de cierre normal. Es una medida drástica que debe usarse con precaución, ya que estás saltando el protocolo de seguridad definido por los controladores. Para complementar esta implementación en entornos de producción, consulte también nuestros análisis técnicos sobre NGINX lento? Cómo monitorear conexiones con stub_status y Pipeline de GitLab CI bloqueado? Cómo cancelar jobs.

Limpiando los finalizadores manualmente vía patch

Si la eliminación forzada no funciona, la alternativa es editar el recurso para eliminar los finalizadores manualmente. Esto puede hacerse a través de un comando patch en la API, que elimina la lista de finalizadores del objeto, liberando a Kubernetes para borrarlo instantáneamente:

kubectl patch pod <nombre-del-pod> -p '{