feat(agent): report VPC transport capabilities

go
codex 3 weeks ago
parent 54dcecd516
commit 6c2ab95f27

@ -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}
}

@ -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
}

@ -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)

@ -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

@ -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"},

@ -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()
}

@ -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"
}

@ -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` | 当前电源观察 |

@ -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:<name>` 或 `network:<name>`;不要复制旧 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 删除验收。

Loading…
Cancel
Save