Compartir a través de

Controlador de entrada NGINX avanzado y configuraciones de entrada con el complemento de enrutamiento de aplicaciones para Azure Kubernetes Service (AKS)

Este artículo le guía por dos maneras de configurar controladores de entrada y objetos de entrada con el complemento de enrutamiento de aplicaciones para Azure Kubernetes Service (AKS):

Requisitos previos

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. Puede instalarlo localmente mediante el az aks install-cli comando . 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 $RESOURCE_GROUP --name $CLUSTER_NAME

Propiedades de configuración para controladores 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 configuraciones existentes.

En la tabla siguiente se enumeran las propiedades que puede establecer para configurar un NginxIngressController:

Campo Tipo Descripción Obligatorio Predeterminado
controllerNamePrefix cuerda / cadena Nombre de los recursos del NGINX Ingress Controller administrado. Sí nginx
customHTTPErrors array Matriz de códigos de error que se enviarán al back-end predeterminado si se produce un error. No
defaultBackendService objeto Servicio para redirigir aquél tráfico HTTP no coincidente. Contiene propiedades anidadas: No
 name cuerda / cadena Nombre del servicio. Sí
 namespace cuerda / cadena Espacio de nombres del servicio. Sí
defaultSSLCertificate objeto Contiene el certificado predeterminado para acceder al servicio back-end predeterminado. Contiene propiedades anidadas: No
 forceSSLRedirect boolean Fuerza el redireccionamiento HTTPS cuando se establece un certificado. No false
 keyVaultURI cuerda / cadena URI de un secreto de Key Vault que almacena el certificado. No
 secret objeto Contiene información secreta para el certificado SSL predeterminado. Contiene propiedades anidadas: No
  name cuerda / cadena Nombre del secreto. Sí
  namespace cuerda / cadena Espacio de nombres secreto. Sí
httpDisabled boolean Marca para deshabilitar el tráfico HTTP en el controlador. No
ingressClassName cuerda / cadena Nombre ingressClass usado por el controlador. Sí nginx.approuting.kubernetes.azure.com
loadBalancerAnnotations objeto Mapa de anotaciones para controlar el comportamiento del servicio del controlador de entrada NGINX estableciendo anotaciones del equilibrador de carga. No
scaling objeto Configuración para escalar el controlador. Contiene propiedades anidadas: No
 maxReplicas entero Límite superior para réplicas. No 100
 minReplicas entero Límite inferior para las réplicas. No 2
 threshold cuerda / cadena Umbral de escalado que define la intensidad de escalado. rapid escala rápidamente para picos repentinos, steady favorece la rentabilidad y balanced es una combinación. No balanced

Controlar la configuración predeterminada del controlador de entrada NGINX

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.

Entre las posibles opciones de configuración se incluyen:

  • None: el controlador de entrada NGINX predeterminado no se crea y no se elimina si ya existe. Si lo desea, debe eliminar manualmente el recurso personalizado predeterminado NginxIngressController .
  • Internal: el controlador de entrada NGINX predeterminado se crea con un equilibrador de carga interno. Se sobrescriben los cambios de anotación en el recurso personalizado NginxIngressController para que sea externo.
  • External: controlador de entrada NGINX predeterminado creado con un equilibrador de carga externo. Los cambios de anotación en el recurso personalizado NginxIngressControllerpara hacerlo interno son sobrescritos.
  • AnnotationControlled (valor predeterminado): el controlador de entrada NGINX predeterminado se crea con un equilibrador de carga externo. Puede editar el recurso personalizado predeterminado NginxIngressController para configurar anotaciones del equilibrador de carga).

Control de la configuración predeterminada del controlador de entrada en un nuevo clúster

  • Habilite el enrutamiento de aplicaciones en un nuevo clúster mediante el comando az aks create con los indicadores --enable-app-routing y --app-routing-default-nginx-controller. Debe establecer <DefaultIngressControllerType> en una de las opciones de configuración descritas en Controlar la configuración predeterminada del controlador de entrada NGINX.

    az aks create \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --location $LOCATION \
  --enable-app-routing \
  --app-routing-default-nginx-controller <DefaultIngressControllerType>

Actualización de la configuración predeterminada del controlador de entrada en un clúster existente

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

  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

  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

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

    az group create --name $NETWORK_RESOURCE_GROUP --location $LOCATION

  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 $NETWORK_RESOURCE_GROUP \
  --name $PUBLIC_IP_NAME \
  --sku Standard \
  --allocation-method static

    Nota:

    Si está utilizando un equilibrador de carga SKU Básico en su clúster AKS, use Basic para el parámetro --sku al definir una IP pública. Solo Basic las direcciones IP de SKU funcionan con el equilibrador de carga de SKU básico y solo Standard las direcciones IP de SKU 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.

    CLIENT_ID=$(az aks show --name $CLUSTER_NAME --resource-group $RESOURCE_GROUP --query identity.principalId -o tsv)
RG_SCOPE=$(az group show --name $NETWORK_RESOURCE_GROUP --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 más eficiente de un balanceador de carga y se recomienda encarecidamente 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: "$PUBLIC_IP_NAME"
    service.beta.kubernetes.io/azure-load-balancer-resource-group: "$NETWORK_RESOURCE_GROUP"

  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

Verifique que se creó el controlador de entrada

  • Compruebe el estado del controlador de entrada NGINX mediante el kubectl get nginxingresscontroller comando .

    kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME

    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

Ver las condiciones del controlador de entrada

  • Vea las condiciones del controlador de entrada para solucionar cualquier problema mediante el kubectl get nginxingresscontroller comando .

    kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME -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. El <IngressClassName> es el que definiste cuando creaste el 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 --namespace 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 creó con el kubectl get ingress comando .

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

    La salida debería ser similar a la salida de ejemplo siguiente:

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

Quitar controladores de entrada

Configuración para cada recurso de ingreso mediante anotaciones

El controlador de entrada NGINX admite la adición de 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. Por ejemplo: "true", "false", "100".

En las secciones siguientes se proporcionan ejemplos de configuraciones comunes. Para obtener una lista completa, consulte la documentación de anotaciones de entrada de NGINX.

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. El <IngressClassName> es el que definiste cuando creaste el 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 de espera que el controlador de ingreso NGINX espera antes de cerrar una conexión con su carga de trabajo. Todos los valores de tiempo de espera son sin unidades y están en segundos. Para invalidar el tiempo de espera predeterminado, use la siguiente anotación para establecer un tiempo de espera de lectura de proxy válido de 120 segundos:

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

Revise los 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. El <IngressClassName> es el que definiste cuando creaste el 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 servidor

El controlador de entrada NGINX usa HTTP para llegar a los servicios de forma predeterminada. Para configurar protocolos de back-end alternativos como HTTPS o GRPC, use una de las siguientes anotaciones:

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

# GRPC annotation
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. El <IngressClassName> es el que definiste cuando creaste el 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

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

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. El <IngressClassName> es el que definiste cuando creaste el 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

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

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

Revise implementación de HTTPS del lado del 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. El <IngressClassName> es el que definiste cuando creaste el 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 un código de estado HTTP 404. Esta configuración es útil con el enrutamiento basado en rutas de acceso , donde puede atender dos aplicaciones web diferentes en el mismo dominio. Puede establecer la ruta de acceso esperada por el servicio mediante la anotación siguiente:

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. El <IngressClassName> es el que definiste cuando creaste el 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

Actualización de la ruta de verificación de salud de NGINX

La ruta de acceso de sondeo de estado predeterminada para el equilibrador de carga de Azure asociado al controlador de Ingress NGINX debe establecerse en "/healthz". Para garantizar las comprobaciones de estado correctas, compruebe que el servicio controlador de entrada tiene la anotación siguiente:

metadata:
  annotations:
    service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Si usa Helm para administrar el controlador de entrada de NGINX, puede definir la anotación de sondeo de estado de Azure Load Balancer en un archivo de valores y aplicarla durante una actualización:

controller:
  service:
    annotations:
      service.beta.kubernetes.io/azure-load-balancer-health-probe-request-path: "/healthz"

Esta configuración ayuda a mantener la disponibilidad del servicio y evita interrupciones inesperadas del tráfico durante las actualizaciones.

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.

  • Last updated on