# 01-07-节点初始化与 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-05`、`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，不打角色标签。

## 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 | Traefik 标签 | 从集群动态获取节点名，打 enablelb/lbpool 标签 |
| 6 | 角色标签（可选） | 当 `k3s_manage_role_labels: true` 时，为控制节点打 control-plane、工作节点打 worker |
| 7 | 验证 | 输出 `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 节点名一致；
- **角色标签（可选）**：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` 中的验证命令与入口验证。