Wie Sie ein AI Gateway auf Kubernetes fuer Inferenz-Workloads einrichten

AI-Traffic ist nicht einfach “normaler API-Traffic mit groesserem JSON.” Inferenz-Anfragen sind oft teurer, latenzempfindlicher, laengerlebig und variabler als Standard-Web-Traffic. Streaming-Antworten halten Verbindungen offen. Tool-aufrufende Agenten faechen in Bursts kleinerer Anfragen aus. Batch-Inferenz kann eher wie Hintergrund-Durchsatz aussehen als wie interaktive Latenz. Und in vielen Umgebungen wird das Gateway auch zum Ort, an dem Modellzugriff, Kostenkontrolle und Tenant-Grenzen wichtig werden.

Deshalb sollten sich Kubernetes-Plattformteams jetzt damit beschaeftigen. Die Kubernetes AI Gateway Working Group wurde speziell gegruendet, um Standards und Best Practices fuer Netzwerkinfrastruktur zu definieren, die AI-Workloads unterstuetzt, und das offizielle Gateway API Inference Extension-Projekt arbeitet bereits an modellbewusstem Routing, Endpoint-Picking und anderen inferenzspezifischen Mustern auf Basis der Gateway API. Mit anderen Worten: Dies ist nicht mehr nur eine anbieterspezifische Produktkategorie. Es wird zu einem Kubernetes-Plattform-Thema.

Dieses Tutorial zeigt, wie man ein praktisches v1 AI Gateway auf Kubernetes baut, ohne so zu tun, als waeren die Standards reifer als sie sind. Sie werden eine grundlegende Gateway-API-Einstiegsschicht aufsetzen, Anfragen an Inferenz-Services routen, Modellversions- und Tenant-bewusste Muster hinzufuegen, Zuverlaessigkeitskontrollen anpassen, Observability hinzufuegen, das Design absichern und es dann unter realistischer Last testen. Das Ziel ist nicht, am ersten Tag das fortschrittlichste Inferenz-Gateway zu bauen. Das Ziel ist, eine saubere Plattform-Basislinie zu schaffen, die Sie sicher weiterentwickeln koennen. Fuer einen breiteren Kontext, wie sich Kubernetes-Networking an AI-Workloads anpasst, siehe Kubernetes AI Workloads and Networking.

Schritt 1: Identifizieren Sie Ihre AI-Traffic-Typen

Bevor Sie Routing-Regeln schreiben, entscheiden Sie, welche Arten von Inferenz-Traffic Sie tatsaechlich haben. Kubernetes hat jetzt eine offizielle AI-Gateway-Initiative, weil AI-Workloads Traffic-Muster einfuehren, die unterschiedliches Netzwerkverhalten erfordern, einschliesslich tokenbewusstem Rate-Limiting, Payload-Inspektion, AI-spezifischem Routing und AI-spezifischen Protokollen. Das Inference-Extension-Projekt geht noch weiter und fuehrt Konzepte wie modellbewusstes Routing, Serving-Prioritaeten, Endpoint-Picking und latenzbewusstes Scheduling basierend auf Modell-Server-Metriken ein.

Klassifizieren Sie interaktive Inferenz

Interaktive Inferenz ist das, was die meisten Teams zuerst meinen: Chat-Completions, Zusammenfassungen, Embeddings on Demand, Assistenten-UX und aehnliche benutzerorientierte Aufrufe. Diese Anfragen sind normalerweise empfindlich gegenueber:

• End-to-End-Latenz
• Zeit bis zum ersten Token
• Streaming-Kontinuitaet
• Modellauswahl
• Pro-Tenant-Quoten

Wenn Sie interaktiven Traffic haben, sollte Ihr Gateway fuer vorhersagbares Antwortverhalten und kontrolliertes Rollout optimiert sein, nicht nur fuer maximalen Durchsatz.

Klassifizieren Sie Batch-Inferenz

Batch-Inferenz sieht normalerweise anders aus:

• groessere Bursts
• weniger Empfindlichkeit gegenueber First-Token-Latenz
• mehr Toleranz fuer Queuing
• mehr Fokus auf Durchsatz und Fairness
• geplante oder asynchrone Ausfuehrungsmuster

Sie wollen nicht Ihr gesamtes Gateway um interaktiven Chat herum optimieren, wenn die Haelfte Ihrer Last Offline-Embeddings oder naechtliche Anreicherungsjobs sind.

Klassifizieren Sie Tool-aufrufende Agenten

Tool-aufrufende Agenten erzeugen oft Traffic, der leicht unterschaetzt wird:

• viele kleine Aufrufe
• Bursts nach Planungsphasen
• Retries vom Aufrufer, wenn ein Tool-Schritt fehlschlaegt
• gemischte Workloads ueber mehrere Modelle oder Endpunkte

Das ist wichtig, weil das Gateway engere Quoten, Idempotenz-Bewusstsein oder staerkere Observability pro Route und pro Tenant benoetigen koennte.

Klassifizieren Sie Streaming-Antworten

Streaming-Inferenz ist der Bereich, in dem Teams am schnellsten in Schwierigkeiten geraten. Gateway API hat jetzt Standard-Unterstuetzung fuer Route-Timeouts, aber Retry-Unterstuetzung befindet sich noch in aktiver Entwicklung und ist besonders nuanciert bei Streaming- oder bidirektionalen Mustern. Behandeln Sie langlebige Streams als eigene Klasse, nicht einfach als “dieselbe Route mit einem anderen Body.”

Erstellen Sie ein einfaches Traffic-Klassifizierungsdokument, bevor Sie weitermachen.

File: traffic-profile.yaml

interactive_inference:
  examples:
    - chat-completions
    - real-time-summarization
  latency_sensitive: true
  streaming: true
  retry_friendly: false

batch_inference:
  examples:
    - offline-embeddings
    - nightly-document-labeling
  latency_sensitive: false
  streaming: false
  retry_friendly: true

tool_calling_agents:
  examples:
    - planner-executor-agents
    - retrieval-agents
  latency_sensitive: mixed
  streaming: mixed
  retry_friendly: mixed

streaming_responses:
  examples:
    - server-sent-events
    - token-streaming-chat
  latency_sensitive: true
  streaming: true
  retry_friendly: false

Sie sollten nun ein Traffic-Profil haben, das Ihnen sagt, welche Pfade niedrige Latenz benoetigen, welche Queuing tolerieren koennen und welche Retries komplett vermeiden sollten.

Schritt 2: Entscheiden Sie, was das Gateway tun soll

Ein Gateway wird unuebersichtlich, wenn es zufaellig Verantwortlichkeiten uebernimmt. Die Kubernetes AI Gateway-Initiative rahmt AI Gateways explizit als Infrastruktur ein, die Policy, Zugriffskontrolle, Payload-Inspektion, tokenbewusstes Limiting und AI-spezifisches Routing durchsetzen kann. Das bedeutet nicht, dass Ihre erste Version all das auf einmal tun sollte. Es bedeutet, dass Sie den Umfang von vornherein festlegen sollten.

Beginnen Sie mit einem kleinen Verantwortungsbereich

Fuer eine erste Version sollte Ihr AI Gateway normalerweise diese Dinge tun:

• einen oder mehrere stabile Einstiegspunkte exponieren
• Anfragen an den richtigen Inferenz-Service routen
• Tenants oder Umgebungen isolieren
• grundlegende Auth- und Admission-Grenzen durchsetzen
• zuverlaessige Logs und Metriken ausgeben
• sichere Modell-Rollouts unterstuetzen

Was es in v1 normalerweise nicht tun sollte:

• volle semantische Prompt-Inspektion inline durchfuehren
• Ihr einziges Quota-System werden
• jedes Provider-Fallback-Muster implementieren
• saemtliches Modell-Server-Verhalten vor dem Application-Team verstecken

Definieren Sie die Routing-Dimensionen

Die meisten Teams benoetigen eine oder mehrere davon:

• Routing nach Modellfamilie wie Chat versus Embeddings
• Routing nach Modellversion wie v1 versus v2
• Routing nach Tenant ueber Hostnamen, Pfade oder Header
• Routing nach Traffic-Klasse wie interaktiv versus Batch

Schreiben Sie die Policy auf. Lassen Sie sie nicht in Helm-Werten oder Controller-Defaults versteckt.

File: ai-gateway-responsibilities.yaml

entrypoints:
  - tenant-hostnames
  - shared-api-domain

routing_dimensions:
  - route_by_path
  - route_by_model_version
  - route_by_tenant

required_controls:
  - authn
  - authz
  - request_logging
  - per_route_timeouts
  - rollout_support

deferred_for_v2:
  - semantic_payload_inspection
  - provider_failover
  - token_based_rate_limiting
  - body_based_model_routing

Entscheiden Sie, ob das Gateway oder ein Router-Service die Modellauswahl uebernimmt

Dies ist eine der wichtigsten Designentscheidungen.

Wenn Ihre Clients unterschiedliche Endpunkte wie /v1/chat/completions und /v1/embeddings aufrufen, reicht Standard-HTTPRoute fuer ein gutes v1-Design aus. Wenn Ihre Clients eine OpenAI-kompatible Anfrage senden, bei der der Modellname nur im Request-Body steht, reicht Standard Gateway API allein nicht fuer modellbewusstes Routing. Genau deshalb fuehrt das Inference-Extension-Projekt Body-basiertes Routing und Endpoint-Picking-Muster ein.

Fuer v1 waehlen Sie eine dieser Optionen:

• Einfaches Pfad- oder Hostname-Routing, wenn Ihre API-Oberflaeche Workloads bereits sauber trennt
• Ein schlanker interner Router-Service, wenn der Modellname nur im Body existiert und Sie die externe API stabil halten wollen
• Eine inferenzbewusste Erweiterung spaeter, wenn Body-bewusstes Routing die Komplexitaet wert wird

Sie sollten nun wissen, was Ihr Gateway besitzt, was es nicht besitzt und ob die Modellauswahl in Standard-Gateway-Regeln, in einem Router-Service oder in einer fortgeschritteneren inferenzbewussten Schicht spaeter stattfindet.

Schritt 3: Deployen Sie eine grundlegende Gateway-Schicht

Der sauberste Ausgangspunkt ist ein gemeinsames Gateway in einem Plattform-Namespace, Modell-Services in einem Model-Serving-Namespace und Tenant-Routen in Tenant-Namespaces. Gateway API ist fuer diese Art der Trennung konzipiert, und Cross-Namespace-Routing ist ein erstklassiges Muster. Wenn eine Route auf ein Backend in einem anderen Namespace zeigt, muss der Ziel-Namespace dies explizit mit einem ReferenceGrant erlauben.

Erstellen Sie Namespaces und Labels

File: namespaces.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: ai-gateway
---
apiVersion: v1
kind: Namespace
metadata:
  name: ai-models
---
apiVersion: v1
kind: Namespace
metadata:
  name: tenant-a
  labels:
    ai-routes: "enabled"

Wenden Sie sie an:

kubectl apply -f namespaces.yaml

Erstellen Sie das gemeinsame Gateway

Dieses Beispiel setzt voraus, dass Ihr Controller bereits eine GatewayClass installiert hat. Ersetzen Sie your-gateway-class durch den echten Klassennamen aus Ihrer Umgebung.

File: gateway.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ai-shared-gateway
  namespace: ai-gateway
spec:
  gatewayClassName: your-gateway-class
  listeners:
    - name: https
      protocol: HTTPS
      port: 443
      hostname: "*.ai.example.com"
      tls:
        mode: Terminate
        certificateRefs:
          - name: ai-example-com-tls
      allowedRoutes:
        namespaces:
          from: Selector
          selector:
            matchLabels:
              ai-routes: "enabled"

Wenden Sie es an:

kubectl apply -f gateway.yaml
kubectl get gateway -n ai-gateway

Exponieren Sie Ihre Inferenz-Services

Dieses Tutorial setzt voraus, dass Sie bereits Model-Serving-Deployments laufen haben. Erstellen Sie stabile Services dafuer.

File: model-services.yaml

apiVersion: v1
kind: Service
metadata:
  name: chat-llama3-8b-v1
  namespace: ai-models
spec:
  selector:
    app: chat-llama3-8b-v1
  ports:
    - name: http
      port: 8000
      targetPort: 8000
---
apiVersion: v1
kind: Service
metadata:
  name: embed-bge-small-v1
  namespace: ai-models
spec:
  selector:
    app: embed-bge-small-v1
  ports:
    - name: http
      port: 8000
      targetPort: 8000

Wenden Sie es an:

kubectl apply -f model-services.yaml

Erlauben Sie Cross-Namespace-Backend-Referenzen

Da die HTTPRoute in tenant-a leben wird und die Backends in ai-models, benoetigen Sie einen ReferenceGrant im Backend-Namespace.

File: referencegrant.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: ReferenceGrant
metadata:
  name: allow-tenant-a-routes
  namespace: ai-models
spec:
  from:
    - group: gateway.networking.k8s.io
      kind: HTTPRoute
      namespace: tenant-a
  to:
    - group: ""
      kind: Service

Wenden Sie es an:

kubectl apply -f referencegrant.yaml

Erstellen Sie die initiale HTTPRoute

File: tenant-a-routes.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tenant-a-inference
  namespace: tenant-a
spec:
  parentRefs:
    - name: ai-shared-gateway
      namespace: ai-gateway
      sectionName: https
  hostnames:
    - "tenant-a.ai.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1/chat/completions
      backendRefs:
        - name: chat-llama3-8b-v1
          namespace: ai-models
          port: 8000
    - matches:
        - path:
            type: PathPrefix
            value: /v1/embeddings
      backendRefs:
        - name: embed-bge-small-v1
          namespace: ai-models
          port: 8000

Wenden Sie es an und verifizieren Sie:

kubectl apply -f tenant-a-routes.yaml
kubectl get httproute -n tenant-a
kubectl describe httproute tenant-a-inference -n tenant-a

Sie sollten nun ein grundlegendes gemeinsames AI Gateway, zwei Model-Serving-Services und eine Tenant-Route haben, die Chat- und Embeddings-Traffic durch die Gateway API weiterleitet.

Schritt 4: Fuegen Sie AI-bewusstes Routing hinzu

Nachdem die Basislinie funktioniert, fuegen Sie die Arten von Routing hinzu, die speziell fuer Inferenz wichtig sind. Das offizielle Inference-Extension-Projekt konzentriert sich auf modellbewusstes Routing, Serving-Prioritaet, Rollouts und Endpunktauswahl basierend auf Modell-Server-Metriken wie Cache-Zustand und Queue-Tiefe. Das ist die langfristige Richtung. Fuer v1 halten Sie es einfacher: Verwenden Sie Gateway API zuerst fuer Modellversions-Rollout und Tenant-Grenzen und fuehren Sie Body-basiertes Routing oder Endpoint-Picking nur ein, wenn Sie einen klaren Bedarf haben.

Fuegen Sie Modellversions-Canary-Routing hinzu

Gateway API unterstuetzt gewichtetes Traffic-Splitting durch backendRefs, was es gut geeignet fuer Modell-Rollouts macht.

File: tenant-a-chat-canary.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tenant-a-chat-canary
  namespace: tenant-a
spec:
  parentRefs:
    - name: ai-shared-gateway
      namespace: ai-gateway
      sectionName: https
  hostnames:
    - "tenant-a.ai.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1/chat/completions
      backendRefs:
        - name: chat-llama3-8b-v1
          namespace: ai-models
          port: 8000
          weight: 90
        - name: chat-llama3-8b-v2
          namespace: ai-models
          port: 8000
          weight: 10

Dies ist der sauberste Weg, Modell-Rollouts durchzufuehren, wenn die externe API gleich bleibt und sich nur die Serving-Implementierung aendert.

Fuegen Sie Tenant-Isolation durch Hostname oder Route-Ownership hinzu

Die Kubernetes Multi-Tenancy-Empfehlungen empfehlen Namespace-Grenzen, RBAC, Quotas und Network Policies als grundlegende Kontrollen fuer geteilte Cluster. In der Praxis ist das einfachste AI-Gateway-Isolationsmodell:

• ein gemeinsames Gateway
• ein routenbesitzender Namespace pro Tenant oder App-Team
• ein Model-Serving-Namespace oder Pro-Tenant-Modell-Namespaces bei Bedarf
• expliziter ReferenceGrant, wo Cross-Namespace-Zugriff erlaubt ist

Das haelt die Tenant-Routing-Ownership getrennt von plattformeigenen Einstiegspunkten.

Halten Sie Fallback in v1 einfach

Echtes Inferenz-Fallback ist subtiler als normales HTTP-Failover. Moeglicherweise moechten Sie von einer Modellversion auf eine andere, von einem Pool auf einen anderen oder von selbstgehostetem Inferenz auf einen externen Provider failoversn. Die aktiven Egress-Vorschlaege der AI Gateway Working Group zielen explizit auf externe AI-Services, Failover, Compliance-Routing und sichere Token-Injektion ab, was Ihnen sagt, dass dies noch ein sich entwickelnder Standardbereich ist.

Fuer v1 verwenden Sie eine dieser Optionen:

• einen dedizierten Router-Service hinter Ihrem Gateway fuer komplexe Fallback-Logik
• eine modellspezifische Route mit einem kontrollierten Canary-Split
• eine implementierungsspezifische Inference-Extension, wenn Sie sich bereits fuer diesen Stack entschieden haben

Ein sauberes Muster ist es, die oeffentliche Route stabil zu halten und komplexe Fallback-Logik an einen internen Router-Service zu senden:

File: tenant-a-chat-router.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tenant-a-chat-router
  namespace: tenant-a
spec:
  parentRefs:
    - name: ai-shared-gateway
      namespace: ai-gateway
      sectionName: https
  hostnames:
    - "tenant-a.ai.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1/chat/completions
      backendRefs:
        - name: llm-router
          namespace: tenant-a
          port: 8080

Dieser Router kann policybewusste Fallback-Entscheidungen treffen, ohne jeden Inferenz-Aspekt in Gateway-YAML zu zwingen.

Sie sollten nun eine Moeglichkeit haben, sichere Modellversions-Rollouts durchzufuehren, ein klares Tenant-Isolationsmuster und eine realistische v1-Haltung zur Fallback-Logik.

Schritt 5: Fuegen Sie Zuverlaessigkeitskontrollen hinzu

Inferenz-Traffic versagt anders als eine normale CRUD-API. Einige Anfragen sind teuer und langlebig. Einige Streams sollten nie automatisch wiederholt werden. Einige Modell-Server reihen intern ein, bevor sie antworten. Das bedeutet, dass Zuverlaessigkeit eine Mischung aus Gateway-Einstellungen und Modell-Server-Verhalten ist.

Setzen Sie explizite Route-Timeouts

Gateway API bietet jetzt Standard-Route-Timeout-Felder auf HTTPRoute-Regeln. Verwenden Sie sie. Lassen Sie kritische Inferenz-Pfade nicht komplett bei Controller-Defaults.

File: tenant-a-route-timeouts.yaml

apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: tenant-a-inference-with-timeouts
  namespace: tenant-a
spec:
  parentRefs:
    - name: ai-shared-gateway
      namespace: ai-gateway
      sectionName: https
  hostnames:
    - "tenant-a.ai.example.com"
  rules:
    - matches:
        - path:
            type: PathPrefix
            value: /v1/chat/completions
      timeouts:
        request: 120s
        backendRequest: 115s
      backendRefs:
        - name: chat-llama3-8b-v1
          namespace: ai-models
          port: 8000
    - matches:
        - path:
            type: PathPrefix
            value: /v1/embeddings
      timeouts:
        request: 30s
        backendRequest: 25s
      backendRefs:
        - name: embed-bge-small-v1
          namespace: ai-models
          port: 8000

Diese Zahlen sind Beispiele. Die richtigen Werte haengen von Ihren Modellen und Benutzererwartungen ab. Der wichtige Punkt ist, dass Chat und Embeddings nicht blind dieselbe Timeout-Policy erben sollten.

Seien Sie konservativ mit Retries

Gateway-Retry-Funktionalitaet existiert, aber es ist noch ein Bereich, in dem die Semantik variiert und Streaming besonders heikel ist. Fuer Streaming-Chat verwenden Sie standardmaessig keine automatischen Gateway-Retries, es sei denn, Sie haben das Verhalten explizit Ende-zu-Ende getestet. Fuer nicht-streamende idempotente Anfragen wie einige Embedding-Workloads koennen begrenzte Retries akzeptabel sein, wenn Ihre Implementierung sie unterstuetzt und Ihre Backend-Semantik sicher ist.

Fuegen Sie grundlegende Backend-Zuverlaessigkeit hinzu

Fokussieren Sie sich nicht nur auf das Gateway. Ihre Model-Serving-Workloads benoetigen auch stabiles Disruption-Verhalten.

File: chat-pdb.yaml

apiVersion: policy/v1
kind: PodDisruptionBudget
metadata:
  name: chat-llama3-8b-v1
  namespace: ai-models
spec:
  minAvailable: 1
  selector:
    matchLabels:
      app: chat-llama3-8b-v1

Das loest keine Ueberlastung, aber es schuetzt Sie vor vermeidbaren freiwilligen Unterbrechungen waehrend der Wartung.

Entscheiden Sie, wo Queuing und Backpressure leben

Fuer v1 ist die sicherste Regel:

• Gateway: verbindungs- und routenbasierte Grenzen durchsetzen
• Modell-Server oder Router: Queuing- und Request-Shedding-Entscheidungen uebernehmen
• Autoscaling: auf tatsaechliche Nachfragesignale reagieren, wo moeglich

Wenn Ihr Stack spaeter inferenzbewusste Queue-Sichtbarkeit oder Endpoint-Picking unterstuetzt, koennen Sie sich dorthin weiterentwickeln. Das Inference-Extension-Projekt ist speziell um Endpunktauswahl und Modell-Server-Metriken wie Queue-Laenge und Cache-Zustand aufgebaut, was ein starkes Zeichen dafuer ist, dass generisches L7-Load-Balancing nicht fuer ausgereifte Inferenz-Workloads ausreicht.

Sie sollten nun explizite Timeouts, eine konservative Retry-Haltung und eine klare Trennung zwischen Gateway-Zuverlaessigkeitskontrollen und Modell-Server-Backpressure-Verhalten haben.

Schritt 6: Fuegen Sie Observability hinzu

Ein AI Gateway ohne Observability wird zum Kostenverstaerker und Debugging-Engpass. Mindestens sollten Sie verstehen:

• Anfragevolumen
• Anfrage-Latenz
• Fehlerrate
• Tenant-Verteilung
• Modell-Verteilung
• Streaming versus Nicht-Streaming
• Token- und Kostensignale, wenn verfuegbar

Die offizielle Inference-Extension-Arbeit hebt auch Modell-Server-Metriken, Time-to-First-Token-Ziele und modellbewusste Scheduling-Entscheidungen hervor, was ein gutes Signal dafuer ist, was ausgereifte Observability enthalten muss.

Standardisieren Sie einen Gateway-Log-Vertrag

Selbst wenn sich Ihre genaue Metriken-Pipeline spaeter aendert, definieren Sie jetzt einen strukturierten Log-Vertrag.

File: gateway-log-example.json

{
  "timestamp": "2026-03-10T15:22:11.418Z",
  "request_id": "req_01JPN8XQZ0Y1M0AX3R0D4M9J7E",
  "tenant": "tenant-a",
  "hostname": "tenant-a.ai.example.com",
  "route": "/v1/chat/completions",
  "model_route": "chat-llama3-8b-v1",
  "stream": true,
  "http_status": 200,
  "latency_ms": 1840,
  "ttft_ms": 420,
  "prompt_tokens": 612,
  "completion_tokens": 238,
  "estimated_cost_usd": 0.0194,
  "gateway_backend": "chat-llama3-8b-v1.ai-models.svc.cluster.local:8000"
}

Wenn Sie nicht jedes Feld am ersten Tag bekommen koennen, ist das in Ordnung. Aber Tenant, Route, Backend, Status, Latenz und Stream/Nicht-Stream sollten von Anfang an vorhanden sein.

Erstellen Sie Recording-Regeln fuer eigene Metriken

Wenn Sie eine benutzerdefinierte Router- oder Adapter-Schicht betreiben, exportieren Sie Ihre eigenen Metriken mit stabilen Namen und Labels.

File: prometheus-rules.yaml

apiVersion: monitoring.coreos.com/v1
kind: PrometheusRule
metadata:
  name: ai-gateway-recording-rules
  namespace: ai-gateway
spec:
  groups:
    - name: ai-gateway.rules
      rules:
        - record: ai_gateway:requests_per_second
          expr: sum(rate(ai_gateway_requests_total[5m])) by (tenant, route, model_route)
        - record: ai_gateway:error_rate
          expr: sum(rate(ai_gateway_requests_total{status=~"5.."}[5m])) by (tenant, route, model_route)
        - record: ai_gateway:p95_latency_ms
          expr: histogram_quantile(0.95, sum(rate(ai_gateway_request_duration_ms_bucket[5m])) by (le, tenant, route, model_route))

Dies sind Beispiel-Metriknamen fuer Ihre Adapter- oder Gateway-Telemetrie. Die genaue Quelle kann Ihr Controller, Ihr Router-Service oder beides sein.

Verfolgen Sie Gateway- und Backend-Metriken getrennt

Halten Sie diese Kategorien getrennt:

• Gateway-Request-Latenz
• Backend-Modell-Latenz
• Queue-Tiefe
• Saettigung oder Shedding
• Token-Durchsatz
• Kosten oder geschaetzte Kosten
• Pro-Modell-Erfolgsrate

Wenn Sie alles in eine einzige “AI-Latenz”-Zahl zusammenfuehren, wissen Sie nicht, ob das Problem beim Routing, beim Controller, beim Modell-Server oder beim Upstream-GPU-Druck liegt.

Sie sollten nun einen strukturierten Observability-Plan haben, der Gateway-Verhalten, Modell-Verhalten und Tenant- oder Modell-Level-Kostensichtbarkeit abdeckt.

Schritt 7: Absichern

Ihr AI Gateway ist sowohl eine Netzwerkgrenze als auch eine Policy-Grenze. Das macht es zu einem natuerlichen Ort, um Zugriff, Tenant-Trennung und Audit-Sichtbarkeit durchzusetzen. Kubernetes’ eigene Multi-Tenancy-Leitlinien betonen Namespaces, RBAC, Quotas und Network Policies als Kernbausteine fuer die Isolation von Tenants und die Vermeidung von Noisy-Neighbor- oder Ueberprivilegierungsproblemen in geteilten Clustern.

Isolieren Sie Modell-Services vom Rest des Clusters

Lassen Sie nicht jeden Workload Ihren Model-Serving-Namespace direkt aufrufen. Verwenden Sie eine NetworkPolicy, damit nur der Gateway-Namespace Model-Serving-Pods erreichen kann.

File: model-networkpolicy.yaml

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: only-gateway-to-models
  namespace: ai-models
spec:
  podSelector: {}
  policyTypes:
    - Ingress
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              kubernetes.io/metadata.name: ai-gateway
      ports:
        - protocol: TCP
          port: 8000

Wenden Sie es an:

kubectl apply -f model-networkpolicy.yaml

Platzieren Sie Tenant-Budgets an einem expliziten Ort

Request- oder Token-Quoten sind oft controller-spezifisch oder app-spezifisch, aber Sie sollten trotzdem den Tenant-Ressourcenverbrauch auf Namespace-Ebene isolieren.

File: tenant-a-quota.yaml

apiVersion: v1
kind: ResourceQuota
metadata:
  name: tenant-a-ai-quota
  namespace: tenant-a
spec:
  hard:
    requests.cpu: "20"
    requests.memory: 64Gi
    limits.cpu: "40"
    limits.memory: 128Gi
    pods: "50"

Dies ist keine Anfragen-pro-Minute-Quota. Es ist eine Cluster-Fairness-Grenze. Halten Sie Traffic-Level-Quoten in Ihrer Gateway- oder Router-Schicht, aber vergessen Sie nicht die Cluster-Level-Fairness.

Machen Sie Auth und Audit explizit

Authentifizierung und Autorisierung am Gateway haengen von Ihrer Implementierung ab. Einige Stacks verwenden JWT- oder mTLS-Policy-Attachment. Andere verwenden externe Auth-Services. Ihre minimale sichere Basislinie sollte trotzdem dieselbe sein:

• Aufrufer vor dem Inferenz-Zugriff authentifizieren
• nach Tenant und Route autorisieren
• protokollieren, wer was aufgerufen hat
• vermeiden, rohe sensible Prompt-Inhalte in breite Logs zu schreiben
• genug Audit-Metadaten erfassen, um den Zugriff spaeter zu rekonstruieren

Ein einfacher Audit-Vertrag reicht zum Start.

File: audit-log-example.json

{
  "timestamp": "2026-03-10T15:40:02.112Z",
  "tenant": "tenant-a",
  "subject": "svc:agent-platform",
  "route": "/v1/chat/completions",
  "model_route": "chat-llama3-8b-v1",
  "decision": "allow",
  "request_id": "req_01JPN92C7S49YJ1E0QY6T5G6P3",
  "sensitive_payload_logged": false
}

Schuetzen Sie sensible Prompt- und Antwortdaten

Fuer v1 halten Sie es einfach:

• loggen Sie standardmaessig keine vollstaendigen Prompts
• loggen Sie standardmaessig keine vollstaendigen gestreamten Antworten
• redaktieren Sie Geheimnisse oder offensichtliche Identifikatoren in Middleware, wo moeglich
• reservieren Sie Payload-Inspektion fuer explizite Policy-Anwendungsfaelle

Die AI Gateway Working Group arbeitet aktiv an Payload-Verarbeitungs- und AI-Traffic-Guardrail-Vorschlaegen, was ein starker Indikator dafuer ist, dass Inline-Prompt/Response-Inspektion echtes Plattform-Territorium ist, aber es ist noch ein sich entwickelnder Standardbereich. Ueberbauen Sie es nicht am ersten Tag.

Sie sollten nun Netzwerkisolation um Modell-Services, Namespace-Level-Tenant-Grenzen und einen klaren Ausgangspunkt fuer Auth- und Audit-Kontrollen haben.

Schritt 8: Testen Sie mit einem realistischen Workload

Validieren Sie nun das Design unter Bedingungen, die eher wie Produktion aussehen. AI-Traffic ist selten einheitlich. Sie wollen Burst-Traffic, gemischte Routen, Streaming und mindestens einen Backend-Ausfall.

Senden Sie Burst-Traffic an eine nicht-streamende Route

Erstellen Sie eine Embeddings-Payload.

File: embeddings.json

{
  "input": [
    "hello world",
    "design a safe ai gateway on kubernetes",
    "measure latency, error rate, and cost"
  ],
  "model": "bge-small"
}

Fuehren Sie einen Burst-Test durch:

export GATEWAY_ADDR=http://YOUR_GATEWAY_ADDRESS
hey -n 200 -c 20 \
  -m POST \
  -T application/json \
  -H "Host: tenant-a.ai.example.com" \
  -D embeddings.json \
  ${GATEWAY_ADDR}/v1/embeddings

Dies validiert die Burst-Verarbeitung auf einer Route, die generell sicherer zu wiederholen und einfacher ueber Durchlaeufe hinweg zu vergleichen ist.

Testen Sie Streaming-Verhalten explizit

Erstellen Sie eine Streaming-Anfrage.

File: chat-stream.json

{
  "model": "llama3-8b",
  "stream": true,
  "messages": [
    { "role": "user", "content": "Explain why AI gateways need different timeout and routing rules." }
  ]
}

Fuehren Sie sie aus:

curl -N \
  -H "Host: tenant-a.ai.example.com" \
  -H "Content-Type: application/json" \
  -X POST \
  --data @chat-stream.json \
  ${GATEWAY_ADDR}/v1/chat/completions

Achten Sie auf:

• Zeit bis zum ersten Token
• gleichmaessige Stream-Kontinuitaet
• vorzeitige Verbindungsabbrueche
• Proxy-Pufferungs-Ueberraschungen
• falsches Timeout-Verhalten

Mischen Sie Routen und Traffic-Typen

Eine einfache Shell-Schleife reicht fuer die erste Validierung.

for i in $(seq 1 20); do
  curl -s \
    -H "Host: tenant-a.ai.example.com" \
    -H "Content-Type: application/json" \
    -X POST \
    --data @embeddings.json \
    ${GATEWAY_ADDR}/v1/embeddings > /dev/null &

  curl -s \
    -H "Host: tenant-a.ai.example.com" \
    -H "Content-Type: application/json" \
    -X POST \
    --data @chat-stream.json \
    ${GATEWAY_ADDR}/v1/chat/completions > /dev/null &
done

wait

Dies ist kein perfekter Benchmark. Es reicht aus, um Routen-Fehlanpassungen, Saettigung und schlechtes Standardverhalten aufzudecken.

Injizieren Sie einen Backend-Ausfall

Beweisen Sie nun, dass Ihre Timeouts, Rollout-Splits und Observability sich so verhalten, wie Sie es erwarten.

kubectl -n ai-models scale deployment chat-llama3-8b-v2 --replicas=0
kubectl -n ai-models get pods -w

Senden Sie dann erneut Traffic und beobachten Sie:

• Hat die Canary-Route nur fuer den Canary-Anteil versagt
• Hat das Gateway die richtigen Fehler zurueckgegeben
• Haben Logs das Backend sauber identifiziert
• Haben Streaming-Routen laenger als erwartet gehaengt
• Haben Ihre Metriken Gateway-Fehler von Backend-Fehlern getrennt

Sie sollten nun Belege haben, dass das Gateway unter Burst-Last, gemischtem Routengebrauch und kontrolliertem Ausfall funktioniert, anstatt nur unter Happy-Path-Curl-Tests.

Haeufige Einrichtungsprobleme

Das AI Gateway wie gewoehnliches Ingress behandeln

Symptome:

• ein generisches Timeout fuer alles
• keine Unterscheidung zwischen Chat und Embeddings
• Streaming-Routen brechen unerwartet ab
• Rollout-Verhalten ist zu grob

Ursache: Das Gateway wurde wie ein normales Web-Ingress entworfen, nicht wie eine Inferenz-Einstiegsschicht.

Loesung: Klassifizieren Sie zuerst Traffic-Typen, trennen Sie interaktive und Batch-Routen und behandeln Sie Streaming als eigene Klasse.

Versuchen, nach Modellnamen ohne modellbewusste Schicht zu routen

Symptome:

• Clients senden das Modell im Request-Body
• Gateway-Regeln koennen Backends nicht korrekt auswaehlen
• Teams beginnen, unglueckliche Pfadvarianten hartzucodieren

Ursache: Standard-Gateway-Regeln parsen JSON-Bodies nicht selbststaendig fuer das Routing.

Loesung: Halten Sie v1 pfad- oder hostnamenbasiert, fuegen Sie einen schlanken Router-Service hinzu oder uebernehmen Sie bewusst spaeter eine inferenzbewusste Erweiterung.

Fehlender ReferenceGrant fuer Cross-Namespace-Backends

Symptome:

• HTTPRoute existiert, kann aber Backend-Referenzen nicht aufloesen
• Traffic erreicht nie die Modell-Services

Ursache: Der Route-Namespace kann das gemeinsame Gateway sehen, aber der Backend-Namespace hat nie Cross-Namespace-Referenzzugriff gewaehrt.

Loesung: Fuegen Sie einen ReferenceGrant im Backend-Namespace fuer den spezifischen Quell-Namespace und die Art hinzu.

Retries auf Streaming-Routen aktiviert

Symptome:

• doppelte Teilausgaben
• seltsames Client-Verhalten bei Ausfaellen
• irrefuehrende Erfolgsraten

Ursache: Retry-Logik wurde angewendet, als ob Streaming-Traffic sich wie kurze idempotente Anfragen verhalten wuerde.

Loesung: Deaktivieren oder beschraenken Sie Retries auf Streaming-Routen stark und lassen Sie den Aufrufer Replay bei Bedarf handhaben.

Keine Tenant- oder Modell-Labels in Logs und Metriken

Symptome:

• Latenz sieht schlecht aus, aber niemand weiss fuer wen
• Kosten steigen, aber es gibt keine routenbasierte Sichtbarkeit
• Rollout-Probleme sind schwer zu lokalisieren

Ursache: Observability wurde nur als generische HTTP-Telemetrie hinzugefuegt.

Loesung: Loggen und labeln Sie von Anfang an nach Tenant, Route, Backend, Modell-Route und Stream-Flag.

Zusammenfassung

Ein gutes v1 AI Gateway auf Kubernetes ist keine riesige benutzerdefinierte Plattform. Es ist eine saubere Gateway-API-Einstiegsschicht mit expliziter Ownership, stabilen Routen, sicheren Rollout-Kontrollen, solider Isolation und genug Observability, um Latenz, Ausfaelle und Kosten zu verstehen. Halten Sie die erste Version einfach: trennen Sie Traffic-Klassen, routen Sie klar, isolieren Sie Tenants, setzen Sie explizite Timeouts und verifizieren Sie das Verhalten mit echtem Traffic.

Wechseln Sie zu einer fortgeschritteneren Architektur, wenn Sie sie tatsaechlich benoetigen: Body-basiertes Modell-Routing, Endpoint-Picking basierend auf Modell-Server-Metriken, externes Provider-Failover, tokenbewusstes Limiting oder Inline-Payload-Verarbeitung. Die Kubernetes AI Gateway Working Group und das Gateway API Inference Extension-Projekt machen deutlich, dass diese Muster zu erstklassigen Plattform-Belangen werden, aber sie entwickeln sich noch. Genau deshalb ist ein einfaches, gut strukturiertes v1 der richtige Ausgangspunkt.