OpenSkillIndex← back to search
claude-code

Agent-almanac configure-api-gateway

install
source · Clone the upstream repo
git clone https://github.com/pjt222/agent-almanac
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/de/skills/configure-api-gateway" ~/.claude/skills/pjt222-agent-almanac-configure-api-gateway-ca99ef && rm -rf "$T"
manifest: i18n/de/skills/configure-api-gateway/SKILL.md
source content

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