Kubernetes 配置指南

将 Kubernetes 集群绑定到 MOI 后，智能体可以在凭证授权范围内读取 Namespace、Node、Pod、Deployment、Service 和 Event，查看集群资源状态。

配置前准备

• 一个可用的 Kubernetes 集群，以及需要读取的目标 Namespace。

• 集群管理员提供的只读凭证：ServiceAccount Token 或客户端证书，也可以使用包含这些凭证的 kubeconfig。

• API Server 地址及验证其证书所需的 CA 信息。

• MOI 工作区的工具配置权限，以及 MOI 服务端到 API Server 的网络连通性。

首次接入建议使用测试集群和受限凭证，不要直接复制生产集群的个人管理员 kubeconfig。

配置步骤

1. 准备集群连接信息

向集群管理员确认以下信息：

信息	用途
API Server	集群 API 地址，例如 https://k8s.example.com:6443，不是集群管理控制台地址。
Namespace	本次要读取资源的命名空间。
Token 或客户端证书及私钥	验证连接身份，选择一种认证方式。
API Server CA	验证服务端证书；使用私有 CA 的集群需要提供对应 CA。
凭证有效期与权限	确认凭证仍有效，并且能读取目标资源。

ServiceAccount 的身份和资源访问权限需要分别配置，详见 Kubernetes ServiceAccount 官方说明。

2. 在 MOI 中选择 Kubernetes

打开 资源中心 > 工具库，在工具市场中找到 Kubernetes，进入工具详情并创建实例。

从资源中心进入工具库，查找 Kubernetes 工具。

3. 填写集群连接

输入 工具实例名称，例如「测试集群」。连接信息可以从 kubeconfig 填充，也可以手动填写，选择一种方式即可。

MOI Kubernetes 表单可通过 kubeconfig 填充，或填写 API Server、认证与 TLS 配置。

方式一：从 kubeconfig 填充

1. 点击 从 kubeconfig 填充 选择文件；也可以在右侧文本框中粘贴 YAML 或 JSON，再点击 使用粘贴的 kubeconfig。

2. 如提示选择 context，选择目标集群对应的 context。

3. 核对填充后的 API Server、默认 Namespace、认证方式和 CA，确认没有选错集群。

填充不会自动保存实例。当前导入不支持 exec、auth-provider、tokenFile 或外部证书文件路径；遇到这些配置时，请管理员提供内嵌凭证的 kubeconfig，或改用手动填写。

方式二：手动填写

1. 填写 API Server 和 默认 Namespace。

2. 在 认证方式 中选择 ServiceAccount Bearer Token 或 客户端证书，填入对应凭证。

3. 根据集群配置填写 CA；需要指定 TLS Server Name 时，展开 高级 TLS 设置，使用管理员提供的名称。

字段	何时需要	填写说明
API Server	必填	例如 https://k8s.example.com:6443。
认证方式	必选其一	ServiceAccount Bearer Token 或客户端证书。
Bearer Token	Token 模式必填	使用管理员提供的 ServiceAccount Token 原值。
客户端证书 / 私钥	证书模式必填	客户端证书可填写 PEM 或上传文件；私钥输入框填写 Base64 的 client-key-data，PEM 私钥使用文件上传。
默认 Namespace	按需	未指定 Namespace 的 namespaced 读取使用此值；不是权限授权。
API Server CA / TLS Server Name	按需	用于验证证书及名称；由管理员提供，不随意填写。

4. 保存并测试连接

1. 核对 API Server、Namespace 和凭证有效期，保存实例。

2. 对该实例执行连接测试，查看结果。

3. 测试失败时，按错误提示检查网络、证书或权限，修改后再次测试。

默认 Namespace 只用于补充读取请求的目标，不会授予资源访问权限。连接测试成功也不代表该凭证能够读取所有资源。

5. 绑定智能体并验证

回到目标智能体详情，在工具区域检查对应能力是否已绑定；提供实例选择时，核对目标连接。具体步骤见绑定并验证工具。

在对话中指定目标集群和 Namespace，例如：

使用「测试集群」实例，列出 test 命名空间中的 Pod 名称与状态，不修改任何资源。

将 test 替换为实际 Namespace。查看工具调用记录，并与集群中的 Pod 列表核对名称和状态。确认结果来自正确集群，而不只是看到实例的「已配置」标签。

常见问题

现象	检查方法
kubeconfig 无法导入	当前导入不支持 exec、auth-provider、tokenFile 或外部证书文件路径；请管理员提供内嵌支持的凭据材料。
证书错误	核对 CA、服务地址和证书域名；不要改成跳过 TLS 校验。
403	请管理员为明确的资源读取需求配置最小 RBAC，不直接提升到管理员。
过期 / 401	更换有效 Token 或证书，保存后重新测试。

相关链接

• Kubernetes ServiceAccount 官方说明

• 返回工具配置指南目录。

最后更新于 2026 年 10 月 12 日