Annotations pour le contrôleur d’entrée Application Gateway

  • Article

La ressource d’entrée Kubernetes peut être annotée avec des paires clé/valeur arbitraires. AGIC s’appuie sur les annotations pour programmer des fonctionnalités Application Gateway, qui ne sont pas configurables à l’aide du YAML d’entrée. Les annotations d’entrée sont appliquées à tous les paramètres HTTP, pools de back-ends et écouteurs dérivés d’une ressource d’entrée.

Liste des annotations prises en charge

Pour qu’une ressource d’entrée soit observée par AGIC, elle doit être annotée avec kubernetes.io/ingress.class: azure/application-gateway. Ce n’est qu’à ce moment-là qu’AGIC fonctionne avec la ressource d’entrée en question.

Clé d’annotation Type de valeur Valeur par défaut Valeurs autorisées
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 (secondes) 30
appgw.ingress.kubernetes.io/cookie-based-affinity bool false
appgw.ingress.kubernetes.io/request-timeout int32 (secondes) 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

Préfixe du chemin d’accès principal

L’annotation suivante permet de réécrire le chemin de back-end spécifié dans une ressource d’entrée avec le préfixe spécifié dans cette annotation. Elle permet aux utilisateurs d’exposer des services dont les points de terminaison sont différents des noms de point de terminaison utilisés pour exposer un service dans une ressource d’entrée.

Utilisation

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

Exemple

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

Dans l’exemple précédent, nous avons défini une ressource d’entrée nommée go-server-ingress-bkprefix avec une annotation appgw.ingress.kubernetes.io/backend-path-prefix: "/test/". L’annotation indique à la passerelle applicative de créer un paramètre HTTP, dont le préfixe de chemin /hello est substitué par /test/.

Remarque

Dans l’exemple ci-dessus, une seule règle est définie. Toutefois, les annotations sont applicables à l’ensemble de la ressource d’entrée. Par conséquent, si un utilisateur a défini plusieurs règles, le préfixe de chemin de back-end sera configuré pour chacun des chemins spécifiés. Ainsi, si un utilisateur souhaite des règles différentes avec des préfixes de chemin différents (même pour le même service), il a besoin de définir des ressources d’entrée différentes.

Redirection TLS

Application Gateway peut être configurée pour rediriger automatiquement les URL HTTP vers leur équivalent HTTPS. Quand cette annotation est présente et que le protocole TLS est correctement configuré, le contrôleur d’entrée Kubernetes crée une règle de routage avec une configuration de redirection et applique les modifications à votre Application Gateway. La redirection créée sera HTTP 301 Moved Permanently.

Utilisation

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

Exemple

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

Drainage de la connexion

connection-draining : Cette annotation nous permet de spécifier si le drainage de connexion doit être activé ou non. connection-draining-timeout : Cette annotation nous permet de spécifier un délai d’expiration, après lequel Application Gateway met fin aux requêtes adressées au point de terminaison back-end de drainage.

Utilisation

appgw.ingress.kubernetes.io/connection-draining: "true"
appgw.ingress.kubernetes.io/connection-draining-timeout: "60"

Exemple

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’annotation suivante vous permet de spécifier si l’affinité basée sur les cookies doit être activée ou non.

Utilisation

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

Exemple

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

Délai de demande

L’annotation suivante vous permet de spécifier le délai d’expiration de la requête en secondes, à l’issue duquel Application Gateway fait échouer la requête si la réponse n’est pas reçue.

Utilisation

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

Exemple

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

Utiliser une adresse IP privée

L’annotation suivante vous permet de spécifier si l’exposition de ce point de terminaison est nécessaire ou non sur le protocole Internet (IP) privé d’Application Gateway.

Remarque

  • Application Gateway ne prend pas en charge plusieurs IP sur le même port (par exemple : 80/443). Une entrée avec l’annotation appgw.ingress.kubernetes.io/use-private-ip: "false" et une autre avec appgw.ingress.kubernetes.io/use-private-ip: "true" sur HTTP entraînent l’échec d’AGIC pendant la mise à jour d’Application Gateway.
  • Pour Application Gateway sans IP privé, les entrées avec appgw.ingress.kubernetes.io/use-private-ip: "true" sont ignorées. Cela se reflète dans les journaux du contrôleur et les événements d’entrée pour les entrées avec l’avertissement NoPrivateIP.

Utilisation

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

Exemple

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

Protocole principal

L’annotation suivante vous permet de spécifier le protocole qu’Application Gateway doit utiliser lors de la communication avec les pods. Les protocoles pris en charge sont http et https.

Remarque

Alors que les certificats auto-signés sont pris en charge sur Application Gateway, AGIC prend actuellement en charge https uniquement quand des pods utilisent un certificat signé par une autorité de certification reconnue.

N’utilisez pas le port 80 avec HTTPS ni le port 443 avec HTTP sur les pods.

Utilisation

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

Exemple

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

Ensemble de règles de réécriture

L’annotation suivante vous permet d’attribuer un ensemble de règles de réécriture existant à la règle de routage des requêtes correspondante.

Utilisation

appgw.ingress.kubernetes.io/rewrite-rule-set: <rewrite rule set name>

Exemple

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