libvirt provider 版本需与宿主机 libvirt/qemu 匹配，推荐 dmacvicar/libvirt ≥ v0.7.5（对应 libvirt ≥ 6.0、qemu ≥ 5.2）；复杂网络须分层建模；多网卡需 cloudinit 显式配置；拓扑感知依赖 libvirt_node_info/node_devices 动态获取宿主机能力。
libvirt provider 版本和依赖必须匹配当前 libvirt/QEMU
不匹配会导致 provider 初始化失败、资源创建卡死，或出现类似 virError: internal error: unable to initialize network 'default' 的报错。2026 年主流环境（CentOS 8.3+/Ubuntu 22.04+）应使用 dmacvicar/libvirt ≥ v0.7.5，对应 libvirt ≥ 6.0、QEMU ≥ 5.2。旧版 provider（如 v0.6.x）在 NUMA 拓扑识别、PCI 直通设备绑定等场景下会静默忽略配置。
验证方式：运行 virsh version 和 terraform providers，确认输出中 libvirt 版本与 required_providers 声明一致。若用 dnf install libvirt 安装，注意 CentOS Stream 默认源可能提供过旧版本，建议启用 epel 或手动编译 libvirt 6.10+。
复杂网络拓扑必须拆解为「基础网络 + 连接关系」两层建模
Terraform libvirt provider 不支持“一键拉起多网段桥接+路由+NAT”的复合网络对象。强行在一个 libvirt_network 资源里堆砌 forward_mode = "route" 和多个 ip 块，会导致 apply 失败或状态漂移。
- 先定义独立的底层网络资源：例如
libvirt_network "mgmt"（forward_mode = "nat"）、libvirt_network "data"（forward_mode = "bridge"，绑定物理接口br0） - 再通过虚拟机的
network_interface显式挂载：每个libvirt_domain的network_interface块需指定network_id = libvirt_network.mgmt.id或network_id = libvirt_network.data.id - 跨网段通信靠 guest OS 内部配置：Terraform 不管理路由表、iptables 或 dnsmasq 配置，这些必须由
cloudinit_config或provisioner注入
cloudinit 配合 libvirt 是实现多网卡自动寻址的关键
裸用 libvirt_domain 创建多网卡虚拟机后，guest 往往只对第一张网卡做 DHCP，其余网卡无 IP —— 因为默认 cloud-init 只处理 eth0。要让 eth1、eth2 也自动获取地址，必须显式构造 cloudinit_config 并覆盖网络配置。
示例要点：
- 用
data "template_file" "netplan"渲染 netplan YAML，明确列出每张网卡的dhcp4: true或静态地址 - 在
libvirt_domain中引用：user_data = data.cloudinit_config.vm.rendered - 确保镜像已预装
cloud-init且启用：检查/etc/cloud/cloud.cfg中disable_root: false和datasource_list: [ NoCloud, ConfigDrive, None ]
libvirt_node_info 和 libvirt_node_devices 是拓扑感知的前提
构建真实生产级拓扑（比如 CPU pinning、SR-IOV VF 分配、NUMA-aware 内存分配）时，不能硬编码 vcpu = 4 或 memory = 4096。必须先用数据源动态获取宿主机能力，再约束虚拟机规格。
典型组合用法：
-
data "libvirt_node_info" "host" {}→ 获取cpu_cores_total、memory_total_kb，用于计算最大可分配 vCPU 数量 -
data "libvirt_node_devices" "sriov_vfs" { filter { capability = "net" driver = "vfio-pci" } }→ 扫描可用 VF 设备，供libvirt_domain的host_device引用 - 把上述数据源输出作为
count或for_each条件，避免 apply 时因资源不足失败
注意：libvirt_node_devices 在非 root 用户下执行会返回空列表，务必确保 Terraform 运行用户属于 libvirt 组且能访问 /var/run/libvirt/libvirt-sock。
