接入Kubernetes集群
本文介绍如何将一个已有的Kubernetes或K3s集群接入矩尺平台，并验证Gateway、Route、Service、Pod、Node、ConfigMaps、Secrets和Event等页面能够读取集群数据。
前提条件
- 已激活包含“云原生流量引擎”功能的许可证；如未激活，参见许可证授权与激活说明；
- 矩尺管理节点能够访问Kubernetes API Server；
- 已获取目标集群的kubeconfig；
- kubeconfig中包含客户端证书
client-certificate-data和客户端私钥client-key-data，或已准备可用的ServiceAccount Token。
第一步：确认API Server地址
查看kubeconfig中的clusters[].cluster.server。如果该地址是127.0.0.1或localhost，它只适用于集群节点本机。接入矩尺平台时，应使用矩尺管理节点能够访问到的API Server IP地址和端口。
K3s的API Server端口默认通常为6443。接入前应先确认网络路由和防火墙允许管理节点访问该端口。
第二步：创建Kubernetes证书凭证
- 进入【平台系统-用户凭证】，点击“新增”；
- 填写凭证名称；
- 认证类型选择“Kubernetes 证书认证”；
- “Kubernetes证书”填写kubeconfig中
users[].user.client-certificate-data的Base64原文； - “Kubernetes私钥”填写kubeconfig中
users[].user.client-key-data的Base64原文； - 点击“确定”。
不要粘贴PEM内容
不要先对kubeconfig字段执行Base64解码。输入框中不应出现-----BEGIN...-----或-----END...-----。平台需要的是kubeconfig字段本身的Base64字符串。
CA字段不用于客户端证书
certificate-authority-data是集群CA数据，不是客户端证书。不要将它填入“Kubernetes证书”字段。
第三步：新增Kubernetes环境
- 进入【Kubernetes-环境配置】，点击“新增”；
- 填写环境名称；
- “Master IP”填写矩尺管理节点可访问的API Server地址；
- “Master端口”填写API Server端口；
- “用户凭证”选择上一步创建的凭证；
- 点击“确定”。
第四步：设为当前环境
在环境列表中找到新建环境，点击“设为当前环境”。顶部的当前环境状态显示为绿色，且环境列表能显示Kubernetes版本时，说明接入成功。
第五步：检查资源页面
依次进入以下页面确认数据能够正常加载：
| 页面 | 预期内容 |
|---|---|
| Gateway虚拟服务 | Gateway名称、命名空间、GatewayClass、外部接入地址和监听器 |
| Route分发规则 | Route名称、类型、服务器池及绑定Gateway |
| Service服务器池 | Service名称、端口映射、类型和创建时间 |
| Pod节点 | Pod状态、IP、Node、镜像和关联Service |
| Node节点 | Node状态、内部IP和Pod数量 |
| ConfigMaps、Secrets | 配置对象的名称、命名空间、类型和数据键 |
| Event事件 | 对象、事件类型、原因、信息、次数和最近发生时间 |
如果Event事件中出现BackOff、Unhealthy等Warning事件，说明平台已经能够读取集群事件，但集群内对应工作负载可能存在运行问题，需要结合Pod状态和事件信息继续排查。
下一步：创建Gateway实例
集群接入成功后，需要先准备控制器和业务后端镜像，再通过kubectl apply创建Gateway、Service和Route。完整顺序、YAML示例和验证方法参见创建Kubernetes Gateway。
常见错误
用户凭证错误
优先检查证书和私钥是否误填为解码后的PEM内容。正确值通常是以LS0t...开头的Base64字符串，且输入框中没有字面量BEGIN或END。
当前用户凭证正在被引用，不可更改
新建一个正确的凭证，然后修改Kubernetes环境并切换其用户凭证。确认环境验证成功后，再清理不再使用的旧凭证。
环境连接失败
从矩尺管理节点检查API Server IP和端口是否可达，并确认配置的地址不是127.0.0.1或localhost。如集群启用了额外的访问控制，还需确认客户端证书或Token具有读取相关资源的权限。
完整字段说明和环境维护操作参见用户手册中的用户凭证和Kubernetes环境配置。