147 lines
7.2 KiB
Markdown
147 lines
7.2 KiB
Markdown
# 01-06-节点初始化与 k3s 自动安装（Ansible 实践）
|
||
|
||
> 目标：给一组已经装好 OS、可以 SSH 的裸金属/虚机，**一键完成基础初始化 + 安装 k3s server/worker**，得到与 `01-01`、`01-02` 文档一致的集群（含 `/storage` 数据盘方案）。
|
||
>
|
||
> **状态：已验证**（2026-03，Fedora + K3s，4 节点 61~64）。
|
||
> 部署环境详见 `00-04-部署环境说明.md`。
|
||
|
||
## 1. 适用边界与前提
|
||
|
||
- 已完成：
|
||
- **控制机**（运行 ansible-playbook 的那台机器）已安装 Ansible：
|
||
- Fedora / RHEL：`sudo dnf install ansible`
|
||
- Debian / Ubuntu：`sudo apt install ansible`
|
||
- 验证：`ansible --version`、`ansible-playbook --version`
|
||
- 每台目标机器已经安装好 Linux（如 Fedora/CentOS/Debian 等）；
|
||
- 能通过 SSH 无密码/密钥登录（Ansible 能连通）；
|
||
- 若使用 `scripts/ssh/setup-k3s-workers-ssh.sh` 为每节点配置独立密钥，需在 inventory 中为各 host 指定 `ansible_ssh_private_key_file`（见下文示例）；
|
||
- 使用 **root** SSH 连接（`group_vars/all.yml` 中 `ansible_user: root`），配合 `scripts/ssh/setup-k3s-workers-ssh.sh` 为**所有节点**（含控制节点）配置 jack + root 的公钥；
|
||
- IP 规划、主机名已大致确定，例如：
|
||
- `ylc61`：k3s server，IP `192.168.2.61`
|
||
- `ylc62` ~ `ylc64`：k3s worker，IP `192.168.2.62` ~ `192.168.2.64`
|
||
- **数据盘**：若使用 `/storage` 方案，需在每台节点上提前挂载数据盘并创建 `/storage`；
|
||
- 不覆盖：
|
||
- 从「完全裸铁 + 无系统」开始的 PXE 装机；
|
||
- 高级 HA（多 server + 外部 datastore）——仍按 `01-04`、`03-10` 执行。
|
||
|
||
## 2. 目录结构
|
||
|
||
本仓库已有 `ansible/`：
|
||
|
||
```text
|
||
ansible/
|
||
ansible.cfg # host_key_checking=False 等
|
||
inventory.ini
|
||
group_vars/
|
||
all.yml
|
||
playbooks/
|
||
k3s-init-and-install.yml # 标准 IPv4 安装
|
||
```
|
||
|
||
## 3. 示例 inventory
|
||
|
||
`ansible/inventory.ini`：
|
||
|
||
```ini
|
||
[k3s_server]
|
||
ylc61 ansible_host=192.168.2.61 ansible_ssh_private_key_file=~/.ssh/id_ed25519_k3s_192.168.2.61
|
||
|
||
[k3s_worker]
|
||
ylc62 ansible_host=192.168.2.62 ansible_ssh_private_key_file=~/.ssh/id_ed25519_k3s_192.168.2.62
|
||
ylc63 ansible_host=192.168.2.63 ansible_ssh_private_key_file=~/.ssh/id_ed25519_k3s_192.168.2.63
|
||
ylc64 ansible_host=192.168.2.64 ansible_ssh_private_key_file=~/.ssh/id_ed25519_k3s_192.168.2.64
|
||
|
||
[k3s_nodes:children]
|
||
k3s_server
|
||
k3s_worker
|
||
```
|
||
|
||
> 提示：上面使用短主机名（如 `ylc61`～`ylc64`），应与各节点 hostname 及 `kubectl get nodes` 输出的 NAME 一致，便于配合 Cloudflare CDN；playbook 的 Init 阶段会为所有 k3s 节点写入 /etc/hosts 条目。
|
||
|
||
## 4. 全局变量
|
||
|
||
**唯一真源**：[`ansible/group_vars/all.yml`](../ansible/group_vars/all.yml)（含 `ansible_user`、`k3s_data_dir`、`k3s_server_ip`、`k3s_manage_*` 等）。
|
||
|
||
若需安装后自动打 **control-plane/worker 角色标签**（供 `02-05` 与 `03-02` 的 M1/M3 使用），在同一文件中增加，例如：
|
||
|
||
- `k3s_manage_role_labels: true`
|
||
- `k3s_control_plane_nodenames: ["ylc61"]`
|
||
- `k3s_worker_nodenames: ["ylc62", "ylc63", "ylc64"]`
|
||
|
||
节点名必须与 `kubectl get nodes` 输出一致（使用短主机名 ylc61～ylc64）。未配置时仅打 enablelb/lbpool，不打角色标签。
|
||
|
||
**CoreDNS 上游 DNS**（供 ACME 解析 Let's Encrypt，见 `03-02` 常见问题）：若宿主机 `/etc/resolv.conf` 为 IPv6，Pod 网络仅 IPv4 时无法解析，ACME 会失败。playbook 默认会将 CoreDNS `forward` 改为 IPv4：
|
||
|
||
- `k3s_manage_coredns: true`（默认开启）
|
||
- `coredns_forward_servers: "223.5.5.5 8.8.8.8"`（可按环境修改）
|
||
|
||
禁用时设 `k3s_manage_coredns: false`。
|
||
|
||
## 5. 执行流程概览
|
||
|
||
playbook 依次执行：
|
||
|
||
| 顺序 | 阶段 | 内容 |
|
||
|------|------|------|
|
||
| 1 | Init | 时区、基础包、/etc/hosts、**firewalld 开放 8472/udp（全部节点）与 6443/tcp（仅 server）** |
|
||
| 2 | Install server | 安装 k3s server（`--data-dir=/storage`） |
|
||
| 3 | Install agent | 逐台安装 worker（`serial: 1`，`async/poll` 防止卡死） |
|
||
| 4 | Firewalld 基线 | 等待 flannel.1/cni0 出现（最多 120s），加入 trusted zone |
|
||
| 5 | **CoreDNS（可选）** | 当 `k3s_manage_coredns: true` 时，将 forward 改为 IPv4（223.5.5.5 8.8.8.8），避免 ACME 解析 Let's Encrypt 失败 |
|
||
| 6 | Traefik 标签 | 从集群动态获取节点名，打 enablelb/lbpool 标签 |
|
||
| 7 | 角色标签（可选） | 当 `k3s_manage_role_labels: true` 时，为控制节点打 control-plane、工作节点打 worker |
|
||
| 8 | 验证 | 输出 `kubectl get nodes`、`kubectl get pods -n kube-system`、curl 各节点 HTTP |
|
||
|
||
**关键实现点**：
|
||
|
||
- **端口 8472/udp**：flannel VXLAN 所需，必须在 Init 阶段开放，否则 worker 上 flannel 无法建立 overlay，`flannel.1` / `cni0` 永远不会出现；
|
||
- **Firewalld 基线（flannel.1/cni0 → trusted）**：FCOS/Fedora 默认 firewalld 转发策略较严格；K3s 不会自动配置宿主机 firewalld 的 zone 接口归类。入口 Pod（Traefik/svclb-traefik）可能调度到任意节点，回包路径会经过该节点本地的 `flannel.1`/`cni0`。若某节点上 `flannel.1 ↔ cni0` 的转发被 firewalld 拦截，该节点上的入口流量就会异常，即使其它节点正常。详见 `01-02-k3s-工作节点.md`；
|
||
- **Traefik 标签**：使用 `kubectl get nodes -o jsonpath` 获取实际节点名，不依赖 inventory 主机名与 K8s 节点名一致；
|
||
- **CoreDNS（可选）**：宿主机若使用 IPv6 DNS（如运营商分配的 `240e:...`），Pod 网络仅 IPv4 时 CoreDNS 无法访问上游，导致 Traefik ACME 无法解析 Let's Encrypt 域名。playbook 会将 `forward . /etc/resolv.conf` 改为 `forward . 223.5.5.5 8.8.8.8`，详见 `03-02` 常见问题。
|
||
- **角色标签（可选）**：playbook 默认只打 enablelb/lbpool，**不打** `node-role.kubernetes.io/control-plane` 与 `node-role.kubernetes.io/worker`。若需 `03-01` / `03-03` nginx 矩阵的 M1/M3 能调度，可开启 `k3s_manage_role_labels` 并配置控制节点/工作节点名列表（见下），或安装后在控制节点按 01-02 可选步骤手动打标。
|
||
- **Agent 安装**：token 通过 `slurp` 从 server 读取，`delegate_to` 到 server 执行。
|
||
|
||
## 6. 使用方式
|
||
|
||
### 6.1 SSH 前置（若未配置）
|
||
|
||
先运行 `scripts/ssh/setup-k3s-workers-ssh.sh`，为所有 k3s 节点（含 server）配置 jack + root 公钥及 inventory 所需的私钥。
|
||
|
||
### 6.2 执行 playbook
|
||
|
||
在 `ansible/` 目录下执行：
|
||
|
||
```bash
|
||
cd ansible
|
||
# 标准 IPv4 安装
|
||
ansible-playbook -i inventory.ini playbooks/k3s-init-and-install.yml
|
||
```
|
||
|
||
执行结束后，playbook 会输出：
|
||
|
||
- `kubectl get nodes`
|
||
- `kubectl get pods -n kube-system -o wide`
|
||
- 各节点 IP 的 curl HTTP 测试结果
|
||
|
||
### 6.3 手动验证（可选）
|
||
|
||
在 server（如 ylc61）上执行：
|
||
|
||
```bash
|
||
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get nodes -o wide
|
||
KUBECONFIG=/etc/rancher/k3s/k3s.yaml kubectl get pods -n kube-system -o wide
|
||
```
|
||
|
||
确认 `/storage` 方案：
|
||
|
||
- server 与 worker 的 k3s 数据目录均为 `/storage`；
|
||
- token 路径为 `/storage/server/token`。
|
||
|
||
## 7. 下一步
|
||
|
||
集群就绪后，可继续阅读：
|
||
|
||
- `03-09-k3s-gitops-集群配置管理.md`：用 Argo CD/Flux 管理 Traefik、监控、应用清单；
|
||
- `01-01`、`01-02` 中的验证命令与入口验证。
|
||
|