Deploy-Laboratory/docs/01-08-双控制节点ha.md

01-08-双控制节点HA（安装与准备）

TL;DR

• 自动化验收（基线）：./scripts/verify.sh run 01-08（只做集群可达性基线；HA 加入/切换需按本文手工演练）
• 你需要准备：第二个 server、外部 datastore、6443 LB（HAProxy 等）、维护窗口与备份
• 成功判据：能按本文完成外部 datastore 与 LB 的准备清单；并在 03-08 中完成加入/切换演练
• 失败排障：见本文「排障」小节（datastore/LB/tls-san/6443）

本文只讲双控制节点 HA 的安装前准备与基础环境搭建。 具体集群参数切换、server 加入与迁移步骤见 03-08-k3s-ha-集群配置与切换.md。

前置条件

• 已完成 01-01-k3s-控制节点含traefik.md
• 已完成 01-02-k3s-工作节点.md
• 当前集群运行稳定，可执行维护窗口

目标与边界

• 目标：控制平面单点故障时仍可管理集群
• 边界：家庭网关（如 OpenWrt）可能仍是整体单点

安装准备清单

1. 新增第二个 server 节点（示例 192.168.2.63）
2. 准备外部数据存储（MySQL/PostgreSQL/etcd）
3. 准备 6443 负载均衡（HAProxy）
4. 备份现有 token 与关键配置

外部 datastore 与 k3s server 最小示例

以下只给出一个“最小可参考”的 PostgreSQL + k3s server 参数示意，具体地址/账号请按你自己的环境调整：

• 若采用 01-01 的数据盘方案：在 server 参数中增加 --data-dir=/storage，与首节点一致（第二个 server 安装时同样需要）。

# 假设外部 PostgreSQL 已创建数据库与账号：
#   host=192.168.2.50 dbname=k3s user=k3s password=strong-password

# 在首个 server（例如 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.61 \
  --tls-san 192.168.2.62 \
  --tls-san 192.168.2.63 \
  --tls-san 192.168.2.60   # 这里示例为 LB IP

# 若使用数据盘方案，增加 --data-dir=/storage，例如：
# sudo k3s server --data-dir=/storage \
#   --datastore-endpoint="postgres://..." --tls-san ...

说明：上面的命令仅作为参数示意，实际部署时建议改用 systemd unit 或官方安装脚本的额外参数（INSTALL_K3S_EXEC=...），并结合 03-08-k3s-ha-集群配置与切换.md 中的步骤执行。

从现有 worker 升级为第二控制节点（推荐路径）

在家庭实验室环境中，第二个控制节点通常可以直接复用一台已有的 worker 节点。整体思路是：

1. 确认 worker 节点健康：
   • 已按 01-02-k3s-工作节点.md 正常加入集群；
   • 无关键 Pod 仅运行在该节点（可先用 kubectl drain 或手动迁移工作负载）。
2. 在 01-08 阶段完成外部 datastore 与 LB 准备：
   • 不要立即改动现有 server/worker 的 systemd 配置，只确保 datastore/LB 均已就绪。
3. 在 03-09 中按步骤将该 worker 替换为 server：
   • 停止该节点上的 k3s-agent 服务（或执行官方卸载脚本）；
   • 使用与首个 server 相同的 token/datastore/LB 地址重新以 server 角色安装 k3s；
   • 最终形成“2 个 server + 若干 worker”的目标拓扑。

具体切换命令与顺序详见：03-08-k3s-ha-集群配置与切换.md 中的操作步骤。

基础验证

kubectl get nodes -o wide
kubectl get pods -A

风险提示

• 这是高级改造，建议在业务稳定后执行
• 执行前务必做完整备份

下一步

排障

• LB 6443 不通：先在客户端 curl -k https://<lb_ip>:6443/ping；再在各 server 检查监听与防火墙放行。

• 加入第二个 server 后 kubeconfig 指向错误地址：确认 --tls-san 包含 LB IP/域名与各 server IP，并更新 kubeconfig server 地址。

• 外部 datastore 连接失败：检查连接串、网络 ACL、防火墙、账号权限；在 server 上用 psql/mysql 先手工连通再跑 k3s 参数。

• 03-08-k3s-ha-集群配置与切换.md