Rozwiązywanie problemów z agentycznym interfejsem wiersza poleceń dla usługi Azure Kubernetes Service (AKS) (wersja próbna)

Ten artykuł zawiera wskazówki dotyczące rozwiązywania typowych problemów z interfejsem wiersza polecenia agenta dla usługi Azure Kubernetes Service (AKS).

Typowe kroki rozwiązywania problemów

Jeśli napotkasz jakiekolwiek problemy podczas korzystania z agentic CLI dla usługi AKS, spróbuj wykonać następujące kroki rozwiązywania problemów:

  • Jeśli w odpowiedziach zobaczysz ponawianie żądań do /chat/completions, być może jesteś ograniczany przez limity tokenu na minutę (TPM) z LLM. Zwiększ limit modułu TPM lub złóż wniosek o większy przydział.
  • Jeśli dane wyjściowe różnią się, może to być spowodowane zmiennością odpowiedzi LLM lub sporadycznymi połączeniami serwera protokołu MCP (Model Context Protocol).
  • Upewnij się, że nazwa wdrożenia jest taka sama jak nazwa modelu we wdrożeniach usługi Azure OpenAI.
  • Jeśli instalacja aks-agent zakończy się niepowodzeniem, spróbuj odinstalować Azure CLI i ponownie zainstalować najnowszą wersję.

Błąd: Demon platformy Docker nie jest uruchomiony

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

  1. Jeśli pojawi się błąd wskazujący, że demon Dockera nie jest uruchomiony, uruchom usługę Dockera, wykonując właściwe kroki dla swojego systemu operacyjnego.

    • macOS/Windows:

      • Uruchom aplikację Docker Desktop z poziomu aplikacji.
      • Poczekaj na uruchomienie platformy Docker.

    • Linux:

      • Uruchom usługę Platformy Docker przy użyciu następujących poleceń:

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

  2. Sprawdź, czy platforma Docker jest uruchomiona przy użyciu następującego polecenia:

    docker info

Błąd: Odmowa uprawnień platformy Docker

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

Aby rozwiązać problemy z uprawnieniami platformy Docker, upewnij się, że użytkownik ma niezbędne uprawnienia dostępu do demona platformy Docker, wykonując kroki dla systemu operacyjnego:

  • macOS/Windows:

    • Uruchom ponownie program Docker Desktop, aby upewnić się, że ma niezbędne uprawnienia.

  • Linux:

    • Dodaj użytkownika do grupy platformy Docker, aby zezwolić na dostęp inny niż główny do platformy Docker przy użyciu następujących poleceń:
    sudo usermod -aG docker $USER
newgrp docker  # Apply group changes immediately

Błąd: Błędy ściągania obrazu platformy Docker

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

Aby rozwiązać problemy z błędami ściągania obrazu platformy Docker, spróbuj wykonać następujące czynności:

  • Upewnij się, że masz łączność z Internetem.
  • Sprawdź, czy zapory firmowe blokują dostęp do rejestru platformy Docker.
  • Spróbuj ponownie zainicjować agenta za pomocą polecenia az aks agent-init.

Problemy z poświadczeniami platformy Azure

Błąd: Uwierzytelnianie platformy Azure nie powiodło się

Aby rozwiązać problemy z uwierzytelnianiem platformy Azure, upewnij się, że interfejs wiersza polecenia platformy Azure jest prawidłowo uwierzytelniony i ma dostęp do niezbędnych zasobów, wykonując następujące czynności:

  1. Sprawdź, czy poświadczenia platformy Azure są prawidłowo skonfigurowane przy użyciu az account show polecenia .

    az account show

  2. W razie potrzeby zaloguj się ponownie przy użyciu az login polecenia .

    az login

Problemy z kontami usług i RBAC (kontrolą dostępu opartą na rolach)

Błąd: Nie znaleziono konta usługi

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

Aby rozwiązać problemy z kontem usługi, upewnij się, że konto usługi Kubernetes zostało prawidłowo utworzone i skonfigurowane, wykonując następujące czynności:

  1. Sprawdź, czy konto usługi istnieje przy użyciu następującego polecenia:

    kubectl get serviceaccount aks-mcp --namespace $NAMESPACE

  2. Jeśli konto użytkownika usługi nie zostanie znalezione, utwórz je, wykonując kroki w Tworzenie konta użytkownika usługi i konfigurowanie tożsamości obciążenia roboczego dla agenta CLI usługi Azure Kubernetes Service (AKS) (wersja próbna)

Błąd: Odmowa dostępu

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

Aby usunąć błędy odmowy uprawnień, upewnij się, że konto usługi Kubernetes ma niezbędne uprawnienia RBAC, wykonując następujące czynności:

  1. Sprawdź, czy uprawnienia RBAC są poprawnie skonfigurowane przy użyciu następujących poleceń:

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

  2. Sprawdź, czy RoleBinding kojarzy prawidłowe konto usługi z rolą, używając następującego polecenia:

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

Problemy z tożsamością zadań obliczeniowych

Błąd: Tożsamość obciążenia nie jest włączona

Error: workload identity is not enabled on this cluster

Jeśli zostanie wyświetlony błąd wskazujący, że tożsamość obciążenia nie jest włączona, sprawdź, czy klaster usługi AKS ma włączoną tożsamość obciążenia, wykonując następujące czynności:

  1. Sprawdź, czy tożsamość obciążenia jest włączona w klastrze AKS przy użyciu polecenia az aks show.

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

  2. Jeśli tożsamość operacyjna nie jest włączona, wykonaj kroki opisane w artykule Tworzenie konta usługi i konfigurowanie tożsamości operacyjnej dla agent CLI usługi Azure Kubernetes Service (wersja preview), aby włączyć tożsamość operacyjną w klastrze.

Błąd: brak adnotacji

Error: service account does not have workload identity annotation

Aby usunąć brakujące błędy adnotacji, upewnij się, że konto usługi Kubernetes ma poprawną adnotację tożsamości obciążenia, wykonując następujące kroki:

  1. Sprawdź, czy adnotacja istnieje na koncie usługi przy użyciu następującego polecenia:

    kubectl describe serviceaccount aks-mcp --namespace $NAMESPACE

  2. Jeśli brakuje adnotacji, dodaj ją przy użyciu następującego polecenia. Upewnij się, że zastąpisz $CLIENT_ID rzeczywistym identyfikatorem klienta uprawnienia tożsamości federacyjnej.

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

Błąd: Opóźnienie propagacji poświadczeń federacyjnych

Jeśli wystąpią błędy związane z nieodnalezieniem poświadczeń tożsamości federacyjnej lub niepowodzeniami uwierzytelniania, może to być spowodowane opóźnieniami propagacji po utworzeniu poświadczeń tożsamości federacyjnej na platformie Azure. Aby rozwiązać ten problem, spróbuj wykonać następujące kroki:

  1. Poczekaj kilka minut na propagację poświadczeń tożsamości federacyjnej w usługach platformy Azure.
  2. Sprawdź przy użyciu polecenia az identity federated-credential list, czy poświadczenie tożsamości federacyjnej istnieje.
az identity federated-credential list --identity-name $IDENTITY_NAME --resource-group $RESOURCE_GROUP

Problemy z inicjalizacją

Błąd: Nie znaleziono rozszerzenia

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

Aby rozwiązać błędy 'rozszerzenie nie znaleziono', upewnij się, że rozszerzenie aks-agent jest poprawnie zainstalowane i załadowane, wykonując następujące kroki:

  1. Zainstaluj rozszerzenie aks-agent przy użyciu polecenia az extension add.

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

  2. Zweryfikuj pomyślną instalację przy użyciu polecenia az extension list.

    az extension list

    Dane wyjściowe powinny zawierać wpis dla aks-agent.

Treści powiązane

  • Last updated on