Construcción de APIs dinámicas en Kubernetes sin controladores personalizados

En una publicación en el blog de Kubernetes en noviembre de 2024, Andrei Kvapil de Ænix detalló cómo su equipo construyó un servidor de API de extensión dinámica para Cozystack. El artículo explora la implementación técnica de la capa de agregación de la API de Kubernetes, contrastándola con las Definiciones Personalizadas de Recursos (CRDs) y los operadores estándar.

Qué ocurrió

Kvapil explicó que, aunque la mayoría de las extensiones de Kubernetes dependen de CRDs y controladores, este enfoque tiene limitaciones para casos de uso específicos. Los operadores estándar sobresalen en la reconciliación declarativa de estados, pero tienen dificultades con la lógica imperativa, la generación de datos en tiempo real o los requisitos complejos de validación. Para abordar estas carencias, el equipo de Cozystack implementó un servidor de API de extensión personalizado que se integra directamente en el marco de la API de Kubernetes a través de la capa de agregación.

El núcleo de esta implementación implica registrar un objeto APIService dentro del clúster. Este registro indica al servidor principal de la API de Kubernetes que reenvíe las solicitudes para grupos de recursos específicos al servidor de extensión externo. En el caso de Cozystack, esto permitió a la plataforma exponer dinámicamente nuevos tipos de recursos basados en los charts de Helm disponibles sin requerir cambios en el código ni recompilación. El sistema asigna tipos intuitivos para el usuario, como Postgres o Redis, directamente a releases subyacentes de Helm, abstrayendo la complejidad para los usuarios finales.

Este enfoque también resolvió importantes desafíos de RBAC. El Control Basado en Roles (RBAC) estándar de Kubernetes no puede filtrar operaciones de listado por etiquetas o campos específicos de la especificación, solo por nombres de recursos. Al generar distintos tipos de recursos para cada tipo de servicio, Cozystack pudo aprovechar las políticas nativas de RBAC para restringir el acceso con precisión. Además, el servidor de extensión maneja la conversión bidireccional entre los nuevos tipos personalizados y los recursos internos HelmRelease, garantizando la compatibilidad hacia atrás con paneles de control y herramientas existentes.

Cómo funciona

La capa de agregación de la API actúa como un proxy dentro del plano de control de Kubernetes. Cuando un usuario envía una solicitud a la API de Kubernetes para un grupo de recursos atendido por una extensión, el servidor principal de la API reenvía esa solicitud al servidor de API de extensión. Este servidor opera independientemente de los componentes principales del plano de control y puede implementar su propia lógica de negocio, validación y mecanismos de almacenamiento.

A diferencia de los controladores estándar que sincronizan el estado con etcd, un servidor de API de extensión puede generar respuestas sobre la marcha. Esto es similar a cómo funciona metrics-server, obteniendo datos en tiempo real de los Kubelets en lugar de almacenarlos. En el caso de Cozystack, el servidor descubre dinámicamente los servicios disponibles y los registra como recursos de la API. Valida las entradas, las convierte en objetos HelmRelease y los envía al clúster, manteniendo todo ello una separación clara entre la API orientada al usuario y la implementación interna.

Detalles clave

• La capa de agregación de la API permite que los servidores de extensión manejen lógica imperativa y subrecursos como /exec o /log.
• Las APIs de extensión se registran mediante un objeto APIService, que dirige el tráfico de grupos de API específicos al servidor externo.
• A diferencia de las CRDs, los servidores de extensión no necesitan almacenar estado en etcd, lo que habilita la generación de datos en tiempo real y reduce la sobrecarga de almacenamiento.
• Cozystack utiliza este modelo para mapear dinámicamente tipos de servicio como Postgres a charts de Helm subyacentes sin recompilar código.
• La implementación admite validación compleja en el lado del servidor y formatos de salida de tabla personalizados más allá de las capacidades de las CRDs.
• Los servidores de extensión inestables pueden bloquear la eliminación de namespaces o causar latencia en la API, por lo que la fiabilidad es crítica.

Por qué importa

Para los ingenieros de plataforma, comprender la capa de agregación abre patrones de diseño difíciles o imposibles de lograr solo con CRDs. Permite la creación de APIs que se comportan como recursos nativos de Kubernetes pero operan con lógica imperativa o backends externos. Esto es particularmente útil para integrar sistemas heredados, exponer métricas en tiempo real o crear interfaces simplificadas para aplicaciones complejas.

Sin embargo, este poder conlleva riesgos operacionales. Si un servidor de API de extensión se vuelve inaccesible, puede degradar el rendimiento de todo el clúster. Operaciones como la eliminación de namespaces pueden colgarse mientras esperan que la extensión confirme la limpieza de recursos. Los ingenieros deben sopesar los beneficios del comportamiento de API personalizado frente a la complejidad añadida y los posibles impactos en la estabilidad de ejecutar servidores de API adicionales.

Qué puedes hacer

• Evalúa si tu caso de uso requiere lógica imperativa o datos en tiempo real antes de elegir entre CRDs y una API de extensión.
• Usa APIService para registrar la extensión y dirigir el tráfico de grupos de API específicos al servidor externo.