Configurar ingress con Kubernetes Gateway API a través del complemento de enrutamiento de aplicaciones para Azure Kubernetes Service (AKS)

El complemento de enrutamiento de aplicaciones admite la API de puerta de enlace de Kubernetes para la administración del tráfico de entrada. La API de Gateway de Kubernetes es un conjunto de recursos que proporcionan un marco estandarizado, orientado a roles y extensible para la administración del tráfico, diseñado para ser sucesor y evolución de la API de Ingress. Por lo tanto, la implementación de la API de enrutamiento del Gateway de aplicaciones tiene como objetivo servir como sucesor del complemento NGINX administrado, que se basa en la API de Ingress heredada y no recibirá soporte de Azure después de noviembre de 2026. Si usa NGINX administrado, debe migrar a la implementación de la API de gateway de enrutamiento de aplicaciones u otra implementación compatible, para noviembre de 2026.

En el caso de las cargas de trabajo de producción, este modelo es el modelo de entrada predeterminado recomendado en AKS Automatic. A partir de la versión 1.36 de AKS, los nuevos clústeres automáticos de AKS usan la API de puerta de enlace de Kubernetes mediante el complemento de enrutamiento de aplicaciones de forma predeterminada. Para obtener información general sobre los valores predeterminados para producción de AKS Automatic, consulte ¿Qué es Azure Kubernetes Service (AKS) Automatic?

Comparación con el complemento de malla de servicios Istio

La implementación del complemento de enrutamiento de aplicaciones de la API de puerta de enlace de Kubernetes despliega un plano de control de Istio para gestionar la infraestructura de los recursos de la API de puerta de enlace de Kubernetes. Sin embargo, difiere del complemento de malla de servicio Istio para AKS de las siguientes maneras:

Cuándo usar la API de puerta de enlace de enrutamiento de aplicaciones en producción

Use esta implementación como ruta de acceso de entrada predeterminada cuando desee:

• Valor predeterminado de entrada administrada listo para producción en AKS Automatic.
• Entrada HTTP/HTTPS nativa de la API de pasarela de Kubernetes.
• Infraestructura de puerta de enlace administrada con medidas de seguridad operativas integradas, como el escalado automático y los presupuestos de interrupciones en servidores proxy de puerta de enlace.

Tenga en cuenta alternativas cuando necesite funcionalidades fuera de la compatibilidad actual en este artículo, como:

• Comportamiento completo de la malla de servicios de Istio con gestión del tráfico basada en sidecars y un uso más amplio de las CRD de Istio.
• Las características actualmente enumeradas como no admitidas, como el paso SNI basado en TLSRoute.

Limitaciones

• No se pueden habilitar al mismo tiempo la implementación de la API de Gateway de enrutamiento de aplicaciones y el complemento de malla de servicios de Istio. Debe deshabilitar uno primero y luego habilitar el otro como parte de una operación por separado. Al realizar la transición desde el complemento de malla de servicio de Istio a la implementación de la API de puerta de enlace de enrutamiento de aplicaciones, debe eliminar la GatewayClass de Istio y los CRD de Istio después de deshabilitar el complemento de Istio. El complemento de Istio instala las CRD (como virtualservices.networking.istio.io, destinationrules.networking.istio.io y otras en los grupos de API networking.istio.io, security.istio.io, telemetry.istio.io y extensions.istio.io) que no se eliminan cuando se deshabilita el complemento. Si estos CRD permanecen en el clúster, el plano de control de Istio de la API de la puerta de enlace de enrutamiento de aplicaciones no se puede iniciar. Ejecute el siguiente comando para eliminarlos:

  kubectl delete crd $(kubectl get crd -o name | grep -E 'istio\.io')
  kubectl delete gatewayclass istio
  

  Nota:

  Si tiene recursos personalizados de Istio existentes (como VirtualServices o DestinationRules), la eliminación de los CRD también elimina esos recursos. Asegúrese de que ya no los necesita antes de continuar.

• La implementación de la API de puerta de enlace de enrutamiento de aplicaciones usa la misma lista de permitidos de personalización de recursos que el complemento Istio para validar las personalizaciones de ConfigMap para los recursos Gateway. Los webhooks gestionados por los complementos bloquean las personalizaciones que no están en la lista de elementos permitidos.

• La configuración del acceso de entrada HTTPS para los servicios HTTPS (por ejemplo, el paso a través de la Indicación de Nombre de Servidor (SNI), a través del recurso TLSRoute no es compatible actualmente. La compatibilidad con el TLSRoute recurso estará disponible una vez que AKS agregue compatibilidad con Istio 1.30, en cuyo momento el plano de control de Istio de enrutamiento de aplicaciones se actualiza automáticamente a esa versión.

• No se admite la gestión del tráfico de salida a través de la implementación de Gateway API para el enrutamiento de aplicaciones.

• No se admite oficialmente la inyección de sidecars no administrados por Microsoft (por ejemplo, telemetría personalizada, registro o agentes de seguridad) en los pods del proxy de puerta de enlace de Istio administrados por el complemento de enrutamiento de aplicaciones. Si decide inyectar su propio sidecar en un pod proxy administrado, Microsoft solo ofrece soporte limitado para cualquier problema que encuentre.

• El registro de acceso de Envoy está habilitado de forma predeterminada en los pods del proxy de la puerta de enlace, pero el formato del registro, el alcance y el proveedor no se pueden personalizar mediante la API de Istio Telemetry. Para personalizarlo, use en su lugar la entrada de la API de la puerta de enlace en el complemento de malla de servicios Istio.

Prerrequisitos

Actualización de la versión de la CLI de Azure

Debe usar azure-cli la versión 2.86.0 o superior. Ejecute az --version para buscar la azure-cli versión y ejecute az upgrade para actualizar.

Habilitar las CRD de la API de gateway administrado

Active la instalación de la API de puerta de enlace administrada. No se admite el uso de las CRD de la API de puerta de enlace autoadministradas con el complemento de enrutamiento de aplicaciones.

Comportamiento predeterminado automático de AKS (AKS 1.36 y versiones posteriores)

En los nuevos clústeres de AKS Automatic que ejecutan AKS 1.36 o posterior, la API de puerta de enlace de Kubernetes a través del complemento de enrutamiento de aplicaciones está habilitada de forma predeterminada.

Normalmente no es necesario ejecutar el comando de habilitación de características a menos que sea:

• Uso de un clúster existente.
• Uso de una versión anterior de AKS.
• Vuelva a habilitar la característica después de deshabilitarla.

Habilitar la implementación de la API de Gateway para el enrutamiento de aplicaciones

Habilitar durante la creación del clúster

Ejecute el siguiente comando para habilitar la implementación de la API de puerta de enlace de enrutamiento de aplicaciones durante la creación del clúster estándar de AKS:

# Set environment variables
export CLUSTER=<cluster-name>
export RESOURCE_GROUP=<resource-group-name>

# Enable the application routing Gateway API implementation during AKS Standard cluster creation
az aks create --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --enable-app-routing-istio

Habilitar para un clúster existente

Ejecute el siguiente comando para habilitar la implementación de la API de gateway de enrutamiento de aplicaciones para un clúster existente:

# Set environment variables
export CLUSTER=<cluster-name>
export RESOURCE_GROUP=<resource-group-name>

# Enable the application routing Gateway API implementation for an existing cluster
az aks update --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --enable-app-routing-istio

Debería ver los pods istiod en el espacio de nombres aks-istio-system:

kubectl get pods -n aks-istio-system

NAME                      READY   STATUS    RESTARTS   AGE
istiod-12a3bc45de-fghi6   1/1     Running   0          3m15s
istiod-78j9kl01mn-opqrs   1/1     Running   0          3m

También debería observar que ValidatingWebhookConfiguration se ha implementado:

kubectl get validatingwebhookconfiguration

NAME                                        WEBHOOKS   AGE
aks-node-validating-webhook                 1          117m
azure-service-mesh-ccp-validating-webhook   1          4m2s

Si tiene habilitada la instalación de la API de puerta de enlace administrada, también debería observar que el ConfigMap de personalización de la puerta de enlace de Istio se ha creado:

kubectl get cm -n aks-istio-system

NAME                                  DATA   AGE
...
istio-gateway-class-defaults          2      43s
...

Configurar ingreso usando un Gateway de Kubernetes

Implementación de una aplicación de ejemplo

En primer lugar, despliegue la aplicación httpbin de ejemplo en el espacio de nombres default.

export ISTIO_RELEASE="release-1.27"
kubectl apply -f https://raw.githubusercontent.com/istio/istio/$ISTIO_RELEASE/samples/httpbin/httpbin.yaml

Creación de una puerta de enlace de Kubernetes y HTTPRoute

A continuación, implemente una configuración de API de puerta de enlace en el espacio de nombres default con el gatewayClassName establecido en approuting-istio.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: httpbin-gateway
spec:
  gatewayClassName: approuting-istio
  listeners:
  - name: http
    port: 80
    protocol: HTTP
    allowedRoutes:
      namespaces:
        from: Same
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: httpbin
spec:
  parentRefs:
  - name: httpbin-gateway
  hostnames: ["httpbin.example.com"]
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /get
    backendRefs:
    - name: httpbin
      port: 8000
EOF

Compruebe que se han creado un Deployment, Service, HorizontalPodAutoscaler, y PodDisruptionBudget para httpbin-gateway:

kubectl get deployment httpbin-gateway-approuting-istio

NAME                               READY   UP-TO-DATE   AVAILABLE   AGE
httpbin-gateway-approuting-istio   2/2     2            2           6m41s

kubectl get service httpbin-gateway-approuting-istio

NAME                               TYPE           CLUSTER-IP   EXTERNAL-IP      PORT(S)                        AGE
httpbin-gateway-approuting-istio   LoadBalancer   10.0.54.96   <external-ip>    15021:30580/TCP,80:32693/TCP   7m13s

kubectl get hpa httpbin-gateway-approuting-istio

NAME                               REFERENCE                                     TARGETS       MINPODS   MAXPODS   REPLICAS   AGE
httpbin-gateway-approuting-istio   Deployment/httpbin-gateway-approuting-istio   cpu: 3%/80%   2         5         2          8m13s

kubectl get pdb httpbin-gateway-approuting-istio

NAME                               MIN AVAILABLE   MAX UNAVAILABLE   ALLOWED DISRUPTIONS   AGE
httpbin-gateway-approuting-istio   1               N/A               1                     9m1s

Envío de una solicitud a una aplicación de ejemplo

Por último, intente enviar una curl solicitud a la httpbin aplicación. En primer lugar, establezca la variable de entorno INGRESS_HOST:

kubectl wait --for=condition=programmed gateways.gateway.networking.k8s.io httpbin-gateway
export INGRESS_HOST=$(kubectl get gateways.gateway.networking.k8s.io httpbin-gateway -ojsonpath='{.status.addresses[0].value}')

A continuación, intente enviar una solicitud HTTP a httpbin:

curl -s -I -HHost:httpbin.example.com "http://$INGRESS_HOST/get"

Debería ver una respuesta HTTP 200.

Registro de acceso

La implementación de la API de puerta de enlace para el enrutamiento de aplicaciones habilita, de forma predeterminada, el registro de acceso de Envoy en todos los pods de proxy administrados de Gateway. Los registros de acceso se escriben en la salida estándar del contenedor proxy en el formato de texto predeterminado de Envoy. Puede ver los registros mediante kubectl logs:

kubectl logs deployment/<your-gateway-name>-approuting-istio

Cada solicitud que procesa la puerta de enlace genera una línea de registro que contiene detalles como el método HTTP, la ruta de acceso, el código de respuesta, el servicio upstream y los tamaños de la solicitud y de la respuesta. Este detalle facilita la observación del tráfico de entrada y la solución de problemas de enrutamiento sin ninguna configuración adicional.

Control de versiones y actualizaciones

La implementación de Gateway API para el enrutamiento de aplicaciones despliega y actualiza el plano de control de Istio según la versión de Kubernetes del clúster de AKS, tanto en las actualizaciones de versiones secundarias como de parche. Este modelo local se alinea con los valores predeterminados de producción automática de AKS, donde la administración del ciclo de vida de la plataforma está diseñada para reducir las operaciones manuales.

La versión de Istio es la versión secundaria máxima admitida de Istio que es compatible con la versión de AKS del clúster. Por ejemplo, si tiene la versión de AKS 1.34, la versión máxima admitida de Istio que está instalada (a partir de marzo de 2026) es 1.28. Tenga en cuenta que la versión máxima admitida de Istio para una versión determinada de Kubernetes puede diferir entre los clústeres de soporte a largo plazo (LTS) y los clústeres que no son LTS.

Para conocer la versión secundaria máxima de Istio admitida para su versión de Kubernetes de AKS, consulte el calendario de versiones del complemento de malla de servicio. Aunque la implementación de API de puerta de enlace para el enrutamiento de aplicaciones no está versionada por revisiones, la versión secundaria del plano de control de Istio corresponde a la revisión indicada del complemento de malla de servicio (por ejemplo, para la revisión del complemento de malla de servicio asm-1-28, la versión secundaria del plano de control de Istio para el enrutamiento de aplicaciones es 1.28). Para ver la versión secundaria de Istio, también puede comprobar la versión de revisión en la imagen de implementación de Istio:

kubectl get deployment istiod -n aks-istio-system -o=jsonpath="{.spec.template.spec.containers[*].image}"

Actualizaciones

Las actualizaciones de la versión de parche y de la versión secundaria del plano de control de Istio para la implementación de la API de la puerta de enlace de enrutamiento de aplicaciones se realizan localmente. Las actualizaciones de versiones de parche se realizan automáticamente como parte de las versiones de AKS. Las actualizaciones de versiones secundarias pueden activarse automáticamente o manualmente según la versión de Kubernetes de AKS y la programación de las versiones secundarias de Istio. Las actualizaciones de versiones secundarias se producen en los escenarios siguientes:

• El clúster de AKS se actualiza a una nueva versión que tiene una versión superior máxima admitida de Istio anclada a él. El plano de control de Istio se actualiza a la versión secundaria más reciente como parte de la actualización del clúster de AKS.
• Se publica una nueva versión de Istio para AKS y se convierte en la versión máxima admitida de Istio para la versión del clúster de AKS. Después del despliegue en tu región, el plano de control de Istio en tu clúster se actualiza automáticamente a la nueva versión menor. Para realizar un seguimiento de los lanzamientos de nuevas versiones de Istio y ver cuándo se distribuye la nueva versión en su región, siga las notas de versiones de AKS y el rastreador de versiones de AKS.

Las interrupciones del tráfico pueden producirse durante el proceso de actualización. Para minimizar las interrupciones durante las actualizaciones, el complemento de enrutamiento de aplicaciones implementa Horizontal Pod Autoscaler (HPA) con dos réplicas mínimas y un PodDisruptionBudget (PDB) con una disponibilidad mínima de una para cada Gateway. Puede personalizar estos recursos para modificar esta configuración.

Personalizaciones de recursos

Personalización de Horizontal Pod Autoscaling (HPA) del plano de control

La implementación de la API de puerta de enlace de enrutamiento de aplicaciones admite la personalización de Horizontal Pod Autoscaler (HPA) del plano de control de Istio. El istiod recurso de HPA tiene las siguientes configuraciones predeterminadas:

• Réplicas mínimas: dos
• Número máximo de réplicas: Cinco
• Uso de CPU: 80%

La configuración de HPA se puede modificar mediante revisiones y modificaciones directas. Ejemplo:

kubectl patch hpa istiod -n aks-istio-system --type merge --patch '{"spec": {"minReplicas": 3, "maxReplicas": 6}}'

Personalización de recursos de puerta de enlace

La implementación de la API de gateway de enrutamiento de aplicaciones admite la personalización de los Gateway recursos a través de anotaciones y ConfigMaps. El enrutamiento de aplicaciones usa la misma lista de permitidos para la personalización de recursos que el complemento de malla de servicio Istio para la personalización de recursos de la puerta de enlace de API. Siga los pasos descritos en los documentos de API de puerta de enlace del complemento Istio para configurar los recursos generados para Gateways y para ver qué campos se encuentran en la lista de permitidos.

 service: |
    spec:
       externalTrafficPolicy: Local
    metadata:
      annotations:
        service.beta.kubernetes.io/port_80_health-probe_port:
        service.beta.kubernetes.io/port_80_health-probe_protocol:
        service.beta.kubernetes.io/port_80_health-probe_request-path:

Deshabilitar la implementación de la API de Gateway de enrutamiento de aplicaciones

Ejecute el siguiente comando para deshabilitar la implementación de la API de gateway de enrutamiento de aplicaciones:

az aks update --resource-group ${RESOURCE_GROUP} --name ${CLUSTER} --disable-app-routing-istio

Limpieza de recursos

Ejecute los comandos siguientes para eliminar los Gateway recursos y HTTPRoute :

kubectl delete gateways.gateway.networking.k8s.io httpbin-gateway
kubectl delete httproute httpbin

Si ha creado un objeto ConfigMap para personalizar Gateway, ejecute el siguiente comando para eliminar el ConfigMap:

kubectl delete configmap gw-options

Si creó un secretProviderClass y un secreto que se usará para la terminación TLS, elimine los siguientes recursos:

kubectl delete secret httpbin-credential
kubectl delete pod secrets-store-sync-httpbin
kubectl delete secretproviderclass httpbin-credential-spc

Contenido relacionado

• ¿Qué es Azure Kubernetes Service (AKS) Automático?
• Creación de un clúster automático de AKS
• Configurar Azure DNS y TLS con la implementación de la API de Gateway para el enrutamiento de aplicaciones
• Protección del tráfico de entrada con la implementación de la API de gateway de enrutamiento de aplicaciones (configuración manual)