Condividi tramite

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

  • Articolo

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.

La CRD NginxIngressController include un campo loadBalancerAnnotations che consente di controllare il comportamento del servizio del controller in ingresso NGINX impostando annotazioni del servizio di bilanciamento del carico.

Controller in ingresso NGINX predefinito

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.

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 dell'oggetto in ingresso, l'host e l'indirizzo IP 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 operazione risulta particolarmente utile con un percorso basato sul routing 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.