Gateway API

info

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 au lieu de la ressource Ingress historique. Cette option est opt-in : les installations existantes continuent d'utiliser Ingress par défaut.

La Gateway API est le successeur moderne, pérenne et standardisé de Ingress pour le routage du trafic Kubernetes : au lieu de reposer sur des annotations spécifiques au contrôleur comme le fait NGINX Ingress, elle exprime le routage via des ressources portables et orientées rôles. Son adoption permet également des fonctionnalités telles que l'autoscaling basé sur la latence de l'application web.

Exigence du contrôleur

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 utiliser Gateway API ?

Gateway API est le bon choix lorsque :

• Votre équipe plateforme a standardisé sur 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 Gateway partagé géré par une autre équipe, et vous souhaitez que les routes de GitGuardian s'y attachent plutôt que de provisionner un point d'entrée dédié.
• Votre data plane (Istio, Envoy Gateway, Kong, NGINX Gateway Fabric, …) s'éloigne de la ressource Ingress et Gateway API vous offre une séparation des rôles plus claire 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és à l'échelle du cluster
• Un contrôleur conforme à Gateway API prenant en charge la correspondance de chemin RegularExpression — consultez l'avertissement ci-dessus pour les contrôleurs validés.
• Une GatewayClass que le contrôleur réconcilie, prête à être référencée par votre Gateway

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és :

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 devez voir au moins une entrée avec ACCEPTED=True. Notez la colonne NAME — c'est 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 volontairement orthogonales :

• ingress.routingApi : ingress (par défaut) ou gateway-api. Sélectionne l'API de routage utilisée pour exposer GitGuardian.
• ingress.controller : le data plane qui remplit 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 gardent la même signification dans les deux modes :

Champ	Objectif
ingress.enabled	Interrupteur principal pour l'exposition externe.
ingress.controller	Nom du data plane. 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 à 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 que le chart référence. 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 de posséder le Gateway en même temps que la release Helm. false fait que le chart attache 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 s'attacher si create=false.
ingress.gatewayApi.gateway.namespace	Namespace du Gateway existant. Requis uniquement lorsque create=false et que le Gateway se trouve 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 load balancer 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 : attacher à 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 remplies côté équipe plateforme pour que l'attachement réussisse :

1. Le spec.listeners[].allowedRoutes.namespaces du Gateway cible doit autoriser les routes provenant du namespace GitGuardian. Définissez-le sur From: All, ou utilisez From: Selector avec un label qui correspond au namespace GitGuardian.
2. Si TLS est activé et que vous référencez un Secret depuis le chart, ce Secret doit être accessible par le Gateway (généralement dans le namespace du Gateway). Lorsque le certificat est entièrement géré au niveau du Gateway, laissez ingress.tls.existingSecret vide.
3. Le Gateway doit exposer des listeners avec les noms que les routes du chart ciblent via sectionName :
   • Un listener nommé http est 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é https est requis lorsque ingress.tls.enabled=true.

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, donc le plafond effectif est la valeur par défaut de votre contrôleur (≈1 Mo sur NGF). Pour correspondre au mode historique, attachez une policy 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 exemple EnvoyFilter, paramètre au niveau de la route, middleware) sur le même HTTPRoute.

Spécificités de NGINX Gateway Fabric

• Timeouts par route. NGF ignore spec.rules[].timeouts (les routes affichent Accepted=True reason=UnsupportedField). Pour les restaurer, appliquez une ProxySettingsPolicy (NGF ≥ 2.6) à l'HTTPRoute concerné — par exemple pour conserver le plafond de 3600 s sur l'export des métriques de facturation, ciblez gim-app avec proxyReadTimeout: 3600s.
• SSE de in-app-agent. Le chart saute automatiquement l'en-tête X-Accel-Buffering: no sur NGF (NGF le rejette de son allowlist). NGINX ne met pas en tampon les réponses en streaming par défaut, donc SSE circule correctement.

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 qu'Istio.

Migrer d'Ingress vers Gateway API

Basculer routingApi de ingress à gateway-api peut avoir un impact sur le trafic : le chart cesse de créer des ressources Ingress et crée à la place des ressources Gateway/HTTPRoute. Que cela nécessite une fenêtre de maintenance ou un basculement DNS dépend de la configuration de votre cluster.

Étape 1 — Identifier votre scénario

Deux chemins possibles :

• A. Attacher à un Gateway partagé existant géré par votre équipe plateforme. Le Gateway et son load balancer existent déjà ; GitGuardian n'ajoute que des ressources HTTPRoute à celui-ci. Voir Exemple : attacher à un Gateway existant.
• B. Créer un nouveau Gateway depuis le chart. Le chart provisionne un Gateway dédié, et votre contrôleur Gateway API provisionne le load balancer sous-jacent pour celui-ci. Voir Exemple : Gateway géré par le chart.

Le scénario A est le modèle pour lequel Gateway API a été conçu : l'administrateur du cluster possède le Gateway (point d'entrée, listeners, certificats, load balancer) et les équipes applicatives possèdent leurs ressources HTTPRoute. Cette séparation des responsabilités est une bonne pratique fondamentale — l'administrateur du cluster conserve le contrôle total sur la façon 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 Gateway API dans le cluster, lorsque vous n'avez pas (encore) de Gateway partagé, ou lorsque GitGuardian doit posséder son point d'entrée public pour des raisons organisationnelles. C'est également une étape intermédiaire pratique lors de la migration depuis Ingress avant d'extraire ultérieurement le Gateway vers la propriété de l'équipe plateforme.

Étape 2 — Déterminer l'impact sur l'adresse publique

Que l'IP publique / le nom d'hôte de GitGuardian change dépend de votre scénario.

Scénario A — Attacher à un Gateway existant. L'adresse est celle du Gateway partagé. Passer 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 soutenus par le même load balancer, ce qui est peu courant. Prévoyez un basculement DNS et une fenêtre de maintenance.

Scénario B — Gateway géré par le chart. Le provisionnement d'un nouveau load balancer dépend de votre contrôleur Gateway API :

• Certains contrôleurs provisionnent un Service de type LoadBalancer par Gateway (Istio en mode Gateway API, Envoy Gateway, Kong, Contour Gateway Provisioner). Avec ceux-ci, le nouveau Gateway obtient une nouvelle adresse — prévoyez un basculement DNS et une fenêtre de maintenance.
• Certains contrôleurs peuvent réutiliser un unique load balancer partagé entre plusieurs ressources Gateway, voire le partager avec le data path Ingress historique (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 le basculement se rapproche d'une mise à niveau Helm ordinaire.

Vérifiez la documentation de votre contrôleur avant de supposer le comportement — c'est la question la plus importante à laquelle répondre 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 « nouveau load balancer ».

Étape 3 — Planifier le basculement

Si l'adresse change (la plupart des cas) :

L'objectif est de répéter d'abord le basculement de bout en bout dans un environnement non-production — appliquer la même modification de values.yaml et confirmer que les routes fonctionnent — de sorte que le basculement en production soit une quantité connue plutôt qu'une découverte. Une fois cela fait :

1. Déployez le nouveau contrôleur Gateway API à côté du contrôleur Ingress existant si possible (en staging, ou comme release parallèle dans un namespace séparé), afin que les enregistrements DNS et les certificats puissent être préparés en fonction de la future adresse.
2. Abaissez le TTL sur vos enregistrements DNS avant le basculement afin que le rollback soit rapide.
3. Basculez la release GitGuardian sur routingApi: gateway-api. Le chart supprime les ressources Ingress et crée les routes contre le Gateway.
4. Mettez à jour le DNS vers la nouvelle adresse du Gateway (kubectl get gateway <name> -o jsonpath='{.status.addresses}').
5. Si un reverse proxy 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 load balancer) :

Le basculement se rapproche d'une mise à niveau Helm ordinaire, mais l'objectif reste de le répéter d'abord dans un environnement non-production afin que le basculement soit une quantité connue. Une fois cela fait :

1. Basculez la release GitGuardian sur routingApi: gateway-api. Le chart échange les ressources Ingress contre des ressources Gateway/HTTPRoute ; le trafic continue de circuler à travers le même load balancer.
2. Confirmez avec kubectl get httproute -n <namespace> et kubectl describe gateway <name> que toutes les routes sont Accepted=True et que le Gateway est Programmed=True.

Certificat TLS

Le Secret TLS référencé par ingress.tls.existingSecret doit se trouver 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 reposez-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, aucune reconfiguration HPA/KEDA n'est donc nécessaire lors de la migration (Contour nécessite en outre le canal expérimental des CRDs Gateway API). Pour tout autre data plane (NGINX Gateway Fabric, Kong, Cilium, Envoy Gateway, …), définissez controller: other et fournissez votre propre trigger KEDA.

Consultez Autoscaling des applications web pour la matrice de support et les exemples de configuration (requête intégrée, other + trigger personnalisé, et surcharge de la requête).

Rollback

Pour effectuer un rollback, 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, le load balancer 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

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 d'attachement
kubectl get httproute -n <gitguardian-namespace>
kubectl describe httproute -n <gitguardian-namespace>

Cas fréquents :

• Accepted=False sur HTTPRoute avec une raison NotAllowedByListeners — le Gateway partagé n'autorise pas les routes provenant du namespace GitGuardian. Mettez à jour spec.listeners[].allowedRoutes.namespaces du Gateway.
• Programmed=False sur Gateway — le contrôleur n'a pas fini de provisionner le load balancer sous-jacent. Vérifiez les logs du contrôleur.
• Aucun trafic n'atteint GitGuardian mais les routes sont acceptées — confirmez que le DNS pointe vers l'adresse du nouveau Gateway, et que les groupes de sécurité du load balancer cloud autorisent le trafic entrant sur les ports du listener.
• Échecs de handshake TLS — confirmez que le Secret référencé par ingress.tls.existingSecret existe dans un namespace accessible par le Gateway (généralement le namespace du Gateway).