Versiones Kubernetes Gateway API: Guía Completa de Compatibilidad y Actualización

Publicado: 2 de febrero de 2026 · Por Alexandre Vazquez

La Kubernetes Gateway API ha madurado a un ritmo notable: de sus orígenes experimentales ha pasado a convertirse en el estándar de facto para la gestión del tráfico de ingress y service mesh. Sin embargo, con varias versiones publicadas y distintos niveles de madurez en cada una de ellas, entender qué versión utilizar, cómo se relaciona con tu clúster de Kubernetes y cuándo actualizar puede resultar complejo.

Esta guía de referencia cubre en profundidad las versiones de Gateway API disponibles, su relación con las versiones de Kubernetes, los niveles de soporte de los principales proveedores y la filosofía de actualización que te permitirá tomar decisiones fundamentadas para tu infraestructura.

Entendiendo el modelo de versionado de Gateway API

El modelo de versionado de Gateway API es deliberadamente distinto al de las APIs nativas de Kubernetes. Mientras que los recursos integrados en Kubernetes están ligados a una versión concreta del clúster, los CRDs de Gateway API se instalan de forma independiente siempre que el clúster cumpla los requisitos mínimos.

Esta independencia tiene implicaciones prácticas importantes: puedes actualizar Gateway API sin necesidad de actualizar Kubernetes y, a la inversa, actualizar Kubernetes sin que eso fuerce un cambio en tus CRDs de Gateway API. Son dos ciclos de vida desacoplados que hay que gestionar de forma coordinada, pero no sincronizada obligatoriamente.

Requisitos mínimos de versión de Kubernetes

A partir de Gateway API v1.1 y versiones posteriores, el requisito mínimo es Kubernetes 1.26 o superior. El proyecto se compromete a mantener soporte para un mínimo de las últimas 5 versiones menores de Kubernetes, lo que ofrece una ventana razonable para planificar las actualizaciones del clúster.

Esto significa que si ejecutas Kubernetes 1.26, 1.27, 1.28, 1.29 o 1.30, puedes instalar la última versión de Gateway API sin preocuparte por incompatibilidades. Para la mayoría de los equipos que mantienen sus clústeres relativamente actualizados, esta restricción rara vez supone un problema.

Canales de publicación: Standard y Experimental

Gateway API utiliza dos canales de publicación diferenciados para equilibrar estabilidad e innovación. Comprender cuándo usar cada uno es fundamental antes de instalar o actualizar los CRDs.

Canal Standard

El canal Standard contiene únicamente recursos y campos a nivel GA (Generally Available, v1) y Beta (v1beta1). Al instalar desde el canal Standard obtienes:

Garantías de estabilidad: no se introducen cambios disruptivos una vez que un recurso alcanza Beta o GA
Compatibilidad hacia atrás: es seguro actualizar entre versiones menores sin modificar tus configuraciones existentes
Preparación para producción: funcionalidades ampliamente probadas con múltiples implementaciones
Cobertura de conformance: las pruebas de conformance completas garantizan portabilidad entre implementaciones

Los recursos incluidos en el canal Standard son GatewayClass, Gateway, HTTPRoute y ReferenceGrant a nivel v1, además de recursos estabilizados como GRPCRoute.

Canal Experimental

El canal Experimental incluye todo lo del canal Standard más recursos Alpha y campos experimentales. Este canal está orientado a:

Pruebas tempranas de funcionalidades: acceder a nuevas capacidades antes de que se estabilicen
Funcionalidad de vanguardia: probar las últimas novedades de Gateway API
Sin garantías de estabilidad: pueden producirse cambios disruptivos entre versiones
Retroalimentación al proyecto: contribuir a dar forma a la API mediante la prueba de características experimentales

Las funcionalidades pueden graduarse del canal Experimental al Standard, o bien ser descartadas, en función de la experiencia de implementación y la retroalimentación de la comunidad.

Recomendación: salvo que tengas una necesidad concreta de una característica experimental, utiliza siempre el canal Standard en entornos de producción.

Historial de versiones y funcionalidades de Gateway API

v1.0 (octubre de 2023)

La versión 1.0 marcó un hito importante al graduar los recursos principales al nivel GA. Este lanzamiento incluyó:

Gateway, GatewayClass y HTTPRoute a nivel v1 (estables)
Garantías de compatibilidad hacia atrás para los recursos v1
Estado de preparación para producción en la gestión del tráfico de ingress
Múltiples implementaciones conformes de distintos fabricantes

Con v1.0 se estableció que Gateway API estaba lista para cargas de trabajo productivas, dejando de ser un experimento para convertirse en una apuesta seria del ecosistema Kubernetes.

v1.1 (mayo de 2024)

La versión 1.1 amplió significativamente la API con soporte para service mesh:

GRPCRoute: soporte nativo para el enrutamiento de tráfico gRPC
Capacidades de service mesh: gestión del tráfico este-oeste junto al norte-sur
Múltiples implementaciones: tanto Istio como otros service mesh alcanzaron conformance
Funcionalidades mejoradas: criterios de coincidencia adicionales y capacidades de enrutamiento avanzadas

Esta versión cerró la brecha entre los controladores de ingress tradicionales y las implementaciones completas de service mesh, consolidando Gateway API como una solución unificada para ambos casos de uso.

v1.2 y v1.3

Estas versiones intermedias introdujeron ciclos de publicación más estructurados y funcionalidades adicionales:

Refinamiento de las pruebas de conformance
BackendTLSPolicy (experimental en v1.3)
Mejoras en observabilidad y depuración
Enrutamiento entre namespaces mejorado

v1.4 (octubre de 2025)

La última versión GA disponible en el momento de escribir esta guía, v1.4.0, incorporó:

Refinamiento continuado de la API
Funcionalidades experimentales adicionales para la comunidad
Perfiles de conformance mejorados
Documentación y guías de migración más completas

Matriz de compatibilidad: Gateway API vs. Kubernetes

La siguiente tabla muestra la relación entre versiones de Gateway API y versiones de Kubernetes:

Versión Gateway API	Kubernetes mínimo	Kubernetes recomendado	Fecha de publicación
v1.0.x	1.25	1.26+	Octubre 2023
v1.1.x	1.26	1.27+	Mayo 2024
v1.2.x	1.26	1.28+	2024
v1.3.x	1.26	1.29+	2024
v1.4.x	1.26	1.30+	Octubre 2025

La conclusión clave de esta tabla es que Gateway API v1.1 y versiones posteriores requieren Kubernetes 1.26 como mínimo. Esto significa que en cualquier clúster medianamente actualizado puedes ejecutar la última versión de Gateway API sin restricciones de compatibilidad con Kubernetes en sí.

Niveles de soporte de los proveedores

Los distintos proveedores (implementaciones de Gateway API) soportan versiones y conjuntos de funcionalidades diferentes. Entender el nivel de soporte de tu proveedor es tan importante como conocer la versión de Gateway API que quieres instalar.

Niveles de conformance

Gateway API define tres niveles de conformance para las funcionalidades:

Core: funcionalidades que toda implementación debe soportar para afirmar conformance. Son portables entre todas las implementaciones.
Extended: funcionalidades opcionales estandarizadas. Las implementaciones indican soporte Extended de forma separada al Core.
Implementation-specific: funcionalidades propias del fabricante sin requisitos de conformance.

Esta jerarquía te permite razonar sobre portabilidad: si usas únicamente funcionalidades Core, puedes cambiar de proveedor sin reescribir tus recursos de Gateway API.

Soporte de los principales proveedores

Istio

Istio alcanzó el soporte GA de Gateway API en su versión 1.22 (mayo de 2024). Istio ofrece:

Soporte completo del canal Standard (recursos v1)
Gestión del tráfico de service mesh (este-oeste) mediante GAMMA
Control del tráfico de ingress (norte-sur)
Soporte experimental de BackendTLSPolicy a partir de Istio 1.26

Istio es la opción preferida para organizaciones que necesitan tanto ingress como service mesh en una única solución, dado su nivel de madurez y su amplia adopción.

Envoy Gateway

Envoy Gateway sigue de cerca las publicaciones de Gateway API. La versión 1.4.0 incluye:

Soporte de Gateway API v1.3.0
Matriz de compatibilidad con versiones de Envoy Proxy
Enfoque en casos de uso de ingress
Fuerte adopción de funcionalidades experimentales

Es importante consultar la matriz de compatibilidad de Envoy Gateway para asegurarse de que la versión de Envoy Proxy instalada es coherente con la versión de Gateway API y de Kubernetes en uso.

Cilium

Cilium integra Gateway API de forma profunda con su implementación CNI:

Arquitectura de proxy Envoy por nodo
Aplicación de políticas de red para el tráfico gestionado por Gateway
Soporte tanto de ingress como de service mesh
Procesamiento de paquetes basado en eBPF

La arquitectura singular de Cilium lo convierte en una opción muy potente para organizaciones que ya utilizan Cilium para la red del clúster, al poder unificar en un mismo componente la red, la seguridad y el enrutamiento del tráfico de aplicaciones.

Contour

Contour v1.31.0 implementa Gateway API v1.2.1, con soporte de:

Todos los recursos v1 del canal Standard
La mayoría de los recursos v1alpha2 (TLSRoute, TCPRoute, GRPCRoute)
Soporte de BackendTLSPolicy

Cómo verificar la conformance de tu proveedor

Antes de decidir qué versión de Gateway API instalar, sigue estos pasos para validar el soporte de tu proveedor:

Visita la página oficial de implementaciones: el proyecto Gateway API mantiene una lista actualizada de implementaciones con sus niveles de conformance.
Consulta la documentación del proveedor: la mayoría de los proveedores publican matrices de compatibilidad que relacionan versiones de Gateway API, Kubernetes y proxy.
Revisa los informes de conformance: los proveedores envían resultados de pruebas de conformance que detallan exactamente qué funcionalidades Core y Extended soportan.
Prueba en entornos no productivos: antes de actualizar producción, valida tus casos de uso específicos en un entorno de staging.

Filosofía de actualización: cuándo y cómo actualizar

Una de las preguntas más frecuentes sobre Gateway API es: ¿necesito ejecutar siempre la última versión? La respuesta depende de tus necesidades concretas y tu tolerancia al riesgo.

Permanecer en versiones antiguas

No es necesario ejecutar siempre la última versión de Gateway API. Es perfectamente válido:

Mantenerse en una versión estable más antigua si cubre tus necesidades
Actualizar solo cuando necesites funcionalidades específicas de una versión posterior
Esperar a que tu proveedor soporte oficialmente las versiones más recientes
Priorizar la estabilidad frente a tener las últimas novedades

Las garantías de compatibilidad hacia atrás del canal Standard aseguran que, cuando finalmente actualices, tus configuraciones existentes seguirán funcionando sin modificaciones.

Cuándo considerar la actualización

Conviene plantearse una actualización cuando:

Necesitas una funcionalidad específica: un nuevo matcher de HTTPRoute, soporte de GRPCRoute u otra capacidad disponible únicamente en versiones más recientes.
Tu proveedor lo recomienda: los proveedores suelen optimizar su soporte para versiones concretas de Gateway API; seguir sus recomendaciones es una práctica sensata.
Consideraciones de seguridad: aunque es infrecuente, pueden surgir vulnerabilidades que justifiquen una actualización urgente.
Actualización del clúster Kubernetes: al actualizar Kubernetes, verifica que tu versión de Gateway API es compatible con la nueva versión del clúster.

Prácticas seguras de actualización

1. Utiliza siempre el canal Standard

El uso de los CRDs del canal Standard simplifica y hace más seguras las actualizaciones. Las funcionalidades experimentales pueden introducir cambios disruptivos entre versiones, mientras que las del canal Standard mantienen compatibilidad.

2. Actualiza una versión menor a la vez

Aunque en general es seguro saltarse versiones, la ruta de actualización más probada es la incremental. Pasar de v1.2 a v1.3 y después a v1.4 es más seguro que saltar directamente de v1.2 a v1.4.

3. Prueba siempre antes de actualizar en producción

Valida las actualizaciones en entornos no productivos antes de aplicarlas en producción:

# Instalar una versión específica de Gateway API en el clúster de pruebas
kubectl apply -f https://github.com/kubernetes-sigs/gateway-api/releases/download/v1.4.0/standard-install.yaml

4. Revisa las notas de publicación

Cada versión de Gateway API publica notas detalladas que incluyen:

Nuevas funcionalidades y capacidades
Graduación de características experimentales al canal Standard
Avisos de deprecación
Consideraciones específicas de la actualización

No omitas este paso: las notas de publicación son la fuente más fiable para anticipar cualquier impacto en tus configuraciones existentes.

5. Verifica la compatibilidad del proveedor primero

Antes de actualizar los CRDs de Gateway API, confirma que tu controlador de Gateway soporta la versión objetivo. Instalar Gateway API v1.4 no aporta ningún beneficio si tu controlador solo soporta v1.2; en el peor de los casos, puede generar comportamientos inesperados.

6. Nunca sobreescribas CRDs de un canal diferente

Las implementaciones no deben sobreescribir CRDs de Gateway API que pertenezcan a un canal diferente. Lleva un registro de si estás usando una instalación del canal Standard o Experimental y mantén la coherencia.

Gestión de CRDs: comandos útiles

La gestión de los CRDs de Gateway API requiere atención al detalle. Estos comandos te ayudarán a verificar el estado actual de tu instalación:

# Comprobar la versión instalada de Gateway API
kubectl get crd gateways.gateway.networking.k8s.io -o yaml | \
  grep 'gateway.networking.k8s.io/bundle-version'

# Verificar qué canal está instalado
kubectl get crd gateways.gateway.networking.k8s.io -o yaml | \
  grep 'gateway.networking.k8s.io/channel'

Ejecuta estos comandos antes de cualquier actualización para tener una línea de base clara de lo que tienes instalado.

Mantenerse informado sobre nuevas versiones

Gateway API sigue un ciclo de publicación estructurado con canales de comunicación claros. Aquí tienes las fuentes más relevantes para estar al día:

Fuentes para seguir las publicaciones

Página de releases en GitHub: sigue el repositorio kubernetes-sigs/gateway-api para recibir notificaciones de nuevas versiones en el momento en que se publican.
Blog oficial de Kubernetes: las publicaciones mayores de Gateway API se anuncian en el blog oficial de Kubernetes con explicaciones detalladas de las novedades.
Listas de correo y Slack: únete a los canales de la comunidad Gateway API para debates y anuncios anticipados.
Anuncios del proveedor: los proveedores de Gateway anuncian el soporte de nuevas versiones de Gateway API a través de sus propios canales; suscríbete a los de tu proveedor específico.

Cadencia de publicación

Gateway API sigue una cadencia de publicación trimestral para las versiones menores, con versiones de parche según sea necesario para correcciones de errores y problemas de seguridad. Esta cadencia predecible facilita la planificación de actualizaciones en los equipos de infraestructura.

Marco de decisión práctico

Este marco te ayudará a decidir qué versión de Gateway API ejecutar en función de tu situación concreta.

Para nuevos despliegues

Cargas de trabajo de producción: usa la última versión GA soportada por tu proveedor, instalada desde el canal Standard.
Entornos orientados a la innovación: considera el canal Experimental si necesitas funcionalidades de vanguardia y puedes asumir posibles cambios disruptivos.
Enfoque conservador: usa v1.1 o posterior con el canal Standard; es un punto de partida seguro y funcional para la mayoría de los casos de uso.

Para despliegues existentes

Si todo funciona correctamente: mantente en tu versión actual hasta que necesites nuevas funcionalidades. La estabilidad tiene valor.
Si el proveedor recomienda actualizar: sigue las indicaciones del proveedor, especialmente si hay implicaciones de seguridad.
Si tienes planificada una actualización de Kubernetes: verifica la compatibilidad con antelación; puede que necesites actualizar Gateway API antes o simultáneamente al clúster.

Actualizaciones motivadas por funcionalidades

Necesidad	Versión mínima requerida
Soporte de service mesh (GAMMA)	v1.1
GRPCRoute estable	v1.1
BackendTLSPolicy	v1.3+ (canal Experimental) + soporte del proveedor
Perfiles de conformance refinados	v1.4

Preguntas frecuentes sobre compatibilidad de Gateway API

¿Cuál es la diferencia entre Kubernetes Ingress y Gateway API?

Kubernetes Ingress es una API heredada centrada principalmente en el tráfico HTTP(S) con capacidades de extensión limitadas. Gateway API es su sucesor, y ofrece un modelo más expresivo y orientado a roles que soporta múltiples protocolos, enrutamiento avanzado, mejor separación de responsabilidades y un comportamiento coherente entre implementaciones. Si empiezas un nuevo proyecto hoy, Gateway API es la elección correcta.

¿Qué versión de Gateway API debería usar en producción hoy?

Para la mayoría de los entornos de producción, lo recomendable es usar la última versión GA (v1.x) soportada por tu proveedor de Gateway, instalada desde el canal Standard. Esto garantiza estabilidad, compatibilidad hacia atrás y las garantías de conformance, sin renunciar a las mejoras continuas del proyecto.

¿Puedo actualizar Gateway API sin actualizar mi clúster Kubernetes?

Sí. Los CRDs de Gateway API se instalan de forma independiente a Kubernetes. Mientras tu clúster cumpla el requisito mínimo de versión de Kubernetes (1.26+ para versiones recientes), puedes actualizar Gateway API sin tocar el clúster.

¿Qué ocurre si mi proveedor no soporta la última versión de Gateway API?

Si tu proveedor va por detrás de las últimas versiones, debes mantenerte en la última versión soportada oficialmente por ese proveedor. Instalar CRDs de Gateway API más nuevos de lo que soporta tu controlador puede dar lugar a funcionalidades no disponibles o a comportamientos indefinidos. La compatibilidad con el proveedor siempre debe tener prioridad sobre ejecutar la versión más reciente de la API.

¿Es seguro actualizar los CRDs de Gateway API sin tiempo de inactividad?

En la mayoría de los casos, sí, cuando se utiliza el canal Standard. Gateway API ofrece garantías sólidas de compatibilidad hacia atrás para los recursos GA y Beta. No obstante, siempre deberías probar las actualizaciones en entornos no productivos y verificar que tu proveedor soporta la versión objetivo antes de aplicarlas en producción.

¿Qué son los perfiles de conformance en Gateway API?

Los perfiles de conformance son conjuntos predefinidos de pruebas que agrupan funcionalidades por caso de uso (por ejemplo, ingress HTTP, service mesh, etc.). Permiten a los proveedores declarar su nivel de soporte de forma granular y a los usuarios comparar implementaciones de forma objetiva. Se introdujeron en versiones recientes de Gateway API y siguen evolucionando.

Conclusión

Kubernetes Gateway API representa el futuro de la gestión del tráfico en Kubernetes: una API estandarizada, extensible y orientada a roles tanto para ingress como para service mesh. Entender el modelo de versionado, los requisitos de compatibilidad y la filosofía de actualización te permite tomar decisiones fundamentadas que equilibran innovación y estabilidad.

Los puntos clave de esta guía:

Los CRDs de Gateway API se instalan de forma independiente a Kubernetes; solo requieren la versión 1.26 o superior para versiones recientes.
El canal Standard ofrece estabilidad y compatibilidad; el canal Experimental da acceso anticipado a nuevas funcionalidades con el coste de posibles cambios disruptivos.
No es necesario ejecutar siempre la última versión: actualiza cuando necesites funcionalidades específicas o cuando tu proveedor lo recomiende.
Verifica siempre la compatibilidad del proveedor antes de actualizar los CRDs de Gateway API.
Sigue prácticas seguras de actualización: prueba primero, actualiza de forma incremental, revisa las notas de publicación.

Siguiendo estas pautas, podrás desplegar y mantener Gateway API en tu infraestructura Kubernetes con confianza, tomando decisiones de actualización que se ajusten a las necesidades y la tolerancia al riesgo de tu organización.