Installieren und Verwenden der agentischen CLI für Azure Kubernetes Service (AKS) (Vorschau)

• Docker auf Ihrem lokalen Computer installiert und ausgeführt. Installationsanweisungen finden Sie unter "Erste Schritte mit Docker".
• Stellen Sie sicher, dass der Docker-Daemon gestartet und ausgeführt wird, bevor Sie mit der Installation fortfahren.
• Stellen Sie sicher, dass Ihre Azure-Anmeldeinformationen ordnungsgemäß konfiguriert sind und Sie über die erforderlichen Berechtigungen für den Zugriff auf Clusterressourcen verfügen.

• Vor der Installation müssen Sie ein erforderliches Kubernetes-Dienstkonto mit RBAC-Berechtigungen erstellen. (Die Einrichtung der Workload-Identität ist optional.)
• Sie benötigen Schreibzugriff, um den Kubernetes-Namespace bereitzustellen, in dem der Agent bereitgestellt wird.

Überprüfen der Docker-Installation und Starten des Docker-Daemons

1. Vergewissern Sie sich, dass Docker installiert ist und der Docker-Daemon mit den folgenden Befehlen ausgeführt wird:

   docker --version
   docker ps
   

2. Wenn Sie einen Fehler erhalten, der angibt, dass der Docker-Daemon nicht ausgeführt wird, starten Sie den Docker-Dienst mit den entsprechenden Schritten für Ihr Betriebssystem:

   • macOS / Windows:

     • Starten Sie Docker Desktop aus Ihren Anwendungen.
     • Warten Sie, bis Docker gestartet wird.

   • Linux:

     • Starten Sie den Docker-Dienst mit den folgenden Befehlen:

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

3. Überprüfen Sie, ob Docker mit dem folgenden Befehl ausgeführt wird:

   docker info
   

   Dieser Befehl sollte Docker-Systeminformationen ohne Fehler zurückgeben.

Initialisieren des Clientmodus

1. Initialisieren Sie die agentische CLI mit dem Clientmodus mithilfe des az aks agent-init Befehls. Ersetzen Sie die Werte der Platzhalter durch den tatsächlichen Namen der Ressourcengruppe und des Clusters.

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

2. Wenn Sie aufgefordert werden, einen Bereitstellungsmodus auszuwählen, geben Sie "2 " für den Clientmodus ein.

   🚀 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. Konfigurieren Sie Ihre LLM-Anbieterdetails. Beispiel:

   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.
   

   Hinweis

   Der API-Schlüssel wird aus Sicherheitsgründen beim Eingeben als leer angezeigt. Stellen Sie sicher, dass Sie den richtigen API-Schlüssel eingeben.

4. Überprüfen Sie, ob die Initialisierung erfolgreich war. Der Agent ruft automatisch die erforderlichen Docker-Images ab, wenn Sie den ersten Befehl ausführen.

Clustermodus initialisieren

1. Initialisieren Sie die agentische CLI mit dem Clustermodus mithilfe des az aks agent-init Befehls. Ersetzen Sie die Werte der Platzhalter durch den tatsächlichen Namen der Ressourcengruppe und des Clusters.

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

2. Wenn Sie aufgefordert werden, einen Bereitstellungsmodus auszuwählen, geben Sie "1 " für den Clustermodus ein.

   🚀 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. Wenn Sie aufgefordert werden, den Zielnamespace anzugeben, geben Sie den Namespace ein, in dem Sie das Dienstkonto erstellt haben. Im folgenden Beispiel wird als Platzhalter verwendet your-namespace . Stellen Sie sicher, dass Sie ihn durch den tatsächlichen Namespace ersetzen, den Sie verwendet haben.

   ✅ 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. Konfigurieren Sie Ihre LLM-Anbieterdetails. Beispiel:

   📦 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. Stellen Sie Dienstkontodetails mithilfe des Kubernetes-Dienstkontos bereit, das Sie für die Agentbereitstellung erstellt haben. Im folgenden Beispiel wird als Platzhalter für den Dienstkontonamen verwendet aks-mcp . Stellen Sie sicher, dass Sie ihn durch den tatsächlichen Namen Ihres Dienstkontos ersetzen.

   👤 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. Warten Sie auf den Abschluss der Bereitstellung. Bei der Initialisierung wird der Agent mithilfe von Helm bereitgestellt.

   🚀 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. Überprüfen Sie die erfolgreiche Bereitstellung und kontrollieren Sie den Status des Agents mithilfe des Befehls az aks agent mit dem Parameter --status.

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

   Ihre Ausgabe sollte angeben, dass der Agent bereit ist und läuft, ähnlich wie das Folgende:

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

   Hinweis

   Sie können die erfolgreiche Bereitstellung auch verifizieren, indem Sie die Pods und Bereitstellungen im Ziel-Namespace mit kubectl überprüfen:

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

Im Folgenden finden Sie Beispiele für grundlegende Abfragen, die Sie mit der agentischen CLI für AKS im Clientmodus ausführen können:

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

Im Folgenden finden Sie Beispiele für grundlegende Abfragen, die Sie mit der agentischen CLI für AKS im Clustermodus ausführen können:

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

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

Bereinigen Sie Ihre Bereitstellung im Client-Modus mit dem az aks agent-cleanup-Befehl mit dem Parameter --mode client. Mit diesem Befehl wird die lokale Konfigurationsdatei entfernt und die Agentkonfiguration zurückgesetzt.

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

Bereinigen Sie Ihre Clustermodus-Bereitstellung mit dem Befehl az aks agent-cleanup. Stellen Sie sicher, dass Sie den --namespace Parameter mit dem Namespace angeben, in dem der Agent bereitgestellt wird. Mit diesem Befehl wird der Agent-Pod aus dem angegebenen Namespace entfernt und die im Cluster gespeicherte LLM-Konfiguration gelöscht.

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

Überprüfen Sie, ob die lokale Konfigurationsdatei und Docker-Images mithilfe der folgenden Befehle entfernt wurden:

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

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

Überprüfen Sie, ob der Agent-Pod und die zugehörigen Ressourcen mithilfe der folgenden Befehle mit dem entsprechenden Namespace aus dem Cluster entfernt wurden:

# 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