Gateway API

info

Cette page concerne uniquement les installations basées sur Helm sur un existing cluster. Voir Ingress pour le modèle de routage par défaut.

Le chart Helm de GitGuardian peut acheminer le trafic externe via la Kubernetes Gateway API au lieu de la ressource Ingress historique. 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é de Ingress pour le routage du trafic Kubernetes : au lieu de s'appuyer sur des annotations spécifiques à chaque contrôleur comme le fait l'Ingress NGINX, elle exprime le routage à travers des ressources portables et orientées rôles. Son adoption ouvre également la voie aux capacités à venir telles que l'autoscaling basé sur la latence de l'application web.

Exigence du contrôleur

Chaque HTTPRoute émise par le chart utilise le type de correspondance de chemin RegularExpression. Votre contrôleur Gateway API DOIT prendre en charge les matchers 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 par votre contrôleur avant d'activer le mode Gateway API.

Quand 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 Gateway partagé 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 data plane (Istio, Envoy Gateway, Kong, NGINX Gateway Fabric, …) s'éloigne de la ressource Ingress et la Gateway API vous offre une séparation des rôles plus claire entre les équipes plateforme et applicatives.

Si aucun de ces cas 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
• CRD Gateway API ≥ v1.0 (canal : standard) installés au niveau 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 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 au mode Gateway API.

Confirmez que les CRD sont installés :

kubectl get crd gateways.gateway.networking.k8s.io \
  httproutes.gateway.networking.k8s.io \
  gatewayclasses.gateway.networking.k8s.io

Les trois CRD doivent exister. S'ils n'existent pas, 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 — c'est la valeur que vous définirez dans ingress.gatewayApi.gatewayClassName.

Confirmez que le contrôleur est en bonne santé :

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 tous les pods du namespace dans lequel il s'exécute (istio-system, envoy-gateway-system, kong, projectcontour, …) sont à 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 satisfait les routes. Utilisé dans les deux modes pour les métriques d'autoscaling ; en mode Ingress, il sélectionne également le format du manifeste de routage.

Champs communs

Les champs suivants conservent la même signification dans les deux modes :

Champ	Objet
ingress.enabled	Interrupteur principal pour l'exposition externe.
ingress.controller	Nom du data plane. Détermine la sélection des métriques 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 utilisés que lorsque routingApi: gateway-api :

Champ	Objet
ingress.routingApi	Définir à 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 de posséder le Gateway aux côtés de 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 lui provisionne un load balancer.

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
    # Laisser 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 du côté de l'équipe plateforme pour que le rattachement réussisse :

1. Les spec.listeners[].allowedRoutes.namespaces du Gateway cible doivent autoriser les routes provenant du namespace GitGuardian. Définissez-le sur From: All, ou utilisez From: Selector avec un label correspondant 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 portant les noms ciblés par les routes du chart 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 du corps ne font pas partie du standard Gateway API. Le chart n'en définit aucune en mode Gateway API, donc le plafond effectif est celui par défaut de votre contrôleur (≈1 Mo sur NGF). Pour correspondre au mode historique, 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 affichent Accepted=True reason=UnsupportedField). Pour les restaurer, appliquez une ProxySettingsPolicy (NGF ≥ 2.6) à l'HTTPRoute concernée — 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 l'in-app-agent. Le chart ignore 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 le flux SSE fonctionne correctement.

AWS Load Balancer Controller n'est pas pris en charge

Le mode Gateway API du AWS Load Balancer Controller (gateway.k8s.aws/alb) n'est pas pris en charge : les HTTPRoute du chart utilisent un filtre ResponseHeaderModifier pour les en-têtes de sécurité, qu'il rejette (seul RequestRedirect est pris en charge), donc le Gateway n'atteint jamais l'état 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 potentiellement impacter le trafic : le chart cesse de créer des ressources Ingress et crée des ressources Gateway/HTTPRoute à la place. 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. Rattachement à un Gateway partagé existant géré par votre équipe plateforme. Le Gateway et son load balancer existent déjà ; GitGuardian se contente d'y ajouter des ressources HTTPRoute. Voir Exemple : rattachement à un Gateway existant.
• B. Création d'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. 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, 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 garde un contrôle complet 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 supporter, privilégiez le scénario A.

Le scénario B reste un choix valide 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 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

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é. Basculer de votre Ingress actuel vers ce Gateway modifiera l'adresse publique à laquelle GitGuardian est accessible — sauf si le contrôleur Ingress actuel et le Gateway partagé sont adossés au même load balancer, ce qui est rare. Prévoyez un basculement DNS et une fenêtre de maintenance.

Scénario B — Gateway géré par le chart. Le fait qu'un nouveau load balancer soit provisionné 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 est plus proche d'une mise à niveau Helm classique.

Consultez la documentation de votre contrôleur avant de présumer du comportement — c'est la question la plus importante à laquelle il faut 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 (cas le plus fréquent) :

L'objectif est de répéter d'abord le basculement de bout en bout dans un environnement hors production — appliquez le même changement de values.yaml et confirmez que les routes fonctionnent — afin 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 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 contre la future adresse.
2. Réduisez le TTL de vos enregistrements DNS avant le basculement pour 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 ou un CDN d'entreprise 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 est plus proche d'une mise à niveau Helm classique, mais l'objectif reste de le répéter d'abord dans un environnement hors production afin que le basculement soit une quantité connue. Une fois cela fait :

1. Basculez la release GitGuardian sur routingApi: gateway-api. Le chart remplace les ressources Ingress par 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 propre namespace du Gateway. Si vous conservez actuellement le certificat dans le namespace GitGuardian et que vous basculez vers 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

Seul controller: istio est actuellement pris en charge pour l'autoscaling de la webapp basé sur la latence en mode Gateway API — le chart réutilise les mêmes métriques istio_request_duration_milliseconds_bucket qu'en mode Ingress, donc aucune reconfiguration HPA/KEDA n'est nécessaire lors de la migration. Les autres contrôleurs (NGINX Gateway Fabric, Traefik, …) ne sont pas compatibles : désactivez l'autoscaling de la webapp ou basculez le déclencheur sur un déclencheur basé sur le CPU / le taux de requêtes.

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 restaurés 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=False sur une HTTPRoute avec une raison NotAllowedByListeners — le Gateway partagé n'autorise pas les routes du namespace GitGuardian. Mettez à jour les spec.listeners[].allowedRoutes.namespaces du Gateway.
• Programmed=False sur le 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 la nouvelle adresse du Gateway, et que les security groups du load balancer cloud autorisent le trafic entrant sur les ports des listeners.
• É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).