Deploy-Laboratory/docs/03-08-k3s-ha-集群配置与切换.md

03-08-k3s HA 集群配置与切换

本文只讲双控制节点 HA 的集群配置与切换步骤。

TL;DR

• 自动化验收：./scripts/verify.sh run 03-08
• 关键前置：按本文「前置条件」准备环境变量/Secret/入口 IP
• 成功判据：达到本文「预期」且 playbook 断言通过
• 排障：见本文「排障」

前置条件

• 已完成 01-08-双控制节点ha.md 安装准备
• 外部 datastore 与 6443 LB 已可用
• 已确认可执行变更窗口

操作步骤

1. 在首个 server 配置外部 datastore 参数
2. 第二个 server 使用一致参数加入
3. 将 worker 与 kubeconfig 的 API 地址切换到 LB 地址
4. 校验所有节点与核心组件健康

一个简化的两节点 server 启动示例（仅用于帮助理解参数含义）：

# server1（例如 192.168.2.61）
sudo k3s server \
  --datastore-endpoint="postgres://k3s:strong-password@192.168.2.50:5432/k3s?sslmode=disable" \
  --tls-san 192.168.2.60

# server2（例如 192.168.2.63），使用相同 datastore 与 token：
sudo k3s server \
  --server https://192.168.2.60:6443 \
  --token <SAME_TOKEN> \
  --datastore-endpoint="postgres://k3s:strong-password@192.168.2.50:5432/k3s?sslmode=disable" \
  --tls-san 192.168.2.60

实际执行时，请优先参考官方 HA 文档与本仓库步骤，将上述命令转化为持久化的 systemd 配置或安装脚本参数。

推荐：将现有 worker 升级为第二控制节点的顺序

假设你已有一个控制节点（server1，示例 192.168.2.61）和一个工作节点（示例 192.168.2.63），希望把 192.168.2.63 升级为第二控制节点，大致顺序建议如下：

1. 在首个 server 上完成外部 datastore 与 LB 切换
   • 按前文「server1 启动示例」准备好外部 datastore 参数与 --tls-san（LB 地址）。
   • 确保此时集群仍然健康，kubectl get nodes 只有一个 control-plane 节点为 Ready。
2. 排空并停止原有 worker
   • 可选：使用 kubectl drain 192.168.2.63 --ignore-daemonsets --delete-emptydir-data 将工作负载迁走；
   • 在该节点上停止 k3s-agent 服务（或执行 k3s-agent-uninstall.sh），避免 agent 与后续 server 角色冲突。
3. 在该节点以 server 角色重新加入
   • 使用与 server1 相同的 token、datastore、LB 地址，执行 k3s server 安装（命令示例参考上面的 server2 启动片段）；
   • 确保 --server 指向 LB 地址（例如 https://192.168.2.60:6443），而不是单一节点 IP。
4. 重新标记工作负载调度策略
   • 根据需要为新 server 添加/调整 node-role 或 taints，决定是否在控制节点上承载工作负载；
   • 再次查看 kubectl get nodes -o wide，确认两个 server 都为 Ready，原 worker 已成功「升级」为控制节点。

验证命令

kubectl get nodes -o wide
kubectl get pods -A

进行一次故障演练：停止任意一个 server，确认 API 仍可访问。

预期

• 两个 server 都为 Ready
• 控制平面故障切换后，集群仍可管理

失败排查

• 检查 datastore 连通性与账号权限
• 检查 LB 后端健康与 6443 转发
• 检查两个 server 参数是否一致

参考

• 01-08-双控制节点ha.md
• 01-01-k3s-控制节点含traefik.md
• 01-02-k3s-工作节点.md

下一步

• 返回 00-00-构建总览.md，按导航继续。

排障

• 先看 playbook 输出：失败时先定位是 deploy/wait/http_check 哪一步。
• 集群侧总览：kubectl get nodes -o wide、kubectl -n kube-system get pods -o wide。
• 事件与日志：kubectl -n <ns> describe ...、kubectl -n <ns> logs ... --tail=200。