De agentische CLI voor Azure Kubernetes Service (AKS) installeren en gebruiken (preview)

In dit artikel leest u hoe u de agentische CLI voor Azure Kubernetes Service (AKS) installeert, configureert en gebruikt in de clientmodus of clustermodus om op AI gebaseerde probleemoplossing en inzichten voor uw AKS-clusters op te halen.

Voor meer informatie, zie het overzicht van de Agentic CLI voor AKS.

Belangrijk

AKS preview-functies zijn beschikbaar op selfservice, opt-in basis. Previews worden geleverd 'zoals het is' en 'voor zover beschikbaar' en zijn uitgesloten van de serviceovereenkomsten en beperkte garantie. AKS-previews worden gedeeltelijk gedekt door klantondersteuning naar best vermogen. Zodoende zijn deze functies niet bedoeld voor productiegebruik. Zie de volgende ondersteuningsartikelen voor meer informatie:

Vereiste voorwaarden

  • Azure CLI versie 2.76 of hoger. Controleer uw versie met behulp van de az version opdracht. Als u Azure CLI wilt installeren of bijwerken, raadpleegt u Azure CLI installeren.

  • Een LLM-API-sleutel (Large Language Model) hebben. U moet uw eigen API-sleutel van een van de ondersteunde providers gebruiken:

    • Azure OpenAI (aanbevolen)
    • OpenAI of andere LLM-providers die compatibel zijn met OpenAPI-specificaties

  • Stel uw actieve Azure-abonnement in met behulp van de az account set opdracht.

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

  • Versie 1.0.0b16 of hoger van de aks-agent Azure CLI-extensie, die de agentische CLI voor AKS-functionaliteit biedt. U kunt de extensie installeren of bijwerken met behulp van de Azure CLI.

  • Docker is geïnstalleerd en uitgevoerd op uw lokale computer. Zie Aan de slag met Docker voor installatie-instructies.
  • Zorg ervoor dat de Docker-daemon is gestart en wordt uitgevoerd voordat u doorgaat met de installatie.
  • Zorg ervoor dat uw Azure-referenties correct zijn geconfigureerd en u beschikt over de benodigde machtigingen voor toegang tot clusterbronnen.

De agentische CLI voor AKS-extensie installeren

  1. Installeer de agentische CLI voor AKS-extensie met behulp van de az extension add opdracht. Als de extensie al is geïnstalleerd, kunt u met de opdracht bijwerken naar de az extension update nieuwste versie. Het kan 5 tot 10 minuten duren voordat deze stap is voltooid.

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

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

  2. Controleer of de installatie is geslaagd met behulp van de az extension list opdracht.

    az extension list

    De uitvoer moet een vermelding bevatten voor aks-agent.

  3. Controleer of de agentische CLI voor AKS-opdrachten beschikbaar zijn met behulp van de opdracht [az aks agent][/cli/azure/aks#az-aks-agent] met de --help parameter.

    az aks agent --help

    De uitvoer moet de aks-agent bijbehorende versiegegevens in de extensions sectie weergeven. Voorbeeld:

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

Stel uw LLM API-sleutel in

Voordat u doorgaat met de installatie, moet u uw LLM API-sleutel instellen. We raden u aan nieuwere modellen zoals GPT-5 of Claude Opus MINI te gebruiken voor betere prestaties. Zorg ervoor dat u een model selecteert met een hoge contextgrootte van ten minste 128.000 tokens of hoger.

  1. Maak een Azure OpenAI-resource.
  2. Implementeer het model. Gebruik voor de implementatienaam dezelfde naam als de modelnaam, zoals gpt-4o of gpt-4o-mini, afhankelijk van de toegang. U kunt elke regio gebruiken waar u toegang en quota voor het model hebt. Selecteer in de implementatie een TPM-limiet (token per minuut) die zo hoog mogelijk is. We raden u aan om maximaal 1 miljoen TPM's te gebruiken voor goede prestaties.
  3. Nadat de implementatie is voltooid, noteert u de API-basis-URL en API-sleutel. De API-versie is niet de modelversie. U kunt elke API-versie gebruiken die beschikbaar is en wordt ondersteund in Azure OpenAI in Microsoft Foundry Models v1 API. De Azure API-basis verwijst naar het Azure OpenAI-eindpunt (dat meestal eindigt op openai.azure.com/), niet de doel-URI van de implementatie in Foundry.

Azure OpenAI met Microsoft Entra ID (sleutelloze verificatie)

Wanneer u 'Azure Open AI (Microsoft Entra ID)' selecteert als uw LLM-provider, kunt u sleutelloze verificatie configureren met behulp van Microsoft Entra-id. Met deze optie hoeft u geen API-sleutel op te geven. In plaats daarvan zijn voor deze verificatiemethode de volgende roltoewijzingen vereist:

  • Clientmodus: aan de lokale Azure CLI-referenties moet de rol Cognitive Services-gebruiker of Azure AI-gebruiker in de Azure OpenAI-resource worden toegewezen.
  • Clustermodus: aan de workloadidentiteit moet de rol Cognitive Services-gebruiker of Azure AI-gebruiker in de Azure OpenAI-resource worden toegewezen.

Andere LLM-providers

Als u een andere openAI-compatibele provider gebruikt, volgt u de bijbehorende documentatie voor instructies over het maken van een account en het ophalen van de API-sleutel.

Docker-installatie verifiëren en Docker-daemon starten

  1. Controleer of Docker is geïnstalleerd en of de Docker-daemon wordt uitgevoerd met behulp van de volgende opdrachten:

    docker --version
docker ps

  2. Als er een foutbericht wordt weergegeven dat de Docker-daemon niet wordt uitgevoerd, start u de Docker-service met behulp van de juiste stappen voor uw besturingssysteem:

    • macOS/Windows:

      • Start Docker Desktop vanuit uw toepassingen.
      • Wacht tot Docker is gestart.

    • Linux:

      • Start de Docker-service met behulp van de volgende opdrachten:

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

  3. Controleer of Docker wordt uitgevoerd met behulp van de volgende opdracht:

    docker info

    Met deze opdracht moet docker-systeeminformatie zonder fouten worden geretourneerd.

Clientmodus initialiseren

  1. Initialiseer de agentische CLI met de clientmodus met behulp van de az aks agent-init opdracht. Zorg ervoor dat u de plaatshouderwaarden vervangt door uw werkelijke resourcegroep en clusternaam.

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

  2. Wanneer u wordt gevraagd om een implementatiemodus te selecteren, voert u 2 in voor de clientmodus.

    🚀 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. Configureer de details van uw LLM-provider. Voorbeeld:

    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.

    Opmerking

    De API-sleutel wordt leeg weergegeven terwijl u typt voor beveiliging. Zorg ervoor dat u de juiste API-sleutel invoert.

  4. Controleer of de initialisatie is geslaagd. De agent haalt automatisch de benodigde Docker-installatiekopieën op wanneer u uw eerste opdracht uitvoert.

Clustermodus initialiseren

  1. Initialiseer de agentische CLI met de clustermodus met behulp van de az aks agent-init opdracht. Zorg ervoor dat u de plaatshouderwaarden vervangt door uw werkelijke resourcegroep en clusternaam.

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

  2. Wanneer u wordt gevraagd om een implementatiemodus te selecteren, voert u 1 in voor de clustermodus.

    🚀 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. Wanneer u wordt gevraagd om de doelnaamruimte op te geven, voert u de naamruimte in waar u het serviceaccount hebt gemaakt. your-namespace wordt in het volgende voorbeeld als een tijdelijke aanduiding gebruikt. Zorg ervoor dat u deze vervangt door de werkelijke naamruimte die u hebt gebruikt.

    ✅ 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. Configureer de details van uw LLM-provider. Voorbeeld:

    📦 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. Geef serviceaccountgegevens op met behulp van het Kubernetes-serviceaccount dat u hebt gemaakt voor de agentimplementatie. Het volgende voorbeeld gebruikt aks-mcp als tijdelijke aanduiding voor de naam van het service-account. Zorg ervoor dat u deze vervangt door de werkelijke naam van uw serviceaccount.

    👤 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. Wacht tot de implementatie is voltooid. De initialisatie implementeert de agent met behulp van 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. Controleer of de implementatie is geslaagd en controleer de status van de agent met behulp van de az aks agent opdracht met de --status parameter.

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

    Je resultaat moet aangeven dat de agent klaar en actief is, vergelijkbaar met het volgende:

    📊 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!

    Opmerking

    U kunt ook een geslaagde implementatie controleren door de pods en implementaties in de doelnaamruimte te controleren met behulp van kubectl:

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

De agentische CLI voor AKS gebruiken

Nadat u de agentische CLI voor AKS hebt geïnitialiseerd, kunt u problemen met uw clusters oplossen en intelligente inzichten verkrijgen met behulp van query's in natuurlijke taal. De syntaxis en functionaliteit van de opdracht zijn hetzelfde voor zowel clientmodus als clustermodus, met uitzondering van de --mode en --namespace parameters. De clustermodus is de standaardimplementatiemodus, dus u hoeft alleen op te geven --mode client wanneer u de clientmodus gebruikt. Voor de clustermodus moet u de --namespace parameter opgeven met de naamruimte waarin de agent is geïmplementeerd.

Basisqueries

Opmerking

Als u meerdere modellen hebt ingesteld, kunt u het model opgeven dat voor elke query moet worden gebruikt met behulp van de --model parameter. Bijvoorbeeld: --model=azure/gpt-4o.

Hier volgen enkele voorbeelden van basisquery's die u kunt uitvoeren met de agentische CLI voor AKS in de clientmodus:

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

Hier volgen enkele voorbeelden van basisquery's die u kunt uitvoeren met de agentische CLI voor AKS in de clustermodus:

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

De ervaring maakt standaard gebruik van de interactieve modus, zodat u vragen met behoud van context kunt blijven stellen totdat u wilt vertrekken. Als u de ervaring wilt verlaten, voert u in /exit.

Opdrachtparameters

De az aks agent opdracht heeft verschillende parameters waarmee u de probleemoplossingservaring kunt aanpassen. In de volgende tabel worden de belangrijkste parameters beschreven die u kunt gebruiken bij het uitvoeren van uw query's:

Kenmerk Description
--max-steps Het maximum aantal stappen dat de LLM kan uitvoeren om het probleem te onderzoeken. Standaard: 40.
--mode De modus bepaalt hoe de agent wordt geïmplementeerd. Toegestane waarden: client, cluster. Standaard: cluster.
--model Geef de LLM-provider en het model of de implementatie op die moet worden gebruikt voor de AI-assistent.
--name, -n Naam van het beheerde cluster. (Vereist)
--namespace De Kubernetes-naamruimte waar de AKS-agent is geïmplementeerd. Vereist voor de clustermodus.
--no-echo-request Schakel het terugkoppelen van de vraag aan de AKS-agent uit in de uitvoer.
--no-interactive Schakel de interactieve modus uit. Wanneer deze is ingesteld, wordt de agent niet gevraagd om invoer en wordt deze uitgevoerd in de batchmodus.
--refresh-toolsets Vernieuw de status van de toolsets.
--resource-group, -g Naam van resourcegroep. (Vereist)
--show-tool-output Geef de uitvoer weer van elk hulpprogramma dat is aangeroepen.
--status Configuratie- en statusgegevens van de AKS-agent weergeven.

Modelspecificatie

De --model parameter bepaalt welke LLM en provider uw cluster analyseert. Voorbeeld:

  • OpenAI: Gebruik de modelnaam rechtstreeks (bijvoorbeeld gpt-4o).
  • Azure OpenAI: Gebruiken azure/<deployment name> (bijvoorbeeld azure/gpt-4o).
  • Antropisch: Gebruik anthropic/claude-sonnet-4.

Interactieve opdrachten

De az aks agent bevat een reeks subopdrachten die de probleemoplossingservaring helpen. Voer / in de interactieve moduservaring in.

In de volgende tabel worden de beschikbare interactieve opdrachten beschreven:

Command Description
/exit Laat de interactieve modus staan.
/help Help-berichten weergeven met alle opdrachten.
/clear Wis het scherm en stel de gesprekscontext opnieuw in.
/tools Beschikbare toolsets en hun status weergeven.
/auto Schakel de weergave van de uitvoer van tools na ontvangst van reacties.
/last Alle uitvoer van het hulpprogramma uit het laatste antwoord weergeven.
/run Voer een Bash-opdracht uit en deel deze desgewenst met LLM.
/shell Ga naar de interactieve shell en deel de sessie vervolgens optioneel met LLM.
/context De grootte van de gesprekscontext en het aantal tokens weergeven.
/show De specifieke uitvoer van het hulpprogramma weergeven in een schuifbare weergave.
/feedback Feedback geven over het antwoord van de agent.

Interactieve modus uitschakelen

U kunt de interactieve modus uitschakelen met behulp van de --no-interactive vlag met uw opdracht. Voorbeeld:

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

Hulpmiddelensets

De agentgebaseerde CLI voor AKS biedt vooraf gedefinieerde integraties voor veelgebruikte tools voor monitoring en waarneembaarheid via toolsets. Sommige integraties werken automatisch met Kubernetes. Voor andere integraties zijn API-sleutels of configuratie vereist.

Voor AKS zijn er specifieke hulpprogramma's die u helpen bij het oplossen van problemen. Deze hulppakketten worden weergegeven in de uitvoer aan het begin van de gebruikerservaring.

...
✅ 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`

Integratie van AKS MCP-server

De MCP-server (AKS Model Context Protocol) is standaard ingeschakeld met de agentische CLI voor AKS. Dit programma start de AKS MCP-server lokaal op (of in het cluster in clustermodus) en gebruikt deze als telemetriebron.

Agent-gebaseerde CLI-implementatie opschonen

Schoon de implementatie van de clientmodus op met behulp van de az aks agent-cleanup opdracht met de --mode client parameter. Met deze opdracht wordt het lokale configuratiebestand verwijderd en wordt de agentconfiguratie opnieuw ingesteld.

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

Schoon de implementatie van de clustermodus op met behulp van de az aks agent-cleanup opdracht. Zorg ervoor dat u de --namespace parameter opgeeft met de naamruimte waar de agent is geïmplementeerd. Met deze opdracht verwijdert u de agentpod uit de opgegeven naamruimte en verwijdert u de LLM-configuratie die is opgeslagen op het cluster.

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

Controleren of het opschonen is gelukt

Controleer of het lokale configuratiebestand en docker-installatiekopieën zijn verwijderd met behulp van de volgende opdrachten:

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

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

Controleer of de agentpod en gerelateerde resources uit het cluster zijn verwijderd met behulp van de volgende opdrachten met de juiste naamruimte:

# 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

De agentische CLI voor AKS-extensie verwijderen

Verwijder de agentische CLI voor AKS-extensie met behulp van de az extension remove opdracht.

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

Verwante inhoud

  • Last updated on