多 master K3s 集群中仅首个 master 节点可正常使用 kubectl，其余节点报错是因 kubeconfig 未同步、API Server 地址未指向 VIP/LB、证书未统一、kubectl 未正确配置所致。
部署多 master 的 K3s 高可用集群后，常出现只有第一个 master 节点能正常使用 kubectl，其余 master 节点执行命令报错（如 connection refused、certificate is valid for ... not ... 或直接提示找不到配置），这并非集群本身故障，而是配置和环境未同步导致的典型现象。
kubeconfig 文件未同步到其他 master 节点
K3s 默认只在首个 server 节点生成完整可用的 /etc/rancher/k3s/k3s.yaml，其他 master 节点虽然运行正常，但该文件要么不存在、要么内容不完整（比如缺失 client-certificate-data 或 server 地址错误）。
- 手动复制首个 master 的 kubeconfig 到其他 master 节点：
sudo scp /etc/rancher/k3s/k3s.yaml user@<other-master-ip>:/etc/rancher/k3s/k3s.yaml</other-master-ip> - 确保目标节点上设置正确环境变量：
export KUBECONFIG=/etc/rancher/k3s/k3s.yaml - 或复制到用户级配置目录并修正权限：
mkdir -p ~/.kube && sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config && sudo chown $USER:$USER ~/.kube/config
API Server 地址未指向高可用入口（VIP 或负载均衡器）
如果各 master 节点的 kubeconfig 中 server: 字段仍写死为本机 IP（如 https://10.0.0.40:6443），那么当该节点宕机或证书不匹配时，kubectl 就会失败。高可用部署必须统一使用 VIP 或 LB 地址。
- 编辑 kubeconfig，将
server:行改为高可用地址，例如：server: https://10.0.0.41:6443（对应 keepalived VIP）或https://k3s-lb.example.com:6443 - 若使用 TLS SAN，需在所有 master 启动时通过
--tls-san显式加入该 VIP 或域名，否则证书校验失败
节点间证书与身份未对齐
K3s 多 master 模式下，每个节点拥有独立的证书对。若未使用外部数据存储（如 PostgreSQL/MySQL），而是依赖内置 etcd，则所有 master 必须共用同一套 CA 和 server 证书，否则 API 认证会拒绝非首节点发起的请求。
- 推荐方案：部署时统一指定证书路径，例如：
--tls-cert-file /var/lib/rancher/k3s/server/tls/serving-k3s.crt --tls-key-file /var/lib/rancher/k3s/server/tls/serving-k3s.key - 更稳妥做法是启用外部数据库（PostgreSQL/MySQL），由其统一管理集群状态和证书上下文，避免节点间证书漂移
服务未启用 kubectl 命令别名或二进制缺失
部分 K3s 安装方式（尤其是离线包或自定义脚本）可能未自动创建 k3s kubectl 别名，或未将 kubectl 二进制软链到 /usr/local/bin。
- 检查是否可调用：
which kubectl或which k3s - 若只有
k3s可用，直接用：k3s kubectl get nodes - 若需全局
kubectl，建立软链接：sudo ln -sf /usr/local/bin/k3s /usr/local/bin/kubectl
