Řešení potíží s rozhraním příkazového řádku pro Azure Kubernetes Service (AKS) (Preview)

Tento článek obsahuje pokyny k řešení běžných problémů s rozhraním příkazového řádku agenta pro Službu Azure Kubernetes Service (AKS).

Postup řešení běžných potíží

Pokud při použití agentického rozhraní příkazového řádku pro AKS narazíte na nějaké problémy, vyzkoušejte následující kroky pro řešení potíží:

• Pokud vidíte v odpovědích žádosti, které se /chat/completions opakují, může to znamenat, že jste byli omezeni limity tokenů za minutu (TPM) z LLM. Zvyšte limit TPM nebo požádejte o větší kvótu.
• Pokud se výstupy liší, důvodem může být proměnlivost odezvy LLM nebo přerušovaná připojení serveru MCP (Model Context Protocol).
• Ujistěte se, že je název nasazení stejný jako název modelu v nasazeních Azure OpenAI.
• Pokud se aks-agent instalace nedaří, zkuste odinstalovat Azure CLI a znovu nainstalovat nejnovější verzi.

Problémy související s Dockerem

Chyba: Démon Dockeru není spuštěn

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

1. Pokud se zobrazí chyba oznamující, že proces démon Dockeru není spuštěný, spusťte službu Docker pomocí příslušných kroků pro váš operační systém:

   • macOS / Windows:

     • Spusťte Docker Desktop z vašich aplikací.
     • Počkejte na spuštění Dockeru.

   • Linux:

     • Spusťte službu Docker pomocí následujících příkazů:

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

2. Pomocí následujícího příkazu ověřte, že docker běží:

   docker info
   

Chyba: Oprávnění Docker byla odepřena.

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

Pokud chcete vyřešit problémy s oprávněními Dockeru, ujistěte se, že má uživatel potřebná oprávnění pro přístup k procesu démona Dockeru pomocí kroků pro váš operační systém:

• macOS / Windows:

  • Restartujte Docker Desktop, abyste měli jistotu, že má potřebná oprávnění.

• Linux:

  • Přidejte uživatele do skupiny Dockeru, aby byl povolený přístup k Dockeru bez kořenového přístupu pomocí následujících příkazů:

  sudo usermod -aG docker $USER
  newgrp docker  # Apply group changes immediately
  

Chyba: Selhání vyžádání image Dockeru

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

Pro vyřešení selhání při stahování image Dockeru vyzkoušejte následující kroky:

• Ujistěte se, že máte připojení k internetu.
• Zkontrolujte, jestli podnikové firewally neblokují přístup k registru Dockeru.
• Zkuste agenta inicializovat znovu pomocí az aks agent-init.

Problémy s přihlašovacími údaji Azure

Chyba: Ověřování Azure selhalo

Pokud chcete vyřešit problémy s ověřováním Azure, ujistěte se, že je vaše rozhraní příkazového řádku Azure správně ověřené a má přístup k potřebným prostředkům pomocí následujícího postupu:

1. Pomocí příkazu ověřte, že jsou vaše přihlašovací údaje Azure správně nakonfigurované az account show .

   az account show
   

2. V případě potřeby se znovu přihlaste pomocí az login příkazu.

   az login
   

Problémy s účtem služby a oprávněními RBAC

Chyba: Účet služby se nenašel

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

Pokud chcete vyřešit problémy s účtem služby, ujistěte se, že je účet služby Kubernetes správně vytvořený a nakonfigurovaný pomocí následujícího postupu:

1. Pomocí následujícího příkazu ověřte, že účet služby existuje:

   kubectl get serviceaccount aks-mcp --namespace $NAMESPACE
   

2. Pokud se účet služby nenajde, vytvořte ho podle kroků v části Vytvoření účtu služby a nakonfigurujte identitu úlohy pro rozhraní příkazového řádku agenta pro Azure Kubernetes Service (AKS) (Preview).

Chyba: Odepření oprávnění

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

Pokud chcete vyřešit chyby odepření oprávnění, pomocí následujícího postupu se ujistěte, že účet služby Kubernetes má potřebná oprávnění RBAC:

1. Pomocí následujících příkazů ověřte, že jsou oprávnění RBAC správně nakonfigurovaná:

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

2. Zkontrolujte, zda RoleBinding spojuje správný účet služby s rolí pomocí následujícího příkazu:

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

Problémy s identitou úloh

Chyba: Identita úlohy není povolená

Error: workload identity is not enabled on this cluster

Pokud se zobrazí chyba oznamující, že identita úlohy není povolená, pomocí následujícího postupu ověřte, že je v clusteru AKS povolená identita úloh:

1. Pomocí příkazu zkontrolujte, jestli je ve vašem clusteru az aks show AKS povolená identita úloh.

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

2. Pokud není identita úlohy povolena, postupujte podle pokynů uvedených ve Vytvoření účtu služby a konfigurace identity úlohy pro CLI agentů v Azure Kubernetes Service (AKS) (preview), abyste povolili identitu úlohy ve vašem clusteru.

Chyba: Chybějící poznámka

Error: service account does not have workload identity annotation

Pokud chcete vyřešit chybějící chyby poznámek, ujistěte se, že účet služby Kubernetes má správnou poznámku k identitě úloh pomocí následujícího postupu:

1. Pomocí následujícího příkazu zkontrolujte, jestli v účtu služby existuje poznámka:

   kubectl describe serviceaccount aks-mcp --namespace $NAMESPACE
   

2. Pokud anotaci chybí, přidejte ji pomocí následujícího příkazu. Nezapomeňte nahradit $CLIENT_ID skutečným ID klienta přihlašovacích údajů federované identity.

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

Chyba: Zpoždění šíření federovaných přihlašovacích údajů

Pokud dojde k chybám souvisejícím s nenalezenými přihlašovacími údaji federované identity nebo selháním ověřování, příčinou může být zpoždění šíření po vytvoření přihlašovacích údajů federované identity v Azure. K vyřešení problému proveďte následující kroky:

1. Počkejte několik minut, než se přihlašovací údaje federované identity rozšíří napříč službami Azure.
2. Ověřte existenci přihlašovacích údajů federované identity pomocí příkazu az identity federated-credential list.

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

Problémy s inicializací

Chyba: Rozšíření nebylo nalezeno.

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

Chcete-li vyřešit chyby 'rozšíření nenalezeno', ujistěte se, že rozšíření aks-agent je správně nainstalováno a načteno pomocí následujících kroků:

1. aks-agent Nainstalujte rozšíření pomocí az extension add příkazu.

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

2. Pomocí příkazu ověřte úspěšnou az extension list instalaci.

   az extension list
   

   Výstup by měl obsahovat položku pro aks-agent.

Související obsah

• Pokyny k instalaci najdete v tématu Instalace a použití agentického rozhraní příkazového řádku pro AKS.
• Informace o nastavení účtu služby a identity úloh najdete v tématu Vytvoření účtu služby a konfigurace identity úloh pro rozhraní příkazového řádku agenta pro AKS.
• Přehled agentického rozhraní příkazového řádku pro AKS najdete v tématu o agentickém rozhraní příkazového řádku pro AKS.
• Odpovědi na běžné otázky týkající se agentického rozhraní příkazového řádku pro AKS najdete v tématu Nejčastější dotazy k rozhraní příkazového řádku agentů pro AKS.