Rancher 生成 kubeconfig 使用 FQDN 时出现报错问题

通过 Rancher 创建的 RKE、RKE2、K3s 集群均支持开启 Authorized Cluster Endpoint（ACE）。开启 ACE 后，Rancher 生成的 kubeconfig 可以将上下文切换为 FQDN，从而直接访问下游 RKE、RKE2 或 K3s 集群，无需通过 Rancher 进行代理转发。

开启 ACE 后，下游集群会在 cattle-system 命名空间中运行 kube-api-auth 服务。当 kubeconfig 上下文切换为 FQDN 时，集群 API Server 会通过 kube-api-auth 作为 Webhook 进行身份验证。

---

问题现象

当用户通过 Rancher 生成 kubeconfig 时，Rancher 会先在 local 集群中创建 Token，随后在下游集群中创建对应的 ClusterAuthToken。

只有以下两个资源同时存在且未过期时，才能通过 ACE 正常访问下游集群：

• local 集群中的 Token
• 下游集群中的 ClusterAuthToken

但在旧版本 Rancher 中，可能会出现 local 集群已经创建 Token，但下游集群未创建对应 ClusterAuthToken 的情况。

此时，如果使用 FQDN 访问下游集群，认证会失败：

E0504 09:33:45.563277 19290 memcache.go:265] "Unhandled Error" err="couldn't get current server API group list: the server has asked for the client to provide credentials"
error: You must be logged in to the server (the server has asked for the client to provide credentials)

并且 kube-api-auth 会出现如下报错：

time="2026-05-04T01:50:37Z" level=error msg="clusterauthtokens.cluster.cattle.io \"cattle-system/kubeconfig-u-xxx\" not found"

---

修复版本

该问题将在以下 Rancher 版本中修复：

• v2.14.0
• v2.13.4

如果暂时无法升级 Rancher，可以通过以下 Workaround 手动触发 Token 同步。

---

Workaround

在 local 集群中，给对应 Token 补充必要的 annotation 和 label，触发 Controller 重新同步。

TOKEN_NAME="kubeconfig-u-xxx"   # local 集群中的 Token 名称
CLUSTER_ID="c-m-yyy"        # 该 Token 需要同步到的下游集群 ID

# 以下命令均在 local 集群中执行

# 添加 lifecycle annotation
kubectl annotate token "$TOKEN_NAME" -n cattle-system \
  "lifecycle.cattle.io/create.cat-token-controller_${CLUSTER_ID}=true" \
  --overwrite

# 添加 kind label
kubectl label token "$TOKEN_NAME" -n cattle-system \
  "authn.management.cattle.io/kind=kubeconfig" \
  --overwrite

# 触发 Controller 重新同步
kubectl annotate token "$TOKEN_NAME" -n cattle-system \
  force-sync="$(date +%s)" \
  --overwrite

执行完成后，等待几分钟，下游集群中应会生成对应的 ClusterAuthToken。

如果存在较多 Token 需要手动同步，也可以通过重启 Rancher Pod 的方式触发同步。

---

验证方式

在下游集群中检查是否已生成对应的 ClusterAuthToken：

kubectl -n cattle-system get clusterauthtoken

如果对应的 ClusterAuthToken 已生成，再次使用 FQDN 上下文访问下游集群即可恢复正常。