Condividi tramite

Annotazioni per il Controller in ingresso del gateway applicazione

Alla risorsa Kubernetes in ingresso possono essere associate annotazioni 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

Prendere in considerazione il gateway applicazione per contenitori per la soluzione in ingresso Kubernetes. Per altre informazioni, vedere Guida introduttiva - Distribuire gateway applicazione per il controller ALB dei contenitori.

Elenco di annotazioni supportate

Affinché il controller AGIC osservi una risorsa in ingresso, la risorsa deve essere annotata con kubernetes.io/ingress.class: azure/application-gateway.

Chiave di annotazione Tipo di valore Valore predefinito Valori consentiti
appgw.ingress.kubernetes.io/backend-path-prefix string nil
appgw.ingress.kubernetes.io/backend-hostname string nil
appgw.ingress.kubernetes.io/health-probe-hostname string 127.0.0.1
appgw.ingress.kubernetes.io/health-probe-port int32 80
appgw.ingress.kubernetes.io/health-probe-path string /
appgw.ingress.kubernetes.io/health-probe-status-codes string 200-399
appgw.ingress.kubernetes.io/health-probe-interval int32 30 (secondi)
appgw.ingress.kubernetes.io/health-probe-timeout int32 30 (secondi)
appgw.ingress.kubernetes.io/health-probe-unhealthy-threshold int32 3
appgw.ingress.kubernetes.io/ssl-redirect bool false
appgw.ingress.kubernetes.io/connection-draining bool false
appgw.ingress.kubernetes.io/connection-draining-timeout int32 (secondi) 30
appgw.ingress.kubernetes.io/use-private-ip bool false
appgw.ingress.kubernetes.io/override-frontend-port bool false
appgw.ingress.kubernetes.io/cookie-based-affinity bool false
appgw.ingress.kubernetes.io/request-timeout int32 (secondi) 30
appgw.ingress.kubernetes.io/use-private-ip bool false
appgw.ingress.kubernetes.io/backend-protocol string http http, https
appgw.ingress.kubernetes.io/hostname-extension string nil
appgw.ingress.kubernetes.io/waf-policy-for-path string nil
appgw.ingress.kubernetes.io/appgw-ssl-certificate string nil
appgw.ingress.kubernetes.io/appgw-ssl-profile string nil
appgw.ingress.kubernetes.io/appgw-trusted-root-certificate string nil
appgw.ingress.kubernetes.io/rewrite-rule-set string nil
appgw.ingress.kubernetes.io/rewrite-rule-set-custom-resource
appgw.ingress.kubernetes.io/rule-priority int32 nil

Prefisso del percorso back-end

L'annotazione seguente consente di riscrivere il percorso back-end indicato in una risorsa in ingresso con il prefisso specificato. Usarla per esporre i servizi i cui endpoint sono diversi dai nomi degli endpoint usati per esporre un servizio in una risorsa di ingresso.

Uso

appgw.ingress.kubernetes.io/backend-path-prefix: <path prefix>

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-bkprefix
  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 per il percorso da /hello a /test/.

L'esempio definisce una sola regola. Tuttavia, le annotazioni si applicano all'intera risorsa in ingresso. Pertanto, se si definiscono più regole, si configura il prefisso del percorso back-end per ciascuno dei percorsi specificati. Se si desidera avere regole diverse con prefissi di percorso differenti, anche per lo stesso servizio, è necessario definire risorse in ingresso diverse.

Nome host back-end

Usare l’annotazione seguente per specificare il nome host che il gateway applicazione deve usare nella comunicazione con i pod.

Uso

appgw.ingress.kubernetes.io/backend-hostname: "internal.example.com"

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-timeout
  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 Application Gateway per inviare una sonda di monitoraggio personalizzata al pool di indirizzi backend. Quando sono presenti le annotazioni seguenti, il controller in 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-codes: 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.

Uso

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-codes: "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
  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-codes: "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 in 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.

Uso

appgw.ingress.kubernetes.io/ssl-redirect: "true"

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-redirect
  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 della connessione

Se si intende usare lo svuotamento della connessione, usare le annotazioni seguenti:

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

Uso

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

Per abilitare l'affinità basata su cookie, usare l'annotazione seguente.

Uso

appgw.ingress.kubernetes.io/cookie-based-affinity: "true"

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-affinity
  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

Per specificare il timeout della richiesta in secondi, usare l'annotazione seguente. Dopo il timeout, il gateway applicazione restituisce esito negativo per la richiesta se la risposta non viene ricevuta.

Uso

appgw.ingress.kubernetes.io/request-timeout: "20"

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-timeout
  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 l'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 in ingresso per tali ingressi visualizzano un avviso NoPrivateIP.

Uso

appgw.ingress.kubernetes.io/use-private-ip: "true"

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-privateip
  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.

Uso

appgw.ingress.kubernetes.io/override-frontend-port: "port"

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-overridefrontendport
  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

Note

Le richieste esterne devono avere come destinazione http://somehost:8080 anziché http://somehost.

Protocollo back-end

Usare l'annotazione seguente per specificare il protocollo che il gateway applicazione deve usare quando comunica con i pod. I protocolli supportati sono HTTP e HTTPS.

Sebbene i certificati autofirmati siano supportati nel gateway applicazione, il controller 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.

Uso

appgw.ingress.kubernetes.io/backend-protocol: "https"

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-timeout
  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 al nome di dominio completo definito nelle informazioni spec.rules.host in ingresso sul listener front-end per configurarlo come un listener multisito.

Uso

appgw.ingress.kubernetes.io/hostname-extension: "hostname1, hostname2"

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-multisite
  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.

Criteri WAF per il percorso

Usare l'annotazione seguente per collegare i criteri web application firewall (WAF) esistenti ai percorsi di elenchi per un host in una risorsa in ingresso Kubernetes annotata. I criteri WAF vengono applicati agli URL /ad-server e /auth.

Uso

appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/SampleRG/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/AGICWAFPolcy"

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: ad-server-ingress
  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 senza versione di Azure Key Vault. Quando l'annotazione è presente con un nome certificato e il certificato è 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. È anche possibile usare l'annotazione appgw-ssl-certificate con un'annotazione ssl-redirect nel caso di un reindirizzamento SSL.

Note

L'annotazione appgw-ssl-certificate viene ignorata quando la specifica TLS è definita contemporaneamente in ingresso. Se si vogliono certificati diversi con host diversi (terminazione di più certificati TLS), è necessario definire risorse in ingresso diverse.

Uso

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

Uso

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
  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 il controller AGIC. È possibile usare l'annotazione appgw-trusted-root-certificate con l'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.

Uso

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

Uso

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

Note

Il rilascio del gateway applicazione per contenitori introduce numerose modifiche a prestazioni, resilienza e funzionalità. Prendere in considerazione l'uso del gateway applicazione per contenitori per la distribuzione successiva.

È possibile trovare regole di riscrittura URL per il gateway applicazione per contenitori in questo articolo sull’API gateway e in questo articolo sull'API in ingresso. È possibile trovare le regole di riscrittura delle intestazioni per il gateway applicazione 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 URL nonché modificare parametri della stringa di query e intestazioni di richieste e risposte. È anche possibile usare questa funzionalità per aggiungere le condizioni necessarie al fine di garantire che l'URL o le intestazioni specificate vengono riscritte solo se 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 le intestazioni, è possibile eseguire attività importanti come l'aggiunta di campi di intestazione correlati alla sicurezza, ad esempio HSTS o X-XSS-Protection, la rimozione di campi di intestazione della risposta che potrebbero rivelare informazioni riservate e la rimozione delle 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 di quelle che corrispondono a una o più delle condizioni impostate. Tali condizioni si basano sulle proprietà della richiesta e della risposta (intestazione di richiesta e risposta e variabili server).
  • Scegliere di instradare la richiesta in base all'URL originale o all'URL riscritto.

Note

Questa funzionalità è supportata a partire dalla versione 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.

Uso

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 in ingresso del gateway applicazione di impostare in modo esplicito la priorità delle regole di gestione delle richieste associate.

Uso

appgw.ingress.kubernetes.io/rule-priority:

Esempio

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: go-server-ingress-rulepriority
  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.

Passaggi successivi

  • Last updated on