pjt222/configure-api-gateway

API-Gateway konfigurieren

API-Gateway fuer zentralisiertes API-Traffic-Management und Richtliniendurchsetzung deployen und konfigurieren.

Wann verwenden

• Mehrere Backend-Services benoetigen einheitlichen API-Endpunkt mit konsistenten Richtlinien
• Zentrale Authentifizierung/Autorisierung fuer API-Zugriff erforderlich
• Rate-Limiting und Kontingent-Management ueber APIs hinweg benoetigt
• Anfragen/Antworten transformieren ohne Backend-Services zu aendern
• API-Versionierung und Deprecation-Strategien implementieren
• Detaillierte API-Analysen und Monitoring benoetigt
• Service-Discovery und Load-Balancing fuer Microservices erforderlich

Eingaben

• Erforderlich: Kubernetes-Cluster oder Docker-Umgebung
• Erforderlich: Auswahl des API-Gateways (Kong oder Traefik)
• Erforderlich: Backend-Service-Endpunkte als Proxy-Ziele
• Optional: Authentifizierungs-Provider (OAuth2, OIDC, API-Keys)
• Optional: Rate-Limiting-Anforderungen (Anfragen pro Minute/Stunde)
• Optional: Benutzerdefinierte Middleware- oder Plugin-Konfigurationen
• Optional: TLS-Zertifikate fuer HTTPS-Endpunkte

Vorgehensweise

Siehe Erweiterte Beispiele fuer vollstaendige Konfigurationsdateien und Vorlagen.

Schritt 1: API-Gateway installieren

API-Gateway mit Datenbank (Kong) oder dateibasierter Konfiguration (Traefik) deployen.

Fuer Kong mit PostgreSQL:

# kong-deployment.yaml (excerpt - see EXAMPLES.md for complete file)
apiVersion: v1
kind: Namespace
metadata:
  name: kong
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: kong
  namespace: kong
spec:
  replicas: 2
  # ... (PostgreSQL, migrations, services - see EXAMPLES.md)

Fuer Traefik:

# traefik-deployment.yaml (excerpt - see EXAMPLES.md for complete file)
apiVersion: v1
kind: Namespace
metadata:
  name: traefik
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: traefik
  namespace: traefik
spec:
  replicas: 2
  # ... (RBAC, ConfigMap, services - see EXAMPLES.md)

Vollstaendige Deployment-Manifeste unter EXAMPLES.md verfuegbar.

Deployen:

kubectl apply -f kong-deployment.yaml  # OR traefik-deployment.yaml
kubectl wait --for=condition=ready pod -l app=kong -n kong --timeout=300s
kubectl get svc -n kong kong-proxy  # Get load balancer IP

Erwartet: Gateway-Pods laufen mit 2 Replikas. LoadBalancer-Service hat externe IP zugewiesen. Admin-API erreichbar (Kong: Port 8001, Traefik: Dashboard-Port 8080). Health-Checks bestehen.

Bei Fehler:

• Pod-Logs pruefen: kubectl logs -n kong -l app=kong
• Datenbankverbindung pruefen (Kong): kubectl logs -n kong kong-migrations-<hash>
• Service-Account-Berechtigungen pruefen (Traefik): kubectl get clusterrolebinding traefik -o yaml
• Pruefen ob Ports bereits belegt: kubectl get svc --all-namespaces | grep 8000

Schritt 2: Backend-Services und Routen konfigurieren

Upstream-Services definieren und Routen zur API-Exponierung erstellen.

Fuer Kong (mit decK fuer deklarative Konfiguration):

# Install decK CLI
curl -sL https://github.com/Kong/deck/releases/download/v1.28.0/deck_1.28.0_linux_amd64.tar.gz | tar -xz
sudo mv deck /usr/local/bin/

# Create kong.yaml with services, routes, upstreams
# (see EXAMPLES.md for complete configuration)
deck sync --kong-addr http://localhost:8001 -s kong.yaml
curl -i http://localhost:8001/routes  # Verify routes

Fuer Traefik (mit IngressRoute CRD):

# traefik-routes.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: user-api-route
spec:
  entryPoints: [websecure]
  routes:
  - match: Host(`api.example.com`) && PathPrefix(`/api/users`)
    # ... (see EXAMPLES.md for full configuration)

Routen anwenden:

kubectl apply -f traefik-routes.yaml
curl -H "Host: api.example.com" https://GATEWAY_IP/api/users

Vollstaendige Routing-Konfigurationen unter EXAMPLES.md verfuegbar.

Erwartet: Routen leiten Traffic korrekt an Backend-Services weiter. Gewichtetes Routing verteilt Traffic gemaess Konfiguration. Health-Checks ueberwachen Backend-Service-Gesundheit.

Bei Fehler:

• Pruefen, ob Backend-Services laufen: kubectl get svc -n default
• DNS-Aufloesung pruefen: kubectl run test --rm -it --image=busybox -- nslookup user-service.default.svc.cluster.local
• Gateway-Logs pruefen: kubectl logs -n kong -l app=kong --tail=50
• Konfiguration validieren: deck validate -s kong.yaml

Schritt 3: Authentifizierung und Autorisierung implementieren

Authentifizierungs-Plugins/-Middleware fuer API-Sicherheit konfigurieren.

Fuer Kong (API-Key- und JWT-Authentifizierung):

# kong-auth-config.yaml (excerpt)
consumers:
- username: mobile-app
  custom_id: app-001

keyauth_credentials:
- consumer: mobile-app
  key: mobile-secret-key-123

plugins:
- name: key-auth
  service: user-api
  # ... (see EXAMPLES.md for full configuration)

deck sync --kong-addr http://localhost:8001 -s kong-auth-config.yaml
curl -i -H "apikey: mobile-secret-key-123" http://GATEWAY_IP/api/users

Fuer Traefik (BasicAuth und ForwardAuth Middleware):

# traefik-auth-middleware.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: basic-auth-middleware
spec:
  basicAuth:
    secret: basic-auth
    removeHeader: true
# ... (see EXAMPLES.md for OAuth2, rate limiting)

kubectl apply -f traefik-auth-middleware.yaml
curl -u user1:password https://GATEWAY_IP/api/protected

Vollstaendige Authentifizierungs-Konfigurationen unter EXAMPLES.md verfuegbar.

Erwartet: Nicht authentifizierte Anfragen geben 401 zurueck. Gueltige Credentials erlauben Zugriff. Rate-Limiting gibt 429 nach Ueberschreiten des Schwellenwerts zurueck. JWT-Tokens werden korrekt validiert. ACL setzt Gruppenberechtigungen durch.

Bei Fehler:

• Consumer-Erstellung pruefen: curl http://localhost:8001/consumers
• Plugin aktiviert pruefen: curl http://localhost:8001/plugins | jq .
• Mit Verbose testen: curl -v fuer Antwort-Header pruefen
• JWT validieren: jwt.io zum Dekodieren des Tokens verwenden

Schritt 4: Anfrage-/Antwort-Transformation konfigurieren

Middleware zum Transformieren von Anfragen und Antworten hinzufuegen.

Fuer Kong:

# kong-transformations.yaml (excerpt)
plugins:
- name: request-transformer
  service: user-api
  config:
    add:
      headers: [X-Gateway-Version:1.0, X-Request-ID:$(uuid)]
    remove:
      headers: [X-Internal-Token]
- name: correlation-id
  # ... (see EXAMPLES.md for full configuration)

deck sync --kong-addr http://localhost:8001 -s kong-transformations.yaml

Fuer Traefik:

# traefik-transformations.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: add-headers
spec:
  headers:
    customRequestHeaders:
      X-Gateway-Version: "1.0"
    # ... (see EXAMPLES.md for circuit breaker, retry, chain)

kubectl apply -f traefik-transformations.yaml
curl -v https://GATEWAY_IP/api/users | grep X-Gateway

Vollstaendige Transformations-Konfigurationen unter EXAMPLES.md verfuegbar.

Erwartet: Anfrage-Header werden wie konfiguriert hinzugefuegt/entfernt. Antwort-Header enthalten Gateway-Metadaten. Grosse Anfragen werden mit 413 abgelehnt. Circuit-Breaker loest bei wiederholten Fehlern aus. Retries erfolgen bei voruebertgehenden Fehlern.

Bei Fehler:

• Middleware-Reihenfolge in der Kette pruefen
• Auf Header-Konflikte mit Backend-Services pruefen
• Transformationen einzeln testen, bevor sie verknuepft werden
• Logs auf Transformations-Fehler pruefen

Schritt 5: Monitoring und Analysen aktivieren

Metriken, Logging und Dashboards fuer API-Sichtbarkeit konfigurieren.

Kong-Monitoring einrichten:

# kong-monitoring.yaml (excerpt)
plugins:
- name: prometheus
  config:
    per_consumer: true
- name: http-log
  service: user-api
  # ... (see EXAMPLES.md for Datadog, file-log configuration)

deck sync --kong-addr http://localhost:8001 -s kong-monitoring.yaml

# Deploy ServiceMonitor (see EXAMPLES.md)
kubectl apply -f kong-servicemonitor.yaml
curl http://localhost:8100/metrics

Traefik-Monitoring (integriert):

# ServiceMonitor (excerpt - see EXAMPLES.md for Grafana dashboard)
apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: traefik-metrics
spec:
  endpoints:
  - port: metrics
    path: /metrics
    interval: 30s

kubectl port-forward -n traefik svc/traefik-dashboard 8080:8080
# Open http://localhost:8080/dashboard/

Vollstaendige Monitoring-Konfigurationen unter EXAMPLES.md verfuegbar.

Erwartet: Prometheus scraped Gateway-Metriken erfolgreich. Dashboards zeigen Anfrage-Raten, Latenz-Perzentile, Fehlerraten. Logs werden an Aggregationssystem weitergeleitet. Metriken segmentiert nach Service, Route und Consumer.

Bei Fehler:

• ServiceMonitor pruefen: kubectl get servicemonitor -A
• Prometheus-Targets in UI pruefen
• Sicherstellen, dass Metriken-Port erreichbar: kubectl port-forward -n kong svc/kong-metrics 8100:8100
• Erreichbarkeit des Log-Endpunkts validieren

Schritt 6: API-Versionierung und Deprecation implementieren

Versions-Management und schrittweise API-Deprecation konfigurieren.

Kong-Versionierungsstrategie:

# kong-versioning.yaml (excerpt)
services:
- name: user-api-v1
  url: http://user-service-v1.default.svc.cluster.local:8080
  routes:
  - name: user-v1-route
    paths: [/api/v1/users]
  plugins:
  - name: response-transformer
    config:
      add:
        headers:
        - X-Deprecation-Notice:"API v1 deprecated on 2024-12-31"
        - Sunset:"Wed, 31 Dec 2024 23:59:59 GMT"
# ... (see EXAMPLES.md for v2, default routing, rate limits)

Traefik-Versionierung:

# traefik-versioning.yaml (excerpt)
apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: v1-deprecation-headers
spec:
  headers:
    customResponseHeaders:
      X-Deprecation-Notice: "API v1 deprecated on 2024-12-31"
# ... (see EXAMPLES.md for complete IngressRoutes)

Versionierung testen:

curl -i https://api.example.com/api/v1/users  # Deprecated
curl -i https://api.example.com/api/v2/users  # Current
curl -i https://api.example.com/api/users     # Routes to v2

Vollstaendige Versionierungs-Konfigurationen unter EXAMPLES.md verfuegbar.

Erwartet: Verschiedene Versionen leiten an entsprechende Backend-Services weiter. Deprecation-Header in v1-Antworten vorhanden. Rate-Limits strenger fuer veraltete Versionen. Standard-Pfad leitet zur neuesten Version. Metriken nach API-Version segmentiert.

Bei Fehler:

• Pfad-Praezedenz/-Prioritaet pruefen (hoehere Prioritaet = zuerst ausgewertet)
• Auf ueberlappende Pfad-Muster pruefen
• Jede Versions-Route unabhaengig testen
• Routing-Logs auf Pfad-Matching pruefen
• Sicherstellen, dass Backend-Services fuer jede Version laufen

Validierung

• [ ] API-Gateway-Pods laufen mit mehreren Replikas fuer Hochverfuegbarkeit
• [ ] LoadBalancer-Service hat externe IP zugewiesen
• [ ] Routen leiten Traffic korrekt an Backend-Services weiter
• [ ] Authentifizierung/Autorisierung setzt Zugangskontrolle durch (401/403-Antworten)
• [ ] Rate-Limiting gibt 429 nach Ueberschreiten des Kontingents zurueck
• [ ] Anfrage-/Antwort-Transformation fuegt/entfernt Header korrekt
• [ ] Circuit-Breaker loest bei wiederholten Backend-Fehlern aus
• [ ] Metriken exponiert und von Prometheus gescraped
• [ ] Dashboards zeigen Anfrage-Raten, Latenz, Fehler
• [ ] API-Versionierung leitet Anfragen an korrekte Backend-Versionen
• [ ] Deprecation-Header in aelteren API-Versionen vorhanden
• [ ] Health-Checks ueberwachen Backend-Service-Verfuegbarkeit

Haeufige Stolperfallen

• Datenbankabhaengigkeit (Kong): Kong mit Datenbank benoetigt PostgreSQL/Cassandra. DB-loser Modus verfuegbar, schraenkt aber einige Funktionen ein. DB-Modus fuer Produktion mit mehreren Gateway-Instanzen verwenden.

• Pfad-Matching-Reihenfolge: Routen/IngressRoutes werden in bestimmter Reihenfolge ausgewertet. Spezifischere Pfade sollten hoehere Prioritaet haben. Ueberlappende Pfade verursachen unvorhersehbares Routing.

• Authentifizierungs-Bypass: Sicherstellen, dass Authentifizierungs-Plugins auf alle Routen angewendet werden. Leicht, Route ohne Auth hinzuzufuegen. Standard-Plugins auf Service-Ebene verwenden, dann pro Route ueberschreiben.

• Rate-Limit-Umfang: Rate-Limiting policy: local zaehlt pro Gateway-Pod. Fuer konsistente Limits ueber Replikas zentralisierte Richtlinie (Redis) oder Sticky Sessions verwenden.

• CORS-Konfiguration: API-Gateway sollte CORS behandeln, nicht einzelne Services. CORS-Plugin/Middleware frueh hinzufuegen, um Browser-Preflight-Fehler zu vermeiden.

• SSL/TLS-Terminierung: Gateway terminiert normalerweise SSL. Sicherstellen, dass Zertifikate gueltig sind und automatische Erneuerung konfiguriert ist. cert-manager fuer Kubernetes-Zertifikatsverwaltung verwenden.

• Upstream-Health-Checks: Aktive Health-Checks konfigurieren, um Backend-Ausfaelle schnell zu erkennen. Passive Checks verlaessen sich auf echten Traffic und koennen langsamer reagieren.

• Plugin-/Middleware-Ausfuehrungsreihenfolge: Reihenfolge ist wichtig. Authentifizierung vor Rate-Limiting (vermeidet verschwendete Rate-Limit-Slots fuer ungueltige Anfragen). Transformation vor Logging (transformierte Werte protokollieren).

• Ressourcenlimits: Gateway-Pods koennen unter Last erhebliche CPU verbrauchen. Geeignete Ressourcenanforderungen/-limits setzen. CPU-Drosselung in Produktion ueberwachen.

• Migrationsstrategie: Nicht alle Plugins auf einmal aktivieren. Schrittweise einfuehren: Routing → Authentifizierung → Rate-Limiting → Transformationen → erweiterte Funktionen.

Verwandte Skills

• configure-ingress-networking - Ingress-Controller-Setup ergaenzt API-Gateway
• setup-service-mesh - Service-Mesh bietet komplementaeres Ost-West-Traffic-Management
• manage-kubernetes-secrets - Zertifikats- und Credential-Management fuer Gateway
• setup-prometheus-monitoring - Monitoring-Integration fuer Gateway-Metriken
• enforce-policy-as-code - Richtliniendurchsetzung ergaenzt Gateway-Autorisierung