Installera och använda agentic CLI för Azure Kubernetes Service (AKS) (förhandsversion)

Den här artikeln visar hur du installerar, konfigurerar och använder agentiska CLI för Azure Kubernetes Service (AKS) i klientläge eller klusterläge för att få AI-baserad felsökning och insikter för dina AKS-kluster.

Mer information finns i Översikt över Agentic CLI för AKS.

Viktigt!

AKS-förhandsversionsfunktioner är tillgängliga via självbetjäning och frivillig registrering. Förhandsversioner tillhandahålls "i befintligt skick" och "i mån av tillgång," och de är undantagna från servicenivåavtal och begränsad garanti. AKS-förhandsversioner stöds delvis av kundsupport efter bästa förmåga. Därför är dessa funktioner inte avsedda för produktionsanvändning. Mer information finns i följande supportartiklar:

Förutsättningar

  • Azure CLI version 2.76 eller senare. Kontrollera din version med hjälp av az version kommandot . Information om hur du installerar eller uppdaterar finns i Installera Azure CLI.

  • Ha en API-nyckel för stor språkmodell (LLM). Du måste ta med din egen API-nyckel från någon av de leverantörer som stöds:

    • Azure OpenAI (rekommenderas)
    • OpenAI eller andra LLM-leverantörer som är kompatibla med OpenAPI-specifikationer

  • Ange din aktiva Azure-prenumeration med hjälp av az account set kommandot .

    az account set --subscription "your-subscription-id-or-name"

  • Version 1.0.0b16 eller senare av aks-agent Azure CLI-tillägget, som tillhandahåller agentic CLI för AKS-funktioner. Du kan installera eller uppdatera tillägget med hjälp av Azure CLI.

  • Docker har installerats och körts på den lokala datorn. Installationsinstruktioner finns i Komma igång med Docker.
  • Kontrollera att Docker-daemonen startas och körs innan du fortsätter med installationen.
  • Se till att dina Azure-autentiseringsuppgifter är korrekt konfigurerade och att du har de behörigheter som krävs för att komma åt klusterresurser.

Installera agentic CLI för AKS-tillägget

  1. Installera det agentiska CLI för AKS-tillägget med kommandot az extension add . Om tillägget redan är installerat kan du uppdatera till den senaste versionen med az extension update kommandot . Det här steget kan ta 5 till 10 minuter att slutföra.

    # Install the extension
az extension add --name aks-agent --debug

# Update the extension
az extension update --name aks-agent --debug

  2. Kontrollera att installationen har slutförts med kommandot az extension list.

    az extension list

    Dina utdata bör innehålla en post för aks-agent.

  3. Kontrollera att de agentiska CLI för AKS-kommandona är tillgängliga med hjälp av kommandot [az aks agent][/cli/azure/aks#az-aks-agent] med parametern --help .

    az aks agent --help

    Dina utdata bör visa aks-agent med dess versionsinformation i avsnittet extensions . Till exempel:

    ...
"extensions": {
"aks-agent": "1.0.0b17",
}

Konfigurera din LLM API-nyckel

Innan du fortsätter med installationen måste du konfigurera DIN LLM API-nyckel. Vi rekommenderar att du använder nyare modeller som GPT-5 eller Claude Opus MINI för bättre prestanda. Se till att välja en modell med en hög kontextstorlek på minst 128 000 token eller högre.

  1. Skapa en Azure OpenAI-resurs.
  2. Distribuera modellen. För distributionsnamnet använder du samma namn som modellnamnet, till exempel gpt-4o eller gpt-4o-mini, beroende på åtkomsten. Du kan använda valfri region där du har åtkomst och kvot för modellen. I distributionen väljer du en TPM-gräns (token per minut) så hög som möjligt. Vi rekommenderar uppemot 1 miljon TPM för bra prestanda.
  3. När distributionen är klar bör du notera API-bas-URL:en och API-nyckeln. API-versionen är inte modellversionen. Du kan använda valfri API-version som är tillgänglig och stöds i Azure OpenAI i Microsoft Foundry Models v1 API. Azure API-basen refererar till Azure OpenAI-slutpunkten (som vanligtvis slutar i openai.azure.com/), inte mål-URI:n för distributionen i Foundry.

Azure OpenAI med Microsoft Entra-ID (nyckellös autentisering)

När du väljer "Azure Open AI (Microsoft Entra ID)" som LLM-provider kan du konfigurera nyckellös autentisering med hjälp av Microsoft Entra-ID. Med det här alternativet behöver du inte ange någon API-nyckel. I stället kräver den här autentiseringsmetoden följande rolltilldelningar:

  • Klientläge: De lokala Azure CLI-autentiseringsuppgifterna måste tilldelas rollen Cognitive Services-användare eller Azure AI-användare på Azure OpenAI-resursen.
  • Klusterläge: Arbetsbelastningsidentiteten måste tilldelas rollen Cognitive Services-användare eller Azure AI-användare på Azure OpenAI-resursen.

Andra LLM-leverantörer

Om du använder en annan OpenAI-kompatibel provider följer du deras dokumentation för instruktioner om hur du skapar ett konto och hämtar API-nyckeln.

Verifiera Docker-installationen och starta Docker-daemon

  1. Kontrollera att Docker är installerat och att Docker-daemonen körs med hjälp av följande kommandon:

    docker --version
docker ps

  2. Om du får ett fel som anger att Docker-daemonen inte körs startar du Docker-tjänsten med lämpliga steg för operativsystemet:

    • macOS/Windows:

      • Starta Docker Desktop från dina program.
      • Vänta tills Docker startar.

    • Linux:

      • Starta Docker-tjänsten med följande kommandon:

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

  3. Kontrollera att Docker körs med följande kommando:

    docker info

    Det här kommandot bör returnera Docker-systeminformation utan fel.

Initiera klientläge

  1. Initiera det agentiska CLI:et med klientläget med hjälp av az aks agent-init kommandot . Ersätt platshållarvärdena med den faktiska resursgruppen och klusternamnet.

    az aks agent-init --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME

  2. När du uppmanas att välja ett distributionsläge anger du 2 för klientläge.

    🚀 Welcome to AKS Agent initialization!

Please select the mode you want to use:
  1. Cluster mode - Deploys agent as a pod in your AKS cluster
     Uses service account and workload identity for secure access to cluster and Azure resources
  2. Client mode - Runs agent locally using Docker
     Uses your local Azure credentials and cluster user credentials for access

Enter your choice (1 or 2): 2

  3. Konfigurera information om LLM-providern. Till exempel:

    Welcome to AKS Agent LLM configuration setup. Type '/exit' to exit.
 1. Azure Open AI (API Key)
 1. Azure Open AI (Microsoft Entra ID)
 3. OpenAI
 4. Anthropic
 5. Gemini
 6. Openai Compatible
Enter the number of your LLM provider: 1
Your selected provider: azure
Enter value for MODEL_NAME:  (Hint: should be consistent with your deployed name, e.g., gpt-4.1) gpt-4.1
Enter your API key: 
Enter value for AZURE_API_BASE:  (Hint: https://{your-custom-endpoint}.openai.azure.com/) https://test-example.openai.azure.com
Enter value for AZURE_API_VERSION:  (Default: 2025-04-01-preview)
LLM configuration setup successfully.

    Anmärkning

    API-nyckeln visas tom när du skriver för säkerhet. Ange rätt API-nyckel.

  4. Kontrollera att initieringen lyckades. Agenten hämtar automatiskt nödvändiga Docker-avbildningar när du kör ditt första kommando.

Initiera klusterläge

  1. Initiera det agentiska CLI med klusterläge med hjälp av az aks agent-init kommandot . Ersätt platshållarvärdena med den faktiska resursgruppen och klusternamnet.

    az aks agent-init --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME

  2. När du uppmanas att välja ett distributionsläge anger du 1 för klusterläge.

    🚀 Welcome to AKS Agent initialization!

Please select the mode you want to use:
  1. Cluster mode - Deploys agent as a pod in your AKS cluster
     Uses service account and workload identity for secure access to cluster and Azure resources
  2. Client mode - Runs agent locally using Docker
     Uses your local Azure credentials and cluster user credentials for access

Enter your choice (1 or 2): 1

  3. När du uppmanas att ange målnamnområdet anger du det namnområde där du skapade tjänstkontot. I följande exempel används your-namespace som platshållare. Ersätt den med det faktiska namnområdet som du använde.

    ✅ Cluster mode selected. This will set up the agent deployment in your cluster.

Please specify the namespace where the agent will be deployed.

Enter namespace (e.g., 'kube-system'): your-namespace

  4. Konfigurera information om LLM-providern. Till exempel:

    📦 Using namespace: your-namespace
No existing LLM configuration found. Setting up new configuration...
Please provide your LLM configuration. Type '/exit' to exit.
 1. Azure OpenAI
 2. OpenAI
 3. Anthropic
 4. Gemini
 5. OpenAI Compatible
 6. For other providers, see https://aka.ms/aks/agentic-cli/init
Please choose the LLM provider (1-5): 1

  5. Ange tjänstkontoinformation med hjälp av Kubernetes-tjänstkontot som du skapade för agentdistributionen. I följande exempel används aks-mcp som platshållare för tjänstkontonamnet. Ersätt det med det faktiska namnet på ditt tjänstkonto.

    👤 Service Account Configuration
The AKS agent requires a service account with appropriate permissions in the 'your-namespace'
namespace.
Please ensure you have created the necessary Role and RoleBinding in your namespace for 
this service account.

Enter service account name: aks-mcp

  6. Vänta tills distributionen har slutförts. Initialiseringen implementerar agenten med hjälp av Helm.

    🚀 Deploying AKS agent (this typically takes less than 2 minutes)...
✅ AKS agent deployed successfully!
Verifying deployment status...
✅ AKS agent is ready and running!

🎉 Initialization completed successfully!

  7. Kontrollera framgångsrik distribution och agentens status med hjälp av kommandot az aks agent och parametern --status.

    az aks agent \
--status \
--resource-group $RESOURCE_GROUP \
--name $CLUSTER_NAME \
--namespace $NAMESPACE

    Dina utdata bör indikera att agenten är redo och körs, ungefär så här:

    📊 Checking AKS agent status...

✅ Helm Release: deployed

📦 Deployments:
  • aks-agent: 1/1 ready
  • aks-mcp: 1/1 ready

🐳 Pods:
  • aks-agent-xxxxx-xxxxx: Running ✓
  • aks-mcp-xxxxx-xxxxx: Running ✓

📋 LLM Configurations:
  • azure/gpt-4o
    API Base: https://your-service.openai.azure.com/
    API Version: 2025-04-01-preview

✅ AKS agent is ready and running!

    Anmärkning

    Du kan också verifiera lyckad distribution genom att kontrollera poddar och distributioner i målnamnområdet med hjälp av kubectl:

    kubectl get pods --namespace $NAMESPACE | grep aks-
kubectl get deployment --namespace $NAMESPACE | grep aks-

Använda agentic CLI för AKS

När du har initierat det kan du använda det agentiska CLI för AKS för att felsöka dina kluster och få intelligenta insikter med hjälp av frågor på naturligt språk. Kommandosyntaxen och funktionerna är desamma för både klientläge och klusterläge, förutom parametrarna --mode och --namespace . Klusterläge är standarddistributionsläget, så du behöver bara ange --mode client när du använder klientläge. För klusterläge måste du ange parametern --namespace med namnområdet där agenten distribueras.

Grundläggande frågor

Anmärkning

Om du har konfigurerat flera modeller kan du ange vilken modell som ska användas för varje fråga med hjälp av parametern --model . Till exempel --model=azure/gpt-4o.

Följande är exempel på grundläggande frågor som du kan köra med agentiska CLI för AKS i klientläge:

az aks agent "How many nodes are in my cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client
az aks agent "What is the Kubernetes version on the cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client
az aks agent "Why is coredns not working on my cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client
az aks agent "Why is my cluster in a failed state?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client

Följande är exempel på grundläggande frågor som du kan köra med agentiska CLI för AKS i klusterläge:

az aks agent "How many nodes are in my cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE
az aks agent "What is the Kubernetes version on the cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE
az aks agent "Why is coredns not working on my cluster?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE
az aks agent "Why is my cluster in a failed state?" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE

Upplevelsen använder interaktivt läge som standard, så du kan fortsätta att ställa frågor med kvarhållen kontext tills du vill lämna. Om du vill lämna upplevelsen anger du /exit.

Kommandoparametrar

Kommandot az aks agent har flera parametrar som gör att du kan anpassa felsökningsfunktionen. I följande tabell beskrivs de nyckelparametrar som du kan använda när du kör dina frågor:

Parameter Description
--max-steps Maximalt antal steg som LLM kan vidta för att undersöka problemet. Standard: 40.
--mode Läget bestämmer hur agenten ska distribueras. Tillåtna värden: client, cluster. Förvald: cluster.
--model Ange llm-providern och modellen eller distributionen som ska användas för AI-assistenten.
--name, -n Namnet på det hanterade klustret. (Obligatoriskt)
--namespace Kubernetes-namnområdet där AKS-agenten distribueras. Krävs för klusterläge.
--no-echo-request Inaktivera eko av frågan som tillhandahålls aks-agenten i utdata.
--no-interactive Inaktivera interaktivt läge. När den har angetts uppmanas inte agenten att ange indata och körs i batchläge.
--refresh-toolsets Uppdatera verktygsuppsättningens status.
--resource-group, -g Namnet på resursgruppen. (Obligatoriskt)
--show-tool-output Visa utdata för varje verktyg som anropades.
--status Visa konfigurations- och statusinformation för AKS-agenten.

Modellspecifikation

Parametern --model avgör vilken LLM och provider som analyserar klustret. Till exempel:

  • OpenAI: Använd modellnamnet direkt (till exempel gpt-4o).
  • Azure OpenAI: Använd azure/<deployment name> (till exempel azure/gpt-4o).
  • Antropisk: Använd anthropic/claude-sonnet-4.

Interaktiva kommandon

az aks agent Har en uppsättning underkommandon som underlättar felsökningen. Om du vill komma åt dem anger du / i den interaktiva lägesupplevelsen.

I följande tabell beskrivs tillgängliga interaktiva kommandon:

Befallning Description
/exit Lämna det interaktiva läget.
/help Visa hjälpmeddelanden med alla kommandon.
/clear Rensa skärmen och återställ konversationskontexten.
/tools Visa tillgängliga verktygsuppsättningar och deras status.
/auto Växla visning av verktygsutdata efter svar.
/last Visa alla verktygsutdata från det senaste svaret.
/run Kör ett Bash-kommando och dela det eventuellt med LLM.
/shell Släpp in i det interaktiva gränssnittet och dela sedan sessionen med LLM.
/context Visa konversationskontextens storlek och antal token.
/show Visa de specifika verktygsutdata i en rullningsbar vy.
/feedback Ge feedback om agentens svar.

Inaktivera interaktivt läge

Du kan inaktivera interaktivt läge med hjälp av --no-interactive flaggan med kommandot . Till exempel:

az aks agent "How many pods are in the kube-system namespace" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client --model=azure/gpt-4o --no-interactive
az aks agent "Why are the pods in Crashloopbackoff in the kube-system namespace" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client --model=azure/gpt-4o --no-interactive --show-tool-output

az aks agent "How many pods are in the kube-system namespace" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE --model=azure/gpt-4o --no-interactive
az aks agent "Why are the pods in Crashloopbackoff in the kube-system namespace" --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE --model=azure/gpt-4o --no-interactive --show-tool-output

Verktygsuppsättningar

Det agentiska CLI för AKS innehåller fördefinierade integreringar för populära övervaknings- och observerbarhetsverktyg via verktygsuppsättningar. Vissa integreringar fungerar automatiskt med Kubernetes. Andra integreringar kräver API-nycklar eller konfiguration.

För AKS finns det specifika verktygsuppsättningar som hjälper dig med felsökningen. Dessa verktygsuppsättningar visas i utdata i början av upplevelsen:

...
✅ Toolset kubernetes/kube-prometheus-stack
✅ Toolset internet
✅ Toolset bash
✅ Toolset runbook
✅ Toolset kubernetes/logs
✅ Toolset kubernetes/core
✅ Toolset kubernetes/live-metrics
✅ Toolset aks/core
✅ Toolset aks/node-health
Using 37 datasources (toolsets). To refresh: use flag `--refresh-toolsets`

AKS MCP-serverintegration

SERVERN AKS Model Context Protocol (MCP) är aktiverad som standard med agentic CLI för AKS. Den här upplevelsen startar AKS MCP-servern lokalt (eller i klustret med klusterläge) och använder den som källa för telemetri.

Rensa CLI-distribution av agentik

Rensa klientlägets distribution genom att använda kommandot az aks agent-cleanup tillsammans med parametern --mode client. Det här kommandot tar bort den lokala konfigurationsfilen och återställer agentkonfigurationen.

az aks agent-cleanup --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --mode client

Rensa klusterlägesdistributionen med hjälp av az aks agent-cleanup-kommandot. Ange parametern --namespace med namnområdet där agenten distribueras. Det här kommandot tar bort agentpodden från det angivna namnområdet och tar bort LLM-konfigurationen som lagras i klustret.

az aks agent-cleanup --resource-group $RESOURCE_GROUP --name $CLUSTER_NAME --namespace $NAMESPACE

Utför verifiering av framgångsrik rensning

Kontrollera att den lokala konfigurationsfilen och Docker-avbildningarna har tagits bort med hjälp av följande kommandon:

# Check if configuration file was removed
ls ~/.azure/aksAgent.config

# Check for remaining Docker images
docker images | grep aks-agent

Kontrollera att agentpodden och relaterade resurser har tagits bort från klustret med hjälp av följande kommandon med rätt namnområde:

# Check if agent pod was removed
kubectl get pods --namespace $NAMESPACE

# Check if service account was removed
kubectl get serviceaccount --namespace $NAMESPACE

# Check if namespace was removed (if it was created during init)
kubectl get namespace $NAMESPACE

Ta bort det agentiska CLI för AKS-tillägget

Ta bort det agentiska CLI för AKS-tillägget med kommandot az extension remove .

az extension remove --name aks-agent --debug

Relaterat innehåll

  • Last updated on