基本框架
This commit is contained in:
137
docs/01-07-节点初始化-ansible-实践.md
Normal file
137
docs/01-07-节点初始化-ansible-实践.md
Normal file
@@ -0,0 +1,137 @@
|
||||
# 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` 中的验证命令与入口验证。
|
||||
|
||||
Reference in New Issue
Block a user