Aller au contenu principal

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 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.

Exigence relative au 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 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 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 plan de données (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 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 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é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) ou gateway-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 :

ChampObjectif
ingress.enabledInterrupteur principal pour l'exposition externe.
ingress.controllerNom 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.enabledActive TLS sur les listeners publics et la redirection HTTP → HTTPS.
ingress.tls.existingSecretNom du Secret contenant le certificat TLS.
hostname / domainNoms 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 :

ChampObjectif
ingress.routingApiDéfinissez sur gateway-api pour activer ce mode. La valeur par défaut est ingress.
ingress.gatewayApi.gatewayClassNameNom 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.createtrue 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.nameNom 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.namespaceNamespace 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.httpListenerPortPort du listener HTTP sur le Gateway géré par le chart. Par défaut 80. Ignoré lorsque create=false.
ingress.gatewayApi.gateway.httpsListenerPortPort 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 :

  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 portant 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, 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 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 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 Gateway partagé existant géré par votre équipe plateforme. Le Gateway et son équilibreur de charge existent déjà ; GitGuardian ne fait qu'y ajouter des ressources HTTPRoute. Voir Exemple : rattachement à 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 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 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 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é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 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 :

  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 par rapport à la future adresse.
  2. Abaissez le TTL de vos enregistrements DNS avant la bascule afin que le retour en arrière soit rapide.
  3. Basculez la release GitGuardian vers routingApi: gateway-api. Le chart supprime les ressources Ingress et crée les routes par rapport au Gateway.
  4. Mettez à jour le DNS vers la nouvelle adresse du Gateway (kubectl get gateway <name> -o jsonpath='{.status.addresses}').
  5. 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 :

  1. Basculez la release GitGuardian vers routingApi: gateway-api. Le chart remplace les ressources Ingress par des ressources Gateway/HTTPRoute ; le trafic continue de circuler par le même équilibreur de charge.
  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 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=False sur HTTPRoute avec une raison 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 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 Secret référencé par ingress.tls.existingSecret existe dans un namespace accessible par le Gateway (généralement le namespace du Gateway).