Installer et utiliser l’interface CLI agentique pour Azure Kubernetes Service (AKS) (préversion)

Cet article explique comment installer, configurer et utiliser l’interface CLI agentique pour Azure Kubernetes Service (AKS) en mode client ou en mode cluster pour obtenir des informations et des dépannages optimisés pour l’IA pour vos clusters AKS.

Pour plus d’informations, consultez la vue d’ensemble de l’interface CLI agentique pour AKS.

Important

Les fonctionnalités d’évaluation AKS sont disponibles en libre-service et font l’objet d’un abonnement. Les versions d'essai sont fournies « en l’état » et « selon disponibilité », et elles sont exclues des contrats de niveau de service et de la garantie limitée. Les versions préliminaires AKS sont, dans la mesure du possible, partiellement couvertes par le service clientèle. Par conséquent, ces fonctionnalités ne sont pas destinées à une utilisation en production. Pour plus d’informations, consultez les articles de support suivants :

Prerequisites

  • Azure CLI version 2.76 ou ultérieure. Vérifiez votre version en utilisant la commande az version. Pour installer ou mettre à jour, consultez Installer Azure CLI.

  • Avoir une clé API de modèle de langage volumineux (LLM). Vous devez apporter votre propre clé API à partir de l’un des fournisseurs pris en charge :

    • Azure OpenAI (recommandé)
    • OpenAI ou d’autres fournisseurs LLM compatibles avec les spécifications OpenAPI

  • Définissez votre abonnement Azure actif à l’aide de la az account set commande.

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

  • Version 1.0.0b16 ou ultérieure de l’extension aks-agent Azure CLI, qui fournit l’interface CLI agentique pour les fonctionnalités AKS. Vous pouvez installer ou mettre à jour l’extension à l’aide d’Azure CLI.

  • Docker installé et en cours d’exécution sur votre ordinateur local. Pour obtenir des instructions d’installation, consultez Prise en main de Docker.
  • Vérifiez que le démon Docker est démarré et en cours d’exécution avant de poursuivre l’installation.
  • Vérifiez que vos informations d’identification Azure sont correctement configurées et que vous disposez des autorisations nécessaires pour accéder aux ressources du cluster.

Installer l’interface CLI agentique pour l’extension AKS

  1. Installez l’interface CLI agentique pour l’extension AKS à l’aide de la az extension add commande. Si l’extension est déjà installée, vous pouvez effectuer une mise à jour vers la dernière version avec la az extension update commande. Cette étape peut prendre 5 à 10 minutes.

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

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

  2. Vérifiez la réussite de l’installation à l’aide de la az extension list commande.

    az extension list

    Votre sortie doit inclure une entrée pour aks-agent.

  3. Vérifiez que l'interface CLI pour les commandes AKS est disponible en utilisant la commande [az aks agent][/cli/azure/aks#az-aks-agent] avec le paramètre --help.

    az aks agent --help

    Votre sortie doit afficher les informations de version de aks-agent dans la section extensions. Par exemple:

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

Configurer votre clé API LLM

Avant de procéder à l’installation, vous devez configurer votre clé API LLM. Nous vous recommandons d’utiliser des modèles plus récents tels que GPT-5 ou Claude Opus MINI pour de meilleures performances. Veillez à sélectionner un modèle avec une taille de contexte élevée d’au moins 128 000 jetons ou plus.

  1. Créez une ressource Azure OpenAI.
  2. Déployez le modèle. Pour le nom du déploiement, utilisez le même nom que le nom du modèle, tel que gpt-4o ou gpt-4o-mini, en fonction de l’accès. Vous pouvez utiliser n’importe quelle région où vous avez accès et quota pour le modèle. Dans le déploiement, sélectionnez une limite de jeton par minute (TPM) aussi élevée que possible. Nous vous recommandons plus de 1 million de TPM pour une bonne performance.
  3. Une fois le déploiement terminé, notez l’URL de base de l’API et la clé API. La version de l’API n’est pas la version du modèle. Vous pouvez utiliser n’importe quelle version d’API disponible et prise en charge dans Azure OpenAI dans l’API Microsoft Foundry Models v1. La base d’API Azure fait référence au point de terminaison Azure OpenAI (qui se termine généralement par openai.azure.com/), et non à l’URI cible du déploiement dans Foundry.

Azure OpenAI avec Microsoft Entra ID (authentification sans clé)

Lorsque vous sélectionnez « Azure Open AI (Microsoft Entra ID) » comme fournisseur LLM, vous pouvez configurer l’authentification sans clé à l’aide de l’ID Microsoft Entra. Avec cette option, vous n’avez pas besoin de fournir une clé API. Au lieu de cela, cette méthode d’authentification nécessite les attributions de rôles suivantes :

  • Mode client : les informations d’identification Azure CLI locales doivent être affectées au rôle Utilisateur Cognitive Services ou Utilisateur Azure AI sur la ressource Azure OpenAI.
  • Mode cluster : l’identité de charge de travail doit être affectée au rôle Utilisateur Cognitive Services ou Utilisateur Azure AI sur la ressource Azure OpenAI.

Autres fournisseurs LLM

Si vous utilisez un autre fournisseur compatible OpenAI, suivez leur documentation pour obtenir des instructions sur la création d’un compte et la récupération de la clé API.

Vérifier l’installation de Docker et démarrer le démon Docker

  1. Vérifiez que Docker est installé et que le démon Docker s’exécute à l’aide des commandes suivantes :

    docker --version
docker ps

  2. Si vous recevez une erreur indiquant que le démon Docker n’est pas en cours d’exécution, démarrez le service Docker en suivant les étapes appropriées pour votre système d’exploitation :

    • macOS / Windows :

      • Lancez Docker Desktop à partir de vos applications.
      • Attendez que Docker démarre.

    • Linux :

      • Démarrez le service Docker à l’aide des commandes suivantes :

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

  3. Vérifiez que Docker s’exécute à l’aide de la commande suivante :

    docker info

    Cette commande doit retourner les informations système Docker sans erreurs.

Initialiser le mode client

  1. Initialisez l’interface CLI agentique avec le mode client à l’aide de la az aks agent-init commande. Veillez à remplacer les valeurs d’espace réservé par le nom réel de votre groupe de ressources réel et de votre cluster.

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

  2. Lorsque vous êtes invité à sélectionner un mode de déploiement, entrez 2 pour le mode client.

    🚀 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. Configurez les détails de votre fournisseur LLM. Par exemple:

    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.

    Note

    La clé API s’affiche vide lorsque vous tapez pour la sécurité. Veillez à entrer la clé API appropriée.

  4. Vérifiez que l’initialisation a réussi. L’agent extrait automatiquement les images Docker nécessaires lorsque vous exécutez votre première commande.

Initialiser le mode cluster

  1. Initialisez l’interface CLI agentique avec le mode cluster à l’aide de la az aks agent-init commande. Veillez à remplacer les valeurs d’espace réservé par le nom réel de votre groupe de ressources réel et de votre cluster.

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

  2. Lorsque vous êtes invité à sélectionner un mode de déploiement, entrez 1 pour le mode cluster.

    🚀 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. Lorsque vous êtes invité à spécifier l’espace de noms cible, entrez l’espace de noms où vous avez créé le compte de service. L’exemple suivant utilise your-namespace comme espace réservé. Veillez à le remplacer par l’espace de noms réel que vous avez utilisé.

    ✅ 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. Configurez les détails de votre fournisseur LLM. Par exemple:

    📦 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. Fournissez les détails du compte de service à l’aide du compte de service Kubernetes que vous avez créé pour le déploiement de l’agent. L’exemple suivant utilise aks-mcp comme espace réservé pour le nom du compte de service. Veillez à le remplacer par le nom réel de votre compte de service.

    👤 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. Attendez la fin du déploiement. L’initialisation déploie l’agent à l’aide de 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. Vérifiez le déploiement réussi et vérifiez l’état de l’agent à l’aide de la az aks agent commande avec le --status paramètre.

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

    Votre sortie doit indiquer que l’agent est prêt et en fonctionnement, comme suit :

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

    Note

    Vous pouvez également vérifier le bon déroulement du déploiement en vérifiant les pods et les déploiements dans l’espace de noms cible à l’aide de kubectl.

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

Utiliser l’interface CLI agentique pour AKS

Une fois initialisé, vous pouvez utiliser l’interface CLI agentique pour AKS pour résoudre les problèmes de vos clusters et obtenir des insights intelligents à l’aide de requêtes en langage naturel. La syntaxe de commande et le fonctionnement sont identiques pour le mode client et le mode cluster, à l’exception des paramètres --mode et --namespace. Le mode cluster est le mode de déploiement par défaut. Vous devez donc uniquement spécifier --mode client lors de l’utilisation du mode client. Pour le mode cluster, vous devez spécifier le --namespace paramètre avec l’espace de noms où l’agent est déployé.

Requêtes de base

Note

Si plusieurs modèles sont configurés, vous pouvez spécifier le modèle à utiliser pour chaque requête à l’aide du --model paramètre. Par exemple : --model=azure/gpt-4o.

Voici des exemples de requêtes de base que vous pouvez exécuter avec l’interface CLI agentique pour AKS en mode client :

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

Voici des exemples de requêtes de base que vous pouvez exécuter avec l’interface CLI agentique pour AKS en mode cluster :

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

L’expérience utilise le mode interactif par défaut. Vous pouvez donc continuer à poser des questions avec un contexte conservé jusqu’à ce que vous souhaitiez quitter. Pour quitter l’expérience, entrez /exit.

Paramètres de commande

La az aks agent commande a plusieurs paramètres qui vous permettent de personnaliser l’expérience de résolution des problèmes. Le tableau suivant décrit les paramètres clés que vous pouvez utiliser lors de l’exécution de vos requêtes :

Paramètre Descriptif
--max-steps Nombre maximal d’étapes que le LLM peut effectuer pour examiner le problème. Valeur par défaut : 40.
--mode Le mode détermine la façon dont l’agent est déployé. Valeurs autorisées : client, cluster. Par défaut : cluster.
--model Spécifiez le fournisseur LLM et le modèle ou le déploiement à utiliser pour l’Assistant IA.
--name, -n Nom du cluster géré. (Obligatoire)
--namespace Espace de noms Kubernetes où l’agent AKS est déployé. Obligatoire pour le mode cluster.
--no-echo-request Désactivez l’écho de la question fournie à AKS Agent dans la sortie.
--no-interactive Désactivez le mode interactif. Quand il est défini, l’agent ne demande pas d’entrée et s’exécute en mode batch.
--refresh-toolsets Actualisez l’état des ensembles d’outils.
--resource-group, -g Nom du groupe de ressources. (Obligatoire)
--show-tool-output Affichez la sortie de chaque outil appelé.
--status Afficher les informations de configuration et d’état de l’agent AKS.

Spécification du modèle

Le --model paramètre détermine le LLM et le fournisseur qui analyse votre cluster. Par exemple:

  • OpenAI : Utilisez directement le nom du modèle (par exemple, gpt-4o).
  • Azure OpenAI : Utiliser azure/<deployment name> (par exemple, azure/gpt-4o).
  • Anthropic : Use anthropic/claude-sonnet-4.

Commandes interactives

az aks agent a un ensemble de sous-commandes qui facilitent l’expérience de résolution des problèmes. Pour y accéder, entrez / dans l’expérience de mode interactif.

Le tableau suivant décrit les commandes interactives disponibles :

Command Descriptif
/exit Quittez le mode interactif.
/help Afficher les messages d’aide avec toutes les commandes.
/clear Effacez l’écran et réinitialisez le contexte de conversation.
/tools Afficher les ensembles d’outils disponibles et leur état.
/auto Changer l’affichage des sorties de l’outil après les réponses.
/last Afficher toutes les sorties de l’outil à partir de la dernière réponse.
/run Exécutez une commande Bash et partagez-la éventuellement avec LLM.
/shell Accédez au shell interactif, puis partagez éventuellement la session avec LLM, si vous le souhaitez.
/context Afficher la taille du contexte de conversation et le nombre de jetons.
/show Afficher la sortie de l’outil spécifique dans une vue à défilement.
/feedback Fournissez des commentaires sur la réponse de l’agent.

Désactiver le mode interactif

Vous pouvez désactiver le mode interactif à l’aide de l’indicateur --no-interactive avec votre commande. Par exemple:

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

Ensembles d’outils

L’interface CLI agentique pour AKS inclut des intégrations prédéfinies pour les outils de surveillance et d’observabilité populaires via des ensembles d’outils. Certaines intégrations fonctionnent automatiquement avec Kubernetes. D’autres intégrations nécessitent des clés d’API ou une configuration.

Pour AKS, il existe des ensembles d’outils spécifiques qui aident à résoudre les problèmes. Ces ensembles d’outils apparaissent dans la sortie au début de l’expérience :

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

Intégration du serveur AKS MCP

Le serveur MCP (AKS Model Context Protocol) est activé par défaut avec l’interface CLI agentique pour AKS. Cette expérience fait tourner le serveur MCP AKS localement (ou dans le cluster en mode cluster) et l’utilise comme source pour la télémétrie.

Nettoyer le déploiement de l’interface CLI agentique

Nettoyez votre déploiement en mode client à l’aide de la commande az aks agent-cleanup avec le paramètre --mode client. Cette commande supprime le fichier de configuration local et réinitialise la configuration de l’agent.

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

Nettoyez votre déploiement en mode cluster à l’aide de la az aks agent-cleanup commande. Veillez à spécifier le --namespace paramètre avec l’espace de noms où l’agent est déployé. Cette commande supprime le pod de l’agent de l’espace de noms spécifié et supprime la configuration LLM stockée sur le cluster.

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

Vérifier le nettoyage réussi

Vérifiez que le fichier de configuration local et les images Docker ont été supprimés à l’aide des commandes suivantes :

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

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

Vérifiez que le pod de l’agent et les ressources associées ont été supprimés du cluster à l’aide des commandes suivantes avec l’espace de noms approprié :

# 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

Supprimer l’interface CLI agentique pour l’extension AKS

Supprimez l’interface CLI agentique pour l’extension AKS à l’aide de la commande az extension remove.

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

Contenu connexe

  • Last updated on