Controlador de entrada y configuraciones de entrada de NGINX avanzadas con el complemento de enrutamiento de aplicaciones

El complemento de enrutamiento de aplicaciones admite dos maneras de configurar controladores de entrada y objetos de entrada:

• Configuración del controlador de entrada NGINX como crear varios controladores, configurar equilibradores de carga privados y establecer direcciones IP estáticas.
• Recurso de configuración por entrada mediante anotaciones.

Requisitos previos

Un clúster de AKS con el complemento de enrutamiento de aplicaciones.

Conectarse al clúster AKS

Para conectarse al clúster de Kubernetes desde su equipo local, use kubectl, el cliente de la línea de comandos de Kubernetes. Lo puede instalar localmente. Para ello debe usar el comando az aks install-cli. Si usa Azure Cloud Shell, kubectl ya está instalado.

Configure kubectl para conectarse al clúster de Kubernetes usando el comando az aks get-credentials.

az aks get-credentials -resource-group <ResourceGroupName> --name <ClusterName>

Configuración del controlador de entrada NGINX

El complemento de enrutamiento de aplicaciones usa una definición de recursos personalizados (CRD) de Kubernetes denominada NginxIngressController para configurar controladores de entrada NGINX. Puede crear más controladores de entrada o modificar la configuración existente.

Esta es una referencia a las propiedades que puede establecer para configurar un NginxIngressController.

Opciones de configuración comunes

Control de la configuración predeterminada del controlador de entrada NGINX (versión preliminar)

Al habilitar el complemento de enrutamiento de aplicaciones con NGINX, crea un controlador de entrada denominado default en el app-routing-namespace configurado con un equilibrador de carga de Azure orientado al público. Ese controlador de entrada usa un nombre de clase de entrada de webapprouting.kubernetes.azure.com.

También puede controlar si el valor predeterminado obtiene una dirección IP pública o interna, o si se crea al habilitar el complemento.

Estas son las posibles opciones de configuración:

• None: el controlador de entrada Nginx predeterminado no se crea y no se eliminará si ya existe. Los usuarios deben eliminar manualmente el recurso personalizado predeterminado NginxIngressController si lo desea.
• Internal: el controlador de entrada Nginx predeterminado se crea con un equilibrador de carga interno. Se sobrescribirán los cambios de anotaciones en el recurso personalizado NginxIngressController para que sea externo.
• External: controlador de entrada Nginx predeterminado creado con un equilibrador de carga externo. Se sobrescribirán los cambios de anotaciones en el recurso personalizado NginxIngressController para que sea interno.
• AnnotationControlled (predeterminado): el controlador de entrada Nginx predeterminado se crea con un equilibrador de carga externo. Los usuarios pueden editar el recurso personalizado predeterminado NginxIngressController para configurar las anotaciones del equilibrador de carga.

az aks create \
--resource-group <ResourceGroupName> \
--name <ClusterName> \
--location <Location> \
--enable-app-routing \
--app-routing-default-nginx-controller <DefaultIngressControllerType>

az aks approuting update --resource-group <ResourceGroupName> --name <ClusterName> --nginx <DefaultIngressControllerType>

"ingressProfile": {
  "webAppRouting": {
    "nginx": {
        "defaultIngressControllerType": "None|Internal|External|AnnotationControlled"
    }
}

Creación de otro controlador de entrada NGINX orientado al público

Para crear otro controlador de entrada NGINX con una instancia pública de Azure Load Balancer:

1. Copie el siguiente manifiesto YAML en un nuevo archivo denominado nginx-public-controller.yaml y guarde el archivo en el equipo local.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-public
   spec:
     ingressClassName: nginx-public
     controllerNamePrefix: nginx-public
   

2. Cree los recursos del controlador de entrada NGINX mediante el comando kubectl apply.

   kubectl apply -f nginx-public-controller.yaml
   

   En la siguiente salida de ejemplo se muestran los recursos creados:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-public created
   

Creación de un controlador de entrada NGINX interno con una dirección IP privada

Para crear un controlador de entrada NGINX con una instancia interna de Azure Load Balancer con una dirección IP privada haga lo siguiente:

1. Copie el siguiente manifiesto YAML en un nuevo archivo denominado nginx-internal-controller.yaml y guarde el archivo en el equipo local.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-internal
   spec:
     ingressClassName: nginx-internal
     controllerNamePrefix: nginx-internal
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-load-balancer-internal: "true"
   

2. Cree los recursos del controlador de entrada NGINX mediante el comando kubectl apply.

   kubectl apply -f nginx-internal-controller.yaml
   

   En la siguiente salida de ejemplo se muestran los recursos creados:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-internal created
   

Creación de un controlador de entrada NGINX con una dirección IP estática

Para crear un controlador de entrada NGINX con una dirección IP estática en Azure Load Balancer haga lo siguiente:

1. Cree un grupo de recursos de Azure con el comando az group create.

   az group create --name myNetworkResourceGroup --location eastus
   

2. Use el comando az network public ip create para crear una dirección IP pública estática.

   az network public-ip create \
       --resource-group myNetworkResourceGroup \
       --name myIngressPublicIP \
       --sku Standard \
       --allocation-method static
   

   Nota:

   Si usa un equilibrador de carga de SKU Básico en el clúster de AKS, use Básico para el parámetro --sku al definir una dirección IP pública. Solo las direcciones IP de SKU Básicas funcionan con el equilibrador de carga de SKU Básico y solo las IP de SKU Estándar funcionan con los equilibradores de carga de SKU Estándar.

3. Asegúrese de que la identidad de clúster que usa el clúster de AKS haya delegado permisos en el grupo de recursos de la dirección IP pública con el comando az role assignment create.

   Nota:

   Actualice <ClusterName> y <ClusterResourceGroup> con el nombre y el nombre del grupo de recursos del clúster de AKS.

   CLIENT_ID=$(az aks show --name <ClusterName> --resource-group <ClusterResourceGroup> --query identity.principalId -o tsv)
   RG_SCOPE=$(az group show --name myNetworkResourceGroup --query id -o tsv)
   az role assignment create \
       --assignee ${CLIENT_ID} \
       --role "Network Contributor" \
       --scope ${RG_SCOPE}
   

4. Copie el siguiente manifiesto YAML en un nuevo archivo denominado nginx-staticip-controller.yaml y guarde el archivo en el equipo local.

   Nota:

   Puede usar service.beta.kubernetes.io/azure-pip-name para un nombre de IP pública o service.beta.kubernetes.io/azure-load-balancer-ipv4 para una dirección IPv4 y service.beta.kubernetes.io/azure-load-balancer-ipv6 para una dirección IPv6, como se muestra en el ejemplo de YAML. Agregar la anotación service.beta.kubernetes.io/azure-pip-name garantiza la creación de LoadBalancer más eficaz y es muy recomendable para evitar posibles limitaciones.

   apiVersion: approuting.kubernetes.azure.com/v1alpha1
   kind: NginxIngressController
   metadata:
     name: nginx-static
   spec:
     ingressClassName: nginx-static
     controllerNamePrefix: nginx-static
     loadBalancerAnnotations: 
       service.beta.kubernetes.io/azure-pip-name: "myIngressPublicIP"
       service.beta.kubernetes.io/azure-load-balancer-resource-group: "myNetworkResourceGroup"
   

5. Cree los recursos del controlador de entrada NGINX mediante el comando kubectl apply.

   kubectl apply -f nginx-staticip-controller.yaml
   

   En la siguiente salida de ejemplo se muestran los recursos creados:

   nginxingresscontroller.approuting.kubernetes.azure.com/nginx-static created
   

Comprobación de que se creó el controlador de entrada

Puede comprobar el estado del controlador de entrada NGINX mediante el comando kubectl get nginxingresscontroller.

kubectl get nginxingresscontroller -n <IngressControllerName>

En la siguiente salida de ejemplo se muestra el recurso creado. El controlador puede tardar unos minutos en estar disponible:

NAME           INGRESSCLASS   CONTROLLERNAMEPREFIX   AVAILABLE
nginx-public   nginx-public   nginx                  True

También puede ver las condiciones para solucionar cualquier problema:

kubectl get nginxingresscontroller -n <IngressControllerName> -o jsonpath='{range .items[*].status.conditions[*]}{.lastTransitionTime}{"\t"}{.status}{"\t"}{.type}{"\t"}{.message}{"\n"}{end}'

En la salida de ejemplo siguiente se muestran las condiciones de un controlador de entrada correcto:

2023-11-29T19:59:24Z    True    IngressClassReady       Ingress Class is up-to-date
2023-11-29T19:59:50Z    True    Available               Controller Deployment has minimum availability and IngressClass is up-to-date
2023-11-29T19:59:50Z    True    ControllerAvailable     Controller Deployment is available
2023-11-29T19:59:25Z    True    Progressing             Controller Deployment has successfully progressed

Uso del controlador de entrada en una entrada

1. Copie el siguiente manifiesto YAML en un nuevo archivo denominado ingress.yaml y guarde el archivo en el equipo local.

   Nota:

   Actualice <Hostname> con el nombre de host DNS. <IngressClassName> es el que definió al crear NginxIngressController.

   apiVersion: networking.k8s.io/v1
   kind: Ingress
   metadata:
     name: aks-helloworld
     namespace: hello-web-app-routing
   spec:
     ingressClassName: <IngressClassName>
     rules:
     - host: <Hostname>
       http:
         paths:
         - backend:
             service:
               name: aks-helloworld
               port:
                 number: 80
           path: /
           pathType: Prefix
   

2. Cree los recursos del clúster mediante el comando kubectl apply.

   kubectl apply -f ingress.yaml -n hello-web-app-routing
   

   En la siguiente salida de ejemplo se muestran los recursos creados:

   ingress.networking.k8s.io/aks-helloworld created
   

Comprobación de que se creó la entrada administrada

Compruebe que la entrada administrada se ha creado con el comando kubectl get ingress.

kubectl get ingress -n hello-web-app-routing

En la siguiente salida de ejemplo se muestra la entrada administrada creada. La clase de entrada, el host y la dirección IP pueden ser diferentes:

NAME             CLASS                                HOSTS               ADDRESS       PORTS     AGE
aks-helloworld   webapprouting.kubernetes.azure.com   myapp.contoso.com   20.51.92.19   80, 443   4m

Limpieza de controladores de entrada

Puede quitar el controlador de entrada NGINX mediante el comando kubectl delete nginxingresscontroller.

kubectl delete nginxingresscontroller -n <IngressControllerName>

Recurso de configuración por entrada mediante anotaciones

El controlador de entrada NGINX permite agregar anotaciones a objetos de entrada específicos para personalizar su comportamiento.

Puede anotar el objeto de entrada si agrega la anotación respectiva en el campo metadata.annotations.

Estas son algunas anotaciones de ejemplos para configuraciones comunes. Revise la documentación de anotaciones de entrada NGINX para obtener una lista completa.

Tamaño máximo personalizado del cuerpo

Para NGINX, se devuelve un error 413 al cliente cuando el tamaño de una solicitud supera el tamaño máximo permitido del cuerpo de la solicitud de cliente. Para invalidar el valor predeterminado, use la anotación:

nginx.ingress.kubernetes.io/proxy-body-size: 4m

Esta es una configuración de entrada de ejemplo mediante esta anotación:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: 4m
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Tiempo de espera de conexión personalizado

Puede cambiar el tiempo que el controlador de entrada NGINX espera para cerrar una conexión con su carga de trabajo. Todos los valores de tiempo de espera son no unitarios y vienen en segundos. Para invalidar el tiempo de espera predeterminado, use la siguiente anotación, que establece un tiempo de espera de lectura de proxy válido de 120 segundos:

nginx.ingress.kubernetes.io/proxy-read-timeout: "120"

Revise tiempos de espera personalizados para ver otras opciones de configuración.

Esta es una configuración de entrada de ejemplo mediante esta anotación:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/proxy-read-timeout: "120"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Protocolo de back-end

De forma predeterminada, el controlador de entrada NGINX usa HTTP para llegar a los servicios. Para configurar protocolos de back-end alternativos como HTTPS o GRPC, use la anotación:

nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"

or

nginx.ingress.kubernetes.io/backend-protocol: "GRPC"

Revise protocolos de back-end para ver otras opciones de configuración.

Esta es una configuración de entrada de ejemplo mediante esta anotación:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/backend-protocol: "HTTPS"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Uso compartido de recursos entre orígenes (CORS)

Para habilitar el uso compartido de recursos entre orígenes (CORS) en una regla de entrada, use la anotación:

nginx.ingress.kubernetes.io/enable-cors: "true"

Revise habilitar CORS para ver otras opciones de configuración.

Esta es una configuración de entrada de ejemplo mediante esta anotación:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/enable-cors: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Deshabilitación del redireccionamiento SSL

De forma predeterminada, el controlador redirige (308) a HTTPS si TLS está habilitado para una entrada. Para deshabilitar esta característica para recursos de entrada específicos, use la anotación:

nginx.ingress.kubernetes.io/ssl-redirect: "false"

Revise aplicación https del lado servidor a través de redirección para ver otras opciones de configuración.

Esta es una configuración de entrada de ejemplo mediante esta anotación:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/ssl-redirect: "false"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - backend:
          service:
            name: aks-helloworld
            port:
              number: 80
        path: /
        pathType: Prefix

Reescritura de direcciones URL

En algunos escenarios, la dirección URL expuesta en el servicio back-end difiere de la ruta de acceso especificada en la regla de entrada. Sin una reescritura, cualquier solicitud devuelve 404. La configuración es útil con una ruta de acceso basada en enrutamiento donde puede servir dos aplicaciones web diferentes bajo el mismo dominio. Puede establecer la ruta de acceso esperada por el servicio mediante la anotación:

nginx.ingress.kubernetes.io/rewrite-target": /$2

Esta es una configuración de entrada de ejemplo mediante esta anotación:

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: aks-helloworld
  namespace: hello-web-app-routing
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: /$2
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  ingressClassName: <IngressClassName>
  rules:
  - host: <Hostname>
    http:
      paths:
      - path: /app-one(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-one
            port:
              number: 80
      - path: /app-two(/|$)(.*)
        pathType: Prefix 
        backend:
          service:
            name: app-two
            port:
              number: 80

Pasos siguientes

Obtenga información sobre la supervisión de las métricas del controlador de ingress-nginx incluidas con el complemento de enrutamiento de aplicaciones con Prometheus en Grafana como parte del análisis del rendimiento y el uso de la aplicación.