Les passerelles MSE Ingress prennent en charge les annotations principales et courantes des passerelles NGINX Ingress, ce qui simplifie la migration. Elles proposent également 40 annotations supplémentaires pour une gestion avancée du trafic.
Les ressources Kubernetes Ingress standard ne gèrent que le chiffrement TLS (Transport Layer Security) et le routage HTTP de base au niveau de la couche 7. Les contrôleurs NGINX Ingress définissent à eux seuls plus de 100 annotations personnalisées pour répondre aux exigences réelles en matière de gestion du trafic et de sécurité. Les passerelles MSE Ingress sont compatibles avec les annotations NGINX Ingress les plus courantes, permettant ainsi de migrer les charges de travail existantes sans réécrire les configurations Ingress.
Présentation
Le tableau suivant résume la couverture des annotations.
Couverture des annotations NGINX Ingress
| Catégorie | Nombre | Notes |
|---|---|---|
| Pris en charge | 51 | Couvre 90 % des cas d'utilisation |
| Aucune configuration requise | 15 | La fonctionnalité est disponible sans configuration explicite |
| Prévu | 48 | S'applique à un nombre restreint de cas d'utilisation |
| Non pris en charge | 5 | Lié à des extraits de code spécifiques à NGINX |
MSE implémente les fonctionnalités différemment de NGINX. Les variables NGINX utilisées dans les annotations et les extraits de code NGINX Ingress ne sont pas compatibles avec leurs équivalents NGINX.
Corps de requête volumineux : L'annotation nginx.ingress.kubernetes.io/proxy-body-size définit une taille maximale pour le corps de la requête dans NGINX et rejette tout contenu dépassant cette limite. MSE utilise plutôt l'encodage par transfert fragmenté (chunked transfer encoding), qui gère automatiquement les corps volumineux sans limite de taille. Pour définir les limites du tampon de connexion amont, configurez le paramètre DownstreamConnectionBufferLimits dans le volet Parameter Settings de votre passerelle MSE.
Redirections et variables NGINX : Les variables NGINX (telles que $host ou $request_uri) dans les annotations de redirection peuvent fonctionner dans certaines versions de NGINX Ingress, mais elles ne sont pas documentées officiellement. Évitez d'utiliser des variables NGINX pour les redirections dans NGINX Ingress, car elles ne sont pas compatibles avec MSE.
Annotations exclusives à MSE
| Catégorie | Nombre | Notes |
|---|---|---|
| Annotations étendues | 40 | Ajoute des capacités de gouvernance du trafic et de protection de la sécurité au-delà de NGINX Ingress |
Portée des annotations
Chaque annotation s'applique à l'un des trois niveaux suivants :
Ingress — s'applique aux règles de routage définies sur la ressource Ingress.
Domain — s'applique aux noms d'hôte définis sur la ressource Ingress et prend également effet sur les mêmes noms d'hôte d'autres ressources Ingress.
Service — s'applique aux services backend référencés par la ressource Ingress et prend également effet sur les mêmes services référencés par d'autres ressources Ingress.
Préfixes d'annotation
Les annotations compatibles avec MSE acceptent le préfixe nginx ou mse . Par exemple, nginx.ingress.kubernetes.io/ssl-redirect et mse.ingress.kubernetes.io/ssl-redirect sont équivalents.
Les annotations exclusives à MSE utilisent uniquement le préfixe mse . Le remplacement de mse par nginx pour ces annotations n'a aucun effet.
Index de référence rapide
Le tableau suivant répertorie toutes les annotations prises en charge avec leur statut de compatibilité et leur catégorie. Utilisez ce tableau pour vérifier rapidement si une annotation spécifique est prise en charge avant de lire les détails complets ci-dessous.
| Annotation | Statut | Catégorie |
|---|---|---|
nginx.ingress.kubernetes.io/canary |
Compatible | Version Canary |
nginx.ingress.kubernetes.io/canary-by-header |
Compatible | Version Canary |
nginx.ingress.kubernetes.io/canary-by-header-value |
Compatible | Version Canary |
nginx.ingress.kubernetes.io/canary-by-header-pattern |
Compatible | Version Canary |
mse.ingress.kubernetes.io/canary-by-query |
Exclusif à MSE | Version Canary |
mse.ingress.kubernetes.io/canary-by-query-value |
Exclusif à MSE | Version Canary |
mse.ingress.kubernetes.io/canary-by-query-pattern |
Exclusif à MSE | Version Canary |
nginx.ingress.kubernetes.io/canary-by-cookie |
Compatible | Version Canary |
mse.ingress.kubernetes.io/canary-by-cookie-value |
Exclusif à MSE (V1.2.30+) | Version Canary |
nginx.ingress.kubernetes.io/canary-weight |
Compatible | Version Canary |
nginx.ingress.kubernetes.io/canary-weight-total |
Compatible | Version Canary |
mse.ingress.kubernetes.io/destination |
Exclusif à MSE | Routage multi-services |
mse.ingress.kubernetes.io/service-subset |
Exclusif à MSE (V1.2.25+) | Sous-ensemble de services |
mse.ingress.kubernetes.io/subset-labels |
Exclusif à MSE (V1.2.25+) | Sous-ensemble de services |
nginx.ingress.kubernetes.io/default-backend |
Compatible | Service de secours |
nginx.ingress.kubernetes.io/custom-http-errors |
Compatible | Service de secours |
nginx.ingress.kubernetes.io/use-regex |
Compatible | Correspondance de chemin par expression régulière |
nginx.ingress.kubernetes.io/rewrite-target |
Compatible | Réécriture de chemin |
nginx.ingress.kubernetes.io/upstream-vhost |
Compatible | Réécriture de chemin |
nginx.ingress.kubernetes.io/ssl-redirect |
Compatible | Redirection |
nginx.ingress.kubernetes.io/force-ssl-redirect |
Compatible | Redirection |
nginx.ingress.kubernetes.io/permanent-redirect |
Compatible | Redirection |
nginx.ingress.kubernetes.io/permanent-redirect-code |
Compatible | Redirection |
nginx.ingress.kubernetes.io/temporal-redirect |
Compatible | Redirection |
nginx.ingress.kubernetes.io/app-root |
Compatible | Redirection |
nginx.ingress.kubernetes.io/enable-cors |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-allow-origin |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-allow-methods |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-allow-headers |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-expose-headers |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-allow-credentials |
Compatible | CORS |
nginx.ingress.kubernetes.io/cors-max-age |
Compatible | CORS |
mse.ingress.kubernetes.io/request-header-control-add |
Exclusif à MSE | Contrôle des en-têtes |
mse.ingress.kubernetes.io/request-header-control-update |
Exclusif à MSE | Contrôle des en-têtes |
mse.ingress.kubernetes.io/request-header-control-remove |
Exclusif à MSE | Contrôle des en-têtes |
mse.ingress.kubernetes.io/response-header-control-add |
Exclusif à MSE | Contrôle des en-têtes |
mse.ingress.kubernetes.io/response-header-control-update |
Exclusif à MSE | Contrôle des en-têtes |
mse.ingress.kubernetes.io/response-header-control-remove |
Exclusif à MSE | Contrôle des en-têtes |
mse.ingress.kubernetes.io/timeout |
Exclusif à MSE | Délai d'expiration |
nginx.ingress.kubernetes.io/proxy-next-upstream-tries |
Compatible | Nouvelle tentative |
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout |
Compatible | Nouvelle tentative |
nginx.ingress.kubernetes.io/proxy-next-upstream |
Compatible | Nouvelle tentative |
mse.ingress.kubernetes.io/mirror-target-service |
Exclusif à MSE | Mise en miroir du trafic |
mse.ingress.kubernetes.io/mirror-percentage |
Exclusif à MSE (V1.2.32+) | Mise en miroir du trafic |
nginx.ingress.kubernetes.io/server-alias |
Partiellement compatible (V1.2.30+) | Alias de domaine |
mse.ingress.kubernetes.io/route-limit-rpm |
Exclusif à MSE | Limitation de débit (passerelle unique, à déprécier) |
mse.ingress.kubernetes.io/route-limit-rps |
Exclusif à MSE | Limitation de débit (passerelle unique, à déprécier) |
mse.ingress.kubernetes.io/route-limit-burst-multiplier |
Exclusif à MSE | Limitation de débit (passerelle unique, à déprécier) |
mse.ingress.kubernetes.io/rate-limit |
Exclusif à MSE (V1.2.25+) | Limitation de débit (globale) |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code |
Exclusif à MSE (V1.2.25+) | Limitation de débit (globale) |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type |
Exclusif à MSE (V1.2.25+) | Limitation de débit (globale) |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body |
Exclusif à MSE (V1.2.25+) | Limitation de débit (globale) |
mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url |
Exclusif à MSE (V1.2.25+) | Limitation de débit (globale) |
mse.ingress.kubernetes.io/concurrency-limit |
Exclusif à MSE (V1.2.25+) | Contrôle de la concurrence |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code |
Exclusif à MSE (V1.2.25+) | Contrôle de la concurrence |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type |
Exclusif à MSE (V1.2.25+) | Contrôle de la concurrence |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body |
Exclusif à MSE (V1.2.25+) | Contrôle de la concurrence |
mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url |
Exclusif à MSE (V1.2.25+) | Contrôle de la concurrence |
nginx.ingress.kubernetes.io/backend-protocol |
Partiellement compatible | Protocole backend |
nginx.ingress.kubernetes.io/load-balance |
Partiellement compatible | Équilibrage de charge |
nginx.ingress.kubernetes.io/upstream-hash-by |
Partiellement compatible | Équilibrage de charge |
mse.ingress.kubernetes.io/warmup |
Exclusif à MSE | Mise en chauffe du service |
nginx.ingress.kubernetes.io/affinity |
Compatible | Affinité par cookie |
nginx.ingress.kubernetes.io/affinity-mode |
Partiellement compatible | Affinité par cookie |
nginx.ingress.kubernetes.io/session-cookie-name |
Compatible | Affinité par cookie |
nginx.ingress.kubernetes.io/session-cookie-path |
Compatible | Affinité par cookie |
nginx.ingress.kubernetes.io/session-cookie-max-age |
Compatible | Affinité par cookie |
nginx.ingress.kubernetes.io/session-cookie-expires |
Compatible | Affinité par cookie |
nginx.ingress.kubernetes.io/whitelist-source-range |
Compatible | Contrôle d'accès IP |
nginx.ingress.kubernetes.io/denylist-source-range |
Compatible (V1.2.31+) | Contrôle d'accès IP |
mse.ingress.kubernetes.io/blacklist-source-range |
Exclusif à MSE | Contrôle d'accès IP |
mse.ingress.kubernetes.io/domain-whitelist-source-range |
Exclusif à MSE | Contrôle d'accès IP |
mse.ingress.kubernetes.io/domain-blacklist-source-range |
Exclusif à MSE | Contrôle d'accès IP |
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection |
Exclusif à MSE | Pool de connexions |
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint |
Exclusif à MSE | Pool de connexions |
mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection |
Exclusif à MSE | Pool de connexions |
mse.ingress.kubernetes.io/tls-min-protocol-version |
Exclusif à MSE | TLS (client vers passerelle) |
mse.ingress.kubernetes.io/tls-max-protocol-version |
Exclusif à MSE | TLS (client vers passerelle) |
nginx.ingress.kubernetes.io/ssl-cipher |
Compatible | TLS (client vers passerelle) |
mse.ingress.kubernetes.io/auth-tls-secret |
Partiellement compatible | TLS (client vers passerelle) |
nginx.ingress.kubernetes.io/proxy-ssl-secret |
Compatible | TLS (passerelle vers backend) |
nginx.ingress.kubernetes.io/proxy-ssl-name |
Compatible | TLS (passerelle vers backend) |
nginx.ingress.kubernetes.io/proxy-ssl-server-name |
Compatible | TLS (passerelle vers backend) |
nginx.ingress.kubernetes.io/auth-type |
Partiellement compatible | Authentification |
nginx.ingress.kubernetes.io/auth-secret |
Compatible | Authentification |
nginx.ingress.kubernetes.io/auth-secret-type |
Compatible | Authentification |
nginx.ingress.kubernetes.io/auth-realm |
Compatible | Authentification |
Annotations prises en charge
Gouvernance du trafic
Déploiement canari
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/canary |
Ingress | Compatible | Active le déploiement canari pour l'Ingress. |
nginx.ingress.kubernetes.io/canary-by-header |
Ingress | Compatible | Répartit le trafic selon la clé d'en-tête de la requête. |
nginx.ingress.kubernetes.io/canary-by-header-value |
Ingress | Compatible | Répartit le trafic selon la valeur de l'en-tête de la requête. Prend en charge la correspondance exacte. |
nginx.ingress.kubernetes.io/canary-by-header-pattern |
Ingress | Compatible | Répartit le trafic selon la valeur de l'en-tête de la requête. Prend en charge la correspondance par expression régulière. |
mse.ingress.kubernetes.io/canary-by-query |
Ingress | Exclusif à MSE | Répartit le trafic selon la clé du paramètre de requête URL. |
mse.ingress.kubernetes.io/canary-by-query-value |
Ingress | Exclusif à MSE | Répartit le trafic selon la valeur du paramètre de requête URL. Prend en charge la correspondance exacte. |
mse.ingress.kubernetes.io/canary-by-query-pattern |
Ingress | Exclusif à MSE | Répartit le trafic selon la valeur du paramètre de requête URL. Prend en charge la correspondance par expression régulière. |
nginx.ingress.kubernetes.io/canary-by-cookie |
Ingress | Compatible | Répartit le trafic selon la clé du cookie. |
mse.ingress.kubernetes.io/canary-by-cookie-value |
Ingress | Exclusif à MSE (nécessite la passerelle V1.2.30 ou ultérieure) | Répartit le trafic selon la valeur du cookie. Prend en charge la correspondance exacte. |
nginx.ingress.kubernetes.io/canary-weight |
Ingress | Compatible | Définit le poids du trafic pour le service canari. |
nginx.ingress.kubernetes.io/canary-weight-total |
Ingress | Compatible | Définit le poids total utilisé pour les calculs de répartition du trafic. |
Routage multi-services
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/destination |
Ingress | Exclusif à MSE | Répartit le trafic entre plusieurs services selon un poids. |
Syntaxe : {weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}
La configuration de cette annotation remplace les services de destination pour toutes les règles de routage de l'Ingress. Si la syntaxe est invalide, l'annotation est ignorée et les règles de routage d'origine restent en vigueur.
Exemple :
annotations:
# Route 60% of traffic to foo and 40% to bar
mse.ingress.kubernetes.io/destination: |
60% foo.default.svc.cluster.local:8080
40% bar.default.svc.cluster.local:9090Sous-ensemble de service
Utilisez des sous-ensembles de service lorsqu'un seul service Kubernetes gère plusieurs déploiements, par exemple une version stable et une version canari. Un sous-ensemble dirige les requêtes vers un groupe spécifique de pods.
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/service-subset |
Ingress | Exclusif à MSE (nécessite la passerelle V1.2.25 ou ultérieure) | Achemine les requêtes vers un sous-ensemble de pods du service cible. Lorsque mse.ingress.kubernetes.io/subset-labels n'est pas défini, le comportement de routage dépend de la valeur de cette annotation : définissez-la sur "" ou base pour cibler les pods avec opensergo.io/canary: "" ou les pods sans le préfixe de libellé opensergo.io/canary ; définissez-la sur toute autre valeur (par exemple, gray) pour cibler les pods avec le libellé opensergo.io/canary-gray: gray. Lorsque mse.ingress.kubernetes.io/subset-labels est défini, les requêtes sont transférées uniquement aux pods dont les libellés correspondent aux paires clé-valeur qui y sont définies. Si aucun pod ne correspond au libellé, les requêtes se rabattent sur tous les pods du service. |
mse.ingress.kubernetes.io/subset-labels |
Ingress | Exclusif à MSE (nécessite la passerelle V1.2.25 ou ultérieure) | Facultatif. Utilisez avec mse.ingress.kubernetes.io/service-subset pour spécifier les libellés qui définissent le sous-ensemble de pods. |
Service de secours
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/default-backend |
Ingress | Compatible | Spécifie un service de secours. Si aucun nœud n'est disponible pour le service défini dans une règle Ingress, les requêtes sont transférées vers ce service. |
nginx.ingress.kubernetes.io/custom-http-errors |
Ingress | Compatible | Fonctionne avec nginx.ingress.kubernetes.io/default-backend. Lorsqu'un backend renvoie l'un des codes d'état HTTP spécifiés, la requête est transférée au service de secours avec le chemin réécrit vers /. |
Correspondance de chemin par expression régulière
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/use-regex |
Ingress | Compatible | Active la correspondance par expression régulière pour le chemin défini dans la règle Ingress. Utilise la syntaxe RE2. |
Réécriture de chemin
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/rewrite-target |
Ingress | Compatible | Réécrit le chemin de la requête avant le transfert vers le backend. Prend en charge les groupes de capture. |
nginx.ingress.kubernetes.io/upstream-vhost |
Ingress | Compatible | Réécrit l'en-tête Host avec la valeur spécifiée lors du transfert des requêtes vers le backend. |
Redirection
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/ssl-redirect |
Ingress | Compatible | Redirige les requêtes HTTP vers HTTPS. |
nginx.ingress.kubernetes.io/force-ssl-redirect |
Ingress | Compatible | Force la redirection des requêtes HTTP vers HTTPS. |
nginx.ingress.kubernetes.io/permanent-redirect |
Ingress | Compatible | Redirige les requêtes vers l'URL spécifiée avec une redirection permanente. |
nginx.ingress.kubernetes.io/permanent-redirect-code |
Ingress | Compatible | Définit le code d'état HTTP pour les redirections permanentes. |
nginx.ingress.kubernetes.io/temporal-redirect |
Ingress | Compatible | Redirige les requêtes vers l'URL spécifiée avec une redirection temporaire. |
nginx.ingress.kubernetes.io/app-root |
Ingress | Compatible | Redirige les requêtes depuis / vers le chemin racine de l'application spécifié. |
Partage de ressources cross-origin (CORS)
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/enable-cors |
Ingress | Compatible | Active le partage de ressources cross-origin (CORS). |
nginx.ingress.kubernetes.io/cors-allow-origin |
Ingress | Compatible | Définit les origines autorisées pour les requêtes CORS. |
nginx.ingress.kubernetes.io/cors-allow-methods |
Ingress | Compatible | Définit les méthodes HTTP autorisées pour les requêtes CORS, telles que GET, POST et PUT. |
nginx.ingress.kubernetes.io/cors-allow-headers |
Ingress | Compatible | Définit les en-têtes de requête autorisés pour les requêtes CORS. |
nginx.ingress.kubernetes.io/cors-expose-headers |
Ingress | Compatible | Définit les en-têtes de réponse exposés aux navigateurs dans les réponses CORS. |
nginx.ingress.kubernetes.io/cors-allow-credentials |
Ingress | Compatible | Indique si les informations d'identification peuvent être incluses dans les requêtes CORS. |
nginx.ingress.kubernetes.io/cors-max-age |
Ingress | Compatible | Définit la durée de mise en cache des résultats des requêtes preflight. |
Contrôle des en-têtes
Les annotations de contrôle des en-têtes sur les routes de base et les routes canari sont indépendantes et validées séparément. Configurez des politiques d'en-tête différentes pour le trafic des routes de base et celui des routes canari selon vos besoins.
| Annotation | Portée | Statut de prise en charge | Description | |
|---|---|---|---|---|
mse.ingress.kubernetes.io/request-header-control-add |
Ingress | Exclusif à MSE | Ajoute un en-tête aux requêtes avant le transfert vers le backend. Si l'en-tête existe déjà, la nouvelle valeur est ajoutée à l'originale. Pour un seul en-tête, utilisez une paire clé-valeur. Pour plusieurs en-têtes, utilisez un bloc littéral YAML ( |
`) avec une paire clé-valeur par ligne. |
mse.ingress.kubernetes.io/request-header-control-update |
Ingress | Exclusif à MSE | Modifie un en-tête dans les requêtes avant le transfert vers le backend. Si l'en-tête existe, la nouvelle valeur écrase l'originale. Même syntaxe que request-header-control-add. |
|
mse.ingress.kubernetes.io/request-header-control-remove |
Ingress | Exclusif à MSE | Supprime des en-têtes des requêtes avant le transfert vers le backend. Pour un seul en-tête, spécifiez la clé. Pour plusieurs en-têtes, séparez les clés par des virgules. | |
mse.ingress.kubernetes.io/response-header-control-add |
Ingress | Exclusif à MSE | Ajoute un en-tête aux réponses avant le transfert vers le client. Si l'en-tête existe déjà, la nouvelle valeur est ajoutée à l'originale. Même syntaxe que request-header-control-add. |
|
mse.ingress.kubernetes.io/response-header-control-update |
Ingress | Exclusif à MSE | Modifie un en-tête dans les réponses avant le transfert vers le client. Si l'en-tête existe, la nouvelle valeur écrase l'originale. Même syntaxe que request-header-control-add. |
|
mse.ingress.kubernetes.io/response-header-control-remove |
Ingress | Exclusif à MSE | Supprime des en-têtes des réponses avant le transfert vers le client. Pour un seul en-tête, spécifiez la clé. Pour plusieurs en-têtes, séparez les clés par des virgules. |
Délai d'expiration
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/timeout |
Ingress | Exclusif à MSE | Définit le délai d'expiration de la requête en secondes. Aucun délai d'expiration n'est appliqué par défaut. S'applique au niveau de la couche application, et non au niveau de la couche de transport TCP. |
Nouvelle tentative
| Annotation | Portée | Statut de prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/proxy-next-upstream-tries |
Ingress | Compatible | Définit le nombre maximal de tentatives de nouvelle tentative. Par défaut : 3. |
nginx.ingress.kubernetes.io/proxy-next-upstream-timeout |
Ingress | Compatible | Définit le délai d'expiration pour les tentatives de nouvelle tentative en secondes. Aucun délai d'expiration n'est appliqué par défaut. |
nginx.ingress.kubernetes.io/proxy-next-upstream |
Ingress | Compatible | Définit les conditions qui déclenchent une nouvelle tentative. Consultez le mécanisme de nouvelle tentative NGINX pour connaître les valeurs prises en charge. |
Mise en miroir du trafic
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/mirror-target-service |
Ingress | Exclusif à MSE | Transmet une copie du trafic entrant au service spécifié. Format : namespace/name:port. Le namespace correspond par défaut à celui de la passerelle d'entrée. Le port utilise par défaut le premier port du service. |
mse.ingress.kubernetes.io/mirror-percentage |
Ingress | Exclusif à MSE (nécessite la version V1.2.32 ou ultérieure de la passerelle) | Définit le pourcentage de trafic à mettre en miroir. Valeurs valides : 0–100. Par défaut : 100. |
Alias de domaine
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/server-alias |
Domaine | Partiellement compatible — domaines exacts et domaines génériques uniquement (nécessite la version V1.2.30 ou ultérieure de la passerelle) | Définit un alias de domaine pour le nom d'hôte spécifié dans la spécification Ingress. L'alias hérite de la configuration TLS, du routage et de la gouvernance du trafic du domaine source. |
Limitation de débit (passerelle unique, destiné à être obsolète)
Lorsque la limitation de débit est déclenchée, le corps de la réponse est local_rate_limited. Le code d'état de la réponse dépend de la version de la passerelle : les versions antérieures à V1.2.23 renvoient 503 ; les versions V1.2.23 et ultérieures renvoient 429.
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/route-limit-rpm |
Ingress | Exclusif à MSE | Définit le nombre maximal de requêtes par minute (RPM) sur une route. La limite de rafale équivaut à cette valeur multipliée par mse.ingress.kubernetes.io/route-limit-burst-multiplier. |
mse.ingress.kubernetes.io/route-limit-rps |
Ingress | Exclusif à MSE | Définit le nombre maximal de requêtes par seconde (RPS) sur une route. La limite de rafale équivaut à cette valeur multipliée par mse.ingress.kubernetes.io/route-limit-burst-multiplier. |
mse.ingress.kubernetes.io/route-limit-burst-multiplier |
Ingress | Exclusif à MSE | Définit le multiplicateur de la limite de rafale. Par défaut : 5. |
Limitation de débit (globale, recommandée)
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/rate-limit |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Définit le nombre maximal de RPS pour la limitation de débit globale sur une route. |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Définit le code de réponse HTTP renvoyé lorsque la limitation de débit est activée. Par défaut : 429. Mutuellement exclusif avec mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url. |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Définit le format du corps de la réponse en cas de limitation de débit. Par défaut : text. La valeur text renvoie Content-Type: text/plain; charset=UTF-8. La valeur JSON renvoie Content-Type: application/json; charset=UTF-8. |
mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-body |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Définit le contenu du corps de la réponse en cas de limitation de débit. Par défaut : sentinel rate limited. |
mse.ingress.kubernetes.io/rate-limit-fallback-redirect-url |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Redirige les requêtes vers l'URL spécifiée lorsque la limitation de débit est activée. Mutuellement exclusif avec mse.ingress.kubernetes.io/rate-limit-fallback-custom-response-code. |
Contrôle de concurrence (global)
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/concurrency-limit |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Définit le nombre maximal de requêtes simultanées sur une route. |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Définit le code de réponse HTTP lorsque le contrôle de concurrence est activé. Par défaut : 429. Mutuellement exclusif avec mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url. |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Définit le format du corps de la réponse en cas de limitation de concurrence. Par défaut : text. La valeur text renvoie Content-Type: text/plain; charset=UTF-8. La valeur JSON renvoie Content-Type: application/json; charset=UTF-8. |
mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Définit le contenu du corps de la réponse en cas de limitation de concurrence. Par défaut : sentinel rate limited. |
mse.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url |
Ingress | Exclusif à MSE (nécessite la version V1.2.25 ou ultérieure de la passerelle) | Redirige les requêtes vers l'URL spécifiée lorsque le contrôle de concurrence est activé. Mutuellement exclusif avec mse.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code. |
Protocole backend
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/backend-protocol |
Service | Partiellement compatible — AJP et FCGI ne sont pas pris en charge | Définit le protocole utilisé pour communiquer avec les services backend. Par défaut : HTTP. Valeurs prises en charge : HTTP, HTTP2, HTTPS, gRPC, gRPCS. |
Équilibrage de charge
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/load-balance |
Service | Partiellement compatible — l'algorithme EWMA (Exponentially Weighted Moving Average) n'est pas pris en charge et revient au round-robin | Définit l'algorithme d'équilibrage de charge. Par défaut : round_robin. Valeurs prises en charge : round_robin, least_conn, random. |
nginx.ingress.kubernetes.io/upstream-hash-by |
Service | Partiellement compatible — la combinaison de variables NGINX avec des constantes n'est pas prise en charge | Active le hachage cohérent. Types de clés de hachage pris en charge : $request_uri (chemin de la requête, y compris les paramètres de chemin), $host (nom d'hôte de la requête), $remote_addr (adresse IP du client), $http_<headerName> (valeur de l'en-tête de la requête), $arg_<varName> (valeur du paramètre de requête URL). |
Préchauffage du service (démarrage progressif)
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/warmup |
Service | Exclusif à MSE | Définit la durée de préchauffage en secondes. Désactivé par défaut. Pris en charge uniquement avec les algorithmes d'équilibrage de charge round_robin et least_conn. |
Affinité basée sur les cookies
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/affinity |
Service | Compatible | Définit le type d'affinité. La seule valeur valide est cookie. |
nginx.ingress.kubernetes.io/affinity-mode |
Service | Partiellement compatible — le mode persistent n'est pas pris en charge |
Définit le mode d'affinité. La seule valeur valide est balanced. |
nginx.ingress.kubernetes.io/session-cookie-name |
Service | Compatible | Définit le nom du cookie utilisé comme clé de hachage pour l'affinité de session. |
nginx.ingress.kubernetes.io/session-cookie-path |
Service | Compatible | Définit l'attribut path du cookie de session généré. Par défaut : /. |
nginx.ingress.kubernetes.io/session-cookie-max-age |
Service | Compatible | Définit la valeur Max-Age du cookie de session généré, en secondes. Par défaut, l'expiration se fait au niveau de la session. |
nginx.ingress.kubernetes.io/session-cookie-expires |
Service | Compatible | Définit l'attribut Expires du cookie de session généré, en secondes. Par défaut, l'expiration se fait au niveau de la session. |
Contrôle d'accès basé sur l'adresse IP
Les listes d'autorisation au niveau de la route sont prioritaires sur celles au niveau du domaine. Les listes de blocage au niveau de la route sont prioritaires sur celles au niveau du domaine.
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/whitelist-source-range |
Ingress | Compatible | Définit une liste d'autorisation d'adresses IP pour la route. Accepte les adresses IP et les blocs CIDR, séparés par des virgules. |
nginx.ingress.kubernetes.io/denylist-source-range |
Ingress | Compatible (nécessite la version V1.2.31 ou ultérieure de la passerelle) | Définit une liste de blocage d'adresses IP pour la route. Accepte les adresses IP et les blocs CIDR, séparés par des virgules. Prioritaire sur mse.ingress.kubernetes.io/blacklist-source-range. |
mse.ingress.kubernetes.io/blacklist-source-range |
Ingress | Exclusif à MSE | Définit une liste de blocage d'adresses IP pour la route. Accepte les adresses IP et les blocs CIDR, séparés par des virgules. |
mse.ingress.kubernetes.io/domain-whitelist-source-range |
Ingress | Exclusif à MSE | Définit une liste d'autorisation d'adresses IP au niveau du domaine. Accepte les adresses IP et les blocs CIDR, séparés par des virgules. |
mse.ingress.kubernetes.io/domain-blacklist-source-range |
Ingress | Exclusif à MSE | Définit une liste de blocage d'adresses IP au niveau du domaine. Accepte les adresses IP et les blocs CIDR, séparés par des virgules. |
Pool de connexions (passerelle vers backend)
| Annotation | Portée | État de la prise en charge | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection |
Service | Exclusif à MSE | Définit le nombre maximal de connexions TCP entre la passerelle et le service backend. |
mse.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint |
Service | Exclusif à MSE | Définit le nombre maximal de connexions TCP entre la passerelle et un seul pod backend. |
mse.ingress.kubernetes.io/connection-policy-http-max-request-per-connection |
Service | Exclusif à MSE | Définit le nombre maximal de requêtes HTTP par connexion entre la passerelle et le service backend. |
Protection de la sécurité
TLS entre les clients et la passerelle
| Annotation | Portée | État du support | Description |
|---|---|---|---|
mse.ingress.kubernetes.io/tls-min-protocol-version |
Domaine | Exclusif à MSE | Définit la version minimale de TLS. Par défaut : TLSv1.0. Valeurs valides : TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. |
mse.ingress.kubernetes.io/tls-max-protocol-version |
Domaine | Exclusif à MSE | Définit la version maximale de TLS. Par défaut : TLSv1.3. Valeurs valides : TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3. |
nginx.ingress.kubernetes.io/ssl-cipher |
Domaine | Compatible | Définit les suites de chiffrement TLS, séparées par des virgules. S'applique uniquement aux négociations TLS 1.0–1.2. Suites de chiffrement par défaut : ECDHE-ECDSA-AES128-GCM-SHA256, ECDHE-RSA-AES128-GCM-SHA256, ECDHE-ECDSA-AES128-SHA, ECDHE-RSA-AES128-SHA, AES128-GCM-SHA256, AES128-SHA, ECDHE-ECDSA-AES256-GCM-SHA384, ECDHE-RSA-AES256-GCM-SHA384, ECDHE-ECDSA-AES256-SHA, ECDHE-RSA-AES256-SHA, AES256-GCM-SHA384, AES256-SHA. |
mse.ingress.kubernetes.io/auth-tls-secret |
Domaine | Partiellement compatible — le nom du secret doit respecter le format <domain-certificate-secret-name>-cacert |
Spécifie le certificat CA que la passerelle utilise pour vérifier les certificats clients lors des négociations TLS mutuelles (mTLS). |
TLS entre la passerelle et les services backend
| Annotation | Portée | État du support | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/proxy-ssl-secret |
Service | Compatible | Spécifie le certificat client que la passerelle présente aux services backend lors des négociations TLS. |
nginx.ingress.kubernetes.io/proxy-ssl-name |
Service | Compatible | Définit la valeur SNI (Server Name Indication) utilisée lors de la négociation TLS avec le backend. |
nginx.ingress.kubernetes.io/proxy-ssl-server-name |
Service | Compatible | Active ou désactive le SNI lors de la négociation TLS avec le backend. |
Authentification
Authentification de base
| Annotation | Portée | État du support | Description |
|---|---|---|---|
nginx.ingress.kubernetes.io/auth-type |
Ingress | Partiellement compatible — seule l'authentification basic est prise en charge |
Définit le type d'authentification. |
nginx.ingress.kubernetes.io/auth-secret |
Ingress | Compatible | Spécifie le secret contenant les identifiants pour la route. Format : <namespace>/<name>. |
nginx.ingress.kubernetes.io/auth-secret-type |
Ingress | Compatible | Définit le format des données du secret. auth-file : la clé auth contient des paires username:password séparées par des sauts de ligne. auth-map : chaque clé correspond à un nom d'utilisateur et sa valeur au mot de passe. |
nginx.ingress.kubernetes.io/auth-realm |
Ingress | Compatible | Définit le domaine d'authentification. Les identifiants sont partagés au sein d'un même domaine. |
Pour obtenir la liste complète des annotations NGINX Ingress, consultez la page Annotations.