Files

jack be97836e0d chore: 清理调试脚本并收敛到 Ansible 流程

移除已废弃的调试/验证脚本与空目录，统一文档与脚本说明到 ansible-playbook 的部署方式，避免失效引用和误用路径。

Made-with: Cursor

2026-03-23 19:18:55 +08:00

7.2 KiB

Raw Blame History

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/：

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：

[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_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/ 目录下执行：

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）上执行：

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 中的验证命令与入口验证。

7.2 KiB Raw Blame History Unescape Escape