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:

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.

Di seguito è riportato un riferimento alle proprietà che è possibile impostare per configurare un oggetto NginxIngressController.

Proprietà Descrizione
ingressClassName Nome dell'oggetto IngressClass che verrà usato per il controller di ingresso NGINX. Il valore predefinito è il nome dell'oggetto NginxIngressController se non specificato.
controllerNamePrefix Nome usato per anteporre le risorse del controller di ingresso NGINX gestite. Il valore predefinito è nginx.
loadBalancerAnnotations Set di annotazioni per controllare il comportamento del servizio del controller di ingresso NGINX impostando le annotazioni del servizio di bilanciamento del carico
scalata Opzioni di configurazione per la scalabilità del controller di ingresso NGINX.
scaling.minReplicas Limite inferiore per il numero di repliche controller in ingresso. Il valore predefinito è 2 pod.
scaling.maxReplicas Limite superiore per il numero di repliche controller in ingresso. Il valore predefinito è 100 pod.
scaling.threshold Definisce la velocità con cui i pod del controller di ingresso NGINX devono essere ridimensionati in base al carico di lavoro. Rapid significa che il controller di ingresso verrà ridimensionato rapidamente e aggressivamente per la gestione di picchi improvvisi e significativi del traffico. Steady assegna priorità all'efficienza dei costi con un minor numero di repliche che gestiscono più lavoro. Balanced è un buon mix tra i due che funziona per la maggior parte dei casi d'uso. Se non specificato, per impostazione predefinita questo campo è Balanced.
defaultBackendService Il servizio Kubernetes che il controller di ingresso NGINX deve usare per impostazione predefinita, che gestisce tutti i percorsi URL e ospita il controller Ingress-NGINX, ovvero tutte le richieste non mappate a un ingresso. Il controller indirizza il traffico alla prima porta del servizio. Se non specificato, verrà usato il back-end predefinito incorporato.
defaultBackendService.namespace Spazio dei nomi del servizio.
defaultBackendService.name Nome del servizio.
defaultSSLCertificate Il segreto a cui fa riferimento questa proprietà contiene il certificato predefinito da usare quando si accede al servizio back-end predefinito. Se questa proprietà non viene specificata, NGINX userà un certificato autofirmato. Se la tls: sezione non è impostata su un ingresso, NGINX fornirà il certificato predefinito, ma non forza il reindirizzamento HTTPS.
defaultSSLCertificate.forceSSLRedirect Forza un reindirizzamento per Ingresses che non specificano una tls: sezione.
defaultSSLCertificate.keyVaultURI URI di Azure Key Vault in cui è possibile trovare il certificato SSL predefinito. Il componente aggiuntivo deve essere configurato per l'uso dell'insieme di credenziali delle chiavi.
defaultSSLCertificate.secret Configura il nome e lo spazio dei nomi in cui il segreto SSL predefinito si trova nel cluster.
defaultSSLCertificate.secret.name Nome del segreto.
defaultSSLCertificate.secret.namespace Spazio dei nomi del segreto.

Configurazioni comuni

Controllare la configurazione predefinita del controller di ingresso NGINX (anteprima)

Nota

Il controllo della configurazione del controller di ingresso NGINX quando si abilita il componente aggiuntivo è disponibile in API 2024-06-02-preview, Kubernetes versione 1.30 o successiva e la versione 7.0.0b5 dell'estensione dell'interfaccia della riga di comando di Azure aks-preview o versione successiva. Per controllare la versione del cluster del servizio Azure Kubernetes, vedere Verificare la disponibilità di aggiornamenti del cluster del servizio Azure Kubernetes.

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.

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>

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 della connessione personalizzata

È possibile modificare il timeout che il controller in ingresso NGINX attende prima di chiudere una connessione con il carico di lavoro. Tutti i valori di timeout sono senza unità ed espressi 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"

Vedere l'articolo sui 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"

or

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

Cross-Origin Resource Sharing (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.