# Kubernetes 配置指南

## 你可以用它做什么

让智能体查看集群资源。需要集群管理员协助准备受限凭证，初次接入不要使用 cluster-admin。

## 配置前准备

向集群管理员索取 API Server、目标 Namespace、最小只读权限的 ServiceAccount Token 或客户端证书，以及必要的 CA。明确凭证有效期，并确认 MOI 服务所在网络可访问集群。不要从生产集群直接复制个人管理员 kubeconfig。

需要能够在当前 MOI 工作区创建或编辑工具配置。若没有入口或提示无权操作，请联系工作区管理员，不要借用他人的账号。

## 配置页面


```{figure} /assets/images/agents/guide-5-hd/16-kubernetes-config.png
:alt: Kubernetes 可通过 kubeconfig 导入，或填写 API Server、认证与 TLS 配置。
:class: agent-guide-image
:figclass: agent-guide-shot

Kubernetes 可通过 kubeconfig 导入，或填写 API Server、认证与 TLS 配置。
```

## 在 MOI 中操作

1. 进入工具市场的 Kubernetes，创建实例。
2. 选择「从 kubeconfig 填充」并上传/粘贴文件，选择目标 context；也可以手工填写表单。导入只是填充，仍需保存。
3. 确认 API Server 与目标集群一致，再选择 Token 或客户端证书认证；若同时存在两种材料，明确选一种。
4. 填写默认 Namespace；私有 CA 环境填写 API Server CA，需要名称覆盖时由管理员提供 TLS Server Name。
5. 核对凭证到期提示，保存并测试连接，再为智能体选择该实例。

## 字段怎么填写

| 字段 | 何时需要 | 填写说明 |
| --- | --- | --- |
| 实例名称 / 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 | 按需 | 用于验证证书及名称；由管理员提供，不随意填写。 |

## 让智能体实际使用

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

让智能体「只列出测试 Namespace 中的 Pod 名称与状态，不修改任何资源」。核对结果属于正确集群和 Namespace。连接成功不代表拥有每一种资源的读取权限。

验收时逐项确认：

- [ ] 保存成功，重新打开后配置仍存在。
- [ ] 测试连接返回成功，而不是只有「已配置」标签。
- [ ] 对话的工具调用记录显示实际调用，结果与目标平台一致。

## 常见问题

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

## 凭证维护与安全

只在 MOI 的敏感字段中输入 Key、Token、密码或私钥，不要放进提示词、截图、Issue 或 Git 仓库。配置更换前先确认有哪些智能体使用该实例；更换后重新测试，再验证一次实际任务。若凭证泄露，应到提供方撤销并生成新凭证。删除或停用配置会影响依赖它的调用，请先确认影响范围。

## 资料与核对范围

- [Kubernetes ServiceAccount 官方说明](https://kubernetes.io/docs/concepts/security/service-accounts/)。外部控制台菜单可能随版本变化；以提供方页面为准。
- 接入范围与资料依据见[指南说明](index.md#tool-configuration-sources)。
- [返回工具配置指南目录](index.md)。