用途：将现存的 kube-hetzner 集群从 v2.x 迁移到 v3.x，面向真实用户 Terraform 根，而非新建集群，优先保护基础设施并使校验失败可操作。
主要能力：提供迁移操作手册、变量映射、发布证据、SELinux 策略说明与静态配置/计划审计脚本；可识别 v2 专用输入、生成迁移报告并给出建议。
必要用法：先阅读 docs/v2-to-v3-migration.md、docs/v3-release-evidence.md、MIGRATION.md、CHANGELOG.md、variables.tf、kube.tf.example 及 scripts/v2_to_v3_migration_assistant.py、docs/selinux.md、scripts/destroy.sh 与 cleanup.sh。按步骤：检查当前根（terraform version、terraform providers、rg 查找模块与 v2 输入，运行 uv run python .../v2_to_v3_migration_assistant.py --root . 并配合 rg 交叉核对）；备份状态（terraform state pull > "terraform-state-before-kube-hetzner-v3-$(date +%Y%m%d%H%M%S).json"）；按 MIGRATION.md 改写配置（如 k3s_token -> cluster_token、kubernetes_distribution_type -> kubernetes_distribution，反转 disable_* 布尔，existing_network_id 改为 existing_network = { id = 123 }，enable_x86/enable_arm 改为 enabled_architectures，移除若干旧输入等）；首次 apply 前确定 K3s 通道策略、插件版本策略、SSH 授权键策略与节点可达性；再执行 terraform fmt -recursive、terraform init -upgrade、terraform validate -no-color，必要时用 tofu 无后端校验；然后用 terraform plan 并用严格审计脚本与 jq 门禁检查 hcloud_server、hcloud_network、hcloud_network_subnet、hcloud_load_balancer、hcloud_volume、hcloud_primary_ip、hcloud_placement_group、hcloud_firewall 的 delete/replace。
适用场景：标准在线 v2 到 v3 升级、NAT/私有节点/Robot/vSwitch/多网络等特殊拓扑的评估。
限制：未获得用户明确批准不得运行 terraform apply；必须备份状态；不得忽略 destroy、replace 或 forces replacement；v3 默认 k3s_channel = "stable" 且自动升级默认开启，用户须在首次 v3 apply 前选择；迁移中不得重排或插入控制面/代理节点池，只能追加；不得绕过校验；自定义网络、纯私有、Robot/vSwitch 或多网络集群若不确定安全应建议蓝绿重建；SELinux 默认保持启用，禁止全局禁用而应收集 AVC 并遵循 docs/selinux.md；多网络公共覆盖层仅实验室预览，Tailscale 节点传输尚无 Hetzner/Tailscale 在线端到端验证，不得仅据静态检查用于生产；首次原地升级不应同时添加 Cilium Gateway API、嵌入镜像仓库或 Cloudflare Access/Tunnel 等新特性。官方资料未提供具体收费、价格或平台信息。