Configurazioni avanzate di ingresso e controller in ingresso NGINX con il componente aggiuntivo di routing delle applicazioni per il servizio Azure Kubernetes (AKS)

Questo articolo illustra due modi per configurare i controller di ingresso e gli oggetti in ingresso con il componente aggiuntivo di routing delle applicazioni per il servizio Azure Kubernetes:

• Configurazione del controller in ingresso NGINX, ad esempio la creazione di più controller, la configurazione di servizi di bilanciamento del carico privato e l'impostazione di indirizzi IP statici.
• Configurazione per singola risorsa in ingresso tramite le annotazioni.

Prerequisiti

• Un cluster AKS con il componente aggiuntivo di routing dell'applicazione abilitato.
• kubectl configurato per connettersi al cluster AKS. Per altre informazioni, vedere Connessione al cluster AKS.

Connettersi al cluster del servizio Azure Kubernetes

Per connettersi al cluster Kubernetes dal computer locale, si usa kubectl, ovvero il client da riga di comando di Kubernetes. È possibile installarlo in locale usando il az aks install-cli comando . Se si usa Azure Cloud Shell, kubectl è già installato.

• Configurare kubectl per connettersi al cluster Kubernetes usando il comando az aks get-credentials.

  az aks get-credentials --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME
  

Proprietà di configurazione per i controller di ingresso NGINX

Il componente aggiuntivo di routing delle applicazioni usa una definizione di risorsa personalizzata (CRD, Custom Resource Definition) Kubernetes denominata NginxIngressController per configurare i controller in ingresso NGINX. È possibile creare più controller di ingresso o modificare le configurazioni esistenti.

Nella tabella seguente sono elencate le proprietà che è possibile impostare per configurare un oggetto NginxIngressController:

Campo	TIPO	Descrizione	Obbligatorio	Impostazione predefinita
controllerNamePrefix	string	Nome delle risorse gestite del controller Ingress NGINX.	Sì	nginx
customHTTPErrors	array	Matrice di codici di errore da inviare al back-end predefinito se si verifica un errore.	NO
defaultBackendService	oggetto	Servizio per instradare il traffico HTTP non abbinato. Contiene proprietà annidate:	NO
name	string	Nome del servizio.	Sì
namespace	string	Namespace del servizio.	Sì
defaultSSLCertificate	oggetto	Contiene il certificato predefinito per l'accesso al servizio back-end predefinito. Contiene proprietà annidate:	NO
forceSSLRedirect	boolean	Forza il reindirizzamento HTTPS quando viene impostato un certificato.	NO	false
keyVaultURI	string	URI per un segreto di Key Vault che archivia il certificato.	NO
secret	oggetto	Contiene informazioni segrete per il certificato SSL predefinito. Contiene proprietà annidate:	NO
name	string	Nome segreto.	Sì
namespace	string	Spazio dei nomi segreto.	Sì
httpDisabled	boolean	Flag per disabilitare il traffico HTTP verso il controller.	NO
ingressClassName	string	Nome IngressClass usato dal controller.	Sì	nginx.approuting.kubernetes.azure.com
loadBalancerAnnotations	oggetto	Mappa delle annotazioni per controllare il comportamento del servizio del controller di ingresso NGINX impostando le annotazioni del servizio di bilanciamento del carico.	NO
scaling	oggetto	Configurazione per il ridimensionamento del controller. Contiene proprietà annidate:	NO
maxReplicas	integer	Limite massimo per le repliche.	NO	100
minReplicas	integer	Limite inferiore per le repliche.	NO	2
threshold	string	Soglia di ridimensionamento che definisce la scalabilità aggressiva. rapid si adatta rapidamente ai picchi improvvisi, steady favorisce la convenienza economica ed balanced è una combinazione.	NO	balanced

Controllare la configurazione predefinita del controller di ingresso NGINX

Quando si abilita il componente aggiuntivo di routing delle applicazioni con NGINX, viene creato un controller in ingresso denominato default in app-routing-namespace configurato con un'istanza pubblica di Azure Load Balancer. Il controller in ingresso usa il nome di classe in ingresso webapprouting.kubernetes.azure.com.

È anche possibile controllare se l'impostazione predefinita ottiene un indirizzo IP pubblico o interno o se viene creato durante l'abilitazione del componente aggiuntivo.

Le opzioni di configurazione possibili includono:

• None: il controller di ingresso NGINX predefinito non viene creato e non viene eliminato se esiste già. Se necessario, eliminare manualmente la risorsa personalizzata predefinita NginxIngressController .
• Internal: Il controller di ingresso NGINX predefinito viene creato con un bilanciatore del carico interno. Tutte le modifiche alle annotazioni nella risorsa personalizzata NginxIngressController per renderla esterna vengono sovrascritte.
• External: Il controller di ingresso NGINX predefinito creato con un bilanciatore di carico esterno. Tutte le modifiche alle annotazioni nella risorsa personalizzata NginxIngressController per renderla interna vengono sovrascritte.
• AnnotationControlled (impostazione predefinita): il controller di ingresso NGINX predefinito viene creato con un servizio di bilanciamento del carico esterno. È possibile modificare la risorsa personalizzata predefinita NginxIngressController per configurare le annotazioni del servizio di bilanciamento del carico.

Controllare la configurazione predefinita del controller di ingresso in un nuovo cluster

Interfaccia della riga di comando di Azure

• Abilitare il routing delle applicazioni in un nuovo cluster usando il comando az aks create con i flag --enable-app-routing e --app-routing-default-nginx-controller. È necessario impostare su <DefaultIngressControllerType> una delle opzioni di configurazione descritte in Controllare la configurazione predefinita del controller di ingresso NGINX.

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

Bicipite

Il webAppRouting profilo ha una configurazione facoltativa nginx con una defaultIngressControllerType proprietà che è possibile modificare per controllare la configurazione predefinita.

• Impostare la defaultIngressControllerType proprietà su una delle opzioni di configurazione descritte in Controllare la configurazione predefinita del controller di ingresso NGINX.

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

Aggiornare la configurazione predefinita del controller di ingresso in un cluster esistente

Interfaccia della riga di comando di Azure

• Aggiorna la configurazione predefinita del controller di ingresso del routing dell'applicazione in un cluster esistente usando il comando az aks approuting update con il flag --nginx. È necessario impostare su <DefaultIngressControllerType> una delle opzioni di configurazione descritte in Controllare la configurazione predefinita del controller di ingresso NGINX.

  az aks approuting update \
    --resource-group $RESOURCE_GROUP \
    --name $CLUSTER_NAME \
    --nginx <DefaultIngressControllerType>
  

Bicipite

Il webAppRouting profilo ha una configurazione facoltativa nginx con una defaultIngressControllerType proprietà che è possibile modificare per controllare la configurazione predefinita.

• Impostare la defaultIngressControllerType proprietà su una delle opzioni di configurazione descritte in Controllare la configurazione predefinita del controller di ingresso NGINX.

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

Creare un altro controller in ingresso NGINX pubblico

1. Copiare il manifesto YAML seguente in un nuovo file denominato nginx-public-controller.yaml e salvare il file nel computer locale.

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

2. Creare le risorse del controller in ingresso NGINX con il comando kubectl apply.

   kubectl apply -f nginx-public-controller.yaml
   

   L'output di esempio seguente mostra la risorsa creata:

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

Creare un controller in ingresso NGINX interno con un indirizzo IP privato

1. Copiare il manifesto YAML seguente in un nuovo file denominato nginx-internal-controller.yaml e salvare il file nel computer locale.

   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. Creare le risorse del controller in ingresso NGINX con il comando kubectl apply.

   kubectl apply -f nginx-internal-controller.yaml
   

   L'output di esempio seguente mostra la risorsa creata:

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

Creare un controller in ingresso NGINX con un indirizzo IP statico

1. Creare un gruppo di risorse di Azure con il comando az group create.

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

2. Creare un indirizzo IP pubblico statico con il comando az network public ip create.

   az network public-ip create \
     --resource-group $NETWORK_RESOURCE_GROUP \
     --name $PUBLIC_IP_NAME \
     --sku Standard \
     --allocation-method static
   

   Note

   Se state utilizzando un bilanciamento del carico di SKU di tipo Basic nel vostro cluster AKS, usate Basic per il parametro --sku quando definite un indirizzo IP pubblico. Solo gli SKU IP Basic funzionano con il bilanciamento del carico SKU Basic e solo gli SKU IP Standard funzionano con il bilanciamento del carico SKU Standard.

3. Verificare che l'identità del cluster usata dal cluster del servizio Azure Kubernetes abbia autorizzazioni delegate al gruppo di risorse dell'indirizzo IP pubblico usando il 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. Copiare il manifesto YAML seguente in un nuovo file denominato nginx-staticip-controller.yaml e salvare il file nel computer locale.

   Note

   È possibile usare service.beta.kubernetes.io/azure-pip-name per il nome IP pubblico oppure service.beta.kubernetes.io/azure-load-balancer-ipv4 per un indirizzo IPv4 e service.beta.kubernetes.io/azure-load-balancer-ipv6 per un indirizzo IPv6, come illustrato nell'esempio relativo a YAML. L'aggiunta dell'annotazione service.beta.kubernetes.io/azure-pip-name garantisce la maggiore efficienza nella creazione del servizio di bilanciamento del carico ed è altamente consigliabile per evitare potenziali limitazioni della larghezza di banda della rete.

   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. Creare le risorse del controller in ingresso NGINX con il comando kubectl apply.

   kubectl apply -f nginx-staticip-controller.yaml
   

   L'output di esempio seguente mostra la risorsa creata:

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

Verificare che il controller in ingresso sia stato creato

• Verificare lo stato del controller di ingresso NGINX usando il kubectl get nginxingresscontroller comando .

  kubectl get nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
  

  L'output di esempio seguente mostra la risorsa creata. Possono essere necessari alcuni minuti prima che il controller sia disponibile:

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

Visualizzare le condizioni del controller di ingresso

• Visualizzare le condizioni del controller di ingresso per risolvere eventuali problemi tramite il 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}'
  

  L'output di esempio seguente mostra le condizioni di un controller di ingresso integro:

  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
  

Usare il controller in ingresso in un oggetto in ingresso

1. Copiare il manifesto YAML seguente in un nuovo file denominato ingress.yaml e salvare il file nel computer locale.

   Note

   Aggiornare <HostName> con il nome host DNS. Il valore di <IngressClassName> corrisponde a quello definito durante la creazione di 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. Creare le risorse del cluster con il comando kubectl apply.

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

   L'output di esempio seguente mostra la risorsa creata:

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

Verificare che l'ingresso gestito sia stato creato

• Verificare che l'ingresso gestito sia stato creato usando il kubectl get ingress comando .

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

  L'output dovrebbe essere simile all'output di esempio seguente:

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

Rimuovere i controller di ingresso

• Rimuovere il controller di ingresso NGINX usando il kubectl delete nginxingresscontroller comando .

  kubectl delete nginxingresscontroller --name $INGRESS_CONTROLLER_NAME
  

Configurazione per singola risorsa in ingresso tramite annotazioni

Il controller di ingresso NGINX supporta l'aggiunta di annotazioni a oggetti di ingresso specifici per personalizzare il comportamento.

È possibile annotare l'oggetto in ingresso aggiungendo la rispettiva annotazione nel campo metadata.annotations.

Note

Le chiavi e i valori di annotazione possono essere solo di tipo stringa. Altri tipi, ad esempio valori booleani o numerici, devono essere racchiusi tra virgolette. Ad esempio: "true", "false", "100".

Le sezioni seguenti forniscono esempi per le configurazioni comuni. Per un elenco completo, vedere la documentazione relativa alle annotazioni in ingresso NGINX.

Dimensioni massime personalizzate del corpo

Per NGINX viene restituito un errore 413 al client quando le dimensioni del corpo di una richiesta client superano quelle massime consentite. Per eseguire l'override del valore predefinito, usare l'annotazione:

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

Ecco un esempio di configurazione di oggetti in ingresso con questa annotazione:

Note

Aggiornare <HostName> con il nome host DNS. Il valore di <IngressClassName> corrisponde a quello definito durante la creazione di 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

Timeout connessione personalizzata

È possibile modificare il timeout durante il quale il controller di ingresso NGINX attende prima di chiudere una connessione con il tuo carico di lavoro. Tutti i valori di timeout sono senza unità e in secondi. Per eseguire l'override del timeout predefinito, usare l'annotazione seguente per impostare un timeout di lettura proxy di 120 secondi valido:

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

Verifica i timeout personalizzati per altre opzioni di configurazione.

Ecco un esempio di configurazione di oggetti in ingresso con questa annotazione:

Note

Aggiornare <HostName> con il nome host DNS. Il valore di <IngressClassName> corrisponde a quello definito durante la creazione di 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

Protocollo back-end

Il controller di ingresso NGINX usa HTTP per raggiungere i servizi per impostazione predefinita. Per configurare protocolli back-end alternativi, ad HTTPS esempio o GRPC, usare una delle annotazioni seguenti:

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

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

Vedere l'articolo sui protocolli back-end per altre opzioni di configurazione.

Ecco un esempio di configurazione di oggetti in ingresso con questa annotazione:

Note

Aggiornare <HostName> con il nome host DNS. Il valore di <IngressClassName> corrisponde a quello definito durante la creazione di 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

Condivisione delle risorse tra origini diverse (CORS)

Per abilitare la Condivisione di Risorse tra Origini (CORS) in una regola di Ingress, usare l'annotazione seguente.

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

Vedere l'articolo sull'abilitazione di CORS per altre opzioni di configurazione.

Ecco un esempio di configurazione di oggetti in ingresso con questa annotazione:

Note

Aggiornare <HostName> con il nome host DNS. Il valore di <IngressClassName> corrisponde a quello definito durante la creazione di 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

Disabilitare il reindirizzamento SSL

Il controller reindirizza (308) a HTTPS se TLS è abilitato per un ingresso per impostazione predefinita. Per disabilitare questa funzionalità per risorse di ingresso specifiche, usare l'annotazione seguente:

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

Vedere l'articolo sull'applicazione di HTTPS sul lato server tramite reindirizzamento per altre opzioni di configurazione.

Ecco un esempio di configurazione di oggetti in ingresso con questa annotazione:

Note

Aggiornare <HostName> con il nome host DNS. Il valore di <IngressClassName> corrisponde a quello definito durante la creazione di 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

Riscrittura URL

In alcuni scenari, l'URL esposto nel servizio back-end è diverso dal percorso specificato nella regola di ingresso. Senza una riscrittura qualsiasi richiesta restituisce 404. Questa configurazione è utile con il routing basato sul percorso in cui è possibile gestire due applicazioni Web diverse nello stesso dominio. È possibile impostare il percorso previsto dal servizio usando l'annotazione seguente:

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

Ecco un esempio di configurazione di oggetti in ingresso con questa annotazione:

Note

Aggiornare <HostName> con il nome host DNS. Il valore di <IngressClassName> corrisponde a quello definito durante la creazione di 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

Aggiornamento del percorso della sonda di integrità NGINX

Il percorso predefinito del probe di integrità per Azure Load Balancer associato al controller in ingresso NGINX deve essere impostato su "/healthz". Per garantire controlli di integrità corretti, verificare che il servizio del controller in ingresso abbia l'annotazione seguente:

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

Se si usa Helm per gestire il controller di ingresso NGINX, è possibile definire l'annotazione probe di integrità di Azure Load Balancer in un file di valori e applicarla durante un aggiornamento:

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

Questa configurazione consente di mantenere la disponibilità del servizio ed evitare interruzioni impreviste del traffico durante gli aggiornamenti.

Passaggi successivi

Informazioni sul monitoraggio delle metriche del controller ingress-nginx incluse nel componente aggiuntivo di routing delle applicazioni con Prometheus in Grafana come parte dell'analisi delle prestazioni e dell'utilizzo dell'applicazione.