Condividi tramite

Risolvere i problemi della CLI dell'agente per Azure Kubernetes Service (AKS) (anteprima)

Questo articolo fornisce indicazioni sulla risoluzione dei problemi comuni relativi all'interfaccia della riga di comando agente per il servizio Azure Kubernetes.

Normale procedura di risoluzione dei problemi

Se si verificano problemi quando si usa il CLI agentic per AKS, provare la seguente procedura di risoluzione dei problemi:

  • Se si notano richieste che ritentano chiamate a /chat/completions nelle risposte, si potrebbe essere soggetti a limitazioni dovute ai limiti di token al minuto (TPM) imposti dal modello linguistico di grandi dimensioni. Aumentare il limite TPM o richiedere una quota maggiore.
  • Se gli output variano, potrebbe essere dovuto alla variabilità delle risposte LLM o alle connessioni server MCP (Model Context Protocol) intermittenti.
  • Assicurarsi che il nome della distribuzione corrisponda al nome del modello nelle distribuzioni di Azure OpenAI.
  • Se l'installazione aks-agent non riesce, provare a disinstallare l'interfaccia della riga di comando di Azure e reinstallare la versione più recente.

Errore: Il daemon Docker non è in esecuzione

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?

  1. Se viene visualizzato un errore che indica che il daemon Docker non è in esecuzione, avviare il servizio Docker usando i passaggi appropriati per il sistema operativo:

    • macOS/Windows:

      • Avviare Docker Desktop dalle applicazioni.
      • Attendere l'avvio di Docker.

    • Linux:

      • Avviare il servizio Docker usando i comandi seguenti:

        sudo systemctl start docker
sudo systemctl enable docker  # Enable Docker to start on boot

  2. Verificare che Docker sia in esecuzione usando il comando seguente:

    docker info

Errore: Autorizzazione Docker negata

Got permission denied while trying to connect to the Docker daemon socket

Per risolvere i problemi di autorizzazione di Docker, assicurarsi che l'utente disponga delle autorizzazioni necessarie per accedere al daemon Docker seguendo la procedura per il sistema operativo:

  • macOS/Windows:

    • Riavviare Docker Desktop per assicurarsi che disponga delle autorizzazioni necessarie.

  • Linux:

    • Aggiungere l'utente al gruppo Docker per consentire l'accesso non radice a Docker usando i comandi seguenti:
    sudo usermod -aG docker $USER
newgrp docker  # Apply group changes immediately

Errore: Errori di scaricamento dell'immagine Docker

Error response from daemon: pull access denied for aks-agent, repository does not exist or may require 'docker login'

Per risolvere gli errori di pull delle immagini Docker, seguire questa procedura:

  • Assicurarsi di disporre della connettività Internet.
  • Controllare se i firewall aziendali bloccano l'accesso al Registro di sistema Docker.
  • Provare a inizializzare nuovamente l'agente con az aks agent-init.

Problemi relativi alle credenziali di Azure

Errore: Autenticazione di Azure non riuscita

Per risolvere i problemi di autenticazione di Azure, assicurarsi che l'interfaccia della riga di comando di Azure sia autenticata correttamente e abbia accesso alle risorse necessarie seguendo questa procedura:

  1. Verificare che le credenziali di Azure siano configurate correttamente usando il az account show comando .

    az account show

  2. Se necessario, accedere di nuovo usando il az login comando .

    az login

Problemi relativi al service account e al controllo degli accessi in base al ruolo (RBAC)

Errore: l'account del servizio non è stato trovato

Error: service account "aks-mcp" not found in namespace "default"

Per risolvere i problemi dell'account del servizio, assicurarsi che l'account del servizio Kubernetes sia stato creato correttamente e configurato seguendo questa procedura:

  1. Verificare che l'account del servizio esista usando il comando seguente:

    kubectl get serviceaccount aks-mcp --namespace $NAMESPACE

  2. Se l'account del servizio non viene trovato, crearne uno seguendo la procedura descritta in Creare un account del servizio e configurare l'identità del carico di lavoro per l'interfaccia della riga di comando agente per il servizio Azure Kubernetes (anteprima)

Errore: Permesso negato

Error: forbidden: User "system:serviceaccount:<namespace>:aks-mcp" cannot get resource "pods" in API group "" in the namespace "<namespace>"

Per risolvere gli errori di autorizzazione negata, assicurarsi che il Kubernetes service account disponga delle autorizzazioni RBAC necessarie utilizzando la seguente procedura:

  1. Verificare che le autorizzazioni RBAC siano configurate correttamente utilizzando i seguenti comandi:

    kubectl get role aks-mcp-role --namespace $NAMESPACE
kubectl get rolebinding aks-mcp-rolebinding --namespace $NAMESPACE

  2. Controllare che RoleBinding associ l'account del servizio corretto al ruolo usando il comando seguente:

    kubectl describe rolebinding aks-mcp-rolebinding --namespace $NAMESPACE

Problemi di identità dei carichi di lavoro

Errore: Identità del workload non abilitata

Error: workload identity is not enabled on this cluster

Se ricevi un errore che indica che la workload identity non è abilitata, verifica che la workload identity del cluster AKS sia abilitata utilizzando la seguente procedura:

  1. Controllare se l'identità del carico di lavoro è abilitata nel cluster AKS usando il comando az aks show.

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

  2. Se l'identità del carico di lavoro non è abilitata, seguire la procedura descritta in Creare un account del servizio e configurare l'identità del carico di lavoro per la CLI agentica per Azure Kubernetes Service (AKS) (anteprima) per abilitare l'identità del carico di lavoro nel cluster.

Errore: Annotazione mancante

Error: service account does not have workload identity annotation

Per risolvere gli errori di annotazione mancanti, verificare che l'account del servizio Kubernetes disponga dell'annotazione corretta dell'identità del carico di lavoro seguendo questa procedura:

  1. Controllare se l'annotazione esiste nell'account del servizio usando il comando seguente:

    kubectl describe serviceaccount aks-mcp --namespace $NAMESPACE

  2. Se l'annotazione non è presente, aggiungerla usando il comando seguente. Assicurarsi di sostituire $CLIENT_ID con l'ID client effettivo della credenziale dell'identità federata.

    kubectl annotate serviceaccount aks-mcp --namespace $NAMESPACE azure.workload.identity/client-id="$CLIENT_ID" --overwrite

Errore: Ritardo di propagazione delle credenziali federate

Se si ricevono errori relativi alle credenziali dell'identità federata non trovate o problemi di autenticazione, potrebbe essere dovuto a ritardi nella propagazione dopo aver creato le credenziali dell'identità federata in Azure. Per risolvere questo problema, tentare di procedere come segue:

  1. Attendere alcuni minuti per la propagazione delle credenziali dell'identità federata tra i servizi di Azure.
  2. Verificare che la credenziale dell'identità federata esista usando il az identity federated-credential list comando .
az identity federated-credential list --identity-name $IDENTITY_NAME --resource-group $RESOURCE_GROUP

Problemi di inizializzazione

Errore: Estensione non trovata

ERROR: The command 'aks agent' is invalid or not supported. Use 'az aks --help' to see available commands

Per risolvere gli errori di estensione non trovati, verificare che l'estensione aks-agent sia installata correttamente e caricata seguendo questa procedura:

  1. Installare l'estensioneaks-agent usando il comando az extension add.

    az extension add --name aks-agent --debug

  2. Verificare che l'installazione abbia esito positivo usando il az extension list comando .

    az extension list

    L'output deve includere una voce per aks-agent.

Contenuti correlati

  • Last updated on