Gateway API
Cette page concerne uniquement les installations basées sur Helm sur un existing cluster. Consultez Ingress pour le modèle de routage par défaut.
Le chart Helm de GitGuardian peut router le trafic externe via la Kubernetes Gateway API plutôt que via la ressource Ingress héritée. Cette option est facultative : les installations existantes continuent d'utiliser Ingress par défaut.
La Gateway API est le successeur moderne, pérenne et standardisé d'Ingress pour le routage du trafic Kubernetes : au lieu de s'appuyer sur des annotations spécifiques au contrôleur comme le fait l'Ingress NGINX, elle exprime le routage via des ressources portables et orientées rôles. Son adoption permet également des fonctionnalités telles que l'autoscaling de l'application web basé sur la latence.
Chaque HTTPRoute émis par le chart utilise le type de correspondance de chemin RegularExpression. Votre contrôleur Gateway API DOIT prendre en charge les correspondances RegularExpression, sinon les ressources sont rejetées et le trafic ne circule pas. Contrôleurs validés : Istio (≥ 1.25), NGINX Gateway Fabric, Traefik (≥ v3). Vérifiez la prise en charge de votre contrôleur avant d'activer le mode Gateway API.
Quand devriez-vous utiliser la Gateway API ?
La Gateway API est le bon choix lorsque :
- Votre équipe plateforme s'est standardisée sur la Gateway API et souhaite que GitGuardian suive le même modèle que le reste du cluster.
- Vous exploitez un cluster multi-tenant avec un
Gatewaypartagé géré par une autre équipe, et vous souhaitez que les routes de GitGuardian s'y rattachent plutôt que de provisionner un point d'entrée dédié. - Votre plan de données (Istio, Envoy Gateway, Kong, NGINX Gateway Fabric, …) s'éloigne de la ressource
Ingresset la Gateway API vous offre une séparation des rôles plus nette entre les équipes plateforme et applicatives.
Si aucun des cas ci-dessus ne s'applique, le mode Ingress par défaut est le choix le plus simple.
Prérequis
Pour utiliser le mode Gateway API, vous avez besoin de :
- Kubernetes ≥ 1.25
- CRDs Gateway API ≥ v1.0 (canal : standard) installées à l'échelle du cluster
- Un contrôleur conforme à la Gateway API avec prise en charge des correspondances de chemin
RegularExpression— voir l'avertissement ci-dessus pour les contrôleurs validés. - Une
GatewayClassque le contrôleur réconcilie, prête à être référencée par votreGateway
Vérifier la compatibilité du cluster
Exécutez les vérifications suivantes avant de passer en mode Gateway API.
Confirmez que les CRDs sont installées :
kubectl get crd gateways.gateway.networking.k8s.io \
httproutes.gateway.networking.k8s.io \
gatewayclasses.gateway.networking.k8s.io
Les trois CRDs doivent exister. Si ce n'est pas le cas, installez-les en suivant la documentation de votre contrôleur (la plupart des contrôleurs les fournissent ou documentent l'URL exacte de kubectl apply).
Confirmez qu'une GatewayClass est disponible et acceptée :
kubectl get gatewayclass
NAME CONTROLLER ACCEPTED AGE
istio istio.io/gateway-controller True 28d
Vous devriez voir au moins une entrée avec ACCEPTED=True. Notez la colonne NAME — il s'agit de la valeur que vous définirez dans ingress.gatewayApi.gatewayClassName.
Confirmez que le contrôleur est sain :
kubectl get pods -A -l 'app.kubernetes.io/component in (controller, gateway-api)'
Le label exact dépend de votre contrôleur ; en cas de doute, vérifiez que le namespace dans lequel il s'exécute (istio-system, envoy-gateway-system, kong, projectcontour, …) a tous ses pods à l'état Running.
Configuration
Deux valeurs contrôlent le routage dans votre fichier values.yaml, et elles sont intentionnellement orthogonales :
ingress.routingApi:ingress(par défaut) ougateway-api. Sélectionne l'API de routage utilisée pour exposer GitGuardian.ingress.controller: le plan de données qui satisfait les routes. Utilisé dans les deux modes pour les métriques d'autoscaling ; en mode Ingress, il choisit également le format du manifeste de routage.
Champs communs
Les champs suivants conservent la même signification dans les deux modes :
| Champ | Objectif |
|---|---|
ingress.enabled | Interrupteur principal pour l'exposition externe. |
ingress.controller | Nom du plan de données. Détermine la sélection de la métrique d'autoscaling (HPA / KEDA). En mode Gateway API, il n'influence pas le routage. |
ingress.tls.enabled | Active TLS sur les listeners publics et la redirection HTTP → HTTPS. |
ingress.tls.existingSecret | Nom du Secret contenant le certificat TLS. |
hostname / domain | Noms d'hôtes publics utilisés par le chart (app, API, receiver). |
Champs spécifiques à la Gateway API
Ces champs ne sont consommés que lorsque routingApi: gateway-api :
| Champ | Objectif |
|---|---|
ingress.routingApi | Définissez sur gateway-api pour activer ce mode. La valeur par défaut est ingress. |
ingress.gatewayApi.gatewayClassName | Nom de la GatewayClass référencée par le chart. Requis uniquement lorsque gateway.create=true. Exécutez kubectl get gatewayclass pour trouver les classes disponibles dans votre cluster. |
ingress.gatewayApi.gateway.create | true permet au chart de créer et posséder le Gateway aux côtés de la release Helm. false fait que le chart rattache ses ressources HTTPRoute à un Gateway géré ailleurs (modèle multi-tenant). |
ingress.gatewayApi.gateway.name | Nom du Gateway. Le Gateway que le chart crée si create=true, ou le Gateway existant auquel se rattacher si create=false. |
ingress.gatewayApi.gateway.namespace | Namespace du Gateway existant. Requis uniquement lorsque create=false et que le Gateway réside dans un namespace différent de celui de GitGuardian. |
ingress.gatewayApi.gateway.httpListenerPort | Port du listener HTTP sur le Gateway géré par le chart. Par défaut 80. Ignoré lorsque create=false. |
ingress.gatewayApi.gateway.httpsListenerPort | Port du listener HTTPS sur le Gateway géré par le chart. Par défaut 443. Ignoré lorsque create=false. |
Exemple : Gateway géré par le chart
La configuration la plus simple. Le chart crée le Gateway dans le namespace GitGuardian ; le contrôleur provisionne un équilibreur de charge pour celui-ci.
ingress:
enabled: true
routingApi: gateway-api
controller: istio
tls:
enabled: true
existingSecret: gitguardian-tls
gatewayApi:
gatewayClassName: istio
gateway:
create: true
name: gitguardian
httpListenerPort: 80
httpsListenerPort: 443
Exemple : rattachement à un Gateway existant (multi-tenant)
Le chart n'émet que des ressources HTTPRoute pointant vers un Gateway qui existe déjà dans le cluster. Typique lorsqu'une équipe plateforme exploite un Gateway partagé pour de nombreuses applications.
ingress:
enabled: true
routingApi: gateway-api
controller: istio
tls:
enabled: true
# Laissez vide si le certificat est géré au niveau du Gateway
# par votre équipe plateforme.
existingSecret: ''
gatewayApi:
gatewayClassName: istio
gateway:
create: false
name: shared-gateway
namespace: gateway-system
Trois conditions doivent être réunies du côté de l'équipe plateforme pour que le rattachement réussisse :
- Le
spec.listeners[].allowedRoutes.namespacesduGatewaycible doit autoriser les routes provenant du namespace GitGuardian. Définissez-le surFrom: All, ou utilisezFrom: Selectoravec un label qui correspond au namespace GitGuardian. - Si TLS est activé et que vous référencez un
Secretdepuis le chart, ceSecretdoit être accessible par leGateway(généralement dans le namespace duGateway). Lorsque le certificat est entièrement géré au niveau duGateway, laissezingress.tls.existingSecretvide. - Le
Gatewaydoit exposer des listeners portant les noms que les routes du chart ciblent viasectionName:- Un listener nommé
httpest toujours requis (utilisé par la route de redirection HTTP → HTTPS lorsque TLS est activé, ou par toutes les routes lorsque TLS est désactivé). - Un listener nommé
httpsest requis lorsqueingress.tls.enabled=true.
- Un listener nommé
Limitations
Les limites de taille de corps ne font pas partie du standard Gateway API. Le chart n'en définit pas en mode Gateway API, de sorte que la limite effective est celle par défaut de votre contrôleur (≈1 Mo sur NGF). Pour correspondre au mode hérité, attachez une politique spécifique au contrôleur à l'HTTPRoute gim-exposed avec une limite de 25 Mo. Exemple sur NGINX Gateway Fabric :
apiVersion: gateway.nginx.org/v1alpha1
kind: ClientSettingsPolicy
metadata:
name: gim-exposed-body-limit
namespace: <gitguardian-namespace>
spec:
targetRef:
group: gateway.networking.k8s.io
kind: HTTPRoute
name: gim-exposed
body:
maxSize: 25m
Pour Istio, Contour, Envoy Gateway ou Traefik, utilisez le mécanisme natif équivalent (par ex. EnvoyFilter, paramètre au niveau de la route, middleware) sur la même HTTPRoute.
Spécificités de NGINX Gateway Fabric
- Timeouts par route. NGF ignore
spec.rules[].timeouts(les routes affichentAccepted=True reason=UnsupportedField). Pour les restaurer, appliquez uneProxySettingsPolicy(NGF ≥ 2.6) à l'HTTPRoute concernée — par exemple pour conserver le plafond de 3600 s sur l'export des métriques de facturation, ciblezgim-appavecproxyReadTimeout: 3600s.
AWS Load Balancer Controller n'est pas pris en charge
Le mode Gateway API de l'AWS Load Balancer Controller (gateway.k8s.aws/alb) n'est pas pris en charge : les HTTPRoutes du chart utilisent un filtre ResponseHeaderModifier pour les en-têtes de sécurité, qu'il rejette (seul RequestRedirect est pris en charge), de sorte que le Gateway ne devient jamais Programmed. Sur Amazon EKS, utilisez plutôt un contrôleur validé tel que Istio.
Mise à niveau d'Ingress vers Gateway API
Le passage de routingApi de ingress à gateway-api peut potentiellement impacter le trafic : le chart cesse de créer des ressources Ingress et crée à la place des ressources Gateway/HTTPRoute. Le fait que cela nécessite une fenêtre de maintenance ou une bascule DNS dépend de la configuration de votre cluster.
Étape 1 — Identifier votre scénario
Deux chemins possibles :
- A. Rattachement à un
Gatewaypartagé existant géré par votre équipe plateforme. LeGatewayet son équilibreur de charge existent déjà ; GitGuardian ne fait qu'y ajouter des ressourcesHTTPRoute. Voir Exemple : rattachement à un Gateway existant. - B. Créer un nouveau
Gatewaydepuis le chart. Le chart provisionne unGatewaydédié, et votre contrôleur Gateway API provisionne l'équilibreur de charge sous-jacent pour celui-ci. Voir Exemple : Gateway géré par le chart.
Le scénario A est le modèle pour lequel la Gateway API a été conçue : l'administrateur du cluster possède le Gateway (point d'entrée, listeners, certificats, équilibreur de charge) et les équipes applicatives possèdent leurs ressources HTTPRoute. Cette séparation des responsabilités est une bonne pratique essentielle — l'administrateur du cluster garde un contrôle total sur la manière dont le trafic entre dans le cluster, tandis que les équipes applicatives restent libres de gérer leur propre routage sans toucher à l'infrastructure. Si votre organisation peut le prendre en charge, préférez le scénario A.
Le scénario B reste un choix valable lorsque GitGuardian est la seule application utilisant la Gateway API dans le cluster, lorsque vous n'avez pas (encore) de Gateway partagé, ou lorsque GitGuardian doit posséder son propre point d'entrée public pour des raisons organisationnelles. C'est également un tremplin pratique lors d'une migration depuis Ingress avant d'extraire ultérieurement le Gateway vers la responsabilité de l'équipe plateforme.
Étape 2 — Déterminer l'impact sur l'adresse publique
Le fait que l'IP / le nom d'hôte public de GitGuardian change dépend de votre scénario.
Scénario A — Rattachement à un Gateway existant. L'adresse est celle du Gateway partagé. Le passage de votre Ingress actuel à ce Gateway changera l'adresse publique à laquelle GitGuardian est accessible — à moins que le contrôleur Ingress existant et le Gateway partagé ne soient tous deux adossés au même équilibreur de charge, ce qui est peu courant. Planifiez une bascule DNS et une fenêtre de maintenance.
Scénario B — Gateway géré par le chart. Le fait qu'un nouvel équilibreur de charge soit provisionné dépend de votre contrôleur Gateway API :
- Certains contrôleurs provisionnent un
Servicede typeLoadBalancerparGateway(Istio en mode Gateway API, Envoy Gateway, Kong, Contour Gateway Provisioner). Avec ceux-ci, le nouveauGatewayobtient une nouvelle adresse — planifiez une bascule DNS et une fenêtre de maintenance. - Certains contrôleurs peuvent réutiliser un unique équilibreur de charge partagé entre plusieurs ressources
Gateway, voire le partager avec le chemin de donnéesIngresshérité (Traefik en mode Gateway API en est un exemple fréquent, selon la configuration). Avec ceux-ci, l'adresse publique peut être préservée et la bascule se rapproche d'une mise à niveau Helm ordinaire.
Consultez la documentation de votre contrôleur avant de présumer du comportement — c'est la question la plus importante à résoudre avant de planifier la migration. Commande utile une fois un Gateway déployé :
kubectl get gateway <name> -n <namespace> -o jsonpath='{.status.addresses}'
Si l'adresse diffère de celle vers laquelle votre DNS pointe actuellement, vous êtes dans la situation « nouvel équilibreur de charge ».
Étape 3 — Planifier la bascule
Si l'adresse change (la plupart des cas) :
L'objectif est de répéter d'abord la bascule de bout en bout dans un environnement hors production — appliquez la même modification de values.yaml et confirmez que les routes fonctionnent — afin que la bascule en production soit une opération maîtrisée plutôt qu'une découverte. Une fois cela fait :
- Déployez le nouveau contrôleur Gateway API aux côtés du contrôleur Ingress existant si possible (en staging, ou en tant que release parallèle dans un namespace séparé), afin que les enregistrements DNS et les certificats puissent être préparés par rapport à la future adresse.
- Abaissez le TTL de vos enregistrements DNS avant la bascule afin que le retour en arrière soit rapide.
- Basculez la release GitGuardian vers
routingApi: gateway-api. Le chart supprime les ressourcesIngresset crée les routes par rapport auGateway. - Mettez à jour le DNS vers la nouvelle adresse du
Gateway(kubectl get gateway <name> -o jsonpath='{.status.addresses}'). - Si un proxy inverse d'entreprise ou un CDN se trouve devant GitGuardian, mettez à jour son origine vers la nouvelle adresse.
Si l'adresse est préservée (le contrôleur réutilise le même équilibreur de charge) :
La bascule se rapproche d'une mise à niveau Helm ordinaire, mais l'objectif reste de la répéter d'abord dans un environnement hors production afin que la bascule soit une opération maîtrisée. Une fois cela fait :
- Basculez la release GitGuardian vers
routingApi: gateway-api. Le chart remplace les ressourcesIngresspar des ressourcesGateway/HTTPRoute; le trafic continue de circuler par le même équilibreur de charge. - Confirmez avec
kubectl get httproute -n <namespace>etkubectl describe gateway <name>que toutes les routes sontAccepted=Trueet que leGatewayestProgrammed=True.
Certificat TLS
Le Secret TLS référencé par ingress.tls.existingSecret doit résider dans un namespace accessible par le Gateway — généralement le namespace propre au Gateway. Si vous conservez actuellement le certificat dans le namespace GitGuardian et que vous passez à un Gateway dans un autre namespace, répliquez le Secret (ou appuyez-vous sur un outil comme cert-manager ou reflector pour le copier).
Autoscaling
En mode Gateway API, des requêtes de latence intégrées sont disponibles pour controller: istio, traefik et contour — elles réutilisent les mêmes métriques qu'en mode Ingress, de sorte qu'aucune reconfiguration HPA/KEDA n'est nécessaire lors de la migration (Contour nécessite en outre le canal expérimental des CRDs Gateway API). Pour tout autre plan de données (NGINX Gateway Fabric, Kong, Cilium, Envoy Gateway, …), définissez controller: other et fournissez votre propre déclencheur KEDA.
Consultez Autoscaling des applications web pour la matrice de prise en charge et des exemples de configuration (requête intégrée, other + déclencheur personnalisé, et remplacement de la requête).
Rollback
Pour revenir en arrière, redéfinissez routingApi sur ingress et réappliquez. Le chart recréera les ressources Ingress. Les ressources Gateway/HTTPRoute sont supprimées par Helm ; dans le scénario B, l'équilibreur de charge cloud sous-jacent est libéré par le contrôleur. Les enregistrements DNS doivent être rétablis manuellement s'ils ont été modifiés.
Dépannage
La Gateway API expose des conditions de statut sur chaque ressource. La plupart des problèmes y apparaissent.
# Listeners du Gateway et adresse assignée
kubectl get gateway -n <namespace>
kubectl describe gateway <name> -n <namespace>
# Routes et leur statut de rattachement
kubectl get httproute -n <gitguardian-namespace>
kubectl describe httproute -n <gitguardian-namespace>
Cas courants :
Accepted=FalsesurHTTPRouteavec une raisonNotAllowedByListeners— leGatewaypartagé n'autorise pas les routes provenant du namespace GitGuardian. Mettez à jour lespec.listeners[].allowedRoutes.namespacesduGateway.Programmed=FalsesurGateway— le contrôleur n'a pas terminé le provisionnement de l'équilibreur de charge sous-jacent. Consultez les logs du contrôleur.- Aucun trafic n'atteint GitGuardian mais les routes sont acceptées — confirmez que le DNS pointe vers la nouvelle adresse du
Gateway, et que les groupes de sécurité de l'équilibreur de charge cloud autorisent le trafic entrant sur les ports des listeners. - Échecs de handshake TLS — confirmez que le
Secretréférencé paringress.tls.existingSecretexiste dans un namespace accessible par leGateway(généralement le namespace duGateway).