Fehlerbehebung des Container Network Insights Agent auf AKS

In diesem Artikel werden häufig auftretende Probleme behandelt, die beim Bereitstellen, Einrichten oder Verwenden des Container Network Insights-Agents auf AKS auftreten können. Jeder Abschnitt folgt einem Symptom → Cause → Resolution Format.

Anweisungen zur Bereitstellung finden Sie unter Bereitstellen und Verwenden des Container Network Insights-Agents auf AKS.

Fehler bei der Erweiterungsinstallation

Symptom: Der az k8s-extension create Befehl schlägt fehl, oder der Erweiterungsbereitstellungsstatus wird angezeigt Failed.

Cause: Souveräne Cloudregion (die Erweiterung wird nur in Azure öffentlichen Regionen unterstützt), fehlende Clusterfeatures oder unzureichende Berechtigungen.

Lösung:

1. Überprüfen Sie den Erweiterungsbereitstellungsstatus auf Details:

   az k8s-extension show \
       --cluster-name $CLUSTER_NAME \
       --resource-group $RESOURCE_GROUP \
       --cluster-type managedClusters \
       --name containernetworkingagent \
       --query "{state:provisioningState, statuses:statuses}" -o json
   

2. Überprüfen Sie, ob sich Ihr Cluster in einer Azure öffentlichen Region befindet. Die Erweiterung ist in allen Azure öffentlichen Regionen verfügbar, in denen AKS unterstützt wird, aber in Azure Government, Microsoft Azure von 21Vianet oder anderen souveränen Clouds nicht verfügbar ist.

3. Überprüfen Sie, ob Ihr Cluster über die Workloadidentität verfügt und der OIDC-Aussteller aktiviert ist:

   az aks show \
       --resource-group $RESOURCE_GROUP \
       --name $CLUSTER_NAME \
       --query "{oidcEnabled:oidcIssuerProfile.enabled, workloadIdentityEnabled:securityProfile.workloadIdentity.enabled}"
   

4. Überprüfen Sie, ob Sie die Rollen Contributor und User Access Administrator in der Ressourcengruppe haben.

5. Wenn Sie bereits einmal ausgeführt haben az k8s-extension create , gibt die Ausführung erneut einen Fehler zurück, da die Erweiterung bereits vorhanden ist. Verwenden Sie az k8s-extension update, um die Konfiguration einer vorhandenen Erweiterung zu ändern.

   az k8s-extension update \
     --cluster-name $CLUSTER_NAME \
     --resource-group $RESOURCE_GROUP \
     --cluster-type managedClusters \
     --name containernetworkingagent \
     --configuration-settings config.SOME_SETTING=new-value
   

Identitäts- und Berechtigungsfehler

Symptom: Der Agent-Pod startet, gibt aber bei der Verarbeitung von Anfragen 401 Unauthorized- oder 403 Forbidden-Fehler zurück. Pod-Protokolle zeigen Authentifizierungs- oder Autorisierungsfehler an.

Ursache: Die verwaltete Identität hat keine erforderlichen RBAC-Rollenzuweisungen, oder das Subjekt der Verbundanmeldeinformationen stimmt nicht mit dem Dienstkonto des Agents überein.

Lösung:

1. Überprüfen Sie, ob die verwaltete Identität über alle vier erforderlichen Rollenzuweisungen verfügt:

   az role assignment list --assignee <identity-principal-id> --all -o table
   

   Stellen Sie sicher, dass diese Rollen vorhanden sind:

   Rolle	Geltungsbereich
   Cognitive Services OpenAI User	Azure OpenAI-Ressource
   Azure Kubernetes Service Cluster User Role	AKS-Cluster
   Azure Kubernetes Service Contributor Role	AKS-Cluster
   Reader	Ressourcengruppe

2. Überprüfen Sie, ob die Workloadidentität im Cluster aktiviert ist:

   az aks show \
       --resource-group $RESOURCE_GROUP \
       --name $CLUSTER_NAME \
       --query "securityProfile.workloadIdentity.enabled"
   

3. Überprüfen Sie, ob der Betreff der Verbundanmeldeinformationen mit dem Dienstkonto übereinstimmt:

   az identity federated-credential list \
       --identity-name $IDENTITY_NAME \
       --resource-group $RESOURCE_GROUP
   

   Das subject Feld sollte sein system:serviceaccount:kube-system:container-networking-agent-reader.

4. Überprüfen Sie, ob das Kubernetes-Dienstkonto die richtige Workload-Identitätsanmerkung aufweist:

   kubectl get serviceaccount container-networking-agent-reader -n kube-system -o yaml
   

   Die azure.workload.identity/client-id Anmerkung muss mit der Client-ID Ihrer verwalteten Identität übereinstimmen. Wenn sie nicht übereinstimmen, korrigieren Sie sie, und starten Sie den Pod neu:

   kubectl annotate serviceaccount container-networking-agent-reader \
     -n kube-system \
     azure.workload.identity/client-id=$IDENTITY_CLIENT_ID \
     --overwrite
   
   kubectl rollout restart deployment container-networking-agent -n kube-system
   

Azure OpenAI-Konnektivitätsprobleme

Symptom: Der Agent-Pod wird gestartet, aber Chatanfragen schlagen fehl. Podprotokolle zeigen 401 Unauthorized, 404 Not Found oder Verbindungsfehler an, die auf den Azure OpenAI-Endpunkt verweisen.

Cause: Der Azure OpenAI-Endpunkt, der Bereitstellungsname oder die verwalteten Identitätsanmeldeinformationen sind falsch konfiguriert, oder der Netzwerkdatenverkehr an den Endpunkt wird blockiert.

Lösung:

1. Überprüfen Sie die Pod-Protokolle auf bestimmte Fehlermuster:

   Protokollmeldung	Ursache	Reparatur
   401 Unauthorized	Für verwaltete Identität fehlt die Cognitive Services OpenAI User-Rolle	Rolle für die OpenAI-Ressource zuweisen
   404 Not Found	Falsche Endpunkt-URL oder Bereitstellungsname	Überprüfen Sie AZURE_OPENAI_ENDPOINT und AZURE_OPENAI_DEPLOYMENT
   Connection refused / Name resolution failed	Netzwerk- oder DNS-Problem	Überprüfen Sie die NSG/Firewall-Regeln, und überprüfen Sie den Endpunkthostnamen.
   Token acquisition failed	Workload-Identität nicht konfiguriert	Anmerkungen zum Dienstkonto und die föderierten Anmeldeinformationen überprüfen

2. Überprüfen Sie, ob die verwaltete Identität über die Rolle Cognitive Services OpenAI User für die Azure OpenAI-Ressource verfügt:

   az role assignment list \
     --assignee <managed-identity-principal-id> \
     --scope /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<openai-resource-name> \
     --output table
   

3. Wenn Sie Netzwerkrichtlinien, Azure Firewall oder NSGs verwenden, stellen Sie sicher, dass ausgehender HTTPS-Datenverkehr (Port 443) vom kube-system Namespace an Ihren Azure OpenAI-Endpunkt zulässig ist. Stellen Sie sicher, dass keine Netzwerkrichtlinien ausgehenden Datenverkehr blockieren:

   kubectl get networkpolicies -n kube-system
   

Fehler bei der App-Registrierung und Entra ID Authentifizierung

Symptom: Der Microsoft Entra ID (MSAL)-Anmeldefluss schlägt fehl, bei der Anmeldung treten Fehler auf, die Anmeldeumleitungen geben Fehler zurück, oder die Pod-Protokolle zeigen den Platzhalterwert 44444444-4444-4444-4444-444444444444 für ENTRA_CLIENT_ID an.

Ursache: Die App-Registrierung ist nicht ordnungsgemäß konfiguriert oder wurde während der ENTRA_CLIENT_ID Erweiterungsbereitstellung nicht festgelegt.

Lösung:

1. Wenn die Pod-Logs den Platzhalterwert 44444444-4444-4444-4444-444444444444 anzeigen, aktualisieren Sie die Erweiterung mit Ihrer tatsächlichen Client-ID für die App-Registrierung:

   az k8s-extension update \
     --cluster-name $CLUSTER_NAME \
     --resource-group $RESOURCE_GROUP \
     --cluster-type managedClusters \
     --name containernetworkingagent \
     --configuration-settings config.ENTRA_CLIENT_ID=<your-app-registration-client-id>
   

2. Wenn der Anmelderückruf mit einem redirect_uri mismatch-Fehler fehlschlägt, überprüfen Sie die Umleitungs-URI im Azure-Portal unter App-Registrierungen > Ihre App > Authentifizierung > Umleitungs-URIs. Für den lokalen Zugriff mit Port-Weiterleitung muss der URI http://localhost:8080/auth/callback lauten.

   Hinweis

   Derzeit werden nur localhost Umleitungs-URIs unterstützt. Öffentliche LoadBalancer-URLs werden für Umleitungs-URIs nicht unterstützt.

3. Stellen Sie sicher, dass die App-Registrierung über die erforderlichen Microsoft Graph delegierten Berechtigungen verfügt: openid, profile, User.Read, offline_access. Wenn die Administratorzustimmung erforderlich ist, erteilen Sie sie:

   az ad app permission admin-consent --id <app-registration-object-id>
   

4. Überprüfen Sie die Podprotokolle auf Authentifizierungsspezifische Fehler:

   kubectl logs -n kube-system -l app=container-networking-agent | grep -i "auth\|msal\|entra"
   

Fehlende Umgebungsvariablen beim Start

Symptom: Der Agent-Pod stürzt beim Start sofort ab mit:

RuntimeError: Missing required Azure OpenAI environment variable(s): AZURE_OPENAI_ENDPOINT, AZURE_OPENAI_DEPLOYMENT, AZURE_OPENAI_API_VERSION.

Ursache: Mindestens ein erforderlicher Konfigurationswert wurde beim Bereitstellen der Erweiterung nicht festgelegt.

Lösung:

1. Überprüfen Sie die ConfigMap auf Platzhalterwerte oder fehlende Einstellungen:

   kubectl get configmap -n kube-system -l app=container-networking-agent -o yaml
   

2. Vergewissern Sie sich, dass diese erforderlichen Variablen mit realen Werten festgelegt werden (keine Platzhalter wie 00000000-0000-0000-0000-000000000000):

   Variable	Beschreibung	Beispiel
   AZURE_OPENAI_ENDPOINT	Azure OpenAI-Ressourcenendpunkt	https://your-instance.openai.azure.com/
   AZURE_OPENAI_DEPLOYMENT	Modellbereitstellungsname	gpt-4o
   AZURE_OPENAI_API_VERSION	API-Version	2025-03-01-preview
   AZURE_CLIENT_ID	Client-ID für verwaltete Identität	UUID
   AZURE_TENANT_ID	Azure Mandanten-ID	UUID
   AZURE_SUBSCRIPTION_ID	Azure Abonnement-ID	UUID
   AKS_CLUSTER_NAME	AKS-Cluster-Name	Ihr Clustername
   AKS_RESOURCE_GROUP	Clusterressourcengruppe	Ihre Ressourcengruppe

3. Wenn Werte Platzhalter anzeigen, aktualisieren Sie die Erweiterung mit den richtigen Einstellungen:

   az k8s-extension update \
     --cluster-name $CLUSTER_NAME \
     --resource-group $RESOURCE_GROUP \
     --cluster-type managedClusters \
     --name containernetworkingagent \
     --configuration-settings config.AZURE_OPENAI_ENDPOINT=<your-endpoint> \
     --configuration-settings config.AZURE_OPENAI_DEPLOYMENT=<your-deployment>
   

Agent-Pod wird nicht ausgeführt oder stürzt ab

Symptom: Der Agent-Pod befindet sich in einem CrashLoopBackOff, Error oder Pending Zustand.

Cause: Fehlkonfiguration, fehlende Azure OpenAI-Konnektivität oder unzureichende Clusterressourcen.

Lösung:

1. Überprüfen Sie Pod-Ereignisse auf unmittelbare Fehler:

   kubectl describe pod -n kube-system -l app=container-networking-agent
   

2. Überprüfen Sie die Podprotokolle auf Fehlermeldungen:

   kubectl logs -n kube-system -l app=container-networking-agent --tail=200
   

3. Abgleichen von Protokollmeldungen zu bekannten Ursachen:

   Protokollmeldung	Ursache	Reparatur
   Missing required Azure OpenAI environment variable(s)	ConfigMap enthält Platzhalterwerte	Festlegen korrekter Werte über az k8s-extension update
   bootstrap.validation_agent_failed	Herstellen einer Verbindung mit Azure OpenAI nicht möglich	Überprüfen Sie das Netzwerk, die Endpunkt-URL und die verwaltete Identität RBAC.
   AKS MCP binary not found	Binärdatei fehlt im Bild	Verwenden Sie das offizielle Erweiterungsbild von acnpublic.azurecr.io
   FailedMount-Fehler / Fehler beim Einbinden von Volumes	Fehlende Geheime Schlüssel des Hubble-Zertifikats	Bereitstellen mit hubble.enabled=false oder sicherstellen, dass ACNS aktiviert ist
   Token acquisition failed	Workload-Identität nicht konfiguriert	Anmerkungen zum Dienstkonto und die föderierten Anmeldeinformationen überprüfen

4. Stellen Sie sicher, dass der Azure OpenAI-Endpunkt über den Cluster erreichbar ist. Wenn Sie Ausgangsbeschränkungen verwenden, stellen Sie sicher, dass ausgehendes HTTPS (Port 443) vom kube-system-Namespace an Ihren Azure OpenAI-Endpunkt zulässig ist.

Fehler beim Bereitschaftstest

Symptom: Der Pod ist Running, zeigt aber den Status 0/1 bereit an. Der /ready Endpunkt gibt HTTP 503 zurück.

Ursache: Mindestens eine Startüberprüfung wurde noch nicht abgeschlossen: Der Warmup-Agent-Pool wird noch nicht initialisiert, Clustereigenschaften weisen Fehler auf, oder es sind keine vorgewärmten Agents verfügbar.

Lösung:

1. Warten Sie nach der Bereitstellung bis zu 2 oder 3 Minuten, bis der Warmup-Pool vorab betriebsbereite Agenten erstellt hat.

2. Überprüfen Sie die Bereitschaftsreaktion auf spezifische Fehlgründe.

   kubectl port-forward svc/container-networking-agent-service -n kube-system 8080:80
   curl -s http://localhost:8080/ready | jq
   

3. Überprüfen Sie die Pod-Protokolle auf Probleme beim Aufwärmen:

   kubectl logs -n kube-system -l app=container-networking-agent | grep -i "warmup\|ready\|error"
   

4. Wenn Clustereigenschaften fehlschlagen, überprüfen Sie, ob AKS_CLUSTER_NAMEAKS_RESOURCE_GROUP, , und AZURE_SUBSCRIPTION_ID sind in der Erweiterungskonfiguration richtig festgelegt.

Der Aufwärmpool fällt ständig aus

Symptom: Der Pod ist Running, wird aber nicht einsatzbereit. Pod-Protokolle zeigen wiederholte "Failed to create warmed agent"-Fehler selbst nach mehreren Minuten Wartezeit an.

Ursache: Der Hintergrund-Warmuppool kann keine vorgewärmten Agentinstanzen erstellen. Dies wird in der Regel durch ein nicht behobenes Azure OpenAI-Konnektivitätsproblem oder durch einen MCP-Initialisierungsfehler verursacht, der die Erstellung von Agents verhindert.

Lösung:

1. Überprüfen Sie die Protokolle auf den spezifischen zugrunde liegenden Fehler:

   kubectl logs -n kube-system -l app=container-networking-agent | grep -i "warmup\|Failed to create"
   

2. Ordne den Fehler seiner Behebung zu:

   Fehler in Protokollen	Reparatur
   401 Unauthorized oder 403 Forbidden	Siehe Azure OpenAI-Konnektivitätsprobleme und überprüfen Sie die Zuweisung verwalteter Identitätsrollen
   Token acquisition failed	Identitäts- und Berechtigungsfehler
   404 Not Found am Endpunkt	Überprüfen Sie AZURE_OPENAI_ENDPOINT und AZURE_OPENAI_DEPLOYMENT in der ConfigMap
   AKS MCP binary not found	Siehe Agent Pod wird nicht ausgeführt oder stürzt ab

3. Sobald das zugrundeliegende Problem behoben ist, wird der Warmup-Pool automatisch erneut gestartet. Sie brauchen den Pod nicht neu zu starten, solange der Fehler nach der Behebung der Ursache nicht weiterhin besteht.

Hubble-Befehle schlagen fehl

Symptom: Der Agent meldet Fehler für Hubble-bezogene Diagnosen, oder die Hubble-Flussanalyse ist nicht verfügbar.

Ursache: Der Cluster verfügt nicht über Advanced Container Networking Services (ACNS) oder der Cilium-Datenplan ist aktiviert.

Lösung:

• Wenn Ihr Cluster ACNS nicht verwendet, stellen Sie die Erweiterung mit hubble.enabled=false und config.AKS_MCP_ENABLED_COMPONENTS=kubectl bereit. Der Agent stellt weiterhin DNS-, Paketablage- und Standard-Kubernetes-Netzwerkdiagnose ohne Hubble bereit.

• Um Hubble zu aktivieren, muss Ihr Cluster Azure CNI verwenden, das von Cilium mit aktivierten Advanced Container Networking Services (ACNS) unterstützt wird.

• Überprüfen Sie, ob Hubble auf Ihrem Cluster ausgeführt wird:

  kubectl get pods -n kube-system -l k8s-app=hubble-relay
  

  Wenn keine Pods zurückkehren, ist Hubble nicht aktiviert. Aktivieren Sie ACNS auf Ihrem Cluster oder legen Sie hubble.enabled=false in der Erweiterungskonfiguration fest.

Einschränkung der Chatrate

Symptom: Chatanforderungen geben HTTP 429 mit X-RateLimit-* oder X-LLM-RateLimit-* Antwortheadern zurück.

Ursache: Der integrierte Ratenbegrenzer drosselt Anfragen zum Schutz des Dienstes.

Lösung:

Der Container Network Insights-Agent verfügt über drei Ebenen zur Begrenzung der Geschwindigkeit:

• Bei Chat-429-Fehlern: Verringern Sie die Nachrichtenhäufigkeit, und warten Sie, bis sich der Rate-Limit-Bucket wieder auffüllt.
• Bei LLM 429-Fehlern: Überprüfen Sie ihr Azure OpenAI-Token-Per-Minute (TPM)-Kontingent im Azure-Portal. Fordern Sie unter Cognitive Services > Quotas eine Kontingenterhöhung an, wenn Sie einen höheren Durchsatz benötigen.

Chatnachricht gesendet, aber keine Antwort

Symptom: Eine Chatnachricht wird gesendet, aber es wird keine Antwort angezeigt. Die Anforderung hängt oder gibt schließlich einen Timeout-Fehler zurück.

Ursache: Azure OpenAI ist möglicherweise ratenbegrenzt oder nicht erreichbar, es sind möglicherweise noch keine betriebsbereiten Agenten verfügbar oder ein lang laufender Diagnosebefehl wird noch ausgeführt.

Lösung:

1. Überprüfen Sie, ob der Pod über aktive Sitzungen verfügt und ob ein Agent zugewiesen ist:

   kubectl port-forward svc/container-networking-agent-service -n kube-system 8080:80
   curl -s http://localhost:8080/api/status/sessions | jq
   

2. Überprüfen Sie die Pod-Protokolle auf Fehlermuster:

   kubectl logs -n kube-system -l app=container-networking-agent --tail=50
   

   Protokollindikator	Ursache	Reparatur
   429 Fehler	Azure OpenAI-Ratenbegrenzung	Warten Sie, bis die Ratenbegrenzung zurückgesetzt wird; überprüfen Sie das TPM-Kontingent
   "No pre-warmed agents available"	Der Warmup-Pool ist nicht bereitgestellt	Warten Sie auf die Initialisierung; siehe "Warmup-Pool schlägt immer wieder fehl"
   Verbindungs-Timeouts	Netzwerk- oder NSG-Problem	Überprüfen Sie das Pod-Netzwerk, die DNS- und die NSG-Regeln

3. Wenn die Anforderung nach 2 Minuten noch aussteht, beginnen Sie eine neue Unterhaltung und senden Sie zunächst eine einfache Abfrage (z. B. "pods im Standard-Namespace auflisten"), um zu überprüfen, ob der Agent antwortet, bevor Sie eine komplexe diagnostische Frage stellen.

Langsame erste Anforderung

Symptom: Die erste Chatnachricht nach dem Neustart der Bereitstellung oder des Pods dauert 10-30 Sekunden, um zu antworten.

Ursache: Container Network Insights Agent verwaltet einen Pool von vorgewärmten Agents, um die Latenz zu reduzieren. Nach einem Neustart eines Pods benötigt der Warmup-Pool Zeit, um jeden Agenten zu initialisieren, was den Start des MCP-Plugins, die Einrichtung der Azure-Anmeldeinformationen und die Initialisierung des AI-Frameworks erfordert.

Auflösung: Dies ist ein erwartetes Verhalten. Warten Sie, bis der /ready Endpunkt HTTP 200 zurückgibt, bevor Anforderungen gesendet werden. Dadurch wird bestätigt, dass mindestens ein vorgewärmter Agent verfügbar ist. Nachfolgende Anforderungen verwenden den vorgewärmten Pool und reagieren schneller (in der Regel 5-10 Sekunden für einfache Abfragen).

kubectl port-forward svc/container-networking-agent-service -n kube-system 8080:80
curl -s http://localhost:8080/ready | jq

Langsame Antworten für komplexe Diagnosen

Symptom: Diagnoseantworten dauern 30 Sekunden bis 2 Minuten.

Cause: Die Multi-Step-Diagnose umfasst sequenzielle Vorgänge: einen anfänglichen LLM-Klassifizierungsaufruf an Azure OpenAI, mehrere kubectl/cilium/hubble-Befehle, die gegen den Cluster ausgeführt werden, und eine abschließende LLM-Analyse der gesammelten Nachweise. Jeder Schritt fügt Latenz hinzu.

Auflösung: Dies wird für komplexe Diagnosen erwartet. Die folgende Tabelle zeigt typische Antwortzeiten:

So verringern Sie die Latenz:

• Verwenden Sie eine bestimmte Abfrage, die auf ein bekanntes Symptom anstatt auf eine allgemeine Frage ausgerichtet ist. Beispielsweise ist "die DNS-Auflösung für den Dienst my-svc im Namespace my-ns überprüfen" schneller als "alle Netzwerkprobleme diagnostizieren".
• Stellen Sie sicher, dass sich Ihre Azure OpenAI-Ressource in derselben Azure Region wie Ihr AKS-Cluster befindet, um die Netzwerk-Roundtripzeit zu minimieren.
• Überprüfen Sie Ihr Azure OpenAI TPM-Kontingent – ein höheres Kontingent ermöglicht die parallele Tokenverarbeitung.

Diagnosebefehle, bei denen es zum Timeout kommt

Symptom: Der Agent meldet ein Timeout eines Befehls, oder der Chat reagiert für mehr als 10 Minuten nicht, bevor ein Fehler angezeigt wird.

Ursache: Das Standardtimeout für Diagnosebefehle (kubectl, cilium, hubble) beträgt 600 Sekunden (10 Minuten). Breite Abfragen , z. B. das Sammeln von Statistiken von jedem Knoten in einem großen Cluster, können diesen Grenzwert überschreiten.

Lösung:

• Beschränken Sie ihre Abfrage auf einen bestimmten Knoten, einen bestimmten Pod oder einen Namespace anstelle des gesamten Clusters. Beispiel:

  • Statt: "Paketverluste auf allen Knoten prüfen"
  • Fragen Sie: "Paketverluste auf dem Knoten <specific-node-name> überprüfen"

• Wenn Timeouts für einen Abfragetyp konsistent auftreten, kann der Cluster Leistungs- oder Konnektivitätsprobleme haben, die die Befehlsantworten unabhängig voneinander verlangsamen.

• Überprüfen Sie die Pod-Protokolle auf Einträge im Zusammenhang mit Timouts:

  kubectl logs -n kube-system -l app=container-networking-agent | grep -i "timeout\|timed out"
  

Nach dem Neustart des Pods gehen die Sitzungsdaten verloren.

Symptom: Alle Chatverlaufs- und aktiven Sitzungen verschwinden nach dem Neustart des Pods.

Ursache: Sitzungsdaten werden nur im Arbeitsspeicher gespeichert. Alle Daten gehen verloren, wenn der Pod neu gestartet wird.

Auflösung: Dies wird für die aktuelle Architektur erwartet. Starten Sie nach einem Pod-Neustart eine neue Sitzung.

Die Sitzung läuft unerwartet ab

Symptom: Sie werden während einer aktiven Sitzung ohne Warnung abgemeldet, oder Ihre Sitzung endet nach einem Zeitraum der Inaktivität, obwohl Sie die Erweiterung verwendet haben.

Ursache: Der Container Network Insights-Agent erzwingt Sitzungstimeouts für die Sicherheit. Es gelten zwei unabhängige Grenzwerte:

Lösung: Melden Sie sich erneut an, um eine neue Sitzung zu starten. Der Chatverlauf aus der abgelaufenen Sitzung kann nicht wiederhergestellt werden.

Der Chat-Kontext scheint nach vielen Interaktionen verloren gegangen zu sein

Symptom: Nach ca. 15 Austauschen scheint der Agent frühere Teile der Unterhaltung zu vergessen oder verweist nicht auf den Kontext früher in der Sitzung.

Ursache: Der Container Network Insights Agent fasst den Unhaltungsverlauf zusammen, um das Azure OpenAI-Token-Limit nicht zu überschreiten. Wenn das Kontextfenster ungefähr 15 Nachrichten erreicht, werden ältere Nachrichten durch eine automatisch generierte Zusammenfassung ersetzt. Die neuesten Nachrichten und die Zusammenfassung werden beibehalten und an das Modell übergeben.

Auflösung: Dies ist ein erwartetes Verhalten. Die Zusammenfassung behält den wichtigen Diagnosekontext bei, während Azure OpenAI-Tokengrenzwerte verwaltet werden. Wenn Sie in der Unterhaltung auf etwas von viel früherer Zeit verweisen müssen:

• Wiederholen Sie den relevanten Kontext: "Früher haben Sie X gefunden – können Sie weiter untersuchen?"
• Beginnen Sie eine neue Unterhaltung mit einer präzisen Zusammenfassung der bekannten Ergebnisse.

Unterhaltungslimit erreicht

Symptom: Die Benutzeroberfläche zeigt einen Fehler an, dass Sie keine neue Unterhaltung erstellen können, oder die ältesten Unterhaltungen verschwinden, ohne explizit gelöscht zu werden.

Ursache: Jedes Benutzerkonto ist auf 20 aktive Unterhaltungen beschränkt. Wenn dieser Grenzwert erreicht ist, werden die beiden ältesten Unterhaltungen automatisch entfernt, um Platz zu schaffen, beginnend mit der Anzahl von 18 (90% des Grenzwerts von 20 Unterhaltungen).

Auflösung: Dieses automatische Bereinigungsverhalten wird erwartet. Wenn Sie keine neue Unterhaltung erstellen können, warten Sie kurz, bis die Hintergrundbereinigung ausgeführt wird, und versuchen Sie es dann erneut. Die beiden am wenigsten kürzlich verwendeten Unterhaltungen werden automatisch entfernt.

Debug DaemonSet bleibt nach einem Absturz erhalten

Symptom: Das rx-troubleshooting-debug DaemonSet verbleibt nach einer Diagnosesitzung im kube-system Namespace.

Ursache: Der Container Network Insights Agent setzt während der Paketverlust-Diagnose ein einfaches Debug-DaemonSet ein. Wenn der Agent-Pod während dieser Diagnose unerwartet abstürzt, wird der Bereinigungsschritt nicht ausgeführt.

Auflösung: Manuelles Löschen des DaemonSets:

kubectl delete ds rx-troubleshooting-debug -n kube-system

Paketverlustdiagnose schlägt fehl

Symptom: Wenn Sie den Agent bitten, Paketverluste zu untersuchen, meldet er Fehler bei der Bereitstellung von Diagnose-Pods oder kann keine Statistiken auf Knotenebene sammeln.

Ursache: Die Paketablagediagnose stellt für jeden Knoten ein einfaches DaemonSet (rx-troubleshooting-debug) bereit, um Netzwerkstatistiken auf Hostebene (Ethtool-Statistiken, Softnetzähler, Ringpufferstatus) zu sammeln. Fehler treten auf, wenn das Dienstkonto des Agents nicht über die Berechtigung zum Erstellen von DaemonSets kube-systemverfügt oder Knoten den erforderlichen privilegierten Zugriff blockieren, um Hostnetzwerkstatistiken zu sammeln.

Lösung:

1. Überprüfen Sie, ob das DaemonSet erstellt wurde:

   kubectl get daemonset -n kube-system rx-troubleshooting-debug
   

   Wenn sie nicht vorhanden ist, ist der Bereitstellungsschritt fehlgeschlagen. Überprüfen Sie die Pod-Protokolle:

   kubectl logs -n kube-system -l app=container-networking-agent | grep -i "daemonset\|rx\|packet\|error"
   

2. Wenn das DaemonSet erstellt wurde, aber seine Pods nicht starten, beschreiben Sie sie, um die Ursache zu finden:

   kubectl describe pods -n kube-system -l app=cna-diagnostic
   

3. Überprüfen Sie, ob der dem Agenten zugewiesene ClusterRole die Berechtigungen zur Erstellung von DaemonSets enthält.

   kubectl get clusterrole -l app=container-networking-agent -o yaml | grep -A2 daemonset
   

4. Wenn das DaemonSet von einer fehlgeschlagenen Ausführung übrig bleibt, löschen Sie es manuell, und bitten Sie den Agent, den Vorgang erneut auszuführen:

   kubectl delete daemonset -n kube-system -l app=cna-diagnostic
   

DNS-Diagnose gibt unvollständige oder keine Ergebnisse zurück.

Symptom: Bei der Problembehandlung eines DNS-Problems gibt der Agent partielle Diagnosedaten zurück, meldet Fehler bei der Ausführung von DNS-Prüfungen oder beendet die Untersuchung ohne Ergebnisse.

Ursache: Die DNS-Diagnosetools des Agents führen Auflösungstests aus und prüfen CoreDNS aus dem Cluster heraus. Unvollständige Ergebnisse können auftreten, wenn das Dienstkonto des Agents keinen Lesezugriff auf Clusterebene hat, auf CoreDNS-Pods nicht zugegriffen werden kann oder einzelne Befehle auf das Timeout von 30 Sekunden pro Befehl klicken.

Lösung:

1. Überprüfen Sie, ob CoreDNS ausgeführt wird:

   kubectl get pods -n kube-system -l k8s-app=kube-dns
   

   Wenn die CoreDNS-Pods nicht ausgeführt werden, ist das die Ursache dafür. Beschreiben Sie diese für nähere Einzelheiten.

   kubectl describe pods -n kube-system -l k8s-app=kube-dns
   

2. Stellen Sie sicher, dass die verwaltete Identität über die Azure Kubernetes Service Cluster User Role-Zuweisung für den Cluster verfügt. Mit dieser Rolle kann der Agent kubeconfig abrufen und kubectl-Befehle ausführen:

   az role assignment list --assignee <identity-principal-id> --all -o table
   

3. Wenn der Agent während der DNS-Überprüfung Befehlszeitüberschreitungen meldet, schränken Sie den Umfang Ihrer Anfrage ein. Anstatt beispielsweise "alle DNS-Probleme zu diagnostizieren", formulieren Sie die Frage "DNS-Auflösung für Pod <pod-name> im Namespace <namespace> überprüfen".

Agent stoppt die Ermittlung mitten im Prozess

Symptom: Der Agent beginnt eine Diagnoseuntersuchung, stoppt jedoch, bevor er abgeschlossen wird, ohne eine Ursachenanalyse oder einen Abschlussbericht bereitzustellen.

Ursache: Mehrere Faktoren können eine mehrstufige Untersuchung unterbrechen:

• Timeout eines Diagnosebefehls.
• Die Azure OpenAI-Ratenbeschränkung oder Tokenbeschränkung wurde während der Untersuchung erreicht.
• Das Kontextfenster des Unterhaltungsverlaufs hat den Schwellenwert für Zusammenfassungen erreicht, was dazu führt, dass der Agent den aktuellen Plan nicht mehr nachvollziehen kann.

Lösung:

• Bitten Sie den Agent, die Unterhaltung fortzusetzen: "Please continue the investigation" oder "What other checks can you run?". Der Agent kann die Unterhaltung auch vom aktuellen Stand aus fortsetzen.
• Wenn Timeouts die Ursache sind, beschränken Sie die nächste Abfrage enger. Beispiel: "Überprüfen Sie den spezifischen Namespace <name>" anstelle des vollständigen Clusters.
• Wenn die Untersuchung aufgrund einer Zinsbegrenzung beendet wurde, warten Sie eine Minute, und bitten Sie den Agent, den Vorgang fortzusetzen.
• Öffnen Sie für einen neuen Start eine neue Unterhaltung und geben Sie eine kurze Zusammenfassung der bereits gefundenen Informationen an: "Ich habe bestätigt, dass die DNS-Auflösung im Namespace X fehlschlägt. Können Sie die NetworkPolicy für diesen Namespace untersuchen?"

Die Workloadidentität ist im Cluster nicht aktiviert.

Symptom: Einrichtung von Verbundanmeldeinformationen schlägt fehl, oder der Agent-Pod kann sich nicht bei Azure authentifizieren. Pod-Protokolle zeigen "Failed to acquire token" oder "AADSTS..." Fehler an.

Ursache: Der AKS-Cluster wurde erstellt, ohne dass die Identität des OIDC-Ausstellers oder der Workload aktiviert war.

Auflösung: Aktivieren Sie beide Features in Ihrem vorhandenen Cluster mithilfe des az aks update Befehls:

az aks update \
  --resource-group $RESOURCE_GROUP \
  --name $CLUSTER_NAME \
  --enable-oidc-issuer \
  --enable-workload-identity

Führen Sie nach dem Aktivieren die Einrichtungsschritte für Verbundanmeldeinformationen aus dem Bereitstellungshandbuch erneut aus, um die verwaltete Identität mit dem Kubernetes-Dienstkonto zu verknüpfen.

Azure OpenAI-Modell in der ausgewählten Region nicht verfügbar

Symptom: Azure OpenAI-Bereitstellungserstellung schlägt fehl, oder der Start des Container Network Insights-Agents schlägt unmittelbar nach der Bereitstellung mit einem Endpunkt- oder Modellfehler fehl.

Cause: Das ausgewählte Azure OpenAI-Modell ist in ihrer ausgewählten Azure Region nicht verfügbar.

Lösung:

1. Überprüfen Sie, welche Modelle in Ihrer Region verfügbar sind:

   az cognitiveservices model list -l <your-region> --output table
   

2. Verwenden Sie eine Region, in der Ihr Zielmodell verfügbar ist. Weitere Informationen zur aktuellen Verfügbarkeit finden Sie in der Azure OpenAI-Modellregion-Unterstützung-Referenz.

3. Vergewissern Sie sich, dass Ihr Abonnement über ausreichende Token-Per-Minute (TPM)-Kontingent für das Modell verfügt. Wenn die Modellbereitstellung mit einem Kontingentfehler fehlschlägt, fordern Sie eine Kontingenterhöhung im Azure Portal unter Cognitive Services > Quotas an.

Schnelle Diagnosebefehle

Verwenden Sie diese Befehle, um häufig auftretende Probleme schnell zu diagnostizieren:

# ──── Pod Status ────
kubectl get pods -n kube-system -l app=container-networking-agent
kubectl describe pod -n kube-system -l app=container-networking-agent
kubectl top pod -n kube-system -l app=container-networking-agent

# ──── Application Logs ────
kubectl logs -n kube-system -l app=container-networking-agent --tail=200
kubectl logs -n kube-system -l app=container-networking-agent -f              # Stream live
kubectl logs -n kube-system -l app=container-networking-agent | grep ERROR     # Errors only

# ──── Health Checks (requires port-forward) ────
kubectl port-forward svc/container-networking-agent-service -n kube-system 8080:80
curl -s http://localhost:8080/ready | jq
curl -s http://localhost:8080/live | jq
curl -s http://localhost:8080/api/status/sessions | jq

# ──── Configuration ────
kubectl get configmap -n kube-system -l app=container-networking-agent -o yaml
kubectl get serviceaccount container-networking-agent-reader -n kube-system -o yaml

# ──── Workload Identity ────
kubectl describe serviceaccount container-networking-agent-reader -n kube-system
az identity show --name $IDENTITY_NAME -g $RESOURCE_GROUP --query "{clientId:clientId, principalId:principalId}"

# ──── RBAC ────
az role assignment list --assignee <principal-id> --output table

# ──── Extension Status ────
az k8s-extension show \
  --cluster-name $CLUSTER_NAME \
  --resource-group $RESOURCE_GROUP \
  --cluster-type managedClusters \
  --name containernetworkingagent \
  --query "{state:provisioningState, version:version}" -o table

# ──── Cleanup Stuck Resources ────
kubectl delete daemonset rx-troubleshooting-debug -n kube-system    # Leftover diagnostic DaemonSet
kubectl delete pod -n kube-system -l app=container-networking-agent    # Force pod restart

Nächste Schritte

• Bereitstellen und Verwenden des Container Network Insights-Agents auf AKS
• Übersicht über den Container Network Insights Agent
• Übersicht über fortgeschrittene Container Networking Services
• Azure CNI unterstützt von Cilium