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.
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 predefinitaNginxIngressController
.Internal
: il controller di ingresso Nginx predefinito viene creato con un servizio di bilanciamento del carico interno. Tutte le annotazioni apportate allaNginxIngressController
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 allaNginxIngressController
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 predefinitaNginxIngressController
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:
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
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:
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"
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:
Creare un gruppo di risorse di Azure con il comando
az group create
.az group create --name myNetworkResourceGroup --location eastus
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.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}
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 oppureservice.beta.kubernetes.io/azure-load-balancer-ipv4
per un indirizzo IPv4 eservice.beta.kubernetes.io/azure-load-balancer-ipv6
per un indirizzo IPv6, come illustrato nell'esempio relativo a YAML. L'aggiunta dell'annotazioneservice.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"
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
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 diNginxIngressController
.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
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.
Azure Kubernetes Service