Tous les produits
Search

Ce produit

    API Gateway:Annotations prises en charge par APIG Ingress

    Centre de documentation

    API Gateway:Annotations prises en charge par APIG Ingress

    Dernière mise à jour :Oct 12, 2026

    APIG Ingress prend en charge 51 annotations NGINX Ingress pour une migration transparente et 40 annotations étendues pour la gouvernance du trafic et la sécurité.

    Résumé de la prise en charge des annotations

    Catégorie Nombre Description
    Annotations compatibles avec NGINX Ingress 51 Couvrent 90 % des cas d'utilisation
    Annotations sans effet fonctionnel 15 Aucune configuration requise
    Annotations à prendre en charge 48 Prévu ; utilisé dans des scénarios limités
    Annotations non prises en charge 5 Spécifiques aux extraits de code internes de NGINX Ingress
    Annotations étendues APIG 40 Contrôles supplémentaires de gouvernance du trafic et de sécurité au-delà de NGINX Ingress

    Référence rapide

    Cliquez sur une annotation pour consulter sa description complète.

    Annotation Portée Statut Valeur par défaut Catégorie
    nginx.ingress.kubernetes.io/canary Ingress Compatible — Déploiement Canary
    nginx.ingress.kubernetes.io/canary-by-header Ingress Compatible — Déploiement Canary
    nginx.ingress.kubernetes.io/canary-by-header-value Ingress Compatible — Déploiement Canary
    nginx.ingress.kubernetes.io/canary-by-header-pattern Ingress Compatible — Déploiement Canary
    higress.ingress.kubernetes.io/canary-by-query Ingress Extension Higress — Déploiement Canary
    higress.ingress.kubernetes.io/canary-by-query-value Ingress Extension Higress — Déploiement Canary
    higress.ingress.kubernetes.io/canary-by-query-pattern Ingress Extension Higress — Déploiement Canary
    nginx.ingress.kubernetes.io/canary-by-cookie Ingress Compatible — Déploiement Canary
    higress.ingress.kubernetes.io/canary-by-cookie-value Ingress Extension Higress (V1.2.30+) — Déploiement Canary
    nginx.ingress.kubernetes.io/canary-weight Ingress Compatible — Déploiement Canary
    nginx.ingress.kubernetes.io/canary-weight-total Ingress Compatible — Déploiement Canary
    higress.ingress.kubernetes.io/destination Ingress Extension Higress — Routage multi-services
    higress.ingress.kubernetes.io/service-subset Ingress Extension Higress (V1.2.25+) — Sous-ensembles de services
    higress.ingress.kubernetes.io/subset-labels Ingress Extension Higress (V1.2.25+) — Sous-ensembles de services
    nginx.ingress.kubernetes.io/default-backend Ingress Compatible — Secours
    nginx.ingress.kubernetes.io/custom-http-errors Ingress Compatible — Secours
    nginx.ingress.kubernetes.io/use-regex Ingress Compatible — Correspondance regex
    nginx.ingress.kubernetes.io/rewrite-target Ingress Compatible — Réécriture
    nginx.ingress.kubernetes.io/upstream-vhost Ingress Compatible — Réécriture
    nginx.ingress.kubernetes.io/ssl-redirect Ingress Compatible — Redirection
    nginx.ingress.kubernetes.io/force-ssl-redirect Ingress Compatible — Redirection
    nginx.ingress.kubernetes.io/permanent-redirect Ingress Compatible — Redirection
    nginx.ingress.kubernetes.io/permanent-redirect-code Ingress Compatible — Redirection
    nginx.ingress.kubernetes.io/temporal-redirect Ingress Compatible — Redirection
    nginx.ingress.kubernetes.io/app-root Ingress Compatible — Redirection
    nginx.ingress.kubernetes.io/enable-cors Ingress Compatible — CORS
    nginx.ingress.kubernetes.io/cors-allow-origin Ingress Compatible — CORS
    nginx.ingress.kubernetes.io/cors-allow-methods Ingress Compatible — CORS
    nginx.ingress.kubernetes.io/cors-allow-headers Ingress Compatible — CORS
    nginx.ingress.kubernetes.io/cors-expose-headers Ingress Compatible — CORS
    nginx.ingress.kubernetes.io/cors-allow-credentials Ingress Compatible — CORS
    nginx.ingress.kubernetes.io/cors-max-age Ingress Compatible — CORS
    higress.ingress.kubernetes.io/request-header-control-add Ingress Extension Higress — Contrôle des en-têtes
    higress.ingress.kubernetes.io/request-header-control-update Ingress Extension Higress — Contrôle des en-têtes
    higress.ingress.kubernetes.io/request-header-control-remove Ingress Extension Higress — Contrôle des en-têtes
    higress.ingress.kubernetes.io/response-header-control-add Ingress Extension Higress — Contrôle des en-têtes
    higress.ingress.kubernetes.io/response-header-control-update Ingress Extension Higress — Contrôle des en-têtes
    higress.ingress.kubernetes.io/response-header-control-remove Ingress Extension Higress — Contrôle des en-têtes
    higress.ingress.kubernetes.io/timeout Ingress Extension Higress Aucune Délai d'expiration
    nginx.ingress.kubernetes.io/proxy-next-upstream-tries Ingress Compatible 3 Nouvelle tentative
    nginx.ingress.kubernetes.io/proxy-next-upstream-timeout Ingress Compatible Aucune Nouvelle tentative
    nginx.ingress.kubernetes.io/proxy-next-upstream Ingress Compatible — Nouvelle tentative
    higress.ingress.kubernetes.io/mirror-target-service Ingress Extension Higress — Mise en miroir du trafic
    higress.ingress.kubernetes.io/mirror-percentage Ingress Extension Higress (V1.2.32+) 100 Mise en miroir du trafic
    nginx.ingress.kubernetes.io/server-alias Nom de domaine Partiellement compatible (V1.2.30+) — Alias de domaine
    higress.ingress.kubernetes.io/route-limit-rpm Ingress Extension Higress — Limitation de débit (obsolète)
    higress.ingress.kubernetes.io/route-limit-rps Ingress Extension Higress — Limitation de débit (obsolète)
    higress.ingress.kubernetes.io/route-limit-burst-multiplier Ingress Extension Higress 5 Limitation de débit (obsolète)
    higress.ingress.kubernetes.io/rate-limit Ingress Extension Higress (V1.2.25+) — Limitation globale du débit
    higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code Ingress Extension Higress (V1.2.25+) 429 Limitation globale du débit
    higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type Ingress Extension Higress (V1.2.25+) text Limitation globale du débit
    higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body Ingress Extension Higress (V1.2.25+) sentinel rate limited Limitation globale du débit
    higress.ingress.kubernetes.io/rate-limit-fallback-redirect-url Ingress Extension Higress (V1.2.25+) — Limitation globale du débit
    higress.ingress.kubernetes.io/concurrency-limit Ingress Extension Higress (V1.2.25+) — Concurrence globale
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code Ingress Extension Higress (V1.2.25+) 429 Concurrence globale
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type Ingress Extension Higress (V1.2.25+) text Concurrence globale
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body Ingress Extension Higress (V1.2.25+) sentinel rate limited Concurrence globale
    higress.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url Ingress Extension Higress (V1.2.25+) — Concurrence globale
    nginx.ingress.kubernetes.io/backend-protocol Service Partiellement compatible HTTP Protocole backend
    nginx.ingress.kubernetes.io/load-balance Service Partiellement compatible round_robin Équilibrage de charge
    nginx.ingress.kubernetes.io/upstream-hash-by Service Partiellement compatible — Équilibrage de charge
    higress.ingress.kubernetes.io/warmup Service Extension Higress Désactivé Préchauffage
    nginx.ingress.kubernetes.io/affinity Service Compatible cookie Affinité de cookie
    nginx.ingress.kubernetes.io/affinity-mode Service Partiellement compatible balanced Affinité de cookie
    nginx.ingress.kubernetes.io/session-cookie-name Service Compatible — Affinité de cookie
    nginx.ingress.kubernetes.io/session-cookie-path Service Compatible / Affinité de cookie
    nginx.ingress.kubernetes.io/session-cookie-max-age Service Compatible Niveau session Affinité de cookie
    nginx.ingress.kubernetes.io/session-cookie-expires Service Compatible Niveau session Affinité de cookie
    nginx.ingress.kubernetes.io/whitelist-source-range Ingress Compatible — Contrôle d'accès IP
    nginx.ingress.kubernetes.io/denylist-source-range Ingress Compatible (V1.2.31+) — Contrôle d'accès IP
    higress.ingress.kubernetes.io/blacklist-source-range Ingress Extension Higress — Contrôle d'accès IP
    higress.ingress.kubernetes.io/domain-whitelist-source-range Ingress Extension Higress — Contrôle d'accès IP
    higress.ingress.kubernetes.io/domain-blacklist-source-range Ingress Extension Higress — Contrôle d'accès IP
    higress.ingress.kubernetes.io/connection-policy-tcp-max-connection Service Extension Higress — Pool de connexions
    higress.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint Service Extension Higress — Pool de connexions
    higress.ingress.kubernetes.io/connection-policy-http-max-request-per-connection Service Extension Higress — Pool de connexions
    higress.ingress.kubernetes.io/tls-min-protocol-version Nom de domaine Extension Higress TLSv1.0 TLS client-vers-passerelle
    higress.ingress.kubernetes.io/tls-max-protocol-version Nom de domaine Extension Higress TLSv1.3 TLS client-vers-passerelle
    nginx.ingress.kubernetes.io/ssl-cipher Nom de domaine Compatible Voir la description TLS client-vers-passerelle
    higress.ingress.kubernetes.io/auth-tls-secret Nom de domaine Partiellement compatible — TLS client-vers-passerelle
    nginx.ingress.kubernetes.io/proxy-ssl-secret Service Compatible — TLS passerelle-vers-backend
    nginx.ingress.kubernetes.io/proxy-ssl-name Service Compatible — TLS passerelle-vers-backend
    nginx.ingress.kubernetes.io/proxy-ssl-server-name Service Compatible — TLS passerelle-vers-backend
    nginx.ingress.kubernetes.io/auth-type Ingress Partiellement compatible — Authentification de base
    nginx.ingress.kubernetes.io/auth-secret Ingress Compatible — Authentification de base
    nginx.ingress.kubernetes.io/auth-secret-type Ingress Compatible — Authentification de base
    nginx.ingress.kubernetes.io/auth-realm Ingress Compatible — Authentification de base

    Portée

    Chaque annotation s'applique à une portée spécifique :

    • Ingress — S'applique aux règles de routage de la ressource Ingress sur laquelle l'annotation est définie.

    • Nom de domaine — S'applique à toutes les ressources Ingress qui partagent les mêmes hôtes.

    • Service — S'applique à toutes les ressources Ingress qui partagent les mêmes services.

    Préfixes d'annotation

    Pour les annotations partagées entre NGINX Ingress et APIG Ingress, ces préfixes sont interchangeables :

    • nginx.ingress.kubernetes.io/xxx

    • higress.ingress.kubernetes.io/xxx

    Les annotations marquées Higress extension nécessitent le préfixe higress et ne peuvent pas utiliser le préfixe nginx.

    Notes de compatibilité

    Principales différences par rapport à NGINX Ingress :

    1. Variables NGINX : Les variables NGINX utilisées dans les annotations et les extraits de code ne sont pas compatibles avec APIG Ingress. Vérifiez les annotations dépendantes des variables avant la migration.

    2. Taille du corps de la requête : NGINX Ingress utilise nginx.ingress.kubernetes.io/proxy-body-size pour imposer une limite stricte et renvoie une erreur en cas de dépassement. APIG Ingress utilise un streaming par blocs sans limite prédéfinie de taille de corps. Pour les transferts de fichiers volumineux, ajustez DownstreamConnectionBufferLimits dans la configuration de l'instance de passerelle.

    Annotations de gouvernance du trafic

    Déploiement canari

    Annotation Portée Statut Description
    nginx.ingress.kubernetes.io/canary Ingress Compatible Active ou désactive le déploiement canari pour une route.
    nginx.ingress.kubernetes.io/canary-by-header Ingress Compatible Clé d'en-tête de requête utilisée pour la répartition du trafic.
    nginx.ingress.kubernetes.io/canary-by-header-value Ingress Compatible Valeur d'en-tête de requête pour la répartition du trafic. Prend en charge la correspondance exacte.
    nginx.ingress.kubernetes.io/canary-by-header-pattern Ingress Compatible Valeur d'en-tête de requête pour la répartition du trafic. Prend en charge les expressions régulières.
    higress.ingress.kubernetes.io/canary-by-query Ingress Extension Higress Clé de paramètre de requête URL utilisée pour la répartition du trafic.
    higress.ingress.kubernetes.io/canary-by-query-value Ingress Extension Higress Valeur de paramètre de requête URL pour la répartition du trafic. Prend en charge la correspondance exacte.
    higress.ingress.kubernetes.io/canary-by-query-pattern Ingress Extension Higress Valeur de paramètre de requête URL pour la répartition du trafic. Prend en charge les expressions régulières.
    nginx.ingress.kubernetes.io/canary-by-cookie Ingress Compatible Clé de cookie utilisée pour la répartition du trafic.
    higress.ingress.kubernetes.io/canary-by-cookie-value Ingress Extension Higress (V1.2.30+) Valeur de cookie pour la répartition du trafic. Prend en charge la correspondance exacte.
    nginx.ingress.kubernetes.io/canary-weight Ingress Compatible Pondération du service utilisée pour la répartition du trafic.
    nginx.ingress.kubernetes.io/canary-weight-total Ingress Compatible Pondération totale pour la répartition du trafic.

    Routage multi-services

    Annotation Portée Statut Description
    higress.ingress.kubernetes.io/destination Ingress Extension Higress Répartit le trafic entre plusieurs services selon une pondération. Syntaxe : {weight}% {serviceName}.{serviceNamespace}.svc.cluster.local:{port}
    La définition de cette annotation modifie la destination de toutes les règles de routage sur l'Ingress. Si la syntaxe est incorrecte, l'annotation est ignorée et le routage reste inchangé.

    Exemple :

    annotations:
  # 60% of traffic goes to foo, 40% to bar
  higress.ingress.kubernetes.io/destination: |
    60% foo.default.svc.cluster.local:8080
    40% bar.default.svc.cluster.local:9090

    Sous-ensembles de services

    Acheminez les requêtes vers un sous-ensemble spécifique de pods lorsqu'un service gère plusieurs déploiements.

    Annotation Portée Statut Description
    higress.ingress.kubernetes.io/service-subset Ingress Extension Higress (V1.2.25+) Identifie le sous-ensemble de pods vers lequel acheminer les requêtes.
    higress.ingress.kubernetes.io/subset-labels Ingress Extension Higress (V1.2.25+) (Facultatif) Sélecteur d'étiquettes utilisé avec service-subset pour classer les pods en sous-ensembles.

    Comportement de routage pour service-subset :

    • Si subset-labels n'est pas défini :

      • Défini sur "" ou base — achemine vers les pods étiquetés opensergo.io/canary: "" ou les pods sans clé d'étiquette opensergo.io/canary.

      • Défini sur toute autre valeur (par exemple, gray) — achemine vers les pods étiquetés opensergo.io/canary-gray: gray.

    • Si subset-labels est défini — achemine uniquement vers les pods dont les étiquettes correspondent aux paires clé-valeur définies dans subset-labels.

    Si aucun pod ne correspond à l'étiquette spécifiée, les requêtes sont automatiquement transférées vers tous les pods du service.

    Exemple :

    annotations:
  # Route to the "gray" subset of Pods
  higress.ingress.kubernetes.io/service-subset: "gray"

    Secours (Fallback)

    Annotation Portée Statut Description
    nginx.ingress.kubernetes.io/default-backend Ingress Compatible Service de secours lorsque aucun nœud principal sain n'est disponible.
    nginx.ingress.kubernetes.io/custom-http-errors Ingress Compatible Codes d'état HTTP qui déclenchent le transfert vers le service de secours.
    Important

    Lorsqu'une requête est transférée vers le service de secours, le chemin de la requête est réécrit en /. Ce comportement correspond à celui de NGINX Ingress.

    Correspondance par expression régulière

    Annotation Portée Statut Description
    nginx.ingress.kubernetes.io/use-regex Ingress Compatible Active la correspondance de chemin par expression régulière sur l'Ingress en utilisant la syntaxe RE2.

    Réécriture

    Annotation Portée Statut Description
    nginx.ingress.kubernetes.io/rewrite-target Ingress Compatible Chemin de destination pour la réécriture d'URL. Les groupes de capture sont pris en charge.
    nginx.ingress.kubernetes.io/upstream-vhost Ingress Compatible Réécrit l'en-tête Host dans les requêtes transférées vers un service backend.

    Redirection

    L'utilisation des variables NGINX pour la redirection n'est pas documentée dans NGINX Ingress et peut entraîner des problèmes de compatibilité. Évitez d'utiliser les variables NGINX dans les annotations de redirection.
    Annotation Portée Statut Description
    nginx.ingress.kubernetes.io/ssl-redirect Ingress Compatible Redirige HTTP vers HTTPS.
    nginx.ingress.kubernetes.io/force-ssl-redirect Ingress Compatible Force la redirection de HTTP vers HTTPS.
    nginx.ingress.kubernetes.io/permanent-redirect Ingress Compatible Envoie une redirection permanente vers l'URL spécifiée.
    nginx.ingress.kubernetes.io/permanent-redirect-code Ingress Compatible Code d'état HTTP utilisé pour les redirections permanentes.
    nginx.ingress.kubernetes.io/temporal-redirect Ingress Compatible Envoie une redirection temporaire vers l'URL spécifiée.
    nginx.ingress.kubernetes.io/app-root Ingress Compatible Redirige les requêtes depuis / vers le chemin racine de l'application spécifié.

    CORS

    Annotation Portée Statut 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 Origines autorisées pour les requêtes CORS.
    nginx.ingress.kubernetes.io/cors-allow-methods Ingress Compatible Méthodes HTTP autorisées pour CORS. Inclut GET, POST et PUT.
    nginx.ingress.kubernetes.io/cors-allow-headers Ingress Compatible En-têtes de requête autorisés pour CORS.
    nginx.ingress.kubernetes.io/cors-expose-headers Ingress Compatible En-têtes de réponse exposés aux navigateurs.
    nginx.ingress.kubernetes.io/cors-allow-credentials Ingress Compatible Indique si les identifiants peuvent être inclus dans les requêtes CORS.
    nginx.ingress.kubernetes.io/cors-max-age Ingress Compatible Durée de mise en cache (en secondes) des résultats des requêtes préliminaires.

    Contrôle des en-têtes

    Les annotations de contrôle des en-têtes sur les routes de base et canari sont indépendantes et validées séparément. Utilisez-les pour configurer des politiques d'en-têtes distinctes pour chaque type de trafic.
    Annotation Portée Statut Description
    higress.ingress.kubernetes.io/request-header-control-add Ingress Extension Higress Ajoute un en-tête aux requêtes transférées. Si l'en-tête existe, la valeur est ajoutée.
    higress.ingress.kubernetes.io/request-header-control-update Ingress Extension Higress Écrase un en-tête dans les requêtes transférées.
    higress.ingress.kubernetes.io/request-header-control-remove Ingress Extension Higress Supprime un en-tête des requêtes transférées.
    higress.ingress.kubernetes.io/response-header-control-add Ingress Extension Higress Ajoute un en-tête aux réponses client. Si l'en-tête existe, la valeur est ajoutée.
    higress.ingress.kubernetes.io/response-header-control-update Ingress Extension Higress Écrase un en-tête dans les réponses client.
    higress.ingress.kubernetes.io/response-header-control-remove Ingress Extension Higress Supprime un en-tête des réponses client.

    Syntaxe :

    • En-tête unique (ajout/mise à jour) : Utilisez une paire clé-valeur. Exemple : X-Custom-Header: value

    • Plusieurs en-têtes (ajout/mise à jour) : Utilisez un scalaire de bloc YAML (|). Chaque paire clé-valeur sur une ligne distincte.

    • En-tête unique (suppression) : Utilisez uniquement la clé de l'en-tête.

    • Plusieurs en-têtes (suppression) : Clés d'en-tête séparées par des virgules.

    Exemple — ajouter un en-tête de requête :

    annotations:
  higress.ingress.kubernetes.io/request-header-control-add: "X-Request-Id: abc123"

    Exemple — ajouter plusieurs en-têtes de réponse :

    annotations:
  higress.ingress.kubernetes.io/response-header-control-add: |
    X-Custom-Header: value1
    X-Another-Header: value2

    Exemple — supprimer plusieurs en-têtes de requête :

    annotations:
  higress.ingress.kubernetes.io/request-header-control-remove: "X-Forwarded-For,X-Real-IP"

    Délai d'expiration (Timeout)

    Annotation Portée Statut Par défaut Description
    higress.ingress.kubernetes.io/timeout Ingress Extension Higress Aucun Délai d'expiration de la requête en secondes.
    Ce délai d'expiration s'applique au niveau de la couche application (HTTP), et non au niveau de la couche de transport TCP.

    Nouvelle tentative (Retry)

    Annotation Portée Statut Par défaut Description
    nginx.ingress.kubernetes.io/proxy-next-upstream-tries Ingress Compatible 3 Nombre maximal de tentatives de nouvelle tentative.
    nginx.ingress.kubernetes.io/proxy-next-upstream-timeout Ingress Compatible Aucun Délai d'expiration pour les tentatives de nouvelle tentative, en secondes.
    nginx.ingress.kubernetes.io/proxy-next-upstream Ingress Compatible — Conditions de nouvelle tentative. Consultez le mécanisme de nouvelle tentative NGINX pour connaître les valeurs valides.

    Mise en miroir du trafic

    Annotation Portée Statut Par défaut Description
    higress.ingress.kubernetes.io/mirror-target-service Ingress Extension Higress — Service cible pour le trafic mis en miroir. Format : namespace/name:port. namespace prend par défaut l'espace de noms de la passerelle Ingress ; port prend par défaut le premier port. name est obligatoire.
    higress.ingress.kubernetes.io/mirror-percentage Ingress Extension Higress (V1.2.32+) 100 Pourcentage de trafic à mettre en miroir. Valeurs valides : 0–100.

    Exemple :

    annotations:
  # Mirror 20% of traffic to the shadow service
  higress.ingress.kubernetes.io/mirror-target-service: "default/shadow-service:8080"
  higress.ingress.kubernetes.io/mirror-percentage: "20"

    Alias de domaine

    Annotation Portée Statut Description
    nginx.ingress.kubernetes.io/server-alias Nom de domaine Partiellement compatible (V1.2.30+) Domaine alias partageant la configuration TLS, de routage et de gouvernance du trafic du domaine principal. Prend uniquement en charge les domaines à correspondance exacte et les domaines génériques.

    Limitation de débit (obsolète)

    Ces annotations sont obsolètes. Utilisez plutôt le contrôle global de la limitation de débit.
    Annotation Portée Statut Par défaut Description
    higress.ingress.kubernetes.io/route-limit-rpm Ingress Extension Higress — Nombre maximal de requêtes par minute (RPM) par passerelle. Limite de rafale = valeur × route-limit-burst-multiplier. Lorsqu'elle est déclenchée, le corps de la réponse est local_rate_limited. Renvoie 503 avant la version V1.2.23, 429 à partir de la version V1.2.23.
    higress.ingress.kubernetes.io/route-limit-rps Ingress Extension Higress — Nombre maximal de requêtes par seconde (RPS) par passerelle. Même comportement de rafale et de réponse que route-limit-rpm.
    higress.ingress.kubernetes.io/route-limit-burst-multiplier Ingress Extension Higress 5 Multiplicateur de limite de rafale.

    Contrôle global de la limitation de débit (recommandé)

    Toutes les annotations de cette section nécessitent la version V1.2.25 ou ultérieure de la passerelle.

    Annotation Portée Statut Par défaut Description
    higress.ingress.kubernetes.io/rate-limit Ingress Extension Higress — Nombre maximal de RPS pour la route. Utilisé pour la limitation globale de débit.
    higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code Ingress Extension Higress 429 Code de réponse HTTP lorsque la limitation de débit est déclenchée.
    higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type Ingress Extension Higress text Type de contenu du corps de la réponse lorsque la limitation de débit est déclenchée. Définissez sur json pour renvoyer application/json; charset=UTF-8.
    higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body Ingress Extension Higress sentinel rate limited Corps de la réponse lorsque la limitation de débit est déclenchée.
    higress.ingress.kubernetes.io/rate-limit-fallback-redirect-url Ingress Extension Higress — URL de redirection lorsque la limitation de débit est déclenchée.
    rate-limit-fallback-custom-response-code et rate-limit-fallback-redirect-url sont mutuellement exclusifs. Définissez-en un seul.

    Exemple — renvoyer une réponse JSON personnalisée lorsque la limitation de débit est déclenchée :

    annotations:
  higress.ingress.kubernetes.io/rate-limit: "100"
  higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-code: "429"
  higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body-type: "json"
  higress.ingress.kubernetes.io/rate-limit-fallback-custom-response-body: '{"error":"rate limit exceeded"}'

    Contrôle global de la concurrence

    Toutes les annotations de cette section nécessitent la version V1.2.25 ou ultérieure de la passerelle.

    Annotation Portée Statut Par défaut Description
    higress.ingress.kubernetes.io/concurrency-limit Ingress Extension Higress — Nombre maximal de requêtes simultanées sur la route.
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-code Ingress Extension Higress 429 Code de réponse HTTP lorsque le contrôle de concurrence est déclenché.
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body-type Ingress Extension Higress text Type de contenu du corps de la réponse lorsque le contrôle de concurrence est déclenché. Définissez sur json pour renvoyer application/json; charset=UTF-8.
    higress.ingress.kubernetes.io/concurrency-limit-fallback-custom-response-body Ingress Extension Higress sentinel rate limited Corps de la réponse lorsque le contrôle de concurrence est déclenché.
    higress.ingress.kubernetes.io/concurrency-limit-fallback-redirect-url Ingress Extension Higress — URL de redirection lorsque le contrôle de concurrence est déclenché.
    concurrency-limit-fallback-custom-response-code et concurrency-limit-fallback-redirect-url sont mutuellement exclusifs. Définissez-en un seul.

    Protocole backend

    Annotation Portée Statut Par défaut Description
    nginx.ingress.kubernetes.io/backend-protocol Service Partiellement compatible HTTP Protocole utilisé par le service backend. AJP et FCGI ne sont pas pris en charge. Valeurs valides : HTTP, HTTP2, HTTPS, gRPC, gRPCS.

    Équilibrage de charge

    Annotation Portée Statut Par défaut Description
    nginx.ingress.kubernetes.io/load-balance Service Partiellement compatible round_robin Algorithme d'équilibrage de charge. La moyenne mobile exponentiellement pondérée (EWMA) n'est pas prise en charge ; le système revient à round_robin. Valeurs valides : round_robin, least_conn, random.
    nginx.ingress.kubernetes.io/upstream-hash-by Service Partiellement compatible — Algorithme de hachage cohérent. La combinaison de variables NGINX avec des constantes n'est pas prise en charge. Prend en charge le hachage par variable NGINX ($request_uri, $host, $remote_addr), en-tête de requête ($http_headerName), ou paramètre de requête ($arg_varName).

    Préchauffage (démarrage progressif)

    Annotation Portée Statut Par défaut Description
    higress.ingress.kubernetes.io/warmup Service Extension Higress Désactivé Durée de la période de préchauffage en secondes.
    Important

    Le préchauffage nécessite un algorithme d'équilibrage de charge round_robin ou least_conn. Il n'est pas pris en charge avec d'autres algorithmes.

    Affinité par cookie

    Annotation Portée Statut Par défaut Description
    nginx.ingress.kubernetes.io/affinity Service Compatible cookie Type d'affinité. Valeur par défaut et seule valeur valide : cookie.
    nginx.ingress.kubernetes.io/affinity-mode Service Partiellement compatible balanced Mode d'affinité. Le mode persistent n'est pas pris en charge. Valeur par défaut et seule valeur valide : balanced.
    nginx.ingress.kubernetes.io/session-cookie-name Service Compatible — Nom du cookie utilisé comme clé de hachage.
    nginx.ingress.kubernetes.io/session-cookie-path Service Compatible / Chemin du cookie généré lorsque le cookie spécifié n'existe pas.
    nginx.ingress.kubernetes.io/session-cookie-max-age Service Compatible Niveau session Durée d'expiration du cookie généré, en secondes.
    nginx.ingress.kubernetes.io/session-cookie-expires Service Compatible Niveau session Durée d'expiration du cookie généré, en secondes.

    Contrôle d'accès par adresse IP

    Annotation Portée Statut Description
    nginx.ingress.kubernetes.io/whitelist-source-range Ingress Compatible Liste d'autorisation d'adresses IP et de blocs CIDR pour la route. Séparés par des virgules.
    nginx.ingress.kubernetes.io/denylist-source-range Ingress Compatible (V1.2.31+) Liste de blocage au niveau de la route pour les adresses IP et les blocs CIDR. Séparés par des virgules. Prend le pas sur higress.ingress.kubernetes.io/blacklist-source-range.
    higress.ingress.kubernetes.io/blacklist-source-range Ingress Extension Higress Liste de blocage d'adresses IP et de blocs CIDR pour la route. Séparés par des virgules.
    higress.ingress.kubernetes.io/domain-whitelist-source-range Ingress Extension Higress Liste d'autorisation au niveau du domaine pour les adresses IP et les blocs CIDR. Séparés par des virgules. Les listes d'autorisation au niveau de la route prennent le pas.
    higress.ingress.kubernetes.io/domain-blacklist-source-range Ingress Extension Higress Liste de blocage au niveau du domaine pour les adresses IP et les blocs CIDR. Séparés par des virgules. Les listes de blocage au niveau de la route prennent le pas.

    Pool de connexions (passerelle vers backend)

    Annotation Portée Statut Description
    higress.ingress.kubernetes.io/connection-policy-tcp-max-connection Service Extension Higress Nombre maximal total de connexions TCP vers le service backend.
    higress.ingress.kubernetes.io/connection-policy-tcp-max-connection-per-endpoint Service Extension Higress Nombre maximal de connexions TCP par endpoint backend.
    higress.ingress.kubernetes.io/connection-policy-http-max-request-per-connection Service Extension Higress Nombre maximal de requêtes HTTP par connexion backend.

    Annotations de sécurité

    TLS entre le client et la passerelle

    Annotation Portée Statut Valeur par défaut Description
    higress.ingress.kubernetes.io/tls-min-protocol-version Nom de domaine Extension Higress TLSv1.0 Version minimale du protocole TLS. Valeurs valides : TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3.
    higress.ingress.kubernetes.io/tls-max-protocol-version Nom de domaine Extension Higress TLSv1.3 Version maximale du protocole TLS. Valeurs valides : TLSv1.0, TLSv1.1, TLSv1.2, TLSv1.3.
    nginx.ingress.kubernetes.io/ssl-cipher Nom de domaine Compatible Voir ci-dessous Suites de chiffrement TLS, séparées par des virgules. S'applique uniquement aux versions TLS v1.0 à v1.2 (pas à la v1.3).
    higress.ingress.kubernetes.io/auth-tls-secret Nom de domaine Partiellement compatible — Certificat CA pour la vérification du client mTLS. Format du nom du secret : {domain-certificate-secret-name}-cacert.

    Suites de chiffrement par défaut pour ssl-cipher : 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.

    TLS entre la passerelle et le backend

    Annotation Portée Statut Description
    nginx.ingress.kubernetes.io/proxy-ssl-secret Service Compatible Certificat client utilisé par la passerelle pour l'authentification auprès du backend.
    nginx.ingress.kubernetes.io/proxy-ssl-name Service Compatible Indication du nom du serveur (SNI) envoyée lors du handshake TLS avec le backend.
    nginx.ingress.kubernetes.io/proxy-ssl-server-name Service Compatible Active ou désactive le SNI lors du handshake TLS avec le backend.

    Authentification de base

    Annotation Portée Statut Description
    nginx.ingress.kubernetes.io/auth-type Ingress Partiellement compatible Type d'authentification. Seule la valeur basic est prise en charge.
    nginx.ingress.kubernetes.io/auth-secret Ingress Compatible Secret contenant les identifiants pour la route. Format : <namespace>/<name>.
    nginx.ingress.kubernetes.io/auth-secret-type Ingress Compatible Format des données du secret. auth-file : la clé est auth, la valeur est username:password (une entrée par ligne). auth-map : la clé est le nom d'utilisateur, la valeur est le mot de passe.
    nginx.ingress.kubernetes.io/auth-realm Ingress Compatible Domaine d'authentification. Les identifiants sont partagés au sein d'un même domaine.

    Référence complète des annotations NGINX Ingress : Annotations.