Anwendungsgateway für Container – Konfigurieren des Ableitungsgateways

In diesem Artikel wird gezeigt, wie Sie einen selbstgehosteten vLLM-Modellserver über das Inferenzgateway von Application Gateway for Containers mithilfe der Kubernetes-Gateway API Inference Extension bereitstellen. Die Konfiguration verwendet Gateway-API-Ressourcen, ein InferencePool und die Endpoint Picker-Erweiterung (EPP), um Inferenzanfragen an Modellserver-Pods weiterzuleiten.

In diesem Handbuch stellen Sie Folgendes bereit:

  • Ein GPU-gesicherter vLLM-Modellserver, der eine openAI-kompatible API bedient
  • Gateway-API-Inference-Erweiterungsressourcen
  • Ein Gateway
  • Eine EPP-Bereitstellung, ein Dienst und InferencePool
  • Ein HTTPRoute, der /v1-Datenverkehr an den InferencePool sendet

Wie die Komponenten zusammenpassen

Application Gateway für Container empfängt Anforderungen am Gateway-Listener und gleicht sie mit einem HTTPRoute ab. Wenn der backendRef der Route ein InferencePool ist, programmiert der ALB-Controller den Datenpfad so, dass für jede Anforderung der Endpoint Picker (EPP) konsultiert wird. Die EPP überwacht die Pods, die der InferencePool Auswahl entsprechen, liest vLLM-Metriken (Warteschlangentiefe, KV-Cacheauslastung, bereitgestellte Modelle) und teilt dem Datenpfad mit, an welchen bestimmten Pod die Anforderung gesendet werden soll.

Important

Das Inferenzgateway für Application Gateway für Container befindet sich derzeit in der Vorschau.
Die zusätzlichen Nutzungsbestimmungen für Microsoft Azure-Vorschauen enthalten rechtliche Bedingungen. Sie gelten für diejenigen Azure-Features, die sich in der Beta- oder Vorschauversion befinden oder aber anderweitig noch nicht zur allgemeinen Verfügbarkeit freigegeben sind.

Voraussetzungen

Bevor Sie beginnen, führen Sie die folgenden Aufgaben aus:

  1. Bereitstellen des Anwendungsgateways für Container und ALB-Controller. Weitere Informationen finden Sie unter Schnellstart: Bereitstellen des ALB-Controllers von Application Gateway für Container.
  2. Aktivieren Sie die Inferenz-Gateway-Funktion im ALB Controller. Für Neuinstallationen oder Aktualisierungen des ALB Controller fügen Sie --set albController.aiGateway=true in den Helm-Befehl ein. Wenn Sie diese Einstellung aktivieren, installiert ALB Controller auch v1.3.1 der Gateway API Inference Extension CRDs.

Note

Das Inference Gateway wird derzeit nicht über das AKS-Add-on von Application Gateway for Containers unterstützt. Sie müssen den ALB-Controller von Application Gateway for Containers per Helm-Chart bereitstellen, um diese Funktion zu konfigurieren.

  1. Bereiten Sie einen AKS-Cluster mit einem GPU-Knotenpool vor, der mindestens eine geplante GPU und das NVIDIA-Geräte-Plug-In installiert hat. Anweisungen finden Sie unter Verwenden von GPUs für rechenintensive Workloads auf AKS.
  2. Installieren Sie die folgenden Tools auf Ihrer Arbeitsstation, oder verwenden Sie Azure Cloud Shell, sofern verfügbar:
    • Azure CLI
    • kubectl
    • helm
  3. Erstellen oder beschaffen Sie ein Hugging Face-Zugriffstoken, mit dem das von Ihrer vLLM-Bereitstellung verwendete Modell heruntergeladen werden kann.

Festlegen von Umgebungsvariablen

Legen Sie die variablen fest, die von den Befehlen in diesem Artikel verwendet werden.

NAMESPACE='inference'
INFERENCE_POOL_NAME='vllm-qwen2-5-0-5b'
MODEL_NAME='Qwen/Qwen2.5-0.5B-Instruct'
GATEWAY_NAME='ai-gateway'
HF_TOKEN='<your Hugging Face access token>'

Wenn Sie die vom ALB verwaltete Bereitstellungsstrategie verwenden, legen Sie den Namespace und den Namen Ihrer ApplicationLoadBalancer Ressource fest.

ALB_NAMESPACE='alb-test-infra'
ALB_NAME='alb-test'

Namespace erstellen

Erstellen Sie einen Namespace für die Modellserver-, Gateway-, HTTPRoute-, InferencePool- und EPP-Ressourcen.

kubectl create namespace $NAMESPACE --dry-run=client -o yaml | kubectl apply -f -

Überprüfen der CRDs der Gateway-API-Inferenz-Erweiterung

Stellen Sie sicher, dass der ALB-Controller die CRDs der Gateway API Inference Extension installiert hat.

kubectl get crds | grep inference.networking

Erwartete Ausgabe (CRD-Namen; Erstellungszeitstempel unterscheiden sich):

inferenceobjectives.inference.networking.x-k8s.io   2026-05-06T22:07:44Z
inferencepools.inference.networking.k8s.io          2026-05-06T22:07:45Z

Bereitstellen eines vLLM-Modellservers

Erstellen Sie ein Kubernetes-Geheimnis für das Hugging Face-Zugriffstoken.

kubectl create secret generic hf-token \
  --namespace $NAMESPACE \
  --from-literal=token=$HF_TOKEN \
  --dry-run=client -o yaml | kubectl apply -f -

Stellen Sie einen vLLM-Modellserver bereit. Das Beispiel verwendet Qwen/Qwen2.5-0.5B-Instruct, aber die Konfiguration von Application Gateway for Containers und der Gateway API Inference Extension ist modellagnostisch. Sie können jedes vLLM-kompatible Modell ersetzen, das auf Ihre GPU-SKU passt.

Der vLLM-Pod erfordert einen nvidia.com/gpu und toleriert einen sku=gpu:NoSchedule-Taint, sodass er auf einem GPU-Knoten landet. Entfernen Sie die Toleranz, wenn Ihr Knotenpool nicht mit einem Taint versehen ist, oder wenden Sie den Taint mit kubectl taint nodes -l agentpool=<gpu-pool> sku=gpu:NoSchedule an. Die Pod-Bezeichnungen (app: ${INFERENCE_POOL_NAME}) sind das, wonach der InferencePool später auswählt. Ändern Sie sie daher nicht, ohne auch den inferencePool.modelServers.matchLabels.app-Wert des Charts zu aktualisieren.

kubectl apply -n $NAMESPACE -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: ${INFERENCE_POOL_NAME}
  labels:
    app: ${INFERENCE_POOL_NAME}
spec:
  replicas: 1
  selector:
    matchLabels:
      app: ${INFERENCE_POOL_NAME}
  template:
    metadata:
      labels:
        app: ${INFERENCE_POOL_NAME}
        inference.networking.k8s.io/engine-type: vllm
    spec:
      containers:
      - name: vllm
        image: vllm/vllm-openai:latest
        imagePullPolicy: Always
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - "--model"
        - "${MODEL_NAME}"
        - "--port"
        - "8000"
        - "--max-model-len"
        - "2048"
        - "--gpu-memory-utilization"
        - "0.8"
        env:
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-token
              key: token
        ports:
        - containerPort: 8000
          name: http
          protocol: TCP
        readinessProbe:
          httpGet:
            path: /health
            port: http
          periodSeconds: 5
          failureThreshold: 12
        startupProbe:
          httpGet:
            path: /health
            port: http
          periodSeconds: 10
          failureThreshold: 60
        resources:
          limits:
            nvidia.com/gpu: "1"
          requests:
            nvidia.com/gpu: "1"
        volumeMounts:
        - mountPath: /dev/shm
          name: shm
      tolerations:
      - key: "sku"
        operator: "Equal"
        value: "gpu"
        effect: "NoSchedule"
      - key: "nvidia.com/gpu"
        operator: "Exists"
        effect: "NoSchedule"
      volumes:
      - name: shm
        emptyDir:
          medium: Memory
EOF

Warten Sie, bis der Modellserver bereit ist. Der Modelldownload und der Start können mehrere Minuten dauern.

kubectl rollout status deployment/${INFERENCE_POOL_NAME} -n $NAMESPACE --timeout=900s

Erwartete Ausgabe:

deployment "vllm-qwen2-5-0-5b" successfully rolled out

Erstellen des Gateways

Erstellen Sie ein Gateway für Application Gateway für Container. Wählen Sie die Registerkarte für Ihre Bereitstellungsstrategie aus.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: ${GATEWAY_NAME}
  namespace: ${NAMESPACE}
  annotations:
    alb.networking.azure.io/alb-namespace: ${ALB_NAMESPACE}
    alb.networking.azure.io/alb-name: ${ALB_NAME}
spec:
  gatewayClassName: azure-alb-external
  listeners:
  - name: http
    protocol: HTTP
    port: 80
    allowedRoutes:
      namespaces:
        from: Same
EOF

Warten Sie, bis das Gateway programmiert ist.

kubectl wait \
  --for=condition=Programmed \
  gateway/${GATEWAY_NAME} \
  -n $NAMESPACE \
  --timeout=300s

Wenn sie bereit ist, wird die folgende Meldung angezeigt:

gateway.gateway.networking.k8s.io/ai-gateway condition met

Stellen Sie den InferencePool und die Endpunktauswahl bereit

Stellen Sie die EVP und InferencePool zusammen mithilfe des inferencepool Helm-Diagramms bereit, das vom Kubernetes Gateway API Inference Extension-Projekt veröffentlicht wurde. Das Chart erstellt ein EPP-Deployment, einen Service an Port 9002, die ServiceAccount, Role und RoleBinding, mit denen der EPP Pods überwachen kann, sowie die InferencePool-Ressource selbst (benannt nach dem Helm-Release).

IGW_CHART_VERSION='v1.3.1'
EPP_IMAGE_TAG='v1.3.1'

Installieren Sie das Diagramm.

Note

Das Chart hängt -epp an den Namen des Helm-Release an, wenn das EPP-Deployment und -Service (${INFERENCE_POOL_NAME}-epp) benannt werden. In späteren Schritten wird auf diesen Namen verwiesen, wenn der Rolloutstatus überprüft, Protokolle verfolgt und Endpunkt-Slices untersucht werden.

helm upgrade --install "${INFERENCE_POOL_NAME}" \
  --namespace "${NAMESPACE}" \
  --set "inferencePool.modelServers.matchLabels.app=${INFERENCE_POOL_NAME}" \
  --set "inferenceExtension.image.tag=${EPP_IMAGE_TAG}" \
  --set "provider.name=none" \
  --version "${IGW_CHART_VERSION}" \
  oci://registry.k8s.io/gateway-api-inference-extension/charts/inferencepool

Warning

Das inferencepool Helm-Diagramm, das vom Kubernetes Gateway API Inference Extension-Projekt verwaltet wird, rendert eine InferencePool Ressource, die nach der Helm-Version benannt ist. Wenn ein InferencePool mit demselben Namen im Namespace bereits vorhanden ist und außerhalb von Helm erstellt wurde, weigert sich helm upgrade --install, dieses zu übernehmen, und der Befehl schlägt mit einem invalid ownership metadata-Fehler fehl. Wenn der vorhandene Pool einem anderen Helm-Release gehört, überschreibt die Installation die Spezifikation dieses InferencePool, einschließlich des Zurücksetzens des EPP-Images, des Selektors und von endpointPickerRef auf die Standardwerte des v1.3.1-Charts. Bevor Sie den Befehl ausführen, löschen Sie entweder den vorhandenen Pool (kubectl delete inferencepool <name> -n $NAMESPACE) oder wählen Sie eine andere INFERENCE_POOL_NAME für diese exemplarische Vorgehensweise aus.

Warten Sie, bis die EPP-Bereitstellung verfügbar ist.

kubectl rollout status deployment/${INFERENCE_POOL_NAME}-epp -n $NAMESPACE --timeout=180s

Wenn sie bereit ist, wird die folgende Meldung angezeigt:

deployment "vllm-qwen2-5-0-5b-epp" successfully rolled out

Überprüfen des InferencePools

Das Helm-Chart hat eine InferencePool-Ressource namens ${INFERENCE_POOL_NAME} erstellt, die mit app=${INFERENCE_POOL_NAME} bezeichnete Pods auswählt und auf den über das Chart installierten EPP-Dienst verweist. Bestätigen Sie, dass sie vorhanden ist.

kubectl get inferencepool ${INFERENCE_POOL_NAME} -n $NAMESPACE -o yaml

Suchen Sie im Status Accepted=True nach ResolvedRefs=True und InferencePool.

Erstellen der HTTPRoute

Erstellen Sie ein HTTPRoute, das InferencePool als Gateway API-Backend verwendet.

kubectl apply -f - <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: ${INFERENCE_POOL_NAME}
  namespace: ${NAMESPACE}
spec:
  parentRefs:
  - name: ${GATEWAY_NAME}
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /v1
    backendRefs:
    - group: inference.networking.k8s.io
      kind: InferencePool
      name: ${INFERENCE_POOL_NAME}
EOF

Überprüfen des Routenstatus

Vergewissern Sie sich, dass die HTTPRoute akzeptiert wird und Verweise aufgelöst werden.

kubectl get httproute ${INFERENCE_POOL_NAME} -n $NAMESPACE -o yaml

Suchen Sie nach Bedingungen, die der folgenden Ausgabe ähneln.

  status:
    parents:
    - conditions:
      - lastTransitionTime: "2026-05-07T03:54:14Z"
        message: ""
        observedGeneration: 3
        reason: ResolvedRefs
        status: "True"
        type: ResolvedRefs
      - lastTransitionTime: "2026-05-07T03:54:14Z"
        message: Route is Accepted
        observedGeneration: 3
        reason: Accepted
        status: "True"
        type: Accepted
      - lastTransitionTime: "2026-05-07T03:54:14Z"
        message: Application Gateway for Containers resource has been successfully
          updated.
        observedGeneration: 3
        reason: Programmed
        status: "True"
        type: Programmed
      controllerName: alb.networking.azure.io/alb-controller
      parentRef:
        group: gateway.networking.k8s.io
        kind: Gateway
        name: ai-gateway

Inferenzdatenverkehr senden

Rufen Sie die Gateway-Adresse ab.

GATEWAY_ADDRESS=$(kubectl get gateway/${GATEWAY_NAME} \
  -n $NAMESPACE \
  -o jsonpath='{.status.addresses[0].value}')

Senden Sie eine Chatabschlussanfrage über das Anwendungsgateway für Container.

curl -i http://${GATEWAY_ADDRESS}/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"${MODEL_NAME}\",
    \"messages\": [{\"role\": \"user\", \"content\": \"What is 2+2? Answer in one word.\"}],
    \"max_tokens\": 10
  }"

Erwartete Antwort (IDs, Zeitstempel und Tokenanzahl unterscheiden sich):

HTTP/1.1 200 OK
content-type: application/json

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "Qwen/Qwen2.5-0.5B-Instruct",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "Four."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 18, "completion_tokens": 2, "total_tokens": 20}
}

Sie können auch Textvervollständigungen testen.

curl -i http://${GATEWAY_ADDRESS}/v1/completions \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"${MODEL_NAME}\",
    \"prompt\": \"San Francisco is\",
    \"max_tokens\": 50
  }"

Optional: Erstellen eines InferenceObjectives

Erstellen Sie ein InferenceObjective, wenn Clients dem EPP die Bereitstellungspriorität signalisieren sollen. Der EPP nutzt das Ziel; der HTTPRoute verweist nicht direkt darauf. Höhere priority-Werte werden vor niedrigeren bedient, wenn der EPP Last abwerfen muss.

Warning

Die InferenceObjective-Ressource befindet sich derzeit in der inference.networking.x-k8s.io/v1alpha2-API-Gruppe, während InferencePool in v1 überführt wurde; beide Gruppen bestehen nebeneinander, während sich die InferenceObjective-API stabilisiert. Api-Änderungen an der Ressource erwarten.

kubectl apply -n $NAMESPACE -f - <<EOF
apiVersion: inference.networking.x-k8s.io/v1alpha2
kind: InferenceObjective
metadata:
  name: critical-inference
spec:
  poolRef:
    group: inference.networking.k8s.io
    kind: InferencePool
    name: ${INFERENCE_POOL_NAME}
  priority: 10
EOF

Senden Sie eine Anforderung, die das Ziel verwendet.

curl -i http://${GATEWAY_ADDRESS}/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -H 'x-gateway-inference-objective: critical-inference' \
  -d "{
    \"model\": \"${MODEL_NAME}\",
    \"messages\": [{\"role\": \"user\", \"content\": \"Summarize what an inference gateway does.\"}],
    \"max_tokens\": 80
  }"

Beobachten des Verhaltens der Endpunktauswahl

Überprüfen Sie die EPP-Protokolle, um sicherzustellen, dass Anfragen über die Endpunktauswahl geleitet werden.

kubectl logs deployment/${INFERENCE_POOL_NAME}-epp -n $NAMESPACE --tail=100

Überprüfen Sie die vLLM-Metriken im Pod des Modellservers.

POD=$(kubectl get pods -n $NAMESPACE -l app=${INFERENCE_POOL_NAME} -o jsonpath='{.items[0].metadata.name}')

kubectl exec -n $NAMESPACE $POD -- curl -s http://localhost:8000/metrics \
  | grep -E "^vllm:(num_requests_waiting|num_requests_running|kv_cache_usage_perc)"

Troubleshoot

Wenn der Datenverkehr den Modellserver nicht erreicht, verwenden Sie die folgenden Prüfungen:

  • Vergewissern Sie sich, dass der ALB-Controller mit aktivierter AI-Gateway-Funktion läuft.
  • Bestätigen Sie, dass der Gateway Status enthält Accepted=True und Programmed=True.
  • Vergewissern Sie sich, dass der HTTPRoute Status enthält Accepted=True, ResolvedRefs=Trueund Programmed=True.
  • Bestätigen Sie, dass der InferencePool Status enthält Accepted=True und ResolvedRefs=True.
  • Bestätigen Sie, dass der InferencePool Selektor mit den Labels auf den vLLM-Pods übereinstimmt.
  • Vergewissern Sie sich, dass der EPP-Dienst und das Deployment im selben Namespace wie das InferencePool ausgeführt werden.
  • Vergewissern Sie sich, dass die Modellserver-Pods bereit sind und Port 8000 verfügbar machen.
  • Überprüfen Sie die EPP-Protokolle auf Fehler bei der Endpunktauswahl oder bei der Modellsuche.

Übliche Fehler

Symptom Wahrscheinliche Ursache Beheben
vLLM-Pod hängt in Pending fest Keine zuweisbare GPU, Taints stimmen nicht mit den Toleranzen des Pods überein, oder die nvidia.com/gpu-Ressource wird vom Geräte-Plug-In nicht angekündigt. Verwenden Sie kubectl describe pod, um die Planer-Nachricht anzuzeigen. Überprüfen Sie, ob der GPU-Knotenpool vorhanden ist, das NVIDIA-Geräte-Plug-In-DaemonSet Ready ist und die Toleranz mit Ihrem Taint übereinstimmt.
vLLM-Pod in CrashLoopBackOff mit 401 Unauthorized in Protokollen Das Hugging-Face-Token ist ungültig, abgelaufen oder hat keine Zugriffsberechtigung für das Modell. Erstellen Sie das hf-token Secret mit einem Token, das Lesezugriff auf das Model-Repository hat, neu, und führen Sie dann kubectl rollout restart deployment/${INFERENCE_POOL_NAME} aus.
HTTPRoute-Status zeigt ResolvedRefs=False mit reason: BackendNotFound und message: InferencePool <namespace>/<name> not found an Der HTTPRoute-Name des backendRef stimmt nicht mit einem vorhandenen InferencePool überein, oder das InferencePool existiert zwar, hat aber keine einsatzbereiten Endpunkte (z. B. wenn der vLLM-Pod den Status Pending hat, weil kein GPU-Knoten eingeplant oder hochskaliert werden konnte). ALB Controller meldet einen Pool mit null verfügbaren Endpunkten als BackendNotFound. Führen Sie die Ausführung kubectl get inferencepool -n $NAMESPACE aus, um zu bestätigen, dass der Name der Route backendRefentspricht. Führen Sie kubectl get pods -n $NAMESPACE -l app=${INFERENCE_POOL_NAME} und kubectl describe pod <pod> -n $NAMESPACE dann aus. Wenn der Pod Pending ist und FailedScheduling Ereignisse wie Insufficient nvidia.com/gpu oder untolerated taint(s) aufweist, skalieren Sie den GPU-Knotenpool hoch, korrigieren Sie die Toleration, oder wählen Sie eine SKU mit verfügbarer GPU-Kapazität aus.
curl gibt 503 vom Gateway zurück. Der EPP kann den Pool nicht erreichen (keine bereiten Endpunkte), oder der EPP-Dienstname in endpointPickerRef wird nicht aufgelöst. Überprüfen Sie kubectl get endpointslices -n $NAMESPACE -l kubernetes.io/service-name=${INFERENCE_POOL_NAME}-epp, und vergewissern Sie sich, dass InferencePool.spec.endpointPickerRef.name mit dem über das Chart installierten Dienstnamen übereinstimmt.
curl gibt 404 zurück. Der Pfad entspricht nicht dem HTTPRoute. Vergewissern Sie sich, dass der Anforderungspfad beginnt /v1 und dass die Route parentRefs auf dasselbe Gateway im selben Namespace verweist.
Anfragen bleiben für >60 Sekunden hängen und geben dann einen Fehler zurück vLLM lädt das Modell weiterhin in den GPU-Speicher. Warten Sie, bis der Bereitschaftstest erfolgreich ist. Verfolgen Sie die vLLM-Protokolle, bis Application startup complete angezeigt wird.

Bereinigen von Ressourcen

Löschen Sie die Ressourcen, die Sie in diesem Artikel erstellt haben.

kubectl delete inferenceobjective critical-inference -n $NAMESPACE --ignore-not-found
kubectl delete httproute ${INFERENCE_POOL_NAME} -n $NAMESPACE --ignore-not-found
helm uninstall ${INFERENCE_POOL_NAME} -n $NAMESPACE 2>/dev/null || true
kubectl delete gateway ${GATEWAY_NAME} -n $NAMESPACE --ignore-not-found
kubectl delete deployment ${INFERENCE_POOL_NAME} -n $NAMESPACE --ignore-not-found
kubectl delete secret hf-token -n $NAMESPACE --ignore-not-found
kubectl delete namespace $NAMESPACE --ignore-not-found

Nächste Schritte

  • Last updated on