📖 Manuel

Kong API Gateway

Workflow en 6 étapes

1. Choisir le mode de déploiement

Règle : choisir DB-less par défaut. Passer en mode DB uniquement si Kong Manager, Konnect, ou des plugins enterprise nécessitent une base.

2. Écrire le kong.yml (DB-less)

_format_version: "3.0"
_transform: true   # permet d'utiliser des urls courtes (http://host:port)

services:
  - name: payment-service
    url: http://payment-api:8080
    connect_timeout: 5000
    write_timeout: 60000
    read_timeout: 60000
    retries: 3
    routes:
      - name: payment-route
        paths:
          - /api/payments
        methods: [GET, POST, PUT, DELETE]
        strip_path: true
        preserve_host: false
    plugins:
      - name: rate-limiting
        config:
          minute: 100
          policy: redis
          redis_host: redis
          redis_port: 6379
      - name: jwt
        config:
          claims_to_verify: [exp]
          key_claim_name: kid

  - name: order-service
    url: http://order-api:8080
    routes:
      - name: order-route
        paths: [/api/orders]
        strip_path: true
    plugins:
      - name: rate-limiting
        config:
          minute: 200
          policy: local          # local si pas de Redis, attention au multi-noeud
      - name: cors
        config:
          origins: [https://app.company.com]
          methods: [GET, POST, OPTIONS]
          headers: [Authorization, Content-Type]
          exposed_headers: [X-Request-ID]
          credentials: true
          max_age: 3600

# Consumers (pour JWT / Key Auth)
consumers:
  - username: mobile-app
    jwt_secrets:
      - key: mobile-app-key
        algorithm: RS256
        rsa_public_key: |
          -----BEGIN PUBLIC KEY-----
          ...
          -----END PUBLIC KEY-----

# Plugins globaux (s'appliquent à toutes les routes)
plugins:
  - name: prometheus
    config:
      per_consumer: true
      status_code_metrics: true
      latency_metrics: true
  - name: correlation-id
    config:
      header_name: X-Request-ID
      generator: uuid#counter
      echo_downstream: true
  - name: http-log
    config:
      http_endpoint: http://log-aggregator:5044
      timeout: 1000
      keepalive: 60000

3. Valider et appliquer la configuration

# Valider la syntaxe AVANT de déployer
kong config parse kong.yml

# DB-less : rechargement à chaud via Admin API (pas de downtime)
curl -sX POST http://localhost:8001/config \
  -F config=@kong.yml

# DB : import initial
kong config db_import kong.yml

# Vérifier l'état après rechargement
curl -s http://localhost:8001/status | jq .

4. Démarrer Kong (Docker Compose)

services:
  kong:
    image: kong:3.9          # version LTS 2026
    environment:
      KONG_DATABASE: "off"
      KONG_DECLARATIVE_CONFIG: /etc/kong/kong.yml
      KONG_PROXY_LISTEN: "0.0.0.0:8000, 0.0.0.0:8443 ssl"
      KONG_ADMIN_LISTEN: "127.0.0.1:8001"   # jamais 0.0.0.0 en prod
      KONG_LOG_LEVEL: warn
      KONG_NGINX_WORKER_PROCESSES: auto
      KONG_PLUGINS: bundled              # ou liste explicite
    ports:
      - "8000:8000"    # HTTP proxy
      - "8443:8443"    # HTTPS proxy
    volumes:
      - ./kong.yml:/etc/kong/kong.yml:ro
    healthcheck:
      test: ["CMD", "kong", "health"]
      interval: 10s
      timeout: 5s
      retries: 3

  # Redis pour rate-limiting distribué (multi-noeud obligatoire)
  redis:
    image: redis:7-alpine
    command: redis-server --save "" --appendonly no

5. Opérations courantes via Admin API

# Lister / inspecter
curl -s http://localhost:8001/services | jq '.data[].name'
curl -s http://localhost:8001/routes   | jq '.data[] | {name, paths}'
curl -s http://localhost:8001/plugins  | jq '.data[] | {name, enabled}'

# Désactiver un plugin à chaud (sans redémarrage)
PLUGIN_ID=$(curl -s http://localhost:8001/plugins?name=jwt | jq -r '.data[0].id')
curl -sX PATCH http://localhost:8001/plugins/$PLUGIN_ID \
  -d enabled=false

# Tester une route (proxy sur port 8000)
curl -sI -H "Authorization: Bearer <token>" http://localhost:8000/api/payments

# Recharger la config sans downtime (DB-less)
curl -sX POST http://localhost:8001/config -F config=@kong.yml | jq .

6. Monitoring et observabilité

# Métriques Prometheus (scraper sur :8001/metrics)
curl -s http://localhost:8001/metrics | grep kong_http

# Règle Prometheus à ajouter dans prometheus.yml :
# - job_name: kong
#   static_configs:
#     - targets: ['kong:8001']

# Grafana dashboard ID officiel Kong : 7424

Plugins essentiels — tableau de décision

Anti-patterns et pièges

Rate limiting sans Redis en multi-noeud : policy: local compte par noeud Kong, pas globalement. Avec 3 réplicas, un client peut envoyer 3× le quota. Toujours utiliser policy: redis dès qu'il y a plus d'une instance.

Admin API exposée publiquement : KONG_ADMIN_LISTEN: 0.0.0.0:8001 est une faille critique. Restreindre à 127.0.0.1 ou un réseau interne, puis protéger avec ip-restriction ou mTLS.

**Plugin cors avec origins: ["*"] et credentials: true** : combinaison invalide côté navigateur (CORS spec). Toujours lister les origines explicitement si credentials: true.

strip_path mal configuré : si strip_path: false et que le service upstream ne s'attend pas au préfixe /api/payments, toutes les requêtes retournent 404. Valider avec curl -v.

Order des plugins : Kong applique les plugins dans l'ordre de priorité interne (pas l'ordre du YAML). Vérifier avec GET /plugins?size=100 pour confirmer que jwt s'exécute avant acl.

Timeouts trop courts sur des endpoints batch : read_timeout: 60000 (60 s) par défaut. Pour des imports lourds, augmenter explicitement par route avec config.read_timeout dans le plugin request-termination ou via un service dédié.

Rechargement DB-less sans validation préalable : POST /config sans kong config parse peut corrompre l'état en mémoire si le YAML est invalide. Toujours valider d'abord.

Bonnes pratiques 2026

• Fixer la version image (kong:3.9, pas kong:latest) et la mettre à jour via une PR revue.
• Stocker kong.yml en Git, appliquer via CI/CD (kong config parse en étape de lint, POST /config en deploy).
• Pour Kubernetes, utiliser le Kong Ingress Controller (KIC 3.x) avec CRDs KongPlugin, KongIngress — évite de gérer le kong.yml manuellement.
• Activer HTTPS côté proxy (8443) avec TLS terminé sur Kong ; ne jamais laisser le trafic entre Kong et le client en HTTP en production.
• Séparer les plugins de sécurité (auth, rate limit) des plugins d'observabilité (logs, metrics) dans la configuration pour faciliter l'audit.
• Tester les règles de routing avec curl -v --resolve avant déploiement pour éviter les surprises strip_path / preserve_host.