Exposer un service avec Gateway API et ALB - Container Service for Kubernetes

Configurez les ressources Gateway, HTTPRoute et TLS pour acheminer le trafic externe vers les services ACK via une instance Application Load Balancer (ALB).

Modèle de ressources

L'API Gateway définit trois types de ressources, chacun géré par un rôle différent :

Ressource	Propriétaire	Objectif
GatewayClass	Fournisseur d'infrastructure (Alibaba Cloud)	Définit une classe de passerelle prise en charge par un contrôleur — ici, l'ALB Ingress Controller
Gateway	Opérateur de cluster	Provisionne une instance ALB et configure les écouteurs (ports, protocoles, noms d'hôte)
HTTPRoute	Développeur d'applications	Définit les règles de routage qui associent les requêtes entrantes aux services backend

Les équipes plateforme gèrent l'infrastructure, tandis que les équipes applicatives administrent les règles de routage de manière indépendante.

Le ALB Ingress Controller prend en charge l'API Gateway depuis la version 2.17.0.

Prérequis

Assurez-vous que les conditions suivantes sont remplies :

Un cluster ACK managé exécutant Kubernetes 1.24 ou une version ultérieure
La version 2.17.0 ou ultérieure de l'ALB Ingress Controller installée dans le cluster
La version 1.1.0 ou ultérieure de l'API Gateway installée dans le cluster
Deux vSwitch compatibles avec ALB dans le VPC où votre cluster est déployé

Vérifier l'environnement

L'ALB Ingress Controller crée automatiquement une ressource GatewayClass nommée alb. Vérifiez son existence avant de poursuivre.

Console

Connectez-vous à la console ACK. Dans le volet de navigation de gauche, cliquez sur Clusters.
Sur la page Clusters, cliquez sur le nom de votre cluster. Dans le volet de navigation de gauche, choisissez Workloads > Custom Resources.
Cliquez sur gateway.networking.k8s.io et affichez la ressource GatewayClass sous v1.

kubectl

Vérifiez la GatewayClass :

kubectl get gatewayclass

Exemple de sortie :

NAME   CONTROLLER                         ACCEPTED   AGE
alb    gateways.alibabacloud.com/alb/v1   True       1m

La valeur ACCEPTED: True confirme que la GatewayClass est prête.

Déployer un exemple d'application

Créez un fichier httpbin.yaml :

Le Service utilise ClusterIP par défaut. Si votre cluster utilise le plug-in réseau Flannel, modifiez spec.type en NodePort .

apiVersion: apps/v1
kind: Deployment
metadata:
  name: go-httpbin
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: go-httpbin
  template:
    metadata:
      labels:
        app: go-httpbin
        version: v1
    spec:
      containers:
        - image: registry.cn-hangzhou.aliyuncs.com/mse/go-httpbin
          args:
            - "--port=8090"
            - "--version=v1"
          imagePullPolicy: Always
          name: go-httpbin
          ports:
            - containerPort: 8090
---
apiVersion: v1
kind: Service
metadata:
  name: go-httpbin
  namespace: default
spec:
  type: ClusterIP
  ports:
    - port: 80
      targetPort: 8090
      protocol: TCP
  selector:
    app: go-httpbin

Appliquez le manifeste :

kubectl apply -f httpbin.yaml

Déployer la Gateway et la règle de routage

Important

La création d'une Gateway provisionne une instance ALB et engendre des frais. Les instances ALB créées par une Gateway ne sont pas supprimées automatiquement lorsque vous supprimez le cluster. Supprimez la ressource Gateway avant de supprimer le cluster afin d'éviter des frais imprévus.

Étape 1 : Créer la Gateway et l'HTTPRoute

Créez un fichier gateway.yaml :

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: alb
  namespace: default
spec:
  gatewayClassName: alb
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      hostname: "*.ingress.top"
      allowedRoutes:
        namespaces:
          from: Same
---
apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: demo-route
spec:
  parentRefs:            # Attach this route to the Gateway above
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: alb
  hostnames:
    - demo.ingress.top
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:       # Forward matched traffic to go-httpbin on port 80
        - kind: Service
          name: go-httpbin
          port: 80

La Gateway provisionne une instance ALB avec un écouteur HTTP sur le port 80 pour *.ingress.top. L'HTTPRoute transfère le trafic destiné à demo.ingress.top vers le Service go-httpbin.

Appliquez le manifeste :

kubectl apply -f gateway.yaml

Étape 2 : Attendre que la Gateway soit prête

kubectl wait --for=condition=programmed gateway/alb --timeout=120s

Vérifiez l'adresse de la Gateway :

kubectl get gateway alb

Exemple de sortie :

NAME   CLASS   ADDRESS                                                  PROGRAMMED   AGE
alb    alb     alb-0mwhq4ck6xxxxxxxxx.cn-hangzhou.alb.aliyuncsslb.com   True         2m12s

Étape 3 : Vérifier le statut de l'HTTPRoute

kubectl describe httproute demo-route | grep Status -A 20

Exemple de sortie :

Status:
  Parents:
    Conditions:
      Last Transition Time:  2025-05-23T08:21:25Z
      Message:               Route is accepted.
      Observed Generation:   1
      Reason:                Accepted
      Status:                True
      Type:                  Accepted
      Last Transition Time:  2025-05-23T08:21:25Z
      Message:               Route is resolved.
      Observed Generation:   1
      Reason:                ResolvedRefs
      Status:                True
      Type:                  ResolvedRefs
    Controller Name:         gateways.alibabacloud.com/alb/v1
    Parent Ref:
      Group:  gateway.networking.k8s.io
      Kind:   Gateway
      Name:   alb

Les valeurs Accepted: True et ResolvedRefs: True confirment que la route est active.

Étape 4 : Tester l'accès

Récupérez l'adresse de la Gateway et envoyez une requête de test :

export ALB_DOMAIN=$(kubectl get gateway alb -n default -o jsonpath='{.status.addresses[?(@.type=="Hostname")].value}')
curl -H "Host: demo.ingress.top" http://${ALB_DOMAIN}/version

Exemple de sortie :

version: v1
hostname: go-httpbin-547xxxxxf6-xxxxx

Cas d'utilisation

Modifier les en-têtes de requête avec un filtre

Les filtres HTTPRoute permettent de réécrire les requêtes ou les réponses en transit. Cet exemple ajoute un en-tête de requête personnalisé.

Créez un fichier httproute-filter.yaml :

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: demo-filter
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: alb
  hostnames:
    - filter.ingress.top
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      filters:
        - type: RequestHeaderModifier
          requestHeaderModifier:
            add:
              - name: my-header
                value: foo
      backendRefs:
        - kind: Service
          name: go-httpbin
          port: 80

Le filtre RequestHeaderModifier modifie les requêtes avant qu'elles n'atteignent le backend :

Ajoute my-header: foo aux requêtes correspondantes.
Utilise l'action add qui ajoute l'en-tête sans remplacer les en-têtes existants portant le même nom.

Appliquez la règle de routage :

kubectl apply -f httproute-filter.yaml

Testez avec le point de terminaison /header qui renvoie les en-têtes de la requête :

curl -H "Host: filter.ingress.top" http://${ALB_DOMAIN}/header

Exemple de sortie :

headers: {
    "Accept": [
      "*/*"
    ],
    "Connection": [
      "close"
    ],
    "Host": [
      "filter.ingress.top"
    ],
    "My-Header": [
      "foo"
    ],
    "Path": [
      "/header"
    ],
    "Protocol": [
      "HTTP/1.1"
    ],
    "Remoteip": [
      "118.xx.xx.91"
    ],
    "URL": [
      "/header"
    ],
    "User-Agent": [
      "curl/8.9.1"
    ]
  }
 query param:
, hostname: go-httpbin-547xxxxxf6-xxxxx

La présence de My-Header: foo dans la sortie confirme que le filtre fonctionne.

Répartir le trafic par poids

Attribuez des poids à plusieurs services backend pour distribuer le trafic proportionnellement, par exemple pour des déploiements canari.

Créez un fichier nginx.yaml contenant deux déploiements NGINX :

Développer pour afficher le contenu YAML

apiVersion: apps/v1
kind: Deployment
metadata:
  name: old-nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      run: old-nginx
  template:
    metadata:
      labels:
        run: old-nginx
    spec:
      containers:
      - image: registry.cn-hangzhou.aliyuncs.com/acs-sample/old-nginx
        imagePullPolicy: Always
        name: old-nginx
        ports:
        - containerPort: 80
          protocol: TCP
      restartPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: old-nginx
spec:
  type: ClusterIP
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: old-nginx
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: new-nginx
spec:
  replicas: 1
  selector:
    matchLabels:
      run: new-nginx
  template:
    metadata:
      labels:
        run: new-nginx
    spec:
      containers:
      - image: registry.cn-hangzhou.aliyuncs.com/acs-sample/new-nginx
        imagePullPolicy: Always
        name: new-nginx
        ports:
        - containerPort: 80
          protocol: TCP
      restartPolicy: Always
---
apiVersion: v1
kind: Service
metadata:
  name: new-nginx
spec:
  type: ClusterIP
  ports:
  - port: 80
    protocol: TCP
    targetPort: 80
  selector:
    run: new-nginx

old-nginx renvoie old ; new-nginx renvoie new. Les deux sont déployés dans le namespace default.

Créez un fichier httproute-weight.yaml :

apiVersion: gateway.networking.k8s.io/v1beta1
kind: HTTPRoute
metadata:
  name: demo-weight
spec:
  parentRefs:
    - group: gateway.networking.k8s.io
      kind: Gateway
      name: alb
  hostnames:
    - weight.ingress.top
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /
      backendRefs:
        # Weights are relative, not percentages — they do not need to add up to 100.
        - kind: Service
          name: old-nginx
          port: 80
          weight: 100
        - kind: Service
          name: new-nginx
          port: 80
          weight: 100

Les deux backends ont des poids égaux (100:100), donc le trafic est réparti à parts égales (1:1).

Appliquez les manifestes :

kubectl apply -f nginx.yaml
kubectl apply -f httproute-weight.yaml

Envoyez 10 requêtes pour observer la répartition :

for i in {1..10}; do curl -H "Host: weight.ingress.top" http://${ALB_DOMAIN}/; done

Exemple de sortie :

old
new
new
old
new
old
old
new
new
old

Le trafic est réparti approximativement à parts égales entre les deux backends.

Configurer un certificat TLS

Ajoutez la terminaison HTTPS à la Gateway en référençant un Secret Kubernetes contenant votre certificat TLS.

Étape 1 : Créer un certificat auto-signé

openssl req -subj '/CN=ingress.top' -new -newkey rsa:2048 -sha256 \
  -days 365 -nodes -x509 -keyout server.key -out server.crt \
  -addext "subjectAltName = DNS:ingress.top" \
  -addext "keyUsage = digitalSignature" \
  -addext "extendedKeyUsage = serverAuth" 2> /dev/null; \
  openssl x509 -in server.crt -subject -noout

Étape 2 : Créer un Secret TLS

kubectl create secret tls ingress.top --key server.key --cert server.crt

Étape 3 : Mettre à jour la Gateway pour ajouter un écouteur HTTPS

Créez un fichier gateway-tls.yaml :

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: alb
  namespace: default
spec:
  gatewayClassName: alb
  listeners:
    - name: http
      protocol: HTTP
      port: 80
      hostname: "*.ingress.top"
      allowedRoutes:
        namespaces:
          from: Same
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.ingress.top"
      allowedRoutes:
        namespaces:
          from: Same
      tls:
        mode: Terminate          # ALB terminates TLS and forwards plain HTTP to backends
        certificateRefs:
          - kind: Secret
            name: ingress.top   # The Secret created in the previous step

En mode Terminate, ALB déchiffre le trafic HTTPS et transmet du HTTP simple aux backends. Le champ certificateRefs référence le Secret contenant le certificat et la clé privée.

Appliquez la mise à jour :

kubectl apply -f gateway-tls.yaml

Étape 4 : Vérifier le certificat

Attendez que le statut PROGRAMMED de la Gateway revienne à True :

kubectl wait --for=condition=programmed gateway/alb --timeout=120s

Vérifiez le certificat :

openssl s_client -servername ingress.top -connect ${ALB_DOMAIN}:443

Exemple de sortie :

CONNECTED(00000003)
depth=0 CN = ingress.top
verify error:num=18:self-signed certificate
verify return:1
depth=0 CN = ingress.top
verify return:1
---
Certificate chain
 0 s:CN = ingress.top
   i:CN = ingress.top
   a:PKEY: rsaEncryption, 2048 (bit); sigalg: RSA-SHA256
   v:NotBefore: Jun 24 10:49:39 2025 GMT; NotAfter: Jun 24 10:49:39 2026 GMT
---
Server certificate
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
subject=CN = ingress.top
issuer=CN = ingress.top
---
...
New, TLSv1.2, Cipher is ECDHE-RSA-AES128-GCM-SHA256
Server public key is 2048 bit
...
Verify return code: 18 (self-signed certificate)

Les valeurs CN = ingress.top et le chiffrement TLSv1.2 confirment que la terminaison TLS fonctionne. L'erreur self-signed certificate est attendue — utilisez un certificat signé par une autorité de certification en production.

Testez l'accès HTTPS avec l'indicateur -k pour ignorer la vérification du certificat auto-signé :

curl -H "Host: demo.ingress.top" -k https://${ALB_DOMAIN}/version

Exemple de sortie :

version: v1
hostname: go-httpbin-547xxxxxf6-xxxxx

Étapes suivantes

API Gateway — Spécification complète, y compris le routage avancé tel que la correspondance basée sur les en-têtes et la mise en miroir du trafic.
ALB Ingress Controller — Annotations spécifiques à ALB et configuration pour les charges de travail de production.