You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
virt/docs/VPC_DATAPLANE_ACCEPTANCE.md

11 KiB

VPC 私网数据面宿主机验收矩阵

代码侧已经验证计划解析、稳定私网 MAC、cloud-init 多网卡、生成脚本的 POSIX 语法和 typed readback contract。当前开发环境没有 ip、wg、nft、nmcli、 ifquery 或 libvirt daemon,因此下面的宿主机步骤不能在本机冒充通过。

应用前证据

在每台同地区宿主机保存 Fabric active 的新鲜回读,并确认:

  • wg-fabric0 由 Fabric owner marker 所有,Fabric 锁可用,IPv4 forwarding 已启用; readiness 分别显示 rp_filter 的 all/default、实际 endpoint 接口和 wg-fabric0 raw/effective 值,并按 max(all, interface) 核对有效值。Alma/RHEL 的 default=1 与公网 endpoint 接口 strict 1 是可保留的正常策略,不能据此 阻断 VPC,也不能要求面板改写全局或公网接口;平台拥有的 wg-fabric0 必须在 承载流量前持久化并回读 raw/effective 2。尚未创建时应明确显示待自动配置, 动态 vnet*/tap 不参与该门禁;
  • AlmaLinux 10 只有 NetworkManager/nmcli 处于 active/enabled,Debian 13 只有 ifupdown 的 ifup、ifdown、ifquery 和 /etc/network/interfaces(含已加载 的 interfaces.d)作为网络管理来源;
  • 防火墙精确处于 Fabric 已确认的 native_nftables 模式; nft 命令可用、规则集可读,持久主配置只有一个受管 include, firewalld 不存在或 inactive+masked,且没有遗留 inet firewalld table。任何旧 firewalld_nft desired/manifest/journal 都必须阻断普通 reconcile,不得自动迁移; stock nftables.service 状态只作诊断,不参与 readiness;
  • NetworkManager profile 不 autoconnect、不写 zone;ifupdown fragment 不含 auto。 wg-fabric0 和 VPC bridge 只在受管 nft ACL 精确回读后激活,不依赖任何 firewalld zone/trusted 状态;
  • Fabric 公网或内网 endpoint 均不位于全局租户 VPC CIDR 池,且当前 VPC CIDR 不包含 任一 Fabric endpoint;否则目的策略路由会吸走 WireGuard underlay,必须在 apply 前阻断; /etc/virt-cloud、/run/virt-cloud、/etc/nftables.d 和 sysctl.d 不是符号链;
  • br0、管理接口、默认路由和未知 nft 规则的快照已经保存。

成员接入和回读

对一个跨两台宿主机的 VPC,至少放置两个成员和一个 ACL,逐台检查:

镜像前置契约:安装并启用 qemu-guest-agent,domain 存在 agent channel, guest-info 中 guest-exec 与 guest-exec-status 均为 enabled;镜像必须提供 /usr/bin/timeout、/usr/bin/head、/bin/sh 和 /usr/sbin/ip。不要假定发行版默认允许 guest-exec:Alma/RHEL 系列镜像或加固策略可能在 QGA blocklist 中禁用它,必须逐镜像实际核对。任何一项缺失 都应得到 vpc_private_guest_probe_unsupported(或 unavailable),成员不得 usable。

  1. 运行中 VM 首次加入,或其 MAC、私网 IP、VPC CIDR 变化时,引擎不得改写 NoCloud seed、 inactive XML,也不得对 live domain 执行私网网卡热插/热更新;旧配置必须原样保留。 VM 完全停机后由下一次 reconcile 写入 seed 与 inactive XML,再执行完整 start。 在完成该 stop/reconcile/start 流程前,宿主状态必须是 applying、回读为 pending_restart、错误码为 vpc_private_guest_restart_required,且 VPC usable=false。普通 guest soft reboot 不能替代 libvirt stop/start。

  2. 生成的 bridge 名称、owner/state/proxy 文件均为 root-only,bridge/tap 没有 地址、网关或 DNS;private0 产品角色对应的 libvirt alias 是 ua-private0,其 bridge、稳定 MAC、/32 和持久/实时 XML 都一致,私网接口 不绑定公网 clean-traffic nwfilter。

  3. QGA 回读必须找到唯一的 guest 接口名与 MAC,精确 IPv4 地址只有目标 /32;固定 sysfs 探测必须同时确认接口 flags 含 IFF_UP、operstate=up、carrier=1。 接口 down 后即使地址和路由仍保留也必须返回 vpc_private_guest_link_mismatch,不能通过 usable 门禁。显式 network suspend 则以 persistent/live XML 都为 down 证明隔离,并保持成员 non-usable。

  4. 宿主机上的每个成员 /32 和每条自定义 /32 route 都带 panel route protocol、正确 device/table、via 和 metric;不存在 VPC CIDR、默认路由或宽前缀的替代项。 来宾 main table 的目标 route 必须只有一条 exact scope-link VPC CIDR,不能含 gateway、 nexthop、linkdown、dead 或 unresolved flags;成员或自定义 route 变化不得改变 兄弟 VM 的 guest generation。历史逐成员 /32 seed 只能在完全停机后迁移。

  5. wg show wg-fabric0 allowed-ips 的每个 peer 与完整期望集合一致:overlay /32 加精确 tenant/service /32,没有 0.0.0.0/0、宽前缀或其他 VPC 的未授权地址。

  6. nft inet/bridge/arp 三张表的 owner marker、chain priority、ACL comments、 anti-spoof、IPv6/广播/未知目的 drop 和精确 proxy-ARP set 均能被 observe 回读。 bridge 上通用 proxy_arp=0、同桥下一跳所需的 proxy_arp_pvlan=1、 rp_filter=2,代理项集合与 route destination 集合 完全相同;其他地址的 ARP reply 必须被过滤。 observe 还必须以计划携带的 fabric_plan_digest 重建并核验 Fabric table grammar、 owner/digest、精确 tenant set 和完整 stateless snapshot;Fabric revision 或任一租户 AllowedIPs 漂移时,即使本 VPC 三张表未变也不得报告 active。

  7. 从同机和跨机成员分别验证允许的 TCP/UDP/ICMP 流量、ACL deny、伪造源 MAC/IP、 IPv6、广播/多播和访问宿主机自身地址。验证结果同时记录 guest route、宿主机 route、WireGuard handshake 和 nft counter,不能只看页面的 active。

管理器和重启矩阵

AlmaLinux 10:执行 nmcli connection reload、systemctl restart NetworkManager、 panel-owned Fabric service/timer 修复测试和宿主机重启。不要用 stock nftables.service 的 start/reload/stop 作为验收步骤。每一步都要确认 private bridge 没有靠 autoconnect 抢先启动,helper 先恢复并回读 nft inet/bridge/arp ACL,再按 UUID 激活 profile;过程不应出现 firewalld zone/trusted 依赖;随后 route/rule、proxy ARP、WireGuard peer、 ua-private0 XML 和默认公网路径恢复,NetworkManager 没有接管 br0 或管理接口。

Debian 13:执行 ifquery <private-bridge>、systemctl restart networking、 panel-owned Fabric service/timer 修复测试和宿主机重启。不要启动或重载 stock nftables.service。确认不含 auto 的 interfaces.d fragment 不能让 bridge 绕过 helper 抢先启动,ACL 精确回读后才执行 ifup --force,且不应出现 firewalld zone/trusted 依赖;随后 route/rule、 proxy ARP、WireGuard peer 和 ua-private0 XML 恢复。严禁用 ifdown 操作 br0 或管理接口。

两种发行版都要分别测试 libvirt service、socket activation 和 VM autostart。实际存在的 libvirtd.service 或 virtqemud.service/virtproxyd.service 及 libvirt-guests.service 必须通过受管 Requires=/After= gate 等待 Fabric service。socket 保留发行版默认顺序, 其激活的 daemon 仍须通过相同门禁;任何来宾私网都不能在 ACL 和 bridge 恢复前启动。

故障回滚

在隔离环境中分别让 ip link、ip route、ip rule、ip neigh、wg set、 nft -c、nft -f、NetworkManager/ifup、sysctl 或 libvirt define/seed 上传在 每个阶段失败。预期结果是:

  • apply、实例接入和停机 libvirt 变更失败时,原 panel-owned bridge、route/rule、 peer AllowedIPs、nft 表/include、proxy 项、sysctl、XML 和 seed 按快照恢复;
  • apply/remove/rollback/journal 恢复必须以单次 nft batch 建立或恢复受管 table;只有 marker/digest 精确回读后才能重新激活接口,不能用分离的 table delete/load 暴露无 ACL 窗口;
  • boot 对 panel-owned bridge 执行 hard quarantine 时,必须在 down 前后严格核对有界端口 快照并回读确认 UP flag 消失;bridge 命令/解析失败、端口变化或 NetworkManager 竞态 重新拉起接口都必须停止恢复且不得继续改写 nft,不能靠停用 profile 拆除 tap;
  • 删除/撤销路径使用阶段 journal 和 fail-closed 收敛:未提交的 journal 在回读前 返回 uncertain/manual_reconcile 并保留现场,不重复执行破坏性删除;只有已经 提交且能证明面板资源全部不存在的 journal 才会被清理。因此删除路径的“回滚” 是可审计的停机与人工核对边界,不是假设资源可以自动恢复;
  • 事务开始前或最后 precommit 回读已存在的外部 bridge/profile、未知 route、未知 ARP proxy 项和未知 nft 规则不被删除;同机 root/CAP_NET_ADMIN 与 out-of-band nft 管理器 必须遵守维护互斥,因为 nft CLI 不提供跨进程 compare-and-swap;
  • 恢复本身失败或响应丢失时返回 uncertain/degraded,保留事务目录供下一次 readback,绝不返回成功;
  • 重试只依据新的完整宿主机回读,不对不确定的 libvirt 或网络变更盲目反向执行。

跨宿主机最后还要单独验证 underlay 公网防火墙、NAT、MTU、SELinux 和 UDP 监听。 Fabric/VPC 的 panel-owned nft 表不负责放行 underlay UDP;运维必须在宿主 持久 native nftables 规则或上游云安全组/防火墙中,以精确 peer 源地址、 本机 endpoint /32、UDP 和 Fabric 监听端口放行。还需单独核对外部 DNAT, 并用双向握手和实际流量验收;接口 active 或 unit green 不能证明端到端可达。

发布和规模边界

  • 先应用包含 VPC evidence version 字段的数据库 schema,再发布 PHP/worker,最后发布 engine。历史或混合版本 receipt 没有 evidence_version=2 时必须重新 reconcile,不能 继承旧 active/usable。
  • 用 1、32、256 个成员和至少两台宿主分别压测正常、QGA command disabled、QGA timeout 三种场景。引擎的协作式探测预算到期后必须停止提交新 QGA/SSH 探测,并取消 未开始任务;它不是对已经开始的 libvirt 打开、XML、seed 或 define 操作的强制 HTTP 截止。PHP HTTP timeout 必须大于该探测预算,operation lease 还要留出明确余量;超时只返回 vpc_private_guest_probe_deadline_exceeded 并继续幂等 reconcile,不能 lease steal、 重复派发或遗留不断增长的 guest process/线程/SSH 连接。
  • 宿主 libvirt 必须为 upstream 4.2.0+,或由发行版明确回补 CVE-2018-1064 的 QGA 单响应 10 MiB 读取上限;Python 只解析 不超过 192 KiB 的响应,且默认最多并行 4 个来宾探测。agentSetResponseTimeout 恢复 默认值失败时必须返回 uncertain,不能在 domain-wide timeout 仍被修改时发布 confirmed。
  • 另用单宿主 4096 成员验证周期 reconcile:生命周期目标必须优先;进入 QGA 并发探测前 的逐 VM seed/libvirt 核对仍是已知串行边界,应记录首个目标完成时间和全量收敛时间, 不能仅以请求超时作为容量结论。
  • 同一 VPC 放置 A、B 两个成员:A QGA exact、B stopped/unsupported 时,配置 operation 应完成,A 的实例私网可用、B 单独显示未就绪,聚合健康可 degraded;随后只恢复 B 的 agent/启动状态,不做新 mutation,周期 reconcile 必须最终将 B 和聚合健康推进为 active。