From 73617011e70d5cc5224eb584d4f81a3885b9fc22 Mon Sep 17 00:00:00 2001 From: Peter Sprygada Date: Thu, 19 Nov 2026 05:35:49 -0500 Subject: [PATCH 1/5] feat(worker): Add the Local delivery module Worker resolved destinations on this node to Local but had no module to program them, so every local.* capability reported ModuleNotRunning. Add the Local module (internal/worker/local) and register it next to Fabric. - Programs: local_rx delivers a public packet a dispatcher slot marks with galactic_local_meta to the TAP it names; local_link_rx returns a local.tap reply out of the device the flow arrived on, or sends a flow into the VPC's service-internal veth pair; local_pair_rx delivers the pair's return; local_link_guard drops a routed link source the link was not given. Each decides the receiver's policy on its own path and sets the decided mark; an unauthorized target is dropped, as are IPv6 fragments and packets above the target's MTU. - Lifecycle: tc filters sit after galactic-cni's under its interface lock. The module creates and deletes the pairs and routed links it owns, keeps CNI's interfaces, and reprograms after an ifindex change. A routed link's pod end goes only into the owner's authenticated pod. - Readiness checks the hooks, a live public dispatcher slot, native XDP on the NAT end, interface kind, carrier, MTU and failed neighbors, forward and return separately. - Uplink discovery skips every link Galactic creates per VPC. - API: ClaimStatus gains handoff_interfaces; claims record the owner's pod, which a duplicate Request from a new pod updates. Privileged tests cover every entry path (plain, VLAN and bond, native and generic XDP), policy denials, untrusted entry, hook removal and repair, a cold neighbor, ifindex replacement, partial checksums, routed links and withdrawal. --- .gitignore | 8 + Taskfile.yaml | 3 +- api/galactic/worker/v1alpha1/contract.go | 23 + api/galactic/worker/v1alpha1/worker.pb.go | 137 ++- api/galactic/worker/v1alpha1/worker.proto | 19 + cmd/galactic-worker/root.go | 24 +- internal/plumbing/ebpf/attach/interfaces.go | 25 +- internal/plumbing/ebpf/attach/internal.go | 28 + .../plumbing/ebpf/attach/internal_test.go | 109 +++ internal/plumbing/ebpf/attach/local.go | 147 +++ .../ebpf/egressroutemap/egressroute.go | 10 + internal/plumbing/ebpf/localprog/doc.go | 16 + internal/plumbing/ebpf/localprog/load.go | 196 ++++ .../plumbing/ebpf/localprog/load_root_test.go | 66 ++ internal/plumbing/ebpf/localprog/local.c | 549 ++++++++++++ internal/plumbing/ebpf/localprog/local_meta.h | 28 + .../ebpf/localprog/localfixture/doc.go | 11 + .../ebpf/localprog/localfixture/fixture.c | 289 ++++++ internal/plumbing/ebpf/xdpdispatch/inspect.go | 184 ++++ .../plumbing/ebpf/xdpdispatch/inspect_test.go | 24 + internal/plumbing/intf/intf.go | 40 + internal/worker/claims.go | 31 +- internal/worker/handoff_test.go | 105 +++ internal/worker/harness_test.go | 8 +- internal/worker/local/ensure.go | 365 ++++++++ internal/worker/local/frames_test.go | 173 ++++ internal/worker/local/kernel.go | 644 +++++++++++++ internal/worker/local/kernel_root_test.go | 136 +++ internal/worker/local/lifecycle_root_test.go | 586 ++++++++++++ internal/worker/local/local.go | 236 +++++ internal/worker/local/model.go | 183 ++++ internal/worker/local/model_test.go | 84 ++ internal/worker/local/podns.go | 122 +++ internal/worker/local/podns_root_test.go | 45 + internal/worker/local/podns_test.go | 73 ++ internal/worker/local/read.go | 414 +++++++++ internal/worker/local/rig_root_test.go | 843 ++++++++++++++++++ internal/worker/local/routed.go | 155 ++++ internal/worker/local/watch.go | 113 +++ internal/worker/module/module.go | 27 + internal/worker/reconcile.go | 24 +- internal/worker/sources/sources.go | 7 +- internal/worker/store/store.go | 3 + scripts/required-ci.sh | 2 +- 44 files changed, 6279 insertions(+), 36 deletions(-) create mode 100644 internal/plumbing/ebpf/attach/internal.go create mode 100644 internal/plumbing/ebpf/attach/internal_test.go create mode 100644 internal/plumbing/ebpf/attach/local.go create mode 100644 internal/plumbing/ebpf/localprog/doc.go create mode 100644 internal/plumbing/ebpf/localprog/load.go create mode 100644 internal/plumbing/ebpf/localprog/load_root_test.go create mode 100644 internal/plumbing/ebpf/localprog/local.c create mode 100644 internal/plumbing/ebpf/localprog/local_meta.h create mode 100644 internal/plumbing/ebpf/localprog/localfixture/doc.go create mode 100644 internal/plumbing/ebpf/localprog/localfixture/fixture.c create mode 100644 internal/plumbing/ebpf/xdpdispatch/inspect.go create mode 100644 internal/plumbing/ebpf/xdpdispatch/inspect_test.go create mode 100644 internal/worker/handoff_test.go create mode 100644 internal/worker/local/ensure.go create mode 100644 internal/worker/local/frames_test.go create mode 100644 internal/worker/local/kernel.go create mode 100644 internal/worker/local/kernel_root_test.go create mode 100644 internal/worker/local/lifecycle_root_test.go create mode 100644 internal/worker/local/local.go create mode 100644 internal/worker/local/model.go create mode 100644 internal/worker/local/model_test.go create mode 100644 internal/worker/local/podns.go create mode 100644 internal/worker/local/podns_root_test.go create mode 100644 internal/worker/local/podns_test.go create mode 100644 internal/worker/local/read.go create mode 100644 internal/worker/local/rig_root_test.go create mode 100644 internal/worker/local/routed.go create mode 100644 internal/worker/local/watch.go diff --git a/.gitignore b/.gitignore index a5348439..828d0080 100644 --- a/.gitignore +++ b/.gitignore @@ -62,6 +62,14 @@ internal/plumbing/ebpf/xmitdrops/xmitdrops_bpfel.go internal/plumbing/ebpf/xmitdrops/xmitdrops_bpfel.o internal/plumbing/ebpf/xmitdrops/xmitdrops_bpfeb.go internal/plumbing/ebpf/xmitdrops/xmitdrops_bpfeb.o +internal/plumbing/ebpf/localprog/local_bpfel.go +internal/plumbing/ebpf/localprog/local_bpfel.o +internal/plumbing/ebpf/localprog/local_bpfeb.go +internal/plumbing/ebpf/localprog/local_bpfeb.o +internal/plumbing/ebpf/localprog/localfixture/fixture_bpfel.go +internal/plumbing/ebpf/localprog/localfixture/fixture_bpfel.o +internal/plumbing/ebpf/localprog/localfixture/fixture_bpfeb.go +internal/plumbing/ebpf/localprog/localfixture/fixture_bpfeb.o tests/handoffs/probe/handoff_bpfel.go tests/handoffs/probe/handoff_bpfel.o tests/handoffs/probe/handoff_bpfeb.go diff --git a/Taskfile.yaml b/Taskfile.yaml index 46982680..68f5f2c7 100644 --- a/Taskfile.yaml +++ b/Taskfile.yaml @@ -122,7 +122,7 @@ tasks: cmds: - python3 hack/docs/generate_api.py --check build:ebpf: - desc: Regenerate the eBPF uSID, edge gateway DSR, NAT egress, XDP dispatcher, XDP transmit drop and Local handoff probe programs (requires clang) + desc: Regenerate the eBPF uSID, edge gateway DSR, NAT egress, XDP dispatcher, XDP transmit drop, Local handoff and Local handoff probe programs (requires clang) run: once deps: [require-clang] cmds: @@ -131,6 +131,7 @@ tasks: - go generate ./internal/plumbing/ebpf/natprog/... - go generate ./internal/plumbing/ebpf/xdpdispatch/... - go generate ./internal/plumbing/ebpf/xmitdrops/... + - go generate ./internal/plumbing/ebpf/localprog/... - go generate ./tests/handoffs/probe/... require-clang: internal: true diff --git a/api/galactic/worker/v1alpha1/contract.go b/api/galactic/worker/v1alpha1/contract.go index 333d20b6..523e17e7 100644 --- a/api/galactic/worker/v1alpha1/contract.go +++ b/api/galactic/worker/v1alpha1/contract.go @@ -139,6 +139,29 @@ const ( // ReasonReturnPathNotProgrammed is a destination whose return traffic // this node cannot yet decapsulate into the VPC's table. ReasonReturnPathNotProgrammed = "ReturnPathNotProgrammed" + // ReasonHandoffHookMissing is a Local destination whose handoff program + // is not on its hook: Worker's own tc program, or the program the + // client attaches to the NAT end of a veth pair. + ReasonHandoffHookMissing = "HandoffHookMissing" + // ReasonDispatcherSlotUnclaimed is a local.tap destination with no + // receiving device whose XDP dispatcher runs a live public slot. + ReasonDispatcherSlotUnclaimed = "DispatcherSlotUnclaimed" + // ReasonHandoffMTUTooSmall is a Local destination whose interface's MTU + // is below the receiving path's, so a packet the path carries would + // not reach the guest. + ReasonHandoffMTUTooSmall = "HandoffMTUTooSmall" +) + +// Handoff interface roles, carried in HandoffInterface. +const ( + // HandoffRoleNAT is the NAT end of a service-internal veth pair. + HandoffRoleNAT = "nat" + // HandoffRoleTenant is the tenant end of a service-internal veth pair. + HandoffRoleTenant = "tenant" + // HandoffRoleHost is the host end of a routed link. + HandoffRoleHost = "host" + // HandoffRolePod is the routed link's end in the caller's pod. + HandoffRolePod = "pod" ) // Route rejection reasons, carried in RejectedRoute. diff --git a/api/galactic/worker/v1alpha1/worker.pb.go b/api/galactic/worker/v1alpha1/worker.pb.go index 95f9024a..428afdd3 100644 --- a/api/galactic/worker/v1alpha1/worker.pb.go +++ b/api/galactic/worker/v1alpha1/worker.pb.go @@ -1509,9 +1509,15 @@ type ClaimStatus struct { // confirmed. Released bool `protobuf:"varint,7,opt,name=released,proto3" json:"released,omitempty"` // revision increases with every snapshot Worker produces for the claim. - Revision uint64 `protobuf:"varint,8,opt,name=revision,proto3" json:"revision,omitempty"` - unknownFields protoimpl.UnknownFields - sizeCache protoimpl.SizeCache + Revision uint64 `protobuf:"varint,8,opt,name=revision,proto3" json:"revision,omitempty"` + // handoff_interfaces are the interfaces Worker created for the claim's + // handoff, which the client attaches its own program to or configures: + // the NAT end of a veth_pair claim's service-internal veth pair, and both + // ends of a routed_link or socket claim's routed link. A tap claim has + // none. Each is listed once Worker has created it. + HandoffInterfaces []*HandoffInterface `protobuf:"bytes,9,rep,name=handoff_interfaces,json=handoffInterfaces,proto3" json:"handoff_interfaces,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache } func (x *ClaimStatus) Reset() { @@ -1600,6 +1606,80 @@ func (x *ClaimStatus) GetRevision() uint64 { return 0 } +func (x *ClaimStatus) GetHandoffInterfaces() []*HandoffInterface { + if x != nil { + return x.HandoffInterfaces + } + return nil +} + +// HandoffInterface is one interface Worker created for a claim's handoff. +type HandoffInterface struct { + state protoimpl.MessageState `protogen:"open.v1"` + // role is "nat" for the NAT end of a veth pair, in the host's network + // namespace; "tenant" for the pair's tenant end, in the VPC's VRF; "host" + // for a routed link's host end, in the VPC's VRF; or "pod" for the routed + // link's end in the caller's pod, which the pod configures. + Role string `protobuf:"bytes,1,opt,name=role,proto3" json:"role,omitempty"` + // name is the interface name in its network namespace. + Name string `protobuf:"bytes,2,opt,name=name,proto3" json:"name,omitempty"` + // ifindex is the interface index in its network namespace. + Ifindex int32 `protobuf:"varint,3,opt,name=ifindex,proto3" json:"ifindex,omitempty"` + unknownFields protoimpl.UnknownFields + sizeCache protoimpl.SizeCache +} + +func (x *HandoffInterface) Reset() { + *x = HandoffInterface{} + mi := &file_galactic_worker_v1alpha1_worker_proto_msgTypes[20] + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + ms.StoreMessageInfo(mi) +} + +func (x *HandoffInterface) String() string { + return protoimpl.X.MessageStringOf(x) +} + +func (*HandoffInterface) ProtoMessage() {} + +func (x *HandoffInterface) ProtoReflect() protoreflect.Message { + mi := &file_galactic_worker_v1alpha1_worker_proto_msgTypes[20] + if x != nil { + ms := protoimpl.X.MessageStateOf(protoimpl.Pointer(x)) + if ms.LoadMessageInfo() == nil { + ms.StoreMessageInfo(mi) + } + return ms + } + return mi.MessageOf(x) +} + +// Deprecated: Use HandoffInterface.ProtoReflect.Descriptor instead. +func (*HandoffInterface) Descriptor() ([]byte, []int) { + return file_galactic_worker_v1alpha1_worker_proto_rawDescGZIP(), []int{20} +} + +func (x *HandoffInterface) GetRole() string { + if x != nil { + return x.Role + } + return "" +} + +func (x *HandoffInterface) GetName() string { + if x != nil { + return x.Name + } + return "" +} + +func (x *HandoffInterface) GetIfindex() int32 { + if x != nil { + return x.Ifindex + } + return 0 +} + var File_galactic_worker_v1alpha1_worker_proto protoreflect.FileDescriptor const file_galactic_worker_v1alpha1_worker_proto_rawDesc = "" + @@ -1689,7 +1769,7 @@ const file_galactic_worker_v1alpha1_worker_proto_rawDesc = "" + "\x06reason\x18\x06 \x01(\tR\x06reason\x12\x18\n" + "\amessage\x18\a \x01(\tR\amessage\x12#\n" + "\rforward_ready\x18\b \x01(\bR\fforwardReady\x12!\n" + - "\freturn_ready\x18\t \x01(\bR\vreturnReady\"\xb8\x03\n" + + "\freturn_ready\x18\t \x01(\bR\vreturnReady\"\x93\x04\n" + "\vClaimStatus\x124\n" + "\x03key\x18\x01 \x01(\v2\".galactic.worker.v1alpha1.ClaimKeyR\x03key\x12\x1e\n" + "\n" + @@ -1702,7 +1782,12 @@ const file_galactic_worker_v1alpha1_worker_proto_rawDesc = "" + "\fdestinations\x18\x05 \x03(\v2+.galactic.worker.v1alpha1.DestinationStatusR\fdestinations\x12T\n" + "\x10withdrawal_scope\x18\x06 \x01(\x0e2).galactic.worker.v1alpha1.WithdrawalScopeR\x0fwithdrawalScope\x12\x1a\n" + "\breleased\x18\a \x01(\bR\breleased\x12\x1a\n" + - "\brevision\x18\b \x01(\x04R\brevision*u\n" + + "\brevision\x18\b \x01(\x04R\brevision\x12Y\n" + + "\x12handoff_interfaces\x18\t \x03(\v2*.galactic.worker.v1alpha1.HandoffInterfaceR\x11handoffInterfaces\"T\n" + + "\x10HandoffInterface\x12\x12\n" + + "\x04role\x18\x01 \x01(\tR\x04role\x12\x12\n" + + "\x04name\x18\x02 \x01(\tR\x04name\x12\x18\n" + + "\aifindex\x18\x03 \x01(\x05R\aifindex*u\n" + "\x0fCapabilityState\x12 \n" + "\x1cCAPABILITY_STATE_UNSPECIFIED\x10\x00\x12\x1e\n" + "\x1aCAPABILITY_STATE_AVAILABLE\x10\x01\x12 \n" + @@ -1750,7 +1835,7 @@ func file_galactic_worker_v1alpha1_worker_proto_rawDescGZIP() []byte { } var file_galactic_worker_v1alpha1_worker_proto_enumTypes = make([]protoimpl.EnumInfo, 5) -var file_galactic_worker_v1alpha1_worker_proto_msgTypes = make([]protoimpl.MessageInfo, 20) +var file_galactic_worker_v1alpha1_worker_proto_msgTypes = make([]protoimpl.MessageInfo, 21) var file_galactic_worker_v1alpha1_worker_proto_goTypes = []any{ (CapabilityState)(0), // 0: galactic.worker.v1alpha1.CapabilityState (Handoff)(0), // 1: galactic.worker.v1alpha1.Handoff @@ -1777,11 +1862,12 @@ var file_galactic_worker_v1alpha1_worker_proto_goTypes = []any{ (*Condition)(nil), // 22: galactic.worker.v1alpha1.Condition (*DestinationStatus)(nil), // 23: galactic.worker.v1alpha1.DestinationStatus (*ClaimStatus)(nil), // 24: galactic.worker.v1alpha1.ClaimStatus - (*durationpb.Duration)(nil), // 25: google.protobuf.Duration + (*HandoffInterface)(nil), // 25: galactic.worker.v1alpha1.HandoffInterface + (*durationpb.Duration)(nil), // 26: google.protobuf.Duration } var file_galactic_worker_v1alpha1_worker_proto_depIdxs = []int32{ - 25, // 0: galactic.worker.v1alpha1.GetCapabilitiesResponse.lease:type_name -> google.protobuf.Duration - 25, // 1: galactic.worker.v1alpha1.GetCapabilitiesResponse.renew_interval:type_name -> google.protobuf.Duration + 26, // 0: galactic.worker.v1alpha1.GetCapabilitiesResponse.lease:type_name -> google.protobuf.Duration + 26, // 1: galactic.worker.v1alpha1.GetCapabilitiesResponse.renew_interval:type_name -> google.protobuf.Duration 7, // 2: galactic.worker.v1alpha1.GetCapabilitiesResponse.capabilities:type_name -> galactic.worker.v1alpha1.Capability 0, // 3: galactic.worker.v1alpha1.Capability.state:type_name -> galactic.worker.v1alpha1.CapabilityState 9, // 4: galactic.worker.v1alpha1.Destination.attachment:type_name -> galactic.worker.v1alpha1.AttachmentRef @@ -1807,21 +1893,22 @@ var file_galactic_worker_v1alpha1_worker_proto_depIdxs = []int32{ 22, // 24: galactic.worker.v1alpha1.ClaimStatus.conditions:type_name -> galactic.worker.v1alpha1.Condition 23, // 25: galactic.worker.v1alpha1.ClaimStatus.destinations:type_name -> galactic.worker.v1alpha1.DestinationStatus 4, // 26: galactic.worker.v1alpha1.ClaimStatus.withdrawal_scope:type_name -> galactic.worker.v1alpha1.WithdrawalScope - 5, // 27: galactic.worker.v1alpha1.Worker.GetCapabilities:input_type -> galactic.worker.v1alpha1.GetCapabilitiesRequest - 14, // 28: galactic.worker.v1alpha1.Worker.Request:input_type -> galactic.worker.v1alpha1.RequestRequest - 16, // 29: galactic.worker.v1alpha1.Worker.Update:input_type -> galactic.worker.v1alpha1.UpdateRequest - 20, // 30: galactic.worker.v1alpha1.Worker.Observe:input_type -> galactic.worker.v1alpha1.ObserveRequest - 18, // 31: galactic.worker.v1alpha1.Worker.Release:input_type -> galactic.worker.v1alpha1.ReleaseRequest - 6, // 32: galactic.worker.v1alpha1.Worker.GetCapabilities:output_type -> galactic.worker.v1alpha1.GetCapabilitiesResponse - 15, // 33: galactic.worker.v1alpha1.Worker.Request:output_type -> galactic.worker.v1alpha1.RequestResponse - 17, // 34: galactic.worker.v1alpha1.Worker.Update:output_type -> galactic.worker.v1alpha1.UpdateResponse - 21, // 35: galactic.worker.v1alpha1.Worker.Observe:output_type -> galactic.worker.v1alpha1.ObserveResponse - 19, // 36: galactic.worker.v1alpha1.Worker.Release:output_type -> galactic.worker.v1alpha1.ReleaseResponse - 32, // [32:37] is the sub-list for method output_type - 27, // [27:32] is the sub-list for method input_type - 27, // [27:27] is the sub-list for extension type_name - 27, // [27:27] is the sub-list for extension extendee - 0, // [0:27] is the sub-list for field type_name + 25, // 27: galactic.worker.v1alpha1.ClaimStatus.handoff_interfaces:type_name -> galactic.worker.v1alpha1.HandoffInterface + 5, // 28: galactic.worker.v1alpha1.Worker.GetCapabilities:input_type -> galactic.worker.v1alpha1.GetCapabilitiesRequest + 14, // 29: galactic.worker.v1alpha1.Worker.Request:input_type -> galactic.worker.v1alpha1.RequestRequest + 16, // 30: galactic.worker.v1alpha1.Worker.Update:input_type -> galactic.worker.v1alpha1.UpdateRequest + 20, // 31: galactic.worker.v1alpha1.Worker.Observe:input_type -> galactic.worker.v1alpha1.ObserveRequest + 18, // 32: galactic.worker.v1alpha1.Worker.Release:input_type -> galactic.worker.v1alpha1.ReleaseRequest + 6, // 33: galactic.worker.v1alpha1.Worker.GetCapabilities:output_type -> galactic.worker.v1alpha1.GetCapabilitiesResponse + 15, // 34: galactic.worker.v1alpha1.Worker.Request:output_type -> galactic.worker.v1alpha1.RequestResponse + 17, // 35: galactic.worker.v1alpha1.Worker.Update:output_type -> galactic.worker.v1alpha1.UpdateResponse + 21, // 36: galactic.worker.v1alpha1.Worker.Observe:output_type -> galactic.worker.v1alpha1.ObserveResponse + 19, // 37: galactic.worker.v1alpha1.Worker.Release:output_type -> galactic.worker.v1alpha1.ReleaseResponse + 33, // [33:38] is the sub-list for method output_type + 28, // [28:33] is the sub-list for method input_type + 28, // [28:28] is the sub-list for extension type_name + 28, // [28:28] is the sub-list for extension extendee + 0, // [0:28] is the sub-list for field type_name } func init() { file_galactic_worker_v1alpha1_worker_proto_init() } @@ -1840,7 +1927,7 @@ func file_galactic_worker_v1alpha1_worker_proto_init() { GoPackagePath: reflect.TypeOf(x{}).PkgPath(), RawDescriptor: unsafe.Slice(unsafe.StringData(file_galactic_worker_v1alpha1_worker_proto_rawDesc), len(file_galactic_worker_v1alpha1_worker_proto_rawDesc)), NumEnums: 5, - NumMessages: 20, + NumMessages: 21, NumExtensions: 0, NumServices: 1, }, diff --git a/api/galactic/worker/v1alpha1/worker.proto b/api/galactic/worker/v1alpha1/worker.proto index 46226b9a..57b2cfaf 100644 --- a/api/galactic/worker/v1alpha1/worker.proto +++ b/api/galactic/worker/v1alpha1/worker.proto @@ -257,4 +257,23 @@ message ClaimStatus { bool released = 7; // revision increases with every snapshot Worker produces for the claim. uint64 revision = 8; + // handoff_interfaces are the interfaces Worker created for the claim's + // handoff, which the client attaches its own program to or configures: + // the NAT end of a veth_pair claim's service-internal veth pair, and both + // ends of a routed_link or socket claim's routed link. A tap claim has + // none. Each is listed once Worker has created it. + repeated HandoffInterface handoff_interfaces = 9; +} + +// HandoffInterface is one interface Worker created for a claim's handoff. +message HandoffInterface { + // role is "nat" for the NAT end of a veth pair, in the host's network + // namespace; "tenant" for the pair's tenant end, in the VPC's VRF; "host" + // for a routed link's host end, in the VPC's VRF; or "pod" for the routed + // link's end in the caller's pod, which the pod configures. + string role = 1; + // name is the interface name in its network namespace. + string name = 2; + // ifindex is the interface index in its network namespace. + int32 ifindex = 3; } diff --git a/cmd/galactic-worker/root.go b/cmd/galactic-worker/root.go index 59e167b0..1380f9e9 100644 --- a/cmd/galactic-worker/root.go +++ b/cmd/galactic-worker/root.go @@ -35,10 +35,13 @@ import ( "go.datum.net/galactic/internal/nodelocator" "go.datum.net/galactic/internal/ownership" "go.datum.net/galactic/internal/plumbing/ebpf/attach" + "go.datum.net/galactic/internal/plumbing/ebpf/localprog" + "go.datum.net/galactic/internal/plumbing/ebpf/xdpdispatch" "go.datum.net/galactic/internal/worker" "go.datum.net/galactic/internal/worker/auth" "go.datum.net/galactic/internal/worker/fabric" "go.datum.net/galactic/internal/worker/hostscope" + "go.datum.net/galactic/internal/worker/local" "go.datum.net/galactic/internal/worker/module" "go.datum.net/galactic/internal/worker/routes" "go.datum.net/galactic/internal/worker/sources" @@ -75,6 +78,8 @@ type options struct { claimLimit int resyncInterval time.Duration pinDir string + localPinDir string + dispatchDir string hostGrace time.Duration } @@ -179,8 +184,15 @@ func run(o *options) error { return err } fabric.InitMetrics() + localKernel := &local.Kernel{PinDir: o.pinDir, LocalPinDir: o.localPinDir, DispatchDir: o.dispatchDir, + Pods: &local.ProcPods{ProcRoot: o.procRoot, Pods: auth.CgroupPodResolver{ProcRoot: o.procRoot}}} + defer func() { _ = localKernel.Close() }() + loc, err := local.New(local.Config{Kernel: localKernel, Node: o.nodeName, Log: slog.Default()}) + if err != nil { + return err + } // The delivery modules this build runs. - reg, err := module.NewRegistry(fab) + reg, err := module.NewRegistry(fab, loc) if err != nil { return err } @@ -225,6 +237,13 @@ func run(o *options) error { }); err != nil { return err } + // A receiving device, a pair's NAT end or a failed tenant neighbor + // changing requeues the VPCs whose Local handoffs it touches. + if err := loc.Watch(ctx, w.HostChanged, func(err error) { + slog.Error("Local link and neighbor event subscription failed; relying on periodic resync", "error", err) + }); err != nil { + return err + } mgrErr := make(chan error, 1) go func() { mgrErr <- mgr.Start(ctx) }() @@ -313,6 +332,9 @@ func newRootCommand() *cobra.Command { f.DurationVar(&o.resyncInterval, "resync-interval", worker.DefaultResyncInterval, "How often every VPC scope is reconciled again") f.StringVar(&o.pinDir, "pin-dir", attach.PinDir, "bpffs directory of the pinned uSID maps") + f.StringVar(&o.localPinDir, "local-pin-dir", localprog.PinDir, "bpffs directory of the Local handoff maps") + f.StringVar(&o.dispatchDir, "xdp-dispatch-dir", xdpdispatch.PinDir, + "bpffs directory of the shared XDP dispatcher, read to find public receiving devices") f.DurationVar(&o.hostGrace, "host-grace", worker.DefaultHostGrace, "How long a VPC's host state must go unused before Worker reclaims it") f.Bool("build-info", false, "Print build information and exit") diff --git a/internal/plumbing/ebpf/attach/interfaces.go b/internal/plumbing/ebpf/attach/interfaces.go index 04687093..9c403d53 100644 --- a/internal/plumbing/ebpf/attach/interfaces.go +++ b/internal/plumbing/ebpf/attach/interfaces.go @@ -72,7 +72,7 @@ func ResolveInterfaces() ([]string, error) { // one: a value made only of whitespace is a malformed override, rejected // like one made only of commas, rather than a request to auto-detect. if override := os.Getenv(config.EnvCNIEBPFInterfaces); override != "" { - names = parseInterfaceList(override) + names = withoutInternalLinks(parseInterfaceList(override)) if len(names) == 0 { return nil, fmt.Errorf("attach: %s is set to %q but contains no usable interface names", config.EnvCNIEBPFInterfaces, override) @@ -86,6 +86,23 @@ func ResolveInterfaces() ([]string, error) { return expandBondSlaves(names) } +// withoutInternalLinks drops each override name that resolves to an internal +// link (IsInternalLink), which an operator can name by mistake but is never +// an uplink. A name that does not resolve is kept, as the override has never +// required its interfaces to exist. +func withoutInternalLinks(names []string) []string { + out := names[:0:0] + for _, name := range names { + if link, err := linkByNameFn(name); err == nil && IsInternalLink(link) { + slog.Warn("attach: ignoring an internal Galactic link named as an uplink", + "env", config.EnvCNIEBPFInterfaces, "interface", name) + continue + } + out = append(out, name) + } + return out +} + // DetectUplinks returns the interfaces carrying the IPv6 default route or a // BGP-learned route, in the order and with the exclusions ResolveInterfaces' // auto-detection applies. Unlike ResolveInterfaces it reads no override and @@ -154,6 +171,12 @@ func autoDetectInterfaces() ([]string, error) { if isVRFSlave(link) { return } + // A link Galactic creates for tenant delivery, such as the NAT end + // of a Local veth pair in the host's namespace, can carry a route + // FRR learned over it without ever being an uplink. + if IsInternalLink(link) { + return + } if link.Attrs().Flags&net.FlagLoopback != 0 { return } diff --git a/internal/plumbing/ebpf/attach/internal.go b/internal/plumbing/ebpf/attach/internal.go new file mode 100644 index 00000000..d28f1f04 --- /dev/null +++ b/internal/plumbing/ebpf/attach/internal.go @@ -0,0 +1,28 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package attach + +import ( + "strings" + + "github.com/vishvananda/netlink" + + "go.datum.net/galactic/internal/plumbing/intf" +) + +// InternalAliasPrefix starts the alias of every link Worker's Local module +// creates, such as the NAT end of a service-internal veth pair, which lives +// in the host's namespace outside any VRF. +const InternalAliasPrefix = "galactic-local:" + +// IsInternalLink reports whether link is one Galactic creates for tenant +// delivery and so can never be a node's uplink: a link carrying a Local alias, +// or one named as a CNI attachment, a VPC VRF or a Local link +// (intf.IsGalacticLinkName). Every uplink discovery path skips it, whatever +// routes it carries; a VRF slave is skipped separately (isVRFSlave). +func IsInternalLink(link netlink.Link) bool { + attrs := link.Attrs() + return strings.HasPrefix(attrs.Alias, InternalAliasPrefix) || intf.IsGalacticLinkName(attrs.Name) +} diff --git a/internal/plumbing/ebpf/attach/internal_test.go b/internal/plumbing/ebpf/attach/internal_test.go new file mode 100644 index 00000000..eb0f974c --- /dev/null +++ b/internal/plumbing/ebpf/attach/internal_test.go @@ -0,0 +1,109 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package attach + +import ( + "net" + "testing" + + "github.com/vishvananda/netlink" + "golang.org/x/sys/unix" + + "go.datum.net/galactic/internal/config" +) + +// internalLinks are the links of an uplink discovery fixture: a Local +// pair's NAT end in the host's namespace, a link carrying only a Local alias, +// a CNI host link and VRF that are not enslaved, and the real uplink. +var internalLinks = map[int]netlink.Link{ + 2: &fakeLink{attrs: netlink.LinkAttrs{Index: 2, Name: "G000000080Ob1N", Alias: InternalAliasPrefix + "0000080/n"}, + linkType: "veth"}, + 3: &fakeLink{attrs: netlink.LinkAttrs{Index: 3, Name: "natpeer0", Alias: InternalAliasPrefix + "0000081/n"}, + linkType: "veth"}, + 4: &fakeLink{attrs: netlink.LinkAttrs{Index: 4, Name: "G000000080001H"}, linkType: "tuntap"}, + 5: &fakeLink{attrs: netlink.LinkAttrs{Index: 5, Name: "G000000080V"}, linkType: "vrf"}, + 6: &fakeLink{attrs: netlink.LinkAttrs{Index: 6, Name: testIfaceEth0}}, +} + +func stubInternalLinks(t *testing.T) { + t.Helper() + origByIndex, origByName, origList, origRoutes := linkByIndexFn, linkByNameFn, linkListFn, routeListFn + t.Cleanup(func() { + linkByIndexFn, linkByNameFn, linkListFn, routeListFn = origByIndex, origByName, origList, origRoutes + }) + linkByIndexFn = func(index int) (netlink.Link, error) { + if l, ok := internalLinks[index]; ok { + return l, nil + } + return nil, errFixtureNotFound + } + linkByNameFn = func(name string) (netlink.Link, error) { + for _, l := range internalLinks { + if l.Attrs().Name == name { + return l, nil + } + } + return &fakeLink{attrs: netlink.LinkAttrs{Name: name}}, nil + } + linkListFn = func() ([]netlink.Link, error) { return nil, nil } + // Every internal link carries a default route and a BGP route, as one + // can when FRR learns a route over it, and each is reported before + // the uplink's. + routeListFn = func() ([]netlink.Route, error) { + var out []netlink.Route + for _, idx := range []int{2, 3, 4, 5} { + out = append(out, netlink.Route{LinkIndex: idx}, + netlink.Route{LinkIndex: idx, Protocol: unix.RTPROT_BGP, Dst: mustIPNet(t, "2001:db8:ff::/48")}) + } + return append(out, netlink.Route{LinkIndex: 6}), nil + } +} + +// TestUplinkDiscoveryNeverReturnsInternalLinks covers every discovery path: +// DetectUplinks, which galactic-nat's ResolveUplinks uses, and +// ResolveInterfaces, which UplinkIndexes and srv6.ResolvePublicUplink use, +// with and without the operator's override. +func TestUplinkDiscoveryNeverReturnsInternalLinks(t *testing.T) { + stubInternalLinks(t) + t.Setenv(config.EnvCNIEBPFInterfaces, "") + + got, err := DetectUplinks() + if err != nil || !equalStringSlices(got, []string{testIfaceEth0}) { + t.Fatalf("DetectUplinks() = %v, %v; want [%s]", got, err, testIfaceEth0) + } + got, err = ResolveInterfaces() + if err != nil || !equalStringSlices(got, []string{testIfaceEth0}) { + t.Fatalf("ResolveInterfaces() = %v, %v; want [%s]", got, err, testIfaceEth0) + } + + t.Run("override", func(t *testing.T) { + t.Setenv(config.EnvCNIEBPFInterfaces, "G000000080Ob1N,natpeer0,G000000080001H,"+testIfaceEth0) + got, err := ResolveInterfaces() + if err != nil || !equalStringSlices(got, []string{testIfaceEth0}) { + t.Fatalf("ResolveInterfaces() = %v, %v; want [%s]", got, err, testIfaceEth0) + } + t.Setenv(config.EnvCNIEBPFInterfaces, "G000000080Ob1N") + if got, err := ResolveInterfaces(); err == nil { + t.Fatalf("ResolveInterfaces() = %v with only an internal link named, want an error", got) + } + }) +} + +func TestIsInternalLink(t *testing.T) { + for idx, want := range map[int]bool{2: true, 3: true, 4: true, 5: true, 6: false} { + if got := IsInternalLink(internalLinks[idx]); got != want { + t.Errorf("IsInternalLink(%s) = %t, want %t", internalLinks[idx].Attrs().Name, got, want) + } + } +} + +func mustIPNet(t *testing.T, s string) *net.IPNet { + t.Helper() + _, n, err := net.ParseCIDR(s) + if err != nil { + t.Fatal(err) + } + return n +} diff --git a/internal/plumbing/ebpf/attach/local.go b/internal/plumbing/ebpf/attach/local.go new file mode 100644 index 00000000..44ef5a99 --- /dev/null +++ b/internal/plumbing/ebpf/attach/local.go @@ -0,0 +1,147 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package attach + +import ( + "errors" + "fmt" + "strings" + + "github.com/cilium/ebpf" + "github.com/vishvananda/netlink" +) + +// Worker's Local module (internal/worker/local) attaches its own tc ingress +// programs to tenant interfaces, to the receiving devices of a public handoff +// and to the links it creates. It is the only writer of those filters +// (docs/worker/ownership.md). They sit after galactic-cni's own filters, so +// on a tenant interface a Local program sees only what usid_egress passed on, +// and they take galactic-cni's per-interface lock, so neither replaces the +// other's filter mid-change. + +// LocalFilterPrefix starts the name of every Local filter. +const LocalFilterPrefix = "galactic_local_" + +// localFilterHandle is the tc handle of every Local filter. galactic-cni uses +// handles 1 and 2. +var localFilterHandle = netlink.MakeHandle(0, 0x4c) + +// LocalFilterPriority is the tc priority of every Local filter: the first +// after galactic-cni's ingress filters, which take the configured priority +// and the one after it. +func LocalFilterPriority() uint16 { return filterPriorityFn() + 2 } + +// AttachLocal attaches program to ifaceName's tc ingress as the Local filter +// named name, replacing a Local filter already there. +func AttachLocal(program *ebpf.Program, ifaceName, name string) error { + if program == nil { + return errors.New("attach: Local program is nil") + } + if !strings.HasPrefix(name, LocalFilterPrefix) { + return fmt.Errorf("attach: Local filter name %q lacks prefix %q", name, LocalFilterPrefix) + } + return withInterfaceLockFn(ifaceName, func() error { + link, err := netlink.LinkByName(ifaceName) + if err != nil { + return fmt.Errorf("find link %q: %w", ifaceName, err) + } + // One Local filter per interface: a filter of another name at + // Local's slot is a Local program this one replaces. + if err := deleteLocalFilters(link, func(n string) bool { return n != name }); err != nil { + return err + } + return attachOneAtPriorityFn(program, name, ifaceName, netlink.HANDLE_MIN_INGRESS, + LocalFilterPriority(), localFilterHandle) + }) +} + +// DetachLocal removes every Local filter from ifaceName's tc ingress. An +// interface that no longer exists is not an error. +func DetachLocal(ifaceName string) error { + return withInterfaceLockFn(ifaceName, func() error { + link, err := netlink.LinkByName(ifaceName) + if err != nil { + var notFound netlink.LinkNotFoundError + if errors.As(err, ¬Found) { + return nil + } + return fmt.Errorf("find link %q: %w", ifaceName, err) + } + return deleteLocalFilters(link, func(string) bool { return true }) + }) +} + +// LocalFilter returns the name and program ID of the Local filter on +// ifindex's tc ingress, and false when it carries none at Local's slot. +func LocalFilter(ifindex int) (string, ebpf.ProgramID, bool, error) { + link, err := netlink.LinkByIndex(ifindex) + if err != nil { + var notFound netlink.LinkNotFoundError + if errors.As(err, ¬Found) { + // A link that is gone carries no filter. + return "", 0, false, nil + } + return "", 0, false, fmt.Errorf("find link %d: %w", ifindex, err) + } + filters, err := netlink.FilterList(link, netlink.HANDLE_MIN_INGRESS) + if err != nil { + return "", 0, false, fmt.Errorf("list tc ingress filters on %d: %w", ifindex, err) + } + for _, f := range filters { + bf, ok := f.(*netlink.BpfFilter) + if !ok || !strings.HasPrefix(bf.Name, LocalFilterPrefix) || bf.Priority != LocalFilterPriority() || + bf.Handle != localFilterHandle { + continue + } + return bf.Name, ebpf.ProgramID(bf.Id), true, nil + } + return "", 0, false, nil +} + +// LastCNIIngressPriority returns the highest priority a galactic-cni filter +// holds on ifindex's tc ingress, and false when it holds none. A Local +// filter must sit after it. +func LastCNIIngressPriority(ifindex int) (uint16, bool, error) { + link, err := netlink.LinkByIndex(ifindex) + if err != nil { + return 0, false, fmt.Errorf("find link %d: %w", ifindex, err) + } + filters, err := netlink.FilterList(link, netlink.HANDLE_MIN_INGRESS) + if err != nil { + return 0, false, fmt.Errorf("list tc ingress filters on %d: %w", ifindex, err) + } + var ( + last uint16 + found bool + ) + for _, f := range filters { + bf, ok := f.(*netlink.BpfFilter) + if !ok || !strings.HasPrefix(bf.Name, "galactic_") || strings.HasPrefix(bf.Name, LocalFilterPrefix) { + continue + } + if !found || bf.Priority > last { + last, found = bf.Priority, true + } + } + return last, found, nil +} + +func deleteLocalFilters(link netlink.Link, match func(name string) bool) error { + filters, err := netlink.FilterList(link, netlink.HANDLE_MIN_INGRESS) + if err != nil { + return fmt.Errorf("list tc ingress filters on %q: %w", link.Attrs().Name, err) + } + var errs []error + for _, f := range filters { + bf, ok := f.(*netlink.BpfFilter) + if !ok || !strings.HasPrefix(bf.Name, LocalFilterPrefix) || !match(bf.Name) { + continue + } + if err := filterDeleteFn(f); err != nil { + errs = append(errs, fmt.Errorf("delete Local filter %s on %q: %w", bf.Name, link.Attrs().Name, err)) + } + } + return errors.Join(errs...) +} diff --git a/internal/plumbing/ebpf/egressroutemap/egressroute.go b/internal/plumbing/ebpf/egressroutemap/egressroute.go index 8150f556..4f1eaef0 100644 --- a/internal/plumbing/ebpf/egressroutemap/egressroute.go +++ b/internal/plumbing/ebpf/egressroutemap/egressroute.go @@ -447,6 +447,16 @@ const ( // holds. galactic-router's withdrawals keep them // (UnregisterUnlessPassThroughAs). PassThroughEdge PassThroughOwner = 1 + // PassThroughLocal owns the entries Worker's Local module writes for the + // prefixes its own handoffs serve, such as a routed link's pod address. + // usid_egress passes them to the kernel like any pass-through. + PassThroughLocal PassThroughOwner = 2 + // PassThroughLocalNAT owns the entries that steer a VPC's traffic into + // its service-internal veth pair: a tenant's packet that usid_egress + // passes through one of them is redirected into the pair by the Local + // tc program on the tenant's interface (internal/plumbing/ebpf/localprog). + // The resolver that selects a Local NAT shard writes them. + PassThroughLocalNAT PassThroughOwner = 3 ) // RegisterPassThroughAs is RegisterPassThrough for an entry owner owns. diff --git a/internal/plumbing/ebpf/localprog/doc.go b/internal/plumbing/ebpf/localprog/doc.go new file mode 100644 index 00000000..1e87a11e --- /dev/null +++ b/internal/plumbing/ebpf/localprog/doc.go @@ -0,0 +1,16 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +// Package localprog holds the tc programs of Worker's Local module (#1435) +// and their loader. local.c includes the uSID datapath source, so its policy +// decisions run the product's own tp_capture and tp_decide; Load replaces +// every uSID map those programs use with the map galactic-cni pinned, and +// fails rather than create one. The lt_* maps are Local's own and are pinned +// under the Local pin directory. +// +// local_meta.h is the metadata ABI a public receive program uses to hand a +// packet to local_rx. +package localprog + +//go:generate go run github.com/cilium/ebpf/cmd/bpf2go -cflags "-O2 -g -Wall -Wno-unused-function -idirafter /usr/include/x86_64-linux-gnu -idirafter /usr/include/aarch64-linux-gnu" -target bpfel,bpfeb -type lt_tap_value -type lt_link_value -type lt_guest_key -type lt_guest_value -type lt_pair_value -type lt_guard_value -type lt_flow_key -type lt_flow_value Local local.c diff --git a/internal/plumbing/ebpf/localprog/load.go b/internal/plumbing/ebpf/localprog/load.go new file mode 100644 index 00000000..232da08d --- /dev/null +++ b/internal/plumbing/ebpf/localprog/load.go @@ -0,0 +1,196 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package localprog + +import ( + "errors" + "fmt" + "os" + "path/filepath" + "strings" + + "github.com/cilium/ebpf" + "github.com/cilium/ebpf/rlimit" +) + +// PinDir is the default bpffs directory of the Local maps. +const PinDir = "/sys/fs/bpf/galactic-local" + +// ErrDatapathMismatch means a uSID map galactic-cni pinned does not match the +// map this build of local.c expects, or a Local map pinned by an earlier +// Worker has another layout. +var ErrDatapathMismatch = errors.New("localprog: the pinned datapath does not match this build") + +// ErrDatapathNotLoaded means galactic-cni has not pinned a uSID map the Local +// programs use. +var ErrDatapathNotLoaded = errors.New("localprog: the uSID datapath is not loaded") + +// Programs are the Local tc programs. Assigning only these loads only the +// uSID maps they use, never the rest of the datapath local.c includes. +type Programs struct { + Rx *ebpf.Program `ebpf:"local_rx"` + LinkRx *ebpf.Program `ebpf:"local_link_rx"` + PairRx *ebpf.Program `ebpf:"local_pair_rx"` + LinkGuard *ebpf.Program `ebpf:"local_link_guard"` +} + +// Close closes every program descriptor. +func (p *Programs) Close() error { + var errs []error + for _, prog := range []*ebpf.Program{p.Rx, p.LinkRx, p.PairRx, p.LinkGuard} { + if prog != nil { + errs = append(errs, prog.Close()) + } + } + return errors.Join(errs...) +} + +// Maps are the Local maps. +type Maps struct { + Tap *ebpf.Map `ebpf:"lt_tap"` + Link *ebpf.Map `ebpf:"lt_link"` + Guest *ebpf.Map `ebpf:"lt_guest"` + Pair *ebpf.Map `ebpf:"lt_pair"` + Guard *ebpf.Map `ebpf:"lt_guard"` + Flow *ebpf.Map `ebpf:"lt_flow"` + Stats *ebpf.Map `ebpf:"lt_stats"` +} + +// Close closes every map descriptor. +func (m *Maps) Close() error { + var errs []error + for _, mp := range []*ebpf.Map{m.Tap, m.Link, m.Guest, m.Pair, m.Guard, m.Flow, m.Stats} { + if mp != nil { + errs = append(errs, mp.Close()) + } + } + return errors.Join(errs...) +} + +// Objects are the loaded Local programs and maps. +type Objects struct { + Programs Programs + Maps Maps + pinned []*ebpf.Map +} + +// Close releases this process's descriptors. Pinned maps and attached tc +// filters stay. +func (o *Objects) Close() error { + errs := make([]error, 0, 2+len(o.pinned)) + errs = append(errs, o.Programs.Close(), o.Maps.Close()) + for _, m := range o.pinned { + errs = append(errs, m.Close()) + } + return errors.Join(errs...) +} + +// Load loads the Local programs. Every uSID map they use is replaced with the +// map pinned under galacticPinDir, and a map with no pin there fails the load +// with ErrDatapathNotLoaded, so Load never creates or changes a uSID pin. The +// Local maps (lt_*) are pinned under localPinDir, so a restarted Worker keeps +// the rows the running programs read. +func Load(galacticPinDir, localPinDir string) (*Objects, error) { + if err := rlimit.RemoveMemlock(); err != nil { + return nil, fmt.Errorf("localprog: remove memlock rlimit: %w", err) + } + spec, err := LoadLocal() + if err != nil { + return nil, fmt.Errorf("localprog: load compiled spec: %w", err) + } + if err := os.MkdirAll(localPinDir, 0o755); err != nil { + return nil, fmt.Errorf("localprog: create map pin directory: %w", err) + } + + objs := &Objects{} + replacements := map[string]*ebpf.Map{} + var missing []string + for name, m := range spec.Maps { + switch { + case strings.HasPrefix(name, "lt_"): + m.Pinning = ebpf.PinByName + case strings.HasPrefix(name, "."): + // Global data of the included source, private to this load. + default: + pinned, err := ebpf.LoadPinnedMap(filepath.Join(galacticPinDir, name), nil) + if err != nil { + // Not pinned: drop it from the spec. A program that uses it + // then fails to load instead of getting a fresh map. + delete(spec.Maps, name) + missing = append(missing, name) + continue + } + replacements[name] = pinned + objs.pinned = append(objs.pinned, pinned) + } + } + + opts := &ebpf.CollectionOptions{ + Maps: ebpf.MapOptions{PinPath: localPinDir}, + MapReplacements: replacements, + } + if err := spec.LoadAndAssign(&objs.Programs, opts); err != nil { + _ = objs.Close() + var ve *ebpf.VerifierError + switch { + case errors.Is(err, ebpf.ErrMapIncompatible): + return nil, fmt.Errorf("%w: %w", ErrDatapathMismatch, err) + case errors.As(err, &ve): + return nil, fmt.Errorf("localprog: verifier rejected a Local program:\n%w", ve) + case len(missing) > 0: + return nil, fmt.Errorf("%w: no pin for %s under %s: %w", ErrDatapathNotLoaded, + strings.Join(missing, ", "), galacticPinDir, err) + } + return nil, fmt.Errorf("localprog: load programs: %w", err) + } + if err := spec.LoadAndAssign(&objs.Maps, opts); err != nil { + _ = objs.Close() + if errors.Is(err, ebpf.ErrMapIncompatible) { + return nil, fmt.Errorf("%w: %w", ErrDatapathMismatch, err) + } + return nil, fmt.Errorf("localprog: load Local maps: %w", err) + } + return objs, nil +} + +// StatNames names lt_stats' slots, in local.c's enum lt_stat order. +var StatNames = []string{ + "rx_no_meta", + "rx_unclaimed", + "rx_not_ipv6", + "rx_fragment", + "rx_too_big", + "rx_deny", + "rx_deliver", + "link_reply", + "link_reply_deny", + "link_nat", + "link_nat_deny", + "pair_unclaimed", + "pair_not_ipv6", + "pair_fragment", + "pair_too_big", + "pair_deny", + "pair_deliver", + "guard_pass", + "guard_drop", +} + +// Stats reads lt_stats by name, summed over CPUs. +func Stats(m *ebpf.Map) (map[string]uint64, error) { + out := make(map[string]uint64, len(StatNames)) + for i, name := range StatNames { + var per []uint64 + if err := m.Lookup(uint32(i), &per); err != nil { + return nil, fmt.Errorf("localprog: read %s: %w", name, err) + } + var n uint64 + for _, v := range per { + n += v + } + out[name] = n + } + return out, nil +} diff --git a/internal/plumbing/ebpf/localprog/load_root_test.go b/internal/plumbing/ebpf/localprog/load_root_test.go new file mode 100644 index 00000000..2e55e476 --- /dev/null +++ b/internal/plumbing/ebpf/localprog/load_root_test.go @@ -0,0 +1,66 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package localprog + +import ( + "errors" + "fmt" + "os" + "testing" + + "go.datum.net/galactic/internal/plumbing/ebpf/attach" +) + +func requireRoot(t *testing.T) { + t.Helper() + if os.Geteuid() != 0 { + t.Skip("test requires root to load the datapath; run task test:unit-root") + } +} + +// TestLoadRoot loads the Local programs against a freshly pinned uSID +// datapath, which runs them through the kernel verifier, and checks that a +// second load reuses the Local pins. +func TestLoadRoot(t *testing.T) { + requireRoot(t) + base := fmt.Sprintf("/sys/fs/bpf/galactic-localprog-test-%d", os.Getpid()) + t.Cleanup(func() { _ = os.RemoveAll(base) }) + usid, err := attach.Load(base + "/usid") + if err != nil { + t.Fatalf("load uSID datapath: %v", err) + } + t.Cleanup(func() { _ = usid.Close() }) + + objs, err := Load(base+"/usid", base+"/local") + if err != nil { + t.Fatalf("load Local programs: %v", err) + } + t.Cleanup(func() { _ = objs.Close() }) + if err := objs.Maps.Tap.Put(uint32(7), LocalLtTapValue{TableId: 9}); err != nil { + t.Fatalf("write lt_tap: %v", err) + } + + again, err := Load(base+"/usid", base+"/local") + if err != nil { + t.Fatalf("reload Local programs: %v", err) + } + t.Cleanup(func() { _ = again.Close() }) + var v LocalLtTapValue + if err := again.Maps.Tap.Lookup(uint32(7), &v); err != nil || v.TableId != 9 { + t.Fatalf("reloaded lt_tap row = %+v, %v; want the pinned row", v, err) + } + if _, err := Stats(again.Maps.Stats); err != nil { + t.Fatal(err) + } + + // A host with no uSID datapath refuses to load rather than create one. + _, err = Load(base+"/absent", base+"/local2") + if !errors.Is(err, ErrDatapathNotLoaded) { + t.Fatalf("load with no uSID pins: %v, want ErrDatapathNotLoaded", err) + } + if _, statErr := os.Stat(base + "/absent/egress_route_table"); !os.IsNotExist(statErr) { + t.Fatalf("load created a uSID pin: %v", statErr) + } +} diff --git a/internal/plumbing/ebpf/localprog/local.c b/internal/plumbing/ebpf/localprog/local.c new file mode 100644 index 00000000..367c6c38 --- /dev/null +++ b/internal/plumbing/ebpf/localprog/local.c @@ -0,0 +1,549 @@ +//go:build ignore + +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +// local.c holds the tc programs of Worker's Local module (#1435): the +// same-host handoffs between a service's handoff point and tenant interfaces +// that docs/worker/contract.md#local-handoffs specifies. They grew from the +// prototypes #1444 proved (tests/handoffs/probe/handoff.c). +// +// It includes the uSID datapath source, so every policy decision runs the +// product's tp_capture and tp_decide. The loader replaces every uSID map these +// programs use with the map galactic-cni pinned and never creates one; the +// lt_* maps are Local's own, written only by Worker. +// +// Programs and their hooks: +// +// local_rx tc ingress of a public receiving device, after +// galactic-cni's filter. Delivers a packet a dispatcher +// slot marked with galactic_local_meta to the TAP it +// names (local.tap). +// local_link_rx tc ingress of a tenant interface, after galactic-cni's +// filters. Returns a local.tap reply out of the device the +// flow arrived on, or sends a flow into the VPC's +// service-internal veth pair (local.veth_pair). +// local_pair_rx tc ingress of the pair's tenant end. Delivers what the +// NAT end sent back to the tenant it is for. +// local_link_guard tc ingress of a routed link's host end. Drops any +// source the link was not given (local.routed_link). +// +// Every program that delivers to a tenant decides the receiver's policy on +// its own path and sets the decided mark itself, so tp_deliver skips it +// (contract amendment: per-path policy). None trusts a mark already on the +// packet: a packet reaches a Local delivery only after its own decision. A +// target Worker did not authorize, such as a TAP no claim names, is dropped. + +#include "../prog/usid.c" +#include "local_meta.h" + +static long (*lt_check_mtu)(void *ctx, __u32 ifindex, __u32 *mtu_len, __s32 len_diff, + __u64 flags) = (void *) BPF_FUNC_check_mtu; + +#define LT_INLINE inline __attribute__((always_inline)) + +#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ +#define LT_HTONS(x) __builtin_bswap16(x) +#else +#define LT_HTONS(x) (x) +#endif + +#define LT_ETH_P_IPV6 0x86DD +#define LT_IPPROTO_TCP 6 +#define LT_IPPROTO_UDP 17 +#define LT_IPPROTO_FRAGMENT 44 +#define LT_IPPROTO_ICMPV6 58 +// BPF_MTU_CHK_SEGS: check each segment of a GSO packet against the MTU. +#define LT_MTU_CHK_SEGS 1 +// egress_route_key's fixed prefix: table_id and family. +#define LT_ROUTE_KEY_FIXED_BITS 40 +// egressroutemap.PassThroughLocalNAT. +#define LT_OWNER_LOCAL_NAT 3 +#define LT_GUARD_ADDRS 4 + +// Counters, read by internal/plumbing/ebpf/localprog. Append only; the Go +// side names them by index. +enum lt_stat { + LT_STAT_RX_NO_META = 0, + LT_STAT_RX_UNCLAIMED, + LT_STAT_RX_NOT_IPV6, + LT_STAT_RX_FRAGMENT, + LT_STAT_RX_TOO_BIG, + LT_STAT_RX_DENY, + LT_STAT_RX_DELIVER, + LT_STAT_LINK_REPLY, + LT_STAT_LINK_REPLY_DENY, + LT_STAT_LINK_NAT, + LT_STAT_LINK_NAT_DENY, + LT_STAT_PAIR_UNCLAIMED, + LT_STAT_PAIR_NOT_IPV6, + LT_STAT_PAIR_FRAGMENT, + LT_STAT_PAIR_TOO_BIG, + LT_STAT_PAIR_DENY, + LT_STAT_PAIR_DELIVER, + LT_STAT_GUARD_PASS, + LT_STAT_GUARD_DROP, + LT_STAT_COUNT = 32, +}; + +// lt_tap_value is a TAP a local.tap claim authorizes. Keyed by the TAP's +// ifindex. +struct lt_tap_value { + // nh is the guest address local_rx resolves the neighbor of; all zero + // resolves the packet's destination instead. + __u8 nh[16]; + __u32 table_id; + __u32 pad; +}; + +// lt_link_value is a tenant interface Local returns traffic from. Keyed by +// its ifindex. +struct lt_link_value { + __u32 table_id; + // pair_ifindex is the tenant end of the VPC's service-internal veth + // pair, or 0 when the VPC has none on this node. + __u32 pair_ifindex; + __u8 pair_smac[6]; + __u8 pair_dmac[6]; +}; + +// lt_guest_key is a destination address the pair may deliver to, in one +// VPC's table. Two VPCs may use the same address. +struct lt_guest_key { + __u32 table_id; + __u8 addr[16]; +}; + +struct lt_guest_value { + __u32 link_ifindex; + __u32 pad; +}; + +// lt_pair_value is a service-internal veth pair's tenant end. Keyed by its +// ifindex. +struct lt_pair_value { + __u32 table_id; + __u32 pad; +}; + +// lt_guard_value lists the sources a routed link's host end admits, besides +// link-local and unspecified ones. Keyed by the host end's ifindex. +struct lt_guard_value { + __u32 count; + __u32 pad; + __u8 addr[LT_GUARD_ADDRS][16]; +}; + +// lt_flow_key is one local.tap flow as the guest sends its replies: local is +// the guest side, peer the public client. +struct lt_flow_key { + __u32 link_ifindex; + __u8 proto; + __u8 pad; + __u16 pad2; + __u16 local_port; + __u16 peer_port; + __u8 local[16]; + __u8 peer[16]; +}; + +struct lt_flow_value { + // rx_ifindex is the device the flow's request arrived on, which its + // replies leave through. + __u32 rx_ifindex; + __u32 pad; +}; + +struct { + __uint(type, BPF_MAP_TYPE_HASH); + __uint(max_entries, 4096); + __type(key, __u32); + __type(value, struct lt_tap_value); +} lt_tap SEC(".maps"); + +struct { + __uint(type, BPF_MAP_TYPE_HASH); + __uint(max_entries, 8192); + __type(key, __u32); + __type(value, struct lt_link_value); +} lt_link SEC(".maps"); + +struct { + __uint(type, BPF_MAP_TYPE_HASH); + __uint(max_entries, 16384); + __type(key, struct lt_guest_key); + __type(value, struct lt_guest_value); +} lt_guest SEC(".maps"); + +struct { + __uint(type, BPF_MAP_TYPE_HASH); + __uint(max_entries, 1024); + __type(key, __u32); + __type(value, struct lt_pair_value); +} lt_pair SEC(".maps"); + +struct { + __uint(type, BPF_MAP_TYPE_HASH); + __uint(max_entries, 1024); + __type(key, __u32); + __type(value, struct lt_guard_value); +} lt_guard SEC(".maps"); + +struct { + __uint(type, BPF_MAP_TYPE_LRU_HASH); + __uint(max_entries, 65536); + __type(key, struct lt_flow_key); + __type(value, struct lt_flow_value); +} lt_flow SEC(".maps"); + +struct { + __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); + __uint(max_entries, LT_STAT_COUNT); + __type(key, __u32); + __type(value, __u64); +} lt_stats SEC(".maps"); + +static LT_INLINE void lt_count(__u32 stat) +{ + __u64 *v = bpf_map_lookup_elem(<_stats, &stat); + + if (v) + *v += 1; +} + +static LT_INLINE int lt_eq16(const __u8 *a, const __u8 *b) +{ + const __u64 *x = (const __u64 *) a; + const __u64 *y = (const __u64 *) b; + + return x[0] == y[0] && x[1] == y[1]; +} + +static LT_INLINE int lt_zero16(const __u8 *a) +{ + const __u64 *x = (const __u64 *) a; + + return x[0] == 0 && x[1] == 0; +} + +// lt_ip6 returns the packet's IPv6 header after pulling it, and the first 8 +// bytes of what follows when the packet has them, or 0 when the packet is +// not IPv6. +static LT_INLINE struct usid_ip6hdr *lt_ip6(struct __sk_buff *skb) +{ + if (bpf_skb_pull_data(skb, sizeof(struct usid_ethhdr) + sizeof(struct usid_ip6hdr))) + return 0; + // Best effort: a packet with no transport header has no ports. + bpf_skb_pull_data(skb, sizeof(struct usid_ethhdr) + sizeof(struct usid_ip6hdr) + 8); + + void *data = (void *) (long) skb->data; + void *end = (void *) (long) skb->data_end; + struct usid_ethhdr *eth = data; + struct usid_ip6hdr *ip6 = (void *) (eth + 1); + + if ((void *) (ip6 + 1) > end || eth->h_proto != LT_HTONS(LT_ETH_P_IPV6)) + return 0; + return ip6; +} + +// lt_ports reads the source and destination ports of a TCP or UDP packet, +// and the ICMPv6 echo identifier as both. Other protocols, and a packet +// whose transport header follows extension headers, have none. +static LT_INLINE void lt_ports(struct __sk_buff *skb, struct usid_ip6hdr *ip6, __u16 *sport, __u16 *dport) +{ + void *end = (void *) (long) skb->data_end; + __u16 *l4 = (void *) (ip6 + 1); + + *sport = 0; + *dport = 0; + switch (ip6->nexthdr) { + case LT_IPPROTO_TCP: + case LT_IPPROTO_UDP: + if ((void *) (l4 + 2) <= end) { + *sport = l4[0]; + *dport = l4[1]; + } + break; + case LT_IPPROTO_ICMPV6: + // type, code, checksum, then an echo's identifier. + if ((void *) (l4 + 3) <= end) { + *sport = l4[2]; + *dport = l4[2]; + } + break; + } +} + +// lt_fits reports whether skb fits ifindex's MTU, segment by segment for a +// GSO packet. A redirect does not enforce the receiver's MTU itself. +static LT_INLINE int lt_fits(struct __sk_buff *skb, __u32 ifindex) +{ + __u32 mtu = 0; + + return lt_check_mtu(skb, ifindex, &mtu, 0, LT_MTU_CHK_SEGS) == 0; +} + +// local_rx delivers a public packet a dispatcher slot program marked for a +// tenant TAP. A packet without the metadata is not Local's and goes on to the +// kernel unchanged. One naming a TAP no claim authorizes, an IPv6 fragment, +// which a TAP guest was measured not to take, and one too big for the TAP are +// dropped. +SEC("tc") +int local_rx(struct __sk_buff *skb) +{ + struct galactic_local_meta *meta = (void *) (long) skb->data_meta; + __u32 tap; + + if ((void *) (meta + 1) > (void *) (long) skb->data || meta->magic != GALACTIC_LOCAL_META_MAGIC) { + lt_count(LT_STAT_RX_NO_META); + return TC_ACT_UNSPEC; + } + tap = meta->tap_ifindex; + + struct lt_tap_value *tv = bpf_map_lookup_elem(<_tap, &tap); + + if (!tv) { + lt_count(LT_STAT_RX_UNCLAIMED); + return TC_ACT_SHOT; + } + + __u8 nh[16]; + + __builtin_memcpy(nh, tv->nh, 16); + + struct usid_ip6hdr *ip6 = lt_ip6(skb); + + if (!ip6) { + lt_count(LT_STAT_RX_NOT_IPV6); + return TC_ACT_SHOT; + } + if (ip6->nexthdr == LT_IPPROTO_FRAGMENT) { + lt_count(LT_STAT_RX_FRAGMENT); + return TC_ACT_SHOT; + } + + struct lt_flow_key fk = {}; + struct lt_flow_value fv = {}; + + fk.link_ifindex = tap; + fk.proto = ip6->nexthdr; + lt_ports(skb, ip6, &fk.peer_port, &fk.local_port); + __builtin_memcpy(fk.local, ip6->daddr, 16); + __builtin_memcpy(fk.peer, ip6->saddr, 16); + fv.rx_ifindex = skb->ifindex; + + if (!lt_fits(skb, tap)) { + lt_count(LT_STAT_RX_TOO_BIG); + return TC_ACT_SHOT; + } + tp_capture(skb, TP_DIR_INGRESS, tap, 0); + if (tp_decide(tap, TP_DIR_INGRESS, TP_PATH_PUBLIC_SERVICE)) { + lt_count(LT_STAT_RX_DENY); + return TC_ACT_SHOT; + } + skb->mark |= tp_ingress_mark(); + bpf_map_update_elem(<_flow, &fk, &fv, BPF_ANY); + lt_count(LT_STAT_RX_DELIVER); + if (lt_zero16(nh)) + return bpf_redirect_neigh(tap, 0, 0, 0); + + struct bpf_redir_neigh p = {}; + + p.nh_family = USID_AF_INET6; + __builtin_memcpy(p.ipv6_nh, nh, 16); + return bpf_redirect_neigh(tap, &p, sizeof(p), 0); +} + +// lt_nat_route reports whether dst's entry in table steers into the VPC's +// service-internal veth pair: a pass-through entry PassThroughLocalNAT owns. +static LT_INLINE int lt_nat_route(__u32 table, const __u8 *dst) +{ + struct egress_route_key k = {}; + + k.prefixlen = LT_ROUTE_KEY_FIXED_BITS + 128; + k.table_id = table; + k.family = USID_EGRESS_ROUTE_FAMILY_INET6; + __builtin_memcpy(k.addr, dst, 16); + + struct egress_route_value *v = bpf_map_lookup_elem(&egress_route_table, &k); + + return v && v->link_ifindex == 0 && v->sid[0] == LT_OWNER_LOCAL_NAT; +} + +// local_link_rx runs on a tenant interface after usid_egress has passed the +// packet on. A reply to a flow local_rx delivered leaves through the device +// the flow arrived on. A packet whose destination's entry steers into the +// VPC's service-internal veth pair enters the pair. Anything else goes on +// to the kernel. +SEC("tc") +int local_link_rx(struct __sk_buff *skb) +{ + __u32 ifindex = skb->ifindex; + struct lt_link_value *lv = bpf_map_lookup_elem(<_link, &ifindex); + + if (!lv) + return TC_ACT_UNSPEC; + + __u32 table = lv->table_id; + __u32 pair = lv->pair_ifindex; + __u8 smac[6]; + __u8 dmac[6]; + + __builtin_memcpy(smac, lv->pair_smac, 6); + __builtin_memcpy(dmac, lv->pair_dmac, 6); + + struct usid_ip6hdr *ip6 = lt_ip6(skb); + + if (!ip6) + return TC_ACT_UNSPEC; + + struct lt_flow_key fk = {}; + + fk.link_ifindex = ifindex; + fk.proto = ip6->nexthdr; + lt_ports(skb, ip6, &fk.local_port, &fk.peer_port); + __builtin_memcpy(fk.local, ip6->saddr, 16); + __builtin_memcpy(fk.peer, ip6->daddr, 16); + + struct lt_flow_value *fv = bpf_map_lookup_elem(<_flow, &fk); + + if (fv) { + __u32 rx = fv->rx_ifindex; + + tp_capture(skb, TP_DIR_EGRESS, ifindex, 0); + if (tp_decide(ifindex, TP_DIR_EGRESS, TP_PATH_PUBLIC_SERVICE)) { + lt_count(LT_STAT_LINK_REPLY_DENY); + return TC_ACT_SHOT; + } + lt_count(LT_STAT_LINK_REPLY); + return bpf_redirect_neigh(rx, 0, 0, 0); + } + + __u8 dst[16]; + + __builtin_memcpy(dst, ip6->daddr, 16); + if (!pair || !lt_nat_route(table, dst)) + return TC_ACT_UNSPEC; + + tp_capture(skb, TP_DIR_EGRESS, ifindex, 0); + if (tp_decide(ifindex, TP_DIR_EGRESS, TP_PATH_PUBLIC_NAT)) { + lt_count(LT_STAT_LINK_NAT_DENY); + return TC_ACT_SHOT; + } + + void *data = (void *) (long) skb->data; + void *end = (void *) (long) skb->data_end; + struct usid_ethhdr *eth = data; + + if ((void *) (eth + 1) > end) + return TC_ACT_SHOT; + __builtin_memcpy(eth->h_source, smac, 6); + __builtin_memcpy(eth->h_dest, dmac, 6); + lt_count(LT_STAT_LINK_NAT); + return bpf_redirect(pair, 0); +} + +// local_pair_rx runs on the tenant end of a service-internal veth pair. The +// NAT end sends it the return half of a tenant's flow; it delivers to the +// tenant the destination address names in the pair's VPC, and drops a packet +// for any address no claim authorizes. +SEC("tc") +int local_pair_rx(struct __sk_buff *skb) +{ + __u32 ifindex = skb->ifindex; + struct lt_pair_value *pv = bpf_map_lookup_elem(<_pair, &ifindex); + + if (!pv) { + lt_count(LT_STAT_PAIR_UNCLAIMED); + return TC_ACT_SHOT; + } + + struct lt_guest_key gk = {}; + + gk.table_id = pv->table_id; + + struct usid_ip6hdr *ip6 = lt_ip6(skb); + + if (!ip6) { + lt_count(LT_STAT_PAIR_NOT_IPV6); + return TC_ACT_SHOT; + } + if (ip6->nexthdr == LT_IPPROTO_FRAGMENT) { + lt_count(LT_STAT_PAIR_FRAGMENT); + return TC_ACT_SHOT; + } + __builtin_memcpy(gk.addr, ip6->daddr, 16); + + struct lt_guest_value *gv = bpf_map_lookup_elem(<_guest, &gk); + + if (!gv) { + lt_count(LT_STAT_PAIR_UNCLAIMED); + return TC_ACT_SHOT; + } + + __u32 link = gv->link_ifindex; + + if (!lt_fits(skb, link)) { + lt_count(LT_STAT_PAIR_TOO_BIG); + return TC_ACT_SHOT; + } + tp_capture(skb, TP_DIR_INGRESS, link, 0); + if (tp_decide(link, TP_DIR_INGRESS, TP_PATH_PUBLIC_NAT)) { + lt_count(LT_STAT_PAIR_DENY); + return TC_ACT_SHOT; + } + skb->mark |= tp_ingress_mark(); + lt_count(LT_STAT_PAIR_DELIVER); + + struct bpf_redir_neigh p = {}; + + p.nh_family = USID_AF_INET6; + __builtin_memcpy(p.ipv6_nh, gk.addr, 16); + return bpf_redirect_neigh(link, &p, sizeof(p), 0); +} + +// local_link_guard runs on the host end of a pod-to-host routed link. The link +// joins the pod to the tenant VRF, so a source it was not given would let the +// pod speak as any address in the VPC. Link-local and unspecified sources +// carry Neighbor Discovery on the link itself; anything else not IPv6 is +// dropped. +SEC("tc") +int local_link_guard(struct __sk_buff *skb) +{ + __u32 ifindex = skb->ifindex; + struct lt_guard_value *gv = bpf_map_lookup_elem(<_guard, &ifindex); + + if (!gv) { + lt_count(LT_STAT_GUARD_DROP); + return TC_ACT_SHOT; + } + + __u32 count = gv->count; + struct usid_ip6hdr *ip6 = lt_ip6(skb); + + if (!ip6) { + lt_count(LT_STAT_GUARD_DROP); + return TC_ACT_SHOT; + } + if ((ip6->saddr[0] == 0xfe && (ip6->saddr[1] & 0xc0) == 0x80) || lt_zero16(ip6->saddr)) { + lt_count(LT_STAT_GUARD_PASS); + return TC_ACT_UNSPEC; + } + + __u8 src[16]; + + __builtin_memcpy(src, ip6->saddr, 16); + gv = bpf_map_lookup_elem(<_guard, &ifindex); + if (!gv) + return TC_ACT_SHOT; +#pragma unroll + for (int i = 0; i < LT_GUARD_ADDRS; i++) { + if (i < count && lt_eq16(src, gv->addr[i])) { + lt_count(LT_STAT_GUARD_PASS); + return TC_ACT_UNSPEC; + } + } + lt_count(LT_STAT_GUARD_DROP); + return TC_ACT_SHOT; +} diff --git a/internal/plumbing/ebpf/localprog/local_meta.h b/internal/plumbing/ebpf/localprog/local_meta.h new file mode 100644 index 00000000..29e29237 --- /dev/null +++ b/internal/plumbing/ebpf/localprog/local_meta.h @@ -0,0 +1,28 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +// local_meta.h is the XDP metadata a public receive program hands Worker's +// Local module (#1435): a dispatcher slot program that wants a packet +// delivered to a tenant TAP sets this metadata with bpf_xdp_adjust_meta and +// returns XDP_PASS, and local_rx, the Local tc program on the same +// interface, delivers it. The layout is ABI between the two; it only grows by +// appending fields and raising the magic. +// +// Only an XDP program can write skb metadata, so a packet from the wire +// cannot carry it. local_rx still delivers only to a TAP Worker authorized +// for a Local claim. + +#ifndef GALACTIC_LOCAL_META_H +#define GALACTIC_LOCAL_META_H + +// "GLM1" +#define GALACTIC_LOCAL_META_MAGIC 0x474c4d31 + +struct galactic_local_meta { + __u32 magic; + // tap_ifindex is the tenant TAP the packet is for. + __u32 tap_ifindex; +}; + +#endif diff --git a/internal/plumbing/ebpf/localprog/localfixture/doc.go b/internal/plumbing/ebpf/localprog/localfixture/doc.go new file mode 100644 index 00000000..b233593e --- /dev/null +++ b/internal/plumbing/ebpf/localprog/localfixture/doc.go @@ -0,0 +1,11 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +// Package localfixture holds test stand-ins for the XDP programs the gateway +// and the NAT shard run at Worker's Local handoffs, so the Local programs can +// be tested end to end on a real kernel. It is test code and is never +// deployed. +package localfixture + +//go:generate go run github.com/cilium/ebpf/cmd/bpf2go -cflags "-O2 -g -Wall -Wno-unused-function -idirafter /usr/include/x86_64-linux-gnu -idirafter /usr/include/aarch64-linux-gnu" -target bpfel,bpfeb -type ltf_vip_value -type ltf_shard_value -type ltf_snat_value -type ltf_in6 Fixture fixture.c diff --git a/internal/plumbing/ebpf/localprog/localfixture/fixture.c b/internal/plumbing/ebpf/localprog/localfixture/fixture.c new file mode 100644 index 00000000..7403fa9d --- /dev/null +++ b/internal/plumbing/ebpf/localprog/localfixture/fixture.c @@ -0,0 +1,289 @@ +//go:build ignore + +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +// fixture.c holds test stand-ins for the XDP programs other services run at +// the Local handoffs, so Worker's Local programs can be tested end to end. It +// is never deployed. They grew from the prototypes #1444 proved +// (tests/handoffs/probe/handoff.c). +// +// ltf_gateway a dispatcher slot program on a receiving device, as the +// gateway runs (#1438): it marks a VIP packet for its TAP with +// galactic_local_meta and returns XDP_PASS, and translates the +// return half of a NAT flow back to its guest and redirects it +// into the NAT end of the VPC's pair. +// ltf_nat the NAT shard's program on a pair's NAT end (#1437): it +// translates the guest's source to the shard address and +// redirects the packet out of the receiving device, pushing a +// VLAN tag itself when the device is a VLAN. +// +// Both rewrite the L4 checksum as a complete one, as the probe's prototypes +// did, so a partial checksum reaching them is corrupted, as on a real host. + +#include +#include "../local_meta.h" + +#define SEC(name) __attribute__((section(name), used)) +#define __uint(name, val) int (*name)[val] +#define __type(name, val) typeof(val) *name +#define LTF_INLINE inline __attribute__((always_inline)) + +#if __BYTE_ORDER__ == __ORDER_LITTLE_ENDIAN__ +#define LTF_HTONS(x) __builtin_bswap16(x) +#else +#define LTF_HTONS(x) (x) +#endif + +static void *(*bpf_map_lookup_elem)(void *map, const void *key) = (void *) BPF_FUNC_map_lookup_elem; +static long (*bpf_redirect)(__u32 ifindex, __u64 flags) = (void *) BPF_FUNC_redirect; +static long (*bpf_xdp_adjust_meta)(void *ctx, int delta) = (void *) BPF_FUNC_xdp_adjust_meta; +static long (*bpf_xdp_adjust_head)(void *ctx, int delta) = (void *) BPF_FUNC_xdp_adjust_head; +static __s64 (*bpf_csum_diff)(__be32 *from, __u32 from_size, __be32 *to, __u32 to_size, + __u32 seed) = (void *) BPF_FUNC_csum_diff; + +#define LTF_ETH_P_IPV6 0x86DD +#define LTF_ETH_P_8021Q 0x8100 + +struct ltf_eth { + __u8 dst[6]; + __u8 src[6]; + __be16 proto; +}; + +struct ltf_ip6 { + __u8 vtc[4]; + __be16 plen; + __u8 nexthdr; + __u8 hlim; + __u8 saddr[16]; + __u8 daddr[16]; +}; + +struct ltf_in6 { + __u8 a[16]; +}; + +struct ltf_vip_value { + __u32 tap_ifindex; + // magic is the metadata magic written; a test writes a wrong one. + __u32 magic; +}; + +struct ltf_shard_value { + __u32 peer_ifindex; + __u32 pad; + __u8 guest[16]; + __u8 smac[6]; + __u8 dmac[6]; +}; + +struct ltf_snat_value { + __u32 out_ifindex; + // vid is nonzero when out_ifindex is a VLAN's lower device, whose tag + // the program pushes. + __u32 vid; + __u8 guest[16]; + __u8 shard[16]; + __u8 smac[6]; + __u8 dmac[6]; +}; + +struct { + __uint(type, BPF_MAP_TYPE_HASH); + __uint(max_entries, 16); + __type(key, struct ltf_in6); + __type(value, struct ltf_vip_value); +} ltf_vip SEC(".maps"); + +struct { + __uint(type, BPF_MAP_TYPE_HASH); + __uint(max_entries, 16); + __type(key, struct ltf_in6); + __type(value, struct ltf_shard_value); +} ltf_shard SEC(".maps"); + +struct { + __uint(type, BPF_MAP_TYPE_HASH); + __uint(max_entries, 16); + __type(key, __u32); + __type(value, struct ltf_snat_value); +} ltf_snat SEC(".maps"); + +static LTF_INLINE __u16 ltf_fold(__s64 sum) +{ + __u64 s = (__u64) sum; + + s = (s & 0xffffffff) + (s >> 32); + s = (s & 0xffff) + (s >> 16); + s = (s & 0xffff) + (s >> 16); + return (__u16) s; +} + +static LTF_INLINE int ltf_eq16(const __u8 *a, const __u8 *b) +{ + const __u64 *x = (const __u64 *) a; + const __u64 *y = (const __u64 *) b; + + return x[0] == y[0] && x[1] == y[1]; +} + +// ltf_rewrite replaces the address at addr in ip6 with to and updates a TCP, +// UDP or ICMPv6 checksum as if it were complete. +static LTF_INLINE int ltf_rewrite(struct xdp_md *ctx, struct ltf_ip6 *ip6, __u8 *addr, const __u8 *to) +{ + void *end = (void *) (long) ctx->data_end; + int off = -1; + __u8 from[16]; + __u8 next[16]; + + switch (ip6->nexthdr) { + case 6: + off = 16; + break; + case 17: + off = 6; + break; + case 58: + off = 2; + break; + } + __builtin_memcpy(from, addr, 16); + __builtin_memcpy(next, to, 16); + if (off >= 0) { + __u16 *csum = (void *) (ip6 + 1) + off; + + if ((void *) (csum + 1) > end) + return -1; + if (!(ip6->nexthdr == 17 && *csum == 0)) { + __u32 seed = (~(__u32) *csum) & 0xffff; + + *csum = ~ltf_fold(bpf_csum_diff((__be32 *) from, 16, (__be32 *) next, 16, seed)); + } + } + __builtin_memcpy(addr, next, 16); + return 0; +} + +SEC("xdp") +int ltf_gateway(struct xdp_md *ctx) +{ + void *data = (void *) (long) ctx->data; + void *end = (void *) (long) ctx->data_end; + struct ltf_eth *eth = data; + __u32 l3 = sizeof(*eth); + int tagged = 0; + + if ((void *) (eth + 1) > end) + return XDP_PASS; + if (eth->proto == LTF_HTONS(LTF_ETH_P_8021Q)) { + __be16 *tci = data + sizeof(*eth); + + if ((void *) (tci + 2) > end || tci[1] != LTF_HTONS(LTF_ETH_P_IPV6)) + return XDP_PASS; + l3 += 4; + tagged = 1; + } else if (eth->proto != LTF_HTONS(LTF_ETH_P_IPV6)) { + return XDP_PASS; + } + + struct ltf_ip6 *ip6 = data + l3; + + if ((void *) (ip6 + 1) > end) + return XDP_PASS; + + struct ltf_in6 dst; + + __builtin_memcpy(dst.a, ip6->daddr, 16); + + struct ltf_vip_value *vip = bpf_map_lookup_elem(<f_vip, &dst); + + if (vip) { + __u32 tap = vip->tap_ifindex; + __u32 magic = vip->magic; + + if (bpf_xdp_adjust_meta(ctx, -(int) sizeof(struct galactic_local_meta)) == 0) { + struct galactic_local_meta *meta = (void *) (long) ctx->data_meta; + + if ((void *) (meta + 1) <= (void *) (long) ctx->data) { + meta->magic = magic; + meta->tap_ifindex = tap; + } + } + return XDP_PASS; + } + + struct ltf_shard_value *shard = bpf_map_lookup_elem(<f_shard, &dst); + + if (!shard) + return XDP_PASS; + if (ltf_rewrite(ctx, ip6, ip6->daddr, shard->guest)) + return XDP_PASS; + if (tagged) { + __u8 macs[12]; + + if ((void *) ((__u8 *) data + 16) > end) + return XDP_PASS; + __builtin_memcpy(macs, data, 12); + __builtin_memcpy((__u8 *) data + 4, macs, 12); + if (bpf_xdp_adjust_head(ctx, 4)) + return XDP_PASS; + data = (void *) (long) ctx->data; + end = (void *) (long) ctx->data_end; + eth = data; + if ((void *) (eth + 1) > end) + return XDP_PASS; + } + __builtin_memcpy(eth->src, shard->smac, 6); + __builtin_memcpy(eth->dst, shard->dmac, 6); + return bpf_redirect(shard->peer_ifindex, 0); +} + +SEC("xdp") +int ltf_nat(struct xdp_md *ctx) +{ + __u32 ifindex = ctx->ingress_ifindex; + struct ltf_snat_value *v = bpf_map_lookup_elem(<f_snat, &ifindex); + void *data = (void *) (long) ctx->data; + void *end = (void *) (long) ctx->data_end; + struct ltf_eth *eth = data; + struct ltf_ip6 *ip6 = (void *) (eth + 1); + + if (!v || (void *) (ip6 + 1) > end || eth->proto != LTF_HTONS(LTF_ETH_P_IPV6)) + return XDP_PASS; + if (!ltf_eq16(ip6->saddr, v->guest)) + return XDP_PASS; + if (ltf_rewrite(ctx, ip6, ip6->saddr, v->shard)) + return XDP_PASS; + + __u32 out = v->out_ifindex; + __u32 vid = v->vid; + __u8 smac[6]; + __u8 dmac[6]; + + __builtin_memcpy(smac, v->smac, 6); + __builtin_memcpy(dmac, v->dmac, 6); + if (vid) { + if (bpf_xdp_adjust_head(ctx, -4)) + return XDP_PASS; + data = (void *) (long) ctx->data; + end = (void *) (long) ctx->data_end; + eth = data; + __be16 *tag = data + 12; + + if ((void *) (eth + 1) > end || (void *) (tag + 3) > end) + return XDP_ABORTED; + __builtin_memcpy(eth->dst, dmac, 6); + __builtin_memcpy(eth->src, smac, 6); + tag[0] = LTF_HTONS(LTF_ETH_P_8021Q); + tag[1] = LTF_HTONS((__u16) (vid & 0x0fff)); + tag[2] = LTF_HTONS(LTF_ETH_P_IPV6); + return bpf_redirect(out, 0); + } + __builtin_memcpy(eth->src, smac, 6); + __builtin_memcpy(eth->dst, dmac, 6); + return bpf_redirect(out, 0); +} + +char __license[] SEC("license") = "GPL"; diff --git a/internal/plumbing/ebpf/xdpdispatch/inspect.go b/internal/plumbing/ebpf/xdpdispatch/inspect.go new file mode 100644 index 00000000..2aa4b5c4 --- /dev/null +++ b/internal/plumbing/ebpf/xdpdispatch/inspect.go @@ -0,0 +1,184 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package xdpdispatch + +import ( + "errors" + "fmt" + "os" + "path/filepath" + "strconv" + + "github.com/cilium/ebpf" + "github.com/cilium/ebpf/link" + + "go.datum.net/galactic/internal/plumbing/ebpf/xdpmode" +) + +// ErrNoDispatcher means the host has no dispatch state: no datapath sharing +// the XDP hook has opened a dispatcher on it. +var ErrNoDispatcher = errors.New("xdpdispatch: no dispatcher on this host") + +// ErrSlotEmpty means a slot holds no program. +var ErrSlotEmpty = errors.New("xdpdispatch: slot holds no program") + +// Inspector reads a host's dispatch state without changing it. Unlike Open +// and OpenForSlots it loads no program, pins nothing and takes no lock, so a +// process that only checks whether another datapath's slot covers an +// interface, such as Worker's Local module, never creates dispatch state on a +// host that has none. +type Inspector struct { + dir string + progs *ebpf.Map + leases *ebpf.Map + roles *ebpf.Map + hostMode *ebpf.Map +} + +// Inspect opens dir's pinned dispatch state read-only. It returns +// ErrNoDispatcher when dir holds no root. +func Inspect(dir string) (*Inspector, error) { + abi := filepath.Join(dir, abiDirName) + if _, err := os.Stat(filepath.Join(abi, rootPinName)); errors.Is(err, os.ErrNotExist) { + return nil, ErrNoDispatcher + } + ro := &ebpf.LoadPinOptions{ReadOnly: true} + in := &Inspector{dir: dir} + for _, m := range []struct { + dst **ebpf.Map + path string + }{ + {&in.progs, filepath.Join(abi, "dispatch_progs")}, + {&in.leases, filepath.Join(abi, "slot_lease")}, + {&in.roles, filepath.Join(abi, "iface_roles")}, + {&in.hostMode, filepath.Join(dir, hostModePinName)}, + } { + mp, err := ebpf.LoadPinnedMap(m.path, ro) + if err != nil { + _ = in.Close() + if errors.Is(err, os.ErrNotExist) { + return nil, ErrNoDispatcher + } + return nil, fmt.Errorf("xdpdispatch: open %s: %w", m.path, err) + } + *m.dst = mp + } + return in, nil +} + +// Close releases the inspector's descriptors. +func (in *Inspector) Close() error { + var errs []error + for _, m := range []*ebpf.Map{in.progs, in.leases, in.roles, in.hostMode} { + if m != nil { + errs = append(errs, m.Close()) + } + } + return errors.Join(errs...) +} + +// Interfaces returns every ifindex whose roles include role. +func (in *Inspector) Interfaces(role Role) ([]int, error) { + var ( + out []int + key uint32 + roles uint32 + ) + it := in.roles.Iterate() + for it.Next(&key, &roles) { + if Role(roles)&role != 0 { + out = append(out, int(key)) + } + } + if err := it.Err(); err != nil { + return nil, fmt.Errorf("xdpdispatch: read interface roles: %w", err) + } + return out, nil +} + +// HostMode returns the XDP mode the attaching datapaths on the host +// recorded, and false when none has. +func (in *Inspector) HostMode() (xdpmode.Mode, bool, error) { + var v uint32 + if err := in.hostMode.Lookup(uint32(0), &v); err != nil { + return 0, false, fmt.Errorf("xdpdispatch: read host mode record: %w", err) + } + if v == 0 { + return 0, false, nil + } + return xdpmode.Mode(v - 1), true, nil +} + +// Claimed reports whether some program sees ifindex's traffic through slot, +// whichever program it is. It returns nil when it does, and otherwise +// ErrNoLink, ErrLinkDefunct, ErrNotRoot, ErrModeMismatch, ErrRoleMissing, +// ErrSlotEmpty or ErrLeaseExpired, wrapped. It is Coverage for a reader that +// does not hold the slot's program. +func (in *Inspector) Claimed(ifindex int, slot Slot) error { + if slot >= NumSlots { + return errInvalidSlot + } + // A pinned link takes no read-only open; the inspector only reads it. + pinned, err := link.LoadPinnedLink(filepath.Join(in.dir, linksDirName, strconv.Itoa(ifindex)), nil) + if errors.Is(err, os.ErrNotExist) { + return ErrNoLink + } + if err != nil { + return fmt.Errorf("xdpdispatch: load pinned link for ifindex %d: %w", ifindex, err) + } + defer pinned.Close() //nolint:errcheck // our own descriptor + info, err := pinned.Info() + if err != nil { + return fmt.Errorf("xdpdispatch: read link info for ifindex %d: %w", ifindex, err) + } + if xdp := info.XDP(); xdp == nil || int(xdp.Ifindex) != ifindex { + return ErrLinkDefunct + } + root, err := ebpf.LoadPinnedProgram(filepath.Join(in.dir, abiDirName, rootPinName), nil) + if err != nil { + return fmt.Errorf("xdpdispatch: load pinned root: %w", err) + } + rootID, err := programID(root) + _ = root.Close() + if err != nil { + return err + } + if info.Program != rootID { + return ErrNotRoot + } + want, recorded, err := in.HostMode() + if err != nil { + return err + } + mode, ok, err := attachedMode(ifindex) + if err != nil { + return err + } + if !ok || (recorded && mode != want) { + return ErrModeMismatch + } + var roles uint32 + if err := in.roles.Lookup(uint32(ifindex), &roles); err != nil && !errors.Is(err, ebpf.ErrKeyNotExist) { + return fmt.Errorf("xdpdispatch: read roles for ifindex %d: %w", ifindex, err) + } + if Role(roles)&(1< 0 || len(m.routed) > 0) { + // The links just created must count as present below. + if p.h, err = readHost(); err != nil { + return p.res, err + } + } + for _, name := range sortedKeys(m.tenants) { + if err := p.ensureTenant(m.tenants[name]); err != nil { + return p.res, err + } + } + return p.res, p.removeStale() +} + +// ensurePairs makes each pair exist with its row and filter. +func (p *pass) ensurePairs() error { + for _, name := range sortedKeys(p.m.pairs) { + got, err := p.k.ensurePair(p.h, p.m.pairs[name], p.vrfIdx, p.dry) + if err != nil { + return err + } + p.pairs[name] = got + if err := putRow(p.objs.Maps.Pair, uint32(got.tenant.Attrs().Index), + localprog.LocalLtPairValue{TableId: p.table}, p.dry, "pair row of "+name); err != nil { + return err + } + if err := p.k.ensureFilter(got.tenant, filterPairRx, p.dry); err != nil { + return err + } + } + return nil +} + +// ensureRoutedLinks makes each routed link exist. A link whose pod cannot be +// reached is recorded, not fatal. +func (p *pass) ensureRoutedLinks() error { + if len(p.m.routed) == 0 { + return nil + } + entries, err := p.routes.Entries(p.table) + if err != nil { + return err + } + for _, name := range sortedKeys(p.m.routed) { + err := p.ensureRouted(p.m.routed[name], entries) + switch { + case err == nil: + case errors.Is(err, ErrPodNotFound) || errors.Is(err, ErrPodHostNetwork): + p.res.errs[name] = err + default: + return err + } + } + return nil +} + +// ensureTenant programs one tenant interface a claim delivers to: its link +// row, its TAP row for local.tap, its guest rows for local.veth_pair, and +// local_link_rx. +func (p *pass) ensureTenant(t *tenantWant) error { + l := p.h.byName[t.name] + if l == nil || l.Attrs().MasterIndex != p.vrfIdx { + // Not attached yet, or being replaced; a link event requeues. + return nil + } + idx := uint32(l.Attrs().Index) + lv := localprog.LocalLtLinkValue{TableId: p.table} + if pr, ok := p.pairs[t.pair]; ok { + lv.PairIfindex = uint32(pr.tenant.Attrs().Index) + copy(lv.PairSmac[:], pr.tenant.Attrs().HardwareAddr) + copy(lv.PairDmac[:], pr.nat.Attrs().HardwareAddr) + } + if err := putRow(p.objs.Maps.Link, idx, lv, p.dry, "link row of "+t.name); err != nil { + return err + } + if t.tap { + tv := localprog.LocalLtTapValue{TableId: p.table} + if t.nh.IsValid() { + tv.Nh = t.nh.As16() + } + if err := putRow(p.objs.Maps.Tap, idx, tv, p.dry, "TAP row of "+t.name); err != nil { + return err + } + } + if t.pair != "" { + for _, a := range t.guests { + if err := putRow(p.objs.Maps.Guest, localprog.LocalLtGuestKey{TableId: p.table, Addr: a.As16()}, + localprog.LocalLtGuestValue{LinkIfindex: idx}, p.dry, "guest row "+a.String()); err != nil { + return err + } + } + } + return p.k.ensureFilter(l, filterLinkRx, p.dry) +} + +// removeStale removes the Local state of the VPC that the pass's model does +// not want: its Local links, the Local filters and rows of its tenant +// interfaces, its guest rows and pass-through entries, and every Local row +// whose interface is gone. +func (p *pass) removeStale() error { + if err := p.removeLinks(); err != nil { + return err + } + wanted, err := p.removeFilters() + if err != nil { + return err + } + if err := p.removeRows(wanted); err != nil { + return err + } + if err := p.removeGuests(); err != nil { + return err + } + return p.removePassThrough() +} + +// wantsLink reports whether name is a Local link the model wants. +func (p *pass) wantsLink(name string) bool { + if _, ok := p.m.pairs[name]; ok { + return true + } + if _, ok := p.m.routed[name]; ok { + return true + } + pr, ok := p.m.pairs[pairTenantOf(name)] + return ok && pr.nat == name +} + +// removeLinks deletes the VPC's Local links the model does not want. +func (p *pass) removeLinks() error { + for name, l := range p.h.localLinks(p.m.vpc) { + if p.wantsLink(name) { + continue + } + if err := fix(p.dry, true, func() error { + if err := netlink.LinkDel(l); err != nil && !errors.Is(err, unix.ENODEV) { + return fmt.Errorf("local: delete %s: %w", name, err) + } + return nil + }); err != nil { + return err + } + } + return nil +} + +// removeFilters detaches the Local filter from every interface of the VPC's +// VRF the model does not want, and returns the ifindexes it does want. +func (p *pass) removeFilters() (map[int]bool, error) { + wanted := map[int]bool{} + for _, l := range p.h.enslaved(p.vrfIdx) { + name := l.Attrs().Name + _, tenant := p.m.tenants[name] + if tenant || p.wantsLink(name) { + wanted[l.Attrs().Index] = true + continue + } + fname, _, ok, err := attach.LocalFilter(l.Attrs().Index) + if err != nil { + return nil, err + } + if err := fix(p.dry, ok, func() error { return attach.DetachLocal(name) }); err != nil { + return nil, fmt.Errorf("local: detach %s from %s: %w", fname, name, err) + } + } + return wanted, nil +} + +// removeRows deletes the Local rows of interfaces that are gone, or are in +// the VPC's VRF and wanted by nothing, and the TAP rows of tenants no +// local.tap claim names. +func (p *pass) removeRows(wanted map[int]bool) error { + for _, name := range sortedKeys(p.m.tenants) { + l := p.h.byName[name] + if p.m.tenants[name].tap || l == nil || l.Attrs().MasterIndex != p.vrfIdx { + continue + } + if err := deleteRow(p.objs.Maps.Tap, uint32(l.Attrs().Index), p.dry); err != nil { + return err + } + } + stale := func(idx uint32) bool { + l := p.h.byIdx[int(idx)] + if l == nil { + return true + } + return p.vrfIdx != 0 && l.Attrs().MasterIndex == p.vrfIdx && !wanted[int(idx)] + } + for _, mp := range []*ebpf.Map{p.objs.Maps.Tap, p.objs.Maps.Link, p.objs.Maps.Pair, p.objs.Maps.Guard} { + keys, err := u32Keys(mp) + if err != nil { + return err + } + for _, idx := range keys { + if !stale(idx) { + continue + } + if err := deleteRow(mp, idx, p.dry); err != nil { + return err + } + } + } + return nil +} + +// removeGuests deletes the VPC's guest rows the model does not want, and +// every guest row whose interface is gone. +func (p *pass) removeGuests() error { + want := map[netip.Addr]bool{} + for _, t := range p.m.tenants { + if t.pair == "" { + continue + } + for _, a := range t.guests { + want[a] = true + } + } + var ( + key localprog.LocalLtGuestKey + val localprog.LocalLtGuestValue + stale []localprog.LocalLtGuestKey + ) + it := p.objs.Maps.Guest.Iterate() + for it.Next(&key, &val) { + mine := p.table != 0 && key.TableId == p.table && !want[netip.AddrFrom16(key.Addr)] + if mine || p.h.byIdx[int(val.LinkIfindex)] == nil { + stale = append(stale, key) + } + } + if err := it.Err(); err != nil { + return fmt.Errorf("local: read guest rows: %w", err) + } + for _, key := range stale { + if err := fix(p.dry, true, func() error { return ignoreMissing(p.objs.Maps.Guest.Delete(key)) }); err != nil { + return err + } + } + return nil +} + +// removePassThrough deletes the VPC's Local pass-through entries no routed +// link wants. +func (p *pass) removePassThrough() error { + if p.table == 0 { + return nil + } + want := map[netip.Prefix]bool{} + for _, r := range p.m.routed { + for _, a := range r.addrs { + want[netip.PrefixFrom(a, 128)] = true + } + } + entries, err := p.routes.Entries(p.table) + if err != nil { + return err + } + for prefix, e := range entries { + if !e.PassThrough || e.Owner != egressroutemap.PassThroughLocal || want[prefix] { + continue + } + if err := fix(p.dry, true, func() error { + _, err := p.routes.UnregisterPassThroughAs(p.table, ipnet(prefix), egressroutemap.PassThroughLocal) + return err + }); err != nil { + return err + } + } + return nil +} diff --git a/internal/worker/local/frames_test.go b/internal/worker/local/frames_test.go new file mode 100644 index 00000000..4e126035 --- /dev/null +++ b/internal/worker/local/frames_test.go @@ -0,0 +1,173 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "encoding/binary" + "net" + "net/netip" +) + +// Frame helpers for the root tests: a TAP guest builds and parses Ethernet +// frames itself, as a hypervisor's guest does. + +const ( + ethHdrLen = 14 + ip6HdrLen = 40 + udpHdrLen = 8 + vnetHdrLen = 10 + protoUDP = 17 + protoICMPv6 = 58 + icmpNS = 135 + icmpNA = 136 + // vnetNeedsCsum is VIRTIO_NET_HDR_F_NEEDS_CSUM. + vnetNeedsCsum = 1 +) + +// udpFrame is one parsed UDP-over-IPv6 frame. +type udpFrame struct { + src, dst netip.Addr + sport, dport uint16 + payload []byte + srcMAC, dstMAC net.HardwareAddr + checksumVerified bool +} + +func sum16(b []byte, s uint32) uint32 { + for i := 0; i+1 < len(b); i += 2 { + s += uint32(binary.BigEndian.Uint16(b[i:])) + } + if len(b)%2 == 1 { + s += uint32(b[len(b)-1]) << 8 + } + return s +} + +func fold(s uint32) uint16 { + for s>>16 != 0 { + s = s&0xffff + s>>16 + } + return uint16(s) +} + +// pseudo sums the IPv6 pseudo-header. +func pseudo(src, dst netip.Addr, proto uint8, l4len int) uint32 { + s16, d16 := src.As16(), dst.As16() + s := sum16(s16[:], 0) + s = sum16(d16[:], s) + s += uint32(l4len) + s += uint32(proto) + return s +} + +// buildIP6 returns an Ethernet frame carrying an IPv6 packet with l4. +func buildIP6(srcMAC, dstMAC net.HardwareAddr, src, dst netip.Addr, proto uint8, hlim uint8, l4 []byte) []byte { + f := make([]byte, ethHdrLen+ip6HdrLen+len(l4)) + copy(f[0:6], dstMAC) + copy(f[6:12], srcMAC) + binary.BigEndian.PutUint16(f[12:], 0x86DD) + ip := f[ethHdrLen:] + ip[0] = 0x60 + binary.BigEndian.PutUint16(ip[4:], uint16(len(l4))) + ip[6] = proto + ip[7] = hlim + s16, d16 := src.As16(), dst.As16() + copy(ip[8:24], s16[:]) + copy(ip[24:40], d16[:]) + copy(ip[40:], l4) + return f +} + +// udp returns a UDP frame. partial leaves the checksum to be finished, as a +// guest with checksum offload hands it over: the field holds the folded +// pseudo-header sum, not its complement. +func udp(srcMAC, dstMAC net.HardwareAddr, src, dst netip.Addr, sport, dport uint16, payload []byte, + partial bool) []byte { + l4 := make([]byte, udpHdrLen+len(payload)) + binary.BigEndian.PutUint16(l4[0:], sport) + binary.BigEndian.PutUint16(l4[2:], dport) + binary.BigEndian.PutUint16(l4[4:], uint16(len(l4))) + copy(l4[8:], payload) + ps := pseudo(src, dst, protoUDP, len(l4)) + if partial { + binary.BigEndian.PutUint16(l4[6:], fold(ps)) + } else { + c := ^fold(sum16(l4, ps)) + if c == 0 { + c = 0xffff + } + binary.BigEndian.PutUint16(l4[6:], c) + } + return buildIP6(srcMAC, dstMAC, src, dst, protoUDP, 64, l4) +} + +// vnet prepends a virtio_net_hdr to frame; partial asks the host to finish +// the UDP checksum. +func vnet(frame []byte, partial bool) []byte { + h := make([]byte, vnetHdrLen, vnetHdrLen+len(frame)) + if partial { + h[0] = vnetNeedsCsum + binary.LittleEndian.PutUint16(h[6:], ethHdrLen+ip6HdrLen) // csum_start + binary.LittleEndian.PutUint16(h[8:], 6) // csum_offset + } + return append(h, frame...) +} + +// parseUDP parses a UDP-over-IPv6 frame, verifying its checksum. +func parseUDP(f []byte) (udpFrame, bool) { + if len(f) < ethHdrLen+ip6HdrLen+udpHdrLen || binary.BigEndian.Uint16(f[12:]) != 0x86DD { + return udpFrame{}, false + } + ip := f[ethHdrLen:] + if ip[6] != protoUDP { + return udpFrame{}, false + } + plen := int(binary.BigEndian.Uint16(ip[4:])) + if len(ip) < ip6HdrLen+plen || plen < udpHdrLen { + return udpFrame{}, false + } + l4 := ip[ip6HdrLen : ip6HdrLen+plen] + src := netip.AddrFrom16([16]byte(ip[8:24])) + dst := netip.AddrFrom16([16]byte(ip[24:40])) + return udpFrame{ + src: src, dst: dst, + sport: binary.BigEndian.Uint16(l4[0:]), dport: binary.BigEndian.Uint16(l4[2:]), + payload: append([]byte(nil), l4[8:]...), + srcMAC: append(net.HardwareAddr(nil), f[6:12]...), dstMAC: append(net.HardwareAddr(nil), f[0:6]...), + checksumVerified: fold(sum16(l4, pseudo(src, dst, protoUDP, len(l4)))) == 0xffff, + }, true +} + +// neighborSolicitation returns the target and the solicitor's address and +// MAC of an ICMPv6 Neighbor Solicitation frame. +func neighborSolicitation(f []byte) (target, from netip.Addr, mac net.HardwareAddr, ok bool) { + if len(f) < ethHdrLen+ip6HdrLen+24 || binary.BigEndian.Uint16(f[12:]) != 0x86DD { + return netip.Addr{}, netip.Addr{}, nil, false + } + ip := f[ethHdrLen:] + if ip[6] != protoICMPv6 || ip[ip6HdrLen] != icmpNS { + return netip.Addr{}, netip.Addr{}, nil, false + } + return netip.AddrFrom16([16]byte(ip[ip6HdrLen+8 : ip6HdrLen+24])), netip.AddrFrom16([16]byte(ip[8:24])), + append(net.HardwareAddr(nil), f[6:12]...), true +} + +// neighborAdvertisement answers a solicitation for target from mac. +func neighborAdvertisement(mac net.HardwareAddr, target, to netip.Addr, toMAC net.HardwareAddr) []byte { + l4 := make([]byte, 32) + l4[0] = icmpNA + l4[4] = 0x60 // solicited, override + t16 := target.As16() + copy(l4[8:24], t16[:]) + l4[24] = 2 // target link-layer address + l4[25] = 1 + copy(l4[26:32], mac) + if !to.IsValid() || to.IsUnspecified() { + to = netip.MustParseAddr("ff02::1") + toMAC = net.HardwareAddr{0x33, 0x33, 0, 0, 0, 1} + } + binary.BigEndian.PutUint16(l4[2:], ^fold(sum16(l4, pseudo(target, to, protoICMPv6, len(l4))))) + return buildIP6(mac, toMAC, target, to, protoICMPv6, 255, l4) +} diff --git a/internal/worker/local/kernel.go b/internal/worker/local/kernel.go new file mode 100644 index 00000000..b6f00d3d --- /dev/null +++ b/internal/worker/local/kernel.go @@ -0,0 +1,644 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "errors" + "fmt" + "net" + "net/netip" + "slices" + "strings" + "sync" + + "github.com/cilium/ebpf" + "github.com/safchain/ethtool" + "github.com/vishvananda/netlink" + "github.com/vishvananda/netns" + "golang.org/x/sys/unix" + + "go.datum.net/galactic/internal/plumbing/ebpf/attach" + "go.datum.net/galactic/internal/plumbing/ebpf/egressroutemap" + "go.datum.net/galactic/internal/plumbing/ebpf/localprog" + "go.datum.net/galactic/internal/plumbing/ebpf/xdpdispatch" + "go.datum.net/galactic/internal/plumbing/intf" +) + +// Filter names, one per Local program. +const ( + filterRx = attach.LocalFilterPrefix + "rx" + filterLinkRx = attach.LocalFilterPrefix + "link_rx" + filterPairRx = attach.LocalFilterPrefix + "pair_rx" + filterLinkGuard = attach.LocalFilterPrefix + "link_guard" +) + +// DefaultLinkMTU is the MTU of the links Local creates. A veth with a larger +// MTU than about 3500 bytes takes no native XDP program, which the NAT end of +// a pair needs (docs/worker/qualification.md). +const DefaultLinkMTU = 1500 + +// The ethtool features of a pair's tenant end. Checksum offload off makes the +// kernel finish a partial checksum, and segment a GSO packet, before the +// packet crosses to the NAT end, whose XDP program rewrites addresses as if +// the checksum were complete. GRO on lets the tenant end receive what the NAT +// end's native XDP_REDIRECT sends it. +var tenantFeatures = map[string]bool{featureTxChecksum: false, featureGRO: true} + +// ethtool feature names. +const ( + featureTxChecksum = "tx-checksum-ip-generic" + featureGRO = "rx-gro" +) + +// Link types, as netlink reports them. +const ( + linkVeth = "veth" + linkBond = "bond" + linkVLAN = "vlan" + linkTunTap = "tuntap" + linkVRF = "vrf" +) + +// errDirty stops a dry run at the first change it would make. +var errDirty = errors.New("local: the host differs from desired") + +// Kernel is the Local module's host access, in the calling thread's network +// namespace, which must be the host's. +type Kernel struct { + // PinDir is the bpffs directory of the pinned uSID maps. + PinDir string + // LocalPinDir is the bpffs directory of the Local maps. + LocalPinDir string + // DispatchDir is the XDP dispatcher's pin directory. + DispatchDir string + // Pods opens a routed link owner's pod network namespace. + Pods PodNetns + // LinkMTU is the MTU of the links Local creates; DefaultLinkMTU when 0. + LinkMTU int + + mu sync.Mutex + objs *localprog.Objects + loadErr error + routes *egressroutemap.EgressRouteTable + rclose interface{ Close() error } + progIDs map[string]ebpf.ProgramID + // receivers are the devices local_rx was last attached to. + receivers map[string]struct{} + // swept is set once a stale local_rx left by an earlier Worker on a + // device that is no longer a receiver has been looked for. + swept bool +} + +// Close releases the Kernel's descriptors. Pinned maps and filters stay. +func (k *Kernel) Close() error { + k.mu.Lock() + defer k.mu.Unlock() + var errs []error + if k.objs != nil { + errs = append(errs, k.objs.Close()) + k.objs = nil + } + if k.rclose != nil { + errs = append(errs, k.rclose.Close()) + k.rclose, k.routes = nil, nil + } + return errors.Join(errs...) +} + +func (k *Kernel) mtu() int { + if k.LinkMTU > 0 { + return k.LinkMTU + } + return DefaultLinkMTU +} + +// open loads the Local programs and opens egress_route_table on first use, +// and again after a failure. +func (k *Kernel) open() (*localprog.Objects, *egressroutemap.EgressRouteTable, error) { + k.mu.Lock() + defer k.mu.Unlock() + if k.objs == nil { + objs, err := localprog.Load(k.PinDir, k.LocalPinDir) + if err != nil { + k.loadErr = err + return nil, nil, err + } + ids := map[string]ebpf.ProgramID{} + for name, p := range map[string]*ebpf.Program{filterRx: objs.Programs.Rx, filterLinkRx: objs.Programs.LinkRx, + filterPairRx: objs.Programs.PairRx, filterLinkGuard: objs.Programs.LinkGuard} { + info, err := p.Info() + if err != nil { + _ = objs.Close() + return nil, nil, fmt.Errorf("local: read program %s: %w", name, err) + } + id, _ := info.ID() + ids[name] = id + } + k.objs, k.progIDs, k.loadErr = objs, ids, nil + } + if k.routes == nil { + t, c, err := egressroutemap.OpenPinnedEgressRouteTable(k.PinDir) + if err != nil { + return nil, nil, err + } + k.routes, k.rclose = t, c + } + return k.objs, k.routes, nil +} + +// Loaded returns nil when the Local programs are loaded. +func (k *Kernel) Loaded() error { + _, _, err := k.open() + return err +} + +func (k *Kernel) program(name string) *ebpf.Program { + switch name { + case filterRx: + return k.objs.Programs.Rx + case filterLinkRx: + return k.objs.Programs.LinkRx + case filterPairRx: + return k.objs.Programs.PairRx + default: + return k.objs.Programs.LinkGuard + } +} + +// filterCurrent reports whether ifindex carries the Local filter name with +// the program this Kernel loaded. +func (k *Kernel) filterCurrent(ifindex int, name string) (bool, error) { + got, id, ok, err := attach.LocalFilter(ifindex) + if err != nil || !ok { + return false, err + } + k.mu.Lock() + want := k.progIDs[name] + k.mu.Unlock() + return got == name && id == want, nil +} + +// ensureFilter attaches the Local filter name to link unless it is current. +func (k *Kernel) ensureFilter(link netlink.Link, name string, dry bool) error { + ok, err := k.filterCurrent(link.Attrs().Index, name) + if err != nil || ok { + return err + } + if dry { + return errDirty + } + if err := attach.AttachLocal(k.program(name), link.Attrs().Name, name); err != nil { + return fmt.Errorf("local: attach %s to %s: %w", name, link.Attrs().Name, err) + } + return nil +} + +// TableID returns vpc's host VRF table and ifindex, and false when the VRF +// does not exist. +func TableID(vpc string) (uint32, int, bool, error) { + l, err := netlink.LinkByName(intf.GenerateInterfaceNameVRF(vpc)) + if err != nil { + var nf netlink.LinkNotFoundError + if errors.As(err, &nf) { + return 0, 0, false, nil + } + return 0, 0, false, fmt.Errorf("local: look up VRF of %s: %w", vpc, err) + } + v, ok := l.(*netlink.Vrf) + if !ok { + return 0, 0, false, fmt.Errorf("local: %s is not a VRF", l.Attrs().Name) + } + return v.Table, v.Attrs().Index, true, nil +} + +// host is what one pass read of the links on the host. +type host struct { + all []netlink.Link + byName map[string]netlink.Link + byIdx map[int]netlink.Link +} + +func readHost() (*host, error) { + links, err := netlink.LinkList() + if err != nil { + return nil, fmt.Errorf("local: list links: %w", err) + } + h := &host{all: links, byName: map[string]netlink.Link{}, byIdx: map[int]netlink.Link{}} + for _, l := range links { + h.byName[l.Attrs().Name] = l + h.byIdx[l.Attrs().Index] = l + } + return h, nil +} + +// localLinks returns the Local links of vpc, by name. +func (h *host) localLinks(vpc string) map[string]netlink.Link { + out := map[string]netlink.Link{} + for _, l := range h.all { + if v, _, ok := parseAlias(l.Attrs().Alias); ok && v == vpc && intf.IsLocalLinkName(l.Attrs().Name) { + out[l.Attrs().Name] = l + } + } + return out +} + +// enslaved returns the links whose master is vrfIdx. +func (h *host) enslaved(vrfIdx int) []netlink.Link { + var out []netlink.Link + for _, l := range h.all { + if vrfIdx != 0 && l.Attrs().MasterIndex == vrfIdx { + out = append(out, l) + } + } + return out +} + +// pair is a pair as the host holds it. +type pair struct { + tenant, nat netlink.Link +} + +// readPair returns p's links when both exist, belong to p's claim and are +// each other's peer. +func (h *host) readPair(p pairWant) (pair, bool) { + t, nat := h.byName[p.tenant], h.byName[p.nat] + if t == nil || nat == nil || t.Type() != linkVeth || nat.Type() != linkVeth || + t.Attrs().Alias != alias(p.key) || nat.Attrs().Alias != alias(p.key) { + return pair{}, false + } + peer, err := netlink.VethPeerIndex(t.(*netlink.Veth)) + if err != nil || peer != nat.Attrs().Index { + return pair{}, false + } + return pair{tenant: t, nat: nat}, true +} + +// collision returns an error when a link named name belongs to another claim +// than the one alias a names. +func (h *host) collision(name, a string) error { + if l := h.byName[name]; l != nil && l.Attrs().Alias != a { + return fmt.Errorf("local: link %s belongs to %q, not %q", name, l.Attrs().Alias, a) + } + return nil +} + +// ensurePair makes p exist in the VPC's VRF vrfIdx, up, with the tenant end's +// features set. +func (k *Kernel) ensurePair(h *host, p pairWant, vrfIdx int, dry bool) (pair, error) { + got, ok := h.readPair(p) + if !ok { + if dry { + return pair{}, errDirty + } + var err error + if got, err = k.createPair(h, p); err != nil { + return pair{}, err + } + } + if err := placeInVRF(got.tenant, vrfIdx, dry); err != nil { + return got, err + } + if err := fix(dry, got.nat.Attrs().Flags&net.FlagUp == 0, func() error { + if err := netlink.LinkSetUp(got.nat); err != nil { + return fmt.Errorf("local: set %s up: %w", p.nat, err) + } + return nil + }); err != nil { + return got, err + } + return got, ensureFeatures(p.tenant, dry) +} + +// createPair creates p, replacing whatever is left of it. +func (k *Kernel) createPair(h *host, p pairWant) (pair, error) { + for _, n := range []string{p.tenant, p.nat} { + if err := h.collision(n, alias(p.key)); err != nil { + return pair{}, err + } + if l := h.byName[n]; l != nil { + if err := netlink.LinkDel(l); err != nil && !errors.Is(err, unix.ENODEV) { + return pair{}, fmt.Errorf("local: delete incomplete pair link %s: %w", n, err) + } + } + } + v := &netlink.Veth{LinkAttrs: netlink.LinkAttrs{Name: p.tenant, MTU: k.mtu()}, PeerName: p.nat} + if err := netlink.LinkAdd(v); err != nil { + return pair{}, fmt.Errorf("local: create pair %s/%s: %w", p.tenant, p.nat, err) + } + var got pair + for _, n := range []string{p.tenant, p.nat} { + l, err := netlink.LinkByName(n) + if err != nil { + return pair{}, fmt.Errorf("local: look up new pair link %s: %w", n, err) + } + if err := netlink.LinkSetAlias(l, alias(p.key)); err != nil { + return pair{}, fmt.Errorf("local: mark pair link %s: %w", n, err) + } + if n == p.tenant { + got.tenant = l + } else { + got.nat = l + } + } + return got, nil +} + +// ensureFeatures sets tenantFeatures on name. +func ensureFeatures(name string, dry bool) error { + et, err := ethtool.NewEthtool() + if err != nil { + return fmt.Errorf("local: open ethtool: %w", err) + } + defer et.Close() + cur, err := et.Features(name) + if err != nil { + return fmt.Errorf("local: read features of %s: %w", name, err) + } + change := map[string]bool{} + for f, want := range tenantFeatures { + if have, ok := cur[f]; ok && have != want { + change[f] = want + } + } + if len(change) == 0 { + return nil + } + if dry { + return errDirty + } + if err := et.Change(name, change); err != nil { + return fmt.Errorf("local: set features %v on %s: %w", change, name, err) + } + return nil +} + +// routedLink is a routed link as the host holds it. +type routedLink struct { + host netlink.Link + // podIndex is the pod end's ifindex in the pod's namespace. + podIndex int +} + +// readRouted returns r's host end when it belongs to r's claim and its peer +// is in podNS. +func (h *host) readRouted(r routedWant, podNS netns.NsHandle) (routedLink, bool) { + l := h.byName[r.host] + if l == nil || l.Type() != linkVeth || l.Attrs().Alias != alias(r.key) { + return routedLink{}, false + } + want, err := netlink.GetNetNsIdByFd(int(podNS)) + if err != nil || want < 0 || l.Attrs().NetNsID != want { + return routedLink{}, false + } + peer, err := netlink.VethPeerIndex(l.(*netlink.Veth)) + if err != nil { + return routedLink{}, false + } + return routedLink{host: l, podIndex: peer}, true +} + +// setUpInPod marks the pod end name in podNS with a and sets it up. The pod +// configures everything else on it. +func setUpInPod(podNS netns.NsHandle, name, a string) error { + nh, err := netlink.NewHandleAt(podNS) + if err != nil { + return fmt.Errorf("local: open the pod's netlink: %w", err) + } + defer nh.Close() //nolint:errcheck // our own descriptor + l, err := nh.LinkByName(name) + if err != nil { + return fmt.Errorf("local: look up pod end %s: %w", name, err) + } + if err := nh.LinkSetAlias(l, a); err != nil { + return fmt.Errorf("local: mark pod end %s: %w", name, err) + } + if err := nh.LinkSetUp(l); err != nil { + return fmt.Errorf("local: set pod end %s up: %w", name, err) + } + return nil +} + +func ipnet(p netip.Prefix) *net.IPNet { + return &net.IPNet{IP: net.IP(p.Addr().AsSlice()), Mask: net.CIDRMask(p.Bits(), p.Addr().BitLen())} +} + +// pairTenantOf returns the tenant end's name for a pair's NAT end name. +func pairTenantOf(nat string) string { + if !strings.HasSuffix(nat, intf.LocalRolePairNAT) { + return "" + } + return strings.TrimSuffix(nat, intf.LocalRolePairNAT) + intf.LocalRolePairTenant +} + +func deleteRow(mp *ebpf.Map, idx uint32, dry bool) error { + v, err := mp.LookupBytes(idx) + if err != nil { + return fmt.Errorf("local: read %s: %w", mp.String(), err) + } + if v == nil { + return nil + } + if dry { + return errDirty + } + return ignoreMissing(mp.Delete(idx)) +} + +func ignoreMissing(err error) error { + if errors.Is(err, ebpf.ErrKeyNotExist) { + return nil + } + return err +} + +func u32Keys(mp *ebpf.Map) ([]uint32, error) { + var ( + key uint32 + keys []uint32 + ) + val := make([]byte, mp.ValueSize()) + it := mp.Iterate() + for it.Next(&key, val) { + keys = append(keys, key) + } + if err := it.Err(); err != nil { + return nil, fmt.Errorf("local: read %s: %w", mp.String(), err) + } + return keys, nil +} + +// purgeFlows deletes the local.tap flows of every interface with no lt_link +// row. +func (k *Kernel) purgeFlows() error { + objs, _, err := k.open() + if err != nil { + return err + } + links, err := u32Keys(objs.Maps.Link) + if err != nil { + return err + } + var ( + key localprog.LocalLtFlowKey + val localprog.LocalLtFlowValue + dead []localprog.LocalLtFlowKey + ) + it := objs.Maps.Flow.Iterate() + for it.Next(&key, &val) { + if !slices.Contains(links, key.LinkIfindex) { + dead = append(dead, key) + } + } + if err := it.Err(); err != nil { + return fmt.Errorf("local: read flows: %w", err) + } + for _, d := range dead { + if err := ignoreMissing(objs.Maps.Flow.Delete(d)); err != nil { + return err + } + } + return nil +} + +func sortedKeys[V any](m map[string]V) []string { + out := make([]string, 0, len(m)) + for k := range m { + out = append(out, k) + } + slices.Sort(out) + return out +} + +// receiver is one device local_rx runs on. +type receiver struct { + name string + idx int + mtu int + // slotErr is nil when a live public slot covers the device, or the + // device it receives through. + slotErr error +} + +// receiverDevices returns the devices local_rx belongs on: for each +// interface whose XDP dispatcher has the public role, the device its traffic +// reaches tc on. That is its bond master when it is a bond member, and the +// VLAN devices above that when there are any, since native XDP takes no VLAN +// device and the dispatcher runs on the lower one (contract amendment). +func (k *Kernel) receiverDevices(h *host) ([]receiver, error) { + in, err := xdpdispatch.Inspect(k.DispatchDir) + if errors.Is(err, xdpdispatch.ErrNoDispatcher) { + return nil, nil + } + if err != nil { + return nil, err + } + defer in.Close() //nolint:errcheck // our own descriptors + public, err := in.Interfaces(xdpdispatch.RolePublicLB) + if err != nil { + return nil, err + } + byIdx := map[int]*receiver{} + for _, ifx := range public { + l := h.byIdx[ifx] + if l == nil { + continue + } + slotErr := in.Claimed(ifx, xdpdispatch.SlotGatewayLB) + target := l + if m := h.byIdx[l.Attrs().MasterIndex]; m != nil && m.Type() == linkBond { + target = m + } + var vlans []netlink.Link + for _, c := range h.all { + if c.Type() == linkVLAN && c.Attrs().ParentIndex == target.Attrs().Index { + vlans = append(vlans, c) + } + } + if len(vlans) == 0 { + vlans = []netlink.Link{target} + } + for _, d := range vlans { + r := byIdx[d.Attrs().Index] + if r == nil { + r = &receiver{name: d.Attrs().Name, idx: d.Attrs().Index, mtu: d.Attrs().MTU, slotErr: slotErr} + byIdx[d.Attrs().Index] = r + } else if slotErr == nil { + r.slotErr = nil + } + } + } + out := make([]receiver, 0, len(byIdx)) + for _, r := range byIdx { + out = append(out, *r) + } + slices.SortFunc(out, func(a, b receiver) int { return strings.Compare(a.name, b.name) }) + return out, nil +} + +// ensureReceivers attaches local_rx to every receiving device when want, and +// removes it from every device it is on otherwise or that is no longer one. +func (k *Kernel) ensureReceivers(want, dry bool) error { + if _, _, err := k.open(); err != nil { + return err + } + h, err := readHost() + if err != nil { + return err + } + rs, err := k.receiverDevices(h) + if err != nil { + return err + } + k.mu.Lock() + prev := k.receivers + swept := k.swept + k.mu.Unlock() + if !swept { + // An earlier Worker may have left local_rx anywhere outside a VRF. + prev = map[string]struct{}{} + for _, l := range h.all { + if l.Attrs().MasterIndex != 0 || l.Type() == linkTunTap || l.Type() == linkVRF { + continue + } + if name, _, ok, err := attach.LocalFilter(l.Attrs().Index); err == nil && ok && name == filterRx { + prev[l.Attrs().Name] = struct{}{} + } + } + } + now := map[string]struct{}{} + for _, r := range rs { + if !want { + continue + } + now[r.name] = struct{}{} + if err := k.ensureFilter(h.byIdx[r.idx], filterRx, dry); err != nil { + return err + } + } + for name := range prev { + if _, ok := now[name]; ok { + continue + } + if l := h.byName[name]; l != nil { + if fname, _, ok, err := attach.LocalFilter(l.Attrs().Index); err != nil { + return err + } else if !ok || fname != filterRx { + continue + } + } + if dry { + return errDirty + } + if err := attach.DetachLocal(name); err != nil { + return err + } + } + if !dry { + k.mu.Lock() + k.receivers, k.swept = now, true + k.mu.Unlock() + } + return nil +} diff --git a/internal/worker/local/kernel_root_test.go b/internal/worker/local/kernel_root_test.go new file mode 100644 index 00000000..4c58ccf1 --- /dev/null +++ b/internal/worker/local/kernel_root_test.go @@ -0,0 +1,136 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "fmt" + "testing" + + workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" + "go.datum.net/galactic/internal/plumbing/ebpf/xdpmode" + "go.datum.net/galactic/internal/worker/module" +) + +// wantReady fails unless every destination of claims is Ready in st. +func wantReady(t *testing.T, st module.State, claims []module.Claim) { + t.Helper() + for _, c := range claims { + for _, d := range c.Destinations { + got, ok := st[c.Key][d.ID] + if !ok || !got.Programmed || !got.Ready || !got.ForwardReady || !got.ReturnReady { + t.Fatalf("%s %s = %+v (present %t), want ready", c.Key, d.ID, got, ok) + } + } + } +} + +// wantState fails unless claim c's only destination reports reason with +// the given programmed, forward and return readiness. +func wantState(t *testing.T, st module.State, c module.Claim, programmed, fwd, ret bool, reason string) { + t.Helper() + got := st[c.Key][c.Destinations[0].ID] + if got.Programmed != programmed || got.ForwardReady != fwd || got.ReturnReady != ret || got.Reason != reason { + t.Fatalf("%s = %+v, want programmed %t forward %t return %t reason %q", c.Key, got, programmed, fwd, ret, + reason) + } +} + +// cells are the receiving devices and XDP modes local.tap and +// local.veth_pair are qualified on (docs/worker/qualification.md). The NAT +// end of a pair always runs native. +var cells = []struct { + name string + mode xdpmode.Mode +}{ + {"plain", xdpmode.Native}, + {"plain", xdpmode.Generic}, + {cellVLAN, xdpmode.Native}, + {cellVLAN, xdpmode.Generic}, + {cellBond, xdpmode.Native}, + {cellBond, xdpmode.Generic}, +} + +// TestEntryPathsRoot injects frames on every supported entry path and checks +// guest delivery, or a policy denial, at both VPCs' TAPs, whose guests use the +// same address: a public client through the dispatcher into local.tap and +// the guest's reply back, a guest's flow through local.veth_pair and the NAT +// stand-in to the client, and the client's reply back through the pair. +func TestEntryPathsRoot(t *testing.T) { + for _, cell := range cells { + t.Run(fmt.Sprintf("%s-%s", cell.name, cell.mode), func(t *testing.T) { + r := newRig(t, cell.name+"-"+cell.mode.String(), cell.mode) + for _, v := range r.vpcs { + claims := r.claims(v) + st := r.reconcile(v.vpc, claims) + wantReady(t, st, claims[:1]) + // The pair is programmed, but its return needs the NAT + // program on the NAT end. + wantState(t, st, claims[1], true, true, false, workerv1alpha1.ReasonHandoffHookMissing) + r.natStandIn(v) + wantReady(t, r.reconcile(v.vpc, claims), claims) + if !r.planEmpty(v.vpc, claims) { + t.Fatalf("VPC %s: a second plan would write again", v.vpc) + } + } + sock := r.clientSocket(40000) + for _, v := range r.vpcs { + other := r.vpcs[0] + if other == v { + other = r.vpcs[1] + } + // local.tap: the VIP's request reaches only this VPC's + // guest, and the guest's reply from the VIP reaches the + // client. + req := "tap-request-" + v.vpc + sock.send(t, v.vip, 7, req) + got := v.guest.expect(t, req) + if got.dst != v.vip || got.src != client { + t.Fatalf("the guest received %s -> %s, want %s -> %s", got.src, got.dst, client, v.vip) + } + other.guest.absent(t, req) + reply := "tap-reply-" + v.vpc + v.guest.send(t, v.vip, client, 7, 40000, reply, false) + sock.expect(t, v.vip, reply) + + // Policy on the PublicService path: port 9 is denied toward + // the guest; port 8 is delivered, and the guest's reply from + // it denied. + sock.send(t, v.vip, 9, "tap-denied-in-"+v.vpc) + v.guest.absent(t, "tap-denied-in-"+v.vpc) + sock.send(t, v.vip, 8, "tap-open-"+v.vpc) + v.guest.expect(t, "tap-open-"+v.vpc) + v.guest.send(t, v.vip, client, 8, 40000, "tap-denied-out-"+v.vpc, false) + sock.absent(t, "tap-denied-out-"+v.vpc) + + // local.veth_pair: the guest's flow leaves as the shard + // address, and the client's reply returns to this guest + // only. + flow := "nat-flow-" + v.vpc + v.guest.send(t, guestAddr, client, 5555, 40000, flow, false) + sock.expect(t, v.shard, flow) + back := "nat-return-" + v.vpc + sock.send(t, v.shard, 5555, back) + got = v.guest.expect(t, back) + if got.dst != guestAddr || got.dport != 5555 { + t.Fatalf("the NAT return reached the guest as %s:%d", got.dst, got.dport) + } + other.guest.absent(t, back) + + // Policy on the PublicNAT path: port 9 is denied both ways. + v.guest.send(t, guestAddr, client, 5555, 9, "nat-denied-out-"+v.vpc, false) + sock.absent(t, "nat-denied-out-"+v.vpc) + nine := r.clientSocket(9) + nine.send(t, v.shard, 5555, "nat-denied-in-"+v.vpc) + v.guest.absent(t, "nat-denied-in-"+v.vpc) + _ = nine.conn.Close() + } + s := r.stats() + if s["rx_deliver"] == 0 || s["rx_deny"] == 0 || s["pair_deliver"] == 0 || s["pair_deny"] == 0 || + s["link_reply"] == 0 || s["link_reply_deny"] == 0 || s["link_nat"] == 0 || s["link_nat_deny"] == 0 { + t.Fatalf("counters %v: a path was never taken", s) + } + }) + } +} diff --git a/internal/worker/local/lifecycle_root_test.go b/internal/worker/local/lifecycle_root_test.go new file mode 100644 index 00000000..f154e22b --- /dev/null +++ b/internal/worker/local/lifecycle_root_test.go @@ -0,0 +1,586 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "context" + "errors" + "net" + "net/netip" + "path/filepath" + "testing" + "time" + + "github.com/cilium/ebpf" + "github.com/containernetworking/plugins/pkg/ns" + "github.com/safchain/ethtool" + "github.com/vishvananda/netlink" + "golang.org/x/sys/unix" + + workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" + "go.datum.net/galactic/internal/plumbing/ebpf/attach" + "go.datum.net/galactic/internal/plumbing/ebpf/xdpdispatch" + "go.datum.net/galactic/internal/plumbing/ebpf/xdpmode" + "go.datum.net/galactic/internal/plumbing/intf" + "go.datum.net/galactic/internal/worker/module" +) + +// readyRig returns a plain native rig whose VPCs have a ready local.tap and +// local.veth_pair claim, with the NAT stand-in in place. +func readyRig(t *testing.T, cell string) *rig { + t.Helper() + r := newRig(t, cell, xdpmode.Native) + for _, v := range r.vpcs { + r.reconcile(v.vpc, r.claims(v)) + r.natStandIn(v) + wantReady(t, r.reconcile(v.vpc, r.claims(v)), r.claims(v)) + } + return r +} + +// read reads vpc's state without planning, as after a change Worker has not +// reconciled yet. +func (r *rig) read(vpc string) module.State { + r.t.Helper() + var st module.State + r.in(r.node, func() error { + var err error + st, err = r.mod.Read(context.Background(), module.Scope{VPC: vpc}) + return err + }) + return st +} + +// TestUntrustedEntryRoot checks that a packet that is not claimed, or claims +// a handoff it was not given, enters none: metadata with a wrong magic, as a +// sender without the dispatcher could forge it at best; metadata naming a TAP +// no claim authorizes; a NAT return toward an address no claim delivers to; +// and a packet straight to a guest address, which public ingress cannot +// reach at all. +func TestUntrustedEntryRoot(t *testing.T) { + r := readyRig(t, "trust") + a := r.vpcs[0] + // A TAP in VPC A that no claim names. + stray := &vpcRig{vpc: a.vpc, argument: 0x90, table: a.table} + stray.tap = intf.GenerateInterfaceNameHost(a.vpc, "002") + r.addTap(stray) + sock := r.clientSocket(40000) + + forged := netip.MustParseAddr("2001:db8:4135:a::f0") + r.vip(forged, a.tapIdx, 0x0bad0bad) + before := r.stats() + sock.send(t, forged, 7, "forged-magic") + a.guest.absent(t, "forged-magic") + + unclaimed := netip.MustParseAddr("2001:db8:4135:a::f1") + r.vip(unclaimed, stray.tapIdx, 0) + sock.send(t, unclaimed, 7, "unclaimed-tap") + stray.guest.absent(t, "unclaimed-tap") + + r.in(r.client, func() error { + l, err := netlink.LinkByName(r.clientIf) + if err != nil { + return err + } + return netlink.RouteAdd(&netlink.Route{LinkIndex: l.Attrs().Index, + Dst: ipnet(netip.MustParsePrefix("fd20::/16")), Gw: net.IP(nodeAddr.AsSlice())}) + }) + sock.send(t, guestAddr, 7, "straight-to-guest") + a.guest.absent(t, "straight-to-guest") + r.vpcs[1].guest.absent(t, "straight-to-guest") + + after := r.stats() + if after["rx_no_meta"] <= before["rx_no_meta"] || after["rx_unclaimed"] != before["rx_unclaimed"]+1 { + t.Fatalf("counters before %v after %v: the forged and unclaimed packets were not refused", before, after) + } + if after["rx_deliver"] != before["rx_deliver"] { + t.Fatalf("an untrusted packet was delivered: before %v after %v", before, after) + } + + // The NAT stand-in sends a return for an address no claim names into + // VPC A's pair; the pair delivers it nowhere. + ghost := netip.MustParseAddr("2001:db8:4135:5::f2") + ret, err := r.fixShard(a.shard) + if err != nil { + t.Fatal(err) + } + ret.Guest = netip.MustParseAddr("fd20:80:ff03::99").As16() + if err := r.fixPutShard(ghost, ret); err != nil { + t.Fatal(err) + } + before = r.stats() + sock.send(t, ghost, 5555, "ghost-return") + a.guest.absent(t, "ghost-return") + stray.guest.absent(t, "ghost-return") + after = r.stats() + if after["pair_unclaimed"] <= before["pair_unclaimed"] || after["pair_deliver"] != before["pair_deliver"] { + t.Fatalf("counters before %v after %v: the unclaimed return was not refused", before, after) + } +} + +// TestHookWithdrawalAndRepairRoot checks that each hook a handoff depends on +// withdraws readiness when it goes, and that Local's own hooks are put back. +func TestHookWithdrawalAndRepairRoot(t *testing.T) { + r := readyRig(t, "hooks") + a := r.vpcs[0] + claims := r.claims(a) + tapClaim, natClaim := claims[0], claims[1] + pairTenant := linkName(a.vpc, a.natUID, intf.LocalRolePairTenant) + pairNAT := linkName(a.vpc, a.natUID, intf.LocalRolePairNAT) + + // Local's program on the TAP: both handoffs lose their return. + r.in(r.node, func() error { return attach.DetachLocal(a.tap) }) + st := r.read(a.vpc) + wantState(t, st, tapClaim, true, true, false, workerv1alpha1.ReasonHandoffHookMissing) + wantState(t, st, natClaim, true, true, false, workerv1alpha1.ReasonHandoffHookMissing) + if r.planEmpty(a.vpc, claims) { + t.Fatal("a missing Local filter planned no repair") + } + wantReady(t, r.reconcile(a.vpc, claims), claims) + + // local_rx on the receiving device: local.tap loses its forward path. + r.in(r.node, func() error { return attach.DetachLocal(r.rx) }) + wantState(t, r.read(a.vpc), tapClaim, true, false, true, workerv1alpha1.ReasonHandoffHookMissing) + wantReady(t, r.reconcile(a.vpc, claims), claims) + + // Local's program on the pair's tenant end: the pair loses its forward + // path. + r.in(r.node, func() error { return attach.DetachLocal(pairTenant) }) + wantState(t, r.read(a.vpc), natClaim, true, false, true, workerv1alpha1.ReasonHandoffHookMissing) + wantReady(t, r.reconcile(a.vpc, claims), claims) + + // The dispatcher's public slot: an empty or expired slot is no + // receiving path, and Local cannot repair it. + r.in(r.node, func() error { + lock, err := r.disp.Lock(context.Background()) + if err != nil { + return err + } + defer lock.Unlock() + return lock.Clear(xdpdispatch.SlotGatewayLB) + }) + wantState(t, r.reconcile(a.vpc, claims), tapClaim, true, false, true, workerv1alpha1.ReasonDispatcherSlotUnclaimed) + r.in(r.node, func() error { + lock, err := r.disp.Lock(context.Background()) + if err != nil { + return err + } + defer lock.Unlock() + return lock.Fill(xdpdispatch.SlotGatewayLB, r.fix.LtfGateway) + }) + wantReady(t, r.reconcile(a.vpc, claims), claims) + + // The client's program on the NAT end: gone, then generic, which never + // sees what Local redirects into the pair. + r.in(r.node, func() error { + l, err := netlink.LinkByName(pairNAT) + if err != nil { + return err + } + return netlink.LinkSetXdpFd(l, -1) + }) + wantState(t, r.reconcile(a.vpc, claims), natClaim, true, true, false, workerv1alpha1.ReasonHandoffHookMissing) + r.in(r.node, func() error { + l, err := netlink.LinkByName(pairNAT) + if err != nil { + return err + } + return netlink.LinkSetXdpFdWithFlags(l, r.fix.LtfNat.FD(), 1<<1) // XDP_FLAGS_SKB_MODE + }) + wantState(t, r.reconcile(a.vpc, claims), natClaim, true, true, false, workerv1alpha1.ReasonHookUnsupported) + r.in(r.node, func() error { + l, err := netlink.LinkByName(pairNAT) + if err != nil { + return err + } + if err := netlink.LinkSetXdpFdWithFlags(l, -1, 1<<1); err != nil { // XDP_FLAGS_SKB_MODE + return err + } + return netlink.LinkSetXdpFdWithFlags(l, r.fix.LtfNat.FD(), xdpDrvMode) + }) + wantReady(t, r.reconcile(a.vpc, claims), claims) + + // galactic-cni's chain, as another tc owner adopting the TAP removes + // it: Local reports the interface missing and does not write CNI's + // filters itself. + r.in(r.node, func() error { + l, err := netlink.LinkByName(a.tap) + if err != nil { + return err + } + filters, err := netlink.FilterList(l, netlink.HANDLE_MIN_EGRESS) + if err != nil { + return err + } + for _, f := range filters { + if err := netlink.FilterDel(f); err != nil { + return err + } + } + return nil + }) + wantState(t, r.reconcile(a.vpc, claims), tapClaim, true, false, false, workerv1alpha1.ReasonHandoffInterfaceMissing) + r.in(r.node, func() error { return attach.AttachDeliver(r.usid.TpDeliver, a.tap) }) + wantReady(t, r.reconcile(a.vpc, claims), claims) + + // A TAP whose MTU is below the receiving device's would lose what the + // redirect does not check. + r.in(r.node, func() error { + l, err := netlink.LinkByName(a.tap) + if err != nil { + return err + } + return netlink.LinkSetMTU(l, 1280) + }) + wantState(t, r.reconcile(a.vpc, claims), tapClaim, true, false, true, workerv1alpha1.ReasonHandoffMTUTooSmall) + r.in(r.node, func() error { + l, err := netlink.LinkByName(a.tap) + if err != nil { + return err + } + return netlink.LinkSetMTU(l, 1500) + }) + wantReady(t, r.reconcile(a.vpc, claims), claims) +} + +// TestColdNeighborRoot checks that delivery to a TAP whose guest has no +// neighbor entry resolves the neighbor and delivers, on both handoffs. +func TestColdNeighborRoot(t *testing.T) { + r := readyRig(t, "neigh") + a := r.vpcs[0] + flush := func() { + r.in(r.node, func() error { + err := netlink.NeighDel(&netlink.Neigh{LinkIndex: a.tapIdx, Family: netlink.FAMILY_V6, + IP: net.IP(guestAddr.AsSlice())}) + if err != nil && !errors.Is(err, unix.ENOENT) { + return err + } + return nil + }) + } + sock := r.clientSocket(40000) + flush() + sock.send(t, a.vip, 7, "cold-tap") + a.guest.expect(t, "cold-tap") + flush() + sock.send(t, a.shard, 5555, "cold-nat") + a.guest.expect(t, "cold-nat") + r.in(r.node, func() error { + neighs, err := netlink.NeighList(a.tapIdx, netlink.FAMILY_V6) + if err != nil { + return err + } + for _, n := range neighs { + if n.IP.Equal(net.IP(guestAddr.AsSlice())) && n.HardwareAddr.String() == guestMAC.String() { + return nil + } + } + t.Fatalf("the guest's neighbor was not resolved: %v", neighs) + return nil + }) +} + +// TestIfindexReplacementRoot checks that a TAP CNI replaces under the same +// name, with a new ifindex, is reprogrammed and delivers again, and that the +// old ifindex's rows go. +func TestIfindexReplacementRoot(t *testing.T) { + r := readyRig(t, "replace") + a := r.vpcs[0] + claims := r.claims(a) + old := a.tapIdx + a.guest.close() + r.in(r.node, func() error { + for range 50 { + if _, err := netlink.LinkByName(a.tap); err != nil { + return nil + } + time.Sleep(20 * time.Millisecond) + } + return errors.New("the TAP outlived its reader") + }) + st := r.read(a.vpc) + wantState(t, st, claims[0], false, false, false, workerv1alpha1.ReasonHandoffInterfaceMissing) + r.addTap(a) + if a.tapIdx == old { + t.Fatalf("the replacement TAP kept ifindex %d", old) + } + r.vip(a.vip, a.tapIdx, 0) + wantState(t, r.read(a.vpc), claims[0], false, false, false, workerv1alpha1.ReasonPending) + if r.planEmpty(a.vpc, claims) { + t.Fatal("a replaced TAP planned nothing") + } + wantReady(t, r.reconcile(a.vpc, claims), claims) + + sock := r.clientSocket(40000) + sock.send(t, a.vip, 7, "after-replace-tap") + a.guest.expect(t, "after-replace-tap") + a.guest.send(t, a.vip, client, 7, 40000, "after-replace-reply", false) + sock.expect(t, a.vip, "after-replace-reply") + sock.send(t, a.shard, 5555, "after-replace-nat") + a.guest.expect(t, "after-replace-nat") + + for _, name := range []string{"lt_tap", "lt_link"} { + m, err := ebpf.LoadPinnedMap(filepath.Join(r.pin, "local", name), nil) + if err != nil { + t.Fatal(err) + } + v, err := m.LookupBytes(uint32(old)) + _ = m.Close() + if err != nil || v != nil { + t.Fatalf("%s kept the old ifindex %d's row (%v)", name, old, err) + } + } +} + +// TestPartialChecksumRoot checks the pair's tenant end finishes a guest's +// partial checksum before the NAT program rewrites the address, which a +// rewrite in XDP otherwise corrupts (docs/worker/qualification.md). +func TestPartialChecksumRoot(t *testing.T) { + r := readyRig(t, "csum") + a := r.vpcs[0] + claims := r.claims(a) + sock := r.clientSocket(40000) + a.guest.send(t, guestAddr, client, 5555, 40000, "partial-1", true) + sock.expect(t, a.shard, "partial-1") + + // Without the setting, the same frame reaches the client corrupted and + // its kernel drops it. + tenant := linkName(a.vpc, a.natUID, intf.LocalRolePairTenant) + r.in(r.node, func() error { + et, err := ethtool.NewEthtool() + if err != nil { + return err + } + defer et.Close() + return et.Change(tenant, map[string]bool{featureTxChecksum: true}) + }) + a.guest.send(t, guestAddr, client, 5555, 40000, "partial-2", true) + sock.absent(t, "partial-2") + + if r.planEmpty(a.vpc, claims) { + t.Fatal("a changed feature planned no repair") + } + r.reconcile(a.vpc, claims) + a.guest.send(t, guestAddr, client, 5555, 40000, "partial-3", true) + sock.expect(t, a.shard, "partial-3") +} + +// TestRoutedLinkRoot checks local.routed_link: the link reaches the owner's +// pod and only it, both directions route through the VPC's VRF, the guard +// drops a source the pod was not given, the client learns both ends, and the +// link follows the owner to a new pod. +func TestRoutedLinkRoot(t *testing.T) { + r := newRig(t, "routed", xdpmode.Native) + a := r.vpcs[0] + pod, err := ns.TempNetNS() + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = pod.Close() }) + r.pods.add("pod-1", pod) + dest := module.Destination{ID: "attachment/" + a.attUID, Mode: workerv1alpha1.Mode_MODE_LOCAL, VPC: a.vpc, + Node: testNode, Addresses: []netip.Addr{guestAddr}, HostInterface: a.tap} + claim := module.Claim{Key: module.ClaimKey{Node: testNode, VPC: a.vpc, AttachmentUID: "envoy-1"}, + Owner: "galactic-system/envoy", Generation: 1, Handoff: workerv1alpha1.Handoff_HANDOFF_ROUTED_LINK, + OwnerPod: "pod-1", Addresses: []netip.Addr{podAddr}, Destinations: []module.Destination{dest}} + claims := []module.Claim{claim} + + wantReady(t, r.reconcile(a.vpc, claims), claims) + host := linkName(a.vpc, "envoy-1", intf.LocalRoleRoutedHost) + podEnd := linkName(a.vpc, "envoy-1", intf.LocalRoleRoutedPod) + got := r.mod.HandoffInterfaces(module.Scope{VPC: a.vpc})[claim.Key] + if len(got) != 2 || got[0].Role != workerv1alpha1.HandoffRoleHost || got[0].Name != host || + got[1].Role != workerv1alpha1.HandoffRolePod || got[1].Name != podEnd { + t.Fatalf("handoff interfaces %+v, want the host end %s and the pod end %s", got, host, podEnd) + } + if row, ok, err := r.routes.LookupRow(a.table, ipnet(netip.PrefixFrom(podAddr, 128))); err != nil || !ok || + !row.PassThrough { + t.Fatalf("the pod address has no pass-through entry: %+v %t %v", row, ok, err) + } + + routedTraffic(t, r, a, pod, host, podEnd) + + // The owner's pod is replaced: the link moves to the new pod and the + // old pod keeps nothing. + pod2, err := ns.TempNetNS() + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = pod2.Close() }) + r.pods.add("pod-2", pod2) + claims[0].OwnerPod = "pod-2" + if r.planEmpty(a.vpc, claims) { + t.Fatal("a new pod planned nothing") + } + r.reconcile(a.vpc, claims) + for p, want := range map[ns.NetNS]bool{pod: false, pod2: true} { + if err := p.Do(func(ns.NetNS) error { + _, err := netlink.LinkByName(podEnd) + if (err == nil) != want { + t.Errorf("pod end present %t in %s, want %t", err == nil, p.Path(), want) + } + return nil + }); err != nil { + t.Fatal(err) + } + } + + // The owner's pod is gone: the claim waits for it. + claims[0].OwnerPod = "pod-3" + st := r.reconcile(a.vpc, claims) + wantState(t, st, claims[0], false, false, false, workerv1alpha1.ReasonHandoffInterfaceMissing) +} + +// TestWithdrawalRoot checks that releasing every claim removes everything +// Local programmed, that a claim's links are reported until they are gone, +// and that CNI's state stays. +func TestWithdrawalRoot(t *testing.T) { + r := readyRig(t, "withdraw") + a := r.vpcs[0] + natKey := r.claims(a)[1].Key + + // Before Apply, the released claim's pair keeps it reported. + var st module.State + r.in(r.node, func() error { + ctx := context.Background() + if _, err := r.mod.Plan(ctx, module.Scope{VPC: a.vpc}, nil); err != nil { + return err + } + var err error + st, err = r.mod.Read(ctx, module.Scope{VPC: a.vpc}) + return err + }) + if _, ok := st[natKey][leftoverID]; !ok { + t.Fatalf("the released claim's pair is not reported: %v", st) + } + + for _, v := range r.vpcs { + if st := r.reconcile(v.vpc, nil); len(st) != 0 { + t.Fatalf("VPC %s still reports %v after its claims were released", v.vpc, st) + } + if !r.planEmpty(v.vpc, nil) { + t.Fatalf("VPC %s: a released scope would write again", v.vpc) + } + } + r.in(r.node, func() error { + links, err := netlink.LinkList() + if err != nil { + return err + } + for _, l := range links { + if intf.IsLocalLinkName(l.Attrs().Name) { + t.Errorf("Local link %s outlived its claim", l.Attrs().Name) + } + if _, _, ok, err := attach.LocalFilter(l.Attrs().Index); err == nil && ok { + t.Errorf("a Local filter outlived its claim on %s", l.Attrs().Name) + } + } + for _, v := range r.vpcs { + chain, err := attach.HasEgressChain(v.tap) + if err != nil || !chain { + t.Errorf("galactic-cni's chain on %s went with the claims (%v)", v.tap, err) + } + } + return nil + }) + for _, name := range []string{"lt_tap", "lt_link", "lt_guest", "lt_pair", "lt_guard"} { + m, err := ebpf.LoadPinnedMap(filepath.Join(r.pin, "local", name), nil) + if err != nil { + t.Fatal(err) + } + k := make([]byte, m.KeySize()) + if err := m.NextKey(nil, &k); !errors.Is(err, ebpf.ErrKeyNotExist) { + t.Errorf("%s keeps rows after every claim was released (%v)", name, err) + } + _ = m.Close() + } + // The NAT stand-in's own pass-through for the client's prefix stays: + // Local removes only the entries it owns. + if row, ok, err := r.routes.LookupRow(a.table, ipnet(clientNet)); err != nil || !ok || !row.PassThrough { + t.Fatalf("another owner's pass-through entry went: %+v %t %v", row, ok, err) + } +} + +// routedTraffic configures the pod's end of a routed link as the +// galactic-vrf sidecar does, and checks both directions between the pod and +// VPC a's guest and the guard's drop of a source the pod was not given. +func routedTraffic(t *testing.T, r *rig, a *vpcRig, pod ns.NetNS, host, podEnd string) { + t.Helper() + // The pod configures its end, as the galactic-vrf sidecar does. + var hostLL netip.Addr + r.in(r.node, func() error { + l, err := netlink.LinkByName(host) + if err != nil { + return err + } + addrs, err := netlink.AddrList(l, netlink.FAMILY_V6) + if err != nil { + return err + } + for _, ad := range addrs { + if a, ok := netip.AddrFromSlice(ad.IP); ok && a.IsLinkLocalUnicast() { + hostLL = a + } + } + return nil + }) + if !hostLL.IsValid() { + t.Fatal("the routed link's host end has no link-local address") + } + spoof := netip.MustParseAddr("fd20:80:ff04::66") + podIn := func(fn func() error) { + if err := pod.Do(func(ns.NetNS) error { return fn() }); err != nil { + t.Fatal(err) + } + } + podIn(func() error { + for _, p := range []netip.Addr{podAddr, spoof} { + if err := addrOn(podEnd, netip.PrefixFrom(p, 128)); err != nil { + return err + } + } + l, err := netlink.LinkByName(podEnd) + if err != nil { + return err + } + return netlink.RouteAdd(&netlink.Route{LinkIndex: l.Attrs().Index, + Dst: ipnet(netip.PrefixFrom(guestAddr, 128)), Gw: net.IP(hostLL.AsSlice())}) + }) + var podConn, spoofConn *net.UDPConn + podIn(func() error { + var err error + if podConn, err = net.ListenUDP("udp6", &net.UDPAddr{IP: net.IP(podAddr.AsSlice()), Port: 443}); err != nil { + return err + } + spoofConn, err = net.ListenUDP("udp6", &net.UDPAddr{IP: net.IP(spoof.AsSlice()), Port: 443}) + return err + }) + t.Cleanup(func() { _ = podConn.Close(); _ = spoofConn.Close() }) + + to := &net.UDPAddr{IP: net.IP(guestAddr.AsSlice()), Port: 8080} + if _, err := podConn.WriteToUDP([]byte("from-pod"), to); err != nil { + t.Fatal(err) + } + f := a.guest.expect(t, "from-pod") + if f.src != podAddr { + t.Fatalf("the guest received the pod's packet from %s", f.src) + } + a.guest.send(t, guestAddr, podAddr, 8080, 443, "to-pod", false) + buf := make([]byte, 64) + _ = podConn.SetReadDeadline(time.Now().Add(3 * time.Second)) + n, from, err := podConn.ReadFromUDPAddrPort(buf) + if err != nil || string(buf[:n]) != "to-pod" || from.Addr().Unmap() != guestAddr { + t.Fatalf("the pod read %q from %s (%v), want the guest's reply", buf[:n], from, err) + } + before := r.stats() + if _, err := spoofConn.WriteToUDP([]byte("spoofed"), to); err != nil { + t.Fatal(err) + } + a.guest.absent(t, "spoofed") + if after := r.stats(); after["guard_drop"] <= before["guard_drop"] { + t.Fatalf("the guard dropped nothing: before %v after %v", before, after) + } + +} diff --git a/internal/worker/local/local.go b/internal/worker/local/local.go new file mode 100644 index 00000000..b9ffdc2b --- /dev/null +++ b/internal/worker/local/local.go @@ -0,0 +1,236 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +// Package local is Galactic Worker's Local delivery module (#1435). It +// delivers between a service's handoff point and tenant destinations on this +// node through the handoffs docs/worker/contract.md#local-handoffs +// specifies: +// +// - local.tap: a public packet a dispatcher slot program marked for a +// tenant TAP is delivered by local_rx on the receiving device, and the +// guest's reply leaves through the device it arrived on; +// - local.veth_pair: a service-internal veth pair per VPC and claim, whose +// NAT end the client attaches its native XDP program to; tenant flows +// enter the pair and the pair's return is delivered to the tenant; +// - local.routed_link and local.socket: a veth from the VPC's VRF to the +// owner's pod, whose pod end the pod configures. +// +// The module separates link lifecycle from program ownership. CNI creates +// and deletes tenant interfaces; the module only attaches its own tc +// programs and rows to them, keyed by their current ifindex, and reprograms +// on a replacement. The module creates and deletes the pairs and routed +// links itself. It is the only writer of its tc filters (internal +// /plumbing/ebpf/attach.AttachLocal) and its lt_* maps. +// +// Programmed state is what the module wrote, read back. Observed state, which +// Ready reports, is what it did not write: the tenant interface with carrier +// and galactic-cni's chain, a live dispatcher slot on a receiving device, the +// client's XDP program on the NAT end, the MTUs and the neighbor. +package local + +import ( + "context" + "errors" + "fmt" + "log/slog" + "sync" + + workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" + "go.datum.net/galactic/internal/worker/module" +) + +// Name is the module's name. +const Name = "local" + +// Config configures a Module. +type Config struct { + // Kernel is the host access. + Kernel *Kernel + // Node is this node, the node of every claim key. + Node string + Log *slog.Logger +} + +// Module is the Local delivery module. +type Module struct { + cfg Config + + mu sync.Mutex + // desired is each scope's claims from its last Plan. + desired map[string][]module.Claim + // tapScopes are the scopes with a local.tap claim. + tapScopes map[string]bool + // errs are the per-link errors of each scope's last Apply. + errs map[string]map[string]error + // handoffs are each scope's handoff interfaces from its last Read. + handoffs map[string]map[module.ClaimKey][]module.HandoffInterface + // neighborWait are the scopes with a failed neighbor. + neighborWait map[string]bool +} + +var ( + _ module.Module = (*Module)(nil) + _ module.HandoffReporter = (*Module)(nil) +) + +// New returns a Local module. +func New(cfg Config) (*Module, error) { + if cfg.Kernel == nil || cfg.Node == "" { + return nil, errors.New("local: kernel and node are required") + } + if cfg.Log == nil { + cfg.Log = slog.Default() + } + cfg.Log = cfg.Log.With("module", Name) + return &Module{cfg: cfg, desired: map[string][]module.Claim{}, tapScopes: map[string]bool{}, + errs: map[string]map[string]error{}, handoffs: map[string]map[module.ClaimKey][]module.HandoffInterface{}, + neighborWait: map[string]bool{}}, nil +} + +// Name implements module.Module. +func (m *Module) Name() string { return Name } + +// Mode implements module.Module. +func (m *Module) Mode() workerv1alpha1.Mode { return workerv1alpha1.Mode_MODE_LOCAL } + +// Capabilities implements module.Module. Every Local capability needs the +// Local programs loaded against the pinned uSID datapath. +func (m *Module) Capabilities() []module.Capability { + caps := []module.Capability{ + {Name: workerv1alpha1.CapabilityLocalTap, Available: true}, + {Name: workerv1alpha1.CapabilityLocalVethPair, Available: true}, + {Name: workerv1alpha1.CapabilityLocalRoutedLink, Available: true}, + {Name: workerv1alpha1.CapabilityLocalSocket, Available: true}, + } + if err := m.cfg.Kernel.Loaded(); err != nil { + for i := range caps { + caps[i].Available = false + caps[i].Reason = workerv1alpha1.ReasonDatapathNotLoaded + caps[i].Message = err.Error() + } + } + return caps +} + +// change is the Local module's change for one scope: the model to ensure. +type change struct { + vpc string + m *model + dirty bool +} + +// Empty implements module.Change. +func (c *change) Empty() bool { return !c.dirty } + +// Plan implements module.Module. It computes the scope's desired Local state +// and checks the host against it without writing. +func (m *Module) Plan(_ context.Context, scope module.Scope, desired []module.Claim) (module.Change, error) { + vpc := scope.VPC + want := desire(vpc, desired) + m.mu.Lock() + if len(desired) > 0 { + m.desired[vpc] = desired + } else { + delete(m.desired, vpc) + } + if want.tap { + m.tapScopes[vpc] = true + } else { + delete(m.tapScopes, vpc) + } + anyTap := len(m.tapScopes) > 0 + m.mu.Unlock() + + ch := &change{vpc: vpc, m: want} + if err := m.cfg.Kernel.Loaded(); err != nil { + // Worker programs no destination whose capability is unavailable, + // and leaves whatever an earlier Worker wrote until it can read it. + return ch, nil + } + _, err := m.cfg.Kernel.ensure(want, true) + if err == nil { + err = m.cfg.Kernel.ensureReceivers(anyTap, true) + } + switch { + case errors.Is(err, errDirty): + ch.dirty = true + case err != nil: + return nil, fmt.Errorf("local: plan %s: %w", vpc, err) + } + return ch, nil +} + +// Apply implements module.Module. +func (m *Module) Apply(_ context.Context, scope module.Scope, c module.Change) error { + ch, ok := c.(*change) + if !ok || ch.vpc != scope.VPC { + return fmt.Errorf("local: change for another scope than %s", scope.VPC) + } + res, err := m.cfg.Kernel.ensure(ch.m, false) + if err != nil { + return err + } + for name, e := range res.errs { + m.cfg.Log.Info("a routed link could not be created; retrying on the next change", "vpc", ch.vpc, + "link", name, "error", e) + } + m.mu.Lock() + m.errs[ch.vpc] = res.errs + anyTap := len(m.tapScopes) > 0 + m.mu.Unlock() + if err := m.cfg.Kernel.ensureReceivers(anyTap, false); err != nil { + return err + } + if err := m.cfg.Kernel.purgeFlows(); err != nil { + m.cfg.Log.Warn("removing the flows of released TAPs failed", "error", err) + } + return nil +} + +// Read implements module.Module. +func (m *Module) Read(_ context.Context, scope module.Scope) (module.State, error) { + vpc := scope.VPC + m.mu.Lock() + claims := m.desired[vpc] + errs := m.errs[vpc] + m.mu.Unlock() + res, err := m.cfg.Kernel.read(vpc, m.cfg.Node, claims, desire(vpc, claims), errs) + if err != nil { + return nil, fmt.Errorf("local: read %s: %w", vpc, err) + } + m.mu.Lock() + m.handoffs[vpc] = res.handoffs + if res.failedNeighbors { + m.neighborWait[vpc] = true + } else { + delete(m.neighborWait, vpc) + } + m.mu.Unlock() + return res.state, nil +} + +// HandoffInterfaces implements module.HandoffReporter. +func (m *Module) HandoffInterfaces(scope module.Scope) map[module.ClaimKey][]module.HandoffInterface { + m.mu.Lock() + defer m.mu.Unlock() + out := map[module.ClaimKey][]module.HandoffInterface{} + for k, v := range m.handoffs[scope.VPC] { + out[k] = append([]module.HandoffInterface(nil), v...) + } + return out +} + +// tapVPCs returns the scopes with a local.tap claim. +func (m *Module) tapVPCs() []string { + m.mu.Lock() + defer m.mu.Unlock() + return sortedKeys(m.tapScopes) +} + +// neighborVPCs returns the scopes waiting on a failed neighbor. +func (m *Module) neighborVPCs() []string { + m.mu.Lock() + defer m.mu.Unlock() + return sortedKeys(m.neighborWait) +} diff --git a/internal/worker/local/model.go b/internal/worker/local/model.go new file mode 100644 index 00000000..ce026147 --- /dev/null +++ b/internal/worker/local/model.go @@ -0,0 +1,183 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "crypto/sha256" + "encoding/binary" + "net/netip" + "slices" + "sort" + "strings" + + workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" + "go.datum.net/galactic/internal/plumbing/ebpf/attach" + "go.datum.net/galactic/internal/plumbing/intf" + "go.datum.net/galactic/internal/worker/module" +) + +// maxGuardAddrs is how many source addresses a routed link admits +// (LT_GUARD_ADDRS in local.c). +const maxGuardAddrs = 4 + +// base62 digits, as intf encodes identifiers. +const base62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" + +// linkKey is the 3-character key of the links Local creates for the claim on +// attachmentUID, derived from its UID. Two claims in one VPC whose keys +// collide are told apart by the links' alias. +func linkKey(attachmentUID string) string { + sum := sha256.Sum256([]byte(attachmentUID)) + n := binary.BigEndian.Uint32(sum[:4]) % (62 * 62 * 62) + out := make([]byte, 3) + for i := 2; i >= 0; i-- { + out[i] = base62[n%62] + n /= 62 + } + return string(out) +} + +// linkName is the name of the Local link of role for the claim on +// attachmentUID in vpc. +func linkName(vpc, attachmentUID, role string) string { + return intf.GenerateInterfaceNameLocal(vpc, linkKey(attachmentUID), role) +} + +// alias is the alias of every link Local creates for the claim k: it marks +// the link as internal (attach.IsInternalLink) and names its claim. +func alias(k module.ClaimKey) string { + return attach.InternalAliasPrefix + k.VPC + "/" + k.AttachmentUID +} + +// parseAlias returns the VPC and attachment UID a Local link's alias names. +func parseAlias(a string) (vpc, attachmentUID string, ok bool) { + rest, found := strings.CutPrefix(a, attach.InternalAliasPrefix) + if !found { + return "", "", false + } + vpc, attachmentUID, ok = strings.Cut(rest, "/") + return vpc, attachmentUID, ok && vpc != "" && attachmentUID != "" +} + +// pairWant is the service-internal veth pair of a veth_pair claim. +type pairWant struct { + key module.ClaimKey + nat string + tenant string +} + +// routedWant is the routed link of a routed_link or socket claim. +type routedWant struct { + key module.ClaimKey + host string + pod string + // podUID is the pod the pod end goes in. + podUID string + // addrs are the sources the pod end may use: the claim attachment's + // IPv6 addresses, at most maxGuardAddrs. + addrs []netip.Addr +} + +// tenantWant is one tenant interface a claim delivers to. +type tenantWant struct { + name string + // tap is set when a local.tap claim delivers to it; nh is then the + // guest address local_rx resolves, or the zero address. + tap bool + nh netip.Addr + // pair is the tenant end of the VPC's pair a flow from it enters, or "". + pair string + // guests are its addresses the pair delivers to. + guests []netip.Addr +} + +// model is the Local state one VPC scope wants. +type model struct { + vpc string + pairs map[string]pairWant + routed map[string]routedWant + tenants map[string]*tenantWant + // tap is set when a claim of the scope uses local.tap, which needs + // local_rx on the node's public receiving devices. + tap bool +} + +// Empty reports whether the scope wants no Local state. +func (m *model) empty() bool { + return len(m.pairs) == 0 && len(m.routed) == 0 && len(m.tenants) == 0 +} + +// ipv6 returns addrs' IPv6 addresses, in order. +func ipv6(addrs []netip.Addr) []netip.Addr { + var out []netip.Addr + for _, a := range addrs { + if a.Is6() && !a.Is4In6() { + out = append(out, a) + } + } + return out +} + +// desire computes the Local state the claims of vpc want. A destination +// whose attachment has no host interface yet wants nothing; Read reports it. +func desire(vpc string, claims []module.Claim) *model { + m := &model{vpc: vpc, pairs: map[string]pairWant{}, routed: map[string]routedWant{}, + tenants: map[string]*tenantWant{}} + sorted := slices.Clone(claims) + sort.Slice(sorted, func(i, j int) bool { return sorted[i].Key.String() < sorted[j].Key.String() }) + tenant := func(name string) *tenantWant { + t := m.tenants[name] + if t == nil { + t = &tenantWant{name: name} + m.tenants[name] = t + } + return t + } + for _, c := range sorted { + switch c.Handoff { + case workerv1alpha1.Handoff_HANDOFF_TAP: + m.tap = true + for _, d := range c.Destinations { + if d.HostInterface == "" { + continue + } + t := tenant(d.HostInterface) + t.tap = true + if v6 := ipv6(d.Addresses); len(v6) > 0 && !t.nh.IsValid() { + t.nh = v6[0] + } + } + case workerv1alpha1.Handoff_HANDOFF_VETH_PAIR: + p := pairWant{key: c.Key, nat: linkName(vpc, c.Key.AttachmentUID, intf.LocalRolePairNAT), + tenant: linkName(vpc, c.Key.AttachmentUID, intf.LocalRolePairTenant)} + m.pairs[p.tenant] = p + for _, d := range c.Destinations { + if d.HostInterface == "" { + continue + } + t := tenant(d.HostInterface) + // One pair steers a tenant's flows: the first claim's, + // in claim key order. + if t.pair == "" { + t.pair = p.tenant + } + t.guests = append(t.guests, ipv6(d.Addresses)...) + } + case workerv1alpha1.Handoff_HANDOFF_ROUTED_LINK, workerv1alpha1.Handoff_HANDOFF_SOCKET: + addrs := ipv6(c.Addresses) + if len(addrs) > maxGuardAddrs { + addrs = addrs[:maxGuardAddrs] + } + r := routedWant{key: c.Key, host: linkName(vpc, c.Key.AttachmentUID, intf.LocalRoleRoutedHost), + pod: linkName(vpc, c.Key.AttachmentUID, intf.LocalRoleRoutedPod), podUID: c.OwnerPod, addrs: addrs} + m.routed[r.host] = r + } + } + for _, t := range m.tenants { + slices.SortFunc(t.guests, func(a, b netip.Addr) int { return a.Compare(b) }) + t.guests = slices.Compact(t.guests) + } + return m +} diff --git a/internal/worker/local/model_test.go b/internal/worker/local/model_test.go new file mode 100644 index 00000000..787ad0d2 --- /dev/null +++ b/internal/worker/local/model_test.go @@ -0,0 +1,84 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "net/netip" + "testing" + + workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" + "go.datum.net/galactic/internal/plumbing/ebpf/attach" + "go.datum.net/galactic/internal/plumbing/intf" + "go.datum.net/galactic/internal/worker/module" +) + +func TestLinkNames(t *testing.T) { + k := linkKey("6c1c3b7e-2a64-4d8a-9a51-1f0c9d1e2b3a") + if len(k) != 3 || linkKey("6c1c3b7e-2a64-4d8a-9a51-1f0c9d1e2b3a") != k { + t.Fatalf("linkKey = %q, want 3 stable characters", k) + } + for _, role := range []string{intf.LocalRolePairNAT, intf.LocalRolePairTenant, intf.LocalRoleRoutedHost, + intf.LocalRoleRoutedPod} { + name := linkName("8KxP2", "6c1c3b7e-2a64-4d8a-9a51-1f0c9d1e2b3a", role) + if len(name) > 15 || !intf.IsLocalLinkName(name) || !intf.IsGalacticLinkName(name) { + t.Errorf("linkName(%s) = %q, not a Local link name within 15 characters", role, name) + } + } + for _, cni := range []string{intf.GenerateInterfaceNameHost("8KxP2", "a1"), intf.GenerateInterfaceNameVRF("8KxP2")} { + if intf.IsLocalLinkName(cni) || !intf.IsGalacticLinkName(cni) { + t.Errorf("%q: CNI names are Galactic but not Local", cni) + } + } + key := module.ClaimKey{Node: "n", VPC: "8KxP2", AttachmentUID: "uid-1"} + vpc, uid, ok := parseAlias(alias(key)) + if !ok || vpc != key.VPC || uid != key.AttachmentUID { + t.Fatalf("parseAlias(alias(%v)) = %q %q %t", key, vpc, uid, ok) + } + if _, _, ok := parseAlias(attach.InternalAliasPrefix + "novpc"); ok { + t.Fatal("an alias without an attachment parsed") + } +} + +func TestDesire(t *testing.T) { + v6 := netip.MustParseAddr("fd20::1") + v4 := netip.MustParseAddr("10.0.0.1") + dest := func(host string, addrs ...netip.Addr) module.Destination { + return module.Destination{ID: "attachment/" + host, HostInterface: host, Addresses: addrs} + } + claims := []module.Claim{ + {Key: module.ClaimKey{VPC: "v", AttachmentUID: "gw"}, Handoff: workerv1alpha1.Handoff_HANDOFF_TAP, + Destinations: []module.Destination{dest("tapA", v4, v6), dest("")}}, + {Key: module.ClaimKey{VPC: "v", AttachmentUID: "nat-b"}, Handoff: workerv1alpha1.Handoff_HANDOFF_VETH_PAIR, + Destinations: []module.Destination{dest("tapA", v6)}}, + {Key: module.ClaimKey{VPC: "v", AttachmentUID: "nat-a"}, Handoff: workerv1alpha1.Handoff_HANDOFF_VETH_PAIR, + Destinations: []module.Destination{dest("tapA", v6, v4)}}, + {Key: module.ClaimKey{VPC: "v", AttachmentUID: "envoy"}, Handoff: workerv1alpha1.Handoff_HANDOFF_SOCKET, + OwnerPod: "pod", Addresses: []netip.Addr{v4, v6, netip.MustParseAddr("fd20::2"), + netip.MustParseAddr("fd20::3"), netip.MustParseAddr("fd20::4"), netip.MustParseAddr("fd20::5")}}, + } + m := desire("v", claims) + if !m.tap || len(m.pairs) != 2 || len(m.routed) != 1 || len(m.tenants) != 1 { + t.Fatalf("desire = %+v", m) + } + ta := m.tenants["tapA"] + if !ta.tap || ta.nh != v6 { + t.Errorf("tapA: tap %t nh %s, want a TAP resolving %s", ta.tap, ta.nh, v6) + } + // The first pair in claim key order steers; IPv4 is not delivered. + if want := linkName("v", "nat-a", intf.LocalRolePairTenant); ta.pair != want { + t.Errorf("tapA steers into %q, want %q", ta.pair, want) + } + if len(ta.guests) != 1 || ta.guests[0] != v6 { + t.Errorf("tapA guests = %v, want [%s]", ta.guests, v6) + } + for _, r := range m.routed { + if r.podUID != "pod" || len(r.addrs) != maxGuardAddrs || r.addrs[0] != v6 { + t.Errorf("routed link %+v: want the pod and the first %d IPv6 addresses", r, maxGuardAddrs) + } + } + if !desire("v", nil).empty() { + t.Error("no claims want state") + } +} diff --git a/internal/worker/local/podns.go b/internal/worker/local/podns.go new file mode 100644 index 00000000..1bdbcd39 --- /dev/null +++ b/internal/worker/local/podns.go @@ -0,0 +1,122 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "errors" + "fmt" + "os" + "path/filepath" + "strconv" + "sync" + + "github.com/vishvananda/netns" + + "go.datum.net/galactic/internal/worker/auth" +) + +// ErrPodNotFound means no process of the pod runs on this node, so its +// network namespace cannot be reached. +var ErrPodNotFound = errors.New("local: no process of the pod runs on this node") + +// ErrPodHostNetwork means the pod shares the host's network namespace, where +// a routed link has no pod end to go. +var ErrPodHostNetwork = errors.New("local: the pod uses the host's network namespace") + +// PodNetns opens the network namespace of a pod on this node. +type PodNetns interface { + // Open returns a handle on podUID's network namespace, which the caller + // closes. + Open(podUID string) (netns.NsHandle, error) +} + +// ProcPods is the PodNetns of the host's /proc. It never takes a process +// from a request: it finds one by the pod UID Worker authenticated the +// claim's owner as (auth.Authenticator), and opens that process's namespace +// only while the process's cgroup still names that pod, the same check the +// Worker API applies to its peers (D21). A caller therefore reaches only +// its own pod's namespace. +type ProcPods struct { + // ProcRoot is the host's /proc, as Worker sees it. + ProcRoot string + // Pods maps a process to its pod by its cgroup. + Pods auth.PodResolver + + mu sync.Mutex + // last remembers the process each pod was last found by. + last map[string]int32 +} + +var _ PodNetns = (*ProcPods)(nil) + +// Open implements PodNetns. +func (p *ProcPods) Open(podUID string) (netns.NsHandle, error) { + if podUID == "" { + return netns.None(), fmt.Errorf("%w: the claim records no pod", ErrPodNotFound) + } + p.mu.Lock() + pid, ok := p.last[podUID] + p.mu.Unlock() + if ok { + if h, err := p.openPID(podUID, pid); err == nil || errors.Is(err, ErrPodHostNetwork) { + return h, err + } + } + entries, err := os.ReadDir(p.ProcRoot) + if err != nil { + return netns.None(), fmt.Errorf("local: read %s: %w", p.ProcRoot, err) + } + for _, e := range entries { + n, err := strconv.ParseInt(e.Name(), 10, 32) + if err != nil || n <= 0 { + continue + } + h, err := p.openPID(podUID, int32(n)) + if errors.Is(err, errOtherPod) { + continue + } + if err != nil { + return netns.None(), err + } + p.mu.Lock() + if p.last == nil { + p.last = map[string]int32{} + } + p.last[podUID] = int32(n) + p.mu.Unlock() + return h, nil + } + return netns.None(), fmt.Errorf("%w: pod %s", ErrPodNotFound, podUID) +} + +var errOtherPod = errors.New("local: the process belongs to another pod") + +// openPID opens pid's network namespace when pid belongs to podUID, before +// and after the open, so a process that exits and has its PID reused in +// between is never mistaken for the pod's. +func (p *ProcPods) openPID(podUID string, pid int32) (netns.NsHandle, error) { + if uid, err := p.Pods.PodUID(pid); err != nil || uid != podUID { + return netns.None(), errOtherPod + } + h, err := netns.GetFromPath(filepath.Join(p.ProcRoot, strconv.Itoa(int(pid)), "ns", "net")) + if err != nil { + return netns.None(), errOtherPod + } + if uid, err := p.Pods.PodUID(pid); err != nil || uid != podUID { + _ = h.Close() + return netns.None(), errOtherPod + } + host, err := netns.GetFromPath(filepath.Join(p.ProcRoot, "1", "ns", "net")) + if err != nil { + _ = h.Close() + return netns.None(), fmt.Errorf("local: open the host's network namespace: %w", err) + } + defer host.Close() //nolint:errcheck // our own descriptor + if h.Equal(host) { + _ = h.Close() + return netns.None(), fmt.Errorf("%w: pod %s", ErrPodHostNetwork, podUID) + } + return h, nil +} diff --git a/internal/worker/local/podns_root_test.go b/internal/worker/local/podns_root_test.go new file mode 100644 index 00000000..b8d65d51 --- /dev/null +++ b/internal/worker/local/podns_root_test.go @@ -0,0 +1,45 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "fmt" + "os" + "path/filepath" + "testing" + + "github.com/containernetworking/plugins/pkg/ns" + "github.com/vishvananda/netns" +) + +// TestProcPodsOpensThePodRoot checks that the caller's pod's namespace is +// the one opened: a process whose cgroup names the pod and whose namespace +// is not the host's. +func TestProcPodsOpensThePodRoot(t *testing.T) { + requireRoot(t) + pod, err := ns.TempNetNS() + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = pod.Close() }) + root := procRoot(t, 100) + podNet := filepath.Join(root, "300", "ns", "net") + if err := os.MkdirAll(filepath.Dir(podNet), 0o755); err != nil { + t.Fatal(err) + } + if err := os.Symlink(fmt.Sprintf("/proc/self/fd/%d", pod.Fd()), podNet); err != nil { + t.Fatal(err) + } + pods := &ProcPods{ProcRoot: root, Pods: cgroupPods{100: podB, 300: "pod-a"}} + h, err := pods.Open("pod-a") + if err != nil { + t.Fatalf("Open(pod-a): %v", err) + } + defer h.Close() //nolint:errcheck // test descriptor + want := netns.NsHandle(int(pod.Fd())) + if !h.Equal(want) { + t.Fatalf("Open(pod-a) = %v, want the pod's namespace %v", h, want) + } +} diff --git a/internal/worker/local/podns_test.go b/internal/worker/local/podns_test.go new file mode 100644 index 00000000..8528cd76 --- /dev/null +++ b/internal/worker/local/podns_test.go @@ -0,0 +1,73 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "errors" + "os" + "path/filepath" + "strconv" + "testing" +) + +// podB is a pod other than the one a test opens. +const podB = "pod-b" + +// cgroupPods maps a process to its pod as the fixture's cgroup files say. +type cgroupPods map[int32]string + +func (c cgroupPods) PodUID(pid int32) (string, error) { + if uid, ok := c[pid]; ok { + return uid, nil + } + return "", errors.New("no pod") +} + +// procRoot builds a /proc with a directory per pid whose network namespace +// is the test's own, and a pid 1 whose namespace is the same: the host's. +func procRoot(t *testing.T, pids ...int32) string { + t.Helper() + root := t.TempDir() + for _, pid := range append(pids, 1) { + dir := filepath.Join(root, strconv.Itoa(int(pid)), "ns") + if err := os.MkdirAll(dir, 0o755); err != nil { + t.Fatal(err) + } + if err := os.Symlink("/proc/self/ns/net", filepath.Join(dir, "net")); err != nil { + t.Fatal(err) + } + } + return root +} + +// TestProcPodsOpensOnlyTheCallersPod checks that a claim reaches no +// namespace but its own pod's: another pod's processes are never used, a +// pod with no process is not found, a claim without a pod reaches nothing, +// and a pod on the host's network is refused rather than given the host's +// namespace. +func TestProcPodsOpensOnlyTheCallersPod(t *testing.T) { + root := procRoot(t, 100, 200) + pods := &ProcPods{ProcRoot: root, Pods: cgroupPods{100: podB, 200: podB}} + if h, err := pods.Open("pod-a"); !errors.Is(err, ErrPodNotFound) { + _ = h.Close() + t.Fatalf("Open(pod-a) with only pod-b's processes = %v, want ErrPodNotFound", err) + } + if h, err := pods.Open(""); !errors.Is(err, ErrPodNotFound) { + _ = h.Close() + t.Fatalf("Open with no pod = %v, want ErrPodNotFound", err) + } + // pod-b's processes share the host's namespace in this fixture. + if h, err := pods.Open(podB); !errors.Is(err, ErrPodHostNetwork) { + _ = h.Close() + t.Fatalf("Open(pod-b) on the host's network = %v, want ErrPodHostNetwork", err) + } + // A process that moves to another pod after it was found is not used + // again. + pods.Pods = cgroupPods{200: "pod-c"} + if h, err := pods.Open(podB); !errors.Is(err, ErrPodNotFound) { + _ = h.Close() + t.Fatalf("Open(pod-b) after its processes left = %v, want ErrPodNotFound", err) + } +} diff --git a/internal/worker/local/read.go b/internal/worker/local/read.go new file mode 100644 index 00000000..cb894267 --- /dev/null +++ b/internal/worker/local/read.go @@ -0,0 +1,414 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "fmt" + "net/netip" + + "github.com/vishvananda/netlink" + "golang.org/x/sys/unix" + + workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" + "go.datum.net/galactic/internal/plumbing/ebpf/attach" + "go.datum.net/galactic/internal/plumbing/ebpf/localprog" + "go.datum.net/galactic/internal/plumbing/ebpf/xdpmode" + "go.datum.net/galactic/internal/worker/module" +) + +// leftoverID is the destination ID under which Read reports the Local links +// of a claim that is no longer desired, so Worker keeps the claim as +// withdrawing until they are gone. +const leftoverID = "local/handoff" + +// readResult is one Read of a scope. +type readResult struct { + state module.State + handoffs map[module.ClaimKey][]module.HandoffInterface + // failedNeighbors is set when a destination's neighbor failed, which a + // neighbor event clears. + failedNeighbors bool +} + +// check is one destination's evaluation, filled in order; the first failure +// of each of programmed, forward and return names the reason. +type check struct { + st module.DestinationState + failed bool + fwd bool + ret bool +} + +func newCheck(gen uint64) *check { + return &check{st: module.DestinationState{Generation: gen, Programmed: true}, fwd: true, ret: true} +} + +// unprogrammed records a failure that leaves the destination unprogrammed. +func (c *check) unprogrammed(reason, msg string) { + if c.failed { + return + } + c.failed = true + c.st.Programmed, c.fwd, c.ret = false, false, false + c.st.Reason, c.st.Message = reason, msg +} + +// notReady records an observed failure of the forward path, the return path +// or both. +func (c *check) notReady(fwd, ret bool, reason, msg string) { + if c.failed { + return + } + if fwd { + c.fwd = false + } + if ret { + c.ret = false + } + if c.st.Reason == "" { + c.st.Reason, c.st.Message = reason, msg + } +} + +func (c *check) done() module.DestinationState { + c.st.ForwardReady, c.st.ReturnReady = c.fwd && c.st.Programmed, c.ret && c.st.Programmed + c.st.Ready = c.st.ForwardReady && c.st.ReturnReady + if c.st.Ready { + c.st.Reason, c.st.Message = "", "" + } + return c.st +} + +func lowerUp(l netlink.Link) bool { return l.Attrs().RawFlags&unix.IFF_LOWER_UP != 0 } + +// read reports every Local destination of claims, the claims of vpc m was +// computed from, and the handoff interfaces of each. errs are the per-link +// errors the last ensure recorded. +func (k *Kernel) read(vpc, node string, claims []module.Claim, m *model, errs map[string]error) (readResult, error) { + out := readResult{state: module.State{}, handoffs: map[module.ClaimKey][]module.HandoffInterface{}} + fail := func(reason, msg string) readResult { + for _, c := range claims { + st := map[string]module.DestinationState{} + for _, d := range c.Destinations { + st[d.ID] = module.DestinationState{Generation: c.Generation, Reason: reason, Message: msg} + } + out.state[c.Key] = st + } + return out + } + objs, _, err := k.open() + if err != nil { + return fail(workerv1alpha1.ReasonDatapathNotLoaded, err.Error()), nil + } + _, vrfIdx, haveVRF, err := TableID(vpc) + if err != nil { + return out, err + } + h, err := readHost() + if err != nil { + return out, err + } + desiredKeys := map[module.ClaimKey]bool{} + for _, c := range claims { + desiredKeys[c.Key] = true + } + for _, l := range h.localLinks(vpc) { + v, uid, _ := parseAlias(l.Attrs().Alias) + key := module.ClaimKey{Node: node, VPC: v, AttachmentUID: uid} + if !desiredKeys[key] { + out.state[key] = map[string]module.DestinationState{leftoverID: {}} + } + } + if !haveVRF { + r := fail(workerv1alpha1.ReasonPending, "the VPC has no host VRF yet") + for k, v := range out.state { + r.state[k] = v + } + return r, nil + } + + var rs []receiver + if m.tap { + if rs, err = k.receiverDevices(h); err != nil { + return out, err + } + } + + for _, c := range claims { + states := map[string]module.DestinationState{} + // handoffCheck applies the checks of the claim's own handoff to a + // destination's check. + var handoffCheck func(ck *check, l netlink.Link) + + switch c.Handoff { + case workerv1alpha1.Handoff_HANDOFF_TAP: + handoffCheck = k.tapCheck(rs) + case workerv1alpha1.Handoff_HANDOFF_VETH_PAIR: + handoffCheck = k.pairCheck(h, m, c, vrfIdx, objs, &out) + case workerv1alpha1.Handoff_HANDOFF_ROUTED_LINK, workerv1alpha1.Handoff_HANDOFF_SOCKET: + handoffCheck = k.routedCheck(h, m, c, vrfIdx, objs, errs, &out) + default: + handoffCheck = func(ck *check, _ netlink.Link) { + ck.unprogrammed(workerv1alpha1.ReasonHookUnsupported, "the handoff kind has no Local mechanism") + } + } + + for _, d := range c.Destinations { + ck := newCheck(c.Generation) + l := k.destinationCheck(ck, h, vrfIdx, c, d, objs, &out) + handoffCheck(ck, l) + states[d.ID] = ck.done() + } + out.state[c.Key] = states + } + return out, nil +} + +// destinationCheck checks what every Local destination needs: its interface +// in the VPC's VRF with carrier and galactic-cni's chain, Local's rows and +// filter on it, and no failed neighbor. It returns the interface, or nil. +func (k *Kernel) destinationCheck(ck *check, h *host, vrfIdx int, c module.Claim, d module.Destination, + objs *localprog.Objects, out *readResult) netlink.Link { + if d.HostInterface == "" { + ck.unprogrammed(workerv1alpha1.ReasonHandoffInterfaceMissing, "the destination's attachment is not attached yet") + return nil + } + l := h.byName[d.HostInterface] + if l == nil || l.Attrs().MasterIndex != vrfIdx { + ck.unprogrammed(workerv1alpha1.ReasonHandoffInterfaceMissing, + fmt.Sprintf("interface %s is not in the VPC's VRF", d.HostInterface)) + return nil + } + if c.Handoff == workerv1alpha1.Handoff_HANDOFF_TAP && l.Type() != linkTunTap { + ck.unprogrammed(workerv1alpha1.ReasonHandoffInterfaceMissing, + fmt.Sprintf("interface %s is a %s, not a TAP", d.HostInterface, l.Type())) + return nil + } + idx := uint32(l.Attrs().Index) + if c.Handoff == workerv1alpha1.Handoff_HANDOFF_TAP || c.Handoff == workerv1alpha1.Handoff_HANDOFF_VETH_PAIR { + var lv localprog.LocalLtLinkValue + if err := objs.Maps.Link.Lookup(idx, &lv); err != nil { + ck.unprogrammed(workerv1alpha1.ReasonPending, "Local has not programmed "+d.HostInterface+" yet") + return l + } + if c.Handoff == workerv1alpha1.Handoff_HANDOFF_TAP { + var tv localprog.LocalLtTapValue + if err := objs.Maps.Tap.Lookup(idx, &tv); err != nil { + ck.unprogrammed(workerv1alpha1.ReasonPending, "Local has not authorized "+d.HostInterface+" yet") + return l + } + } + if c.Handoff == workerv1alpha1.Handoff_HANDOFF_VETH_PAIR { + for _, a := range ipv6(d.Addresses) { + var gv localprog.LocalLtGuestValue + key := localprog.LocalLtGuestKey{TableId: lv.TableId, Addr: a.As16()} + if err := objs.Maps.Guest.Lookup(key, &gv); err != nil || gv.LinkIfindex != idx { + ck.unprogrammed(workerv1alpha1.ReasonPending, fmt.Sprintf("Local has not authorized %s yet", a)) + return l + } + } + } + ok, err := k.filterCurrent(int(idx), filterLinkRx) + if err != nil || !ok { + ck.notReady(false, true, workerv1alpha1.ReasonHandoffHookMissing, + "Local's tc program is not on "+d.HostInterface) + } + } + chain, err := attach.HasEgressChain(d.HostInterface) + deliver, derr := attach.HasDeliver(d.HostInterface) + if err != nil || derr != nil || !chain || !deliver { + // Another tc owner, such as a node datapath adopting the + // interface, removed galactic-cni's filters (contract amendment). + ck.notReady(true, true, workerv1alpha1.ReasonHandoffInterfaceMissing, + "galactic-cni's tc chain is missing on "+d.HostInterface) + } + if !lowerUp(l) { + ck.notReady(true, true, workerv1alpha1.ReasonHandoffInterfaceMissing, + fmt.Sprintf("interface %s has no carrier: its reader does not hold it", d.HostInterface)) + } + neighs, err := netlink.NeighList(int(idx), netlink.FAMILY_V6) + if err == nil { + for _, a := range ipv6(d.Addresses) { + for _, n := range neighs { + if addr, ok := netip.AddrFromSlice(n.IP); ok && addr == a && n.State&netlink.NUD_FAILED != 0 { + out.failedNeighbors = true + ck.notReady(true, false, workerv1alpha1.ReasonNeighborUnresolved, + fmt.Sprintf("the neighbor %s on %s failed to resolve", a, d.HostInterface)) + } + } + } + } + return l +} + +// tapCheck checks a local.tap destination's receive path: a receiving device +// whose dispatcher runs a live public slot, carrying local_rx, with an MTU +// the TAP's covers. +func (k *Kernel) tapCheck(rs []receiver) func(*check, netlink.Link) { + return func(ck *check, l netlink.Link) { + if l == nil { + return + } + var live []receiver + var slotErr error + for _, r := range rs { + if r.slotErr == nil { + live = append(live, r) + } else { + slotErr = r.slotErr + } + } + if len(live) == 0 { + msg := "no receiving device's XDP dispatcher runs a live public slot" + if slotErr != nil { + msg += ": " + slotErr.Error() + } + ck.notReady(true, false, workerv1alpha1.ReasonDispatcherSlotUnclaimed, msg) + return + } + hooked := false + for _, r := range live { + if ok, err := k.filterCurrent(r.idx, filterRx); err == nil && ok { + hooked = true + } + if r.mtu > l.Attrs().MTU { + ck.notReady(true, false, workerv1alpha1.ReasonHandoffMTUTooSmall, + fmt.Sprintf("%s's MTU %d is below receiving device %s's %d", l.Attrs().Name, l.Attrs().MTU, + r.name, r.mtu)) + } + } + if !hooked { + ck.notReady(true, false, workerv1alpha1.ReasonHandoffHookMissing, + "Local's tc program is on no receiving device") + } + } +} + +// pairCheck checks a local.veth_pair claim's pair: it exists in the VPC's +// VRF with Local's row and program on its tenant end, both ends have +// carrier, and the client's program runs native on the NAT end. +func (k *Kernel) pairCheck(h *host, m *model, c module.Claim, vrfIdx int, objs *localprog.Objects, + out *readResult) func(*check, netlink.Link) { + var p pairWant + for _, pw := range m.pairs { + if pw.key == c.Key { + p = pw + } + } + got, ok := h.readPair(p) + if ok { + out.handoffs[c.Key] = append(out.handoffs[c.Key], + module.HandoffInterface{Role: workerv1alpha1.HandoffRoleNAT, Name: p.nat, Ifindex: int32(got.nat.Attrs().Index)}, + module.HandoffInterface{Role: workerv1alpha1.HandoffRoleTenant, Name: p.tenant, + Ifindex: int32(got.tenant.Attrs().Index)}) + } + return func(ck *check, l netlink.Link) { + if !ok || got.tenant.Attrs().MasterIndex != vrfIdx { + ck.unprogrammed(workerv1alpha1.ReasonPending, "the service-internal veth pair is not created yet") + return + } + tidx := got.tenant.Attrs().Index + var pv localprog.LocalLtPairValue + if err := objs.Maps.Pair.Lookup(uint32(tidx), &pv); err != nil { + ck.unprogrammed(workerv1alpha1.ReasonPending, "Local has not programmed the pair yet") + return + } + if l != nil { + var lv localprog.LocalLtLinkValue + if err := objs.Maps.Link.Lookup(uint32(l.Attrs().Index), &lv); err == nil && lv.PairIfindex != uint32(tidx) { + // Another pair of the VPC steers this tenant's flows. + ck.notReady(false, true, workerv1alpha1.ReasonHandoffHookMissing, + l.Attrs().Name+"'s flows enter another service-internal veth pair of the VPC") + } + } + if ok, err := k.filterCurrent(tidx, filterPairRx); err != nil || !ok { + ck.notReady(true, false, workerv1alpha1.ReasonHandoffHookMissing, + "Local's tc program is not on "+p.tenant) + } + if !lowerUp(got.tenant) || !lowerUp(got.nat) { + ck.notReady(true, true, workerv1alpha1.ReasonHandoffInterfaceMissing, "the pair has no carrier") + } + xdp := got.nat.Attrs().Xdp + if xdp == nil || !xdp.Attached { + ck.notReady(false, true, workerv1alpha1.ReasonHandoffHookMissing, + fmt.Sprintf("the NAT end %s carries no XDP program", p.nat)) + } else if mode, ok := xdpmode.FromAttachMode(xdp.AttachMode); !ok || mode != xdpmode.Native { + // Generic XDP never sees what a tc program redirected into + // the pair (contract amendment). + ck.notReady(false, true, workerv1alpha1.ReasonHookUnsupported, + fmt.Sprintf("the NAT end %s runs its XDP program in generic mode; attach it native", p.nat)) + } + if l != nil && l.Attrs().MTU < got.tenant.Attrs().MTU { + ck.notReady(true, false, workerv1alpha1.ReasonHandoffMTUTooSmall, + fmt.Sprintf("%s's MTU %d is below the pair's %d", l.Attrs().Name, l.Attrs().MTU, + got.tenant.Attrs().MTU)) + } + } +} + +// routedCheck checks a routed link: it exists from the VPC's VRF to the +// owner's current pod with Local's guard, and has carrier, which it has once +// the pod brings its end up. +func (k *Kernel) routedCheck(h *host, m *model, c module.Claim, vrfIdx int, objs *localprog.Objects, + errs map[string]error, out *readResult) func(*check, netlink.Link) { + var r routedWant + for _, rw := range m.routed { + if rw.key == c.Key { + r = rw + } + } + l := h.byName[r.host] + // The link counts only while it reaches the owner's current pod. + var podErr error + present := false + if podNS, err := k.Pods.Open(r.podUID); err != nil { + podErr = err + } else { + _, present = h.readRouted(r, podNS) + _ = podNS.Close() + } + if present { + out.handoffs[c.Key] = append(out.handoffs[c.Key], module.HandoffInterface{ + Role: workerv1alpha1.HandoffRoleHost, Name: r.host, Ifindex: int32(l.Attrs().Index)}) + if v, ok := l.(*netlink.Veth); ok { + if peer, err := netlink.VethPeerIndex(v); err == nil { + out.handoffs[c.Key] = append(out.handoffs[c.Key], module.HandoffInterface{ + Role: workerv1alpha1.HandoffRolePod, Name: r.pod, Ifindex: int32(peer)}) + } + } + } + return func(ck *check, _ netlink.Link) { + if podErr != nil { + ck.unprogrammed(workerv1alpha1.ReasonHandoffInterfaceMissing, podErr.Error()) + return + } + if err := errs[r.host]; err != nil { + ck.unprogrammed(workerv1alpha1.ReasonHandoffInterfaceMissing, err.Error()) + return + } + if len(r.addrs) == 0 { + ck.unprogrammed(workerv1alpha1.ReasonDestinationAddressUnknown, + "the claim's attachment records no IPv6 address for the routed link's pod end") + return + } + if !present || l.Attrs().MasterIndex != vrfIdx { + ck.unprogrammed(workerv1alpha1.ReasonPending, "the routed link is not created yet") + return + } + var gv localprog.LocalLtGuardValue + if err := objs.Maps.Guard.Lookup(uint32(l.Attrs().Index), &gv); err != nil { + ck.unprogrammed(workerv1alpha1.ReasonPending, "Local has not programmed the routed link's guard yet") + return + } + if ok, err := k.filterCurrent(l.Attrs().Index, filterLinkGuard); err != nil || !ok { + ck.notReady(true, true, workerv1alpha1.ReasonHandoffHookMissing, + "Local's guard is not on "+r.host) + } + if !lowerUp(l) { + ck.notReady(true, true, workerv1alpha1.ReasonHandoffInterfaceMissing, + fmt.Sprintf("the routed link %s has no carrier: the pod has not brought its end up", r.host)) + } + } +} diff --git a/internal/worker/local/rig_root_test.go b/internal/worker/local/rig_root_test.go new file mode 100644 index 00000000..10e57f81 --- /dev/null +++ b/internal/worker/local/rig_root_test.go @@ -0,0 +1,843 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "context" + "errors" + "fmt" + "net" + "net/netip" + "os" + "path/filepath" + "sync" + "testing" + "time" + + "github.com/cilium/ebpf" + "github.com/containernetworking/plugins/pkg/ns" + "github.com/safchain/ethtool" + "github.com/vishvananda/netlink" + "github.com/vishvananda/netns" + "golang.org/x/sys/unix" + + workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" + "go.datum.net/galactic/internal/plumbing/ebpf/attach" + "go.datum.net/galactic/internal/plumbing/ebpf/egressroutemap" + "go.datum.net/galactic/internal/plumbing/ebpf/localprog" + "go.datum.net/galactic/internal/plumbing/ebpf/localprog/localfixture" + "go.datum.net/galactic/internal/plumbing/ebpf/prog" + "go.datum.net/galactic/internal/plumbing/ebpf/tpmap" + "go.datum.net/galactic/internal/plumbing/ebpf/uformat" + "go.datum.net/galactic/internal/plumbing/ebpf/xdpdispatch" + "go.datum.net/galactic/internal/plumbing/ebpf/xdpmode" + "go.datum.net/galactic/internal/plumbing/intf" + "go.datum.net/galactic/internal/trafficpolicy" + "go.datum.net/galactic/internal/worker/module" +) + +func requireRoot(t *testing.T) { + t.Helper() + if os.Geteuid() != 0 { + t.Skip("test requires root to load the datapath and build network namespaces; run task test:unit-root") + } + if _, err := os.Stat("/dev/net/tun"); err != nil { + t.Skipf("test requires /dev/net/tun: %v", err) + } +} + +// The rig's documentation addresses. Both VPCs' guests use one address. +var ( + guestAddr = netip.MustParseAddr("fd20:80:ff03::1:0:0") + nodeAddr = netip.MustParseAddr("2001:db8:4135:1::1") + client = netip.MustParseAddr("2001:db8:4135:1::2") + clientNet = netip.MustParsePrefix("2001:db8:4135:1::/64") + vipNet = netip.MustParsePrefix("2001:db8:4135:a::/64") + shardNet = netip.MustParsePrefix("2001:db8:4135:5::/64") + guestMAC = net.HardwareAddr{0x02, 0x47, 0, 0, 0, 0x01} + // natTable stands in for the shard resolver (#1437): the client's prefix + // steers into the VPC's pair. + podAddr = netip.MustParseAddr("fd20:80:ff04::50") +) + +const ( + testNode = "node-a" + bondName = "bond0" + // rxLower0 is the node's end of the receiving device. + rxLower0 = "rx0" + // clientLower is the client's end of the receiving device. + clientLower = "cl0" + cellVLAN = "vlan" + cellBond = "bond" + tpMark = 0x0de10000 + vlanID = 120 + tableBase = 4100 +) + +// vpcRig is one VPC of the rig: its VRF, its TAP guest and what the gateway +// and NAT stand-ins use for it. +type vpcRig struct { + vpc string + table uint32 + argument uint16 + tap string + tapIdx int + tapMAC net.HardwareAddr + guest *guest + vip netip.Addr + shard netip.Addr + attUID string + natUID string +} + +// rig is a node namespace holding the VPCs, a receiving device and the +// datapath, and a client namespace on the far side of the receiving device. +type rig struct { + t *testing.T + node ns.NetNS + client ns.NetNS + pin string + usid *prog.UsidObjects + tp *tpmap.Maps + routes *egressroutemap.EgressRouteTable + fix localfixture.FixtureObjects + disp *xdpdispatch.Dispatcher + mode xdpmode.Mode + cell string + + // rx is the device local_rx runs on, rxLower the devices the dispatcher + // runs on, out the device the NAT stand-in sends from. + rx string + rxLower []string + out string + outVID uint32 + clientIf string + + kernel *Kernel + mod *Module + vpcs []*vpcRig + pods *fakePods +} + +func newRig(t *testing.T, cell string, mode xdpmode.Mode) *rig { + t.Helper() + requireRoot(t) + r := &rig{t: t, cell: cell, mode: mode, pods: &fakePods{}} + r.pin = fmt.Sprintf("/sys/fs/bpf/galactic-local-test-%d-%s", os.Getpid(), cell) + _ = os.RemoveAll(r.pin) + t.Cleanup(func() { _ = os.RemoveAll(r.pin) }) + + var err error + if r.node, err = ns.TempNetNS(); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = r.node.Close() }) + if r.client, err = ns.TempNetNS(); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = r.client.Close() }) + for _, n := range []ns.NetNS{r.node, r.client} { + r.in(n, func() error { + for _, k := range []string{"net/ipv6/conf/all/accept_dad", "net/ipv6/conf/default/accept_dad", + "net/ipv6/conf/default/accept_ra"} { + if err := os.WriteFile(filepath.Join("/proc/sys", k), []byte("0"), 0o644); err != nil { + return err + } + } + return os.WriteFile("/proc/sys/net/ipv6/conf/all/forwarding", []byte("1"), 0o644) + }) + } + + if r.usid, err = attach.Load(r.pin + "/usid"); err != nil { + t.Fatalf("load the uSID datapath: %v", err) + } + t.Cleanup(func() { _ = r.usid.Close() }) + if r.tp, err = tpmap.OpenPinned(r.pin + "/usid"); err != nil { + t.Fatalf("open policy maps: %v", err) + } + t.Cleanup(r.tp.Close) + table, closer, err := egressroutemap.OpenPinnedEgressRouteTable(r.pin + "/usid") + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = closer.Close() }) + r.routes = table + if err := r.tp.SetState(tpmap.State{Mode: tpmap.ModeEnforce, NATLocatorsSynced: true, Mark: tpMark, + Capable: true}); err != nil { + t.Fatal(err) + } + if err := localfixture.LoadFixtureObjects(&r.fix, nil); err != nil { + t.Fatalf("load the fixture programs: %v", err) + } + t.Cleanup(func() { _ = r.fix.Close() }) + + r.buildReceiver() + r.vpcs = []*vpcRig{ + r.addVPC("80", 0x80, netip.MustParseAddr("2001:db8:4135:a::80"), netip.MustParseAddr("2001:db8:4135:5::80")), + r.addVPC("81", 0x81, netip.MustParseAddr("2001:db8:4135:a::81"), netip.MustParseAddr("2001:db8:4135:5::81")), + } + r.buildDispatcher() + + r.kernel = &Kernel{PinDir: r.pin + "/usid", LocalPinDir: r.pin + "/local", DispatchDir: r.pin + "/xdp", + Pods: r.pods} + t.Cleanup(func() { _ = r.kernel.Close() }) + if r.mod, err = New(Config{Kernel: r.kernel, Node: testNode}); err != nil { + t.Fatal(err) + } + return r +} + +// in runs fn in n on a locked thread. +func (r *rig) in(n ns.NetNS, fn func() error) { + r.t.Helper() + if err := n.Do(func(ns.NetNS) error { return fn() }); err != nil { + r.t.Fatal(err) + } +} + +func addrOn(name string, p netip.Prefix) error { + l, err := netlink.LinkByName(name) + if err != nil { + return err + } + return netlink.AddrAdd(l, &netlink.Addr{IPNet: ipnet(p), Flags: unix.IFA_F_NODAD}) +} + +func up(name string) error { + l, err := netlink.LinkByName(name) + if err != nil { + return err + } + return netlink.LinkSetUp(l) +} + +// wireLike makes a veth end stand in for the far side of a physical link: +// it sends complete checksums, and takes a native XDP_REDIRECT into its +// peer, which a veth receives only with GRO or an XDP program. +func wireLike(name string) error { + et, err := ethtool.NewEthtool() + if err != nil { + return err + } + defer et.Close() + return et.Change(name, map[string]bool{featureTxChecksum: false, featureGRO: true}) +} + +// buildReceiver builds the receiving device for r.cell: a veth (plain), a +// VLAN on one (vlan), or an active-backup bond over two (bond). +func (r *rig) buildReceiver() { + clientFd := int(r.client.Fd()) + pairs := []struct{ node, client string }{{rxLower0, clientLower}} + if r.cell == cellBond { + pairs = append(pairs, struct{ node, client string }{"rx1", "cl1"}) + } + r.in(r.node, func() error { + for _, p := range pairs { + v := &netlink.Veth{LinkAttrs: netlink.LinkAttrs{Name: p.node, MTU: 1500}, PeerName: p.client, + PeerNamespace: netlink.NsFd(clientFd)} + if err := netlink.LinkAdd(v); err != nil { + return err + } + } + return nil + }) + r.clientIf, r.rx = clientLower, rxLower0 + r.rxLower = []string{rxLower0} + switch r.cell { + case cellVLAN: + r.rx, r.clientIf = fmt.Sprintf("rx0.%d", vlanID), fmt.Sprintf("cl0.%d", vlanID) + r.out, r.outVID = rxLower0, vlanID + case cellBond: + r.rx, r.clientIf = bondName, bondName + r.rxLower = []string{rxLower0, "rx1"} + r.out = bondName + default: + r.out = rxLower0 + } + build := func(side ns.NetNS, lowers []string, top string) { + r.in(side, func() error { + for _, l := range lowers { + if err := wireLike(l); err != nil { + return err + } + } + switch r.cell { + case cellVLAN: + parent, err := netlink.LinkByName(lowers[0]) + if err != nil { + return err + } + if err := netlink.LinkAdd(&netlink.Vlan{LinkAttrs: netlink.LinkAttrs{Name: top, + ParentIndex: parent.Attrs().Index}, VlanId: vlanID}); err != nil { + return err + } + case cellBond: + b := netlink.NewLinkBond(netlink.LinkAttrs{Name: top}) + b.Mode = netlink.BOND_MODE_ACTIVE_BACKUP + if err := netlink.LinkAdd(b); err != nil { + return err + } + for _, l := range lowers { + m, err := netlink.LinkByName(l) + if err != nil { + return err + } + if err := netlink.LinkSetBondSlave(m, &netlink.Bond{LinkAttrs: *b.Attrs()}); err != nil { + return err + } + } + } + for _, l := range append(append([]string(nil), lowers...), top) { + if err := up(l); err != nil { + return err + } + } + return nil + }) + } + clientLowers := []string{clientLower} + if r.cell == cellBond { + clientLowers = []string{clientLower, "cl1"} + } + build(r.node, r.rxLower, r.rx) + build(r.client, clientLowers, r.clientIf) + r.in(r.node, func() error { return addrOn(r.rx, netip.PrefixFrom(nodeAddr, 64)) }) + r.in(r.client, func() error { + if err := addrOn(r.clientIf, netip.PrefixFrom(client, 64)); err != nil { + return err + } + l, err := netlink.LinkByName(r.clientIf) + if err != nil { + return err + } + for _, p := range []netip.Prefix{vipNet, shardNet} { + if err := netlink.RouteAdd(&netlink.Route{LinkIndex: l.Attrs().Index, Dst: ipnet(p), + Gw: net.IP(nodeAddr.AsSlice())}); err != nil { + return err + } + } + return nil + }) +} + +// addVPC adds a VPC with a VRF, a TAP guest at guestAddr carrying +// galactic-cni's chain and registration, and its policy. +func (r *rig) addVPC(id string, argument uint16, vip, shard netip.Addr) *vpcRig { + v := &vpcRig{vpc: "00000" + id, argument: argument, table: tableBase + uint32(argument), vip: vip, shard: shard, + attUID: "00000000-0000-4000-8000-0000000000" + id, natUID: "00000000-0000-4000-8000-0000000001" + id} + v.tap = intf.GenerateInterfaceNameHost(v.vpc, "001") + r.in(r.node, func() error { + vrf := &netlink.Vrf{LinkAttrs: netlink.LinkAttrs{Name: intf.GenerateInterfaceNameVRF(v.vpc)}, Table: v.table} + if err := netlink.LinkAdd(vrf); err != nil { + return err + } + return up(vrf.Name) + }) + r.addTap(v) + return v +} + +// addTap creates v's TAP, as galactic-tap does, and its guest. +func (r *rig) addTap(v *vpcRig) { + r.in(r.node, func() error { + g, err := newGuest(v.tap) + if err != nil { + return err + } + v.guest = g + r.t.Cleanup(g.close) + l, err := netlink.LinkByName(v.tap) + if err != nil { + return err + } + vrf, err := netlink.LinkByName(intf.GenerateInterfaceNameVRF(v.vpc)) + if err != nil { + return err + } + if err := netlink.LinkSetMaster(l, vrf); err != nil { + return err + } + if err := netlink.LinkSetUp(l); err != nil { + return err + } + if l, err = netlink.LinkByName(v.tap); err != nil { + return err + } + v.tapIdx, v.tapMAC = l.Attrs().Index, l.Attrs().HardwareAddr + g.hostMAC = v.tapMAC + // The guest's own route, which galactic-tap installs. + if err := netlink.RouteReplace(&netlink.Route{LinkIndex: v.tapIdx, Table: int(v.table), + Dst: ipnet(netip.PrefixFrom(guestAddr, 128))}); err != nil { + return err + } + if err := attach.AttachEgress(r.usid.UsidServiceEgress, r.usid.UsidEgress, v.tap); err != nil { + return err + } + return attach.AttachDeliver(r.usid.TpDeliver, v.tap) + }) + key, err := uformat.NewVRFKey(0x4135, v.argument) + if err != nil { + r.t.Fatal(err) + } + if err := r.usid.IfindexVrfTable.Put(uint32(v.tapIdx), + prog.UsidIfindexVrfValue{Block: 0x4135, Argument: v.argument}); err != nil { + r.t.Fatal(err) + } + if err := r.usid.VrfTable.Put(uint64(key), prog.UsidVrfValue{VrfTableId: v.table}); err != nil { + r.t.Fatal(err) + } + if err := r.tp.PutInterface(uint32(v.tapIdx), 0x4135, tpmap.KindTenant); err != nil { + r.t.Fatal(err) + } + r.policy(v) +} + +// policy binds the handoff policy to v's TAP: every path is allowed except +// UDP port 9 on the public paths both ways, and a PublicService reply from +// the guest's port 8, so a request to port 8 is delivered and its reply +// denied. +func (r *rig) policy(v *vpcRig) { + if v.tapIdx == 0 { + return + } + port9 := trafficpolicy.PortRange{Start: 9, End: 9} + allow := trafficpolicy.Entry{Flags: trafficpolicy.FlagAllow, Rule: 3} + for dir, toGuest := range map[uint32]bool{tpmap.DirIngress: true, tpmap.DirEgress: false} { + entries := []trafficpolicy.Entry{ + denyPort(0, trafficpolicy.PathPublicService, true, port9), + denyPort(1, trafficpolicy.PathPublicNAT, true, port9), + denyPort(2, trafficpolicy.PathPublicNAT, false, port9), + allow, + } + if !toGuest { + entries[0] = denyPort(0, trafficpolicy.PathPublicService, false, trafficpolicy.PortRange{Start: 8, End: 8}) + } + if err := r.tp.Publish(uint32(v.tapIdx), dir, 0x4135, uint32(v.tapIdx)*4, entries); err != nil { + r.t.Fatal(err) + } + } +} + +// denyPort denies UDP on path from or to port. +func denyPort(rule uint16, path trafficpolicy.Path, dport bool, port trafficpolicy.PortRange) trafficpolicy.Entry { + e := trafficpolicy.Entry{Flags: trafficpolicy.FlagPath | trafficpolicy.FlagProto, Rule: rule, Path: path, + Proto: protoUDP} + if dport { + e.Flags |= trafficpolicy.FlagDestPorts + e.DestPorts = port + } else { + e.Flags |= trafficpolicy.FlagSourcePorts + e.SourcePorts = port + } + return e +} + +// buildDispatcher puts the gateway stand-in in the public slot of the +// receiving device's dispatcher. +func (r *rig) buildDispatcher() { + ctx := context.Background() + var err error + if r.disp, err = xdpdispatch.Open(ctx, r.pin+"/xdp", r.mode); err != nil { + r.t.Fatal(err) + } + r.t.Cleanup(func() { _ = r.disp.Close() }) + r.in(r.node, func() error { + lock, err := r.disp.Lock(ctx) + if err != nil { + return err + } + defer lock.Unlock() + for _, name := range r.rxLower { + l, err := netlink.LinkByName(name) + if err != nil { + return err + } + if _, err := lock.EnsureLink(l.Attrs().Index); err != nil { + return fmt.Errorf("attach the dispatcher to %s: %w", name, err) + } + if err := lock.SetRole(l.Attrs().Index, xdpdispatch.RolePublicLB); err != nil { + return err + } + } + return lock.Fill(xdpdispatch.SlotGatewayLB, r.fix.LtfGateway) + }) + for _, v := range r.vpcs { + r.vip(v.vip, v.tapIdx, 0) + } +} + +// vip makes the gateway stand-in mark packets for addr with tapIdx and magic, +// the product's when 0. +func (r *rig) vip(addr netip.Addr, tapIdx int, magic uint32) { + if magic == 0 { + magic = 0x474c4d31 + } + if err := r.fix.LtfVip.Put(localfixture.FixtureLtfIn6{A: addr.As16()}, + localfixture.FixtureLtfVipValue{TapIfindex: uint32(tapIdx), Magic: magic}); err != nil { + r.t.Fatal(err) + } +} + +// claims returns a local.tap claim and a local.veth_pair claim for each VPC. +func (r *rig) claims(v *vpcRig) []module.Claim { + dest := module.Destination{ID: "attachment/" + v.attUID, Mode: workerv1alpha1.Mode_MODE_LOCAL, VPC: v.vpc, + Node: testNode, Addresses: []netip.Addr{guestAddr}, HostInterface: v.tap} + return []module.Claim{ + {Key: module.ClaimKey{Node: testNode, VPC: v.vpc, AttachmentUID: "gw-" + v.vpc}, Owner: "galactic-system/gw", + Generation: 1, Handoff: workerv1alpha1.Handoff_HANDOFF_TAP, Destinations: []module.Destination{dest}}, + {Key: module.ClaimKey{Node: testNode, VPC: v.vpc, AttachmentUID: v.natUID}, Owner: "galactic-system/nat", + Generation: 1, Handoff: workerv1alpha1.Handoff_HANDOFF_VETH_PAIR, Destinations: []module.Destination{dest}}, + } +} + +// reconcile plans, applies when needed, and reads one VPC's claims, as +// Worker's reconcile does, and returns the read-back. +func (r *rig) reconcile(vpc string, claims []module.Claim) module.State { + r.t.Helper() + var st module.State + r.in(r.node, func() error { + ctx := context.Background() + scope := module.Scope{VPC: vpc} + ch, err := r.mod.Plan(ctx, scope, claims) + if err != nil { + return err + } + if !ch.Empty() { + if err := r.mod.Apply(ctx, scope, ch); err != nil { + return err + } + } + st, err = r.mod.Read(ctx, scope) + return err + }) + return st +} + +// planEmpty reports whether a Plan of vpc's claims would write nothing. +func (r *rig) planEmpty(vpc string, claims []module.Claim) bool { + r.t.Helper() + empty := false + r.in(r.node, func() error { + ch, err := r.mod.Plan(context.Background(), module.Scope{VPC: vpc}, claims) + if err != nil { + return err + } + empty = ch.Empty() + return nil + }) + return empty +} + +// natStandIn plays NAT for v: the client's prefix steers into v's pair, the +// NAT stand-in runs native on the pair's NAT end, and the gateway stand-in +// sends v's shard address back into the pair. +func (r *rig) natStandIn(v *vpcRig) { + r.t.Helper() + if err := r.routes.RegisterPassThroughAs(v.table, ipnet(clientNet), egressroutemap.PassThroughLocalNAT); err != nil { + r.t.Fatal(err) + } + natName := linkName(v.vpc, v.natUID, intf.LocalRolePairNAT) + tenantName := linkName(v.vpc, v.natUID, intf.LocalRolePairTenant) + var natIdx int + var natMAC, tenantMAC, outMAC, clientMAC net.HardwareAddr + var outIdx int + r.in(r.client, func() error { + l, err := netlink.LinkByName(r.clientIf) + if err != nil { + return err + } + clientMAC = l.Attrs().HardwareAddr + return nil + }) + r.in(r.node, func() error { + nat, err := netlink.LinkByName(natName) + if err != nil { + return err + } + tenant, err := netlink.LinkByName(tenantName) + if err != nil { + return err + } + out, err := netlink.LinkByName(r.out) + if err != nil { + return err + } + rx, err := netlink.LinkByName(r.rx) + if err != nil { + return err + } + natIdx, natMAC, tenantMAC = nat.Attrs().Index, nat.Attrs().HardwareAddr, tenant.Attrs().HardwareAddr + outIdx, outMAC = out.Attrs().Index, rx.Attrs().HardwareAddr + return netlink.LinkSetXdpFdWithFlags(nat, r.fix.LtfNat.FD(), int(xdpDrvMode)) + }) + snat := localfixture.FixtureLtfSnatValue{OutIfindex: uint32(outIdx), Vid: r.outVID, Guest: guestAddr.As16(), + Shard: v.shard.As16()} + copy(snat.Smac[:], outMAC) + copy(snat.Dmac[:], clientMAC) + if err := r.fix.LtfSnat.Put(uint32(natIdx), snat); err != nil { + r.t.Fatal(err) + } + ret := localfixture.FixtureLtfShardValue{PeerIfindex: uint32(natIdx), Guest: guestAddr.As16()} + copy(ret.Smac[:], natMAC) + copy(ret.Dmac[:], tenantMAC) + if err := r.fix.LtfShard.Put(localfixture.FixtureLtfIn6{A: v.shard.As16()}, ret); err != nil { + r.t.Fatal(err) + } +} + +// xdpDrvMode is XDP_FLAGS_DRV_MODE. +const xdpDrvMode = 1 << 2 + +// clientSocket is a UDP socket in the client namespace. +type clientSocket struct { + conn *net.UDPConn +} + +func (r *rig) clientSocket(port int) *clientSocket { + r.t.Helper() + var c *net.UDPConn + r.in(r.client, func() error { + var err error + c, err = net.ListenUDP("udp6", &net.UDPAddr{IP: net.IP(client.AsSlice()), Port: port}) + return err + }) + r.t.Cleanup(func() { _ = c.Close() }) + return &clientSocket{conn: c} +} + +func (c *clientSocket) send(t *testing.T, to netip.Addr, port int, payload string) { + t.Helper() + if _, err := c.conn.WriteToUDP([]byte(payload), &net.UDPAddr{IP: net.IP(to.AsSlice()), Port: port}); err != nil { + t.Fatalf("send to %s: %v", to, err) + } +} + +// recv returns the next datagram within wait, and false when none arrives. +func (c *clientSocket) recv(wait time.Duration) (netip.Addr, string, bool) { + buf := make([]byte, 2048) + _ = c.conn.SetReadDeadline(time.Now().Add(wait)) + n, from, err := c.conn.ReadFromUDPAddrPort(buf) + if err != nil { + return netip.Addr{}, "", false + } + return from.Addr().Unmap(), string(buf[:n]), true +} + +// expect reads datagrams until one carries payload, and fails unless it +// arrives from want. +func (c *clientSocket) expect(t *testing.T, want netip.Addr, payload string) { + t.Helper() + deadline := time.Now().Add(3 * time.Second) + for time.Now().Before(deadline) { + from, got, ok := c.recv(time.Until(deadline)) + if !ok { + break + } + if got == payload { + if from != want { + t.Fatalf("%q arrived from %s, want %s", payload, from, want) + } + return + } + } + t.Fatalf("the client never received %q", payload) +} + +// absent fails if a datagram carrying payload arrives within a short wait. +func (c *clientSocket) absent(t *testing.T, payload string) { + t.Helper() + deadline := time.Now().Add(500 * time.Millisecond) + for time.Now().Before(deadline) { + _, got, ok := c.recv(time.Until(deadline)) + if !ok { + return + } + if got == payload { + t.Fatalf("the client received %q, which policy denies", payload) + } + } +} + +// guest is a TAP's reader: the hypervisor and its guest. It answers +// Neighbor Discovery for guestAddr and queues every UDP frame. +type guest struct { + file *os.File + hostMAC net.HardwareAddr + frames chan udpFrame + done chan struct{} + once sync.Once +} + +func newGuest(name string) (*guest, error) { + fd, err := unix.Open("/dev/net/tun", unix.O_RDWR|unix.O_CLOEXEC|unix.O_NONBLOCK, 0) + if err != nil { + return nil, err + } + ifr, err := unix.NewIfreq(name) + if err != nil { + _ = unix.Close(fd) + return nil, err + } + ifr.SetUint16(unix.IFF_TAP | unix.IFF_NO_PI | unix.IFF_VNET_HDR) + if err := unix.IoctlIfreq(fd, unix.TUNSETIFF, ifr); err != nil { + _ = unix.Close(fd) + return nil, fmt.Errorf("create TAP %s: %w", name, err) + } + g := &guest{file: os.NewFile(uintptr(fd), name), frames: make(chan udpFrame, 64), done: make(chan struct{})} + go g.run() + return g, nil +} + +func (g *guest) close() { + g.once.Do(func() { + _ = g.file.Close() + <-g.done + }) +} + +func (g *guest) run() { + defer close(g.done) + buf := make([]byte, 65536) + for { + n, err := g.file.Read(buf) + if err != nil { + if errors.Is(err, os.ErrClosed) { + return + } + continue + } + if n <= vnetHdrLen { + continue + } + f := buf[vnetHdrLen:n] + if target, from, mac, ok := neighborSolicitation(f); ok { + if target == guestAddr { + _, _ = g.file.Write(vnet(neighborAdvertisement(guestMAC, guestAddr, from, mac), false)) + } + continue + } + if u, ok := parseUDP(f); ok { + // The host hands a frame with a checksum to finish when its + // sender left it; only the payload is compared then. + if buf[0]&vnetNeedsCsum != 0 { + u.checksumVerified = true + } + select { + case g.frames <- u: + default: + } + } + } +} + +// send writes a UDP frame from the guest to the host. +func (g *guest) send(t *testing.T, src, dst netip.Addr, sport, dport uint16, payload string, partial bool) { + t.Helper() + f := udp(guestMAC, g.hostMAC, src, dst, sport, dport, []byte(payload), partial) + if _, err := g.file.Write(vnet(f, partial)); err != nil { + t.Fatalf("guest send: %v", err) + } +} + +// expect returns the guest's next frame carrying payload. +func (g *guest) expect(t *testing.T, payload string) udpFrame { + t.Helper() + deadline := time.After(3 * time.Second) + for { + select { + case u := <-g.frames: + if string(u.payload) == payload { + if !u.checksumVerified { + t.Fatalf("%q reached the guest with a bad checksum", payload) + } + return u + } + case <-deadline: + t.Fatalf("the guest never received %q", payload) + return udpFrame{} + } + } +} + +// absent fails if a frame carrying payload reaches the guest within a short +// wait. +func (g *guest) absent(t *testing.T, payload string) { + t.Helper() + deadline := time.After(500 * time.Millisecond) + for { + select { + case u := <-g.frames: + if string(u.payload) == payload { + t.Fatalf("the guest received %q, which it must not", payload) + } + case <-deadline: + return + } + } +} + +// fakePods is a PodNetns over test namespaces, by pod UID. +type fakePods struct { + mu sync.Mutex + pods map[string]ns.NetNS +} + +func (f *fakePods) add(uid string, n ns.NetNS) { + f.mu.Lock() + defer f.mu.Unlock() + if f.pods == nil { + f.pods = map[string]ns.NetNS{} + } + f.pods[uid] = n +} + +func (f *fakePods) Open(uid string) (nsHandle, error) { + f.mu.Lock() + n, ok := f.pods[uid] + f.mu.Unlock() + if !ok { + return nsNone(), fmt.Errorf("%w: pod %s", ErrPodNotFound, uid) + } + // A test namespace's path can name another thread's namespace; its + // descriptor does not. + fd, err := unix.Dup(int(n.Fd())) + if err != nil { + return nsNone(), err + } + return netns.NsHandle(fd), nil +} + +type nsHandle = netns.NsHandle + +func nsNone() netns.NsHandle { return netns.None() } + +func statsOf(m *ebpf.Map) (map[string]uint64, error) { return localprog.Stats(m) } + +// stats reads the Local counters. +func (r *rig) stats() map[string]uint64 { + r.t.Helper() + m, err := ebpf.LoadPinnedMap(filepath.Join(r.pin, "local", "lt_stats"), nil) + if err != nil { + r.t.Fatal(err) + } + defer m.Close() //nolint:errcheck // test descriptor + s, err := statsOf(m) + if err != nil { + r.t.Fatal(err) + } + return s +} + +// fixShard returns the gateway stand-in's return entry for shard. +func (r *rig) fixShard(shard netip.Addr) (localfixture.FixtureLtfShardValue, error) { + var v localfixture.FixtureLtfShardValue + err := r.fix.LtfShard.Lookup(localfixture.FixtureLtfIn6{A: shard.As16()}, &v) + return v, err +} + +// fixPutShard makes the gateway stand-in send a return for shard as v says. +func (r *rig) fixPutShard(shard netip.Addr, v localfixture.FixtureLtfShardValue) error { + return r.fix.LtfShard.Put(localfixture.FixtureLtfIn6{A: shard.As16()}, v) +} diff --git a/internal/worker/local/routed.go b/internal/worker/local/routed.go new file mode 100644 index 00000000..03f30c42 --- /dev/null +++ b/internal/worker/local/routed.go @@ -0,0 +1,155 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "errors" + "fmt" + "net" + "net/netip" + + "github.com/vishvananda/netlink" + "github.com/vishvananda/netns" + "golang.org/x/sys/unix" + + "go.datum.net/galactic/internal/plumbing/ebpf/egressroutemap" + "go.datum.net/galactic/internal/plumbing/ebpf/localprog" +) + +// ensureRouted makes r's link exist from the VPC's VRF to its pod, with its +// routes and pass-through entries in the VPC's table and its guard. entries +// are the table's exact entries, which ensureRouted updates as it writes. +func (p *pass) ensureRouted(r routedWant, entries map[netip.Prefix]egressroutemap.Entry) error { + podNS, err := p.k.Pods.Open(r.podUID) + if err != nil { + return err + } + defer podNS.Close() //nolint:errcheck // our own descriptor + got, ok := p.h.readRouted(r, podNS) + if !ok { + if p.dry { + return errDirty + } + if got, err = p.k.createRouted(p.h, r, podNS); err != nil { + return err + } + } + hl := got.host + if err := placeInVRF(hl, p.vrfIdx, p.dry); err != nil { + return err + } + if err := p.ensureRoutes(r, hl.Attrs().Index, entries); err != nil { + return err + } + gv := localprog.LocalLtGuardValue{Count: uint32(len(r.addrs))} + for i, a := range r.addrs { + gv.Addr[i] = a.As16() + } + if err := putRow(p.objs.Maps.Guard, uint32(hl.Attrs().Index), gv, p.dry, "guard of "+r.host); err != nil { + return err + } + return p.k.ensureFilter(hl, filterLinkGuard, p.dry) +} + +// createRouted creates r's link, its host end in the calling namespace and +// its pod end in podNS. A link of the same name to an earlier pod goes first. +func (k *Kernel) createRouted(h *host, r routedWant, podNS netns.NsHandle) (routedLink, error) { + if err := h.collision(r.host, alias(r.key)); err != nil { + return routedLink{}, err + } + if l := h.byName[r.host]; l != nil { + // The owner's pod was replaced: the link to the old pod goes. + if err := netlink.LinkDel(l); err != nil && !errors.Is(err, unix.ENODEV) { + return routedLink{}, fmt.Errorf("local: delete routed link %s: %w", r.host, err) + } + } + v := &netlink.Veth{LinkAttrs: netlink.LinkAttrs{Name: r.host, MTU: k.mtu()}, PeerName: r.pod} + if err := netlink.LinkAdd(v); err != nil { + return routedLink{}, fmt.Errorf("local: create routed link %s: %w", r.host, err) + } + pl, err := netlink.LinkByName(r.pod) + if err != nil { + return routedLink{}, fmt.Errorf("local: look up new pod end %s: %w", r.pod, err) + } + if err := netlink.LinkSetNsFd(pl, int(podNS)); err != nil { + _ = netlink.LinkDel(pl) + return routedLink{}, fmt.Errorf("local: move %s into the pod: %w", r.pod, err) + } + l, err := netlink.LinkByName(r.host) + if err != nil { + return routedLink{}, fmt.Errorf("local: look up new routed link %s: %w", r.host, err) + } + if err := netlink.LinkSetAlias(l, alias(r.key)); err != nil { + return routedLink{}, fmt.Errorf("local: mark routed link %s: %w", r.host, err) + } + if err := setUpInPod(podNS, r.pod, alias(r.key)); err != nil { + return routedLink{}, err + } + if l, err = netlink.LinkByName(r.host); err != nil { + return routedLink{}, err + } + peer, err := netlink.VethPeerIndex(l.(*netlink.Veth)) + if err != nil { + return routedLink{}, fmt.Errorf("local: read routed link peer: %w", err) + } + return routedLink{host: l, podIndex: peer}, nil +} + +// placeInVRF enslaves l to vrfIdx and sets it up. +func placeInVRF(l netlink.Link, vrfIdx int, dry bool) error { + name := l.Attrs().Name + if err := fix(dry, l.Attrs().MasterIndex != vrfIdx, func() error { + if err := netlink.LinkSetMasterByIndex(l, vrfIdx); err != nil { + return fmt.Errorf("local: enslave %s: %w", name, err) + } + return nil + }); err != nil { + return err + } + return fix(dry, l.Attrs().Flags&net.FlagUp == 0, func() error { + if err := netlink.LinkSetUp(l); err != nil { + return fmt.Errorf("local: set %s up: %w", name, err) + } + return nil + }) +} + +// ensureRoutes routes each of r's addresses to the host end hostIdx in the +// VPC's table, and writes its pass-through entry where the table holds no +// exact entry for it. +func (p *pass) ensureRoutes(r routedWant, hostIdx int, entries map[netip.Prefix]egressroutemap.Entry) error { + for _, a := range r.addrs { + dst := netip.PrefixFrom(a, 128) + have, err := netlink.RouteListFiltered(netlink.FAMILY_V6, + &netlink.Route{Table: int(p.table), Dst: ipnet(dst), LinkIndex: hostIdx}, + netlink.RT_FILTER_TABLE|netlink.RT_FILTER_DST|netlink.RT_FILTER_OIF) + if err != nil { + return fmt.Errorf("local: list routes to %s: %w", dst, err) + } + if err := fix(p.dry, len(have) == 0, func() error { + route := &netlink.Route{Table: int(p.table), Dst: ipnet(dst), LinkIndex: hostIdx, + Scope: netlink.SCOPE_LINK} + if err := netlink.RouteReplace(route); err != nil { + return fmt.Errorf("local: route %s via %s: %w", dst, r.host, err) + } + return nil + }); err != nil { + return err + } + // An exact entry another writer holds is left alone: a + // pass-through already passes the address on, and an encapsulating + // entry is that writer's to change. + _, exists := entries[dst] + if err := fix(p.dry, !exists, func() error { + return p.routes.RegisterPassThroughAs(p.table, ipnet(dst), egressroutemap.PassThroughLocal) + }); err != nil { + return err + } + if !exists { + entries[dst] = egressroutemap.Entry{PassThrough: true, Owner: egressroutemap.PassThroughLocal} + } + } + return nil +} diff --git a/internal/worker/local/watch.go b/internal/worker/local/watch.go new file mode 100644 index 00000000..55bb0125 --- /dev/null +++ b/internal/worker/local/watch.go @@ -0,0 +1,113 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "context" + "fmt" + + "github.com/vishvananda/netlink" + "golang.org/x/sys/unix" + + "go.datum.net/galactic/internal/gc" + "go.datum.net/galactic/internal/plumbing/intf" +) + +// Watch requeues the VPCs a link or neighbor event touches, beyond the +// events hostscope.Watch already maps to VPCs (a link joining, leaving or +// changing in a VPC's VRF): +// +// - a Local link outside any VRF, such as a pair's NAT end gaining or +// losing the client's XDP program, requeues its VPC; +// - any other link outside a VRF, such as a receiving device or its bond or +// VLAN, requeues every VPC with a local.tap claim; +// - a neighbor event on a VPC's tenant interface requeues that VPC while +// one of its destinations waits on a failed neighbor. +// +// It returns once subscribed and stops when ctx is done. A lost subscription +// is reported through errs; the periodic resync still covers every VPC. +func (m *Module) Watch(ctx context.Context, changed func(vpc string), errs func(error)) error { + links := make(chan netlink.LinkUpdate, 256) + neighs := make(chan netlink.NeighUpdate, 256) + done := make(chan struct{}) + if err := netlink.LinkSubscribeWithOptions(links, done, + netlink.LinkSubscribeOptions{ErrorCallback: errs}); err != nil { + return fmt.Errorf("local: subscribe to link events: %w", err) + } + if err := netlink.NeighSubscribeWithOptions(neighs, done, + netlink.NeighSubscribeOptions{ErrorCallback: errs}); err != nil { + close(done) + return fmt.Errorf("local: subscribe to neighbor events: %w", err) + } + go func() { + defer close(done) + for { + select { + case <-ctx.Done(): + return + case u, ok := <-links: + if !ok { + return + } + for _, vpc := range m.linkEvent(u) { + changed(vpc) + } + case u, ok := <-neighs: + if !ok { + return + } + for _, vpc := range m.neighEvent(u) { + changed(vpc) + } + } + } + }() + return nil +} + +// linkEvent returns the VPCs a link event touches. +func (m *Module) linkEvent(u netlink.LinkUpdate) []string { + a := u.Attrs() + if v, _, ok := parseAlias(a.Alias); ok && intf.IsLocalLinkName(a.Name) { + return []string{v} + } + if a.MasterIndex != 0 && u.Header.Type != unix.RTM_DELLINK { + // Enslaved to a VRF (hostscope.Watch) or a bond, whose own event + // follows. + if master, err := netlink.LinkByIndex(a.MasterIndex); err == nil && master.Type() == linkVRF { + return nil + } + } + if u.Type() == linkVRF || u.Type() == linkTunTap { + return nil + } + return m.tapVPCs() +} + +// neighEvent returns the VPCs a neighbor event touches. +func (m *Module) neighEvent(u netlink.NeighUpdate) []string { + waiting := m.neighborVPCs() + if len(waiting) == 0 { + return nil + } + l, err := netlink.LinkByIndex(u.LinkIndex) + if err != nil || l.Attrs().MasterIndex == 0 { + return nil + } + master, err := netlink.LinkByIndex(l.Attrs().MasterIndex) + if err != nil { + return nil + } + vpc, ok := gc.VPCFromVRFName(master.Attrs().Name) + if !ok { + return nil + } + for _, w := range waiting { + if w == vpc { + return []string{vpc} + } + } + return nil +} diff --git a/internal/worker/module/module.go b/internal/worker/module/module.go index ed3c7c82..88c65464 100644 --- a/internal/worker/module/module.go +++ b/internal/worker/module/module.go @@ -59,6 +59,10 @@ type Destination struct { // They are empty when the attachment records none, such as for a guest // that manages its own addressing. Addresses []netip.Addr + // HostInterface is the host-side link of the destination's attachment, + // from its trusted source, which a Local destination is delivered + // through. It is empty until CNI has attached it. + HostInterface string } // DestinationID is the identity of a destination within a claim. @@ -82,6 +86,12 @@ type Claim struct { Owner string Generation uint64 Handoff workerv1alpha1.Handoff + // OwnerPod is the UID of the pod the owner last called from, which a + // routed link's pod end is created in. + OwnerPod string + // Addresses are the addresses of the claim's own attachment, from its + // trusted source: for a routed link, the sources its pod end may use. + Addresses []netip.Addr // Destinations are the claim's resolved destinations for the module's // mode, each with an available capability. Destinations []Destination @@ -152,6 +162,23 @@ type Module interface { Read(ctx context.Context, scope Scope) (State, error) } +// HandoffInterface is an interface a module created for a claim's handoff, +// reported to the claim's owner. +type HandoffInterface struct { + // Role is one of the workerv1alpha1.HandoffRole* values. + Role string + Name string + Ifindex int32 +} + +// HandoffReporter is implemented by a module that creates interfaces for a +// claim's handoff. Worker reports them in the claim's status. +type HandoffReporter interface { + // HandoffInterfaces returns the interfaces the module has created for + // each claim of scope, as of its last Read. + HandoffInterfaces(scope Scope) map[ClaimKey][]HandoffInterface +} + // Registry is the set of modules Worker runs and the capability status it // reports. type Registry struct { diff --git a/internal/worker/reconcile.go b/internal/worker/reconcile.go index e7178c8c..ae85a685 100644 --- a/internal/worker/reconcile.go +++ b/internal/worker/reconcile.go @@ -164,7 +164,15 @@ func (w *Worker) Reconcile(ctx context.Context, vpc string) error { } state[m.Mode()] = st } - return w.report(evals, state) + handoffs := map[module.ClaimKey][]module.HandoffInterface{} + for _, m := range mods { + if r, ok := m.(module.HandoffReporter); ok { + for k, ifs := range r.HandoffInterfaces(scope) { + handoffs[k] = append(handoffs[k], ifs...) + } + } + } + return w.report(evals, state, handoffs) } // planClaimedHost reports whether the canonical host state of vpc, which @@ -459,7 +467,8 @@ func (w *Worker) resolve(ctx context.Context, vpc string, claims []claim) ( } for mode, dests := range perMode { desired[mode] = append(desired[mode], module.Claim{Key: e.key, Owner: e.owner, Generation: e.gen, - Handoff: c.spec.GetHandoff(), Destinations: dests}) + Handoff: c.spec.GetHandoff(), OwnerPod: c.rec.PodUID, Addresses: slices.Clone(att.Addresses), + Destinations: dests}) } } return evals, desired, nil @@ -512,7 +521,7 @@ func (w *Worker) resolveDestination(ctx context.Context, vpc string, own netip.P } de.mode, de.resolved = mode, true return module.Destination{ID: de.id, Ref: d, Mode: mode, VPC: att.VPC, Node: att.Node, Locator: loc, - Addresses: slices.Clone(att.Addresses)}, nil + Addresses: slices.Clone(att.Addresses), HostInterface: att.HostInterface}, nil } func modeName(m workerv1alpha1.Mode) string { @@ -568,7 +577,8 @@ func (w *Worker) reportFailure(evals []*claimEval, reason string, err error) { // report turns read-back into status, and deletes released claims whose // programmed state is gone. -func (w *Worker) report(evals []*claimEval, state map[workerv1alpha1.Mode]module.State) error { +func (w *Worker) report(evals []*claimEval, state map[workerv1alpha1.Mode]module.State, + handoffs map[module.ClaimKey][]module.HandoffInterface) error { present := func(k module.ClaimKey) bool { for _, st := range state { if len(st[k]) > 0 { @@ -594,6 +604,11 @@ func (w *Worker) report(evals []*claimEval, state map[workerv1alpha1.Mode]module continue } w.applyStatus(c, e, state) + c.status.HandoffInterfaces = nil + for _, h := range handoffs[e.key] { + c.status.HandoffInterfaces = append(c.status.HandoffInterfaces, + &workerv1alpha1.HandoffInterface{Role: h.Role, Name: h.Name, Ifindex: h.Ifindex}) + } w.publish(c) } w.mu.Unlock() @@ -708,6 +723,7 @@ func (w *Worker) forget(k module.ClaimKey, gen uint64) error { c.status.Released = true c.status.ObservedGeneration = gen c.status.Destinations = nil + c.status.HandoffInterfaces = nil w.publish(c) w.mu.Unlock() updateClaimGauge(w) diff --git a/internal/worker/sources/sources.go b/internal/worker/sources/sources.go index f4616381..d2e40493 100644 --- a/internal/worker/sources/sources.go +++ b/internal/worker/sources/sources.go @@ -46,6 +46,10 @@ type Attachment struct { // without their prefix lengths. A VPCAttachment whose guest manages its // own addressing records none, and neither does an EdgeAttachment. Addresses []netip.Addr + // HostInterface is the host-side link CNI created for a VPCAttachment, + // as its status records: the TAP or host veth. It is empty for an + // attachment not yet attached and for an EdgeAttachment. + HostInterface string } // Sources answers Worker's trusted-source lookups. @@ -90,7 +94,8 @@ func (k Kube) Attachment(ctx context.Context, uid string) (Attachment, bool, err if len(vas.Items) == 1 { a := vas.Items[0] return Attachment{UID: uid, Kind: KindVPCAttachment, VPC: a.Status.VPC, Node: a.Status.Node, - Admitted: a.DeletionTimestamp.IsZero(), Addresses: interfaceAddresses(a.Spec.Interface.Addresses)}, true, nil + Admitted: a.DeletionTimestamp.IsZero(), Addresses: interfaceAddresses(a.Spec.Interface.Addresses), + HostInterface: a.Status.HostInterface}, true, nil } var eas galacticv1alpha1.EdgeAttachmentList if err := k.Reader.List(ctx, &eas, client.MatchingFields{uidIndex: uid}); err != nil { diff --git a/internal/worker/store/store.go b/internal/worker/store/store.go index 03810c58..ee37f1f8 100644 --- a/internal/worker/store/store.go +++ b/internal/worker/store/store.go @@ -34,6 +34,9 @@ type Record struct { AttachmentUID string `json:"attachmentUID"` // Owner is the ServiceAccount, "namespace/name", that created the claim. Owner string `json:"owner"` + // PodUID is the UID of the pod the owner last called from. A routed + // link's pod end is created in that pod, and only there. + PodUID string `json:"podUID,omitempty"` // Capabilities are the capabilities the owner was allowed when the // generation was accepted. Reconciliation programs no destination // whose capability is missing from them. diff --git a/scripts/required-ci.sh b/scripts/required-ci.sh index f70fade7..9dc0e932 100755 --- a/scripts/required-ci.sh +++ b/scripts/required-ci.sh @@ -5,7 +5,7 @@ sudo apt-get -o Acquire::Retries=3 -o Acquire::http::Timeout=10 -o Acquire::http sudo apt-get -o Acquire::Retries=3 -o Acquire::http::Timeout=10 -o Acquire::https::Timeout=10 install -y --no-install-recommends clang-18 llvm-18 linux-libc-dev export BPF2GO_CC=clang-18 -for pkg in prog edgeprog natprog xdpdispatch xmitdrops; do +for pkg in prog edgeprog natprog xdpdispatch xmitdrops localprog; do go generate "./internal/plumbing/ebpf/$pkg/..." done go generate ./tests/handoffs/probe/... From 400e1528628bd9b79408d7c53a9539a7ce42927c Mon Sep 17 00:00:00 2001 From: Peter Sprygada Date: Thu, 19 Nov 2026 05:35:50 -0500 Subject: [PATCH 2/5] docs(worker): Specify the Local module and its ownership Record how the Local module implements the handoffs the contract specifies: its programs and hooks, link and filter ownership, readiness checks and reasons, trust of public ingress, the handoff_interfaces status field, and which writer steers public flows into a handoff. The ownership inventory names the Local module as the sole mutator of its tc filters, its handoff links and its maps. D28 records the accepted decisions; D29 proposes routed-link addressing by the claim attachment's addresses and resolver-written steering entries. --- deploy/containerlab/docs/handoffs.md | 6 ++ docs/worker/README.md | 2 + docs/worker/contract.md | 130 ++++++++++++++++++++++----- docs/worker/ownership.md | 43 ++++----- 4 files changed, 138 insertions(+), 43 deletions(-) diff --git a/deploy/containerlab/docs/handoffs.md b/deploy/containerlab/docs/handoffs.md index 995eaada..13843f0f 100644 --- a/deploy/containerlab/docs/handoffs.md +++ b/deploy/containerlab/docs/handoffs.md @@ -143,6 +143,12 @@ own owner) for the client's prefix and the routed link in both VRFs, which is what Worker programs for a Local destination; see [contract amendments](../../../docs/worker/contract.md#local-handoffs). +Worker's Local module (`internal/worker/local`, +[#1435](https://github.com/datum-cloud/galactic/issues/1435)) now programs the +tc side of these handoffs as product code; its tests reuse the stand-ins for +the gateway's and NAT's XDP programs (`localprog/localfixture`). See +[the Local module](../../../docs/worker/contract.md#the-local-module). + ## Cells Each cell builds one receiving device, places the prototypes in one mode, and diff --git a/docs/worker/README.md b/docs/worker/README.md index a816439c..e566a40c 100644 --- a/docs/worker/README.md +++ b/docs/worker/README.md @@ -62,3 +62,5 @@ PR. "Confirmed" means the product owner approved the decision on the date given. | D25 | Each destination reports `forward_ready` and `return_ready`; `ready` requires both | Accepted | [Contract](contract.md#state-model) | | D26 | A destination's addresses come from its VPCAttachment's spec; one with none reports `DestinationAddressUnknown` | Accepted | [Contract](contract.md#trusted-sources) | | D27 | Local handoffs as #1444 proved them: native XDP on the veth peer, VLAN and checksum limits, per-path policy, Local pass-through | Proposed | [Contract](contract.md#local-handoffs) | +| D28 | Local owns its handoff links and tc filters, after CNI's; status lists them; fragments to a TAP are refused | Accepted | [Contract](contract.md#the-local-module) | +| D29 | A routed link's pod end uses its attachment's addresses as `/128` routes; resolvers write steering entries | Proposed | [Contract](contract.md#the-local-module) | diff --git a/docs/worker/contract.md b/docs/worker/contract.md index 449720ee..b7c9f825 100644 --- a/docs/worker/contract.md +++ b/docs/worker/contract.md @@ -173,6 +173,10 @@ EdgeAttachment condition names where they mean the same thing: | `Ready` | `Programmed` is true and observed state shows every handoff can carry traffic. | | `Withdrawing` | A release, revocation or lease expiry is removing programmed state. Status names the withdrawal scope. | +A claim's status also lists `handoff_interfaces`: each interface Worker +created for the claim's handoff, by role, name and ifindex +([the Local module](#the-local-module)). + The withdrawal scope names what stops: one destination, one claim, every claim of a caller, or a whole VPC on the node. Operators read it to judge the reach of a withdrawal ([#1441](https://github.com/datum-cloud/galactic/issues/1441)). @@ -215,16 +219,17 @@ so Worker compares VPC identity, never addresses. [#1444](https://github.com/datum-cloud/galactic/issues/1444) proved each Local handoff on the [qualified platform](qualification.md), with prototypes placed by today's loaders (D27). Each row below is the mechanism the Local module -([#1435](https://github.com/datum-cloud/galactic/issues/1435)) programs, and -each requirement is part of that handoff's `Ready`. The scripts, captures and -results are in -[the lab's handoff checks](../../deploy/containerlab/docs/handoffs.md). - -| Capability | Mechanism | -| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `local.tap` | A dispatcher slot on the receiving interface returns `XDP_PASS` with metadata naming the TAP. A tc ingress program on the same interface decides the TAP's ingress policy, marks the packet decided and delivers with `bpf_redirect_neigh`. The reply leaves from the TAP's tc ingress. | -| `local.veth_pair` | A tc program on the tenant TAP or veth redirects into the pair's tenant end. XDP on the NAT end runs the shard. The return is redirected into the NAT end and received by tc on the tenant end, which decides policy and delivers. | -| `local.routed_link`, `local.socket` | A veth from a VRF in the pod to the tenant VRF on the host, with a `/127` on each end. A socket bound to the pod's VRF (`SO_BINDTODEVICE`) sends and receives through it with no redirect; the kernel routes both ways. | +([#1435](https://github.com/datum-cloud/galactic/issues/1435), +`internal/worker/local`) programs, and each requirement is part of that +handoff's `Ready`. The scripts, captures and results are in +[the lab's handoff checks](../../deploy/containerlab/docs/handoffs.md); +[the Local module](#the-local-module) describes the implementation. + +| Capability | Mechanism | +| ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `local.tap` | A dispatcher slot on the receiving interface returns `XDP_PASS` with metadata naming the TAP. A tc ingress program on the same interface decides the TAP's ingress policy, marks the packet decided and delivers with `bpf_redirect_neigh`. The reply leaves from the TAP's tc ingress. | +| `local.veth_pair` | A tc program on the tenant TAP or veth redirects into the pair's tenant end. XDP on the NAT end runs the shard. The return is redirected into the NAT end and received by tc on the tenant end, which decides policy and delivers. | +| `local.routed_link`, `local.socket` | A veth from a VRF in the pod to the tenant VRF on the host. Its pod end uses the claim attachment's addresses (D26), each routed as a `/128` to the host end in the tenant VRF (D29). A socket bound to the pod's VRF (`SO_BINDTODEVICE`) sends and receives through it with no redirect; the kernel routes both ways. | These amend the mechanisms the qualification plan first named: @@ -259,10 +264,14 @@ These amend the mechanisms the qualification plan first named: Without one, `usid_egress` sends a tenant's packet for a Local peer (a public client, the shard address's client, the routed link) to the VPC's `::/0` NAT route, encapsulated. Worker writes the pass-through under its own owner. The - egress decision `usid_egress` then makes is on the Private path, so until - [#1435](https://github.com/datum-cloud/galactic/issues/1435) moves the Local - branch into `usid_egress`, a tenant's Private egress grant also governs its - Local flows, and the handoff's own program decides again on the right path. + egress decision `usid_egress` then makes is on the Private path, so while + the Local branch stays out of `usid_egress`, a tenant's Private egress grant + also governs its Local flows, and the handoff's own program decides again + on the right path. [#1435](https://github.com/datum-cloud/galactic/issues/1435) + keeps the branch out (D28): the Local module writes the entries for the + prefixes its own handoffs serve, a routed link's addresses + (`PassThroughLocal`), and the resolver that selects a handoff writes the + entries that steer a tenant's public flows into it (D29). - **No other tc owner may claim a tenant TAP.** A node's other datapath, Cilium in particular, must never attach to a tenant interface. Deployed configurations meet this by pinning Cilium's `devices` to the node's uplink @@ -280,17 +289,87 @@ These amend the mechanisms the qualification plan first named: - **A handoff program on a tenant interface runs after galactic-cni's own.** Its filters take the lowest tc priorities on the interface's ingress, so a separate Local filter sits at the next priority and sees only what - `usid_egress` passed on. #1435 either keeps that order or moves the Local - branch into `usid_egress`. + `usid_egress` passed on. #1435 keeps that order (D28). Each handoff places requirements on its interfaces: -| Handoff | Requirement | -| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `local.tap` | The TAP has carrier only while its reader (the hypervisor) holds it; Worker reports `HandoffInterfaceMissing` until then. `bpf_redirect_neigh` does not check the TAP's MTU: the lab delivered 8049-byte packets into a TAP at MTU 1500, and its guest took them. A real guest drops frames above its own MTU, with no ICMPv6 Packet Too Big to the sender, so the TAP's MTU is at least the receiving path's. IPv6 fragments to a TAP guest were not delivered in either mode; #1435 decides whether Local delivery reassembles or refuses them. | -| `local.veth_pair` | The tenant end of the pair needs GRO (or an XDP program) for a native `XDP_REDIRECT` into the pair to be received. XDP rewrites checksums as complete, so a frame with an offloaded, partial checksum is corrupted; see the checksum row in the [qualification plan](qualification.md#handoffs). | -| `local.routed_link` | The host end is a tenant interface the pod controls. It drops any source outside its `/127`, and the routed link's prefix has a pass-through entry in the tenant VRF. | -| `local.socket` | The socket is bound to the pod's VRF. An unbound socket uses the pod's main table and reaches no tenant. | +| Handoff | Requirement | +| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `local.tap` | The TAP has carrier only while its reader (the hypervisor) holds it; Worker reports `HandoffInterfaceMissing` until then. `bpf_redirect_neigh` does not check the TAP's MTU: the lab delivered 8049-byte packets into a TAP at MTU 1500, and its guest took them. A real guest drops frames above its own MTU, with no ICMPv6 Packet Too Big to the sender, so the TAP's MTU is at least the receiving path's. IPv6 fragments to a TAP guest were not delivered in either mode, so Local refuses them: `local_rx` drops and counts an IPv6 fragment (D28). `local_rx` also drops a packet larger than the TAP's MTU, and the destination reports `HandoffMTUTooSmall` while the TAP's MTU is below a receiving device's. | +| `local.veth_pair` | The tenant end of the pair needs GRO (or an XDP program) for a native `XDP_REDIRECT` into the pair to be received. XDP rewrites checksums as complete, so a frame with an offloaded, partial checksum is corrupted; see the checksum row in the [qualification plan](qualification.md#handoffs). Local creates the pair with GRO on and transmit checksum offload off at the tenant end, so the kernel finishes a partial checksum, and segments a GSO packet, before the NAT end's program sees it. | +| `local.routed_link` | The host end is a tenant interface the pod controls. It drops any source but the claim attachment's IPv6 addresses (at most four) and link-local ones, and each of those addresses has a route to the host end and a pass-through entry in the tenant VRF (D29). | +| `local.socket` | The socket is bound to the pod's VRF. An unbound socket uses the pod's main table and reaches no tenant. | + +### The Local module + +`internal/worker/local` is the Local module, registered with the Fabric module +in `cmd/galactic-worker`. Its tc programs are in +`internal/plumbing/ebpf/localprog` and include the uSID datapath, so every +policy decision runs `tp_capture` and `tp_decide` against the maps galactic-cni +pinned. Its own maps (`lt_*`) are pinned under `/sys/fs/bpf/galactic-local` +(`--local-pin-dir`), so a restarted Worker keeps the rows the running programs +read. + +| Program | Hook | Does | +| ------------------ | ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `local_rx` | tc ingress of each public receiving device: its bond, or its VLANs when it has any | Delivers a packet whose metadata (`localprog/local_meta.h`) names a TAP a `local.tap` claim authorizes, on the PublicService path, and records the flow. A packet without the metadata goes on to the kernel. | +| `local_link_rx` | tc ingress of each destination's tenant interface, after galactic-cni's filters | Sends a recorded flow's reply out of the device the flow arrived on, on the PublicService path, and a flow whose destination has a `PassThroughLocalNAT` entry into the VPC's pair, on the PublicNAT path. | +| `local_pair_rx` | tc ingress of a pair's tenant end | Delivers the NAT end's return to the destination address it names in the pair's VPC, on the PublicNAT path. | +| `local_link_guard` | tc ingress of a routed link's host end | Drops any source the link was not given. | + +The module keeps link lifecycle apart from program ownership. CNI creates and +deletes tenant TAPs and veths; the module attaches only its own filters and +rows to them, keyed by their current ifindex, and reprograms them when CNI +replaces an interface. The module creates the service-internal veth pair of a +`veth_pair` claim and the routed link of a `routed_link` or `socket` claim, +names them `G` with the alias +`galactic-local:/`, and deletes them when the claim goes. It +creates a routed link's pod end only in the pod Worker authenticated the +claim's owner from: it finds a process of that pod through its cgroup, as the +API's peer check does (D21), and refuses a pod on the host's network. A +duplicate `Request` from the owner's new pod moves the link there. + +A destination is programmed when the module's rows and filters are in place, +confirmed by read-back. It is ready when, in addition: + +- its tenant interface is in the VPC's VRF, has carrier and carries + galactic-cni's chain (`HandoffInterfaceMissing` otherwise); +- the module's filters are current (`HandoffHookMissing`); +- for `local.tap`, a receiving device's dispatcher runs a live public slot + (`DispatcherSlotUnclaimed`) and the TAP's MTU covers the device's + (`HandoffMTUTooSmall`); +- for `local.veth_pair`, the client's program runs native on the NAT end + (`HandoffHookMissing`, or `HookUnsupported` in generic mode), and the pair + has carrier; +- for `local.routed_link`, the link reaches the owner's current pod and has + carrier, which it has once the pod brings its end up; +- the destination's neighbor has not failed (`NeighborUnresolved`). A neighbor + not yet resolved is no failure: `bpf_redirect_neigh` resolves it. + +Forward readiness covers the path from the handoff to the destination and +return readiness the path back, so a missing hook withdraws only the direction +it carries. + +Public ingress cannot assert tenant context. Only an XDP program can write +skb metadata, so a packet from the wire carries none, and `local_rx` delivers +only to a TAP Local authorized and drops a packet that names any other. Every +Local program that delivers decides the receiver's policy on its own path and +sets the decided mark itself, and the pair delivers only to the destination +addresses a claim names. Every uplink discovery path skips a link Galactic +creates per VPC, including the NAT end of a pair, which lives in the host's +namespace outside any VRF (`attach.IsInternalLink`). + +A tenant's public flows enter a handoff only through `egress_route_table`. A +`PassThroughLocalNAT` entry steers into the VPC's pair, and the shard resolver +([#1437](https://github.com/datum-cloud/galactic/issues/1437)) writes it for a +Local shard. A `local.tap` reply reaches `local_link_rx` only when its +destination has a pass-through entry, so replies to clients anywhere need +either a default pass-through or a Local branch in `usid_egress`, which +[#1438](https://github.com/datum-cloud/galactic/issues/1438) decides (D29). + +The client learns the interfaces the module created from the claim's +`handoff_interfaces`: the NAT end it attaches its native XDP program to, and +the routed link's pod end it configures. ## Errors and retry @@ -327,7 +406,12 @@ Status carries these reasons besides the ones above: | `RouteWithdrawn` | `Programmed` | The tenant route covering one of the destination's addresses was withdrawn | | `RouteMismatch` | `Programmed` | The route covering one of the destination's addresses leads to another node's locator | | `UnderlayUnreachable` | `Programmed`, `Ready` | No route over an SRv6 uplink reaches the destination's locator; the entry is kept | -| `NeighborUnresolved` | `Programmed`, `Ready` | The underlay next hop has no resolved neighbor, or the entry carries an out-of-date one | +| `NeighborUnresolved` | `Programmed`, `Ready` | The underlay next hop, or a Local destination's guest, has no resolved neighbor, or the entry's is stale | +| `HandoffInterfaceMissing` | `Programmed`, `Ready` | A Local destination's interface or handoff link is missing, has no carrier or lacks galactic-cni's chain | +| `HandoffHookMissing` | `Ready` | A Local handoff program is off its hook: Local's own filter, or the client's program on a pair's NAT end | +| `DispatcherSlotUnclaimed` | `Ready` | No receiving device's XDP dispatcher runs a live public slot for a `local.tap` destination | +| `HandoffMTUTooSmall` | `Ready` | A Local destination's MTU is below its receiving path's | +| `HookUnsupported` | `Ready` | A hook runs in a mode the handoff cannot use, such as the NAT end's program in generic mode | | `ReturnPathNotProgrammed` | `Ready` | This node does not yet decapsulate the VPC's SID into the VPC's table | Clients retry with exponential backoff from 200 ms to 30 s with full jitter. diff --git a/docs/worker/ownership.md b/docs/worker/ownership.md index ba859e58..6852bf7c 100644 --- a/docs/worker/ownership.md +++ b/docs/worker/ownership.md @@ -37,25 +37,27 @@ second writer appears, the class becomes fenced. ## Writers and authorities -| Resource class | Writers at the branch start | Coordination today | Authority after transfer | Transfer step | Task | -| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -| Host VRF device and table ID (1 to `0xEFFF`) | `vrf.EnsureAndEnslave` (`internal/plumbing/vrf/vrf.go:116`) from galactic-veth and galactic-tap; `vrf.Add` (`vrf.go:93`) from `nodevpc.Ensure` in galactic-edge; `vrf.DeleteIfUnused` (`vrf.go:302`) from galactic-router GC | flock in `/var/lib/cni/galactic-vrf` (`lock.go:28`), reservations in `tables.json` (`reservation.go:35`) | Worker | CNI writes with `Exclusive`; galactic-edge calls Worker. GC moves into Worker. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) | -| Per-node VPC state, SID Argument and BGPVRFInstance | `nodevpc.Ensure` (`internal/nodevpc/ensure.go:72`) from galactic-edge (`internal/edge/agent/vpcstate.go:30`); `ClaimArgument` (`argument.go:109`) and `AllocateArgument` (`argument.go:239`) from galactic-bgp and galactic-edge; the galactic-vrf sidecar writes BGPVRFInstance directly (`internal/ingresssidecar/gateway.go:273`) | Argument flock (`argument.go:33`); the sidecar's write takes no lock | Worker | Route the sidecar's BGPVRFInstance write through Worker. `argument.go:91` records that a writer outside the lock can still collide. | [#1434](https://github.com/datum-cloud/galactic/issues/1434), [#1439](https://github.com/datum-cloud/galactic/issues/1439) for the sidecar | -| `vrf_table` datapath rows | `attachreg.RegisterDatapath` (`internal/plumbing/ebpf/attachreg/register.go:98`) and `ReleaseArgument` (`register.go:223`) from galactic-bgp and `nodevpc`; galactic-cni repair and the `SweepEBPFVRFTable` sweep (`internal/gc/gc.go:749`) | Per-key convention and sweeps; no lock | Worker | galactic-bgp registers with `Exclusive`; Worker commits its own rows as owner. The sweep runs in Worker. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) | -| `egress_route_table` rows | galactic-router (`internal/runtime/gobgp/vrfroutes.go:34`, `vrfmove.go:30`); galactic-bgp through `attachreg` (`register.go:386`, `register.go:460`); the galactic-vrf sidecar (`internal/ingresssidecar/backend.go:144`, `backend.go:159`); galactic-cni installer, repair and prune (`internal/installer/egressgroup.go:203`, `attachreg/fill.go:123`, `internal/plumbing/ebpf/sidecarmap/prune.go:80`); galactic-edge (`attachreg/hostlink.go:204`) | An in-process mutex in galactic-router only (`vrfroutes.go:81`); no cross-process lock | Worker (Fabric module) | Worker's Fabric module writes the tenant routes of every VPC Worker owns; galactic-router keeps learning EVPN routes and hands them to Worker ([handoff](contract.md#tenant-route-handoff)), writing with `Exclusive` only in a VPC Worker does not own. The installer sweep skips those tenant routes. The other writers call Worker, or use `Exclusive` until their Task moves them. | [#1436](https://github.com/datum-cloud/galactic/issues/1436); [#1439](https://github.com/datum-cloud/galactic/issues/1439) for the sidecar | -| Per-VPC kernel routes and rules | VRF unreachable defaults (`vrf.go`); the locator local route (`internal/installer/locatorroute.go`); sidecar-return routes (`internal/installer/sidecarreturn.go`) | None beyond the sidecar-return range from `0xF000` | Worker | Worker commits them as the scope owner. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) | -| Sidecar return path (tables from `0xF000`) and reaping | `ensureSidecarReturnPath` (`internal/installer/sidecarreturn.go:159`); `deleteIngressAdvertisement` and `pruneAllSidecarRows` (`internal/installer/sidecarreap.go:243`, `sidecarreap.go:264`), all in galactic-cni | Evidence from advertisement annotations and the host veth | Worker | The sidecar requests a `socket` claim; Worker programs the return path and withdraws it on release or lease expiry. | [#1439](https://github.com/datum-cloud/galactic/issues/1439) | -| BGPAdvertisement for a VPC on a node | galactic-bgp; the galactic-vrf sidecar (`gateway.go:300`); edge route publication; galactic-cni reaping (`sidecarreap.go:243`); galactic-router GC (`RunGC`, `gc.go:1265`) | CRD optimistic concurrency | Worker | CNI records its containers with `Exclusive`; Worker writes service claims and owns deletion. | [#1434](https://github.com/datum-cloud/galactic/issues/1434), [#1436](https://github.com/datum-cloud/galactic/issues/1436) | -| GC of per-VPC state | `RunGC` (`internal/gc/gc.go:1265`) in galactic-router; `SweepEBPFVRFTable` (`gc.go:749`) and `SweepEBPFNPTv6Table` (`gc.go:1146`) in galactic-cni | VRF lock; the edge fence for edge scopes | Worker | Each sweep runs in Worker as the scope owner, on the same evidence it uses today. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) | -| Edge host links | `RegisterHostLink`, `UnregisterHostLink` and `SyncHostLinkRoutes` (`attachreg/hostlink.go:50`, `:161`, `:203`) from galactic-edge | The edge VPC fence | Worker | galactic-edge calls Worker through its `Datapath` implementation ([connector](connector.md)). | [#1440](https://github.com/datum-cloud/galactic/issues/1440) | -| Attachment interface and its rows | galactic-veth and galactic-tap create and delete the device; `RegisterTenantGateway` (`register.go:632`) from galactic-bgp; `UnregisterInterface` (`attachreg/unregister.go:33`) from CNI DEL and `internal/installer/staletaps.go` | Device private to one attachment | CNI | None. Worker observes the interface and never deletes it. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) for observation | -| Sidecar pod VRFs (tables from `0x10000`) in the pod | `vrf.AddInRange` (`internal/ingresssidecar/backend.go:95`) in the pod's network namespace | Separate network namespace | galactic-vrf sidecar | None. Service-specific state stays in the service agent. | [#1439](https://github.com/datum-cloud/galactic/issues/1439) | -| BGP and EVPN route origination | galactic-router (GoBGP, from CRDs) | One process | galactic-router | None. | None | -| Pinned programs and maps in `/sys/fs/bpf/galactic` | galactic-cni loads and pins them (`internal/plumbing/ebpf/attach/attach.go:31`) | One loader | galactic-cni (loading only; rows follow their class) | None. | None | -| TC attachment on an interface | galactic-cni (`attach.go:499`) | flock `/run/galactic/tc-.lock` | galactic-cni | None. | None | -| XDP dispatcher slots | galactic-gateway (slots 0 and 1) and galactic-nat (slot 2) through `Fill`, `Clear`, `Release`, `SetRole` and `Renew` (`internal/plumbing/ebpf/xdpdispatch/dispatcher.go:678-881`), 8 slots (`dispatcher.go:60`) | Lock on the pin directory and a 120 s lease per slot | The service that holds the slot | None. Worker reads slot state for capability status only. | None | -| `/sys/fs/bpf/galactic-nat`, `galactic-edge`, `galactic-xdp` | galactic-nat; galactic-gateway; both through the dispatcher | One writer each, plus the dispatcher lock | The owning service | None. | None | -| IPAM, FRR configuration | `internal/cni/ipam`; `cmd/fabric-config-agent` | flock each | Unchanged | None. | None | +| Resource class | Writers at the branch start | Coordination today | Authority after transfer | Transfer step | Task | +| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Host VRF device and table ID (1 to `0xEFFF`) | `vrf.EnsureAndEnslave` (`internal/plumbing/vrf/vrf.go:116`) from galactic-veth and galactic-tap; `vrf.Add` (`vrf.go:93`) from `nodevpc.Ensure` in galactic-edge; `vrf.DeleteIfUnused` (`vrf.go:302`) from galactic-router GC | flock in `/var/lib/cni/galactic-vrf` (`lock.go:28`), reservations in `tables.json` (`reservation.go:35`) | Worker | CNI writes with `Exclusive`; galactic-edge calls Worker. GC moves into Worker. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) | +| Per-node VPC state, SID Argument and BGPVRFInstance | `nodevpc.Ensure` (`internal/nodevpc/ensure.go:72`) from galactic-edge (`internal/edge/agent/vpcstate.go:30`); `ClaimArgument` (`argument.go:109`) and `AllocateArgument` (`argument.go:239`) from galactic-bgp and galactic-edge; the galactic-vrf sidecar writes BGPVRFInstance directly (`internal/ingresssidecar/gateway.go:273`) | Argument flock (`argument.go:33`); the sidecar's write takes no lock | Worker | Route the sidecar's BGPVRFInstance write through Worker. `argument.go:91` records that a writer outside the lock can still collide. | [#1434](https://github.com/datum-cloud/galactic/issues/1434), [#1439](https://github.com/datum-cloud/galactic/issues/1439) for the sidecar | +| `vrf_table` datapath rows | `attachreg.RegisterDatapath` (`internal/plumbing/ebpf/attachreg/register.go:98`) and `ReleaseArgument` (`register.go:223`) from galactic-bgp and `nodevpc`; galactic-cni repair and the `SweepEBPFVRFTable` sweep (`internal/gc/gc.go:749`) | Per-key convention and sweeps; no lock | Worker | galactic-bgp registers with `Exclusive`; Worker commits its own rows as owner. The sweep runs in Worker. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) | +| `egress_route_table` rows | galactic-router (`internal/runtime/gobgp/vrfroutes.go:34`, `vrfmove.go:30`); galactic-bgp through `attachreg` (`register.go:386`, `register.go:460`); the galactic-vrf sidecar (`internal/ingresssidecar/backend.go:144`, `backend.go:159`); galactic-cni installer, repair and prune (`internal/installer/egressgroup.go:203`, `attachreg/fill.go:123`, `internal/plumbing/ebpf/sidecarmap/prune.go:80`); galactic-edge (`attachreg/hostlink.go:204`) | An in-process mutex in galactic-router only (`vrfroutes.go:81`); no cross-process lock | Worker (Fabric module) | Worker's Fabric module writes the tenant routes of every VPC Worker owns; galactic-router keeps learning EVPN routes and hands them to Worker ([handoff](contract.md#tenant-route-handoff)), writing with `Exclusive` only in a VPC Worker does not own. The installer sweep skips those tenant routes. The other writers call Worker, or use `Exclusive` until their Task moves them. Worker's Local module writes pass-through entries for the prefixes its handoffs serve, owner `PassThroughLocal`; a `PassThroughLocalNAT` entry, written by the resolver that selects a Local shard, steers a tenant's flows into the VPC's service-internal veth pair. | [#1436](https://github.com/datum-cloud/galactic/issues/1436); [#1439](https://github.com/datum-cloud/galactic/issues/1439) for the sidecar; [#1435](https://github.com/datum-cloud/galactic/issues/1435) for Local entries | +| Per-VPC kernel routes and rules | VRF unreachable defaults (`vrf.go`); the locator local route (`internal/installer/locatorroute.go`); sidecar-return routes (`internal/installer/sidecarreturn.go`) | None beyond the sidecar-return range from `0xF000` | Worker | Worker commits them as the scope owner. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) | +| Sidecar return path (tables from `0xF000`) and reaping | `ensureSidecarReturnPath` (`internal/installer/sidecarreturn.go:159`); `deleteIngressAdvertisement` and `pruneAllSidecarRows` (`internal/installer/sidecarreap.go:243`, `sidecarreap.go:264`), all in galactic-cni | Evidence from advertisement annotations and the host veth | Worker | The sidecar requests a `socket` claim; Worker programs the return path and withdraws it on release or lease expiry. | [#1439](https://github.com/datum-cloud/galactic/issues/1439) | +| BGPAdvertisement for a VPC on a node | galactic-bgp; the galactic-vrf sidecar (`gateway.go:300`); edge route publication; galactic-cni reaping (`sidecarreap.go:243`); galactic-router GC (`RunGC`, `gc.go:1265`) | CRD optimistic concurrency | Worker | CNI records its containers with `Exclusive`; Worker writes service claims and owns deletion. | [#1434](https://github.com/datum-cloud/galactic/issues/1434), [#1436](https://github.com/datum-cloud/galactic/issues/1436) | +| GC of per-VPC state | `RunGC` (`internal/gc/gc.go:1265`) in galactic-router; `SweepEBPFVRFTable` (`gc.go:749`) and `SweepEBPFNPTv6Table` (`gc.go:1146`) in galactic-cni | VRF lock; the edge fence for edge scopes | Worker | Each sweep runs in Worker as the scope owner, on the same evidence it uses today. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) | +| Edge host links | `RegisterHostLink`, `UnregisterHostLink` and `SyncHostLinkRoutes` (`attachreg/hostlink.go:50`, `:161`, `:203`) from galactic-edge | The edge VPC fence | Worker | galactic-edge calls Worker through its `Datapath` implementation ([connector](connector.md)). | [#1440](https://github.com/datum-cloud/galactic/issues/1440) | +| Attachment interface and its rows | galactic-veth and galactic-tap create and delete the device; `RegisterTenantGateway` (`register.go:632`) from galactic-bgp; `UnregisterInterface` (`attachreg/unregister.go:33`) from CNI DEL and `internal/installer/staletaps.go` | Device private to one attachment | CNI | None. Worker observes the interface and never deletes it. | [#1434](https://github.com/datum-cloud/galactic/issues/1434) for observation | +| Local handoff links: a service-internal veth pair, a pod-to-host routed link | None at the branch start; the #1444 rig created them for its checks | One writer | Worker's Local module | The module creates them for a `veth_pair`, `routed_link` or `socket` claim, marks them with the alias `galactic-local:/`, and deletes them when the claim goes. A routed link's pod end goes only into the claim owner's authenticated pod (D28). | [#1435](https://github.com/datum-cloud/galactic/issues/1435) | +| Local maps in `/sys/fs/bpf/galactic-local` | None at the branch start | One writer | Worker's Local module | None. | [#1435](https://github.com/datum-cloud/galactic/issues/1435) | +| Sidecar pod VRFs (tables from `0x10000`) in the pod | `vrf.AddInRange` (`internal/ingresssidecar/backend.go:95`) in the pod's network namespace | Separate network namespace | galactic-vrf sidecar | None. Service-specific state stays in the service agent. | [#1439](https://github.com/datum-cloud/galactic/issues/1439) | +| BGP and EVPN route origination | galactic-router (GoBGP, from CRDs) | One process | galactic-router | None. | None | +| Pinned programs and maps in `/sys/fs/bpf/galactic` | galactic-cni loads and pins them (`internal/plumbing/ebpf/attach/attach.go:31`) | One loader | galactic-cni (loading only; rows follow their class) | None. | None | +| TC attachment on an interface | galactic-cni (`attach.go:499`) | flock `/run/galactic/tc-.lock` | galactic-cni for its filters; Worker's Local module for its own | Worker's Local module is the sole mutator of its own filters (`galactic_local_*`, the priority after galactic-cni's last, handle `0x4c`), on tenant interfaces, public receiving devices and the links it creates, under galactic-cni's per-interface lock. Neither replaces the other's filters (D28). | [#1435](https://github.com/datum-cloud/galactic/issues/1435) | +| XDP dispatcher slots | galactic-gateway (slots 0 and 1) and galactic-nat (slot 2) through `Fill`, `Clear`, `Release`, `SetRole` and `Renew` (`internal/plumbing/ebpf/xdpdispatch/dispatcher.go:678-881`), 8 slots (`dispatcher.go:60`) | Lock on the pin directory and a 120 s lease per slot | The service that holds the slot | None. Worker reads slot state read-only, for capability status and the readiness of a `local.tap` destination (`xdpdispatch.Inspect`). | None | +| `/sys/fs/bpf/galactic-nat`, `galactic-edge`, `galactic-xdp` | galactic-nat; galactic-gateway; both through the dispatcher | One writer each, plus the dispatcher lock | The owning service | None. | None | +| IPAM, FRR configuration | `internal/cni/ipam`; `cmd/fabric-config-agent` | flock each | Unchanged | None. | None | NAT translations and shard sessions, Gateway VIP selection and Maglev, and Envoy's proxy sockets stay in their service agents. @@ -127,7 +129,8 @@ CNI and garbage collection. - **Observation.** Worker subscribes to link events. A link joining, leaving or changing in a VPC's VRF requeues that VPC, and `hostscope.AttachmentsOf` reads each attachment's current ifindex and neighbors when a module asks. - Worker never creates or deletes an attachment's link. + Worker never creates or deletes an attachment's link; its Local module + creates and deletes only the handoff links of its own claims. [#1436](https://github.com/datum-cloud/galactic/issues/1436) moves the router's `egress_route_table` writers: From 12e4843f8e2d924e3d5ab6ae6f1072eebc8af0ed Mon Sep 17 00:00:00 2001 From: Peter Sprygada Date: Thu, 19 Nov 2026 05:35:50 -0500 Subject: [PATCH 3/5] test(containerlab): Add a Worker claim client for lab checks worker-claim requests, observes and releases one claim from inside a lab pod, as a service agent would, so the lab can check Local and Fabric programming end to end. worker-fabric.sh now takes the allowlist from WORKER_ALLOWLIST, so a run can grant a lab pod its capabilities. --- deploy/containerlab/scripts/worker-fabric.sh | 10 +- tests/handoffs/cmd/worker-claim/main.go | 154 +++++++++++++++++++ 2 files changed, 162 insertions(+), 2 deletions(-) create mode 100644 tests/handoffs/cmd/worker-claim/main.go diff --git a/deploy/containerlab/scripts/worker-fabric.sh b/deploy/containerlab/scripts/worker-fabric.sh index 90d981e1..bbdffcf1 100755 --- a/deploy/containerlab/scripts/worker-fabric.sh +++ b/deploy/containerlab/scripts/worker-fabric.sh @@ -11,7 +11,9 @@ # gone. Redeploy the lab (task destroy, task deploy) before reusing it. # # Usage: -# worker-fabric.sh start build, copy and start Worker on NODES +# worker-fabric.sh start build, copy and start Worker on NODES, with the +# allowlist file WORKER_ALLOWLIST names, or one +# letting only galactic-router hand it routes # worker-fabric.sh stop stop Worker on NODES # worker-fabric.sh scopes NODE print the node's VPC fence records # worker-fabric.sh table NODE VPC print VPC's VRF table ID on NODE @@ -33,11 +35,15 @@ start() { bin=$(mktemp -d) trap 'rm -rf "${bin}"' RETURN (cd "${REPO_DIR}" && CGO_ENABLED=0 go build -o "${bin}/galactic-worker" ./cmd/galactic-worker) - cat >"${bin}/allowlist.yaml" <<'EOF' + if [ -n "${WORKER_ALLOWLIST:-}" ]; then + cp "${WORKER_ALLOWLIST}" "${bin}/allowlist.yaml" + else + cat >"${bin}/allowlist.yaml" <<'EOF' serviceAccounts: - serviceAccount: galactic-system/galactic-router capabilities: [fabric.routes] EOF + fi for node in ${NODES}; do kind get kubeconfig --name "$(site_of "${node}")" --internal >"${bin}/kubeconfig" docker exec "${node}" mkdir -p "${DIR}" diff --git a/tests/handoffs/cmd/worker-claim/main.go b/tests/handoffs/cmd/worker-claim/main.go new file mode 100644 index 00000000..f7ae5c8e --- /dev/null +++ b/tests/handoffs/cmd/worker-claim/main.go @@ -0,0 +1,154 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +// Command worker-claim requests, observes and releases one Galactic Worker +// claim, for lab checks of the Local and Fabric modules. It is test code: it +// runs inside a lab pod, as a service agent would, with a token bound to that +// pod. +// +// Usage: +// +// worker-claim -node N -vpc V -attachment UID -handoff tap|veth_pair|routed_link|socket \ +// -dest UID[,UID...] [-generation G] [-wait D] [-release] +// +// It prints the claim's last status snapshot as one line of JSON, after the +// status describes the generation and is Programmed, or once -wait passes. +// With -release it releases the claim at -generation and waits until Worker +// reports it released. It exits 0 whatever the status says, and 1 only when +// it cannot reach Worker or Worker refuses the call. +package main + +import ( + "context" + "errors" + "flag" + "fmt" + "os" + "strings" + "time" + + "google.golang.org/protobuf/encoding/protojson" + + workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" + "go.datum.net/galactic/pkg/workerclient" +) + +func main() { + if err := run(); err != nil { + fmt.Fprintln(os.Stderr, "worker-claim:", err) + os.Exit(1) + } +} + +func run() error { + var ( + socket = flag.String("socket", workerv1alpha1.DefaultSocketPath, "Worker's socket") + tokenFile = flag.String("token-file", workerclient.DefaultTokenFile, "the pod's Worker token") + node = flag.String("node", "", "this node") + vpc = flag.String("vpc", "", "the claim's VPC, as its attachment's status records it") + attachment = flag.String("attachment", "", "the claim's attachment UID") + handoff = flag.String("handoff", "tap", "tap, veth_pair, routed_link or socket") + dests = flag.String("dest", "", "comma-separated destination attachment UIDs") + generation = flag.Uint64("generation", 1, "the claim generation") + wait = flag.Duration("wait", 60*time.Second, "how long to wait for the status to settle") + release = flag.Bool("release", false, "release the claim instead of requesting it") + ) + flag.Parse() + h, ok := workerv1alpha1.Handoff_value["HANDOFF_"+strings.ToUpper(*handoff)] + if !ok || *node == "" || *vpc == "" || *attachment == "" { + return errors.New("-node, -vpc, -attachment and a known -handoff are required") + } + ctx, cancel := context.WithTimeout(context.Background(), *wait+30*time.Second) + defer cancel() + c, err := workerclient.Dial(ctx, workerclient.Options{SocketPath: *socket, TokenFile: *tokenFile}) + if err != nil { + return fmt.Errorf("dial Worker: %w", err) + } + defer c.Close() //nolint:errcheck // the claims outlive the session + key := &workerv1alpha1.ClaimKey{Node: *node, Vpc: *vpc, AttachmentUid: *attachment} + obs, err := c.Observe(ctx, key) + if err != nil { + return fmt.Errorf("observe: %w", err) + } + if *release { + if _, err := c.Release(ctx, key, *generation); err != nil { + return fmt.Errorf("release: %w", err) + } + } else { + spec := &workerv1alpha1.ClaimSpec{Handoff: workerv1alpha1.Handoff(h)} + for _, uid := range strings.Split(*dests, ",") { + if uid = strings.TrimSpace(uid); uid != "" { + spec.Destinations = append(spec.Destinations, &workerv1alpha1.Destination{ + Target: &workerv1alpha1.Destination_Attachment{Attachment: &workerv1alpha1.AttachmentRef{Uid: uid}}}) + } + } + if _, err := c.Request(ctx, key, *generation, spec); err != nil { + return fmt.Errorf("request: %w", err) + } + } + last := settle(ctx, obs, *generation, *release, *wait) + b, err := protojson.MarshalOptions{UseProtoNames: true}.Marshal(last) + if err != nil { + return err + } + fmt.Println(string(b)) + return nil +} + +// settle returns the last snapshot once it describes generation and is +// Programmed, or released, or when wait passes. +func settle(ctx context.Context, obs *workerclient.Observer, generation uint64, release bool, + wait time.Duration) *workerv1alpha1.ClaimStatus { + deadline := time.Now().Add(wait) + var last *workerv1alpha1.ClaimStatus + got := make(chan *workerv1alpha1.ClaimStatus) + go func() { + defer close(got) + for { + st, err := obs.Recv() + if err != nil { + return + } + select { + case got <- st: + case <-ctx.Done(): + return + } + } + }() + for { + select { + case st, ok := <-got: + if !ok { + return last + } + last = st + if release && st.GetReleased() { + return last + } + if !release && st.GetObservedGeneration() == generation && programmed(st) { + // One more snapshot settles readiness when it follows soon. + select { + case st2, ok := <-got: + if ok { + last = st2 + } + case <-time.After(3 * time.Second): + } + return last + } + case <-time.After(time.Until(deadline)): + return last + } + } +} + +func programmed(st *workerv1alpha1.ClaimStatus) bool { + for _, c := range st.GetConditions() { + if c.GetType() == workerv1alpha1.ConditionProgrammed { + return c.GetStatus() == workerv1alpha1.ConditionStatus_CONDITION_STATUS_TRUE + } + } + return false +} From 0de62b6271ef39443f1b0f9fef47cd9b41c0950a Mon Sep 17 00:00:00 2001 From: Peter Sprygada Date: Thu, 19 Nov 2026 05:56:17 -0500 Subject: [PATCH 4/5] fix(worker): Harden Local routed links, guards and receivers - Bring a routed link's host end up only after its guard row and filter are in place, and take it down whenever the guard is missing, so a pod never reaches the VPC unguarded. - Mark every new Local link right after creating it and remove the link when a later step fails; treat an unmarked link with a Local name as Local's to replace, so an interrupted creation does not block a claim. - Record a routed link's failure on its own claim and keep programming the rest of the VPC. - Keep local_rx on the receiving devices while any TAP is authorized, so a restarted Worker planning a scope without local.tap first does not detach it. - Admit a link-local source on a routed link only toward a link-local or multicast destination, and the unspecified source only for ICMPv6. - Drop IPv6 fragments behind extension headers, and check the egress MTU on the reply and NAT redirects. - Report claims whose link names collide instead of overwriting one. - Pick a pod's lowest PID when opening its network namespace. --- docs/worker/contract.md | 21 ++- internal/plumbing/ebpf/localprog/load.go | 1 + internal/plumbing/ebpf/localprog/local.c | 69 ++++++++- internal/worker/local/ensure.go | 13 +- internal/worker/local/kernel.go | 60 +++++++- internal/worker/local/model.go | 18 ++- internal/worker/local/model_test.go | 30 ++++ internal/worker/local/podns.go | 16 +- internal/worker/local/read.go | 18 ++- internal/worker/local/review_root_test.go | 169 ++++++++++++++++++++++ internal/worker/local/routed.go | 83 ++++++++--- 11 files changed, 445 insertions(+), 53 deletions(-) create mode 100644 internal/worker/local/review_root_test.go diff --git a/docs/worker/contract.md b/docs/worker/contract.md index b7c9f825..62f25e77 100644 --- a/docs/worker/contract.md +++ b/docs/worker/contract.md @@ -327,7 +327,11 @@ names them `G` with the alias creates a routed link's pod end only in the pod Worker authenticated the claim's owner from: it finds a process of that pod through its cgroup, as the API's peer check does (D21), and refuses a pod on the host's network. A -duplicate `Request` from the owner's new pod moves the link there. +duplicate `Request` from the owner's new pod moves the link there, so a +routed link serves one pod at a time: two pods that hold one claim move it +back and forth, and each pod's link needs its own claim and attachment. The +host end stays down until its guard is attached, and goes down again whenever +the guard is missing. A destination is programmed when the module's rows and filters are in place, confirmed by read-back. It is ready when, in addition: @@ -352,7 +356,13 @@ it carries. Public ingress cannot assert tenant context. Only an XDP program can write skb metadata, so a packet from the wire carries none, and `local_rx` delivers -only to a TAP Local authorized and drops a packet that names any other. Every +only to a TAP Local authorized and drops a packet that names any other. The +programs a receiving device's dispatcher runs are trusted to name the right +one of those TAPs: a slot's holder, such as the gateway, chooses the TAP, and +Worker checks only that a claim authorizes it. `local_rx` drops an IPv6 +fragment, also one behind hop-by-hop, routing or destination options +headers, and each Local redirect drops a packet its egress's MTU does not +cover. Every Local program that delivers decides the receiver's policy on its own path and sets the decided mark itself, and the pair delivers only to the destination addresses a claim names. Every uplink discovery path skips a link Galactic @@ -371,6 +381,13 @@ The client learns the interfaces the module created from the claim's `handoff_interfaces`: the NAT end it attaches its native XDP program to, and the routed link's pod end it configures. +`local_rx` records each flow it delivers in a 65536-entry LRU table, which the +flow's replies use. A sender that opens more flows than that through the +receiving devices evicts older ones, whose replies then go to the kernel +instead of the device they arrived on. `local_rx` stays on the receiving +devices while any TAP is authorized, so a restarted Worker does not take it +away before it has planned every scope. + ## Errors and retry | gRPC code | Reasons | Client action | diff --git a/internal/plumbing/ebpf/localprog/load.go b/internal/plumbing/ebpf/localprog/load.go index 232da08d..e96114ac 100644 --- a/internal/plumbing/ebpf/localprog/load.go +++ b/internal/plumbing/ebpf/localprog/load.go @@ -176,6 +176,7 @@ var StatNames = []string{ "pair_deliver", "guard_pass", "guard_drop", + "link_too_big", } // Stats reads lt_stats by name, summed over CPUs. diff --git a/internal/plumbing/ebpf/localprog/local.c b/internal/plumbing/ebpf/localprog/local.c index 367c6c38..3b380e0e 100644 --- a/internal/plumbing/ebpf/localprog/local.c +++ b/internal/plumbing/ebpf/localprog/local.c @@ -52,7 +52,13 @@ static long (*lt_check_mtu)(void *ctx, __u32 ifindex, __u32 *mtu_len, __s32 len_ #define LT_ETH_P_IPV6 0x86DD #define LT_IPPROTO_TCP 6 #define LT_IPPROTO_UDP 17 +#define LT_IPPROTO_HOPOPTS 0 +#define LT_IPPROTO_ROUTING 43 #define LT_IPPROTO_FRAGMENT 44 +#define LT_IPPROTO_DSTOPTS 60 +// LT_EXT_HDRS is how many extension headers lt_fragment walks before a +// fragment header. +#define LT_EXT_HDRS 4 #define LT_IPPROTO_ICMPV6 58 // BPF_MTU_CHK_SEGS: check each segment of a GSO packet against the MTU. #define LT_MTU_CHK_SEGS 1 @@ -84,6 +90,7 @@ enum lt_stat { LT_STAT_PAIR_DELIVER, LT_STAT_GUARD_PASS, LT_STAT_GUARD_DROP, + LT_STAT_LINK_TOO_BIG, LT_STAT_COUNT = 32, }; @@ -275,6 +282,32 @@ static LT_INLINE void lt_ports(struct __sk_buff *skb, struct usid_ip6hdr *ip6, _ } } +// lt_fragment reports whether the IPv6 packet ip6 heads is a fragment: a +// fragment header first, or after up to LT_EXT_HDRS hop-by-hop, routing or +// destination options headers. A chain longer than that counts as one, so +// it is refused rather than delivered unchecked. +static LT_INLINE int lt_fragment(struct __sk_buff *skb, struct usid_ip6hdr *ip6) +{ + __u8 next = ip6->nexthdr; + __u32 off = sizeof(struct usid_ethhdr) + sizeof(struct usid_ip6hdr); + +#pragma unroll + for (int i = 0; i < LT_EXT_HDRS; i++) { + if (next == LT_IPPROTO_FRAGMENT) + return 1; + if (next != LT_IPPROTO_HOPOPTS && next != LT_IPPROTO_ROUTING && next != LT_IPPROTO_DSTOPTS) + return 0; + __u8 hdr[2]; + + if (bpf_skb_load_bytes(skb, off, hdr, sizeof(hdr))) + return 1; + next = hdr[0]; + off += ((__u32) hdr[1] + 1) * 8; + } + return next == LT_IPPROTO_FRAGMENT || next == LT_IPPROTO_HOPOPTS || next == LT_IPPROTO_ROUTING || + next == LT_IPPROTO_DSTOPTS; +} + // lt_fits reports whether skb fits ifindex's MTU, segment by segment for a // GSO packet. A redirect does not enforce the receiver's MTU itself. static LT_INLINE int lt_fits(struct __sk_buff *skb, __u32 ifindex) @@ -318,10 +351,13 @@ int local_rx(struct __sk_buff *skb) lt_count(LT_STAT_RX_NOT_IPV6); return TC_ACT_SHOT; } - if (ip6->nexthdr == LT_IPPROTO_FRAGMENT) { + if (lt_fragment(skb, ip6)) { lt_count(LT_STAT_RX_FRAGMENT); return TC_ACT_SHOT; } + ip6 = lt_ip6(skb); + if (!ip6) + return TC_ACT_SHOT; struct lt_flow_key fk = {}; struct lt_flow_value fv = {}; @@ -411,6 +447,10 @@ int local_link_rx(struct __sk_buff *skb) if (fv) { __u32 rx = fv->rx_ifindex; + if (!lt_fits(skb, rx)) { + lt_count(LT_STAT_LINK_TOO_BIG); + return TC_ACT_SHOT; + } tp_capture(skb, TP_DIR_EGRESS, ifindex, 0); if (tp_decide(ifindex, TP_DIR_EGRESS, TP_PATH_PUBLIC_SERVICE)) { lt_count(LT_STAT_LINK_REPLY_DENY); @@ -425,6 +465,10 @@ int local_link_rx(struct __sk_buff *skb) __builtin_memcpy(dst, ip6->daddr, 16); if (!pair || !lt_nat_route(table, dst)) return TC_ACT_UNSPEC; + if (!lt_fits(skb, pair)) { + lt_count(LT_STAT_LINK_TOO_BIG); + return TC_ACT_SHOT; + } tp_capture(skb, TP_DIR_EGRESS, ifindex, 0); if (tp_decide(ifindex, TP_DIR_EGRESS, TP_PATH_PUBLIC_NAT)) { @@ -469,10 +513,13 @@ int local_pair_rx(struct __sk_buff *skb) lt_count(LT_STAT_PAIR_NOT_IPV6); return TC_ACT_SHOT; } - if (ip6->nexthdr == LT_IPPROTO_FRAGMENT) { + if (lt_fragment(skb, ip6)) { lt_count(LT_STAT_PAIR_FRAGMENT); return TC_ACT_SHOT; } + ip6 = lt_ip6(skb); + if (!ip6) + return TC_ACT_SHOT; __builtin_memcpy(gk.addr, ip6->daddr, 16); struct lt_guest_value *gv = bpf_map_lookup_elem(<_guest, &gk); @@ -503,10 +550,19 @@ int local_pair_rx(struct __sk_buff *skb) return bpf_redirect_neigh(link, &p, sizeof(p), 0); } +// lt_link_scoped reports whether addr is link-local unicast or multicast: +// an address that never leaves the link the packet is on. +static LT_INLINE int lt_link_scoped(const __u8 *addr) +{ + return addr[0] == 0xff || (addr[0] == 0xfe && (addr[1] & 0xc0) == 0x80); +} + // local_link_guard runs on the host end of a pod-to-host routed link. The link // joins the pod to the tenant VRF, so a source it was not given would let the -// pod speak as any address in the VPC. Link-local and unspecified sources -// carry Neighbor Discovery on the link itself; anything else not IPv6 is +// pod speak as any address in the VPC. A link-local source is admitted only +// toward a link-local or multicast destination, and the unspecified source +// only for ICMPv6 toward one, which is how Neighbor Discovery and MLD use +// them; neither is forwarded into the VPC. Anything else not IPv6 is // dropped. SEC("tc") int local_link_guard(struct __sk_buff *skb) @@ -526,7 +582,10 @@ int local_link_guard(struct __sk_buff *skb) lt_count(LT_STAT_GUARD_DROP); return TC_ACT_SHOT; } - if ((ip6->saddr[0] == 0xfe && (ip6->saddr[1] & 0xc0) == 0x80) || lt_zero16(ip6->saddr)) { + int link_dst = lt_link_scoped(ip6->daddr); + + if (link_dst && ((ip6->saddr[0] == 0xfe && (ip6->saddr[1] & 0xc0) == 0x80) || + (lt_zero16(ip6->saddr) && ip6->nexthdr == LT_IPPROTO_ICMPV6))) { lt_count(LT_STAT_GUARD_PASS); return TC_ACT_UNSPEC; } diff --git a/internal/worker/local/ensure.go b/internal/worker/local/ensure.go index add65a2c..bfa05ee4 100644 --- a/internal/worker/local/ensure.go +++ b/internal/worker/local/ensure.go @@ -127,8 +127,8 @@ func (p *pass) ensurePairs() error { return nil } -// ensureRoutedLinks makes each routed link exist. A link whose pod cannot be -// reached is recorded, not fatal. +// ensureRoutedLinks makes each routed link exist. A link that cannot be made +// is recorded for Read, not fatal. func (p *pass) ensureRoutedLinks() error { if len(p.m.routed) == 0 { return nil @@ -137,14 +137,17 @@ func (p *pass) ensureRoutedLinks() error { if err != nil { return err } + // One link's failure, such as a pod that already holds an interface of + // the pod end's name, is that claim's alone: the rest of the VPC is + // still programmed. for _, name := range sortedKeys(p.m.routed) { err := p.ensureRouted(p.m.routed[name], entries) switch { case err == nil: - case errors.Is(err, ErrPodNotFound) || errors.Is(err, ErrPodHostNetwork): - p.res.errs[name] = err - default: + case errors.Is(err, errDirty): return err + default: + p.res.errs[name] = err } } return nil diff --git a/internal/worker/local/kernel.go b/internal/worker/local/kernel.go index b6f00d3d..ad8d1743 100644 --- a/internal/worker/local/kernel.go +++ b/internal/worker/local/kernel.go @@ -233,12 +233,19 @@ func readHost() (*host, error) { return h, nil } -// localLinks returns the Local links of vpc, by name. +// localLinks returns the Local links of vpc, by name: those marked for one +// of its claims, and unmarked ones named for it, which an interrupted +// creation left. func (h *host) localLinks(vpc string) map[string]netlink.Link { out := map[string]netlink.Link{} + prefix := intf.GenerateInterfaceNameLocal(vpc, "000", intf.LocalRolePairNAT)[:10] for _, l := range h.all { - if v, _, ok := parseAlias(l.Attrs().Alias); ok && v == vpc && intf.IsLocalLinkName(l.Attrs().Name) { - out[l.Attrs().Name] = l + a, name := l.Attrs().Alias, l.Attrs().Name + if !intf.IsLocalLinkName(name) { + continue + } + if v, _, ok := parseAlias(a); (ok && v == vpc) || (a == "" && strings.HasPrefix(name, prefix)) { + out[name] = l } } return out @@ -276,9 +283,11 @@ func (h *host) readPair(p pairWant) (pair, bool) { } // collision returns an error when a link named name belongs to another claim -// than the one alias a names. +// than the one alias a names. A Local link with no alias is what an +// interrupted creation left, and is Local's to replace. func (h *host) collision(name, a string) error { - if l := h.byName[name]; l != nil && l.Attrs().Alias != a { + if l := h.byName[name]; l != nil && l.Attrs().Alias != a && + (l.Attrs().Alias != "" || !intf.IsLocalLinkName(name)) { return fmt.Errorf("local: link %s belongs to %q, not %q", name, l.Attrs().Alias, a) } return nil @@ -297,7 +306,10 @@ func (k *Kernel) ensurePair(h *host, p pairWant, vrfIdx int, dry bool) (pair, er return pair{}, err } } - if err := placeInVRF(got.tenant, vrfIdx, dry); err != nil { + if err := enslave(got.tenant, vrfIdx, dry); err != nil { + return got, err + } + if err := setUp(got.tenant, dry); err != nil { return got, err } if err := fix(dry, got.nat.Attrs().Flags&net.FlagUp == 0, func() error { @@ -323,10 +335,25 @@ func (k *Kernel) createPair(h *host, p pairWant) (pair, error) { } } } + // The kernel takes no alias when it creates a link, so both ends are + // marked after; a failure before then removes the pair, and an unmarked + // pair a crash left in between is Local's to replace (collision). v := &netlink.Veth{LinkAttrs: netlink.LinkAttrs{Name: p.tenant, MTU: k.mtu()}, PeerName: p.nat} if err := netlink.LinkAdd(v); err != nil { return pair{}, fmt.Errorf("local: create pair %s/%s: %w", p.tenant, p.nat, err) } + got, err := markPair(p) + if err != nil { + if l, lerr := netlink.LinkByName(p.tenant); lerr == nil { + _ = netlink.LinkDel(l) + } + return pair{}, err + } + return got, nil +} + +// markPair marks both ends of a new pair and returns them. +func markPair(p pairWant) (pair, error) { var got pair for _, n := range []string{p.tenant, p.nat} { l, err := netlink.LinkByName(n) @@ -336,6 +363,9 @@ func (k *Kernel) createPair(h *host, p pairWant) (pair, error) { if err := netlink.LinkSetAlias(l, alias(p.key)); err != nil { return pair{}, fmt.Errorf("local: mark pair link %s: %w", n, err) } + if l, err = netlink.LinkByName(n); err != nil { + return pair{}, err + } if n == p.tenant { got.tenant = l } else { @@ -579,14 +609,30 @@ func (k *Kernel) receiverDevices(h *host) ([]receiver, error) { // ensureReceivers attaches local_rx to every receiving device when want, and // removes it from every device it is on otherwise or that is no longer one. +// A TAP Local still authorizes keeps local_rx attached whatever want says: +// after a restart, a scope with no local.tap claim can be planned before the +// scopes that have one, and must not take local_rx away from them. func (k *Kernel) ensureReceivers(want, dry bool) error { - if _, _, err := k.open(); err != nil { + objs, _, err := k.open() + if err != nil { return err } h, err := readHost() if err != nil { return err } + if !want { + taps, err := u32Keys(objs.Maps.Tap) + if err != nil { + return err + } + for _, idx := range taps { + if h.byIdx[int(idx)] != nil { + want = true + break + } + } + } rs, err := k.receiverDevices(h) if err != nil { return err diff --git a/internal/worker/local/model.go b/internal/worker/local/model.go index ce026147..e68e79d3 100644 --- a/internal/worker/local/model.go +++ b/internal/worker/local/model.go @@ -26,8 +26,9 @@ const maxGuardAddrs = 4 const base62 = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz" // linkKey is the 3-character key of the links Local creates for the claim on -// attachmentUID, derived from its UID. Two claims in one VPC whose keys -// collide are told apart by the links' alias. +// attachmentUID, derived from its UID. When two claims of one VPC derive the +// same key, the first in claim key order gets the links and the other +// reports why it has none (model.collisions). func linkKey(attachmentUID string) string { sum := sha256.Sum256([]byte(attachmentUID)) n := binary.BigEndian.Uint32(sum[:4]) % (62 * 62 * 62) @@ -102,6 +103,9 @@ type model struct { // tap is set when a claim of the scope uses local.tap, which needs // local_rx on the node's public receiving devices. tap bool + // collisions are the claims whose links would take another claim's + // names, with that claim. + collisions map[module.ClaimKey]module.ClaimKey } // Empty reports whether the scope wants no Local state. @@ -124,7 +128,7 @@ func ipv6(addrs []netip.Addr) []netip.Addr { // whose attachment has no host interface yet wants nothing; Read reports it. func desire(vpc string, claims []module.Claim) *model { m := &model{vpc: vpc, pairs: map[string]pairWant{}, routed: map[string]routedWant{}, - tenants: map[string]*tenantWant{}} + tenants: map[string]*tenantWant{}, collisions: map[module.ClaimKey]module.ClaimKey{}} sorted := slices.Clone(claims) sort.Slice(sorted, func(i, j int) bool { return sorted[i].Key.String() < sorted[j].Key.String() }) tenant := func(name string) *tenantWant { @@ -152,6 +156,10 @@ func desire(vpc string, claims []module.Claim) *model { case workerv1alpha1.Handoff_HANDOFF_VETH_PAIR: p := pairWant{key: c.Key, nat: linkName(vpc, c.Key.AttachmentUID, intf.LocalRolePairNAT), tenant: linkName(vpc, c.Key.AttachmentUID, intf.LocalRolePairTenant)} + if other, ok := m.pairs[p.tenant]; ok { + m.collisions[c.Key] = other.key + continue + } m.pairs[p.tenant] = p for _, d := range c.Destinations { if d.HostInterface == "" { @@ -172,6 +180,10 @@ func desire(vpc string, claims []module.Claim) *model { } r := routedWant{key: c.Key, host: linkName(vpc, c.Key.AttachmentUID, intf.LocalRoleRoutedHost), pod: linkName(vpc, c.Key.AttachmentUID, intf.LocalRoleRoutedPod), podUID: c.OwnerPod, addrs: addrs} + if other, ok := m.routed[r.host]; ok { + m.collisions[c.Key] = other.key + continue + } m.routed[r.host] = r } } diff --git a/internal/worker/local/model_test.go b/internal/worker/local/model_test.go index 787ad0d2..fbd11e4d 100644 --- a/internal/worker/local/model_test.go +++ b/internal/worker/local/model_test.go @@ -6,6 +6,7 @@ package local import ( "net/netip" + "strconv" "testing" workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" @@ -82,3 +83,32 @@ func TestDesire(t *testing.T) { t.Error("no claims want state") } } + +// TestDesireReportsLinkKeyCollisions checks that when two claims of a VPC +// derive the same link names, the first in claim key order gets the links +// and the other is reported, rather than one silently taking the other's. +func TestDesireReportsLinkKeyCollisions(t *testing.T) { + seen := map[string]string{} + var a, b string + for i := 0; a == ""; i++ { + uid := "uid-" + strconv.Itoa(i) + k := linkKey(uid) + if prev, ok := seen[k]; ok { + a, b = prev, uid + } + seen[k] = uid + } + if a > b { + a, b = b, a + } + for _, h := range []workerv1alpha1.Handoff{workerv1alpha1.Handoff_HANDOFF_VETH_PAIR, + workerv1alpha1.Handoff_HANDOFF_ROUTED_LINK} { + ka := module.ClaimKey{VPC: "v", AttachmentUID: a} + kb := module.ClaimKey{VPC: "v", AttachmentUID: b} + m := desire("v", []module.Claim{{Key: kb, Handoff: h}, {Key: ka, Handoff: h}}) + if len(m.pairs)+len(m.routed) != 1 || m.collisions[kb] != ka { + t.Fatalf("%s: links %d, collisions %v; want %s's links and %s reported", h, + len(m.pairs)+len(m.routed), m.collisions, a, b) + } + } +} diff --git a/internal/worker/local/podns.go b/internal/worker/local/podns.go index 1bdbcd39..603abbb2 100644 --- a/internal/worker/local/podns.go +++ b/internal/worker/local/podns.go @@ -9,6 +9,7 @@ import ( "fmt" "os" "path/filepath" + "slices" "strconv" "sync" @@ -68,12 +69,17 @@ func (p *ProcPods) Open(podUID string) (netns.NsHandle, error) { if err != nil { return netns.None(), fmt.Errorf("local: read %s: %w", p.ProcRoot, err) } + // The pod's lowest PID is its sandbox's first process, whose namespace + // is the pod's; a later process may have unshared its own. + var pids []int32 for _, e := range entries { - n, err := strconv.ParseInt(e.Name(), 10, 32) - if err != nil || n <= 0 { - continue + if n, err := strconv.ParseInt(e.Name(), 10, 32); err == nil && n > 0 { + pids = append(pids, int32(n)) } - h, err := p.openPID(podUID, int32(n)) + } + slices.Sort(pids) + for _, n := range pids { + h, err := p.openPID(podUID, n) if errors.Is(err, errOtherPod) { continue } @@ -84,7 +90,7 @@ func (p *ProcPods) Open(podUID string) (netns.NsHandle, error) { if p.last == nil { p.last = map[string]int32{} } - p.last[podUID] = int32(n) + p.last[podUID] = n p.mu.Unlock() return h, nil } diff --git a/internal/worker/local/read.go b/internal/worker/local/read.go index cb894267..a1a453fc 100644 --- a/internal/worker/local/read.go +++ b/internal/worker/local/read.go @@ -5,6 +5,7 @@ package local import ( + "errors" "fmt" "net/netip" @@ -115,7 +116,10 @@ func (k *Kernel) read(vpc, node string, claims []module.Claim, m *model, errs ma desiredKeys[c.Key] = true } for _, l := range h.localLinks(vpc) { - v, uid, _ := parseAlias(l.Attrs().Alias) + v, uid, ok := parseAlias(l.Attrs().Alias) + if !ok { + continue + } key := module.ClaimKey{Node: node, VPC: v, AttachmentUID: uid} if !desiredKeys[key] { out.state[key] = map[string]module.DestinationState{leftoverID: {}} @@ -157,6 +161,12 @@ func (k *Kernel) read(vpc, node string, claims []module.Claim, m *model, errs ma for _, d := range c.Destinations { ck := newCheck(c.Generation) + if other, ok := m.collisions[c.Key]; ok { + ck.unprogrammed(workerv1alpha1.ReasonProgrammingFailed, + "the claim's handoff links would take the names of claim "+other.String()+"'s") + states[d.ID] = ck.done() + continue + } l := k.destinationCheck(ck, h, vrfIdx, c, d, objs, &out) handoffCheck(ck, l) states[d.ID] = ck.done() @@ -385,7 +395,11 @@ func (k *Kernel) routedCheck(h *host, m *model, c module.Claim, vrfIdx int, objs return } if err := errs[r.host]; err != nil { - ck.unprogrammed(workerv1alpha1.ReasonHandoffInterfaceMissing, err.Error()) + reason := workerv1alpha1.ReasonProgrammingFailed + if errors.Is(err, ErrPodNotFound) || errors.Is(err, ErrPodHostNetwork) { + reason = workerv1alpha1.ReasonHandoffInterfaceMissing + } + ck.unprogrammed(reason, err.Error()) return } if len(r.addrs) == 0 { diff --git a/internal/worker/local/review_root_test.go b/internal/worker/local/review_root_test.go new file mode 100644 index 00000000..ab1a5899 --- /dev/null +++ b/internal/worker/local/review_root_test.go @@ -0,0 +1,169 @@ +// Copyright 2026 Datum Cloud, Inc. +// +// SPDX-License-Identifier: AGPL-3.0-or-later + +package local + +import ( + "context" + "net" + "net/netip" + "testing" + "time" + + "github.com/containernetworking/plugins/pkg/ns" + "github.com/vishvananda/netlink" + + workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" + "go.datum.net/galactic/internal/plumbing/ebpf/attach" + "go.datum.net/galactic/internal/plumbing/ebpf/xdpmode" + "go.datum.net/galactic/internal/plumbing/intf" + "go.datum.net/galactic/internal/worker/module" +) + +// TestRestartKeepsReceiveHookRoot checks that a restarted Worker, which +// plans a scope with no local.tap claim before the scopes that have one, +// leaves local_rx on the receiving device while Local still authorizes a TAP. +func TestRestartKeepsReceiveHookRoot(t *testing.T) { + r := readyRig(t, "restart") + k2 := &Kernel{PinDir: r.kernel.PinDir, LocalPinDir: r.kernel.LocalPinDir, DispatchDir: r.kernel.DispatchDir, + Pods: r.pods} + t.Cleanup(func() { _ = k2.Close() }) + m2, err := New(Config{Kernel: k2, Node: testNode}) + if err != nil { + t.Fatal(err) + } + r.in(r.node, func() error { + scope := module.Scope{VPC: "0000099"} + ch, err := m2.Plan(context.Background(), scope, nil) + if err != nil { + return err + } + if !ch.Empty() { + if err := m2.Apply(context.Background(), scope, ch); err != nil { + return err + } + } + l, err := netlink.LinkByName(r.rx) + if err != nil { + return err + } + name, _, ok, err := attach.LocalFilter(l.Attrs().Index) + if err != nil || !ok || name != filterRx { + t.Fatalf("local_rx on %s after a restart: %q %t %v", r.rx, name, ok, err) + } + return nil + }) + sock := r.clientSocket(40000) + sock.send(t, r.vpcs[0].vip, 7, "after-restart") + r.vpcs[0].guest.expect(t, "after-restart") +} + +// TestRoutedLinkFaultsRoot checks a routed link's faults: one pod that +// already holds an interface of the pod end's name fails only its own claim, +// a guard taken off is put back while the link is down, and a link-local +// source toward a VPC address is dropped. +func TestRoutedLinkFaultsRoot(t *testing.T) { + r := newRig(t, "routedfault", xdpmode.Native) + a := r.vpcs[0] + good, err := ns.TempNetNS() + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = good.Close() }) + bad, err := ns.TempNetNS() + if err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = bad.Close() }) + r.pods.add("pod-good", good) + r.pods.add("pod-bad", bad) + dest := module.Destination{ID: "attachment/" + a.attUID, Mode: workerv1alpha1.Mode_MODE_LOCAL, VPC: a.vpc, + Node: testNode, Addresses: []netip.Addr{guestAddr}, HostInterface: a.tap} + claim := func(uid, pod string, addr netip.Addr) module.Claim { + return module.Claim{Key: module.ClaimKey{Node: testNode, VPC: a.vpc, AttachmentUID: uid}, + Generation: 1, Handoff: workerv1alpha1.Handoff_HANDOFF_ROUTED_LINK, OwnerPod: pod, + Addresses: []netip.Addr{addr}, Destinations: []module.Destination{dest}} + } + claims := []module.Claim{claim("envoy-good", "pod-good", podAddr), + claim("envoy-bad", "pod-bad", netip.MustParseAddr("fd20:80:ff04::51"))} + badEnd := linkName(a.vpc, "envoy-bad", intf.LocalRoleRoutedPod) + if err := bad.Do(func(ns.NetNS) error { + return netlink.LinkAdd(&netlink.Dummy{LinkAttrs: netlink.LinkAttrs{Name: badEnd}}) + }); err != nil { + t.Fatal(err) + } + st := r.reconcile(a.vpc, claims) + wantReady(t, st, claims[:1]) + wantState(t, st, claims[1], false, false, false, workerv1alpha1.ReasonProgrammingFailed) + host := linkName(a.vpc, "envoy-good", intf.LocalRoleRoutedHost) + + // The guard goes: the link is down until it is back. + r.in(r.node, func() error { return attach.DetachLocal(host) }) + wantState(t, r.read(a.vpc), claims[0], true, false, false, workerv1alpha1.ReasonHandoffHookMissing) + wantReady(t, r.reconcile(a.vpc, claims), claims[:1]) + + // A link-local source reaches only the link. + var hostLL netip.Addr + r.in(r.node, func() error { + l, err := netlink.LinkByName(host) + if err != nil { + return err + } + addrs, err := netlink.AddrList(l, netlink.FAMILY_V6) + if err != nil { + return err + } + for _, ad := range addrs { + if v, ok := netip.AddrFromSlice(ad.IP); ok && v.IsLinkLocalUnicast() { + hostLL = v + } + } + return nil + }) + podEnd := linkName(a.vpc, "envoy-good", intf.LocalRoleRoutedPod) + var conn *net.UDPConn + if err := good.Do(func(ns.NetNS) error { + l, err := netlink.LinkByName(podEnd) + if err != nil { + return err + } + if err := netlink.RouteAdd(&netlink.Route{LinkIndex: l.Attrs().Index, + Dst: ipnet(netip.PrefixFrom(guestAddr, 128)), Gw: net.IP(hostLL.AsSlice())}); err != nil { + return err + } + addrs, err := netlink.AddrList(l, netlink.FAMILY_V6) + if err != nil { + return err + } + for _, ad := range addrs { + if v, ok := netip.AddrFromSlice(ad.IP); ok && v.IsLinkLocalUnicast() { + // The address is tentative until the pod's duplicate + // address detection ends. + for range 50 { + if conn, err = net.ListenUDP("udp6", &net.UDPAddr{IP: ad.IP, Zone: podEnd}); err == nil { + return nil + } + time.Sleep(100 * time.Millisecond) + } + return err + } + } + return nil + }); err != nil { + t.Fatal(err) + } + if conn == nil { + t.Skip("the pod end has no link-local address to send from") + } + t.Cleanup(func() { _ = conn.Close() }) + before := r.stats() + if _, err := conn.WriteToUDP([]byte("link-local-source"), + &net.UDPAddr{IP: net.IP(guestAddr.AsSlice()), Port: 8080}); err != nil { + t.Skipf("the pod's kernel does not send a link-local source off the link: %v", err) + } + a.guest.absent(t, "link-local-source") + if after := r.stats(); after["guard_drop"] <= before["guard_drop"] { + t.Fatalf("the guard passed a link-local source toward %s: before %v after %v", guestAddr, before, after) + } +} diff --git a/internal/worker/local/routed.go b/internal/worker/local/routed.go index 03f30c42..8e7f4561 100644 --- a/internal/worker/local/routed.go +++ b/internal/worker/local/routed.go @@ -36,11 +36,10 @@ func (p *pass) ensureRouted(r routedWant, entries map[netip.Prefix]egressroutema return err } } + // The host end comes up only once its guard is in place: up without + // it, the pod could send any source into the VPC. hl := got.host - if err := placeInVRF(hl, p.vrfIdx, p.dry); err != nil { - return err - } - if err := p.ensureRoutes(r, hl.Attrs().Index, entries); err != nil { + if err := enslave(hl, p.vrfIdx, p.dry); err != nil { return err } gv := localprog.LocalLtGuardValue{Count: uint32(len(r.addrs))} @@ -50,7 +49,25 @@ func (p *pass) ensureRouted(r routedWant, entries map[netip.Prefix]egressroutema if err := putRow(p.objs.Maps.Guard, uint32(hl.Attrs().Index), gv, p.dry, "guard of "+r.host); err != nil { return err } - return p.k.ensureFilter(hl, filterLinkGuard, p.dry) + guarded, err := p.k.filterCurrent(hl.Attrs().Index, filterLinkGuard) + if err != nil { + return err + } + if !guarded && !p.dry && hl.Attrs().Flags&net.FlagUp != 0 { + if err := netlink.LinkSetDown(hl); err != nil { + return fmt.Errorf("local: set unguarded %s down: %w", r.host, err) + } + if hl, err = netlink.LinkByName(r.host); err != nil { + return err + } + } + if err := p.k.ensureFilter(hl, filterLinkGuard, p.dry); err != nil { + return err + } + if err := setUp(hl, p.dry); err != nil { + return err + } + return p.ensureRoutes(r, hl.Attrs().Index, entries) } // createRouted creates r's link, its host end in the calling namespace and @@ -65,30 +82,47 @@ func (k *Kernel) createRouted(h *host, r routedWant, podNS netns.NsHandle) (rout return routedLink{}, fmt.Errorf("local: delete routed link %s: %w", r.host, err) } } + // The kernel takes no alias when it creates a link, so the host end is + // marked after; it comes up only once its guard is attached. A failure + // before the pod end is in place removes the link, and an unmarked link + // a crash left in between is Local's to replace (collision). v := &netlink.Veth{LinkAttrs: netlink.LinkAttrs{Name: r.host, MTU: k.mtu()}, PeerName: r.pod} if err := netlink.LinkAdd(v); err != nil { return routedLink{}, fmt.Errorf("local: create routed link %s: %w", r.host, err) } - pl, err := netlink.LinkByName(r.pod) + got, err := movePodEnd(r, podNS) if err != nil { - return routedLink{}, fmt.Errorf("local: look up new pod end %s: %w", r.pod, err) - } - if err := netlink.LinkSetNsFd(pl, int(podNS)); err != nil { - _ = netlink.LinkDel(pl) - return routedLink{}, fmt.Errorf("local: move %s into the pod: %w", r.pod, err) + if l, lerr := netlink.LinkByName(r.host); lerr == nil { + _ = netlink.LinkDel(l) + } + return routedLink{}, err } - l, err := netlink.LinkByName(r.host) + return got, nil +} + +// movePodEnd moves a new routed link's pod end into podNS, marks it and sets +// it up there, and returns the link. +func movePodEnd(r routedWant, podNS netns.NsHandle) (routedLink, error) { + hl, err := netlink.LinkByName(r.host) if err != nil { return routedLink{}, fmt.Errorf("local: look up new routed link %s: %w", r.host, err) } - if err := netlink.LinkSetAlias(l, alias(r.key)); err != nil { + if err := netlink.LinkSetAlias(hl, alias(r.key)); err != nil { return routedLink{}, fmt.Errorf("local: mark routed link %s: %w", r.host, err) } + pl, err := netlink.LinkByName(r.pod) + if err != nil { + return routedLink{}, fmt.Errorf("local: look up new pod end %s: %w", r.pod, err) + } + if err := netlink.LinkSetNsFd(pl, int(podNS)); err != nil { + return routedLink{}, fmt.Errorf("local: move %s into the pod: %w", r.pod, err) + } if err := setUpInPod(podNS, r.pod, alias(r.key)); err != nil { return routedLink{}, err } - if l, err = netlink.LinkByName(r.host); err != nil { - return routedLink{}, err + l, err := netlink.LinkByName(r.host) + if err != nil { + return routedLink{}, fmt.Errorf("local: look up new routed link %s: %w", r.host, err) } peer, err := netlink.VethPeerIndex(l.(*netlink.Veth)) if err != nil { @@ -97,20 +131,21 @@ func (k *Kernel) createRouted(h *host, r routedWant, podNS netns.NsHandle) (rout return routedLink{host: l, podIndex: peer}, nil } -// placeInVRF enslaves l to vrfIdx and sets it up. -func placeInVRF(l netlink.Link, vrfIdx int, dry bool) error { - name := l.Attrs().Name - if err := fix(dry, l.Attrs().MasterIndex != vrfIdx, func() error { +// enslave enslaves l to vrfIdx. +func enslave(l netlink.Link, vrfIdx int, dry bool) error { + return fix(dry, l.Attrs().MasterIndex != vrfIdx, func() error { if err := netlink.LinkSetMasterByIndex(l, vrfIdx); err != nil { - return fmt.Errorf("local: enslave %s: %w", name, err) + return fmt.Errorf("local: enslave %s: %w", l.Attrs().Name, err) } return nil - }); err != nil { - return err - } + }) +} + +// setUp sets l up. +func setUp(l netlink.Link, dry bool) error { return fix(dry, l.Attrs().Flags&net.FlagUp == 0, func() error { if err := netlink.LinkSetUp(l); err != nil { - return fmt.Errorf("local: set %s up: %w", name, err) + return fmt.Errorf("local: set %s up: %w", l.Attrs().Name, err) } return nil }) From 6c9fb636d7c6ab2e1ac42a203d98d07db6fa0eba Mon Sep 17 00:00:00 2001 From: Peter Sprygada Date: Thu, 19 Nov 2026 06:45:41 -0500 Subject: [PATCH 5/5] feat(worker): Serve a routed link to one pod at a time A routed_link or socket claim's link reaches one pod. A duplicate Request from another pod of the owner used to move the link, so two pods holding one claim would move it back and forth on every call. Worker now refuses a call on such a claim from another pod with FAILED_PRECONDITION and reason ClaimHeldByAnotherPod while the pod the link serves still runs, and changes nothing. Once that pod is gone, the call moves the link to the calling pod, as after a pod replacement. Claims whose handoff serves no pod never record a move. Worker learns whether a pod runs from the host's /proc, by the same cgroup check the API's peer check uses. --- api/galactic/worker/v1alpha1/contract.go | 16 +++-- cmd/galactic-worker/root.go | 8 ++- docs/worker/contract.md | 31 ++++---- internal/worker/claims.go | 64 ++++++++++++++--- internal/worker/handoff_test.go | 91 +++++++++++++++++++----- internal/worker/harness_test.go | 6 +- internal/worker/local/podns.go | 22 ++++++ internal/worker/local/podns_test.go | 8 +++ internal/worker/worker.go | 5 ++ 9 files changed, 200 insertions(+), 51 deletions(-) diff --git a/api/galactic/worker/v1alpha1/contract.go b/api/galactic/worker/v1alpha1/contract.go index 523e17e7..d83ed451 100644 --- a/api/galactic/worker/v1alpha1/contract.go +++ b/api/galactic/worker/v1alpha1/contract.go @@ -92,12 +92,16 @@ const ( ReasonClaimExists = "ClaimExists" ReasonClaimNotFound = "ClaimNotFound" ReasonGenerationConflict = "GenerationConflict" - ReasonNoSession = "NoSession" - ReasonStaleGeneration = "StaleGeneration" - ReasonResyncing = "Resyncing" - ReasonShuttingDown = "ShuttingDown" - ReasonClaimLimit = "ClaimLimit" - ReasonTableRangeExhausted = "TableRangeExhausted" + // ReasonClaimHeldByAnotherPod refuses a call on a routed_link or socket + // claim from a pod other than the one the claim's link serves, while + // that pod still runs. + ReasonClaimHeldByAnotherPod = "ClaimHeldByAnotherPod" + ReasonNoSession = "NoSession" + ReasonStaleGeneration = "StaleGeneration" + ReasonResyncing = "Resyncing" + ReasonShuttingDown = "ShuttingDown" + ReasonClaimLimit = "ClaimLimit" + ReasonTableRangeExhausted = "TableRangeExhausted" ) // Status reasons, carried in conditions, destination status and diff --git a/cmd/galactic-worker/root.go b/cmd/galactic-worker/root.go index 1380f9e9..d9d5d4f3 100644 --- a/cmd/galactic-worker/root.go +++ b/cmd/galactic-worker/root.go @@ -184,8 +184,9 @@ func run(o *options) error { return err } fabric.InitMetrics() + pods := &local.ProcPods{ProcRoot: o.procRoot, Pods: auth.CgroupPodResolver{ProcRoot: o.procRoot}} localKernel := &local.Kernel{PinDir: o.pinDir, LocalPinDir: o.localPinDir, DispatchDir: o.dispatchDir, - Pods: &local.ProcPods{ProcRoot: o.procRoot, Pods: auth.CgroupPodResolver{ProcRoot: o.procRoot}}} + Pods: pods} defer func() { _ = localKernel.Close() }() loc, err := local.New(local.Config{Kernel: localKernel, Node: o.nodeName, Log: slog.Default()}) if err != nil { @@ -213,8 +214,9 @@ func run(o *options) error { Allowlist: allow, Node: o.nodeName, }, - Routes: tenantRoutes, - Log: slog.Default(), + Routes: tenantRoutes, + Log: slog.Default(), + PodAlive: pods.Alive, }) if err != nil { return err diff --git a/docs/worker/contract.md b/docs/worker/contract.md index 62f25e77..dad50eee 100644 --- a/docs/worker/contract.md +++ b/docs/worker/contract.md @@ -327,11 +327,12 @@ names them `G` with the alias creates a routed link's pod end only in the pod Worker authenticated the claim's owner from: it finds a process of that pod through its cgroup, as the API's peer check does (D21), and refuses a pod on the host's network. A -duplicate `Request` from the owner's new pod moves the link there, so a -routed link serves one pod at a time: two pods that hold one claim move it -back and forth, and each pod's link needs its own claim and attachment. The -host end stays down until its guard is attached, and goes down again whenever -the guard is missing. +routed link serves one pod, so each pod's link needs its own claim and +attachment. A call on the claim from another pod of its owner is refused +with `FAILED_PRECONDITION`/`ClaimHeldByAnotherPod` while the pod the link +serves runs; once that pod is gone, the call moves the link to the calling +pod, as after a pod replacement. The host end stays down until its guard is +attached, and goes down again whenever the guard is missing. A destination is programmed when the module's rows and filters are in place, confirmed by read-back. It is ready when, in addition: @@ -390,16 +391,16 @@ away before it has planned every scope. ## Errors and retry -| gRPC code | Reasons | Client action | -| --------------------- | ------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | -| `INVALID_ARGUMENT` | `MalformedSpec`, `WrongNode` | Fix the request. Do not retry. | -| `UNAUTHENTICATED` | `NoIdentity`, `IdentityExpired` | Refresh the credential, then retry. | -| `PERMISSION_DENIED` | `VPCNotAuthorized`, `AttachmentClaimedByAnotherCaller`, `NotOwner`, `CapabilityNotAllowed` | Do not retry until authority changes. | -| `FAILED_PRECONDITION` | `UnsupportedVersion`, `ClaimExists`, `ClaimNotFound`, `GenerationConflict` | Re-read with `Observe`, then use the right operation. | -| `FAILED_PRECONDITION` | `NoSession` | Call `GetCapabilities` for a new session, then retry. | -| `ABORTED` | `StaleGeneration` | Re-read with `Observe`; retry only with a newer generation. | -| `UNAVAILABLE` | `Resyncing`, `ShuttingDown` | Retry with backoff. | -| `RESOURCE_EXHAUSTED` | `ClaimLimit`, `TableRangeExhausted` | Retry with backoff; report if it persists. | +| gRPC code | Reasons | Client action | +| --------------------- | --------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | +| `INVALID_ARGUMENT` | `MalformedSpec`, `WrongNode` | Fix the request. Do not retry. | +| `UNAUTHENTICATED` | `NoIdentity`, `IdentityExpired` | Refresh the credential, then retry. | +| `PERMISSION_DENIED` | `VPCNotAuthorized`, `AttachmentClaimedByAnotherCaller`, `NotOwner`, `CapabilityNotAllowed` | Do not retry until authority changes. | +| `FAILED_PRECONDITION` | `UnsupportedVersion`, `ClaimExists`, `ClaimNotFound`, `GenerationConflict`, `ClaimHeldByAnotherPod` | Re-read with `Observe`, then use the right operation. | +| `FAILED_PRECONDITION` | `NoSession` | Call `GetCapabilities` for a new session, then retry. | +| `ABORTED` | `StaleGeneration` | Re-read with `Observe`; retry only with a newer generation. | +| `UNAVAILABLE` | `Resyncing`, `ShuttingDown` | Retry with backoff. | +| `RESOURCE_EXHAUSTED` | `ClaimLimit`, `TableRangeExhausted` | Retry with backoff; report if it persists. | `Update` of a claim that does not exist, or is being withdrawn, gets `ClaimNotFound`. diff --git a/internal/worker/claims.go b/internal/worker/claims.go index bf7f4e41..5670b5a5 100644 --- a/internal/worker/claims.go +++ b/internal/worker/claims.go @@ -247,20 +247,13 @@ func (w *Worker) put(ctx context.Context, caller auth.Caller, key *workerv1alpha w.mu.Lock() c := w.claims[k] noop, err := decide(c, caller.ServiceAccount, gen, hash, update) + heldBy := heldPod(c, caller) if err == nil && noop { st := proto.Clone(c.status).(*workerv1alpha1.ClaimStatus) - moved := caller.PodUID != "" && c.rec.PodUID != caller.PodUID rec := c.rec w.mu.Unlock() - if moved { - // The owner calls from a new pod, as after its pod was - // replaced. Nothing else changes, but a routed link follows - // the pod. - if err := w.repod(k, rec, caller.PodUID); err != nil { - w.log.Error("record the claim's new pod", "error", err) - return nil, refusal.New(codes.Unavailable, workerv1alpha1.ReasonResyncing, - "cannot record the claim durably", nil) - } + if err := w.followPod(k, rec, caller, heldBy); err != nil { + return nil, err } return st, nil } @@ -275,6 +268,9 @@ func (w *Worker) put(ctx context.Context, caller auth.Caller, key *workerv1alpha fmt.Sprintf("a caller may hold at most %d claims", w.cfg.ClaimLimit), nil) } w.mu.Unlock() + if err == nil && heldBy != "" { + err = w.heldByAnotherPod(heldBy) + } if err != nil { return nil, w.refuse(err) } @@ -322,6 +318,54 @@ func (w *Worker) put(ctx context.Context, caller auth.Caller, key *workerv1alpha return st, nil } +// heldPod returns the pod claim c's link serves when caller calls from +// another pod of its owner, and "" otherwise. A routed link serves one pod: a +// call from another pod moves the claim only once the pod it serves is gone. +func heldPod(c *claim, caller auth.Caller) string { + if c == nil || c.rec.Releasing || !podBound(c.spec) || caller.PodUID == "" || c.rec.PodUID == "" || + c.rec.PodUID == caller.PodUID { + return "" + } + return c.rec.PodUID +} + +// followPod handles a duplicate Request from another pod of the owner of the +// claim at k: refused while heldBy, the pod the claim serves, runs, and moving +// the claim to the caller's pod once it is gone. With heldBy empty it does +// nothing. +func (w *Worker) followPod(k module.ClaimKey, rec store.Record, caller auth.Caller, heldBy string) error { + if heldBy == "" { + return nil + } + if err := w.heldByAnotherPod(heldBy); err != nil { + return w.refuse(err) + } + // The owner calls from a new pod, as after its pod was replaced. + // Nothing else changes, but the routed link follows the pod. + if err := w.repod(k, rec, caller.PodUID); err != nil { + w.log.Error("record the claim's new pod", "error", err) + return refusal.New(codes.Unavailable, workerv1alpha1.ReasonResyncing, "cannot record the claim durably", nil) + } + return nil +} + +// podBound reports whether a claim's handoff serves one pod: a routed link, +// which the socket handoff also uses. +func podBound(spec *workerv1alpha1.ClaimSpec) bool { + h := spec.GetHandoff() + return h == workerv1alpha1.Handoff_HANDOFF_ROUTED_LINK || h == workerv1alpha1.Handoff_HANDOFF_SOCKET +} + +// heldByAnotherPod refuses a call from another pod while the claim's pod, +// podUID, still runs. +func (w *Worker) heldByAnotherPod(podUID string) error { + if w.d.PodAlive == nil || !w.d.PodAlive(podUID) { + return nil + } + return refusal.New(codes.FailedPrecondition, workerv1alpha1.ReasonClaimHeldByAnotherPod, + "the claim's link serves another pod of its owner, which still runs", nil) +} + // repod records podUID as the pod the owner of the claim at k calls from, // when the claim is still rec, and requeues its scope. The caller holds k's // key lock. diff --git a/internal/worker/handoff_test.go b/internal/worker/handoff_test.go index f6f71200..2b8acecf 100644 --- a/internal/worker/handoff_test.go +++ b/internal/worker/handoff_test.go @@ -10,6 +10,7 @@ import ( "sync" "testing" + "google.golang.org/grpc/codes" "google.golang.org/grpc/metadata" workerv1alpha1 "go.datum.net/galactic/api/galactic/worker/v1alpha1" @@ -17,6 +18,9 @@ import ( "go.datum.net/galactic/internal/worker/module/fake" ) +// podOne is the pod a test's owner first calls from. +const podOne = "pod-1" + // handoffModule is a Local module that records the pod each claim's owner // calls from and reports one handoff interface per claim, as the Local // module reports a veth pair's NAT end. @@ -54,8 +58,8 @@ func (m *handoffModule) pod(k module.ClaimKey) string { } // TestHandoffInterfacesAndOwnerPod checks that a module's handoff -// interfaces reach the claim's status, and that a duplicate Request from the -// owner's new pod records that pod, durably, and changes nothing else. +// interfaces reach the claim's status, and that a claim whose handoff serves +// no pod records only the pod it was requested from. func TestHandoffInterfacesAndOwnerPod(t *testing.T) { e := newEnv(t) hm := &handoffModule{pods: map[module.ClaimKey]string{}} @@ -70,36 +74,91 @@ func TestHandoffInterfacesAndOwnerPod(t *testing.T) { _, err := e.api.Request(ctx, &workerv1alpha1.RequestRequest{Key: k, Generation: 1, Spec: veth("guest-a1")}) return err } - e.mustOK(fromPod("pod-1")) + e.mustOK(fromPod(podOne)) st := e.waitReady(mkey(vpcA, "svc-a"), 1) if got := st.GetHandoffInterfaces(); len(got) != 1 || got[0].GetRole() != workerv1alpha1.HandoffRoleNAT || got[0].GetName() != "Gnat" || got[0].GetIfindex() != 7 { t.Fatalf("handoff interfaces = %v, want the NAT end", got) } - if got := hm.pod(mkey(vpcA, "svc-a")); got != "pod-1" { + if got := hm.pod(mkey(vpcA, "svc-a")); got != podOne { t.Fatalf("the module planned the claim for pod %q, want pod-1", got) } + // A veth pair serves no pod: a call from another pod of the owner + // changes nothing. + e.idle() before := e.persisted() e.mustOK(fromPod("pod-2")) - e.eventually("the claim follows the owner's new pod", func() bool { return hm.pod(mkey(vpcA, "svc-a")) == "pod-2" }) - after := e.persisted() - recorded := false - for name, b := range after { - if strings.HasPrefix(name, "claims/") && strings.Contains(b, `"podUID":"pod-2"`) { - recorded = true + e.idle() + for name, b := range e.persisted() { + if before[name] != b { + t.Fatalf("a duplicate Request from another pod rewrote %s", name) } } - if !recorded { - t.Fatalf("the new pod was not recorded durably: before %v after %v", before, after) + if got := hm.pod(mkey(vpcA, "svc-a")); got != podOne { + t.Fatalf("the module planned the claim for pod %q, want pod-1", got) + } +} + +// TestRoutedLinkServesOnePod checks that a routed link's claim serves one +// pod: while that pod runs, a call from another pod of the owner is refused +// and changes nothing; once it is gone, the call moves the claim. A claim +// whose handoff serves no pod never records a move. +func TestRoutedLinkServesOnePod(t *testing.T) { + e := newEnv(t) + hm := &handoffModule{pods: map[module.ClaimKey]string{}} + e.modules = func(h *fake.Host) []module.Module { + hm.Module = fake.New("local", workerv1alpha1.Mode_MODE_LOCAL, h) + return []module.Module{hm, fake.New("fabric", workerv1alpha1.Mode_MODE_FABRIC, h)} + } + var mu sync.Mutex + alive := map[string]bool{podOne: true} + e.podAlive = func(uid string) bool { + mu.Lock() + defer mu.Unlock() + return alive[uid] } + e.start() + k := key(vpcA, "svc-a") + routed := spec(workerv1alpha1.Handoff_HANDOFF_ROUTED_LINK, "guest-a1") + fromPod := func(pod string, gen uint64) error { + ctx := metadata.AppendToOutgoingContext(e.ctx(routedSA), podMD, pod) + _, err := e.api.Request(ctx, &workerv1alpha1.RequestRequest{Key: k, Generation: gen, Spec: routed}) + return err + } + e.mustOK(fromPod(podOne, 1)) + e.waitReady(mkey(vpcA, "svc-a"), 1) e.idle() - unchanged := e.persisted() - e.mustOK(fromPod("pod-2")) + before := e.persisted() + + // A second pod, while the first runs: refused, with nothing changed. + wantRefusal(t, fromPod("pod-2", 1), codes.FailedPrecondition, workerv1alpha1.ReasonClaimHeldByAnotherPod) + ctx := metadata.AppendToOutgoingContext(e.ctx(routedSA), podMD, "pod-2") + _, err := e.api.Update(ctx, &workerv1alpha1.UpdateRequest{Key: k, Generation: 2, Spec: routed}) + wantRefusal(t, err, codes.FailedPrecondition, workerv1alpha1.ReasonClaimHeldByAnotherPod) e.idle() for name, b := range e.persisted() { - if unchanged[name] != b { - t.Fatalf("a duplicate Request from the same pod rewrote %s", name) + if before[name] != b { + t.Fatalf("a refused call from another pod rewrote %s", name) + } + } + if got := hm.pod(mkey(vpcA, "svc-a")); got != podOne { + t.Fatalf("the claim serves %q after a refused call, want pod-1", got) + } + + // The first pod is gone: the next call moves the claim. + mu.Lock() + delete(alive, podOne) + mu.Unlock() + e.mustOK(fromPod("pod-2", 1)) + e.eventually("the claim follows the owner's new pod", func() bool { return hm.pod(mkey(vpcA, "svc-a")) == "pod-2" }) + recorded := false + for name, b := range e.persisted() { + if strings.HasPrefix(name, "claims/") && strings.Contains(b, `"podUID":"pod-2"`) { + recorded = true } } + if !recorded { + t.Fatal("the claim's new pod was not recorded durably") + } } diff --git a/internal/worker/harness_test.go b/internal/worker/harness_test.go index 0acb8ff6..84a87b84 100644 --- a/internal/worker/harness_test.go +++ b/internal/worker/harness_test.go @@ -48,6 +48,7 @@ const ( gwSA = "galactic-system/gateway" otherSA = "galactic-system/other" routerSA = "galactic-system/galactic-router" + routedSA = "galactic-system/envoy-routed" callerMD = "x-test-caller" // podMD names the pod a test caller calls from. @@ -63,6 +64,7 @@ var ( gwSA: {workerv1alpha1.CapabilityLocalTap}, otherSA: {workerv1alpha1.CapabilityLocalVethPair, workerv1alpha1.CapabilityFabricSRv6}, routerSA: {workerv1alpha1.CapabilityFabricRoutes}, + routedSA: {workerv1alpha1.CapabilityLocalRoutedLink, workerv1alpha1.CapabilityLocalSocket}, } ) @@ -125,6 +127,8 @@ type env struct { cfg Config clock *clock modules func(*fake.Host) []module.Module + // podAlive is Deps.PodAlive. + podAlive func(string) bool // hostState, when set, is the VPCs' canonical host state each // incarnation reconciles. hostState hostscope.Host @@ -223,7 +227,7 @@ func (e *env) start() { e.t.Fatal(err) } w, err := New(e.cfg, Deps{Store: e.store, Fence: e.fence, Sources: e.src, Modules: reg, Auth: metaAuth{}, - Host: e.hostState, Routes: e.routes, Now: e.clock.Now}) + Host: e.hostState, Routes: e.routes, Now: e.clock.Now, PodAlive: e.podAlive}) if err != nil { e.t.Fatal(err) } diff --git a/internal/worker/local/podns.go b/internal/worker/local/podns.go index 603abbb2..cb07e113 100644 --- a/internal/worker/local/podns.go +++ b/internal/worker/local/podns.go @@ -99,6 +99,28 @@ func (p *ProcPods) Open(podUID string) (netns.NsHandle, error) { var errOtherPod = errors.New("local: the process belongs to another pod") +// Alive reports whether a process of the pod with podUID runs on this node. +func (p *ProcPods) Alive(podUID string) bool { + if podUID == "" { + return false + } + entries, err := os.ReadDir(p.ProcRoot) + if err != nil { + // Unknown counts as alive, so a pod is never displaced on a guess. + return true + } + for _, e := range entries { + n, err := strconv.ParseInt(e.Name(), 10, 32) + if err != nil || n <= 0 { + continue + } + if uid, err := p.Pods.PodUID(int32(n)); err == nil && uid == podUID { + return true + } + } + return false +} + // openPID opens pid's network namespace when pid belongs to podUID, before // and after the open, so a process that exits and has its PID reused in // between is never mistaken for the pod's. diff --git a/internal/worker/local/podns_test.go b/internal/worker/local/podns_test.go index 8528cd76..586a57c9 100644 --- a/internal/worker/local/podns_test.go +++ b/internal/worker/local/podns_test.go @@ -71,3 +71,11 @@ func TestProcPodsOpensOnlyTheCallersPod(t *testing.T) { t.Fatalf("Open(pod-b) after its processes left = %v, want ErrPodNotFound", err) } } + +// TestProcPodsAlive checks that a pod runs while a process's cgroup names it. +func TestProcPodsAlive(t *testing.T) { + pods := &ProcPods{ProcRoot: procRoot(t, 100), Pods: cgroupPods{100: podB}} + if !pods.Alive(podB) || pods.Alive("pod-a") || pods.Alive("") { + t.Fatal("Alive did not follow the processes' pods") + } +} diff --git a/internal/worker/worker.go b/internal/worker/worker.go index a8ef1391..2b097b1e 100644 --- a/internal/worker/worker.go +++ b/internal/worker/worker.go @@ -129,6 +129,11 @@ type Deps struct { Log *slog.Logger // Now is the clock, time.Now when nil. Now func() time.Time + // PodAlive reports whether a process of the pod with the given UID runs + // on this node. A routed_link or socket claim's link serves one pod, and + // a call from another pod of its owner is refused while that pod runs. + // Without it, such a call moves the claim to the calling pod. + PodAlive func(podUID string) bool } // claim is one claim's desired state and last status.