Risolvere i problemi dell'agente di Azure Container Network Insights su AKS

Questo articolo affronta i problemi comuni che possono verificarsi durante la distribuzione, la configurazione o l'uso dell'agente di Container Network Insights su AKS. Ogni sezione segue un formato → Causa → risoluzione dei sintomi .

Per le istruzioni di distribuzione, vedere Distribuire e usare l'agente di Container Network Insights su AKS.

L'installazione dell'estensione non riesce

Sintomo: Il az k8s-extension create comando non riesce oppure lo stato di provisioning dell'estensione mostra Failed.

Causa: area di cloud sovrano (l'estensione è supportata solo nelle aree pubbliche di Azure), funzionalità del cluster mancanti, o autorizzazioni insufficienti.

Risoluzione:

1. Controllare lo stato di provisioning dell'estensione per ottenere i dettagli:

   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. Verificare che il cluster si trova in un'area pubblica Azure. L'estensione è disponibile in tutte le aree pubbliche di Azure in cui è supportato AKS, ma non è disponibile in Azure per enti pubblici, Microsoft Azure gestito da 21Vianet o da altri cloud sovrani.

3. Verificare che il cluster abbia l'identità del carico di lavoro e l'emittente OIDC abilitati:

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

4. Verificare di avere i ruoli Contributor e User Access Administrator nel gruppo di risorse.

5. Se hai già eseguito az k8s-extension create una volta, eseguendolo di nuovo restituirà un errore perché l'estensione esiste già. Usare az k8s-extension update per modificare le impostazioni di configurazione in un'estensione esistente:

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

Errori di identità e autorizzazioni

Sintomo: Il pod agente si avvia ma restituisce 401 Unauthorized o 403 Forbidden errori durante l'elaborazione delle richieste. I log dei pod mostrano errori di autenticazione o autorizzazione.

Causa: L'identità gestita manca delle assegnazioni di ruolo RBAC richieste oppure il soggetto delle credenziali federate non corrisponde all'account del servizio dell'agente.

Risoluzione:

1. Verificare che l'identità gestita abbia tutte e quattro le assegnazioni di ruolo necessarie:

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

   Verificare che siano presenti questi ruoli:

   Ruolo	Ambito
   Cognitive Services OpenAI User	Risorsa OpenAI di Azure
   Azure Kubernetes Service Cluster User Role	Cluster AKS
   Azure Kubernetes Service Contributor Role	Cluster AKS
   Reader	Gruppo di risorse

2. Verificare che l'identità del carico di lavoro sia abilitata nel cluster:

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

3. Verificare che l'oggetto delle credenziali federate corrisponda all'account del servizio:

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

   Il subject campo deve essere system:serviceaccount:kube-system:container-networking-agent-reader.

4. Verificare che l'account del servizio Kubernetes abbia l'annotazione corretta dell'identità del carico di lavoro:

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

   L'annotazione azure.workload.identity/client-id deve corrispondere all'ID client dell'identità gestita. Se non corrisponde, correggerlo e riavviare il pod:

   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
   

Problemi di connettività di Azure OpenAI

Sintomo: Il pod agente viene avviato ma le richieste di chat hanno esito negativo. I log dei pod mostrano 401 Unauthorized, 404 Not Found o errori di connessione che fanno riferimento all'endpoint OpenAI Azure.

Cause: L'endpoint Azure OpenAI, il nome della distribuzione o le credenziali di identità gestite non sono configurati correttamente o il traffico di rete verso l'endpoint viene bloccato.

Risoluzione:

1. Controllare i log dei pod per individuare modelli di errore specifici:

   Messaggio di log	Motivo	Correzione
   401 Unauthorized	Ruolo mancante dell'identità gestita Cognitive Services OpenAI User	Assegnare il ruolo alla risorsa OpenAI
   404 Not Found	URL dell'endpoint errato o nome della distribuzione	Verificare AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_DEPLOYMENT
   Connection refused / Name resolution failed	Problema di rete o DNS	Controllare le regole del gruppo di sicurezza di rete/del firewall e verificare il nome host dell'endpoint
   Token acquisition failed	Identità del carico di lavoro non configurata	Controllare l'annotazione dell'account di servizio e le credenziali federate

2. Verificare che l'identità gestita abbia il ruolo Cognitive Services OpenAI User nella risorsa Azure OpenAI:

   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. Se si utilizzano criteri di rete, Firewall di Azure o gruppi di sicurezza della rete (NSG), assicurarsi che il traffico HTTPS in uscita (porta 443) sia consentito dallo spazio dei nomi kube-system al proprio endpoint OpenAI Azure. Verificare che nessun criterio di rete blocchi il traffico in uscita:

   kubectl get networkpolicies -n kube-system
   

Errori di registrazione dell'app e autenticazione Entra ID

Sintomo il flusso di accesso Microsoft Entra ID (MSAL) ha esito negativo, i reindirizzamenti di accesso restituiscono errori o i log del pod mostrano il valore segnaposto 44444444-4444-4444-4444-444444444444 per ENTRA_CLIENT_ID.

Causa: La registrazione dell'app non è configurata correttamente o non è stata impostata durante la ENTRA_CLIENT_ID distribuzione dell'estensione.

Risoluzione:

1. Se i log dei pod mostrano il valore segnaposto 44444444-4444-4444-4444-444444444444, aggiornare l'estensione con l'ID client effettivo della registrazione dell'app:

   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. Se il callback di accesso ha esito negativo e viene visualizzato un errore redirect_uri mismatch, verificare l'URI di reindirizzamento nel portale di Azure in Registrazioni delle app > La tua app > Autenticazione > Redirect URIs. Per l'accesso locale con port forwarding, l'URI deve essere http://localhost:8080/auth/callback.

   Annotazioni

   Attualmente sono supportati solo localhost gli URI di reindirizzamento. Gli URL di LoadBalancer pubblici non sono supportati per gli URI di reindirizzamento.

3. Verificare che la registrazione dell'app disponga delle autorizzazioni delegate necessarie Microsoft Graph: openid, profile, User.Read, offline_access. Se è necessario il consenso dell'amministratore, concederlo:

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

4. Controllare i log dei pod per verificare la presenza di errori specifici dell'autenticazione:

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

Variabili di ambiente mancanti all'avvio

Sintomo: Il pod agente si arresta immediatamente all'avvio con:

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

Causa: Uno o più valori di configurazione necessari non sono stati impostati quando è stata distribuita l'estensione.

Risoluzione:

1. Controllare la ConfigMap per verificare i valori segnaposto o le impostazioni mancanti.

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

2. Verificare che queste variabili obbligatorie siano impostate con valori reali (non segnaposto come 00000000-0000-0000-0000-000000000000):

   Variable	Descrizione	Esempio
   AZURE_OPENAI_ENDPOINT	Azure endpoint della risorsa OpenAI	https://your-instance.openai.azure.com/
   AZURE_OPENAI_DEPLOYMENT	Nome della distribuzione del modello	gpt-4o
   AZURE_OPENAI_API_VERSION	Versione dell'API	2025-03-01-preview
   AZURE_CLIENT_ID	ID client dell'identità gestita	UUID (Identificatore Unico Universale)
   AZURE_TENANT_ID	ID tenant Azure	UUID (Identificatore Unico Universale)
   AZURE_SUBSCRIPTION_ID	ID sottoscrizione Azure	UUID (Identificatore Unico Universale)
   AKS_CLUSTER_NAME	Nome del cluster AKS	Nome del cluster
   AKS_RESOURCE_GROUP	Gruppo di risorse cluster	Il tuo gruppo di risorse

3. Se i valori mostrano segnaposto, aggiornare l'estensione con le impostazioni corrette:

   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>
   

Pod agente non in esecuzione o si arresta in modo anomalo

Sintomo: Il pod dell'agente è nello stato CrashLoopBackOff, Error o Pending.

Cause: Configurazione errata, mancanza di connettività ad Azure OpenAI o risorse del cluster insufficienti.

Risoluzione:

1. Controllare gli eventi del pod per eventuali errori immediati.

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

2. Controllare i log dei pod per i messaggi di errore:

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

3. Trovare le corrispondenze tra i messaggi di log e le cause note:

   Messaggio di log	Motivo	Correzione
   Missing required Azure OpenAI environment variable(s)	ConfigMap ha valori segnaposto	Impostare i valori corretti tramite az k8s-extension update
   bootstrap.validation_agent_failed	Non è possibile connettersi a Azure OpenAI	Controllare la rete, l'URL dell'endpoint e il RBAC dell'identità gestita
   AKS MCP binary not found	File binario mancante nell'immagine	Usare l'immagine di estensione ufficiale da acnpublic.azurecr.io
   FailedMount / errore di montaggio del volume	Segreti del certificato Hubble mancanti	Eseguire la distribuzione con hubble.enabled=false o assicurarsi che ACNS sia abilitato
   Token acquisition failed	Identità del carico di lavoro non configurata	Controllare l'annotazione dell'account di servizio e le credenziali federate

4. Verificare che l'endpoint OpenAI Azure sia raggiungibile dal cluster. Se si usano restrizioni in uscita, assicurarsi che HTTPS in uscita (porta 443) sia consentito dallo spazio dei nomi kube-system all'endpoint Azure OpenAI.

Errori del probe di idoneità

Sintomo: Il pod è Running ma mostra lo stato pronto 0/1. L'endpoint /ready restituisce HTTP 503.

Causa: Uno o più controlli di avvio non sono stati completati: il pool di agenti di riscaldamento non è ancora inizializzato, le proprietà del cluster presentano errori o non sono disponibili agenti pre-riscaldati.

Risoluzione:

1. Attendere fino a 2-3 minuti dopo l'implementazione affinché il pool di riscaldamento crei agenti pre-riscaldati.

2. Controllare la risposta di prontezza per le cause di errore specifiche.

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

3. Controllare i log dei pod per individuare i problemi correlati al riscaldamento:

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

4. Se le proprietà del cluster hanno esito negativo, verificare che AKS_CLUSTER_NAME, AKS_RESOURCE_GROUPe AZURE_SUBSCRIPTION_ID siano impostate correttamente nella configurazione dell'estensione.

Il pool di riscaldamento continua a non riuscire

Sintomo: Il pod è Running ma non diventa mai pronto. I log dei pod mostrano errori ripetuti "Failed to create warmed agent" anche dopo alcuni minuti di attesa.

Causa: Il pool di pre-riscaldamento in background non riesce a creare istanze dell'agente pre-riscaldate. Ciò è in genere causato da un problema di connettività OpenAI non risolto Azure o da un errore di inizializzazione MCP che impedisce la creazione degli agenti.

Risoluzione:

1. Controllare i log per l'errore sottostante specifico:

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

2. Trova la corrispondenza dell'errore con la correzione:

   Errore nei log	Correzione
   401 Unauthorized oppure 403 Forbidden	Vedere Problemi di connettività Azure OpenAI e verificare l'assegnazione del ruolo di identità gestita
   Token acquisition failed	Vedere Errori di identità e autorizzazioni
   404 Not Found nell'endpoint	Verificare AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_DEPLOYMENT nel ConfigMap
   AKS MCP binary not found	Vedere Pod agente non in esecuzione o si arresta in modo anomalo

3. Una volta risolto il problema sottostante, il pool di riscaldamento si riattiva automaticamente. Non è necessario riavviare il pod a meno che l'errore persiste dopo la correzione della causa radice.

I comandi hubble non riescono

Sintomo: L'agente segnala errori per la diagnostica correlata a Hubble o l'analisi del flusso Hubble non è disponibile.

Causa: Il cluster non dispone di Advanced Container Networking Services (ACNS) o del piano dati Cilium abilitato.

Risoluzione:

• Se il cluster non usa ACNS, distribuire l'estensione con hubble.enabled=false e config.AKS_MCP_ENABLED_COMPONENTS=kubectl. L'agente fornisce comunque diagnostica DNS, sul drop dei pacchetti e di rete standard Kubernetes, senza Hubble.

• Per abilitare Hubble, il cluster deve usare Azure CNI con tecnologia Cilium con Advanced Container Networking Services (ACNS) abilitato.

• Verificare che Hubble sia in esecuzione nel cluster:

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

  Se non viene restituito alcun pod, Hubble non è abilitato. Abilitare ACNS nel cluster o impostare hubble.enabled=false nella configurazione dell'estensione.

Limitazione della frequenza di chat

Sintomo: Le richieste di chat restituiscono HTTP 429 con intestazioni di risposta X-RateLimit-* o X-LLM-RateLimit-*.

Causa: Il limitatore di velocità predefinito sta limitando le richieste per proteggere il servizio.

Risoluzione:

L'agente di Container Network Insights di Azure ha tre livelli di limitazione della frequenza.

• Per gli errori di chat 429: ridurre la frequenza dei messaggi e attendere il riempimento del bucket limite di velocità.
• Per gli errori LLM 429: controllare la quota di token al minuto (TPM) di Azure OpenAI nel portale di Azure. È possibile richiedere un aumento della quota sotto Servizi cognitivi > Quote se è necessaria una larghezza di banda più elevata.

Messaggio di chat inviato ma nessuna risposta

Sintomo: Viene inviato un messaggio di chat ma non viene visualizzata alcuna risposta. La richiesta si blocca o restituisce un errore di timeout.

Causa: Azure OpenAI potrebbe essere soggetto a limitazioni o non raggiungibile, non potrebbero essere ancora disponibili agenti pre-riscaldati, oppure potrebbe essere in corso l'esecuzione di un comando diagnostico di lunga durata.

Risoluzione:

1. Controllare se il pod ha sessioni attive e se viene assegnato un agente:

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

2. Controllare i log dei pod per individuare i modelli di errore:

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

   Indicatore del log	Motivo	Correzione
   429 Errori	Velocità di Azure OpenAI limitata	Attendere che il limite di velocità venga reimpostato; controllare la quota TPM
   "No pre-warmed agents available"	Pool di riscaldamento non pronto	Attendere l'inizializzazione; vedere Il pool di riscaldamento continua a non riuscire
   Timeout di connessione	Problema di rete o NSG	Controllare la rete dei pod, DNS e le regole del gruppo di sicurezza di rete (NSG)

3. Se la richiesta è ancora in sospeso dopo 2 minuti, avviare una nuova conversazione e inviare prima una query semplice (ad esempio, "elencare i pod nello spazio dei nomi predefinito") per verificare che l'agente risponda prima di porre una domanda diagnostica complessa.

Prima richiesta lenta

Sintomo: Il primo messaggio di chat dopo il riavvio della distribuzione o del pod richiede 10-30 secondi per rispondere.

Causa: L'agente Di Azure Container Network Insights gestisce un pool di agenti pre-riscaldati per ridurre la latenza. Dopo il riavvio di un pod, il pool di riscaldamento richiede tempo per inizializzare ogni agente, che richiede l'avvio del plug-in MCP, la configurazione delle credenziali Azure e l'inizializzazione del framework di intelligenza artificiale.

Risoluzione: Si tratta di un comportamento previsto. Attendere che l'endpoint /ready restituisca HTTP 200 prima di inviare richieste, il che conferma che è disponibile almeno un agente pre-riscaldato. Le richieste successive usano il pool pre-riscaldato e rispondono più velocemente (in genere 5-10 secondi per le query semplici).

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

Risposte lente per la diagnostica complessa

Sintomo: Il completamento delle risposte di diagnostica richiede da 30 secondi a 2 minuti.

Cause: la diagnostica in più passaggi implica operazioni sequenziali: una chiamata di classificazione LLM iniziale a Azure OpenAI, più comandi kubectl/cilium/hubble eseguiti sul cluster e un'analisi LLM finale delle prove raccolte. Ogni passaggio aggiunge latenza.

Risoluzione: Questo è previsto per la diagnostica complessa. La tabella seguente illustra i tempi di risposta tipici:

Per ridurre la latenza:

• Usare una query specifica che ha come destinazione un sintomo noto anziché una domanda generale. Ad esempio, "controllare la risoluzione DNS per il servizio my-svc nello spazio dei nomi my-ns" è più veloce di "diagnosticare tutti i problemi di rete".
• Assicurarsi che la risorsa Azure OpenAI si trovi nella stessa regione Azure del cluster AKS per ridurre al minimo il tempo di andata e ritorno della rete.
• Controllare la quota Azure TPM OpenAI. La quota più elevata consente un'elaborazione di token parallela maggiore.

Timeout dei comandi diagnostici

Sintomo: L'agente segnala un timeout del comando o la chat smette di rispondere per più di 10 minuti prima di restituire un errore.

Causa: Il timeout predefinito per i comandi di diagnostica (kubectl, cilium, hubble) è di 600 secondi (10 minuti). Le query generali, ad esempio la raccolta di statistiche da ogni nodo in un cluster di grandi dimensioni, possono superare questo limite.

Risoluzione:

• Definire l'ambito della query su un nodo, un pod o uno spazio dei nomi specifico anziché l'intero cluster. Per esempio:

  • Invece di: "Controlla le perdite di pacchetti in tutti i nodi"
  • Chiedi: "Controlla gli scarti di pacchetti sul nodo <specific-node-name>"

• Se i timeout si verificano in modo coerente in un tipo di query, il cluster potrebbe avere problemi di prestazioni o connettività che rallentano in modo indipendente le risposte ai comandi.

• Controllare i log dei pod per le voci relative al timeout:

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

Dati della sessione persi dopo il riavvio del pod

Sintomo: Tutte le sessioni attive e la cronologia delle chat scompaiono dopo il riavvio del pod.

Causa: I dati della sessione vengono archiviati solo in memoria. Tutti i dati vengono persi al riavvio del pod.

Risoluzione: Questo comportamento è previsto per l'architettura corrente. Avviare una nuova sessione dopo il riavvio di un pod.

La sessione scade in modo imprevisto

Sintomo: L'utente viene disconnesso senza avviso durante una sessione attiva o la sessione termina dopo un periodo di inattività anche se si usa l'estensione.

Causa: L'agente Container Network Insights applica i timeout di sessione per la sicurezza. Si applicano due limiti indipendenti:

Risoluzione: Accedere di nuovo per avviare una nuova sessione. La cronologia delle chat dalla sessione scaduta non è recuperabile.

Il contesto di chat viene perso dopo molti scambi

Sintomo: Dopo circa 15 scambi, l'agente sembra dimenticare le parti precedenti della conversazione o non fa riferimento al contesto precedente della sessione.

Cause: Container Network Insights Agent riepiloga la cronologia delle conversazioni per rimanere entro il limite di token OpenAI Azure. Quando la finestra di contesto raggiunge circa 15 messaggi, i messaggi meno recenti vengono sostituiti da un riepilogo generato automaticamente. I messaggi più recenti e il riepilogo vengono conservati e passati al modello.

Risoluzione: Si tratta di un comportamento previsto. Il riepilogo mantiene il contesto diagnostico chiave durante la gestione dei limiti dei token di Azure OpenAI. Se è necessario fare riferimento a qualcosa di molto precedente nella conversazione:

• Ripetere il contesto pertinente: "In precedenza è stata trovata X- è possibile approfondire l'analisi?"
• Avviare una nuova conversazione con un riepilogo conciso dei risultati noti.

Limite di conversazioni raggiunto

Sintomo: L'interfaccia mostra un errore che non è possibile creare una nuova conversazione o che le conversazioni meno recenti scompaiono senza essere eliminate in modo esplicito.

Causa: Ogni account utente è limitato a 20 conversazioni attive. Quando viene raggiunto questo limite, le due conversazioni meno recenti vengono rimosse automaticamente per fare spazio, a partire da quando il conteggio raggiunge 18 (90% del limite di 20 conversazioni).

Risoluzione: Questo comportamento di pulizia automatica è previsto. Se non è possibile creare una nuova conversazione, attendere brevemente che venga eseguita la pulizia in background, quindi riprovare. Le due conversazioni usate meno di recente vengono rimosse automaticamente.

Debug DaemonSet persiste dopo un arresto anomalo

Sintomo: Il rx-troubleshooting-debug DaemonSet rimane nel kube-system namespace dopo una sessione di diagnostica.

Causa: Container Network Insights Agent distribuisce un DaemonSet di debug leggero durante la diagnostica di una perdita di pacchetti. Se il pod agente si arresta in modo imprevisto durante questa procedura di diagnostica, la fase di pulizia non viene eseguita.

Risoluzione: Eliminare manualmente DaemonSet:

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

La diagnostica della perdita dei pacchetti fallisce

Sintomo: Quando si chiede all'agente di analizzare le perdite di pacchetti, riporta errori durante il deployment dei pod di diagnostica o l'impossibilità di raccogliere statistiche a livello di nodo.

Causa: La diagnostica di rilascio dei pacchetti distribuisce un DaemonSet leggero (rx-troubleshooting-debug) in ogni nodo per raccogliere statistiche di rete a livello di host (statistiche ethtool, contatori softnet, stato buffer circolare). Gli errori si verificano se l'account del servizio dell'agente non dispone dell'autorizzazione per creare DaemonSet in kube-systemo se i nodi bloccano l'accesso con privilegi necessario per raccogliere le statistiche di rete host.

Risoluzione:

1. Controllare se DaemonSet è stato creato:

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

   Se non esiste, il passaggio di distribuzione non è riuscito. Controlla i log dei pod:

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

2. Se il DaemonSet è stato creato ma i relativi pod non vengono avviati, descriverli per trovare la causa:

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

3. Verificare che ClusterRole assegnato all'agente includa le autorizzazioni di creazione DaemonSet:

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

4. Se il DaemonSet viene lasciato da un'esecuzione non riuscita, eliminarlo manualmente e chiedere all'agente di riprovare:

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

La diagnostica DNS restituisce risultati incompleti o nessun risultato

Sintomo: Quando si risolve un problema DNS, l'agente restituisce dati di diagnostica parziali, segnala errori che eseguono controlli DNS o esce dall'indagine senza risultati.

Causa: Gli strumenti di diagnostica DNS dell'agente eseguono test di risoluzione ed esaminano CoreDNS dall'interno del cluster. I risultati incompleti possono verificarsi se l'account del servizio dell'agente non dispone dell'accesso in lettura a livello di cluster, i pod CoreDNS non sono accessibili o i singoli comandi raggiungono il timeout di 30 secondi per comando.

Risoluzione:

1. Verificare che CoreDNS sia in esecuzione:

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

   Se i pod CoreDNS non sono in esecuzione, questa è la causa principale. Descrivili per maggiori dettagli.

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

2. Verificare che l'identità gestita disponga dell'assegnazione servizio Azure Kubernetes Cluster User Role nel cluster. Questo ruolo consente all'agente di recuperare kubeconfig ed eseguire i comandi kubectl:

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

3. Se l'agente segnala i timeout dei comandi durante i controlli DNS, limita l'ambito della domanda. Ad esempio, invece di "diagnosticare tutti i problemi DNS", chiedere "controllare la risoluzione DNS per il pod <pod-name> nello spazio dei nomi <namespace>".

L'agente interrompe l'indagine a metà.

Sintomo: L'agente avvia un'indagine diagnostica ma si arresta prima di completarlo, senza fornire un'analisi della causa radice o un report finale.

Causa: Diversi fattori possono interrompere un'indagine in più passaggi:

• Timeout del comando di diagnostica.
• Il limite di velocità o il limite di token di Azure OpenAI è stato raggiunto nel mezzo dell'indagine.
• La finestra di contesto della cronologia delle conversazioni ha raggiunto la soglia di riepilogo, causando all'agente di perdere il filo del piano corrente.

Risoluzione:

• Chiedi all'agente di continuare nella stessa conversazione: "Please continue the investigation" oppure "What other checks can you run?", e l'agente può riprendere dallo stato corrente.
• Se i timeout sono la causa, definire l'ambito della query successiva in modo più ristretto. Ad esempio, "controllare lo specifico spazio dei nomi <name>" anziché controllare il cluster completo.
• Se l'indagine è stata arrestata a causa della limitazione della velocità, attendere un minuto e chieda all'agente di procedere.
• Per iniziare da capo, avviare una nuova conversazione e fornire un riepilogo conciso di ciò che è stato già trovato: "Ho confermato che la risoluzione DNS non riesce nello spazio dei nomi X. Puoi indagare sul NetworkPolicy per quello spazio dei nomi?"

Identità del carico di lavoro non abilitata nel cluster

Symptom: l'installazione delle credenziali federate non riesce oppure il pod dell'agente non può eseguire l'autenticazione per Azure. I log dei pod mostrano errori "Failed to acquire token" o "AADSTS...".

Causa: Il cluster AKS è stato creato senza l'issuer OIDC o l'identità del carico di lavoro abilitata.

Risoluzione: Abilitare entrambe le funzionalità nel cluster esistente usando il az aks update comando :

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

Dopo l'abilitazione, eseguire nuovamente i passaggi di configurazione delle credenziali federate dalla guida alla distribuzione per collegare l'identità gestita all'account del servizio Kubernetes.

Azure modello OpenAI non disponibile nell'area selezionata

Symptom: La creazione della distribuzione di Azure OpenAI non riesce, oppure l'avvio dell'agente Container Network Insights fallisce con un errore di endpoint o modello immediatamente dopo la distribuzione.

Cause: Il modello OpenAI Azure selezionato non è disponibile nell'area di Azure scelta.

Risoluzione:

1. Verificare quali modelli sono disponibili nell'area:

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

2. Usare un'area in cui è disponibile il modello di destinazione. Consultare il riferimento Supporto delle regioni del modello Azure OpenAI per la disponibilità corrente.

3. Verificare che la sottoscrizione disponga di una quota di tokenPer-Minute (TPM) sufficiente per il modello. Se la distribuzione del modello ha esito negativo con un errore di quota, richiedere un aumento della quota nel portale di Azure in Servizi cognitivi > Quote.

Comandi di diagnostica rapida

Usare questi comandi per diagnosticare rapidamente i problemi comuni:

# ──── 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

Passaggi successivi

• Distribuire e usare l'agente di Container Network Insights su AKS
• Panoramica dell'agente di Container Network Insights
• Panoramica di Advanced Container Networking Services
• Azure CNI con tecnologia Cilium