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

Artículo
02/01/2024

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.

La CRD NginxIngressController tiene un campo loadBalancerAnnotations para controlar el comportamiento del servicio del controlador de entrada NGINX al establecer anotaciones del equilibrador de carga.

Controlador de entrada NGINX predeterminado

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.

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:

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

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:

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"

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:

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

az group create --name myNetworkResourceGroup --location eastus

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.

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}

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"
```
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.

Nota:

Actualice <IngressControllerName> con el nombre que usó al crear "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

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

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.

Nota:

Actualice <IngressControllerName> con el nombre que usó al crear 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.

Nota:

Las claves y los valores de anotación solo pueden ser cadenas. Otros tipos, como valores booleanos o numéricos, deben estar entre comillas, es decir, "true", "false", "100".

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:

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
  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:

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
  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"

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:

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
  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

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:

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
  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:

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
  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. Esto es especialmente útil con 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:

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
  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.

Share via

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

Requisitos previos

Conectarse al clúster AKS

Configuración del controlador de entrada NGINX

Controlador de entrada NGINX predeterminado

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

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

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

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

Uso del controlador de entrada en una entrada

Comprobación de que se creó la entrada administrada

Limpieza de controladores de entrada

Recurso de configuración por entrada mediante anotaciones

Tamaño máximo personalizado del cuerpo

Tiempo de espera de conexión personalizado

Protocolo de back-end

Deshabilitación del redireccionamiento SSL

Reescritura de direcciones URL

Pasos siguientes

Recursos adicionales

Share via

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

Requisitos previos

Conectarse al clúster AKS

Configuración del controlador de entrada NGINX

Controlador de entrada NGINX predeterminado

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

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

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

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

Uso del controlador de entrada en una entrada

Comprobación de que se creó la entrada administrada

Limpieza de controladores de entrada

Recurso de configuración por entrada mediante anotaciones

Tamaño máximo personalizado del cuerpo

Tiempo de espera de conexión personalizado

Protocolo de back-end

Uso compartido de recursos entre orígenes (CORS)

Deshabilitación del redireccionamiento SSL

Reescritura de direcciones URL

Pasos siguientes

Recursos adicionales