Migrar Ingress NGINX a Gateway API: inventario antes del cambio

La retirada cambió el mantenimiento, no apagó tus aplicaciones

Kubernetes retiró Ingress NGINX el 24 de marzo de 2026. Desde entonces, el proyecto ya no publica versiones, correcciones de errores ni parches para vulnerabilidades nuevas. Los controladores que ya están instalados siguen funcionando y los artefactos existentes continúan disponibles; eso no restaura el mantenimiento que necesitan para seguir expuestos con el mismo nivel de confianza.

Esto no significa que una migración deba hacerse a ciegas ni que todas las aplicaciones dejaran de responder. Primero identifica si tu plataforma usa el controlador comunitario retirado. El producto NGINX Ingress de F5 es un controlador distinto; su nombre parecido no lo incluye automáticamente en el anuncio de retiro. Laactualización oficial de Kubernetesconfirma tanto el retiro como la continuidad de los despliegues existentes.

1. Confirma qué controlador atiende el tráfico

Haz primero consultas de solo lectura con una identidad que tenga permiso para listar los recursos necesarios. El selector documentado por Kubernetes ayuda a localizar pods del controlador comunitario; los siguientes comandos muestran además las clases y reglas Ingress registradas:

kubectl get pods --all-namespaces --selector app.kubernetes.io/name=ingress-nginx
kubectl get ingressclass -o wide
kubectl get ingress --all-namespaces -o wide
kubectl get ingress --all-namespaces -o yaml > ingress-inventory.yaml

No te detengas en el nombre de un pod. Relaciona cada Ingress con su ingressClassName, el controlador que observa esa clase, la dirección pública que recibe el tráfico y las reglas DNS que apuntan a ella. Un clúster puede tener más de un controlador y varias clases con nombres propios. Registra también la versión instalada y el método de despliegue, por ejemplo Helm, manifiestos o una distribución administrada.

Estos comandos solo leen recursos, pero las salidas pueden revelar nombres internos, namespaces, hosts y referencias a certificados. Guarda el inventario en un lugar de acceso restringido; no publiques un volcado del clúster, un kubeconfig ni datos de clientes para pedir una revisión.

2. Inventaría comportamiento, no solo manifiestos

La API Ingress estándar cubre reglas HTTP y HTTPS básicas. Con los años, muchos controladores agregaron funciones mediante anotaciones, ConfigMaps, plantillas y recursos propios. Esas extensiones suelen contener la parte más difícil de trasladar: dos manifiestos pueden parecer equivalentes y aun así responder distinto a una solicitud real.

• Rutas y host: registra host, puerto, backend, orden y tipo de coincidencia. Señala rutas con expresiones regulares, reescrituras, barras finales o normalización de URL.
• TLS: relaciona cada host con su Secret de certificado, política de redirección HTTP a HTTPS, versión TLS y proceso de renovación. No exportes ni compartas los valores secretos.
• Anotaciones: busca límites de tamaño de cuerpo, tiempos de espera, CORS, cabeceras, autenticación externa, afinidad, listas de acceso, snippets y cambios de ruta.
• Dependencias: documenta ConfigMaps, CRDs del controlador, ExternalDNS, cert-manager, balanceadores, direcciones reservadas, observabilidad y restricciones de red que sostienen el ingreso.

Prueba el comportamiento actual en un entorno autorizado y conserva ejemplos de solicitudes esperadas: host, ruta, método, cabeceras, código de respuesta, redirección y backend. Atención especial a use-regex, rewrite-target y configuration-snippet. El proyecto documenta efectos secundarios de las expresiones y de la normalización de rutas; los snippets pueden insertar configuración NGINX que no tiene un equivalente portable en Gateway API.

Compara esa línea base con laguía oficial de comportamientos de Ingress NGINX. No conviertas una anotación sin revisar qué hacía en ese host y qué clientes podrían depender de ese efecto.

3. Usa Ingress2Gateway como asistente de conversión

Ingress2Gateway puede transformar recursos Ingress y advertir sobre campos que no se tradujeron o requieren revisión. La versión v1.2.0aparece como release en el repositorio del proyecto. La herramienta acelera el inventario; no valida por sí sola que un nuevo controlador entregue el mismo servicio.

Para empezar con un archivo revisado, puedes instalar una versión fijada y generar un manifiesto candidato:

go install github.com/kubernetes-sigs/ingress2gateway@v1.2.0
ingress2gateway print \
  --input-file ingress-inventory.yaml \
  --providers=ingress-nginx > gateway-candidate.yaml

El modo --input-file lee manifiestos YAML o JSON en lugar de consultar el clúster. Revisa la lista de advertencias junto con el archivo generado. La conversión no incorpora automáticamente cada CRD, ConfigMap, regla de firewall, registro DNS, integración o ajuste del balanceador. Un campo no traducido es una tarea pendiente, no un detalle cosmético.

Antes de aplicar el resultado, separa cada función en una de tres decisiones: usar un filtro estándar de Gateway API, configurar una extensión específica del controlador elegido o retirar una función que ya no se necesita. Si una función queda como extensión del proveedor, anótalo: puede reducir la portabilidad del manifiesto. Conserva el Ingress original y el candidato bajo control de versiones para revisar y revertir cambios.

4. Elige la implementación Gateway API según tus requisitos

Gateway API define recursos; un controlador compatible observa esos recursos y configura el plano de datos. Instalar las CRDs no instala automáticamente el controlador ni garantiza que tu proveedor admita todas las capacidades que usaba el Ingress anterior.

Consulta ellistado oficial de implementaciones y conformidad. Compara versiones de Gateway API, tipos de ruta, capacidades Core y Extended, política de soporte, integración con tu nube o balanceador, actualizaciones, observabilidad y límites de operación. La conformidad se reporta por versión y perfil; no equivale a que todas las extensiones de otro controlador estén cubiertas.

Gateway API permite separar responsabilidades entre quien administra la infraestructura y quien mantiene las rutas de una aplicación. Decide qué equipo puede crear o adjuntar Routes, en qué namespaces y a cuáles Listeners. En un clúster pequeño podrías mantener un modelo simple; en uno compartido, el aislamiento y RBAC forman parte del diseño, no de una migración posterior.

5. Valida estado y tráfico en una etapa de prueba

Instala CRDs y el controlador seleccionados en un entorno de prueba según la documentación de ese proyecto. Crea un GatewayClass, un Gateway y sus HTTPRoutes; después revisa estado y referencias antes de enviar tráfico. Los nombres abreviados dependen de que las CRDs ya estén instaladas:

kubectl get gatewayclass
kubectl get gateway,httproute --all-namespaces
kubectl describe gateway <gateway> -n <namespace>
kubectl describe httproute <route> -n <namespace>

Lee las condiciones Accepted, Programmed y ResolvedRefs, junto con su mensaje y generación observada. Accepted indica que el controlador aceptó configuración suficiente para producir efecto; no demuestra que todo el objeto esté correcto ni que el tráfico llegue. ResolvedRefs comprueba referencias; Programmed informa que la configuración fue enviada al plano de datos. Ninguna sustituye una solicitud externa real: valida los códigos, certificados, registros y logs que recibe un cliente.

Con un hostname de pruebas y una dirección de laboratorio, puedes comprobar TLS y enrutamiento antes de mover DNS. Sustituye valores y usa una ruta inocua de tu entorno:

curl --resolve <host>:443:<gateway-ip> \
  --silent --show-error --output /dev/null \
  --write-out '%{http_code}\n' \
  https://<host>/<ruta-de-prueba>

Compara los resultados con la línea base: destinos, respuestas, redirecciones, certificados, SNI, cabeceras, tiempos de espera, límites de cuerpo, rutas con mayúsculas o barras finales y solicitudes largas o WebSocket si tu aplicación las utiliza. Comprueba CORS y autenticación cuando formen parte del servicio. Revisa métricas y registros del controlador y la aplicación; una ruta que responde 200 no demuestra por sí sola que la política de acceso siga siendo correcta.

6. Programa el corte con reversión preparada

Si el diseño lo permite, prueba el nuevo Gateway con un hostname o punto de entrada separado y mantén el Ingress anterior sirviendo el tráfico. No presupongas que ambos controladores pueden compartir la misma dirección, clase o configuración de balanceador sin conflicto. Estima cualquier costo adicional de la etapa en paralelo y define quién observa el cambio.

1. Establece una línea base de disponibilidad, errores, latencia, TLS y tráfico.
2. Fija una ventana, responsables, criterios de aceptación y canal de aviso.
3. Reduce con anticipación el TTL DNS si el proveedor y el plan de corte lo permiten.
4. Dirige una parte del tráfico al nuevo punto de entrada solo con mecanismo compatible y observable.
5. Revierte el cambio de tráfico si se incumple un criterio; conserva el Ingress anterior hasta cerrar la ventana de observación.
6. Retira los recursos antiguos después de confirmar tráfico, TLS, monitoreo y recuperación con los responsables.

Un cambio de DNS no es instantáneo para todos los clientes, y una estrategia de canary requiere soporte explícito de tu balanceador o controlador. Define el rollback antes de tocar producción: quién cambia la ruta, qué señal lo activa y cuánto tiempo se mantiene la configuración anterior. Para revisar salud de Pods y del servicio, complementa esta guía conel uso correcto de readiness, liveness y startup probesy conel diagnóstico de CrashLoopBackOff.

Preguntas que conviene resolver antes de migrar

¿Debo eliminar Ingress NGINX hoy mismo?

No hagas una eliminación apresurada. El controlador retirado sigue atendiendo despliegues existentes, pero ya no recibe mantenimiento de seguridad. Confirma el alcance, prioriza la exposición y prepara un plan de reemplazo con pruebas y fecha responsable.

¿Gateway API es un reemplazo directo?

No. Es una API distinta y necesita una implementación. Reglas estándar pueden mapearse, pero las anotaciones, políticas y comportamientos específicos varían. Verifica la conformidad, el soporte del controlador y el resultado en tu plataforma.

¿Ingress2Gateway deja el clúster listo para el corte?

No. Ayuda a generar recursos candidatos y advertencias. Aún debes elegir controlador, revisar extensiones, instalar componentes compatibles, validar el tráfico y preparar la reversión.

Esta guía se basa en fuentes oficiales revisadas el 17 de octubre de 2026. No se ejecutó una migración contra un clúster de Elaine System ni contra la infraestructura de un cliente. Si necesitas evaluar rutas y dependencias antes de diseñar el cambio, consulta nuestrosservicios de infraestructura Kubernetes y Linux. Comparte solo inventario anonimizado; nunca envíes kubeconfig, tokens, certificados privados ni manifiestos con datos de clientes.