diff --git a/agent/hypervisor/capability_checks.go b/agent/hypervisor/capability_checks.go new file mode 100644 index 00000000..e459b542 --- /dev/null +++ b/agent/hypervisor/capability_checks.go @@ -0,0 +1,20 @@ +package hypervisor + +const ( + maxCapabilityNetworkSelectors = 64 + capabilityMissing = "not_configured" + capabilityUnreadable = "not_readable" + capabilityInvalid = "invalid_resource" + capabilityUnavailable = "unavailable" + capabilityInactive = "inactive" + capabilityExhausted = "no_available_capacity" + capabilityUnsupported = "unsupported" + capabilitySelectorMissing = "no_network_selectors" + capabilitySelectorUnusable = "network_selector_unavailable" +) + +func availableCheck() CapabilityCheck { return CapabilityCheck{Available: true} } + +func unavailableCheck(reason string) CapabilityCheck { + return CapabilityCheck{Available: false, Reason: reason} +} diff --git a/agent/hypervisor/libvirt_adapter.go b/agent/hypervisor/libvirt_adapter.go index 92647d4b..aa97e77a 100644 --- a/agent/hypervisor/libvirt_adapter.go +++ b/agent/hypervisor/libvirt_adapter.go @@ -142,6 +142,11 @@ func (l *Libvirt) Capabilities(ctx context.Context) (Capabilities, error) { return Capabilities{}, err } features, checks, networkSelectors := l.probeRuntimeCapabilities() + vpcCapability, vpcChecks := probeVPCL3Capability() + for name, check := range vpcChecks { + checks[name] = check + } + features.VPCL3 = vpcCapability.ApplySupported peerCapability, peerCheck := l.peerMigrationCapability(features.Backups) checks["peer_migration"] = peerCheck features.PeerMigration = peerCapability != nil @@ -159,6 +164,7 @@ func (l *Libvirt) Capabilities(ctx context.Context) (Capabilities, error) { Features: features, PowerActions: powerActions, Firmware: firmware, NetworkSelectors: networkSelectors, Checks: checks, PeerMigration: peerCapability, + VPCL3: vpcCapability, }, nil } diff --git a/agent/hypervisor/libvirt_capabilities.go b/agent/hypervisor/libvirt_capabilities.go index bb55196b..d644c15a 100644 --- a/agent/hypervisor/libvirt_capabilities.go +++ b/agent/hypervisor/libvirt_capabilities.go @@ -15,19 +15,6 @@ import ( "libvirt.org/go/libvirtxml" ) -const ( - maxCapabilityNetworkSelectors = 64 - capabilityMissing = "not_configured" - capabilityUnreadable = "not_readable" - capabilityInvalid = "invalid_resource" - capabilityUnavailable = "unavailable" - capabilityInactive = "inactive" - capabilityExhausted = "no_available_capacity" - capabilityUnsupported = "unsupported" - capabilitySelectorMissing = "no_network_selectors" - capabilitySelectorUnusable = "network_selector_unavailable" -) - type capabilityPrerequisites struct { firmwareLoader bool nvramTemplate bool @@ -169,12 +156,6 @@ func probeStoragePoolHandle(pool storagePoolReader, binding storagePoolBinding) return availableCheck() } -func availableCheck() CapabilityCheck { return CapabilityCheck{Available: true} } - -func unavailableCheck(reason string) CapabilityCheck { - return CapabilityCheck{Available: false, Reason: reason} -} - func probeReadableRegularFile(path string) CapabilityCheck { if strings.TrimSpace(path) == "" { return unavailableCheck(capabilityMissing) diff --git a/agent/hypervisor/types.go b/agent/hypervisor/types.go index ec830253..5150893d 100644 --- a/agent/hypervisor/types.go +++ b/agent/hypervisor/types.go @@ -73,6 +73,7 @@ type FeatureSet struct { UEFI bool `json:"uefi"` SecureBoot bool `json:"secure_boot"` PeerMigration bool `json:"peer_migration"` + VPCL3 bool `json:"vpc_l3"` } type PeerMigrationCapability struct { @@ -83,6 +84,25 @@ type PeerMigrationCapability struct { ChunkSize int64 `json:"chunk_size_bytes"` } +// VPCTransportCandidate is bounded, non-secret host evidence presented only +// to an authenticated administrator. The panel remains the configuration +// authority and the Agent never chooses a transport address on its own. +type VPCTransportCandidate struct { + AddressCIDR string `json:"address_cidr"` + Address string `json:"address"` + Prefix uint8 `json:"prefix_length"` + Interface string `json:"interface"` + MTU int `json:"mtu"` + Bridge bool `json:"is_bridge"` +} + +type VPCL3Capability struct { + Version uint64 `json:"version"` + ApplySupported bool `json:"apply_supported"` + IPv4Forwarding bool `json:"ipv4_forwarding"` + Candidates []VPCTransportCandidate `json:"transport_candidates"` +} + type Capabilities struct { Backend string `json:"backend"` LibvirtVersion string `json:"libvirt_version,omitempty"` @@ -93,6 +113,7 @@ type Capabilities struct { NetworkSelectors []string `json:"network_selectors"` Checks map[string]CapabilityCheck `json:"checks,omitempty"` PeerMigration *PeerMigrationCapability `json:"peer_migration,omitempty"` + VPCL3 *VPCL3Capability `json:"vpc_l3,omitempty"` } // CapabilityCheck exposes bounded, non-sensitive runtime evidence for a diff --git a/agent/hypervisor/types_test.go b/agent/hypervisor/types_test.go index 458ef61d..c16ed874 100644 --- a/agent/hypervisor/types_test.go +++ b/agent/hypervisor/types_test.go @@ -20,6 +20,7 @@ func TestFeatureSetWireContract(t *testing.T) { "create_vm", "delete_vm", "power", "resources", "settings", "network", "reinstall", "snapshots", "backups", "firewall", "rescue", "metrics", "console", "templates", "user_iso", "uefi", "secure_boot", "peer_migration", + "vpc_l3", } if len(wire) != len(expected) { t.Fatalf("FeatureSet wire keys = %v, want exactly %v", wire, expected) @@ -31,6 +32,36 @@ func TestFeatureSetWireContract(t *testing.T) { } } +func TestVPCL3CapabilityWireContract(t *testing.T) { + encoded, err := json.Marshal(VPCL3Capability{ + Version: 1, ApplySupported: false, IPv4Forwarding: true, + Candidates: []VPCTransportCandidate{{ + AddressCIDR: "172.16.0.11/24", Address: "172.16.0.11", + Prefix: 24, Interface: "br-private", MTU: 1500, Bridge: true, + }}, + }) + if err != nil { + t.Fatalf("marshal VPC capability: %v", err) + } + var wire map[string]any + if err := json.Unmarshal(encoded, &wire); err != nil { + t.Fatalf("decode VPC capability: %v", err) + } + if wire["version"] != float64(1) || wire["apply_supported"] != false || + wire["ipv4_forwarding"] != true { + t.Fatalf("VPC capability header = %#v", wire) + } + rows, ok := wire["transport_candidates"].([]any) + if !ok || len(rows) != 1 { + t.Fatalf("VPC transport candidates = %#v", wire["transport_candidates"]) + } + row, ok := rows[0].(map[string]any) + if !ok || row["address_cidr"] != "172.16.0.11/24" || + row["interface"] != "br-private" || row["is_bridge"] != true { + t.Fatalf("VPC transport candidate = %#v", rows[0]) + } +} + func TestPeerMigrationCapabilityAndStateWireContracts(t *testing.T) { encoded, err := json.Marshal(PeerMigrationCapability{ Version: 3, Endpoints: []string{"https://192.0.2.10:9443"}, diff --git a/agent/hypervisor/vpc_capability.go b/agent/hypervisor/vpc_capability.go new file mode 100644 index 00000000..29bd8b16 --- /dev/null +++ b/agent/hypervisor/vpc_capability.go @@ -0,0 +1,123 @@ +package hypervisor + +import ( + "net" + "net/netip" + "os" + "path/filepath" + "regexp" + "sort" + "strings" +) + +const ( + vpcL3CapabilityVersion = uint64(1) + maxVPCTransportCandidates = 64 + vpcNoTransportCandidates = "no_private_transport_addresses" + vpcIPv4ForwardingDisabled = "ipv4_forwarding_disabled" + vpcL3ImplementationDisabled = "vpc_l3_apply_unavailable" +) + +var vpcTransportInterfacePattern = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9_.-]{0,14}$`) + +type vpcInterfaceSnapshot struct { + Name string + Flags net.Flags + MTU int + Addresses []string + Bridge bool +} + +func probeVPCL3Capability() (*VPCL3Capability, map[string]CapabilityCheck) { + candidates, candidatesCheck := discoverVPCTransportCandidates() + forwardingCheck := probeIPv4Forwarding("/proc/sys/net/ipv4/ip_forward") + return &VPCL3Capability{ + Version: vpcL3CapabilityVersion, ApplySupported: false, + IPv4Forwarding: forwardingCheck.Available, + Candidates: candidates, + }, map[string]CapabilityCheck{ + "vpc_transport_candidates": candidatesCheck, + "vpc_ipv4_forwarding": forwardingCheck, + "vpc_l3_apply": unavailableCheck(vpcL3ImplementationDisabled), + } +} + +func discoverVPCTransportCandidates() ([]VPCTransportCandidate, CapabilityCheck) { + interfaces, err := net.Interfaces() + if err != nil { + return []VPCTransportCandidate{}, unavailableCheck(capabilityUnavailable) + } + snapshots := make([]vpcInterfaceSnapshot, 0, len(interfaces)) + for _, device := range interfaces { + addresses, addressErr := device.Addrs() + if addressErr != nil { + continue + } + values := make([]string, 0, len(addresses)) + for _, address := range addresses { + values = append(values, address.String()) + } + info, statErr := os.Stat(filepath.Join("/sys/class/net", device.Name, "bridge")) + snapshots = append(snapshots, vpcInterfaceSnapshot{ + Name: device.Name, Flags: device.Flags, MTU: device.MTU, + Addresses: values, Bridge: statErr == nil && info.IsDir(), + }) + } + return normalizeVPCTransportCandidates(snapshots) +} + +func normalizeVPCTransportCandidates( + snapshots []vpcInterfaceSnapshot, +) ([]VPCTransportCandidate, CapabilityCheck) { + candidates := make([]VPCTransportCandidate, 0) + seen := make(map[string]struct{}) + for _, device := range snapshots { + if device.Flags&net.FlagUp == 0 || device.Flags&net.FlagLoopback != 0 || + !vpcTransportInterfacePattern.MatchString(device.Name) || + device.MTU < 576 || device.MTU > 65535 { + continue + } + for _, raw := range device.Addresses { + prefix, err := netip.ParsePrefix(strings.TrimSpace(raw)) + if err != nil || !prefix.Addr().Is4() || !prefix.Addr().IsPrivate() || + prefix.Addr().IsLoopback() || prefix.Addr().IsLinkLocalUnicast() || + prefix.Addr().IsUnspecified() || prefix.Addr().IsMulticast() { + continue + } + key := device.Name + "\x00" + prefix.String() + if _, exists := seen[key]; exists { + continue + } + seen[key] = struct{}{} + candidates = append(candidates, VPCTransportCandidate{ + AddressCIDR: prefix.String(), Address: prefix.Addr().String(), + Prefix: uint8(prefix.Bits()), Interface: device.Name, + MTU: device.MTU, Bridge: device.Bridge, + }) + } + } + if len(candidates) > maxVPCTransportCandidates { + return []VPCTransportCandidate{}, unavailableCheck(capabilityInvalid) + } + sort.Slice(candidates, func(left, right int) bool { + if candidates[left].Interface != candidates[right].Interface { + return candidates[left].Interface < candidates[right].Interface + } + return candidates[left].AddressCIDR < candidates[right].AddressCIDR + }) + if len(candidates) == 0 { + return candidates, unavailableCheck(vpcNoTransportCandidates) + } + return candidates, availableCheck() +} + +func probeIPv4Forwarding(path string) CapabilityCheck { + raw, err := os.ReadFile(path) + if err != nil { + return unavailableCheck(capabilityUnreadable) + } + if strings.TrimSpace(string(raw)) != "1" { + return unavailableCheck(vpcIPv4ForwardingDisabled) + } + return availableCheck() +} diff --git a/agent/hypervisor/vpc_capability_test.go b/agent/hypervisor/vpc_capability_test.go new file mode 100644 index 00000000..88906f35 --- /dev/null +++ b/agent/hypervisor/vpc_capability_test.go @@ -0,0 +1,83 @@ +package hypervisor + +import ( + "net" + "os" + "reflect" + "strconv" + "testing" +) + +func TestNormalizeVPCTransportCandidates(t *testing.T) { + candidates, check := normalizeVPCTransportCandidates([]vpcInterfaceSnapshot{ + {Name: "lo", Flags: net.FlagUp | net.FlagLoopback, MTU: 65536, + Addresses: []string{"127.0.0.1/8"}}, + {Name: "br-private", Flags: net.FlagUp | net.FlagBroadcast, MTU: 1500, + Addresses: []string{ + "172.16.0.11/24", "172.16.0.11/24", "203.0.113.5/24", "fe80::1/64", + }, Bridge: true}, + {Name: "bond0", Flags: net.FlagUp, MTU: 9000, + Addresses: []string{"10.20.30.40/16"}}, + {Name: "down0", Flags: 0, MTU: 1500, + Addresses: []string{"192.168.1.2/24"}}, + }) + if !check.Available { + t.Fatalf("private candidates rejected: %#v", check) + } + want := []VPCTransportCandidate{ + {AddressCIDR: "10.20.30.40/16", Address: "10.20.30.40", Prefix: 16, + Interface: "bond0", MTU: 9000, Bridge: false}, + {AddressCIDR: "172.16.0.11/24", Address: "172.16.0.11", Prefix: 24, + Interface: "br-private", MTU: 1500, Bridge: true}, + } + if !reflect.DeepEqual(candidates, want) { + t.Fatalf("private candidates = %#v, want %#v", candidates, want) + } +} + +func TestVPCTransportCandidatesFailClosed(t *testing.T) { + candidates, check := normalizeVPCTransportCandidates([]vpcInterfaceSnapshot{{ + Name: "eth0", Flags: net.FlagUp, MTU: 1500, + Addresses: []string{"203.0.113.5/24"}, + }}) + if check.Available || check.Reason != vpcNoTransportCandidates || len(candidates) != 0 { + t.Fatalf("public-only candidate result = %#v, %#v", candidates, check) + } + + many := make([]vpcInterfaceSnapshot, 0, maxVPCTransportCandidates+1) + for index := 0; index <= maxVPCTransportCandidates; index++ { + many = append(many, vpcInterfaceSnapshot{ + Name: "br0", Flags: net.FlagUp, MTU: 1500, + Addresses: []string{privateTestCIDR(index)}, Bridge: true, + }) + } + candidates, check = normalizeVPCTransportCandidates(many) + if check.Available || check.Reason != capabilityInvalid || len(candidates) != 0 { + t.Fatalf("oversized candidate result = %#v, %#v", candidates, check) + } +} + +func TestProbeIPv4Forwarding(t *testing.T) { + path := t.TempDir() + "/ip_forward" + if err := os.WriteFile(path, []byte("0\n"), 0o600); err != nil { + t.Fatal(err) + } + if check := probeIPv4Forwarding(path); check.Available || + check.Reason != vpcIPv4ForwardingDisabled { + t.Fatalf("disabled forwarding check = %#v", check) + } + if err := os.WriteFile(path, []byte("1\n"), 0o600); err != nil { + t.Fatal(err) + } + if check := probeIPv4Forwarding(path); !check.Available || check.Reason != "" { + t.Fatalf("enabled forwarding check = %#v", check) + } + if check := probeIPv4Forwarding(path + "-missing"); check.Available || + check.Reason != capabilityUnreadable { + t.Fatalf("missing forwarding check = %#v", check) + } +} + +func privateTestCIDR(index int) string { + return "10.0." + strconv.Itoa(index) + ".1/24" +} diff --git a/docs/AGENT_API.md b/docs/AGENT_API.md index f3436617..b4cdbe52 100644 --- a/docs/AGENT_API.md +++ b/docs/AGENT_API.md @@ -144,7 +144,7 @@ Go context 无法可靠中止已进入 CGo/libvirt 的调用。父 Agent 到达 | Method | Path | 用途 | | --- | --- | --- | | GET | `/v1/health` | 进程、Journal 和 libvirt 连接健康 | -| GET | `/v1/capabilities` | 版本、固件、网络和可选能力 | +| GET | `/v1/capabilities` | 版本、固件、网络、VPC L3 前置条件和可选能力 | | GET/POST | `/v1/vms` | 列表 / 创建 VM | | GET/DELETE | `/v1/vms/{uuid}` | 元数据 / 正常关机后删除 | | GET | `/v1/vms/{uuid}/state` | 当前电源观察 | diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md index c2b5f032..df465e54 100644 --- a/docs/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -152,6 +152,8 @@ libvirt 的持久 pool 定义就是 Agent 后续使用的映射,不另写存 Agent 的 capabilities 响应仍使用 `network_selectors` 字段,但它是自动发现的当前可用 `bridge:<名称>` / `network:<名称>` 列表,排序去重且最多 64 项,不再来自配置文件。Linux 网桥必须有 sysfs bridge 目录且接口为 UP;libvirt network 必须处于 active 状态。面板要求 `default_network` 精确匹配列表中的一项;每次创建或换网也会单独重验本次选中的网络。修改面板网络接入后,旧就绪结果立即失效,必须回到“Agent API”重新测试。 +`capabilities.vpc_l3` 只报告 VPC L3 前置条件和候选传输地址,不替代面板配置。Agent 从处于 UP 状态的接口中筛选 RFC1918 IPv4 地址,排序去重并限制为最多 64 项;每项包含 CIDR、接口、MTU 和是否为 Linux bridge。`ipv4_forwarding` 只反映当前 `/proc/sys/net/ipv4/ip_forward`,Agent 不会为能力探测修改 sysctl。管理员后续必须在计算节点页面明确选择一个候选地址;`apply_supported=false` 时即使发现了候选地址也不得启用 VPC 调度。 + 本版本只面向全新部署,不读取旧 `public` alias、旧网络映射或旧就绪记录。部署时必须直接填写真实的 `bridge:` 或 `network:`;不要复制旧 Agent 配置,也不要把旧数据库导入当前 schema。 Agent 的 systemd 样例与当前宿主机部署保持一致:以 root 运行 `/home/agent/virt-agent -config /home/agent/config.json`,不设置 `ProtectSystem`、`ProtectHome`、`ReadWritePaths` 或 `StateDirectory`。这是因为 Agent 除了写入 `journal_path`,还需要在第一个 `storage_path_roots` 中维护 PeerMigration 暂存文件,并可能清理 `nvram_directory` 中由面板管理的 UUID 专属 VARS 文件。配置文件仍应保持 root 所有和 `0600` 权限,运行目录不应存放其他可执行或可写入的非 Agent 内容。若运维自行增加 systemd 沙箱,必须精确放行上述实际目录,并分别完成 Agent 启动、迁移接收、失败清理和 NVRAM 删除验收。