Annotazioni per il Controller in ingresso del gateway applicazione

  • Articolo

La risorsa ingresso Kubernetes può essere annotata con coppie chiave/valore arbitrarie. AGIC si basa sulle annotazioni per programmare le funzionalità del gateway applicazione, 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.

Elenco di annotazioni supportate

Affinché una risorsa in ingresso venga osservata da AGIC, deve essere annotata con kubernetes.io/ingress.class: azure/application-gateway. Solo AGIC funziona con la risorsa ingresso in questione.

Chiave di annotazione Tipo di valore Valore predefinito Valori consentiti
appgw.ingress.kubernetes.io/backend-path-prefix string nil
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/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/rewrite-rule-set string nil

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 in questa annotazione. Consente agli utenti di 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

Nell'esempio precedente è stata definita una risorsa di ingresso chiamata go-server-ingress-bkprefix con un'annotazione 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/.

Nota

Nell'esempio precedente viene definita una sola regola. Tuttavia, le annotazioni sono applicabili all'intera risorsa di ingresso, quindi se un utente ha definito più regole, il prefisso del percorso back-end verrà configurato per ognuno dei percorsi specificati. Se un utente vuole regole diverse con prefissi di percorso diversi (persino per lo stesso servizio), è necessario definire risorse di ingresso diverse.

Reindirizzamento TLS

Il gateway applicazione può essere configurato per reindirizzare automaticamente gli URL HTTP alle controparti HTTPS. Quando questa annotazione è presente e il TLS è configurato correttamente, il controller di ingresso Kubernetes crea una regola di routing con una configurazione di reindirizzamento e applica le modifiche al gateway applicazione. Il reindirizzamento creato sarà 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

connection-draining: questa annotazione consente di specificare se abilitare lo svuotamento delle connessioni. connection-draining-timeout: questa annotazione consente di specificare 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

L'annotazione seguente consente di specificare se 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

L'annotazione seguente consente di specificare il timeout della richiesta in secondi, dopo il quale il gateway applicazione non esegue la 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

L'annotazione seguente consente di specificare se esporre questo endpoint nell'indirizzo IP privato del gateway applicazione.

Nota

  • Il gateway applicazione non supporta più indirizzi IP sulla stessa porta (ad esempio: 80/443). L'ingresso con annotazione appgw.ingress.kubernetes.io/use-private-ip: "false" e un altro con appgw.ingress.kubernetes.io/use-private-ip: "true" in HTTP causerà un errore di AGIC durante l'aggiornamento del gateway applicazione.
  • Per il gateway applicazione che non ha un indirizzo IP privato, l'ingresso con appgw.ingress.kubernetes.io/use-private-ip: "true" viene ignorato. Ciò si riflette nei log del controller e negli ingressi con NoPrivateIP avviso.

Utilizzo

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

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/use-private-ip: "true"
spec:
  rules:
  - http:
      paths:
      - path: /hello/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 80

Protocollo back-end

L'annotazione seguente consente di specificare il protocollo che il gateway applicazione deve usare durante la comunicazione con i pod. I protocolli supportati sono http e https.

Nota

Mentre i certificati autofirmati sono supportati nel gateway applicazione, attualmente AGIC supporta solo https quando i pod usano un certificato firmato da una CA 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: /hello/
        pathType: Exact
        backend:
          service:
            name: go-server-service
            port:
              number: 443

Riscrivere il set di regole

L'annotazione seguente consente di assegnare un set di regole di riscrittura esistente alla regola di routing 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