Instalación y uso de la CLI agente para Azure Kubernetes Service (AKS) (versión preliminar)

• Docker instalado y en ejecución en el equipo local. Para obtener instrucciones de instalación, consulte Introducción a Docker.
• Asegúrese de que el demonio de Docker esté iniciado y ejecutándose antes de continuar con la instalación.
• Asegúrese de que las credenciales de Azure están configuradas correctamente y tiene los permisos necesarios para acceder a los recursos del clúster.

• Antes de la instalación, debe crear una cuenta de servicio de Kubernetes necesaria con permisos de RBAC. (La configuración de identidad de carga de trabajo es opcional).
• Necesita permisos de escritura para desplegar en el namespace de Kubernetes donde se ubicará el agente.

Verificar la instalación de Docker e iniciar el servicio de Docker

1. Compruebe que Docker está instalado y que el daemon de Docker está corriendo con los siguientes comandos:

   docker --version
   docker ps
   

2. Si recibe un error que indica que el demon de Docker no se está ejecutando, inicie el servicio Docker mediante los pasos adecuados para el sistema operativo:

   • macOS/Windows:

     • Inicie Docker Desktop desde las aplicaciones.
     • Espere a que Se inicie Docker.

   • linux:

     • Inicie el servicio docker con los siguientes comandos:

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

3. Compruebe que Docker se está ejecutando con el comando siguiente:

   docker info
   

   Este comando debe devolver información del sistema de Docker sin errores.

Inicializar el modo de cliente

1. Inicialice la CLI agente con el modo de cliente mediante el az aks agent-init comando . Asegúrese de reemplazar los valores de marcador de posición por el nombre real del grupo de recursos y del clúster.

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

2. Cuando se le pida que seleccione un modo de implementación, escriba 2 para el modo de cliente.

   🚀 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. Configure los detalles del proveedor de LLM. Por ejemplo:

   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.
   

   Nota:

   La clave de API se muestra vacía mientras escribe, como medida de seguridad. Asegúrese de escribir la clave de API correcta.

4. Compruebe que la inicialización se realizó correctamente. El agente extrae automáticamente las imágenes de Docker necesarias al ejecutar el primer comando.

Inicialización del modo de clúster

1. Inicialice la CLI agente con el modo de clúster mediante el az aks agent-init comando . Asegúrese de reemplazar los valores de marcador de posición por el nombre real del grupo de recursos y del clúster.

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

2. Cuando se le pida que seleccione un modo de implementación, escriba 1 para el modo de clúster.

   🚀 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. Cuando se le pida que especifique el espacio de nombres de destino, escriba el espacio de nombres donde creó la cuenta de servicio. En el ejemplo siguiente se usa your-namespace como marcador de posición. Asegúrese de reemplazarlo por el espacio de nombres real que usó.

   ✅ 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. Configure los detalles del proveedor de LLM. Por ejemplo:

   📦 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. Proporcione los detalles de la cuenta de servicio mediante la cuenta de servicio de Kubernetes que creó para la implementación del agente. En el ejemplo siguiente se usa aks-mcp como marcador de posición para el nombre de la cuenta de servicio. Asegúrese de reemplazarlo por el nombre real de la cuenta de servicio.

   👤 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. Espere a que finalice la implementación. La inicialización despliega el agente usando 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. Verifique la implementación exitosa y compruebe el estado del agente utilizando el comando az aks agent con el parámetro --status.

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

   La salida debe indicar que el agente está listo y en ejecución, similar al siguiente:

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

   Nota:

   También puede comprobar si la implementación ha sido correcta. Para ello, compruebe los pods e implementaciones en el espacio de nombres de destino mediante kubectl:

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

A continuación se muestran ejemplos de consultas básicas que puede ejecutar con la CLI agente para AKS en modo de cliente:

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

A continuación se muestran ejemplos de consultas básicas que puede ejecutar con la CLI agente para AKS en modo de clúster:

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

Limpie su implementación en modo cliente usando el comando az aks agent-cleanup y el parámetro --mode client. Este comando quita el archivo de configuración local y restablece la configuración del agente.

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

Limpie la implementación del modo de clúster mediante el comando az aks agent-cleanup. Asegúrese de especificar el --namespace parámetro con el espacio de nombres donde se implementa el agente. Este comando elimina el pod del agente del espacio de nombres especificado y borra la configuración de LLM almacenada en el clúster.

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

Compruebe que el archivo de configuración local y las imágenes de Docker se quitaron mediante los siguientes comandos:

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

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

Compruebe que el pod del agente y los recursos relacionados se hayan quitado del clúster mediante los siguientes comandos con el espacio de nombres adecuado:

# 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