Resolução de Problemas do Agente Container Network Insights no AKS

Este artigo aborda problemas comuns que pode encontrar ao implementar, configurar ou utilizar o Container Network Insights Agent no AKS. Cada secção segue um formato de Sintomas → Causa → Resolução .

Para instruções de implementação, consulte Deploy and use Container Network Insights Agent no AKS.

Falha na instalação da extensão

Sintoma: O az k8s-extension create comando falha, ou o estado de provisão da extensão mostra Failed.

Cause: Região de cloud soberana (a extensão é suportada apenas em Azure regiões públicas), falta de funcionalidades do cluster ou permissões insuficientes.

Resolution:

1. Verifique o estado de provisionamento da extensão para mais detalhes:

   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. Verifica se o teu cluster está numa região pública do Azure. A extensão está disponível em todas as regiões públicas do Azure onde o AKS é suportado, mas não está disponível no Azure Government, Microsoft Azure operado pela 21Vianet, ou noutras clouds soberanas.

3. Verifica se o teu cluster tem a identidade da carga de trabalho e o emissor OIDC ativados:

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

4. Confirma se tens Contributor e User Access Administrator funções no grupo de recursos.

5. Se já executaste az k8s-extension create uma vez, executá-lo novamente devolve um erro porque a extensão já existe. Use az k8s-extension update para alterar definições de configuração numa extensão existente:

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

Erros de identidade e permissões

Sintoma: O agente pod inicia-se, mas devolve 401 Unauthorized ou 403 Forbidden erros ao processar pedidos. Os registos do pod mostram falhas de autenticação ou autorização.

Causa: A identidade gerida carece das atribuições obrigatórias de funções RBAC, ou o sujeito da credencial federada não corresponde à conta de serviço do agente.

Resolution:

1. Verifique se a identidade gerida tem as quatro atribuições de funções obrigatórias:

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

   Confirme que estes papéis estão presentes:

   Função	Scope
   Cognitive Services OpenAI User	Azure OpenAI recurso
   Azure Kubernetes Service Cluster User Role	Cluster do AKS
   Azure Kubernetes Service Contributor Role	Cluster do AKS
   Reader	Grupo de recursos

2. Verifique se a identidade da carga de trabalho está ativada no cluster:

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

3. Verifique se o sujeito da credencial federada corresponde à conta do serviço:

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

   O subject campo deve ser system:serviceaccount:kube-system:container-networking-agent-reader.

4. Verifique se a conta do serviço Kubernetes tem a anotação correta de identidade da carga de trabalho:

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

   A anotação azure.workload.identity/client-id deve corresponder ao ID do cliente da sua identidade gerida. Se não coincidir, corrija e reinicie o 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
   

Problemas de conectividade Azure OpenAI

Sintoma: O podcast de agentes começa, mas os pedidos de chat falham. Os registos pod mostram 401 Unauthorized, 404 Not Found, ou erros de ligação que referenciam o endpoint Azure OpenAI.

Cause: O Azure endpoint OpenAI, nome de implementação ou credenciais de identidade gerida estão mal configurados, ou o tráfego de rede para o endpoint é bloqueado.

Resolution:

1. Verifique os registos dos pods para padrões de erro específicos:

   Mensagem de registo	Motivo	Corrigir
   401 Unauthorized	Identidade gerida sem função Cognitive Services OpenAI User	Atribuir o papel ao recurso OpenAI
   404 Not Found	URL de endpoint ou nome de implementação errados	Verificar AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_DEPLOYMENT
   Connection refused / Name resolution failed	Problema de rede ou DNS	Verifique as regras do NSG/firewall e verifique o nome do host do endpoint
   Token acquisition failed	Identidade da carga de trabalho não configurada	Verifique a anotação da conta de serviço e a credencial federada

2. Verifique se a identidade gerida tem o papel Cognitive Services OpenAI User no recurso 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 usar políticas de rede, Azure Firewall ou NSGs, certifique-se de que o tráfego HTTPS de saída (porta 443) é permitido do namespace kube-system para o seu endpoint Azure OpenAI. Verifique se nenhuma política de rede está a bloquear o tráfego de saída:

   kubectl get networkpolicies -n kube-system
   

Erros de registo de aplicações e autenticação do Entra ID

Sintoma: O fluxo de login Microsoft Entra ID (MSAL) falha, os redirecionamentos de login devolvem erros, ou os logs do pod mostram o valor provisório 44444444-4444-4444-4444-444444444444 para ENTRA_CLIENT_ID.

Causa: O Registo da App não está configurado corretamente, ou ENTRA_CLIENT_ID não foi definido durante a implementação da extensão.

Resolution:

1. Se os podlogs mostrarem o valor 44444444-4444-4444-4444-444444444444provisório, atualize a extensão com o seu ID real de cliente de Registo de Aplicações:

   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 o callback de login falhar com um erro redirect_uri mismatch, verifique o URI de redirecionamento no portal Azure em Registos de Aplicações > A Sua Aplicação > Autenticação > Redirecionar URIs. Para acesso local encaminhado por portas, o URI deve ser http://localhost:8080/auth/callback.

   Observação

   Atualmente, apenas os localhost URIs de redirecionamento são suportados. URLs públicas do balanceador de carga não são suportadas para URIs de redirecionamento.

3. Certifique-se de que o Registo de Aplicações tem as permissões Microsoft Graph delegadas necessárias: openid, profile, User.Read, offline_access. Se for necessário consentimento administrativo, conceda-o:

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

4. Verifique os registos dos pods para erros específicos de autenticação:

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

Variáveis de ambiente em falta no arranque

Sintoma: O agente pod falha imediatamente ao iniciar com:

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

Causa: Um ou mais valores de configuração necessários não eram definidos quando a extensão foi implementada.

Resolution:

1. Verifique o ConfigMap para valores provisórios ou definições em falta:

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

2. Confirme que estas variáveis exigidas estão definidas com valores reais (não marcadores como 00000000-0000-0000-0000-000000000000):

   Variable	Descrição	Exemplo
   AZURE_OPENAI_ENDPOINT	Ponto final de recurso do Azure OpenAI	https://your-instance.openai.azure.com/
   AZURE_OPENAI_DEPLOYMENT	Nome da implementação do modelo	gpt-4o
   AZURE_OPENAI_API_VERSION	Versão da API	2025-03-01-preview
   AZURE_CLIENT_ID	ID de cliente de identidade gerida	Identificador Único Universal (UUID)
   AZURE_TENANT_ID	ID do locatário do Azure	Identificador Único Universal (UUID)
   AZURE_SUBSCRIPTION_ID	ID de subscrição do Azure	Identificador Único Universal (UUID)
   AKS_CLUSTER_NAME	Nome do cluster AKS	O nome do teu cluster
   AKS_RESOURCE_GROUP	Grupo de recursos de cluster	O seu grupo de recursos

3. Se os valores mostrarem marcadores de lugar, atualize a extensão com as definições corretas:

   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 de agentes não está a correr nem a crashar

Sintoma: O pod do agente está em CrashLoopBackOff, Error, ou Pending estado.

Causa: Má configuração, falta de conectividade Azure OpenAI ou recursos insuficientes do cluster.

Resolution:

1. Verifique os eventos do pod para erros imediatos:

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

2. Verifique os registos dos pods para mensagens de erro:

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

3. Associe mensagens do log a causas conhecidas.

   Mensagem de registo	Motivo	Corrigir
   Missing required Azure OpenAI environment variable(s)	O ConfigMap tem valores provisórios	Definir valores corretos via az k8s-extension update
   bootstrap.validation_agent_failed	Não consigo ligar-me ao Azure OpenAI	Verifique a rede, a URL do ponto final e o RBAC da identidade gerida
   AKS MCP binary not found	Binário em falta na imagem	Utilize a imagem oficial da extensão de acnpublic.azurecr.io
   FailedMount / erro de montagem do volume	Segredos de certificados do Hubble em falta	Implementar com hubble.enabled=false ou garantir que o ACNS está ativado
   Token acquisition failed	Identidade da carga de trabalho não configurada	Verifique a anotação da conta de serviço e a credencial federada

4. Verifique se o endpoint Azure OpenAI é acessível a partir do cluster. Caso utilize restrições de saída, assegure-se de que o tráfego HTTPS de saída (porta 443) é permitido do espaço de nomes kube-system para o seu ponto final Azure OpenAI.

Falhas da sonda de prontidão

Sintoma: O pod Running mas mostra estado 0/1 pronto. O /ready endpoint retorna HTTP 503.

Causa: Uma ou mais verificações de arranque ainda não foram concluídas: o pool de agentes de aquecimento ainda não está inicializado, as propriedades do cluster apresentam erros ou não existem agentes pré-aquecidos disponíveis.

Resolution:

1. Espere até 2-3 minutos após a implantação para que a piscina de aquecimento crie agentes pré-aquecidos.

2. Verifique a resposta de prontidão relativamente a motivos específicos de falha:

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

3. Consulte os registos dos pods para problemas relacionados com o aquecimento:

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

4. Se as propriedades do cluster estiverem a falhar, verifique que AKS_CLUSTER_NAME, AKS_RESOURCE_GROUP, e AZURE_SUBSCRIPTION_ID estão corretamente definidas na configuração de extensão.

A piscina de aquecimento continua a falhar

Sintoma: O pod está Running , mas nunca fica pronto. Os registos de logs do pod mostram erros repetidos "Failed to create warmed agent" mesmo depois de aguardar vários minutos.

Causa: A piscina de aquecimento de fundo está a falhar em criar instâncias de agentes pré-aquecidos. Isto é normalmente causado por um problema não resolvido de conectividade com o Azure OpenAI ou por uma falha de inicialização do MCP que impede a criação de agentes.

Resolution:

1. Verifique os registos para o erro subjacente específico:

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

2. Compare o erro com a sua correção:

   Erro nos registos	Corrigir
   401 Unauthorized ou 403 Forbidden	Consulte problemas de conectividade do Azure OpenAI e verifique a atribuição do papel de identidade gerida.
   Token acquisition failed	Ver Erros de identidade e permissões
   404 Not Found no ponto final	Verificar AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_DEPLOYMENT no ConfigMap
   AKS MCP binary not found	Ver Pod do agente não está em execução ou a falhar

3. Uma vez resolvido o problema subjacente, a piscina de aquecimento tenta automaticamente. Não precisas de reiniciar o pod a menos que o erro persista depois de corrigires a causa raiz.

Os comandos do Hubble falham

Sintoma: O agente reporta erros nos diagnósticos relacionados com o Hubble, ou a análise de fluxo do Hubble não está disponível.

Causa: O cluster não tem os Advanced Container Networking Services (ACNS) nem o dataplane Cilium ativados.

Resolution:

• Se o seu cluster não usar ACNS, implemente a extensão com hubble.enabled=false e config.AKS_MCP_ENABLED_COMPONENTS=kubectl. O agente continua a fornecer DNS, entrega de pacotes e diagnósticos padrão de rede Kubernetes sem o Hubble.

• Para ativar o Hubble, o seu cluster deve usar Azure CNI alimentado por Cilium com Advanced Container Networking Services (ACNS) ativado.

• Verifique se o Hubble está a funcionar no seu cluster.

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

  Se nenhum pod regressar, o Hubble não está ativado. Ativa o ACNS no teu cluster ou define hubble.enabled=false na configuração da extensão.

Limitação da taxa de chat

Sintoma: Os pedidos de chat devolvem HTTP 429 com cabeçalhos de resposta X-RateLimit-* ou X-LLM-RateLimit-*.

Causa: O limitador de taxa incorporado limita os pedidos para proteger o serviço.

Resolution:

O Container Network Insights Agent tem três camadas limitadoras de velocidade:

• Para erros do chat 429: reduza a frequência das suas mensagens e espere que o reservatório de limite de taxa se reabasteça.
• Para erros LLM 429: verifique a sua quota de Azure OpenAI Tokens-Per-Minute (TPM) no portal Azure. Solicite um aumento da quota em Quotas de Serviços Cognitivos> se precisar de maior capacidade de processamento.

Mensagem de chat enviada mas sem resposta

Sintoma: É enviada uma mensagem por chat, mas não aparece resposta. O pedido fica pendente ou acaba por devolver um erro de timeout.

Causa: Azure OpenAI pode estar sujeito a uma limitação de taxa ou inacessível, ainda podem não existir agentes pré-aquecidos disponíveis, ou um comando de diagnóstico de longa duração ainda pode estar a ser executado.

Resolution:

1. Verifique se o pod tem sessões ativas e se um agente é atribuído:

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

2. Verifique os registos dos pods para padrões de erro:

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

   Indicador de registos	Motivo	Corrigir
   429 Erros	Azure OpenAI com limites de taxa	Esperar que o limite de taxa seja reiniciado; verifique a sua quota de TPM
   "No pre-warmed agents available"	Piscina de aquecimento não pronta	Esperar pela inicialização; ver A piscina de aquecimento continua a falhar
   Tempos limite de ligação	Problema de rede ou NSG	Verifique a rede de pod, DNS e as regras de NSG

3. Se o pedido ainda estiver pendente após 2 minutos, inicie uma nova conversa e envie primeiro uma consulta simples (por exemplo, "listar pods no namespace padrão") para verificar se o agente está a responder antes de fazer uma pergunta diagnóstica complexa.

Pedido inicial lento

Sintoma: A primeira mensagem de chat após a implantação ou reinício do pod demora entre 10 a 30 segundos a responder.

Causa: O Container Network Insights Agent mantém um conjunto de agentes pré-aquecidos para reduzir a latência. Após um reinício do pod, o pool de aquecimento precisa de tempo para inicializar cada agente, o que requer o arranque do plugin MCP, a configuração de credenciais do Azure e a inicialização do framework de IA.

Resolução: Isto é um comportamento esperado. Espere que o /ready endpoint devolva HTTP 200 antes de enviar pedidos — isso confirma que pelo menos um agente pré-inicializado está disponível. Pedidos subsequentes utilizam o pool pré-aquecido e respondem mais rapidamente (normalmente 5-10 segundos para consultas simples).

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

Respostas lentas para diagnósticos complexos

Sintoma: As respostas diagnósticas demoram entre 30 segundos a 2 minutos a ser concluídas.

Causa: Os diagnósticos em múltiplos passos envolvem operações sequenciais: uma chamada inicial de classificação LLM ao Azure OpenAI, múltiplos comandos kubectl/cilium/hubble executados contra o cluster e uma análise final do LLM das evidências recolhidas. Cada passo adiciona latência.

Resolução: Isto é esperado para diagnósticos complexos. A tabela seguinte mostra os tempos de resposta típicos:

Para reduzir a latência:

• Use uma consulta específica que tenha como alvo um sintoma conhecido em vez de uma pergunta ampla. Por exemplo, "verificar resolução DNS para serviço my-svc no namespace my-ns" é mais rápido do que "diagnosticar todos os problemas de rede."
• Garanta que o seu recurso Azure OpenAI está na mesma região do Azure que o seu cluster AKS para minimizar o tempo de ida e volta da rede.
• Verifique a sua quota de TPM do Azure OpenAI — uma quota mais alta permite mais processamento paralelo de tokens.

Comandos de diagnóstico expiram

Sintoma: O agente reporta um comando com tempo de expiração, ou o chat deixa de responder durante mais de 10 minutos antes de devolver um erro.

Causa: O timeout padrão para comandos de diagnóstico (kubectl, cilium, hubble) é de 600 segundos (10 minutos). Consultas amplas — como recolher estatísticas de cada nó de um grande cluster — podem exceder este limite.

Resolution:

• Define o âmbito da tua consulta para um nó, pod ou namespace específico em vez de para todo o cluster. Por exemplo:

  • Em vez de: "Verificar a perda de pacotes em todos os nós"
  • Perguntar: "Verificar perdas de pacotes no nó <specific-node-name>"

• Se os timeouts ocorrerem de forma consistente num tipo de consulta, o cluster pode ter problemas de desempenho ou conectividade que estão a atrasar independentemente as respostas dos comandos.

• Consulte os logs dos pods para entradas relacionadas com tempo limite.

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

Dados da sessão perdidos após o reinício do pod

Sintoma: Todo o histórico de chat e as sessões ativas desaparecem depois de o pod reiniciar.

Causa: Os dados da sessão são armazenados apenas na memória. Todos os dados são perdidos quando o pod reinicia.

Resolução: Este é o comportamento esperado para a arquitetura atual. Inicia uma nova sessão depois de reiniciar o pod.

A sessão termina inesperadamente

Sintoma: Fica desconectado sem aviso durante uma sessão ativa, ou a sua sessão termina após um período de inatividade, mesmo tendo usado a extensão.

Causa: O Agente Container Network Insights aplica limites de tempo das sessões para segurança. Aplicam-se dois limites independentes:

Resolução: Volte a iniciar sessão para estabelecer uma nova sessão. O histórico de chat da sessão expirada não é recuperável.

O contexto do chat parece perdido após muitas trocas

Sintoma: Após cerca de 15 trocas, o agente parece esquecer-se de partes anteriores da conversa ou não referir o contexto do início da sessão.

Causa: O Agente Container Network Insights resume o histórico de conversas para se manter dentro do limite Azure dos tokens OpenAI. Quando a janela de contexto atinge aproximadamente 15 mensagens, as mensagens mais antigas são substituídas por um resumo gerado automaticamente. As mensagens mais recentes e o resumo são mantidos e encaminhados para o modelo.

Resolução: Isto é um comportamento esperado. A sumarização preserva o contexto diagnóstico chave enquanto gere os limites dos tokens Azure OpenAI. Se precisares de referir algo muito mais cedo na conversa:

• Repita o contexto relevante: "Antes encontrou X — pode investigar mais a fundo?"
• Comece uma nova conversa com um resumo conciso das descobertas conhecidas.

Limite de conversa atingido

Sintoma: A interface mostra um erro a indicar que não se pode criar uma nova conversa, ou que as conversas mais antigas desaparecem sem serem explicitamente apagadas.

Causa: Cada conta de utilizador está limitada a 20 conversas ativas. Quando este limite é atingido, as duas conversas mais antigas são automaticamente removidas para abrir espaço, começando quando a contagem atinge 18 (90% do limite de 20 conversas).

Resolução: Esta limpeza automática é um comportamento esperado. Se não conseguir criar uma nova conversa, espere brevemente que a limpeza de antecedentes seja executada e tente novamente. As duas conversas menos usadas recentemente são removidas automaticamente.

Debug DaemonSet persiste após um crash

Sintoma: O rx-troubleshooting-debug DaemonSet permanece no kube-system namespace após uma sessão de diagnóstico.

Causa: O agente Container Network Insights implementa um DaemonSet de depuração leve durante o diagnóstico de quedas de pacotes. Se o pod de agentes parar inesperadamente durante este diagnóstico, a etapa de limpeza não é executada.

Resolução: Apagar manualmente o DaemonSet:

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

O diagnóstico de queda de pacotes falha

Sintoma: Ao pedir ao agente para investigar quedas de pacotes, reporta erros na implementação de pods de diagnóstico ou não consegue recolher estatísticas ao nível do nó.

Causa: Os diagnósticos de perda de pacotes implementam um DaemonSet leve (rx-troubleshooting-debug) em cada nó para recolher estatísticas de rede no nível do anfitrião (as estatísticas do ethtool, contadores softnet, estado do buffer em anel). Falhas ocorrem se a conta de serviço do agente não tiver permissão para criar DaemonSets em kube-system, ou se os nós bloquearem o acesso privilegiado necessário para recolher estatísticas da rede host.

Resolution:

1. Verifique se o DaemonSet foi criado:

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

   Se não existir, a etapa de implementação falhou. Verifique os registos dos pods:

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

2. Se o DaemonSet foi criado mas os seus pods não arrancam, descreve-os para encontrar a causa:

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

3. Verifique se o ClusterRole atribuído ao agente inclui permissões de criação do DaemonSet:

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

4. Se o DaemonSet ficar de uma execução falhada, elimine-o manualmente e peça ao agente para tentar novamente:

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

Os diagnósticos DNS devolvem resultados incompletos ou sem resultados

Sintoma: Ao resolver um problema de DNS, o agente devolve dados parciais de diagnóstico, reporta erros ao executar verificações DNS ou sai da investigação sem resultados.

Causa: As ferramentas de diagnóstico DNS do agente executam testes de resolução e inspecionam o CoreDNS a partir do interior do cluster. Resultados incompletos podem ocorrer se a conta de serviço do agente não tiver acesso de leitura a nível de cluster, pods CoreDNS não forem acessíveis ou comandos individuais atingirem o timeout de 30 segundos por comando.

Resolution:

1. Verifique se o CoreDNS está a funcionar:

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

   Se os pods CoreDNS não estiverem a funcionar, essa é a causa raiz. Descreva-os para mais detalhes:

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

2. Verifica se a identidade gerida tem a atribuição Azure Kubernetes Service Cluster User Role no cluster. Este papel permite ao agente recuperar kubeconfig e executar comandos kubectl:

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

3. Se o agente reportar timeouts de comando durante as verificações DNS, restringa o âmbito da sua questão. Por exemplo, em vez de "diagnosticar todos os problemas de DNS", pergunte "verificar resolução DNS para pod <pod-name> no namespace <namespace>."

Agente para a meio de uma investigação

Sintoma: O agente inicia uma investigação diagnóstica, mas para antes de a concluir, sem fornecer uma análise da causa raiz ou um relatório final.

Causa: Vários fatores podem interromper uma investigação em várias etapas:

• Um comando de diagnóstico expirou.
• O limite de taxa do Azure OpenAI, ou limite de token, foi atingido a meio da investigação.
• A janela de contexto da conversa atingiu o seu limite para resumo, fazendo com que o agente perdesse o controle do plano em curso.

Resolution:

• Peça ao agente para continuar a mesma conversa: "Please continue the investigation" ou "What other checks can you run?" o agente pode retomar a partir do estado atual.
• Se os tempos de espera forem a causa, restrinja a próxima consulta de forma mais restrita. Por exemplo, "verifique o namespace <name>específico " em vez do cluster completo.
• Se a investigação foi interrompida devido ao limite de taxas, espere um minuto e peça ao agente para prosseguir.
• Para um novo começo, abra uma nova conversa e forneça um resumo conciso do que já foi encontrado: "Confirmei que a resolução DNS está a falhar no namespace X. Pode investigar a NetworkPolicy desse namespace?"

Identidade de carga não ativada no cluster

Sintoma: A configuração federada de credenciais falha, ou o pod de agentes não consegue autenticar-se para Azure. Os logs de pod mostram "Failed to acquire token" ou "AADSTS..." erros.

Causa: O cluster AKS foi criado sem o emissor OIDC ou a identidade de carga de trabalho ativada.

Resolução: Ative ambas as funcionalidades no seu cluster existente usando o az aks update comando:

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

Após ativar, volte a executar os passos federados de configuração das credenciais a partir do guia de implementação para ligar a identidade gerida à conta do serviço Kubernetes.

Modelo Azure OpenAI não disponível na região selecionada

Sintoma: A criação da implementação do Azure OpenAI falha, ou a inicialização do Agente Container Network Insights falha com um erro de endpoint ou modelo logo após a implementação.

Cause: O modelo Azure OpenAI que selecionaste não está disponível na região Azure escolhida.

Resolution:

1. Verifique quais os modelos disponíveis na sua região:

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

2. Usa uma região onde o teu modelo-alvo esteja disponível. Consulte a referência de suporte a regiões do modelo Azure OpenAI para ver a disponibilidade atual.

3. Verifique se a sua subscrição tem quota suficiente de Tokens-Per-Minute (TPM) para o modelo. Se a implementação do modelo falhar devido a um erro de quota, solicite um aumento de quota no portal Azure ao abrigo de Cognitive Services > Quotas.

Comandos rápidos de diagnóstico

Use estes comandos para diagnosticar rapidamente problemas comuns:

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

Passos seguintes

• Implementar e utilizar o Agente Container Network Insights no AKS
• Visão geral do Agente Container Network Insights
• Visão geral dos Serviços Avançados de Rede de Contentores
• Azure CNI alimentado por Cilium