Kubernetes: fallos ocultos que tumban el control plane

En ForgeNEX trabajamos con pymes que confían en Kubernetes para mantener sus servicios críticos en marcha. La disponibilidad del control plane no depende solo de que los componentes estén vivos, sino de cómo interactúan bajo presión. Un artículo reciente de The New Stack describe tres escenarios en los que un mecanismo aparentemente correcto se convierte en el amplificador de un fallo local. No es teoría: son casos reales que pueden afectar a cualquier equipo que gestione clústeres, incluso de tamaño moderado.

El efecto amplificador en el control plane

La idea central es que, a escala, un componente no necesita caerse para contribuir a una caída. Un mecanismo válido puede amplificar un defecto local a través de metadatos compartidos, trabajos de inicio sincronizados o comprobaciones de salud demasiado agresivas. Por ejemplo, un informer proporciona a un controlador una vista local del estado del clúster para que sus workers avancen sin consultar repetidamente al API server. Esto es eficiente cuando los controladores arrancan de forma independiente. Pero si muchos controladores se reinician a la vez en una flota grande, la reconstrucción de esas vistas puede generar una presión significativa sobre el control plane. El propio mecanismo del informer se convierte en el amplificador.

Tres casos que deberías conocer

El artículo examina tres situaciones concretas. En la primera, un servidor de API de extensión publicó un esquema inválido tras actualizar una dependencia, y bloqueó a clientes que nunca habían usado su API. En la segunda, agentes DaemonSet se reiniciaron en una flota grande, convirtiendo el trabajo de arranque rutinario en una tormenta de peticiones que el API server no pudo absorber. En la tercera, una comprobación de liveness profunda en un componente de la ruta de peticiones de la API trató una caída de dependencia como un fallo del proceso y provocó reinicios repetidos mientras la dependencia seguía caída.

Estos casos importan a equipos que ejecutan API de extensión, controladores que vigilan grandes colecciones de objetos y componentes en la ruta de peticiones que dependen de comprobaciones profundas de dependencias.

1. Servidores de API de extensión: cómo una actualización de dependencia rompió clientes no relacionados

En uno de los clústeres, los despliegues de Helm empezaron a fallar para charts que solo contenían recursos estándar de Kubernetes. Los charts no tenían relación con la API de extensión que causó el fallo. Usuarios que nunca habían oído hablar de esa extensión veían errores de validación antes de que sus peticiones llegaran al API server. La ruta de fallo pasaba por los metadatos, a través de un documento de esquema que combinaba definiciones de las API registradas en el clúster.

Para entender por qué, hay que saber cómo Kubernetes expone los metadatos de API a los clientes. Kubernetes se puede extender mediante servidores de API agregados, que añaden nuevas API sin modificar el API server principal. Para los usuarios, una API agregada parece nativa: tiene grupo, versión, tipo y rutas de recursos, y kubectl accede a ella a través del endpoint normal del clúster. Un servidor de API de extensión genera un esquema OpenAPI que describe sus objetos y campos. Los clientes recuperan este esquema para entender y validar los recursos antes de enviar peticiones.

OpenAPI v2 y v3: Kubernetes expone este contrato de esquema en dos formas, y la diferencia determina el radio de impacto de una extensión rota. OpenAPI v2 es un único documento combinado disponible en /openapi/v2, que contiene definiciones del API server principal y de las API de extensión agregadas. OpenAPI v3 separa los esquemas por grupo y versión de API. Esa separación reduce el impacto porque los clientes que usan la API principal no necesitan recuperar el documento de cada extensión. El formato v2 crea un dominio de fallo compartido: una definición inválida de una extensión puede impedir que los clientes analicen el documento utilizado para validar recursos no relacionados.

Nombres de modelo OpenAPI explícitos: la PR #131755 de Kubernetes hizo explícitos los nombres de modelo OpenAPI. Antes de este cambio, Kubernetes podía derivar un nombre de modelo a partir de una ruta de paquete Go. Eso facilitaba empezar con un esquema válido, pero también ataba los nombres publicados a detalles de implementación. Mover código o reorganizar paquetes podía cambiar un nombre que los clientes OpenAPI veían. El enfoque más reciente permite a los autores de API declarar un paquete de modelo estable, y la generación de código utiliza ese valor declarado al construir definiciones y referencias de esquema.

Antes del cambio, un esquema podía exponer una definición derivada de la ruta de paquete Go sin procesar. Después del cambio, una vez que el paquete declara un espacio de nombres de modelo OpenAPI, la misma definición utiliza un nombre explícito y estable. Una declaración ausente: un servidor de API de extensión actualizó la dependencia de la maquinaria de API de Kubernetes sin incluir la anotación +k8s:openapi-model-package requerida por la nueva generación de nombres de modelo. Su código generado siguió proporcionando rutas de paquete Go sin procesar al construir definiciones de esquema. La maquinaria de API anterior transformaba esas rutas en nombres seguros para OpenAPI; el comportamiento más reciente espera que la extensión proporcione un paquete de modelo declarado. Sin esa declaración, la extensión comenzó a publicar rutas de paquete sin procesar como identificadores de modelo OpenAPI. Como esas rutas contienen /, hicieron que el esquema resultante fuera inválido. El servidor de extensión arrancó correctamente y siguió sirviendo su API. Las comprobaciones de salud del proceso no validan el documento OpenAPI que publica un proceso. El problema apareció en clientes que leen OpenAPI v2. Debido a que v2 combina los esquemas de API en un solo documento, una definición inválida de una extensión puede hacer que un cliente informe un error antes de enviar la llamada API solicitada, incluso cuando el recurso solicitado pertenece a otra API. El comportamiento de Helm hizo esto especialmente visible. Dependiendo de la versión de Helm, el comando y la configuración de validación, Helm recupera el documento OpenAPI v2 antes de aplicar un chart. Un chart que usa solo recursos ordinarios de Kubernetes puede fallar porque una API agregada no relacionada publica un esquema inválido. Los clientes que usan v3 para recursos principales siguen una ruta más estrecha.

Qué significa para una pyme y qué recomendamos

Si gestionas un clúster Kubernetes, aunque sea pequeño, estos fallos pueden afectar a tus despliegues y a la disponibilidad de tus servicios. La buena noticia es que se pueden mitigar con prácticas concretas. En ForgeNEX recomendamos:

• Revisa tus servidores de API de extensión: si usas API agregadas, asegúrate de que declaran explícitamente el paquete de modelo OpenAPI (+k8s:openapi-model-package) y que generan esquemas válidos. No basta con que el proceso esté vivo; valida el esquema OpenAPI que publica.
• Prioriza OpenAPI v3: cuando sea posible, utiliza clientes y herramientas que consuman OpenAPI v3 para reducir el dominio de fallo compartido. Si dependes de v2, ten en cuenta que un error en una extensión puede bloquear operaciones no relacionadas.
• Controla el arranque de controladores: evita reinicios masivos y sincronizados de controladores que reconstruyen vistas locales (informer). Escalona los despliegues y considera límites de tasa para proteger el API server.
• Diseña comprobaciones de salud adecuadas: no conviertas una caída de dependencia en un fallo del proceso con liveness probes demasiado profundas. Usa readiness para dependencias y evita reinicios en cascada.
• Monitoriza la ruta crítica: observa no solo la salud de los procesos, sino también la validez de los metadatos que publican y el impacto en los clientes.

En un entorno de pyme, donde los equipos son pequeños y los recursos limitados, estos detalles marcan la diferencia entre un incidente controlado y una caída prolongada. Si necesitas ayuda para revisar tu configuración de Kubernetes, en ForgeNEX podemos ayudarte. También puedes leer nuestros artículos sobre KubeVirt y el futuro de las VMs en Kubernetes o sobre agentes de IA que se escapan para estar al día en tendencias de infraestructura.

Fuente: The New Stack. Análisis y adaptación: ForgeNEX.