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/FABRIC_HOST_ACCEPTANCE.md

16 KiB

Fabric 宿主机验收矩阵

这份矩阵用于真实宿主机验收。仓库测试只证明生成脚本、能力解析、所有权回读和事务 契约;没有 AlmaLinux 10 或 Debian 13 真机证据时,不得把下面项目记为已通过。

公网优先与后续内网 underlay

  • 当前公网组网可把 fabric_endpoint_ip 留空,但 SSH host 必须是本机持有的字面 IPv4。SSH 使用域名时必须显式填写 endpoint;引擎不会用 DNS 结果建立 Fabric 身份。
  • 后续改为同地区内网组网时,逐台填写宿主机实际持有的内网 IPv4。每台宿主机仍只公布 一个 endpoint,所以该地址必须被地区内所有其他 Fabric 成员路由可达;不能在同一个 plan 中针对不同 peer 同时公布公网和内网 endpoint。endpoint 不能落入全局租户 VPC CIDR 池;默认 10.0.0.0/8 作为租户池时,应为 underlay 选择与之隔离的公网、 172.16.0.0/12 或 192.168.0.0/16 机房地址。
  • 例如三台机器中一台只有公网、两台另有同机房内网:若公网机器不能路由到另两台的 内网 endpoint,就继续让三台都使用公网 endpoint。只有三台之间都能访问所选内网地址 时才整体迁移;修改 endpoint 后旧 plan 必须显示 migration_required,不能原地冒充 active。
  • 记录 endpoint 地址所属接口,并逐个执行普通 ip -4 route get <peer> 与 ip -4 route get <peer> from <本机 endpoint>。普通查询必须只有一个 dev 和 src; 显式源查询必须只有一个相同的 dev 和 from,可选的 src 若存在也必须唯一且相同。 两种来源字段都必须等于本机 endpoint,地址 owner 接口也必须与出口接口一致;loopback、dummy、 wg-fabric0、VPC bridge、多路径、错误源地址或不同出口均应阻断自动放行。

防火墙所有权

每台宿主机只支持 native_nftables:nft 命令必须可用且规则集可读, 发行版主配置只能有一个 panel 受管 include。stock nftables.service 的 active/enabled/load 状态只作诊断,不参与 readiness;平台自己的 Fabric service/helper 直接加载和回读受管表。测试环境建议保持 stock unit disabled, 不要用它的 start/reload/stop 验收平台规则。firewalld unit 必须不存在或 inactive+masked,且实时规则中不得存在其所有的 inet firewalld table。 仅 disabled 不够,因为 D-Bus 仍可重新激活它。

能力探测发现 firewalld 服务、旧 firewalld_nft desired state、manifest、 journal、zone/rich-rule 所有权或其他管理器冲突时必须 fail-closed。普通 apply/reconcile 不得把旧模式静默映射为 native nftables,也不得删除旧对象。 测试环境的一次性转换应先停止租户流量,备份规则与 journal,在维护窗口 清理 firewalld 及旧 panel 所有权记录,再以全新 native 方案重建。

panel-owned Fabric nft table 不负责放行 underlay UDP。管理员必须在宿主的持久 native nftables 规则或上游防火墙/云安全组中,以可证明的最窄 peer 源地址、 本机 endpoint /32、UDP 和 Fabric listen port 显式放行。外部 DNAT 也由运维 显式管理。触发 panel-owned reconcile、repair timer 和宿主重启后必须重新核对 这条 underlay 路径、panel owner/revision/digest、Fabric/VPC table、WireGuard 双向握手及允许/拒绝流量。 单纯看到 wg-fabric0 active 或 systemd unit green 不能证明 underlay 可达。

AlmaLinux 10 / NetworkManager

确认 NetworkManager 是唯一网络管理器。panel 的 virt-cloud-wg-fabric0 和 VPC bridge keyfile 必须位于 /etc/NetworkManager/system-connections/、owner 为 root、mode 为 0600,并设置 connection.autoconnect=no、不含 connection.zone;/run、 /usr/lib、in-memory/external profile 或其他 mode 不作为可持久恢复证据。接口只能在 nft ACL 精确回读后通过已验证的 UUID 激活,不查询、设置或要求任何 firewalld zone/trusted 状态。执行 nmcli connection reload 和 systemctl restart NetworkManager 时,接口不得先于 repair helper 自动连接, br0、管理接口和默认路由不得改变。

AlmaLinux 10 的 nmcli 把 FILENAME 作为无 ID 的 connection show 列表字段, 不提供 connection show uuid <UUID> 下的 GENERAL.FILENAME。验收必须确认引擎 使用 nmcli -t --escape no -f UUID,FILENAME connection show 并按 UUID 精确、唯一 解析 keyfile;不得因为无效的 detail 字段拒绝合法 endpoint。与 endpoint 无关的 /run/external profile 可以单独 fail-closed,但不得污染已有唯一持久 keyfile 的 endpoint 接口。

执行 native nftables reload,然后重启宿主机。记录 wg show wg-fabric0、ip -4 route show table all、受管 nft table/marker、默认路由和 管理地址;确认 helper 先恢复并回读 Fabric 隔离及全部 VPC inet/bridge/arp ACL,随后才 激活接口。过程中不应出现 firewalld zone/trusted 依赖。

Debian 13 / ifupdown

确认 /etc/network/interfaces 或 interfaces.d 由经典 ifupdown 管理,探测到的 ifup、ifdown、ifquery 路径与面板记录一致,systemd-networkd 和 NetworkManager 没有 active/enabled/configured 接管证据。panel fragment 不得包含 auto,同名 ifcfg 不得存在。 ifup --force wg-fabric0 只能在 ACL 精确回读后运行,不能触碰 br0、默认路由或管理 地址。

Debian 13 的 iproute2 6.15 在 WireGuard 内核模块尚未加载时, ip -j -d link show type wireguard 可能以成功状态返回每个现有 link 对应的 空对象。能力探针只能在模块状态精确为 not_loaded 时忽略 WireGuard typed 段中的精确 {} 占位;已加载模块、普通 link/bridge/address 段或任何非空畸形记录 仍必须 fail-closed。此兼容不代替 modinfo/模块可用性证据,也不允许引擎在只读 检测中执行 modprobe。

执行 native nftables reload,并执行 systemctl restart networking 和宿主机重启。确认 fragment、peer、地址、路由和受管 nft table 都由 helper 按 ACL-first 顺序恢复,且不应出现 firewalld zone/trusted 依赖。

libvirt 启动门禁

检查本机实际存在的 monolithic 或 modular libvirt daemon,包括 libvirtd.service、 virtqemud.service、virtproxyd.service 以及 libvirt-guests.service。受管 daemon drop-in 必须同时包含对 Fabric service 的 Requires= 与 After=;外部同名冲突 drop-in 应阻断 apply。分别测试普通 service 启动、socket activation 和 VM autostart,均不得在 Fabric/VPC ACL 和 bridge 恢复前开放来宾私网。 socket 保留发行版默认启动顺序,其激活的 daemon 仍受上述门禁约束。不得给默认 Before=sockets.target 的 socket 再添加 After=Fabric,也不得让 Fabric Before=socket; Fabric 是依赖网络的普通 service,这种顺序会通过 basic.target 形成启动循环。

启动和恢复脚本保持 root-owned 0700,但 runner、update、apply、临时/固定恢复 helper、 持久 unit 的 ExecStart/ExecCondition 和 ifupdown hooks 都通过绝对路径 /bin/sh 解释。 验证 /run 或存放脚本的目录启用 noexec 后仍可运行;chmod +x 不会覆盖 noexec。 ifupdown 主 service 必须在 ifup --force 后继续完整配置及运行态回读,不能仅凭 ifup 的 返回码把 oneshot 标成 active。经典 ifupdown 重建 hook 环境,仅保留调用者的 IFUPDOWN_* 变量;父 apply、恢复与主 service 通过此命令级前缀传递锁/事务上下文, hook 再严格映射到内部变量。测试必须模拟过滤普通 VC_* 的环境,不能用原样传递 环境的假 ifup 代替。官方语义见 Debian 13 ifupdown 源码、 Debian 13 systemd.service、 Debian 13 systemd.socket 与 RHEL 10 systemd unit。

repair timer 有两个互斥且可核验的分支:主 Fabric service 明确 failed 时,dispatcher 只 重新排队主 service;libvirt daemon 只有本 boot PID 1 的最新该 unit 记录自身为 JOB_TYPE=start/JOB_RESULT=dependency、时间不早于本轮 Fabric 失败、当前 inactive/无 job, 且有效门禁完整时才可自动排队。每 daemon 每 boot 只消费一次有界、root-owned 的证据, 修复后再次回读并用 --no-block --job-mode=fail start 排队;缺日志、未知对象、后续手动 stop/新 job/成功/自身错误均跳过。不得用 service Result=dependency 判断:dependency 是 job 的结果,不是 service 的 Result。主 service 为 active 但受管 nft table、 Fabric 或 VPC 接口漂移时,reconcile service 直接执行同一份带 flock 的完整 ACL-first helper。该分支不得 restart 主 Fabric unit 或任何 libvirt unit,健康状态也 不得进入 helper。

在全新宿主执行 apply 后、不重启宿主机,确认事务 committed 后 apply 释放 flock、同步 启动独立 dispatcher,主 oneshot 最终进入 active,完整 helper 证明无旧 emergency owner/table 并完成 ACL/WireGuard 回读后 apply 才返回 成功;再制造受管 runtime 漂移,确认 timer 能在首次 reboot 之前完成修复。 人为让主 helper 持有 Fabric flock,确认 dispatcher 等待期间 apply 不会持锁死锁;让同步 启动失败时,确认 committed journal 仍保留且旧进程不会删除并发新事务的 ready journal。

异步 operation 与安全日志

  1. 点击“自动配置地区私网”或“重新核对”时,HTTP 应在宿主 apply 完成前返回 202,回执中的 operation ID 必须是 32 位小写十六进制,根记录和全部宿主行必须 显示同一 ID。轮询过程不得再出现第二个 POST。
  2. 在宿主机上用回执 ID 查看 systemctl status virt-cloud-fabric-apply-<operation_id>.service(任务仍被 systemd 保留时)和 journalctl -u virt-cloud-fabric-apply-<operation_id>.service --no-pager。 transient unit 使用 --collect,因此终态后 systemctl status 可以变成 not-found, 但 journal 仍必须可按完整 unit 名回查。journal 只得出现 operation ID、固定 state/checkpoint/reason、固定 helper_phase/apply_check/退出码 与 systemd 生命周期;不得出现私钥、完整脚本、 peer 全量配置、SSH 路径或原始 stderr。 journal 恢复必须按实际进度显示固定子检查点 journal_artifact_restore、 journal_nft_restore、journal_runtime_restore 或 journal_finalize;任何未知值都只能投影为 unknown,不得把原始命令或错误输出透传到页面。 journal_dispatch 表示已验证恢复 helper 身份并即将调用;执行前检查分别显示 preflight_sysctl/tools/artifacts/firewall/vpc/underlay/routes/persistence(每项为独立 preflight_ 检查点)。旧 preflight 的未知命令失败不得再统一误标为资源归属冲突。 async runner 必须继续丢弃原始 stdout/stderr,只通过独立描述符记录净化后的 helper_state=failed helper_phase=... exit_status=...。apply 在回滚开始前记录 apply_state=failed apply_check=... exit_status=...,用于区别首次失败与回滚/服务 的次生错误;未知子项只能为 unknown,不能输出命令、配置或外部错误文本。
  3. /run/virt-cloud/fabric-operations/<operation_id> 必须为 root:root 0700,manifest/status 必须为 0600,apply/update/runner 必须为 0700;任一符号链接、多余文件、owner/mode/hash 漂移都必须 fail-closed。达到上限时只能精确删除最旧的已验证终态目录,不得删除 queued/running/当前 ID 或未知对象。
  4. 分别在“dispatch 已接纳但 SSH 回包丢失”、“operation 目录发布后、systemd-run 前中断”、 “第一台宿主已接纳、第二台尚未下发”、“Engine 重启”和“页面/CDN 超时”复现。页面 GET 与周期核对必须只读;显式“重新核对”只能在完整 ID/hash/unit/逐节点 dispatch fence 证据下 启动原 queued runner,或在已接纳节点精确收敛后对确定未接纳节点继续同 ID 下发。宿主只能 出现一个同 ID 任务,已接纳节点不得重派,也不得生成新 ID;在终态未证明前,新 apply 必须 被拒绝、Fabric gate 必须关闭。
  5. 人为卡住宿主 helper 超过 operation 运行上限,systemd 必须终止该 cgroup,状态只记录 固定的 interrupted/uncertain 原因,保留 journal 与当前现场并禁止自动重放。
  6. 在 Debian 13 把 /run 挂载为 noexec,确认 transient oneshot 的命令行为绝对路径 /bin/sh /run/virt-cloud/fabric-operations/<id>/runner,任务能进入 host_lock 而不是 203/EXEC;确认 unit 使用 TimeoutStartSec=840s 且没有无效的 RuntimeMaxSec=。
  7. 保留一个旧版本生成的 queued/dispatch/none operation,并分别模拟 unit not-found 与 精确的 exit-code/exited/203。升级后第一次显式“重新核对”只能将旧 operation 标记为 failed/dispatch/systemd_failed,不得覆盖或运行旧脚本;第二次显式“重新核对”必须生成新的 operation ID。任一 status 时间、hash、owner/mode、文件集合或 unit 结果不符合时都应拒绝 迁移并保留现场。

失败回滚和安全边界

保留同计划的 native_nftables ready journal 和历史 helper.present:只能在旧 helper 与 journal pre/post-image 精确一致、meta 中 digest/UUID/manager/firewall 全部绑定 当前方案,且 underlay 由当前 plan/helper digest 间接绑定时,才能在核验 当前临时 helper 的权限与计划头后,交由当前实现恢复。恢复完成的 recovery-only 调用不得再次执行已恢复的旧 helper。任何 firewalld_nft journal 及其 snapshot 不进入此 恢复路径;标记为 native 但仍携带已退役 firewalld_*/underlay_* 字段的旧 schema 也只保留现场并进入维护清理。跨计划不得把旧计划的权限移交给新模板。外部文件/密钥/nft 漂移必须保留现场并拒绝。新增 timer 必须在 state=committed 同步落盘之后才启动, timer 启动失败只能保留 committed journal,不能回滚已提交的数据面。

在隔离环境中分别让 nft -c/-f、wg、ip route、 nmcli/ifup、systemd gate 和 timer 返回失败。每次都应看到 apply 失败并保持 uncertain/degraded。panel-owned peer、地址、路由、profile/fragment、 manifest/include 和 systemd 状态必须按快照恢复; 无法恢复时不得报告 active。

分别在 snapshot/journal 写入后、nft 预检前、原子 batch 提交前后和 manifest refresh 前后中断进程并重跑;每次只能在 owner、完整 shape、snapshot 和现场回读全部匹配时继续。 预先放置旧 emergency owner/table、firewalld_nft owner/manifest/journal 或 inet firewalld table,确认普通 apply/reconcile 拒绝并保留现场;不得用新 native desired state 覆盖或清理它们。

让 bridge link show master 失败或返回畸形、重复、超过上限的端口记录,并模拟 ip link set down 返回成功但 NetworkManager 立即把 bridge 恢复为 UP。boot/apply 均 必须 fail-closed、保留 bridge/tap 端口关系,不得继续改写 nft 或提前恢复流量。

预先放置非 panel-owned 同名 nft table、宽前缀路由、策略表路由、同名接口或冲突 systemd drop-in,apply 必须拒绝并保留原状态。最后从其他宿主机核验 WireGuard UDP、 握手、NAT、MTU、SELinux、允许/拒绝流量和 nft counter;本地接口 active 或 unit green 都不能单独证明跨宿主机可用。

平台使用自身 flock、完整 stateless snapshot、nft -c 后的最后 precommit 回读、单次 原子 nft -f 以及提交后回读来保护事务开始前或最后回读时已经存在的外部对象。nft CLI 没有跨进程 compare-and-swap;同机 root/CAP_NET_ADMIN 进程及其他 out-of-band nft 管理器必须遵守维护互斥,不能在平台事务中并发替换同名 table。本验收不宣称抵抗恶意或 不协调的并发特权写入。