az-aks-agent

Azure AKS Agent CLI 技能

概述

Azure Kubernetes Service (AKS) 的 Agentic CLI 是一款由 AI 驱动的故障排查与洞察工具（目前处于预览阶段），可将高级诊断功能直接带到你的终端。你可以用自然语言询问集群的运行状况、配置和问题，无需深入了解 Kubernetes 或掌握复杂的命令语法。

主要命令：az aks agent

快速参考

安装

# Prerequisites: Azure CLI version 2.76 or higher
az version

# Install the extension (takes 5-10 minutes)
az extension add --name aks-agent --debug

# Verify installation
az extension list
az aks agent --help

# Initialize LLM configuration (interactive wizard)
az aks agent-init

# Remove extension if needed
az extension remove --name aks-agent --debug

基本用法

# Get cluster credentials first
az aks get-credentials --resource-group <rg-name> --name <cluster-name>

# Start interactive troubleshooting
az aks agent -g <resource-group> -n <cluster-name>

# Ask a specific question
az aks agent -g <resource-group> -n <cluster-name> --query "What's wrong with my cluster?"

# Non-interactive mode (batch processing)
az aks agent -g <resource-group> -n <cluster-name> --no-interactive --query "Check pod health"

工作流决策树

What do you need to do?
├── Cluster Health Check?
│   └── Use: az aks agent --query "What's the health status of my cluster?"
├── Troubleshoot Pod Issues?
│   └── Use: az aks agent --query "Why are my pods failing?"
├── Networking Problems?
│   └── Use: az aks agent --query "Diagnose networking issues"
├── Storage Issues?
│   └── Use: az aks agent --query "Check storage configuration"
├── Security/RBAC Issues?
│   └── Use: az aks agent --query "Review RBAC configuration"
├── Node Pool Problems?
│   └── Use: az aks agent --query "Check node pool health"
└── Configuration Review?
    └── Use: az aks agent --query "Review cluster configuration"

命令参考

核心命令

命令	说明
az aks agent	启动由 AI 驱动的交互式故障排查
az aks agent-init	初始化大模型提供商配置
az aks agent --help	显示帮助信息和可用选项

命令参数

参数	说明	默认值
-g, --resource-group	资源组名称	必填
-n, --name	AKS 集群名称	必填
--api-key	大模型 API 密钥	从环境变量或配置中获取
--config-file	配置文件路径	~/.azure/aksAgent.config
--max-steps	最大调查步数	10
--model	大模型规格	从配置中获取
--no-interactive	以批处理模式运行	false
--show-tool-output	显示工具调用输出	false
--refresh-toolsets	刷新工具集状态	false

大模型规格

# Azure OpenAI
--model "azure/gpt-4o"
--model "azure/gpt-4o-mini"

# OpenAI
--model "gpt-4o"
--model "gpt-4o-mini"

# Anthropic
--model "anthropic/claude-sonnet-4"
--model "anthropic/claude-3-5-sonnet"

# Gemini
--model "gemini/gemini-pro"

配置

环境变量

# Azure OpenAI API Key
export AZURE_API_KEY="your-azure-openai-key"

# OpenAI API Key
export OPENAI_API_KEY="your-openai-key"

# Anthropic API Key
export ANTHROPIC_API_KEY="your-anthropic-key"

配置文件结构（~/.azure/aksAgent.config）

# Azure OpenAI Configuration
llm_provider: azure
azure_api_base: https://<your-endpoint>.openai.azure.com/
azure_api_version: 2025-04-01-preview
model: gpt-4o

# OR OpenAI Configuration
llm_provider: openai
model: gpt-4o

# OR Anthropic Configuration
llm_provider: anthropic
model: claude-sonnet-4

Azure OpenAI 要求

• 部署名称：必须与模型名称一致
• 最低 TPM：1,000,000+（每分钟令牌数）
• 最小上下文大小：128,000+ 个令牌
• API 基础 URL 格式：https://{endpoint}.openai.azure.com/（不是 AI Foundry URI）

常见用例

集群运行状况分析

# General health check
az aks agent -g myRG -n myCluster --query "What's the overall health of my cluster?"

# Node status
az aks agent -g myRG -n myCluster --query "Are all nodes healthy and ready?"

# Resource utilization
az aks agent -g myRG -n myCluster --query "Show me resource utilization across nodes"

Pod 故障排查

# Failed pods analysis
az aks agent -g myRG -n myCluster --query "Why are pods in CrashLoopBackOff?"

# Pending pods
az aks agent -g myRG -n myCluster --query "Why are some pods stuck in Pending state?"

# OOMKilled pods
az aks agent -g myRG -n myCluster --query "Investigate OOMKilled containers"

网络问题

# Network policy review
az aks agent -g myRG -n myCluster --query "Are there network policies blocking traffic?"

# DNS troubleshooting
az aks agent -g myRG -n myCluster --query "Diagnose DNS resolution issues"

# Service connectivity
az aks agent -g myRG -n myCluster --query "Why can't pods reach external services?"

存储故障排查

# PVC issues
az aks agent -g myRG -n myCluster --query "Why are PersistentVolumeClaims pending?"

# Storage class review
az aks agent -g myRG -n myCluster --query "Review storage class configuration"

安全分析

# RBAC review
az aks agent -g myRG -n myCluster --query "Are RBAC permissions configured correctly?"

# Security best practices
az aks agent -g myRG -n myCluster --query "What security improvements do you recommend?"

AKS 事件参考

查看集群事件

# Get cluster credentials first
az aks get-credentials --resource-group $RESOURCE_GROUP --name $AKS_CLUSTER

# List all events
kubectl get events

# Filter by namespace
kubectl get events --namespace default

# Watch auto-repair events
kubectl get events --field-selector=source=aks-auto-repair --watch

# Detailed pod events
kubectl describe pod $POD_NAME

事件类型

类型	说明
Normal	常规操作和预期活动
Warning	需要关注的潜在问题

常见事件原因

原因	说明
FailedScheduling	Pod 无法调度到节点上
CrashLoopBackOff	容器处于反复重启状态
Scheduled	Pod 已成功分配到节点
Pulled	已成功拉取容器镜像
Created	容器已创建
Started	容器已启动
OOMKilled	容器因内存不足而被终止

事件字段

字段	说明
type	Warning 或 Normal
reason	简短的原因代码
message	易于阅读的描述
namespace	Kubernetes 命名空间
firstSeen	首次观察到的时间戳
lastSeen	最近一次观察到的时间
object	关联的 Kubernetes 对象

最佳实践

有效的查询策略

1. 先从宽泛的问题入手，再逐步缩小范围

   # Start with general health
   "What's wrong with my cluster?"
   # Then focus on specific issues
   "Why are pods in namespace X failing?"
   

2. 提供症状相关的上下文

   "Pods are restarting frequently in the production namespace"
   "Services are experiencing intermittent timeouts"
   

3. 询问具体的建议

   "What changes do you recommend to improve cluster performance?"
   "How can I fix the networking issues you identified?"
   

4. 请求历史分析

   "What patterns do you see in recent pod failures?"
   "Have there been any unusual events in the last 24 hours?"
   

安全注意事项

• 确保已配置适当的 RBAC 权限
• 使用 Azure AD 集成进行身份验证
• 遵循最小权限原则
• 通过 Azure 活动日志审计命令用法
• 自动化时使用服务帐户令牌

集成技巧

1. 与传统监控结合使用：配合 Azure Monitor 和 Container Insights 使用
2. 主动监控：定期运行运行状况检查
3. 记录调查结果：保存重要的诊断输出
4. 启用 Container Insights：获取超过 1 小时保留期的事件

Agent 故障排查

安装问题

# Verify Azure CLI version
az version

# Upgrade Azure CLI if needed
az upgrade

# Force reinstall extension
az extension remove --name aks-agent
az extension add --name aks-agent --debug

身份验证问题

# Verify Azure login
az account show

# Re-authenticate
az login

# Check subscription
az account set --subscription <subscription-id>

LLM 连接问题

# Reinitialize LLM configuration
az aks agent-init

# Check API key environment variable
echo $AZURE_API_KEY

# Test with explicit API key
az aks agent -g myRG -n myCluster --api-key "your-key"

速率限制

• 症状：响应缓慢或出现错误
• 解决方案：提高 Azure OpenAI 部署中的 TPM 配额
• 最低建议值：1,000,000 TPM

重要说明

1. 预览功能：目前处于预览阶段，保修范围有限
2. 不适用于生产关键场景：不建议用于生产环境中的关键决策
3. 事件保留：Kubernetes 事件默认仅保留 1 小时
4. 上下文窗口：为获得最佳性能，需要 128,000+ token 的上下文
5. 身份验证：使用前务必先通过 az login 进行身份验证

资源

参考资料

核心参考资料

• references/cli-commands.md - 完整的 CLI 命令参考
• references/troubleshooting.md - 扩展版故障排除指南
• references/examples.md - 实用用法示例

诊断与监控

• references/diagnostics.md - AKS 诊断和解决问题指南
• references/monitoring.md - 全面的 AKS 监控指南
• references/control-plane-metrics.md - 控制平面指标（API Server、etcd）

故障排除指南

• references/kubelet-logs.md - Kubelet 日志访问与分析
• references/memory-saturation.md - 内存饱和的识别与解决
• references/node-auto-repair.md - 节点自动修复流程与监控
• references/api-server-etcd.md - API server 和 etcd 故障排除

外部文档

• AKS Agent 概述
• AKS Agent 安装
• AKS 事件
• AKS 诊断
• 监控 AKS
• 控制平面指标
• Kubelet 日志
• 内存饱和
• 节点自动修复
• API Server/etcd 故障排除
• AKS 监控参考
• AKS Agent 故障排除
• AKS Agent 常见问题
• GitHub 存储库
• 示例配置

---

注意事项

• Agent 使用 Azure-CLI 会话令牌 — 会话过期后，对 API 的请求会静默失败，但表现为“Agent 无响应”。
• Agent 只能看到 Kubernetes API 事件，看不到自定义控制器事件 — 自定义资源问题对它不可见。
• Top events 会按原因和消息汇总事件 — 细微不同的消息会被分到不同类别；频次统计可能产生误导。
• 集群 MSI 与 Workload Identity：Agent 使用集群 MSI；若要排查采用 Workload Identity 的 Pod 的身份验证问题，必须在该 Pod 的上下文中重新进行身份验证。
• 预览功能：AKS 托管 Prometheus 与 AKS Agent 的集成在部分区域已正式发布，在其他区域仍处于预览阶段。相同的 CLI 版本在不同区域可能表现不同。