Configurazione avanzata di controller in ingresso NGINX e oggetti in ingresso con il componente aggiuntivo di routing delle applicazioni

Con il componente aggiuntivo di routing delle applicazioni sono supportate due soluzioni per configurare i controller in ingresso e gli oggetti in ingresso:

• 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 del servizio Azure Kubernetes con il componente aggiuntivo di routing delle applicazioni.

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 con il comando az aks install-cli. Se si usa Azure Cloud Shell, kubectl è già installato.

Per configurare kubectl per connettersi al cluster Kubernetes, usare il comando az aks get-credentials.

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

Configurazione del 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 in ingresso o modificare la configurazione esistente.

Questa tabella mostra un riferimento alle proprietà che è possibile impostare per configurare un oggetto NginxIngressController.

Campo	TIPO	Descrizione	Obbligatorio	Impostazione predefinita
controllerNamePrefix	corda	Nome delle risorse gestite del controller Ingress NGINX.	Sì	nginx
customHTTPErrors	elenco	Matrice di codici di errore da inviare al back-end predefinito in caso di errore.	NO
defaultBackendService	oggetto	Servizio per instradare il traffico HTTP non abbinato. Contiene proprietà annidate:	NO
name	corda	Nome del servizio.	Sì
namespace	corda	Namespace del servizio.	Sì
defaultSSLCertificate	oggetto	Contiene il certificato predefinito per l'accesso al servizio back-end predefinito. Contiene proprietà annidate:	NO
forceSSLRedirect	booleano	Forza il reindirizzamento HTTPS quando viene impostato un certificato.	NO	false
keyVaultURI	corda	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	corda	Nome segreto.	Sì
namespace	corda	Spazio dei nomi segreto.	Sì
httpDisabled	booleano	Flag per disabilitare il traffico HTTP verso il controller.	NO
ingressClassName	corda	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	numero intero	Limite massimo per le repliche.	NO	100
minReplicas	numero intero	Limite inferiore per le repliche.	NO	2
threshold	corda	Soglia di ridimensionamento che determina l'aggressività della scalabilità. rapid si adatta rapidamente ai picchi improvvisi, steady favorisce la convenienza economica ed balanced è una combinazione.	NO	balanced

Configurazioni comuni

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 oppure se viene creato quando si abilita il componente aggiuntivo.

Ecco le opzioni di configurazione possibili:

• None: il controller di ingresso Nginx predefinito non viene creato e non verrà eliminato se esiste già. Se necessario, gli utenti devono eliminare manualmente la risorsa personalizzata predefinita NginxIngressController .
• Internal: il controller di ingresso Nginx predefinito viene creato con un servizio di bilanciamento del carico interno. Tutte le annotazioni apportate alla NginxIngressController risorsa personalizzata per renderle esterne verranno sovrascritte.
• External: controller di ingresso Nginx predefinito creato con un servizio di bilanciamento del carico esterno. Tutte le annotazioni apportate alla NginxIngressController risorsa personalizzata per renderle interne verranno sovrascritte.
• AnnotationControlled (impostazione predefinita): il controller di ingresso Nginx predefinito viene creato con un servizio di bilanciamento del carico esterno. Gli utenti possono modificare la risorsa personalizzata predefinita NginxIngressController per configurare le annotazioni del servizio di bilanciamento del carico.

Interfaccia della riga di comando di Azure

Controllare la configurazione predefinita del controller di ingresso durante la creazione del cluster

Per abilitare il routing delle applicazioni in un nuovo cluster, usare il az aks create comando , specificando i --enable-app-routing flag e --app-routing-default-nginx-controller . È necessario impostare su <DefaultIngressControllerType> una delle opzioni di configurazione descritte in precedenza.

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

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

Per aggiornare la configurazione predefinita del controller di ingresso del routing dell'applicazione in un cluster esistente, usare il az aks approuting update comando , specificando il --nginx flag . È necessario impostare su <DefaultIngressControllerType> una delle opzioni di configurazione descritte in precedenza.

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

Bicipite

Il webAppRouting profilo ha una configurazione facoltativa nginx con una defaultIngressControllerType proprietà . È necessario impostare la defaultIngressControllerType proprietà su una delle opzioni di configurazione descritte in precedenza.

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

Creare un altro controller in ingresso NGINX pubblico

Per creare un altro controller in ingresso NGINX con un'istanza pubblica di Azure Load Balancer:

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

Per creare un controller in ingresso NGINX con un'istanza interna di Azure Load Balancer 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

Per creare un controller in ingresso NGINX con un indirizzo IP statico nel servizio Azure Load Balancer:

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

   az group create --name myNetworkResourceGroup --location eastus
   

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

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

   Nota

   Se nel cluster del servizio Azure Kubernetes si usa un servizio di bilanciamento del carico dello SKU Basic, usare Basic per il parametro --sku quando si definisce un IP pubblico. Con lo SKU Basic di Load Balancer funzionano solo indirizzi IP dello SKU Basic funzionano e con lo SKU Standard di Load Balancer funzionano solo gli indirizzi IP dello SKU Standard funzionano.

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.

   Nota

   Aggiornare <ClusterName> e <ClusterResourceGroup> con il nome del gruppo di risorse e il nome del cluster del servizio Azure Kubernetes.

   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. Copiare il manifesto YAML seguente in un nuovo file denominato nginx-staticip-controller.yaml e salvare il file nel computer locale.

   Nota

   È 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 una maggiore efficienza nella creazione del servizio di bilanciamento del carico ed è consigliabile per evitare potenziali limitazioni.

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

Per verificare lo stato del controller in ingresso NGINX, usare il comando kubectl get nginxingresscontroller.

Nota

Aggiornare <IngressControllerName> con il nome usato durante la creazione di "NginxIngressController".

kubectl get nginxingresscontroller -n <IngressControllerName>

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

È anche possibile visualizzare le condizioni per risolvere eventuali problemi:

kubectl get nginxingresscontroller -n <IngressControllerName> -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.

   Nota

   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 -n hello-web-app-routing
   

   L'output di esempio seguente mostra la risorsa creata:

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

Verificare che l'oggetto in ingresso gestito sia stato creato

Per verificare che l'oggetto in ingresso gestito sia stato creato, usare il comando kubectl get ingress.

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

L'output di esempio seguente mostra l'oggetto in ingresso gestito creato. La classe, l'host e l'indirizzo IP in ingresso possono essere diversi:

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

Pulizia dei controller in ingresso

Per rimuovere il controller in ingresso NGINX, usare il comando kubectl delete nginxingresscontroller.

Nota

Aggiornare <IngressControllerName> con il nome usato durante la creazione di NginxIngressController.

kubectl delete nginxingresscontroller -n <IngressControllerName>

Configurazione per singola risorsa in ingresso tramite annotazioni

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

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

Nota

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

Ecco alcuni esempi di annotazioni per le configurazioni più comuni. Per un elenco completo, esaminare la documentazione delle 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:

Nota

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 personalizzato

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

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

Esaminare i timeout personalizzati per altre opzioni di configurazione.

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

Nota

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

Per impostazione predefinita, il controller in ingresso NGINX usa HTTP per raggiungere i servizi. Per configurare protocolli back-end alternativi, come HTTPS o GRPC, usare l'annotazione:

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

o

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:

Nota

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 Condivisione di risorse tra le origini (CORS) in una regola in ingresso, usare l'annotazione:

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:

Nota

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

Per impostazione predefinita, il controller applica il reindirizzamento (308) a HTTPS se TLS è abilitato per una risorsa in ingresso. Per disabilitare questa funzionalità per risorse in ingresso specifiche, usare l'annotazione:

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:

Nota

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 dell'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 con l'annotazione:

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

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

Nota

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

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.