Solucionar problemas do Agente de Insights da Rede de Contêineres no AKS

Este artigo aborda problemas comuns que você pode encontrar ao implantar, configurar ou usar o Container Network Insights Agent no AKS. Cada seção segue um formato Sintoma → Causa → Resolução.

Para obter instruções de implantação, consulte Implantar e usar o Agente do Container Network Insights no AKS.

Falha na instalação da extensão

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

Cause: região de nuvem soberana (a extensão tem suporte apenas em Azure regiões públicas), recursos de cluster ausentes ou permissões insuficientes.

Resolução:

1. Verifique o estado de provisionamento de extensão para obter 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. Verifique se o cluster está em uma região pública Azure. A extensão está disponível em todas as regiões públicas Azure em que o AKS tem suporte, mas não está disponível em Azure Governamental, Microsoft Azure operado pela 21Vianet ou outras nuvens soberanas.

3. Verifique se o cluster tem a identidade da carga de trabalho e o emissor OIDC habilitados:

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

4. Verifique se você tem as funções Contributor e User Access Administrator no grupo de recursos.

5. Se você já tiver executado az k8s-extension create uma vez, executá-la novamente retornará um erro porque a extensão já existe. Use az k8s-extension update para alterar as configurações em uma 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 pod do agente inicia, mas retorna 401 Unauthorized ou 403 Forbidden erros ao processar solicitações. Os logs do pod mostram falhas de autenticação ou autorização.

Causa: A identidade gerenciada não tem as atribuições de função RBAC necessárias, ou o sujeito de credencial federada não corresponde à conta de serviço do agente.

Resolução:

1. Verifique se a identidade gerenciada tem todas as quatro atribuições de função necessárias:

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

   Confirme se essas funções estão presentes:

   Função	Scope
   Cognitive Services OpenAI User	Recurso do Azure OpenAI
   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á habilitada 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 de 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 de serviço do Kubernetes tem a anotação de identidade de carga de trabalho correta:

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

   A anotação azure.workload.identity/client-id deve corresponder à ID do cliente da identidade gerenciada. Caso não corresponda, 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 do Azure OpenAI

Sintoma: O pod do agente inicia, mas as solicitações de chat falham. Os logs de pod mostram os erros 401 Unauthorized, 404 Not Found ou de conexão referenciando o ponto de extremidade do OpenAI do Azure.

Cause: O ponto de extremidade do Azure OpenAI, o nome da implantação ou as credenciais de identidade gerenciada estão configurados incorretamente ou o tráfego de rede para o ponto de extremidade está bloqueado.

Resolução:

1. Verifique os logs dos pods em busca de padrões de erro específicos:

   Mensagem de log	Motivo	Corrigir
   401 Unauthorized	Identidade gerenciada com função Cognitive Services OpenAI User ausente	Atribuir a função no recurso OpenAI
   404 Not Found	URL do ponto de extremidade ou nome de implantação incorreto	Verificar AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_DEPLOYMENT
   Connection refused / Name resolution failed	Problema de rede ou DNS	Verifique as regras de NSG/firewall e confirme o nome do host do ponto de extremidade.
   Token acquisition failed	Identidade da carga de trabalho não configurada	Verificar a anotação da conta de serviço e a credencial federada

2. Verifique se a identidade gerenciada tem a função 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 você usar políticas de rede, o Firewall do Azure ou NSGs, verifique se o tráfego HTTPS de saída (porta 443) é permitido do namespace kube-system para seu ponto de extremidade do OpenAI do Azure. Verifique se nenhuma política de rede está bloqueando o tráfego de saída:

   kubectl get networkpolicies -n kube-system
   

Erros de autenticação de Entra ID e registro de aplicativo

Sintoma: o fluxo de login do Microsoft Entra ID (MSAL) falha, os redirecionamentos de login retornam erros ou os logs do pod mostram o valor de espaço reservado 44444444-4444-4444-4444-444444444444 para ENTRA_CLIENT_ID.

Causa: O Registro de Aplicativo não está configurado corretamente ou não foi definido durante a ENTRA_CLIENT_ID implantação da extensão.

Resolução:

1. Se os logs do pod mostrarem o valor do espaço reservado 44444444-4444-4444-4444-444444444444, atualize a extensão com a ID real do cliente de Registro de Aplicativo:

   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 retorno de chamada de login falhar com um erro redirect_uri mismatch, verifique o URI de redirecionamento no portal do Azure em Registros de aplicativo > Seu aplicativo > Autenticação > URIs de redirecionamento. Para acesso local encaminhado pela porta, o URI deve ser http://localhost:8080/auth/callback.

   Observação

   No momento, há suporte apenas localhost para URIs de redirecionamento. URLs do LoadBalancer público não são suportadas para URIs de redirecionamento.

3. Verifique se o Registro de Aplicativo tem as permissões delegadas Microsoft Graph necessárias: openid, profile, User.Read, offline_access. Se o consentimento do administrador for necessário, conceda a ele:

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

4. Verifique os logs de pod em busca de 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 ausentes na inicialização

Sintoma: o pod do agente falha imediatamente na inicialização, apresentando:

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 foram definidos quando a extensão foi implantada.

Resolução:

1. Verifique o ConfigMap quanto a valores substitutos ou configurações ausentes:

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

2. Confirme se essas variáveis necessárias são definidas com valores reais (não espaços reservados como 00000000-0000-0000-0000-000000000000):

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

3. Se os valores aparecerem como marcadores de posição, atualize a extensão com as configuraçõ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>
   

O pod do agente não está em execução ou está apresentando falhas

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

Cause: Configuração incorreta, conectividade Azure OpenAI ausente ou recursos de cluster insuficientes.

Resolução:

1. Verifique os eventos do pod em busca de erros imediatos:

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

2. Verifique os logs do pod em busca de mensagens de erro:

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

3. Associar mensagens de log a causas conhecidas previamente:

   Mensagem de log	Motivo	Corrigir
   Missing required Azure OpenAI environment variable(s)	ConfigMap tem valores de espaço reservado	Definir valores corretos por meio de az k8s-extension update
   bootstrap.validation_agent_failed	Não é possível se conectar ao Azure OpenAI	Verifique a rede, a URL do endpoint e o RBAC da identidade gerenciada
   AKS MCP binary not found	Binário ausente da imagem	Use a imagem de extensão oficial de acnpublic.azurecr.io
   FailedMount /erro de montagem de volume	Segredos dos certificados perdidos do Hubble	Implemente com hubble.enabled=false ou garanta que o ACNS esteja habilitado
   Token acquisition failed	Identidade da carga de trabalho não configurada	Verificar a anotação da conta de serviço e a credencial federada

4. Verifique se o ponto de extremidade do OpenAI do Azure está acessível por meio do cluster. Se você usar restrições de saída, verifique se o tráfego HTTPS de saída (porta 443) é permitido do namespace kube-system para o seu ponto de extremidade do OpenAI do Azure.

Falhas de sondas de prontidão

Sintoma: o pod está com o status Running, mas mostra o status 0/1 pronto. O /ready endpoint retorna HTTP 503.

Causa: Uma ou mais verificações de inicialização ainda não foram concluídas: o pool de agentes de aquecimento ainda não foi inicializado, as propriedades do cluster têm erros ou não há agentes pré-aquecidos disponíveis.

Resolução:

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

2. Verifique a resposta de preparação por motivos de falha específicos:

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

3. Verifique os logs do pod para problemas relacionados ao aquecimento:

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

4. Se as propriedades do cluster estiverem falhando, verifique se AKS_CLUSTER_NAME, AKS_RESOURCE_GROUP e AZURE_SUBSCRIPTION_ID estão definidas corretamente na configuração da extensão.

O pool de aquecimento continua falhando

Sintoma: o pod está com o status Running, mas nunca fica pronto. Os logs do pod mostram erros "Failed to create warmed agent" repetidos mesmo após vários minutos de espera.

Causa: o pool de aquecimento em segundo plano não está conseguindo criar instâncias de agente pré-aquecidas. Isso normalmente é causado por um problema de conectividade openai Azure não resolvido ou uma falha de inicialização do MCP que impede a criação de agentes.

Resolução:

1. Verifique os logs do erro subjacente específico:

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

2. Associe o erro ao seu conserto:

   Erro nos logs	Corrigir
   401 Unauthorized ou 403 Forbidden	Consulte problemas de conectividade do Azure OpenAI e verifique a atribuição de função de identidade gerenciada
   Token acquisition failed	Consulte erros de identidade e permissões
   404 Not Found no ponto de extremidade	Verificar AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_DEPLOYMENT no ConfigMap
   AKS MCP binary not found	Consulte O pod do agente não está em execução ou está apresentando falhas

3. Depois que o problema subjacente é resolvido, o pool de aquecimento reinicia automaticamente. Você não precisa reiniciar o pod, a menos que o erro persista após a correção da causa raiz.

Falha nos comandos do Hubble

Sintoma: O agente relata erros para diagnóstico relacionado ao Hubble ou a análise de fluxo do Hubble não está disponível.

Causa: O cluster não tem ACNS (Serviços Avançados de Rede de Contêiner) ou o plano de dados Cilium habilitado.

Resolução:

• Se o cluster não usar ACNS, implante a extensão com hubble.enabled=false e config.AKS_MCP_ENABLED_COMPONENTS=kubectl. O agente ainda fornece DNS, remoção de pacotes e diagnóstico de rede padrão do Kubernetes sem o Hubble.

• Para habilitar o Hubble, seu cluster deve usar Azure CNI alimentado pelo Cilium com Advanced Container Networking Services (ACNS) habilitados.

• Verifique se o Hubble está em execução no cluster:

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

  Se nenhum pod retornar, o Hubble não estará habilitado. Habilite o ACNS no cluster ou defina hubble.enabled=false na configuração da extensão.

Limitação da taxa de chat

Sintoma: As solicitações de chat retornam HTTP 429 com X-RateLimit-* ou X-LLM-RateLimit-* cabeçalhos de resposta.

Causa: O limitador de taxa interno está limitando as solicitações para proteger o serviço.

Resolução:

O Container Network Insights Agent tem três camadas de limitação de taxa:

• Para erros 429 de chat: reduza a frequência das mensagens e aguarde o reabastecimento do bucket de limite de taxa.
• Para erros 429 de LLM: verifique sua cota de Tokens por Minuto (TPM) do OpenAI do Azure no portal do Azure. Solicite um aumento de cota nas Cotas dos Serviços > Cognitivos se precisar de uma taxa de transferência maior.

Mensagem de chat enviada, mas sem resposta

Sintoma: Uma mensagem de chat é enviada, mas nenhuma resposta é exibida. A solicitação trava ou, eventualmente, retorna um erro de tempo limite.

Causa: o OpenAI do Azure pode estar sujeito a limitações de taxa ou inacessível, pode não haver agentes pré-aquecidos disponíveis ainda ou um comando de diagnóstico de longa duração ainda está em execução.

Resolução:

1. Verifique se o pod tem sessões ativas e se um agente está 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 logs do pod em busca de padrões de erro:

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

   Indicador de log	Motivo	Corrigir
   429 Erros	Limite de taxa do OpenAI do Azure	Aguarde a redefinição do limite de taxa; verifique sua cota de TPM
   "No pre-warmed agents available"	Piscina de aquecimento não pronta	Aguarde a inicialização; ver O pool de aquecimento continua falhando
   Tempos limite de conexão	Problema de rede ou NSG	Verificar rede de pods, DNS e regras de NSG

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

Primeira solicitação lenta

Sintoma: A primeira mensagem de chat após a implantação ou a reinicialização do pod leva de 10 a 30 segundos para responder.

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

Resolução: Esse é o comportamento esperado. Aguarde até que o ponto de extremidade /ready retorne HTTP 200 antes de enviar solicitações; isso confirma que pelo menos um agente pré-aquecido está disponível. As solicitações subsequentes usam o pool pré-aquecido e respondem mais rapidamente (normalmente de 5 a 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 de diagnóstico levam de 30 segundos a 2 minutos para serem concluídas.

Causa: o diagnóstico em várias etapas envolve operações sequenciais: uma chamada inicial de classificação por LLM para o OpenAI do Azure, vários comandos kubectl/cilium/hubble executados no cluster e uma análise final das evidências coletadas por meio de LLM. Cada etapa adiciona latência.

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

Para reduzir a latência:

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

Os comandos de diagnóstico expiram por tempo limite

Sintoma: O agente relata que um comando atingiu o tempo limite ou o chat para de responder por mais de 10 minutos antes de retornar um erro.

Causa: O tempo limite padrão para comandos de diagnóstico (kubectl, cilium, hubble) é de 600 segundos (10 minutos). Consultas abrangentes, como coletar estatísticas de cada nó em um cluster grande, podem exceder esse limite.

Resolução:

• Delimite sua consulta a um nó específico, pod ou namespace ao invés de todo o cluster. Por exemplo:

  • Em vez de: "Verificar remoções de pacotes em todos os nós"
  • Solicite: "Verificar remoções de pacotes no nó <specific-node-name>"

• Se os tempos limite ocorrerem consistentemente em um tipo de consulta, o cluster poderá apresentar problemas de desempenho ou conectividade que, de forma independente, diminuem as respostas dos comandos.

• Verifique os logs do pod para obter entradas relacionadas ao tempo limite:

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

Dados de sessão perdidos após a reinicialização do pod

Sintoma: Todo o histórico de chat e sessões ativas desaparecem após a reinicialização do pod.

Causa: Os dados de sessão são armazenados somente na memória. Todos os dados são perdidos quando o pod é reiniciado.

Resolução: Esse é o comportamento esperado para a arquitetura atual. Inicie uma nova sessão após a reinicialização do pod.

A sessão expira inesperadamente

Sintoma: Você é desconectado sem aviso durante uma sessão ativa, ou sua sessão termina após um período de inatividade, mesmo que você esteja usando a extensão.

Causa: O Container Network Insights Agent impõe tempos limite de sessão para segurança. Dois limites independentes se aplicam:

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

O contexto de chat aparece perdido após muitas trocas

Sintoma: Após aproximadamente 15 trocas, o agente parece esquecer partes anteriores da conversa ou não faz referência ao contexto de antes da sessão.

Cause: Container Network Insights Agent resume o histórico de conversas para permanecer dentro do limite de token Azure 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 passados para o modelo.

Resolução: Esse é o comportamento esperado. O resumo preserva o principal contexto diagnóstico ao gerenciar os limites de tokens do Azure OpenAI. Se você precisar fazer referência a algo de muito antes da conversa:

• Repita o contexto relevante: "Anteriormente você encontrou X — você pode investigar mais?"
• Inicie uma nova conversa com uma recapitulação concisa das descobertas conhecidas.

Limite de conversa atingido

Sintoma: A interface mostra um erro de que você não pode criar uma nova conversa ou as conversas mais antigas desaparecem sem serem excluídas explicitamente.

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

Resolução: Esse comportamento de limpeza automática é esperado. Se você não conseguir criar uma nova conversa, aguarde brevemente a execução da limpeza em segundo plano e tente novamente. As duas conversas menos usadas recentemente são removidas automaticamente.

Debug DaemonSet persiste após uma falha

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

Causa: o Container Network Insights Agent implanta um DaemonSet de depuração leve durante o diagnóstico de remoção de pacotes. Se o pod do agente falhar inesperadamente durante esse diagnóstico, a etapa de limpeza não será executada.

Resolução: Exclua manualmente o DaemonSet:

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

O diagnóstico de remoção de pacotes falha

Sintoma: ao solicitar que o agente investigue remoções de pacotes, ele relata erros na implantação de pods de diagnóstico ou não consegue coletar estatísticas no nível do nó.

Causa: os diagnósticos de remoção de pacotes implantam um DaemonSet leve (rx-troubleshooting-debug) em cada nó para coletar estatísticas de rede no nível do host (estatísticas de ethtool, contadores softnet, estado do buffer de anel). Ocorrerão falhas se a conta de serviço do agente não tiver permissão para criar DaemonSets ou se os nós bloquearem o acesso privilegiado necessário para coletar estatísticas kube-systemde rede do host.

Resolução:

1. Verifique se o DaemonSet foi criado:

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

   Se ele não existir, a etapa de implantação falhará. Verifique os logs do pod:

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

2. Se o DaemonSet foi criado, mas seus pods não estão iniciando, descreva-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 for remanescente de uma execução fracassada, exclua-o manualmente e peça ao agente para tentar novamente.

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

Os diagnósticos de DNS retornam resultados incompletos ou sem resultados

Sintoma: Ao solucionar problemas de DNS, o agente retorna dados de diagnóstico parciais, relata erros que executam 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 de dentro do cluster. Resultados incompletos podem ocorrer se a conta de serviço do agente não tiver acesso de leitura no nível do cluster, os pods CoreDNS não estiverem acessíveis ou os comandos individuais atingirem o tempo limite de 30 segundos por comando.

Resolução:

1. Verifique se o CoreDNS está em execução:

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

   Se os pods CoreDNS não estiverem em execução, essa é a causa raiz. Descreva-os para obter detalhes:

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

2. Verifique se a identidade gerenciada tem a atribuição Serviço de Kubernetes do Azure Cluster User Role no cluster. Essa função permite que o agente recupere kubeconfig e execute comandos kubectl:

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

3. Se o agente relatar tempos limite dos comandos durante as verificações de DNS, reduza o escopo da sua consulta. Por exemplo, em vez de "diagnosticar todos os problemas de DNS", peça para "verificar a resolução de DNS para pod <pod-name> no namespace <namespace>".

Agente interrompe investigação em andamento

Sintoma: O agente inicia uma investigação de diagnóstico, mas para antes de concluí-la, sem fornecer uma análise de causa raiz ou um relatório final.

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

• Um comando de diagnóstico atingiu o tempo limite.
• O limite de taxa do Azure OpenAI ou o limite de token foi atingido durante a investigação em andamento.
• A janela de contexto do histórico da conversa atingiu seu limite de resumo, fazendo com que o agente perdesse o fio da meada do plano atual.

Resolução:

• Peça ao agente para continuar na mesma conversa: "Please continue the investigation" ou "What other checks can you run?" O agente pode retomar do ponto atual.
• Se os tempos limite forem a causa, ajuste o escopo da próxima consulta para que seja mais restrito. Por exemplo, "verifique o namespace <name>específico" em vez do cluster completo.
• Se a investigação parar devido à limitação de taxa, aguarde 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á falhando no namespace X. Você pode investigar a NetworkPolicy para esse namespace?"

A identidade do workload não está habilitada no cluster

Symptom: falha na configuração da credencial federada ou o pod do agente não pode se autenticar no Azure. Os logs do pod mostram os erros "Failed to acquire token" ou "AADSTS...".

Causa: o cluster do AKS foi criado sem o emissor OIDC ou sem a identidade da carga de trabalho habilitada.

Resolução: Habilite ambos os recursos em 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

Depois de habilitar, execute novamente as etapas de configuração de credencial federada do guia de implantação para vincular a identidade gerenciada à conta de serviço do Kubernetes.

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

Sintoma: a criação da implantação do OpenAI do Azure falha ou a inicialização do Container Network Insights Agent falha com um erro de ponto de extremidade ou de modelo imediatamente após a implantação.

Cause: O modelo openai Azure selecionado não está disponível na região de Azure escolhida.

Resolução:

1. Verifique quais modelos estão disponíveis em sua região:

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

2. Use uma região em que seu modelo de destino esteja disponível. Consulte a referência de suporte regional do modelo Azure OpenAI para a disponibilidade atual.

3. Verifique se sua assinatura tem cota suficiente de TokensPer-Minute (TPM) para o modelo. Se a implantação do modelo falhar com um erro de cota, solicite um aumento de cota no portal de Azure em Cognitive Services > Quotas.

Comandos de diagnóstico rápido

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

Próximas Etapas 

• Implantar e usar o Agente de Insights de Rede de Contêiner no AKS
• Visão geral do Agente do Container Network Insights
• Visão geral dos Serviços Avançados de Rede de Contêineres
• Azure CNI impulsionado por Cilium