# 03-09-k3s HA 集群配置与切换

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

## 前置条件

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

## 操作步骤

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

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

```bash
# 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 已成功「升级」为控制节点。

## 验证命令

```bash
kubectl get nodes -o wide
kubectl get pods -A
```

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

## 预期

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

## 失败排查

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

## 参考

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

## 下一步

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