Установка и использование CLI агента для службы Azure Kubernetes (AKS) (предварительная версия)

В этой статье показано, как установить, настроить и использовать интерфейс командной строки agentic для службы Azure Kubernetes (AKS) в режиме клиента или кластерном режиме, чтобы получать устранение неполадок на базе ИИ и аналитические сведения о кластерах AKS.

Дополнительные сведения см. в обзоре Agentic CLI для AKS.

Это важно

Предварительные версии функций AKS доступны на условиях самообслуживания и добровольного выбора. Предварительные версии предоставляются "как есть" и "при наличии". На них не распространяются соглашения об уровне обслуживания и ограниченная гарантия. Предварительные версии AKS сопровождаются частичной поддержкой клиентов на основе принципа лучших усилий. Как таковые, эти функции не предназначены для использования в производстве. Для получения дополнительной информации ознакомьтесь со следующими статьями поддержки:

• Политики поддержки AKS
• Часто задаваемые вопросы о поддержке Azure

Предпосылки

• Azure CLI версии 2.76 или более поздней. Проверьте версию с помощью az version команды. Сведения об установке или обновлении см. в статье "Установка Azure CLI".

• У вас есть ключ API большой языковой модели (LLM). Необходимо принести собственный ключ API из одного из поддерживаемых поставщиков:

  • Azure OpenAI (рекомендуется)
  • OpenAI или другие поставщики LLM, совместимые со спецификациями OpenAPI

• Задайте активную подписку Azure с помощью az account set команды.

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

• Версия 1.0.0b16 или более поздней версии aks-agent расширения Azure CLI, которая предоставляет агентический интерфейс командной строки для функциональных возможностей AKS. Вы можете установить или обновить расширение с помощью Azure CLI.

• Docker установлен и запущен на локальном компьютере. Инструкции по установке см. в разделе "Начало работы с Docker".
• Убедитесь, что демон Docker запущен и работает, прежде чем продолжить установку.
• Убедитесь, что учетные данные Azure настроены правильно и у вас есть необходимые разрешения для доступа к ресурсам кластера.

• Перед установкой необходимо создать необходимую учетную запись службы Kubernetes с разрешениями RBAC. (Настройка удостоверения рабочей нагрузки является необязательной.)
• Вам нужен доступ на запись для развертывания в пространстве имен Kubernetes, где будет развертываться агент.

Установка расширения AGENTIC CLI для AKS

1. Установите агентический интерфейс командной строки для расширения AKS с помощью az extension add команды. Если расширение уже установлено, можно обновить до последней az extension update версии с помощью команды. Для завершения этого шага может потребоваться от 5 до 10 минут.

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

2. Проверьте успешную установку с помощью команды az extension list.

   az extension list
   

   Выходные данные должны содержать запись для aks-agent.

3. Проверьте, что команды agentic CLI для AKS доступны, используя команду [az aks agent][/cli/azure/aks#az-aks-agent] с параметром --help.

   az aks agent --help
   

   Выходные aks-agent данные должны отображаться в разделе со сведениями о extensions его версии. Рассмотрим пример.

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

Настройка ключа API LLM

Прежде чем продолжить установку, необходимо настроить ключ API LLM. Мы рекомендуем использовать более новые модели, такие как GPT-5 или Claude Opus MINI для повышения производительности. Не забудьте выбрать модель с высоким размером контекста не менее 128 000 маркеров или выше.

Azure OpenAI (рекомендуется)

1. Создайте ресурс Azure OpenAI.
2. Разверните модель. Для имени развертывания используйте то же имя, что и имя модели, например gpt-4o или gpt-4o-mini, в зависимости от доступа. Вы можете использовать любой регион, где у вас есть доступ и квота на модель. В развертывании выберите наиболее высокий возможный предел токенов в минуту (TPM). Мы рекомендуем более 1 миллиона TPM для хорошей производительности.
3. После завершения развертывания обратите внимание на базовый URL-адрес API и ключ API. Версия API не является версией модели. Вы можете использовать любую версию API, доступную и поддерживаемую в Azure OpenAI, в API Microsoft Foundry Models версии 1. Основа API Azure относится к конечной точке Azure OpenAI (которая обычно заканчивается на openai.azure.com/), а не к целевому URI развертывания в Foundry.

Azure OpenAI с идентификатором Microsoft Entra (проверка подлинности без ключей)

Выбрав "Azure Open AI (Microsoft Entra ID)" в качестве поставщика LLM, можно настроить проверку подлинности без ключа с помощью идентификатора Microsoft Entra. С помощью этого параметра вам не нужно предоставлять ключ API. Вместо этого этот метод проверки подлинности требует следующих назначений ролей:

• Режим клиента: локальные учетные данные Azure CLI должны быть назначены роли пользователя Cognitive Services или пользователя ИИ Azure в ресурсе Azure OpenAI.
• Режим кластера: удостоверение рабочей нагрузки должно быть назначено роли пользователя Cognitive Services или пользователя ИИ Azure в ресурсе Azure OpenAI.

Другие поставщики LLM

Если вы используете другой поставщик, совместимый с OpenAI, следуйте инструкциям по созданию учетной записи и получению ключа API.

Проверка установки Docker и запуск управляющей программы Docker

1. Убедитесь, что Docker установлен, а управляющая программа Docker выполняется с помощью следующих команд:

   docker --version
   docker ps
   

2. Если появится сообщение об ошибке, указывающее, что управляющая программа Docker не запущена, запустите службу Docker, выполнив соответствующие действия для операционной системы:

   • macOS или Windows:

     • Запустите Docker Desktop из приложений.
     • Дождитесь запуска Docker.

   • Linux:

     • Запустите службу Docker с помощью следующих команд:

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

3. Убедитесь, что Docker выполняется с помощью следующей команды:

   docker info
   

   Эта команда должна возвращать сведения о системе Docker без ошибок.

Инициализация режима клиента

1. Инициализировать агентический интерфейс командной строки с помощью режима клиента с помощью az aks agent-init команды. Обязательно замените значения плейсхолдеров на фактические имена вашей группы ресурсов и кластера.

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

2. При появлении запроса на выбор режима развертывания введите 2 для режима клиента.

   🚀 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. Настройте сведения о поставщике LLM. Рассмотрим пример.

   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.
   

   Замечание

   Ключ API отображается пустым при вводе для безопасности. Обязательно введите правильный ключ API.

4. Убедитесь, что инициализация выполнена успешно. Агент автоматически извлекает необходимые образы Docker при выполнении первой команды.

Инициализация режима кластера

1. Инициализируйте агентский CLI в режиме кластера, используя команду az aks agent-init. Обязательно замените значения плейсхолдеров на фактические имена вашей группы ресурсов и кластера.

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

2. При появлении запроса на выбор режима развертывания введите 1 для режима кластера.

   🚀 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. При появлении запроса на указание целевого пространства имен введите пространство имен, в котором вы создали учетную запись службы. В следующем примере используется your-namespace в качестве заполнителя. Обязательно замените его фактическим пространством имен, которое вы использовали.

   ✅ 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. Настройте сведения о поставщике LLM. Рассмотрим пример.

   📦 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. Укажите сведения об учетной записи службы Kubernetes, которую вы создали для развертывания агента. В следующем примере в качестве заполнителя используется aks-mcp для имени учетной записи службы. Обязательно замените его фактическим именем учетной записи службы.

   👤 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. Дождитесь завершения развертывания. Развертывание агента осуществляется с помощью 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. Проверьте успешное развертывание и проверьте состояние агента с помощью az aks agent команды с параметром --status .

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

   Выходные данные должны указывать, что агент готов и запущен, как показано ниже.

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

   Замечание

   Вы также можете проверить успешное развертывание, проверив модули pod и развертывания в целевом пространстве имен с помощью kubectl:

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

Используйте агентский интерфейс командной строки для AKS

После инициализации можно использовать агентический интерфейс командной строки для AKS для устранения неполадок кластеров и получения интеллектуальной аналитики с помощью запросов естественного языка. Синтаксис команды и функциональные возможности одинаковы как для режима клиента, так и для режима кластера, за исключением --mode параметров и --namespace параметров. Режим кластера — это режим развертывания по умолчанию, поэтому необходимо указать --mode client только при использовании клиентского режима. Для режима кластера необходимо указать --namespace параметр с пространством имен, в котором развертывается агент.

Базовые запросы

Замечание

Если настроено несколько моделей, можно указать модель, используемую для каждого запроса с помощью --model параметра. Например: --model=azure/gpt-4o.

Ниже приведены примеры базовых запросов, которые можно запустить с помощью агента CLI для AKS в клиентском режиме:

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

Ниже приведены примеры базовых запросов, которые можно выполнять с помощью агента cli для AKS в режиме кластера:

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

Интерфейс использует интерактивный режим по умолчанию, поэтому вы можете продолжать задавать вопросы с сохраненным контекстом, пока вы не хотите уйти. Чтобы выйти из опыта, введите /exit.

Параметры команды

Команда az aks agent имеет несколько параметров, позволяющих настроить интерфейс устранения неполадок. В следующей таблице описаны ключевые параметры, которые можно использовать при выполнении запросов:

Параметр	Description
--max-steps	Максимальное количество шагов, которые LLM может предпринять для изучения проблемы. Значение по умолчанию: 40.
--mode	Режим определяет, как развертывается агент. Допустимые значения: client, cluster. По умолчанию: cluster.
--model	Укажите поставщика LLM и модель или развертывание для помощника по искусственному интеллекту.
--name, -n	Имя управляемого кластера. (Обязательно)
--namespace	Пространство имен Kubernetes, внутри которого развернут агент AKS. Требуется для режима кластера.
--no-echo-request	Отключите эхо обратно, предоставленный агенту AKS в выходных данных.
--no-interactive	Отключить интерактивный режим. Если задано, агент не будет запрашивать входные данные и будет выполняться в пакетном режиме.
--refresh-toolsets	Обновите состояние наборов инструментов.
--resource-group, -g	Имя группы ресурсов. (Обязательно)
--show-tool-output	Отображение выходных данных каждого вызываемого средства.
--status	Отображение сведений о конфигурации и состоянии агента AKS.

Спецификация модели

Параметр --model определяет, какой LLM и поставщик анализирует кластер. Рассмотрим пример.

• OpenAI: используйте имя модели напрямую (например, gpt-4o).
• Azure OpenAI: используйте azure/<deployment name> (например, azure/gpt-4o).
• Anthropic: Use anthropic/claude-sonnet-4.

Интерактивные команды

У az aks agent есть набор подкоманд, которые помогают устранить неполадки. Чтобы получить доступ к ним, введите / в интерактивном режиме.

В следующей таблице описываются доступные интерактивные команды:

Command	Description
/exit	Оставьте интерактивный режим.
/help	Показать справочные сообщения по всем командам.
/clear	Очистите экран и сбросьте контекст разговора.
/tools	Отображение доступных наборов инструментов и их состояния.
/auto	Переключите отображение выходных данных средства после ответов.
/last	Показать все выходные данные инструмента из последнего ответа.
/run	Запустите команду Bash и, если необходимо, поделитесь ей с LLM.
/shell	Войдите в интерактивную оболочку, а затем по желанию поделитесь сеансом с LLM.
/context	Отобразить объем контекста беседы и число токенов.
/show	Отображение выходных данных конкретного инструмента в прокручиваемом представлении.
/feedback	Предоставьте отзыв об ответе агента.

Отключение интерактивного режима

Интерактивный режим можно отключить с помощью флага --no-interactive с помощью команды. Рассмотрим пример.

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

Наборы инструментов

Агентический интерфейс командной строки для AKS включает предварительно созданные интеграции для популярных средств мониторинга и наблюдаемости с помощью наборов инструментов. Некоторые интеграции работают автоматически с Kubernetes. Для других интеграции требуются ключи API или конфигурация.

Для AKS существуют определенные наборы инструментов, которые помогают устранить неполадки. Эти наборы инструментов отображаются в результатах в начале работы с продуктом.

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

Сервер контекста модели AKS (MCP) включен по умолчанию с агентическим интерфейсом командной строки для AKS. Этот интерфейс запускает сервер AKS MCP локально (или в кластере с режимом кластера) и использует его в качестве источника для телеметрии.

Очистка развертывания агентического интерфейса командной строки

Очистите развертывание в клиентском режиме с помощью команды az aks agent-cleanup с параметром --mode client. Эта команда удаляет локальный файл конфигурации и сбрасывает конфигурацию агента.

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

Очистите развертывание в режиме кластера с помощью команды az aks agent-cleanup. Обязательно укажите --namespace параметр с пространством имен, в котором развернут агент. Эта команда удаляет модуль pod агента из указанного пространства имен и удаляет конфигурацию LLM, хранящуюся в кластере.

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

Проверка успешной очистки

Убедитесь, что локальный файл конфигурации и образы Docker были удалены с помощью следующих команд:

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

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

Убедитесь, что pod агента и связанные с ним ресурсы были удалены из кластера, используя следующие команды с соответствующим пространством имен:

# 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

Удалите CLI AGENTIC для расширения AKS

Удалите агентический интерфейс командной строки для расширения AKS с помощью az extension remove команды.

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

Связанный контент

• Общие сведения об агентическом интерфейсе командной строки для AKS см. в разделе "Сведения об агентическом интерфейсе командной строки для AKS".
• Сведения об устранении неполадок с агентическим интерфейсом командной строки для AKS см. в статье "Устранение неполадок с агентическим интерфейсом командной строки для AKS".
• Ответы на распространенные вопросы об агентическом интерфейсе командной строки для AKS см. в разделе "Часто задаваемые вопросы об агентическом интерфейсе командной строки для AKS".