Annotazioni per il Controller in ingresso del gateway applicazione
La risorsa ingresso Kubernetes può essere annotata con coppie chiave/valore arbitrarie. Il controller in ingresso del gateway applicazione (Application Gateway Ingress Controller, AGIC) si basa sulle annotazioni per programmare le funzionalità del gateway applicazione di Azure che non sono configurabili tramite YAML in ingresso. Le annotazioni in ingresso vengono applicate a tutte le impostazioni HTTP, i pool back-end e i listener derivati da una risorsa di ingresso.
Suggerimento
Vedere anche Che cos'è Gateway applicativo per contenitori.
Elenco di annotazioni supportate
Affinché AGIC osservi una risorsa in ingresso, la risorsa deve essere annotata con kubernetes.io/ingress.class: azure/application-gateway.
Prefisso del percorso back-end
L'annotazione seguente consente di riscrivere il percorso back-end specificato in una risorsa in ingresso con il prefisso specificato. Usare ciò per esporre i servizi i cui endpoint sono diversi dai nomi degli endpoint usati per esporre un servizio in una risorsa di ingresso.
Utilizzo
appgw.ingress.kubernetes.io/backend-path-prefix: <path prefix>
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-bkprefix
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/backend-path-prefix: "/test/"
spec:
rules:
- http:
paths:
- path: /hello/
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 80
L'esempio precedente definisce una risorsa di ingresso denominata go-server-ingress-bkprefix con un'annotazione denominata appgw.ingress.kubernetes.io/backend-path-prefix: "/test/". L'annotazione indica al gateway applicazione di creare un'impostazione HTTP con un override del prefisso del percorso per il percorso da /hello a /test/.
L'esempio definisce una sola regola. Tuttavia, le annotazioni si applicano all'intera risorsa di ingresso. Pertanto, se si definiscono più regole, si configura il prefisso del percorso back-end per ognuno dei percorsi specificati. Se si vogliono regole diverse con prefissi di percorso diversi (persino per lo stesso servizio), è necessario definire risorse di ingresso diverse.
Nome host back-end
Usare l’annotazione seguente per specificare il nome host che il gateway applicazione deve usare durante la comunicazione con i pod.
Utilizzo
appgw.ingress.kubernetes.io/backend-hostname: "internal.example.com"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-timeout
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/backend-hostname: "internal.example.com"
spec:
rules:
- http:
paths:
- path: /hello/
backend:
service:
name: store-service
port:
number: 80
pathType: Exact
Probe di integrità personalizzato
È possibile configurare il gateway applicazione per inviare probe di integrità personalizzati al pool di indirizzi back-end. Quando sono presenti le annotazioni seguenti, il controller di ingresso Kubernetes crea un probe personalizzato per monitorare l'applicazione back-end. Il controller applica quindi le modifiche al gateway applicazione.
health-probe-hostname: questa annotazione consente un nome host personalizzato nel probe di integrità.health-probe-port: questa annotazione configura una porta personalizzata per il probe di integrità.health-probe-path: questa annotazione definisce un percorso per il probe di integrità.health-probe-status-code: questa annotazione consente al probe di integrità di accettare codici di stato HTTP diversi.health-probe-interval: questa annotazione definisce l'intervallo in cui viene eseguito il probe di integrità.health-probe-timeout: questa annotazione definisce per quanto tempo il probe di integrità attende una risposta prima dell'esito negativo del probe.health-probe-unhealthy-threshold: questa annotazione definisce il numero di probe di integrità che devono avere esito negativo affinché il back-end venga contrassegnato come non integro.
Utilizzo
appgw.ingress.kubernetes.io/health-probe-hostname: "contoso.com"
appgw.ingress.kubernetes.io/health-probe-port: 80
appgw.ingress.kubernetes.io/health-probe-path: "/"
appgw.ingress.kubernetes.io/health-probe-status-code: "100-599"
appgw.ingress.kubernetes.io/health-probe-interval: 30
appgw.ingress.kubernetes.io/health-probe-timeout: 30
appgw.ingress.kubernetes.io/health-probe-unhealthy-threshold: 2
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/health-probe-hostname: "contoso.com"
appgw.ingress.kubernetes.io/health-probe-port: 81
appgw.ingress.kubernetes.io/health-probe-path: "/probepath"
appgw.ingress.kubernetes.io/health-probe-status-code: "100-599"
appgw.ingress.kubernetes.io/health-probe-interval: 31
appgw.ingress.kubernetes.io/health-probe-timeout: 31
appgw.ingress.kubernetes.io/health-probe-unhealthy-threshold: 2
spec:
rules:
- http:
paths:
- path: /
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 80
Reindirizzamento TLS
È possibile configurare il gateway applicazione per reindirizzare automaticamente gli URL HTTP alle controparti HTTPS. Quando questa annotazione è presente e TLS è configurato correttamente, il controller di ingresso Kubernetes crea una regola di gestione con una configurazione di reindirizzamento. Il controller applica quindi le modifiche all'istanza del gateway applicazione. Il reindirizzamento creato è HTTP 301 Moved Permanently.
Utilizzo
appgw.ingress.kubernetes.io/ssl-redirect: "true"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-redirect
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/ssl-redirect: "true"
spec:
tls:
- hosts:
- www.contoso.com
secretName: testsecret-tls
rules:
- host: www.contoso.com
http:
paths:
- backend:
service:
name: websocket-repeater
port:
number: 80
Svuotamento delle connessioni
Usare le annotazioni seguenti se si vuole usare lo svuotamento della connessione:
connection-draining: questa annotazione specifica se abilitare lo svuotamento della connessione.connection-draining-timeout: questa annotazione specifica un timeout, dopo il quale il gateway applicazione termina le richieste all'endpoint back-end di svuotamento.
Utilizzo
appgw.ingress.kubernetes.io/connection-draining: "true"
appgw.ingress.kubernetes.io/connection-draining-timeout: "60"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-drain
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/connection-draining: "true"
appgw.ingress.kubernetes.io/connection-draining-timeout: "60"
spec:
rules:
- http:
paths:
- path: /hello/
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 80
Affinità basata sui cookie
Usare l'annotazione seguente per abilitare l'affinità basata su cookie.
Utilizzo
appgw.ingress.kubernetes.io/cookie-based-affinity: "true"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-affinity
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/cookie-based-affinity: "true"
spec:
rules:
- http:
paths:
- path: /hello/
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 80
Timeout richiesta
Usare l'annotazione seguente per specificare il timeout della richiesta in secondi. Dopo il timeout, il gateway applicazione fallisce nel caso di richiesta se la risposta non viene ricevuta.
Utilizzo
appgw.ingress.kubernetes.io/request-timeout: "20"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-timeout
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/request-timeout: "20"
spec:
rules:
- http:
paths:
- path: /hello/
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 80
Usare l'indirizzo IP privato
Usare l'annotazione seguente per specificare se esporre questo endpoint in un indirizzo IP privato del gateway applicazione.
Per un'istanza del gateway applicazione che non dispone di un indirizzo IP privato, i dati in ingresso con appgw.ingress.kubernetes.io/use-private-ip: "true" vengono ignorati. I log del controller e gli eventi di ingresso per tali dati in ingresso visualizzano un avviso NoPrivateIP.
Utilizzo
appgw.ingress.kubernetes.io/use-private-ip: "true"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-privateip
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/use-private-ip: "true"
spec:
rules:
- http:
paths:
- path: /
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 80
Eseguire l'override della porta front-end
Usare l'annotazione seguente per configurare un listener front-end per usare porte diverse da 80 per HTTP e 443 per HTTPS.
Se la porta è compresa nell'intervallo autorizzato del gateway applicazione (da 1 a 64999), il listener viene creato su questa porta specifica. Se si imposta una porta non valida o nessuna porta nell'annotazione, la configurazione usa il valore predefinito 80 o 443.
Utilizzo
appgw.ingress.kubernetes.io/override-frontend-port: "port"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-overridefrontendport
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/override-frontend-port: "8080"
spec:
rules:
- http:
paths:
- path: /hello/
backend:
service:
name: store-service
port:
number: 80
pathType: Exact
Nota
La richiesta esterna devono avere come destinazione http://somehost:8080 anziché http://somehost.
Protocollo back-end
Usare quanto segue per specificare il protocollo che il gateway applicazione deve usare quando comunica con i pod. I protocolli supportati sono HTTP e HTTPS.
Anche se i certificati autofirmati sono supportati nel gateway applicazione, AGIC supporta attualmente HTTPS solo quando i pod usano un certificato firmato da un'autorità di certificazione nota.
Non usare la porta 80 con HTTPS e la porta 443 con HTTP nei pod.
Utilizzo
appgw.ingress.kubernetes.io/backend-protocol: "https"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-timeout
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/backend-protocol: "https"
spec:
rules:
- http:
paths:
- path: /
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 443
Estensione del nome host
È possibile configurare il gateway applicazione per accettare più nomi host. Usare l'annotazione hostname-extension per definire più nomi host, inclusi i nomi host con caratteri jolly. Questa azione aggiunge i nomi host all'FQDN definito nelle informazioni spec.rules.host di ingresso sul listener frontend, quindi questo è configurato come un listener multisito.
Utilizzo
appgw.ingress.kubernetes.io/hostname-extension: "hostname1, hostname2"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-multisite
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/hostname-extension: "hostname1, hostname2"
spec:
rules:
- host: contoso.com
http:
paths:
- path: /
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 443
L'esempio precedente configura il listener per accettare il traffico per i nomi host hostname1.contoso.com e hostname2.contoso.com.
Criterio WAF per il percorso
Usare l'annotazione seguente per collegare un criterio web application firewall (WAF) esistente ai percorsi di elenco per un host all'interno di una risorsa di ingresso Kubernetes annotata. I criteri WAF vengono applicati agli URL /ad-server e /auth.
Utilizzo
appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/aaaa0000-bb11-2222-33cc-444444dddddd/resourceGroups/SampleRG/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/AGICWAFPolcy"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ad-server-ingress
namespace: commerce
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/abcd/resourceGroups/rg/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/adserver"
spec:
rules:
- http:
paths:
- path: /ad-server
backend:
service:
name: ad-server
port:
number: 80
pathType: Exact
- path: /auth
backend:
service:
name: auth-server
port:
number: 80
pathType: Exact
Certificato SSL del gateway applicazione
È possibile configurare il certificato SSL nel gateway applicazione da un file di certificato PFX locale o da un riferimento a un ID segreto non modificato di Azure Key Vault. Quando l'annotazione è presente con un nome certificato e il certificato è preinstallato nel gateway applicazione, il controller di ingresso Kubernetes crea una regola di gestione con un listener HTTPS e applica le modifiche all'istanza del gateway applicazione. È anche possibile usare l'annotazione appgw-ssl-certificate insieme a un'annotazione ssl-redirect nel caso di un reindirizzamento SSL.
Nota
L'annotazione appgw-ssl-certificate viene ignorata quando la specifica TLS viene definita contemporaneamente in ingresso. Se si vogliono certificati diversi con host diversi (terminazione di più certificati TLS), è necessario definire risorse di ingresso diverse.
Utilizzo
appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-certificate
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
spec:
rules:
- host: www.contoso.com
http:
paths:
- backend:
service:
name: websocket-repeater
port:
number: 80
Profilo SSL del gateway applicazione
È possibile configurare un profilo SSL nell'istanza del gateway applicazione per ogni listener. Quando l'annotazione è presente con un nome del profilo e il profilo è preinstallato nel gateway applicazione, il controller in ingresso Kubernetes crea una regola di gestione con un listener HTTPS e applica le modifiche all'istanza del gateway applicazione.
Utilizzo
appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
appgw.ingress.kubernetes.io/appgw-ssl-profile: "SampleSSLProfile"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-certificate
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
appgw.ingress.kubernetes.io/appgw-ssl-profile: "SampleSSLProfile"
spec:
rules:
- host: www.contoso.com
http:
paths:
- backend:
service:
name: websocket-repeater
port:
number: 80
Certificato radice trusted del gateway applicazione
Ora è possibile configurare i propri certificati radice nel gateway applicazione in modo che siano attendibili tramite AGIC. È possibile usare l'annotazione appgw-trusted-root-certificate insieme all'annotazione backend-protocol per indicare la crittografia SSL end-to-end. Se si specificano più certificati radice, separarli con una virgola, ad esempio name-of-my-root-cert1,name-of-my-root-cert2.
Utilizzo
appgw.ingress.kubernetes.io/backend-protocol: "https"
appgw.ingress.kubernetes.io/appgw-trusted-root-certificate: "name-of-my-root-cert1"
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-certificate
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/backend-protocol: "https"
appgw.ingress.kubernetes.io/appgw-trusted-root-certificate: "name-of-my-root-cert1"
spec:
rules:
- host: www.contoso.com
http:
paths:
- backend:
service:
name: websocket-repeater
port:
number: 80
Riscrivere il set di regole
Usare l’annotazione seguente per assegnare un set di regole di riscrittura esistente alla regola di gestione della richiesta corrispondente.
Utilizzo
appgw.ingress.kubernetes.io/rewrite-rule-set: <rewrite rule set name>
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-bkprefix
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/rewrite-rule-set: add-custom-response-header
spec:
rules:
- http:
paths:
- path: /
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 8080
Riscrivere una risorsa personalizzata del set di regole
Nota
Il rilascio di Gateway applicativo per contenitori introduce numerose modifiche a prestazioni, resilienza e funzionalità. Prendere in considerazione l'uso del Gateway applicativo per contenitori per la distribuzione successiva.
È possibile trovare regole di riscrittura URL per il Gateway applicativo per contenitori in questo articolo sull’API gateway e questo articolo sull'API In ingresso. È possibile trovare le regole di riscrittura delle intestazioni per il Gateway applicativo per contenitori in questo articolo sull'API gateway.
Il gateway applicazione consente di riscrivere il contenuto selezionato di richieste e risposte. Con questa funzionalità è possibile tradurre gli URL, modificare i parametri della stringa di query e modificare le intestazioni di richiesta e risposta. Inoltre è possibile usare questa funzionalità per aggiungere condizioni per assicurarsi che l'URL o le intestazioni specificate vengano riscritte solo quando vengono soddisfatte determinate condizioni. La riscrittura della risorsa personalizzata del set di regole porta questa funzionalità in AGIC.
Le intestazioni HTTP consentono al client e al server di passare informazioni aggiuntive insieme a una richiesta o a una risposta. Riscrivendo queste intestazioni, è possibile eseguire attività importanti come l'aggiunta di campi di intestazione correlati alla sicurezza (ad esempio, HSTS o X-XSS-Protection), rimuovendo i campi di intestazione della risposta che potrebbero rivelare informazioni riservate e rimuovendo le informazioni sulla porta dalle intestazioni X-Forwarded-For.
Con la funzionalità di riscrittura URL, è possibile:
- Riscrivere il nome host, il percorso e la stringa di query dell'URL della richiesta.
- Scegliere di riscrivere l'URL di tutte le richieste o solo le richieste che corrispondono a una o più delle condizioni impostate. Queste condizioni sono basate sulle proprietà della richiesta e della risposta (intestazione della richiesta, intestazione della risposta e variabili del server).
- Scegliere di instradare la richiesta in base all'URL originale o all'URL riscritto
Nota
Questa funzionalità è supportata a partire da 1.6.0-rc1. Usare appgw.ingress.kubernetes.io/rewrite-rule-set, che consente l'uso di un set di regole di riscrittura esistente nel gateway applicazione.
Utilizzo
appgw.ingress.kubernetes.io/rewrite-rule-set-custom-resource
Esempio
apiVersion: appgw.ingress.azure.io/v1beta1
kind: AzureApplicationGatewayRewrite
metadata:
name: my-rewrite-rule-set-custom-resource
spec:
rewriteRules:
- name: rule1
ruleSequence: 21
conditions:
- ignoreCase: false
negate: false
variable: http_req_Host
pattern: example.com
actions:
requestHeaderConfigurations:
- actionType: set
headerName: incoming-test-header
headerValue: incoming-test-value
responseHeaderConfigurations:
- actionType: set
headerName: outgoing-test-header
headerValue: outgoing-test-value
urlConfiguration:
modifiedPath: "/api/"
modifiedQueryString: "query=test-value"
reroute: false
Priorità delle regole
L'annotazione seguente consente al controller di ingresso del gateway applicazione di impostare in modo esplicito la priorità delle regole di gestone delle richieste associate.
Utilizzo
appgw.ingress.kubernetes.io/rule-priority:
Esempio
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: go-server-ingress-rulepriority
namespace: test-ag
annotations:
kubernetes.io/ingress.class: azure/application-gateway
appgw.ingress.kubernetes.io/rule-priority: 10
spec:
rules:
- http:
paths:
- path: /
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 8080
Nell'esempio precedente viene impostata una priorità pari a 10 per la regola di gestione della richiesta.