agent_management/k8s/README.md

Agent Manager Kubernetes部署文档

概述

本文档说明如何在Azure Kubernetes Service (AKS)上部署Agent Manager服务。

前提条件

1. Azure资源

   • Azure订阅
   • AKS集群
   • Azure Container Registry (ACR)
   • Azure DNS Zone（用于自动配置域名）

2. 本地工具

   • kubectl (Kubernetes命令行工具)
   • az (Azure CLI)
   • Docker (用于构建镜像)

3. 权限要求

   • AKS集群的管理员权限
   • ACR的推送权限
   • DNS Zone的管理权限

部署步骤

1. 配置Azure凭据

1.1 创建Service Principal（如果还没有）

# 创建Service Principal
az ad sp create-for-rbac \
  --name "agent-manager-sp" \
  --role contributor \
  --scopes /subscriptions/{subscription-id}

# 输出示例：
# {
#   "appId": "c5ba26db-f180-425f-bac3-93708d853988",
#   "displayName": "agent-manager-sp",
#   "password": "ydt8Q~...",
#   "tenant": "263c3ff6-1be5-4141-8308-b188464fb297"
# }

1.2 配置DNS权限（重要！⚠️）

Agent Manager需要DNS Zone Contributor权限才能为创建的agent自动配置域名。

使用提供的脚本配置DNS权限：

# 方法1：使用自动化脚本（推荐）
bash scripts/setup_dns_permissions.sh

# 方法2：手动配置
AZURE_CLIENT_ID="your-service-principal-app-id"
AZURE_SUBSCRIPTION_ID="your-subscription-id"
AZURE_RESOURCE_GROUP="your-resource-group"
AZURE_DNS_ZONE="your-dns-zone.com"

DNS_ZONE_ID="/subscriptions/$AZURE_SUBSCRIPTION_ID/resourceGroups/$AZURE_RESOURCE_GROUP/providers/Microsoft.Network/dnsZones/$AZURE_DNS_ZONE"

az role assignment create \
  --assignee $AZURE_CLIENT_ID \
  --role "DNS Zone Contributor" \
  --scope $DNS_ZONE_ID

验证权限：

az role assignment list \
  --assignee $AZURE_CLIENT_ID \
  --scope $DNS_ZONE_ID \
  --output table

1.3 更新Kubernetes Secret

编辑 k8s/agent-manager-secret.yaml：

apiVersion: v1
kind: Secret
metadata:
  name: agent-manager-secret
  namespace: agent-manager
type: Opaque
stringData:
  AZURE_TENANT_ID: "263c3ff6-1be5-4141-8308-b188464fb297"
  AZURE_CLIENT_ID: "c5ba26db-f180-425f-bac3-93708d853988"
  AZURE_CLIENT_SECRET: "your-client-secret"
  AZURE_SUBSCRIPTION_ID: "45d7a360-af09-40fc-9afc-56dc475245ec"
  AZURE_RESOURCE_GROUP: "taiji-ai-v0"
  AZURE_DNS_ZONE: "taijiagnet.com"

2. 配置ACR访问

创建ACR secret：

# 获取ACR登录服务器
ACR_NAME="your-acr-name"
ACR_LOGIN_SERVER="${ACR_NAME}.azurecr.io"

# 创建Docker registry secret
kubectl create secret docker-registry acr-secret \
  --namespace agent-manager \
  --docker-server=$ACR_LOGIN_SERVER \
  --docker-username=$AZURE_CLIENT_ID \
  --docker-password=$AZURE_CLIENT_SECRET

或使用脚本：

bash k8s/create-acr-secret.sh

3. 构建和推送镜像

# 构建镜像
docker build -t $ACR_LOGIN_SERVER/agent-manager:latest .

# 登录ACR
az acr login --name $ACR_NAME

# 推送镜像
docker push $ACR_LOGIN_SERVER/agent-manager:latest

4. 部署到Kubernetes

# 创建命名空间
kubectl apply -f k8s/agent-manager-namespace.yaml

# 创建RBAC（ServiceAccount、Role、RoleBinding）
kubectl apply -f k8s/agent-manager-rbac.yaml

# 创建Secret（Azure凭据）
kubectl apply -f k8s/agent-manager-secret.yaml

# 创建ACR Secret
kubectl apply -f k8s/acr-secret.yaml

# 创建ConfigMap（可选）
kubectl apply -f k8s/agent-manager-configmap.yaml

# 创建Deployment
kubectl apply -f k8s/agent-manager-deployment.yaml

# 创建Service（LoadBalancer）
kubectl apply -f k8s/agent-manager-service.yaml

或使用一键部署脚本：

bash k8s/deploy.sh

5. 验证部署

# 检查Pod状态
kubectl get pods -n agent-manager

# 检查Service和外网IP
kubectl get svc -n agent-manager

# 查看日志
kubectl logs -n agent-manager deployment/agent-manager

# 测试健康检查
AGENT_MANAGER_IP=$(kubectl get svc agent-manager -n agent-manager -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
curl http://$AGENT_MANAGER_IP/

6. 测试Agent创建

# 创建测试agent
curl -X POST http://$AGENT_MANAGER_IP/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "test-agent",
    "template": "echo_agent",
    "framework": "API",
    "config": {
      "user_id": "test-user"
    }
  }'

# 检查返回结果应包含：
# - external_ip: 外网IP地址
# - domain: 自动配置的域名 (test-agent.taijiagnet.com)
# - domain_url: 域名访问地址
# - recommended: 推荐访问地址（域名）

# 查看agent状态
curl http://$AGENT_MANAGER_IP/agents/test-agent/status

# 测试域名访问
curl http://test-agent.taijiagnet.com/

# 清理测试agent
curl -X DELETE http://$AGENT_MANAGER_IP/agents/test-agent

目录结构

k8s/
├── README.md                          # 本文档
├── agent-manager-namespace.yaml       # Namespace定义
├── agent-manager-rbac.yaml            # RBAC配置（ServiceAccount、Role等）
├── agent-manager-secret.yaml          # Azure凭据Secret
├── agent-manager-configmap.yaml       # 配置文件ConfigMap
├── agent-manager-deployment.yaml      # Deployment定义
├── agent-manager-service.yaml         # LoadBalancer Service定义
├── acr-secret.yaml                    # ACR访问Secret
├── create-acr-secret.sh              # 创建ACR Secret脚本
└── deploy.sh                         # 一键部署脚本

常见问题

Q1: Agent创建后没有返回域名信息

症状： 创建agent时返回外网IP但没有domain字段。

原因： Service Principal缺少DNS Zone的写权限。

解决方案：

# 运行DNS权限配置脚本
bash scripts/setup_dns_permissions.sh

# 或手动分配权限（见上文"配置DNS权限"部分）

详细信息见：docs/DNS_ISSUE_FIX_REPORT.md

Q2: Pod启动失败，提示ImagePullBackOff

原因： 无法从ACR拉取镜像。

解决方案：

1. 检查ACR secret是否正确创建
2. 验证Service Principal有ACR的pull权限
3. 确认镜像名称和标签正确

# 检查ACR secret
kubectl get secret acr-secret -n agent-manager

# 重新创建ACR secret
bash k8s/create-acr-secret.sh

Q3: LoadBalancer IP一直处于Pending状态

原因： AKS集群配置或云提供商问题。

解决方案：

1. 检查AKS集群是否支持LoadBalancer
2. 查看Service事件：kubectl describe svc agent-manager -n agent-manager
3. 确认Azure订阅有足够的配额

Q4: 如何更新部署

# 方法1：修改YAML文件后重新应用
kubectl apply -f k8s/agent-manager-deployment.yaml

# 方法2：更新镜像
kubectl set image deployment/agent-manager \
  agent-manager=your-acr.azurecr.io/agent-manager:new-tag \
  -n agent-manager

# 方法3：编辑Deployment
kubectl edit deployment agent-manager -n agent-manager

# 查看滚动更新状态
kubectl rollout status deployment/agent-manager -n agent-manager

Q5: 如何查看日志

# 查看所有Pod日志
kubectl logs -n agent-manager -l app=agent-manager

# 查看特定Pod日志
kubectl logs -n agent-manager <pod-name>

# 实时跟踪日志
kubectl logs -n agent-manager -l app=agent-manager -f

# 查看前一个容器的日志（如果Pod重启过）
kubectl logs -n agent-manager <pod-name> --previous

监控和维护

资源使用

# 查看Pod资源使用
kubectl top pods -n agent-manager

# 查看Node资源使用
kubectl top nodes

扩缩容

# 手动扩容
kubectl scale deployment agent-manager \
  --replicas=3 \
  -n agent-manager

# 自动扩缩容（HPA）
kubectl autoscale deployment agent-manager \
  --cpu-percent=80 \
  --min=2 \
  --max=10 \
  -n agent-manager

健康检查

Agent Manager提供以下健康检查端点：

• GET / - 基本健康检查
• GET /templates - 模板列表（验证数据库连接）
• GET /agents - Agent列表（验证K8s连接）

安全最佳实践

1. Secret管理

   • 不要将Secret提交到版本控制
   • 使用Azure Key Vault或Kubernetes Secrets加密
   • 定期轮换凭据

2. RBAC

   • 使用最小权限原则
   • 为不同环境使用不同的Service Principal
   • 定期审计权限分配

3. 网络安全

   • 考虑使用Private LoadBalancer
   • 配置Network Policy限制Pod间通信
   • 使用Ingress Controller配置TLS

4. 镜像安全

   • 定期扫描镜像漏洞
   • 使用最新的基础镜像
   • 不要在镜像中包含敏感信息

故障排查

诊断命令

# 检查所有资源
kubectl get all -n agent-manager

# 查看Pod详情
kubectl describe pod <pod-name> -n agent-manager

# 查看事件
kubectl get events -n agent-manager --sort-by='.lastTimestamp'

# 检查ServiceAccount
kubectl get sa -n agent-manager
kubectl describe sa agent-manager-sa -n agent-manager

# 检查RoleBinding
kubectl get rolebinding -n agent-manager
kubectl describe rolebinding agent-manager-role-binding -n agent-manager

# 进入Pod调试
kubectl exec -it <pod-name> -n agent-manager -- /bin/bash

日志级别

在Deployment中设置环境变量调整日志级别：

env:
- name: LOG_LEVEL
  value: "DEBUG"  # DEBUG, INFO, WARNING, ERROR

参考资料

• Kubernetes官方文档
• Azure Kubernetes Service文档
• Azure DNS文档
• Agent Manager API文档
• DNS问题修复报告

联系支持

如有问题，请：

1. 查看本文档的常见问题部分
2. 查看docs/DNS_ISSUE_FIX_REPORT.md
3. 查看agent-manager日志
4. 联系开发团队