Build local service-route intent for VPC attachments

cmd/galactic-router/main.go

@@ -26,6 +26,9 @@ const (
 	resourceBGPPolicies        = "bgppolicies"
 	resourceBGPVRFInstances    = "bgpvrfinstances"
 	resourceServiceVIPBindings = "servicevipbindings"
+	resourceServiceEndpoints   = "serviceendpoints"
+	resourceServiceRoutePolicy = "serviceroutepolicies"
+	resourceVPCAttachments     = "vpcattachments"
 	resourceSecrets            = "secrets"
 	resourceNodes              = "nodes"
 )
@@ -65,6 +68,9 @@ func checkWatchPermissions(mgr ctrl.Manager) {
 		{group: bgpAPIGroup, version: bgpAPIVersion, resource: resourceBGPPolicies},
 		{group: bgpAPIGroup, version: bgpAPIVersion, resource: resourceBGPVRFInstances},
 		{group: bgpAPIGroup, version: bgpAPIVersion, resource: resourceServiceVIPBindings},
+		{group: bgpAPIGroup, version: bgpAPIVersion, resource: resourceServiceEndpoints},
+		{group: bgpAPIGroup, version: bgpAPIVersion, resource: resourceServiceRoutePolicy},
+		{group: "cloud.datumapis.com", version: "v1alpha1", resource: resourceVPCAttachments},
 		{version: "v1", resource: resourceSecrets},
 		{version: "v1", resource: resourceNodes},
 	}

cmd/galactic-router/root.go

@@ -18,13 +18,15 @@ import (
 	grpchealth "google.golang.org/grpc/health"
 	"google.golang.org/grpc/health/grpc_health_v1"
 	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/types"
 	utilruntime "k8s.io/apimachinery/pkg/util/runtime"
 	clientgoscheme "k8s.io/client-go/kubernetes/scheme"
 	ctrl "sigs.k8s.io/controller-runtime"
 	"sigs.k8s.io/controller-runtime/pkg/log/zap"
 	metricsserver "sigs.k8s.io/controller-runtime/pkg/metrics/server"
 	"sigs.k8s.io/controller-runtime/pkg/webhook"
 
+	cloudv1alpha1 "go.datum.net/cloud/api/v1alpha1"
 	"go.datum.net/galactic/internal/config"
 	"go.datum.net/galactic/internal/controller"
 	"go.datum.net/galactic/internal/hash"
@@ -35,6 +37,7 @@ import (
 	"go.datum.net/galactic/internal/reconcile"
 	galacticruntime "go.datum.net/galactic/internal/runtime"
 	"go.datum.net/galactic/internal/runtime/gobgp"
+	"go.datum.net/galactic/internal/serviceroute"
 	networkwebhook "go.datum.net/galactic/internal/webhook"
 	bgpv1alpha1 "go.datum.net/network/api/v1alpha1"
 )
@@ -80,6 +83,7 @@ func runCmd(cfg *config.RouterConfig) error {
 	scheme := runtime.NewScheme()
 	utilruntime.Must(clientgoscheme.AddToScheme(scheme))
 	utilruntime.Must(bgpv1alpha1.AddToScheme(scheme))
+	utilruntime.Must(cloudv1alpha1.AddToScheme(scheme))
 
 	mgrOptions := ctrl.Options{
 		Scheme:                 scheme,
@@ -268,6 +272,16 @@ func runCmd(cfg *config.RouterConfig) error {
 		return fmt.Errorf("setup ServiceVIPBinding controller: %w", err)
 	}
 
+	// Register the node-local platform service route controller. It resolves
+	// ServiceRoutePolicy against Cloud VPCAttachment.status.node and programs
+	// only this node's local eBPF state. Clear any pinned state left by a prior
+	// controller process before informer reconciliation starts. A missing map is
+	// tolerated because the datapath loader may start after galactic-router;
+	// the first Apply retries initialization.
+	if err := setupServiceRouteController(mgr, nodeName, cfg.GCNamespace); err != nil {
+		return fmt.Errorf("setup ServiceRoutePolicy controller: %w", err)
+	}
+
 	// Register GC controller for cleaning up orphaned BGP CRDs and VRFs.
 	gcRec := &controller.GCReconciler{
 		Client:    mgr.GetClient(),
@@ -332,6 +346,22 @@ func runCmd(cfg *config.RouterConfig) error {
 	return nil
 }
 
+func setupServiceRouteController(mgr ctrl.Manager, nodeName, bgpNamespace string) error {
+	programmer := &serviceroute.EBPFRouteProgrammer{}
+	if err := programmer.Initialize(); err != nil {
+		ctrl.Log.Error(err, "service route eBPF maps are not available yet; initialization will retry on reconcile")
+	}
+
+	return (&controller.ServiceRoutePolicyReconciler{
+		Client:       mgr.GetClient(),
+		Scheme:       mgr.GetScheme(),
+		NodeName:     nodeName,
+		BGPNamespace: bgpNamespace,
+		Programmer:   programmer,
+		Applied:      make(map[types.NamespacedName]map[types.NamespacedName]serviceroute.RouteIntent),
+	}).SetupWithManager(mgr)
+}
+
 // newRootCommand builds the root cobra command with all flags and the
 // application startup logic.
 func newRootCommand() *cobra.Command {

config/galactic-cni/daemonset.yaml

@@ -140,6 +140,10 @@ spec:
               mountPath: /host/var/log/galactic
             - name: bpf-fs
               mountPath: /sys/fs/bpf
+            # Shared with host-executed CNI ADD so both processes take
+            # the same per-interface TC transaction lock.
+            - name: galactic-run
+              mountPath: /run/galactic
             # radv's DefaultStateDir, shared with galactic-tap on the host --
             # see config/galactic-cni/README.md. Writable: the run daemon
             # removes the record of a tap that has gone missing.
@@ -202,3 +206,7 @@ spec:
           hostPath:
             path: /sys/fs/bpf
             type: Directory
+        - name: galactic-run
+          hostPath:
+            path: /run/galactic
+            type: DirectoryOrCreate

config/galactic-router/rbac.yaml

@@ -33,6 +33,11 @@ rules:
     resources:
       - servicevipbindings
     verbs: ["get", "list", "watch", "update", "patch"]
+  - apiGroups: ["network.datumapis.com"]
+    resources:
+      - serviceendpoints
+      - serviceroutepolicies
+    verbs: ["get", "list", "watch"]
   - apiGroups: ["network.datumapis.com"]
     resources:
       - bgprouters/status
@@ -41,7 +46,12 @@ rules:
       - bgppolicies/status
       - bgpvrfinstances/status
       - servicevipbindings/status
+      - serviceroutepolicies/status
     verbs: ["get", "update", "patch"]
+  - apiGroups: ["cloud.datumapis.com"]
+    resources:
+      - vpcattachments
+    verbs: ["get", "list", "watch"]
   - apiGroups: [""]
     resources:
       - secrets

docs/README.md

@@ -32,6 +32,9 @@ data flow, module reference, known constraints):
 
 - [router/configuration.md](router/configuration.md) — `galactic-router`
   env vars/CLI flags, the webhook options, and DaemonSet examples.
+- [router/private-service-routes.md](router/private-service-routes.md) — the
+  direct-endpoint contract for `ServiceEndpoint`, producer selection, and why
+  consumers receive no guest-visible service route.
 - [gateway/configuration.md](gateway/configuration.md) — `galactic-gateway`
   deployment (node labeling, RBAC, per-node overlay), its config reference,
   and the `NetworkGateway`/`NetworkRule`/`ServiceVIPBinding` CRD fields.

docs/router/private-service-routes.md

@@ -0,0 +1,65 @@
+# Private service routes
+
+`ServiceEndpoint` uses a direct-endpoint contract. Its declared
+`spec.address`, `spec.protocol`, and `spec.port` are the exact destination tuple
+that the selected producer attachment must accept. Galactic does not interpret
+the address as a Kubernetes Service frontend: it does not discover
+EndpointSlices, select a backend address, or translate the destination before
+delivery.
+
+The controller that publishes the `ServiceEndpoint` owns the service
+implementation and health. It must ensure every attachment selected by
+`attachmentRef` or `attachmentSelector` is ready to receive the declared tuple.
+`VPCAttachment`'s `Ready` and `Programmed` conditions are necessary networking
+prerequisites; they do not attest that a service listener is healthy. A
+listener may bind or configure the address in the producer, use a transparent
+socket, or use another service-owned mechanism. Galactic does not configure the
+producer VIP; that mechanism and its lifecycle are owned by the service.
+Whatever mechanism is used must make the exact VIP routable through the
+selected producer attachment and neighbor-resolvable on that attachment. A
+transparent socket bind by itself is insufficient when the producer VPC's FIB
+or neighbor discovery cannot deliver the VIP to that interface.
+
+Galactic selects one ready producer for each consumer. A node-local producer is
+preferred and ties are resolved deterministically by attachment namespace and
+name. More than one ready producer in the same node and VPC is rejected because
+the direct-VIP dataplane cannot distinguish those replicas. Replicas on
+different nodes or in distinct VPCs remain valid. `NodeLocal` stops there when
+no local producer is ready; `PreferNodeLocal` may select a remote producer and
+carries the original packet through the SRv6 service tunnel. In both cases the
+producer receives the declared destination and the original consumer source
+unchanged.
+
+## No consumer-visible route
+
+Galactic does not add the service address or a service-specific route to a
+consumer, and does not inject a route into a consumer guest. Consumers send the
+packet through their ordinary default gateway. The attachment's TC-eBPF
+classifier matches the exact service tuple and redirects it to the selected
+producer; unauthorized ports are dropped. Galactic also does not install a
+host route for the service address. The producer service may still need to
+configure or bind the address locally so its own network stack or listener
+accepts the packet; that producer-side configuration is not consumer-visible.
+
+Operators should therefore expect all of the following:
+
+- `ip route` inside a consumer contains no route for the service address;
+- the node has no service-address route created by the service-route
+  controller;
+- the producer receives the original service destination rather than a hidden
+  backend address; and
+- publishing an address that the producer does not accept produces an
+  unavailable service, not automatic backend discovery or translation.
+
+## Not a ServiceVIPBinding
+
+`ServiceVIPBinding` belongs to Galactic's gateway DSR dataplane. It explicitly
+maps a gateway frontend VIP and port to a real backend address and port, and its
+controller programs the separate VIP translation table. A `ServiceEndpoint`
+does not reference a `ServiceVIPBinding`, and the private service-route
+dataplane does not consult that translation to discover a backend. Reusing the
+same address in both APIs does not connect the two mechanisms.
+
+If a service needs a distinct frontend and backend address or port, its API
+must identify that backend explicitly and define its selection and health
+semantics. `ServiceEndpoint` intentionally carries no such fields.

go.mod

@@ -1,6 +1,6 @@
 module go.datum.net/galactic
 
-go 1.26.0
+go 1.26.4
 
 require (
 	github.com/cilium/ebpf v0.22.0
@@ -20,7 +20,8 @@ require (
 	github.com/spf13/pflag v1.0.10
 	github.com/spf13/viper v1.21.0
 	github.com/vishvananda/netlink v1.3.2-0.20261002201547-1d1c62507e3c
-	go.datum.net/network v0.3.0
+	go.datum.net/cloud v0.1.1-0.20260918213150-260f797bbc5c
+	go.datum.net/network v0.3.1-0.20261006185716-0f099eb3b0ea
 	golang.org/x/sys v0.48.0
 	golang.org/x/term v0.46.0
 	google.golang.org/grpc v1.84.0
@@ -42,20 +43,30 @@ require (
 	github.com/eapache/queue v1.1.0 // indirect
 	github.com/emicklei/go-restful/v3 v3.13.0 // indirect
 	github.com/evanphx/json-patch/v5 v5.9.11 // indirect
-	github.com/fsnotify/fsnotify v1.9.0 // indirect
+	github.com/fsnotify/fsnotify v1.10.1 // indirect
 	github.com/fxamacker/cbor/v2 v2.9.0 // indirect
 	github.com/gaissmai/bart v0.26.1 // indirect
 	github.com/go-logr/logr v1.4.3 // indirect
 	github.com/go-logr/zapr v1.3.0 // indirect
-	github.com/go-openapi/jsonpointer v0.21.0 // indirect
-	github.com/go-openapi/jsonreference v0.20.2 // indirect
-	github.com/go-openapi/swag v0.23.0 // indirect
+	github.com/go-openapi/jsonpointer v0.23.1 // indirect
+	github.com/go-openapi/jsonreference v0.21.6 // indirect
+	github.com/go-openapi/swag v0.26.0 // indirect
+	github.com/go-openapi/swag/cmdutils v0.26.0 // indirect
+	github.com/go-openapi/swag/conv v0.26.0 // indirect
+	github.com/go-openapi/swag/fileutils v0.26.0 // indirect
+	github.com/go-openapi/swag/jsonname v0.26.0 // indirect
+	github.com/go-openapi/swag/jsonutils v0.26.0 // indirect
+	github.com/go-openapi/swag/loading v0.26.0 // indirect
+	github.com/go-openapi/swag/mangling v0.26.0 // indirect
+	github.com/go-openapi/swag/netutils v0.26.0 // indirect
+	github.com/go-openapi/swag/stringutils v0.26.0 // indirect
+	github.com/go-openapi/swag/typeutils v0.26.0 // indirect
+	github.com/go-openapi/swag/yamlutils v0.26.0 // indirect
 	github.com/go-viper/mapstructure/v2 v2.4.0 // indirect
-	github.com/google/gnostic-models v0.7.0 // indirect
+	github.com/google/gnostic-models v0.7.1 // indirect
 	github.com/google/go-cmp v0.7.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
 	github.com/inconshreveable/mousetrap v1.1.0 // indirect
-	github.com/josharian/intern v1.0.0 // indirect
 	github.com/json-iterator/go v1.1.12 // indirect
 	github.com/k-sone/critbitgo v1.4.0 // indirect
 	github.com/kylelemons/godebug v1.1.0 // indirect
@@ -93,18 +104,17 @@ require (
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sync v0.22.0 // indirect
 	golang.org/x/text v0.41.0 // indirect
-	golang.org/x/time v0.14.0 // indirect
+	golang.org/x/time v0.15.0 // indirect
 	golang.org/x/tools v0.48.0 // indirect
-	gomodules.xyz/jsonpatch/v2 v2.4.0 // indirect
+	gomodules.xyz/jsonpatch/v2 v2.5.0 // indirect
 	google.golang.org/genproto/googleapis/rpc v0.0.0-20260706201446-f0a921348800 // indirect
 	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 	honnef.co/go/tools v0.7.0 // indirect
-	k8s.io/apiextensions-apiserver v0.36.0 // indirect
+	k8s.io/apiextensions-apiserver v0.36.1 // indirect
 	k8s.io/klog/v2 v2.140.0 // indirect
-	k8s.io/kube-openapi v0.0.0-20260317180543-43fb72c5454a // indirect
-	k8s.io/utils v0.0.0-20260210185600-b8788abfbbc2 // indirect
+	k8s.io/kube-openapi v0.0.0-20260330154417-16be699c7b31 // indirect
+	k8s.io/utils v0.0.0-20260707023825-cf1189d6abe3 // indirect
 	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
 	sigs.k8s.io/knftables v0.0.18 // indirect
 	sigs.k8s.io/randfill v1.0.0 // indirect