Gateway API

info

Cette page ne concerne que 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 router le trafic externe via l'API Gateway de Kubernetes au lieu de la ressource Ingress héritée. Il s'agit d'une option à activer : les installations existantes continuent d'utiliser Ingress par défaut.

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, il exprime le routage à travers des ressources portables et orientées rôle. L'adopter permet également des capacité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 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 de votre contrôleur avant d'activer le mode Gateway API.

Quand devez-vous 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 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 Gateway API vous offre une séparation des rôles plus nette entre les équipes plateforme et applicatives.

Si aucun des points 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 avec prise en charge de la correspondance 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 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 kubectl apply exacte).

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 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 aussi 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 data plane. Pilote la sélection des métriques d'autoscaling (HPA / KEDA). En mode Gateway API, il n'influence pas le routage.
ingress.tls.enabled	Active le 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ôte 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 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 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 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 : rattachement à un Gateway existant (multi-tenant)

Le chart émet uniquement 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 :

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 le 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 le TLS est activé, ou par toutes les routes lorsque le 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 aucune 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 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 exemple 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.

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 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 ne devient jamais Programmed. Sur Amazon EKS, utilisez plutôt un contrôleur validé tel qu'Istio.

Migration d'Ingress vers Gateway API

Le passage de routingApi de ingress à gateway-api peut impacter le trafic : le chart cesse de créer des ressources Ingress et crée à la place des ressources Gateway/HTTPRoute. Le fait qu'il nécessite une fenêtre de maintenance ou un basculement DNS dépend de la configuration de votre cluster.

Étape 1 — Identifiez 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 y ajoute uniquement 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 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 garde le 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, privilégiez le scénario A.

Le scénario B reste un choix valide 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 propre point d'entrée public pour des raisons organisationnelles. C'est aussi une étape intermédiaire pratique lors de la migration depuis Ingress avant d'extraire le Gateway pour le confier à l'équipe plateforme plus tard.

Étape 2 — Déterminez 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 — sauf si le contrôleur Ingress existant et le Gateway partagé sont adossés au même load balancer, ce qui est rare. Planifiez 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 — planifiez 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 chemin de données Ingress hé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 le basculement se rapproche 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 répondre avant de planifier la migration. Commande utile une fois qu'un Gateway est 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 — Planifiez le basculement

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

L'objectif est de répéter le basculement de bout en bout dans un environnement hors production d'abord — appliquez le même changement de values.yaml et confirmez que les routes fonctionnent — afin que le basculement en production soit une donnée 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 comme 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.
2. Abaissez le TTL de 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 sur 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 classique, mais l'objectif reste de le répéter dans un environnement hors production d'abord afin que le basculement soit une donnée 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 résider 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 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, donc 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 data plane (NGINX Gateway Fabric, Kong, Cilium, Envoy Gateway, …), définissez controller: other et fournissez votre propre trigger KEDA.

Voir Autoscaling des applications web pour la matrice de support et des exemples de configuration (requête intégrée, other + trigger personnalisé, et remplacement 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 de rattachement
kubectl get httproute -n <gitguardian-namespace>
kubectl describe httproute -n <gitguardian-namespace>

Cas courants :

• Accepted=False sur HTTPRoute avec un motif NotAllowedByListeners — le Gateway partagé n'autorise pas les routes provenant du namespace GitGuardian. Mettez à jour le spec.listeners[].allowedRoutes.namespaces du Gateway.
• Programmed=False sur Gateway — le contrôleur n'a pas terminé le provisionnement du load balancer 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 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).