Annotations pour le contrôleur d’entrée Application Gateway
Vous pouvez annoter la ressource d’entrée Kubernetes avec des paires clé/valeur arbitraires. Application Gateway Ingress Controller (AGIC) s’appuie sur des annotations pour programmer des fonctionnalités d’Azure Application Gateway qui ne sont pas configurables par le biais 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.
Conseil
Consultez également Présentation de Passerelle d’application pour conteneurs.
Liste des annotations prises en charge
Pour qu’AGIC observe une ressource d’entrée, la ressource doit être annotée avec kubernetes.io/ingress.class: azure/application-gateway.
Préfixe du chemin d’accès principal
L’annotation suivante permet de réécrire le chemin d’accès de back-end spécifié dans une ressource d’entrée avec le préfixe spécifié. Utilisez-la pour exposer des services dont les points de terminaison sont différents des noms de points de terminaison que vous utilisez pour exposer un service dans une ressource d’entrée.
Usage
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
L’exemple précédent définit une ressource d’entrée nommée go-server-ingress-bkprefix avec une annotation nommée appgw.ingress.kubernetes.io/backend-path-prefix: "/test/". L’annotation indique à Application Gateway de créer un paramètre HTTP dont le préfixe de chemin d’accès /hello est substitué par /test/.
L’exemple définit une seule règle. Toutefois, les annotations s’appliquent à l’ensemble de la ressource d’entrée. Par conséquent, si vous définissez plusieurs règles, vous configurez le préfixe de chemin d’accès de back-end pour chacun des chemins d’accès spécifiés. Si vous souhaitez des règles différentes avec des préfixes de chemin d’accès différents (même pour le même service), vous devez définir des ressources d’entrée différentes.
Nom d’hôte du back-end
Utilisez l’annotation suivante pour spécifier le nom d’hôte qu’Application Gateway doit utiliser lors de la communication avec les pods.
Usage
appgw.ingress.kubernetes.io/backend-hostname: "internal.example.com"
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-hostname: "internal.example.com"
spec:
rules:
- http:
paths:
- path: /hello/
backend:
service:
name: store-service
port:
number: 80
pathType: Exact
Sonde d’intégrité personnalisée
Vous pouvez configurer Application Gateway pour envoyer des sondes d’intégrité personnalisées au pool d’adresses de back-end. Lorsque les annotations suivantes sont présentes, le contrôleur d’entrée Kubernetes crée une sonde personnalisée pour surveiller l’application back-end. Le contrôleur applique ensuite les modifications à Application Gateway.
health-probe-hostname: cette annotation autorise un nom d’hôte personnalisé sur la sonde d’intégrité.health-probe-port: cette annotation configure un port personnalisé pour la sonde d’intégrité.health-probe-path: cette annotation définit un chemin d’accès pour la sonde d’intégrité.health-probe-status-code: cette annotation permet à la sonde d’intégrité d’accepter différents codes d’état HTTP.health-probe-interval: cette annotation définit l’intervalle d’exécution de la sonde d’intégrité.health-probe-timeout: cette annotation définit la durée pendant laquelle la sonde d’intégrité attend une réponse avant l’échec de la sonde.health-probe-unhealthy-threshold: cette annotation définit le nombre de sondes d’intégrité qui doivent échouer pour que le serveur principal soit marqué comme non sain.
Usage
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
Exemple
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
Redirection TLS
Vous pouvez configurer Application Gateway 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 d’acheminement avec une configuration de redirection. Le contrôleur applique ensuite les modifications à votre instance Application Gateway. La redirection créée est HTTP 301 Moved Permanently.
Usage
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
Utilisez les annotations suivantes si vous souhaitez utiliser le drainage de connexion :
connection-draining: cette annotation spécifie s’il faut activer ou non le drainage de connexion.connection-draining-timeout: cette annotation spécifie 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.
Usage
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
Affinité basée sur les cookies
Utilisez l’annotation suivante pour activer l’affinité basée sur les cookies.
Usage
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
Utilisez l’annotation suivante pour spécifier le délai d’expiration de la requête en secondes. Au terme du délai d’expiration, Application Gateway fait échouer une requête si la réponse n’est pas reçue.
Usage
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
Utilisez l’annotation suivante pour spécifier s’il faut exposer ou non ce point de terminaison sur une adresse IP privée d’Application Gateway.
Pour une instance Application Gateway sans adresse IP privée, les entrées avec appgw.ingress.kubernetes.io/use-private-ip: "true" sont ignorées. Les journaux du contrôleur et les événements d’entrée pour ces entrées affichent un avertissement NoPrivateIP.
Usage
appgw.ingress.kubernetes.io/use-private-ip: "true"
Exemple
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
Remplace le port front-end
Utilisez l’annotation suivante pour configurer un écouteur front-end afin d’utiliser des ports autres que 80 pour HTTP et 443 pour HTTPS.
Si le port se trouve dans la plage autorisée par Application Gateway (allant de 1 à 64999), l’écouteur est créé sur ce port spécifique. Si vous définissez un port non valide ou si aucun port n’est défini dans l’annotation, la configuration utilise la valeur par défaut (80 ou 443).
Usage
appgw.ingress.kubernetes.io/override-frontend-port: "port"
Exemple
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
Remarque
Les requêtes externes doivent cibler http://somehost:8080 au lieu de http://somehost.
Protocole principal
Utilisez ce qui suit pour spécifier le protocole qu’Application Gateway doit utiliser pour communiquer avec les pods. Les protocoles pris en charge sont HTTP et HTTPS.
Bien que les certificats auto-signés soient pris en charge sur Application Gateway, AGIC ne prend actuellement en charge HTTPS que lorsque les pods utilisent un certificat signé par une autorité de certification connue.
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: /
pathType: Exact
backend:
service:
name: go-server-service
port:
number: 443
Extension de nom d’hôte
Vous pouvez configurer Application Gateway pour accepter plusieurs noms d’hôtes. Utilisez l’annotation hostname-extension pour définir plusieurs noms d’hôte, notamment des noms d’hôte génériques. Cette action ajoute les noms d’hôte au nom de domaine complet défini dans les informations d’entrée spec.rules.host sur l’écouteur front-end. Ce dernier est donc configuré en tant qu’écouteur multisite.
Usage
appgw.ingress.kubernetes.io/hostname-extension: "hostname1, hostname2"
Exemple
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’exemple précédent configure l’écouteur afin qu’il accepte le trafic pour les noms d’hôte hostname1.contoso.com et hostname2.contoso.com.
Stratégie WAF pour le chemin d’accès
Utilisez l’annotation suivante pour attacher une stratégie de pare-feu d’applications web (WAF) existante aux chemins d’accès de liste d’un hôte dans une ressource d’entrée Kubernetes en cours d’annotation. La stratégie WAF est appliquée aux URL /ad-server et /auth.
Usage
appgw.ingress.kubernetes.io/waf-policy-for-path: "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/SampleRG/providers/Microsoft.Network/applicationGatewayWebApplicationFirewallPolicies/AGICWAFPolcy"
Exemple
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
Certificat SSL Application Gateway
Vous pouvez configurer le certificat SSL sur Application Gateway à partir d’un fichier de certificat PFX local ou d’une référence à un ID de secret non versionné Azure Key Vault. Lorsque l’annotation est présente avec un nom de certificat et que le certificat est préinstallé dans Application Gateway, le contrôleur d’entrée Kubernetes crée une règle d’acheminement avec un écouteur HTTPS et applique les modifications à votre instance Application Gateway. Vous pouvez également utiliser l’annotation appgw-ssl-certificate avec une annotation ssl-redirect dans le cas d’une redirection SSL.
Remarque
L’annotation appgw-ssl-certificate est ignorée lorsque la spécification TLS est définie en même temps dans l’entrée. Si vous souhaitez utiliser des certificats différents avec des hôtes différents (terminaison de plusieurs certificats TLS), vous devez définir des ressources d’entrée différentes.
Usage
appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
Exemple
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
Profil SSL de la passerelle Application Gateway
Vous pouvez configurer un profil SSL sur l’instance Application Gateway par écouteur. Lorsque l’annotation est présente avec un nom de profil et que le profil est préinstallé dans Application Gateway, le contrôleur d’entrée Kubernetes crée une règle d’acheminement avec un écouteur HTTPS et applique les modifications à votre instance Application Gateway.
Usage
appgw.ingress.kubernetes.io/appgw-ssl-certificate: "name-of-appgw-installed-certificate"
appgw.ingress.kubernetes.io/appgw-ssl-profile: "SampleSSLProfile"
Exemple
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
Certificat racine approuvé Application Gateway
Vous pouvez désormais configurer vos propres certificats racines sur Application Gateway pour qu’ils soient approuvés via AGIC. Vous pouvez utiliser l’annotation appgw-trusted-root-certificate avec l’annotation backend-protocol pour indiquer un chiffrement SSL de bout en bout. Si vous spécifiez plusieurs certificats racines, séparez-les par une virgule ; par exemple, name-of-my-root-cert1,name-of-my-root-cert2.
Usage
appgw.ingress.kubernetes.io/backend-protocol: "https"
appgw.ingress.kubernetes.io/appgw-trusted-root-certificate: "name-of-my-root-cert1"
Exemple
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
Ensemble de règles de réécriture
Utilisez l’annotation suivante pour attribuer un ensemble de règles de réécriture existant à la règle d’acheminement des requêtes correspondantes.
Usage
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
Réécrire la ressource personnalisée de l’ensemble de règles
Remarque
La sortie de Passerelle d’application pour conteneurs introduit de nombreuses modifications en termes de performances, de résilience et de fonctionnalités. Envisagez d’utiliser Passerelle d’application pour conteneurs pour votre prochain déploiement.
Vous trouverez des règles de réécriture d’URL pour Passerelle d’application pour conteneurs dans cet article sur l’API Gateway et cet article sur l’API Ingress. Vous trouverez des règles de réécriture d’en-tête pour Passerelle d’application pour conteneurs dans cet article sur l’API Gateway.
Application Gateway vous permet de réécrire certains contenus de requêtes et de réponses. Avec cette fonctionnalité, vous pouvez traduire des URL, changer des paramètres de chaîne de requête et modifier des en-têtes de requête et de réponse. Vous pouvez également utiliser cette fonctionnalité pour ajouter des conditions garantissant que l’URL ou les en-têtes spécifiés ne sont réécrits que lorsque certaines conditions sont remplies. Réécrire la ressource personnalisée de l’ensemble de règles apporte cette fonctionnalité à AGIC.
Les en-têtes HTTP permettent à un client et à un serveur de transmettre des informations supplémentaires avec une requête ou une réponse. En réécrivant ces en-têtes, vous pouvez effectuer des tâches importantes, comme l’ajout de champs d’en-tête liés à la sécurité (par exemple, HSTS ou X-XSS-Protection), la suppression des champs d’en-tête de réponse susceptibles de révéler des informations sensibles et la suppression des informations de port des en-têtes X-Forwarded-For.
Avec la fonctionnalité de réécriture d’URL, vous pouvez :
- Réécrire le nom d’hôte, le chemin d’accès et la chaîne de requête de l’URL de requête.
- Choisir de réécrire l’URL de toutes les requêtes ou uniquement des requêtes qui correspondent à une ou plusieurs des conditions que vous avez définies. Ces conditions sont basées sur les propriétés de requête et de réponse (en-tête de requête, en-tête de réponse et variables de serveur).
- Choisir d’acheminer la requête en fonction de l’URL d’origine ou de l’URL réécrite.
Remarque
Cette fonctionnalité est prise en charge depuis la version 1.6.0-rc1. Utilisez appgw.ingress.kubernetes.io/rewrite-rule-set, qui permet d’utiliser un jeu de règles de réécriture existant sur Application Gateway.
Usage
appgw.ingress.kubernetes.io/rewrite-rule-set-custom-resource
Exemple
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é des règles
L’annotation suivante permet au contrôleur d’entrée Application Gateway de définir explicitement la priorité des règles d’acheminement des requêtes associées.
Usage
appgw.ingress.kubernetes.io/rule-priority:
Exemple
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
L’exemple précédent définit une priorité de 10 pour la règle d’acheminement des requêtes.