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（如果还没有）

```bash
# 创建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权限：

```bash
# 方法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
```

验证权限：
```bash
az role assignment list \
  --assignee $AZURE_CLIENT_ID \
  --scope $DNS_ZONE_ID \
  --output table
```

#### 1.3 更新Kubernetes Secret

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

```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：

```bash
# 获取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
bash k8s/create-acr-secret.sh
```

### 3. 构建和推送镜像

```bash
# 构建镜像
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

```bash
# 创建命名空间
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
bash k8s/deploy.sh
```

### 5. 验证部署

```bash
# 检查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创建

```bash
# 创建测试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的写权限。

**解决方案：**
```bash
# 运行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. 确认镜像名称和标签正确

```bash
# 检查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: 如何更新部署

```bash
# 方法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: 如何查看日志

```bash
# 查看所有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
```

## 监控和维护

### 资源使用

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

# 查看Node资源使用
kubectl top nodes
```

### 扩缩容

```bash
# 手动扩容
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. **镜像安全**
   - 定期扫描镜像漏洞
   - 使用最新的基础镜像
   - 不要在镜像中包含敏感信息

## 故障排查

### 诊断命令

```bash
# 检查所有资源
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中设置环境变量调整日志级别：

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

## 参考资料

- [Kubernetes官方文档](https://kubernetes.io/docs/)
- [Azure Kubernetes Service文档](https://docs.microsoft.com/azure/aks/)
- [Azure DNS文档](https://docs.microsoft.com/azure/dns/)
- [Agent Manager API文档](../docs/API_DOCUMENTATION.md)
- [DNS问题修复报告](../docs/DNS_ISSUE_FIX_REPORT.md)

## 联系支持

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