Saltar al contenido principal

Debug de pods con Ephemeral Containers

Kubernetes Header

A veces el pod no tiene curl, ni ping, ni un shell decente porque está construido con una imagen mínima (distroless, scratch, alpine recortada). Cuando algo falla en producción no quieres reconstruir la imagen ni redeployar solo para meter herramientas: para eso existen los Ephemeral Containers.

Un ephemeral container es un contenedor que se agrega temporalmente a un pod en ejecución para diagnosticar problemas. Comparte los namespaces de red y proceso del pod, por lo que ves su tráfico, sus archivos abiertos, sus variables — pero no necesita estar declarado en el manifiesto original.

Crear un debug container con kubectl debug​

La forma más común de usarlos es a través de kubectl debug:

kubectl debug buggypod --image=debian --attach

Lo que hace este comando:

  • Inyecta un contenedor temporal con la imagen debian dentro del pod buggypod.
  • --attach te conecta de inmediato a su salida.
  • Al ser un contenedor más en el pod, puedes hacer curl, dig, tcpdump, etc., contra los servicios que el pod ve.

Opciones útiles:

# Compartir el namespace de proceso para ver los PIDs de los otros containers
kubectl debug buggypod --image=nicolaka/netshoot \
  --target=app --share-processes -it

# Crear una copia del pod con un container extra, sin tocar el original
kubectl debug buggypod -it --copy-to=buggypod-debug --image=busybox

Para usar --target el cluster debe permitir compartir process namespace, y la versión de Kubernetes debe ser ≥ 1.25 para que ephemeralContainers esté GA.

Por qué falla con frecuencia: certificados y red​

Cuando estés depurando comunicación entre pods o hacia servicios externos, antes de culpar al código revisa la capa de transporte:

  • Certificados SSL/TLS vencidos o no confiados por la imagen base.
  • Nombres DNS que no resuelven (CoreDNS, search del resolv.conf).
  • NetworkPolicies que bloquean el tráfico saliente.
  • Puertos cerrados en el firewall del nodo.

El ephemeral container con nicolaka/netshoot viene con dig, nslookup, curl, openssl s_client, tcpdump y casi cualquier herramienta de red que necesites.

RBAC: lo que necesitas para usar kubectl debug​

Para crear ephemeral containers, la cuenta que ejecuta kubectl debug necesita permisos sobre el subrecurso pods/ephemeralcontainers. Algunas combinaciones típicas de RBAC son:

  • Role + RoleBinding → permisos limitados a un namespace.
  • ClusterRole + ClusterRoleBinding → permisos globales en el cluster.
  • ClusterRole + RoleBinding → reutilizas un ClusterRole pero restringes su alcance a un namespace concreto.

Ejemplo mínimo para permitir debug en un namespace:

apiVersion: rbac.authorization.k8s.io/v1
kind: Role
metadata:
  namespace: app
  name: debugger
rules:
  - apiGroups: [""]
    resources: ["pods", "pods/ephemeralcontainers"]
    verbs: ["get", "list", "update", "patch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: RoleBinding
metadata:
  namespace: app
  name: debugger
subjects:
  - kind: User
    name: oncall
    apiGroup: rbac.authorization.k8s.io
roleRef:
  kind: Role
  name: debugger
  apiGroup: rbac.authorization.k8s.io

Con esto el usuario oncall puede ejecutar kubectl debug contra cualquier pod del namespace app sin tener permisos elevados en el resto del cluster.

Resumen​

Los ephemeral containers son el sustituto moderno de "entrar al pod a depurar". No requieren rebuild, no quedan registrados en el manifiesto y se eliminan cuando el pod muere. Combínalos con una imagen como netshoot o busybox y tendrás una caja de herramientas lista para los incidentes del día a día.