主题
Harvester v1.8 实战手册：12 节点 ISO 部署 + VM 直通外网 + 模板化交付
一本可以直接照着做的书。目标：把 12 台裸金属服务器用 Harvester v1.8.2 的 ISO 无人值守方式装成高可用 HCI 集群；管理网走
10.181.0.0/24，Kubernetes 保持默认的 Pod/Service 网段；再额外打通一条 VM 直通外网10.181.91.0/24（VLAN 91）；最后用 VM 模板 + 脚本，实现「几分钟交付一批规格统一的虚拟机」。
一、这本书写给谁
| 读者 | 你能拿到什么 |
|---|---|
| 平台/虚拟化工程师 | 从交换机配置、ISO 装机参数，到 VLAN 网络、双网卡 VM 的完整落地路径 |
| 运维/SRE | 巡检项、备份恢复、节点维护、升级、故障排查手册，命令可直接复制 |
| 交付/实施顾问 | 12 节点无人值守装机脚本与配置模板，改 IP 即可复用到别的项目 |
| 想学 Harvester 的人 | 概念 → 对象模型 → 动手实验，每章都讲「为什么」和「怎么验证」 |
阅读前提：会用 Linux 命令行，了解 VLAN / bond / 网关等基础网络概念，知道 Kubernetes 的 Pod / Node / PVC 大概是什么。不要求精通 KubeVirt。
二、本书贯穿始终的环境基线
全书所有示例都基于下面这三张表。换项目时只需要改这三张表，然后重跑附录里的生成脚本。
2.1 集群基本参数
| 项目 | 取值 | 说明 |
|---|---|---|
| Harvester 版本 | v1.8.2 | v1.8 起新装机器只支持 UEFI，Legacy BIOS 不再支持安装 |
| 安装方式 | ISO 无人值守（远程 config.yaml） | 第 3 章同时覆盖 PXE/iPXE 变体 |
| 节点数量 | 12 | 前 3 台自动成为 management（etcd / control-plane），后 9 台为 worker |
| 主机名 | harvester-01 … harvester-12 | 装机时在 config 里写死，避免 DHCP 随机名 |
| 系统盘 | /dev/sda（install.device） | 按实际盘符调整 |
| 数据盘 | /dev/sdb（install.data_disk） | Longhorn 存储用，建议 NVMe/SSD |
| 存储副本 | Longhorn 默认 3 副本 | 12 节点足够分散 |
2.2 网络参数（核心）
| 网络 | 网段 / ID | 用途 |
|---|---|---|
管理网 mgmt | 10.181.0.0/24，网关 10.181.0.1 | 节点管理、K8s API、UI、Longhorn 默认流量、VM overlay 网络承载 |
| 集群 VIP | 10.181.0.100（vip_mode: static） | UI 入口 https://10.181.0.100，kubectl 的 API 地址 |
| 节点管理 IP | 10.181.0.11 … 10.181.0.22 | 对应 harvester-01 … harvester-12 |
| Pod CIDR | 10.52.0.0/16（默认，不改） | VM 管理网（eth0）地址来自这里 |
| Service CIDR | 10.53.0.0/16（默认，不改） | ClusterIP |
| Cluster DNS | 10.53.0.10（默认，不改） | 集群内 DNS |
| 必须避开的保留网段 | 10.42.0.0/16、10.43.0.0/16、10.52.0.0/16、10.53.0.0/16 | 规划任何 VLAN 网段前先对照 |
| VM 直通网 | 10.181.91.0/24，网关 10.181.91.1，VLAN 91 | VM 第二块网卡，直接与外部通信 |
| ClusterNetwork | cn-vm | 承载 VM underlay 流量的自定义集群网络 |
| VlanConfig | vlan-cfg-vm | 定义哪些节点、用哪些物理网卡、以什么 bond 方式接入 cn-vm |
| VM Network（NAD） | default/net-91 | VM 在 UI 里可选的网络，VLAN ID = 91 |
| 宿主机 VLAN91 地址 | 10.181.91.11 … .22（可选，HostNetworkConfig） | 宿主机自身也进 VM 网段，便于排障/存储/DHCP |
| VM 静态 IP 段 | 10.181.91.101 … .200 | 业务 VM 手工规划区 |
| LB IP 池 | 10.181.91.50 … .99 | Harvester 负载均衡对外 VIP |
| DHCP 池（可选） | 10.181.91.201 … .250 | 外部 DHCP 或 Harvester Managed DHCP 使用 |
| DNS | 10.181.0.2（内网 DNS），备用 223.5.5.5 | 装机 os.dns_nameservers |
| NTP | ntp.aliyun.com、0.suse.pool.ntp.org | etcd 对时间极其敏感 |
2.3 每节点网卡规划
| 网卡 | 绑定 | 交换机端口 | 承载 |
|---|---|---|---|
eno1 + eno2 | mgmt bond（active-backup） | trunk，放行管理 VLAN（或 untagged） | 管理 + Pod/Service overlay + 默认 VM 网络 |
eno3 + eno4 | cn-vm bond（802.3ad LACP，或 active-backup） | trunk，必须放行 VLAN 91 | VM 直通外网 underlay 流量 |
⚠️ 网卡名以真机为准：装机前用
ip -br link确认，并在 config 里同时写name与hwAddr（MAC），双保险。
三、全书目录
| 章节 | 主题 | 读完你能做完什么 |
|---|---|---|
| 01 架构与网络设计 | 组件栈、网络基础速成（VLAN/bond/bridge/MTU/DHCP）、三类网络、数据路径、12 节点角色与容量规划 | 画出并确认网络拓扑，定下所有 IP |
| 02 装机准备：IP 规划与交换机配置 | 前置检查清单、网卡确认、交换机 VLAN/trunk/LACP、HTTP/DNS/NTP 服务 | 环境达到「可以开始装机」的状态 |
| 03 ISO 无人值守安装 12 节点 | config.yaml 逐字段、create/join、内核参数、12 台批量装机、装机后加固 | 12 节点集群 Ready，UI 能登录 |
| 04 集群网络与 VM 直通网络 10.181.91.0/24 | ClusterNetwork / VlanConfig / NAD / VlanStatus、HostNetworkConfig、Managed DHCP | VM 网络 net-91 就绪，宿主机桥/VLAN 验证通过 |
| 05 VM 双网卡与 cloud-init 实战 | 管理网 + VLAN 网双网卡、cloud-init 网络配置、默认路由冲突、NIC 热插拔、LB | VM 拿到 10.181.91.x，外部能直接 SSH 进去 |
| 06 VM 模板与快速批量创建 | VM 模板与版本、Cloud Config Templates、批量脚本、克隆与黄金镜像 | 一条命令批量交付 N 台规格统一的 VM |
| 07 日常运维手册 | 巡检、存储与备份、节点维护/扩缩容、升级、监控告警、凭据轮换、重置与恢复 | 一套可以照抄的运维 SOP |
| 08 全链路验证与故障排查 | L0–L8 分层排查法、逐层验证命令、26 条故障对照表、6 个真实案例复盘、全书总验收清单 | 出问题时知道从哪一层开始查，交付前能逐项签字 |
附录（可直接使用的产物）
| 目录 | 内容 |
|---|---|
appendix/configs/ | 12 个节点的 ISO 装机 config.yaml + 一键生成脚本 gen-configs.sh |
appendix/network/ | ClusterNetwork、VlanConfig、NAD（net-91）、HostNetworkConfig、IPPool、LoadBalancer 的 YAML |
appendix/vm/ | 双网卡 VM 与 cloud-init 模板、vms.csv 清单、批量创建/校验脚本 gen-vms.sh |
appendix/ops/ | 装机前预检 preflight.sh、每日巡检 daily-check.sh、网络分层体检 net-check.sh、配置资产快照 cluster-snapshot.sh、VM 双网卡验收 vm-net-verify.sh |
appendix/tools/ | sync-from-chapters.py：把正文里标注了 # appendix/<路径> 的代码块同步成附录文件（--check 可做 CI 漂移检测） |
附录自带索引与使用顺序：见
appendix/README.md。正文与附录由tools/sync-from-chapters.py保证一致，改完正文跑一次同步即可。
四、怎么读这本书
- 第一次部署：按
01 → 02 → 03 → 04 → 05 → 06顺序做，每章末尾都有「验证清单」，通过后再进下一章。 - 已经装完，只想打通 VM 外网：直接看
04、05，以及08的分层验证。 - 只想批量交付 VM：看
06+appendix/vm/。 - 值班/排障：
07（SOP）+08（故障表），把appendix/ops/*.sh放到跳板机上定时跑。
书写约定
- 命令块中
<尖括号>是需要替换的占位符；所有 IP 都按上面第二章的规划表替换。 kubectl命令默认在 Harvester 节点上执行：ssh rancher@10.181.0.100→sudo -i，此时kubectl直接可用（kubeconfig 在/etc/rancher/rke2/rke2.yaml）。- 也可以在跳板机上用 VIP 远程访问：
export KUBECONFIG=./kubeconfig，其中 kubeconfig 从 UI 或节点上取。 - YAML 都按
kubectl apply -f可直接使用的格式书写；凡涉及需要以集群实际 CRD 为准的字段，正文会给出kubectl explain/-o yaml的反查命令。 - ⚠️ 表示踩过的坑；✅ 表示验证命令或期望结果。
五、Harvester 对象速查（贯穿全书）
| 对象 | API Group | 作用 | 章节 |
|---|---|---|---|
ClusterNetwork | network.harvesterhci.io/v1beta1 | 定义供 VM 流量使用的「集群网络」 | 04 |
VlanConfig | network.harvesterhci.io/v1beta1 | 定义哪些节点、用哪些物理网卡、以什么 bond 方式接入某 ClusterNetwork | 04 |
VlanStatus | network.harvesterhci.io/v1beta1 | 每个节点上网络配置的落地状态（排障必看） | 04 / 08 |
HostNetworkConfig | network.harvesterhci.io/v1beta1 | 给宿主机自身在 VLAN 子接口上配 IP（静态/DHCP），或指定 Kube-OVN underlay | 04 |
NetworkAttachmentDefinition | k8s.cni.cncf.io/v1 | 即 UI 上的「VM Network」，VM 网卡直接引用它 | 04 / 05 |
VirtualMachine | kubevirt.io/v1 | 虚拟机本体 | 05 / 06 |
VirtualMachineTemplate / VirtualMachineTemplateVersion | harvesterhci.io/v1beta1 | VM 模板与模板版本 | 06 |
KeyPair | harvesterhci.io/v1beta1 | SSH 公钥，可注入 VM | 05 / 06 |
IPPool（给 VM 发地址） | network.harvesterhci.io/v1alpha1 | Managed DHCP 插件的地址池（实验特性） | 04 |
IPPool（给 LB 用） | networking.harvesterhci.io/v1beta1 | 负载均衡的 IPAM 地址池 | 05 |
LoadBalancer | 负载均衡相关 group | 四层负载均衡，把外部流量导到 VM | 05 |
CloudInit | node.harvesterhci.io/v1beta1 | 给宿主机下发配置（如关闭 SSH 密码登录） | 03 |
Upgrade / Version | harvesterhci.io/v1beta1 | 集群升级 | 07 |
VirtualMachineBackup / VirtualMachineRestore | harvesterhci.io/v1beta1 | VM 备份与恢复 | 07 |
⚠️ 两个都叫
IPPool的 CRD：给 VM 发 DHCP 地址的是network.harvesterhci.io/v1alpha1（简称ippl），给负载均衡做 IPAM 的是networking.harvesterhci.io/v1beta1。用 kubectl 必须带全限定名，例如kubectl get ippools.network.harvesterhci.io -A，否则极易操作错对象。
六、参考资料
- Harvester v1.8 官方文档：https://docs.harvesterhci.io/v1.8/
- 安装配置参考：
/v1.8/install/harvester-configuration - 硬件与网络要求：
/v1.8/install/requirements - 装机后步骤：
/v1.8/install/post-install - 网络：
/v1.8/networking/（Cluster Network、VM Network、Network Deep Dive、Load Balancer、IP Pool、Best Practice、HostNetwork Configuration） - VM 管理：
/v1.8/vm/（Create a VM、Access to the VM、Backup/Snapshot/Restore、Live Migration、NIC Hotplug） - 升级：
/v1.8/upgrade/ - Managed DHCP（实验特性）：
/v1.8/advanced/addons/managed-dhcp
- 安装配置参考：
- Harvester 源码仓库：
harvester/harvester、harvester/harvester-installer、harvester/harvester-network-controller、harvester/load-balancer-harvester、harvester/terraform-provider-harvester - 上游项目：KubeVirt、Longhorn、RKE2、Multus CNI、cloud-init
版本说明：本书以 v1.8.2 为基准。Harvester 的 UI 与 CRD 字段在小版本间偶有调整，凡涉及具体字段，正文都给出「以集群实际对象为准」的反查命令。执行前先用
kubectl explain <resource>.spec --recursive或kubectl get <obj> -o yaml核对一次，是最稳妥的习惯。
七、30 分钟速览：从零到一台能外部 SSH 的 VM
如果你只想先看结果，下面是全书主干的最短路径（细节见对应章节）：
text
① 12 台服务器 UEFI 启动 ISO，用远程 config.yaml 无人值守装机 → 第 3 章
② kubectl get nodes 看到 12 个 Ready，UI https://10.181.0.100 可登录 → 第 3 章
③ 建 ClusterNetwork cn-vm + VlanConfig（12 节点、eno3/eno4、bond） → 第 4 章
④ 建 VM Network net-91（VLAN 91，路由 10.181.91.0/24 gw 10.181.91.1） → 第 4 章
⑤ 建 VM：nic-0 = Management Network，nic-1 = net-91 → 第 5 章
⑥ cloud-init networkData 里给 eth1 配 DHCP 或静态 IP + 路由 metric → 第 5 章
⑦ 外部机器 ssh ubuntu@10.181.91.x 成功 → 第 5/8 章
⑧ 把这台 VM「Create Template」，之后批量克隆 → 第 6 章每一步都有验证命令。不要把 ③④ 跳过：没有 ClusterNetwork/VlanConfig，VM 的第二块网卡在 UI 里根本选不到 net-91，这是最常见的第一个卡点。