scripts/ — 部署与运维脚本说明

本目录脚本均在 Harvester v1.8.2 / RKE2 v1.34.4-rc11 / 3 节点 环境实测通过。

脚本清单

脚本	用途	幂等	退出码
deploy-harvester.sh	一键部署（前置检查 → helm 渲染校验 → 安装 → 等待就绪）	✅	非 0 = 失败
post-install.sh	部署后固化关键配置（默认 SC、KubeVirt Snapshot gate、VolumeSnapshotClass）	✅	非 0 = 失败
healthcheck.sh	平台健康度巡检（约 20s，不创建任何 VM）	✅（只读）	1 = 有 FAIL 项
vm-e2e-test.sh	VM 能力端到端验证（创建→冷迁移→快照→恢复→清理）	✅（自建自清）	1 = 有 FAIL 项
values-harvester.yaml	Helm values（含 gate 的错误示范注释，实际由 post-install 固化）	—	—
manifests/	可复用的 K8s/KubeVirt/Longhorn 清单	—	—

标准使用顺序

export KUBECONFIG=/etc/rancher/rke2/rke2.yaml      # 或用 --kubeconfig 参数

# 1) 部署（首次）
bash scripts/deploy-harvester.sh --nodeport 32735

# 2) 部署后固化（★ 必做：gate 与默认 SC 会被 helm upgrade 覆盖，升级后需重跑）
bash scripts/post-install.sh

# 3) 巡检
bash scripts/healthcheck.sh

# 4) 能力验证（会创建并自动清理一台测试 VM）
bash scripts/vm-e2e-test.sh

manifests/ 说明

文件	说明
vm-cirros.yaml	Cirros 测试 VM + DataVolume（HTTP 源）+ cloud-init Secret。HTTP 源仅适合验证，生产请用内网源或 Harvester Image
vm-snapshot.yaml	VirtualMachineSnapshot（snapshot.kubevirt.io/v1beta1，KubeVirt 原生 API）
vm-restore.yaml	VirtualMachineRestore（同上 API；目标 VM 需先停机）
vm-migrate.yaml	VirtualMachineInstanceMigration（热迁移；本环境因 RWX 阻塞不可用，留作修复后验证）。⚠️ 该清单要求 vmiName 指向正在运行的 VMI，否则 migration-create-validator.kubevirt.io 会拒绝（the VMI "default/vm-demo" does not exist）——因此 --dry-run=server 在无同名运行 VM 时必然报错，属预期
vm-blank-migrate-test.yaml	空盘 VM（source.blank）+ 冷迁移用的 nodeSelector 示例
volumesnapshotclass-longhorn.yaml	Longhorn VolumeSnapshotClass（type 参数选型见下）

VolumeSnapshotClass type 选型（★ 重要）

type	语义	依赖	恢复可靠性
snap	Longhorn 卷内快照	无（无需 backup target）	⚠️ 恢复需从源卷克隆；源卷被删则 cloneStatus=failed，VM 起不来
bak	Longhorn 备份	必须配置 backup target	✅ 数据在集群外，恢复不依赖源卷（生产推荐）

各脚本参数

bash deploy-harvester.sh --help
bash post-install.sh   --help
bash healthcheck.sh    --help
bash vm-e2e-test.sh    --help

vm-e2e-test.sh 常用参数：

--vm NAME           测试 VM 名（默认 vm-e2e）
--ns NS             命名空间（默认 default）
--size SIZE         磁盘大小（默认 2Gi）
--skip-migrate      跳过冷迁移
--skip-snapshot     跳过快照/恢复
--keep              结束后保留测试 VM（便于人工检查）

设计约定

• 统一 set -euo pipefail；kc() 封装 kubectl，自动兼容 RKE2 内置 kubectl 与 KUBECONFIG；
• 所有写操作幂等：apply 而非 create，kubectl annotate --overwrite， gate 修改前先 grep -qx 判重（避免重复追加）；
• 关键校验不只看控制面：例如恢复后会额外核对 Longhorn 卷 state/robustness/cloneStatus（type=snap 恢复可能"假成功"）；
• 失败即返回非 0，并在输出中给出可直接执行的修复命令与文档指引；
• 已知非致命噪声（Steve/Rancher 聚合、ssl-certificates requeue）降级为 WARN，不计入 FAIL；
• 巡检脚本自身也经过验证：首版 healthcheck.sh 曾误报 7 个 FAIL（根因是 kubectl -o json 为格式化 JSON、awk 不支持反向引用、helm history 列错位、 kubectl get vm -A 状态列是 $4、不存在的命名空间仍返回退出码 0 等）， 修复后 FAIL=0 / PASS=30。详见 ../02-故障排查与修复记录.md 案例 16。