AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 容器服务 Kubernetes 版 ACK ACK托管与专有集群 实践教程 Kagent 使用kagent快速构建一个Kubernetes运维智能体

使用kagent和ACK Gateway结合ACK MCP Server快速构建一个Kubernetes运维智能体

更新时间：
产品详情
我的收藏

本文介绍如何使用kagent和ACK Gateway结合ACK MCP Server快速搭建一个Kubernetes运维智能体。

kagent介绍

kagent是一个开源的智能体编程框架，专为云原生环境设计，将AI智能体的强大功能与工具链深度融合。它使智能体能够通过自然语言交互执行复杂的多步骤任务，并将AI洞察转化为具体操作。

kagent的核心优点：

  1. 高级推理能力：不同于传统的聊天机器人，kagent利用先进的推理和迭代规划能力来自主处理复杂的多步骤问题。

  2. 灵活的工具集成：支持对接MCP工具，智能体可以利用这些工具与各种系统和服务交互，扩展其功能。

  3. 可扩展架构：由Google ADK框架构建，提供广泛的自定义选项，支持通过UI或声明式方式运行智能体。

  4. 团队协作模式：智能体可以组合成团队，由规划智能体制定计划并将任务分配给团队中的各个智能体。

  5. 通用任务处理能力：适用于各种场景的任务自动化，能够处理复杂的问题诊断、数据分析和系统操作等典型场景。

准备工作

  1. 在ACK集群中新建kagent命名空间。

  2. 使用ACK应用市场或者ACK集群应用 > Helm，在kagent命名空间中创建kagent-crds和kagent应用。

  3. 在ACK集群中通过组件管理安装Gateway API组件并且启用实验性通道功能。

  4. 在ACK集群中通过组件管理安装Gateway with Inference Extension组件。

  5. 开通阿里云百炼服务，并第一步：获取 API Key。

步骤一：部署ACK MCP Server

  1. 创建自定义权限策略。

    以下为当前ack-mcp-server所需只读权限集。

    {
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cs:Check*",
        "cs:Describe*",
        "cs:Get*",
        "cs:List*",
        "cs:Query*",
        "cs:RunClusterCheck",
        "cs:RunClusterInspect"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "arms:GetPrometheusInstance",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "log:Describe*",
        "log:Get*",
        "log:List*"
      ],
      "Resource": "*"
    }
  ]
}

  2. 安装ACK MCP Server。详细操作步骤，请参见部署运行ack-mcp-server。

    安装完成后可通过kubectl get --raw "/api/v1/namespaces/kube-system/services/ack-mcp-server/proxy/sse" --v=10命令确认是否安装成功。

  3. 在集群中声明ACK MCP Server。

    kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: RemoteMCPServer
metadata:
  name: ack-mcp-tool-server
  namespace: kagent
spec:
  description: Official ACK tool server
  protocol: SSE
  sseReadTimeout: 5m0s
  terminateOnClose: true
  timeout: 30s
  # ACK MCP Server默认安装在kube-system下，如果切换了命名空间，也请更改此处的url。
  url: http://ack-mcp-server.kube-system:8000/sse
EOF

  4. 查看RemoteMCPServer资源的状态，获取ACK MCP工具。

    kubectl describe RemoteMCPServer ack-mcp-tool-server -n kagent

    预期输出：

    ...
status:
  conditions:
  - lastTransitionTime: "2025-XX-XXT11:35:29Z"
    message: ""
    observedGeneration: 2
    reason: Reconciled
    status: "True"
    type: Accepted
  discoveredTools:
  - description: 获取所有region下所有ACK集群列表，默认返回最多10个集群
    name: list_clusters
  - description: Execute kubectl command with intelligent context management. Supports
      cluster_id for automatic context switching and creation.
    name: ack_kubectl
  - description: 查询一个ACK集群的阿里云Prometheus数据
    name: query_prometheus
  - description: 获取Prometheus指标定义和最佳实践
    name: query_prometheus_metric_guidance
  - description: "对ACK集群的Kubernetes资源进行诊断，当遇到问题难以定位时，使用该工具进行深度诊断。支持诊断的资源包括：\n1. **node**：K8s
      节点\n2. **ingress**：Ingress\n3. **memory**：节点内存\n4. **pod**：Pod\n5. **service**：Service\n6.
      **network**：网络连通性\n                        "
    name: diagnose_resource
  - description: 即可生成并查询一个ACK集群最近的健康巡检报告
    name: query_inspect_report
  - description: |-
      Query Kubernetes (k8s) audit logs.

          Function Description:
          - Supports multiple time formats (ISO 8601 and relative time).
          - Supports suffix wildcards for namespace, resource name, and user.
          - Supports multiple values for verbs and resource types.
          - Supports both full names and short names for resource types.
          - Allows specifying the cluster name to query audit logs from multiple clusters.
          - Provides detailed parameter validation and error messages.

          Usage Suggestions:
          - You can use the list_clusters() tool to view available clusters and their IDs.
          - By default, it queries the audit logs for the last 24 hours. The number of returned records is limited to 10 by default.
    name: query_audit_log
  - description: 获取当前时间，返回 ISO 8601 格式和 Unix 时间戳格式
    name: get_current_time
  - description: 查询ACK集群的控制面组件日志。先查询控制面日志配置，验证组件是否启用，然后查询对应的SLS日志。
    name: query_controlplane_logs
  observedGeneration: 2

步骤二：部署网关并配置百炼模型服务

  1. 创建网关。

    kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: Gateway
metadata:
  name: model-gateway
  namespace: kagent
spec:
  gatewayClassName: ack-gateway
  infrastructure:
    parametersRef:
      group: gateway.envoyproxy.io
      kind: EnvoyProxy
      name: custom-proxy-config
  listeners:
  - name: http-bailian
    protocol: HTTP
    port: 8080
---
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: EnvoyProxy
metadata:
  name: custom-proxy-config
  namespace: kagent
spec:
  provider:
    type: Kubernetes
    kubernetes:
      envoyService:
        type: ClusterIP
EOF

  2. 创建百炼backend。

    kubectl apply -f- <<EOF
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: Backend
metadata:
  name: bailian
  namespace: kagent
spec:
  endpoints:
    - fqdn:
        hostname: dashscope.aliyuncs.com
        port: 443
---
apiVersion: gateway.networking.k8s.io/v1alpha3
kind: BackendTLSPolicy
metadata:
  name: bailian-tls
  namespace: kagent
spec:
  targetRefs:
  - group: gateway.envoyproxy.io
    kind: Backend
    name: bailian
  validation:
    hostname: dashscope.aliyuncs.com
    wellKnownCACertificates: System
EOF

  3. 创建路由规则，将指定请求路由到百炼backend。

    kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: bailian-route
  namespace: kagent
spec:
  parentRefs:
    - name: model-gateway
  rules:
    - backendRefs:
        - group: gateway.envoyproxy.io
          kind: Backend
          name: bailian
      filters:
        - type: URLRewrite
          urlRewrite:
            hostname: dashscope.aliyuncs.com
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /compatible-mode/v1
      matches:
        - path:
            type: PathPrefix
            value: /v1
      timeouts:
        backendRequest: 10m
        request: 10m
EOF

步骤三：使用ACK Gateway管理百炼服务的API Key

访问外部大模型服务时通常需要使用API Key来完成授权。ACK Gateway支持动态为请求注入API Key，可以统一管理所有模型服务的API Key，能够有效降低维护的复杂度和集群安全水位。

  1. 创建一个Secret，用于保存百炼服务的API Key。

    export PROVIDER_API_KEY=${你的百炼APIKey}
kubectl create secret generic bailian-credential -n kagent --from-literal credential="Bearer $PROVIDER_API_KEY"

  2. 创建HTTPRouteFilter资源引用这个Secret。

    kubectl apply -f- <<EOF
apiVersion: gateway.envoyproxy.io/v1alpha1
kind: HTTPRouteFilter
metadata:
  name: credential-injection
  namespace: kagent
spec:
  credentialInjection:
    overwrite: true
    credential:
      valueRef:
        name: bailian-credential
EOF

  3. 修改HTTPRoute资源，开启API Key自动注入。

    kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: bailian-route
  namespace: kagent
spec:
  parentRefs:
    - name: model-gateway
  rules:
    - backendRefs:
        - group: gateway.envoyproxy.io
          kind: Backend
          name: bailian
      filters:
        - type: URLRewrite
          urlRewrite:
            hostname: dashscope.aliyuncs.com
            path:
              type: ReplacePrefixMatch
              replacePrefixMatch: /compatible-mode/v1
        # 主要增加了这一部分
        - type: ExtensionRef
          extensionRef:
            group: gateway.envoyproxy.io
            kind: HTTPRouteFilter
            name: credential-injection
      timeouts:
        backendRequest: 10m
        request: 10m
      matches:
        - path:
            type: PathPrefix
            value: /v1
EOF

步骤四：配置百炼的ModelConfig

  1. 获取网关地址。

    export GATEWAY_HOST=$(kubectl -n kagent get gateway/model-gateway -o jsonpath='{.status.addresses[0].value}')
echo $GATEWAY_HOST

  2. 创建如下ModelConfig。

    kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: ModelConfig
metadata:
  name: my-provider-config
  namespace: kagent
spec:
  model: qwen-plus
  openAI:
    baseUrl: http://$GATEWAY_HOST:8080/v1
  provider: OpenAI
EOF

步骤五：创建Agent

  1. 使用如下 YAML 定义agent。

    kubectl apply -f - <<EOF
apiVersion: kagent.dev/v1alpha2
kind: Agent
metadata:
  name: my-ack-ops-agent
  namespace: kagent
spec:
  declarative:
    deployment:
      env:
        - name: OPENAI_API_KEY
          value: placeholder
      replicas: 1
    modelConfig: my-provider-config
    stream: true
    systemMessage: |-
      # 角色

      你是一个专业的 ACK (Alibaba Cloud Container Service for Kubernetes) 智能助手。你的任务是准确理解用户关于集群的请求，并选择最合适的工具来执行查询、诊断或分析。

      # 核心指令 (Core Instructions)

      1.  **确认目标，首要原则**:
          *   在执行任何操作前，必须先确认用户要操作的 cluster_id。
          *   如果用户的提问中没有提供，**必须**首先调用 list_clusters 工具，并询问用户希望在哪个集群上操作。

      2.  **工具选择策略 (按优先级)**:
          *   **复杂故障诊断**: 当遇到 Pod 异常、网络不通、节点 NotReady 等复杂问题时，**优先使用 diagnose_resource**。
          *   **性能指标查询**: 当问题涉及“CPU/内存高低”、“快慢”、“用量多少”时，**优先使用 query_prometheus**。
          *   **安全与变更审计**: 当问题是关于“谁在什么时间做了什么”时，**优先使用 query_audit_log**。
          *   **集群整体健康**: 当用户想了解“集群是否健康”或要“体检报告”时，**使用 query_inspect_report**。
          *   **控制面问题**: 当怀疑是 API Server、Scheduler 等 Kubernetes 系统组件的问题时，**使用 query_controlplane_logs**。
          *   **通用查询**: 对于其他所有标准的、明确的 Kubernetes 资源查询（如 get pods, describe service, logs <pod>），**使用 ack_kubectl 作为默认工具**。

      3.  **安全红线**:
          *   你的主要职责是查询和诊断。任何通过 ack_kubectl 执行的、**可能修改集群状态**的操作（如 apply, delete，或创建诊断用的临时 Pod），你**必须**先向用户说明你将执行的命令及其目的，并在获得**用户明确授权**后才能执行。

      4.  **行为准则**:
          *   如果用户问题不清楚，先请求澄清再行动。
          *   回答友好、热情。
          *   如果使用工具后仍无法找到答案，**绝不能编造**。诚实地回答：“抱歉，通过现有工具我暂时无法定位问题”，并可以提供你已有的发现。

      # 回复格式 (Response Format)

      *   **始终使用 Markdown 格式**。
      *   回复需包含你的**操作总结**以及对结果的**分析和建议**。

      ---

      ### 总结

      *(用一句话总结你做了什么，以及核心发现。)*
    tools:
      - mcpServer:
          apiGroup: kagent.dev
          kind: RemoteMCPServer
          name: ack-mcp-tool-server
          toolNames:
            - list_clusters
            - ack_kubectl
            - query_prometheus
            - query_prometheus_metric_guidance
            - diagnose_resource
            - query_inspect_report
            - query_audit_log
            - get_current_time
            - query_controlplane_logs
        type: McpServer
  description: 这个智能体可以和ACK MCP Tools进行交互，以获取集群的信息并操作集群。
  type: Declarative
EOF

  2. 确认agent创建状态。

    kubectl get pod -n kagent

    预期输出：

    NAME                                              READY   STATUS    RESTARTS   AGE
my-ack-ops-agent-66b74675fc-rqwwx                 1/1     Running   0          2m6s
...

步骤六：通过UI使用Agent

kagent默认提供了Web UI可以直接与agent进行交互。

  1. 将kagent-ui服务通过端口转发至本地。

    kubectl port-forward -n kagent service/kagent-ui 8082:8080

  2. 在浏览器中通过localhost:8082访问agent。

    1. 问答示例：通过Prometheus查看集群中当前kagent命名空间Pod的各项指标。

      image

      image

上一篇：使用kagent调用HTTP协议的MCPServer下一篇：安全合规