feat(agent): wire NetManager + IP allocator into FirecrackerDriver

- Add Net (NetManager) and Alloc (*Allocator) fields to FirecrackerDriver
- Add netInfo field to fcProc to carry per-VM network state
- Add setupNetwork: fetches ImpNetwork, allocates IP, creates bridge+TAP,
  installs NAT rules (best-effort)
- Start calls setupNetwork when vm.Spec.NetworkRef != nil && d.Net != nil
- buildConfig gains a netInfo arg and populates NetworkInterfaces when set
- Stop calls Net.TeardownVM and Alloc.Release when proc.netInfo != nil
- Inspect returns IP from proc.netInfo.IP when present
- NewFirecrackerDriver initialises Alloc via network.NewAllocator()
- Add four new unit tests covering the above paths

Author: syscod3

internal/agent/firecracker_driver.go

@@ -7,6 +7,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	gonet "net"
 	"os"
 	"os/exec"
 	"path/filepath"
@@ -17,8 +18,10 @@ import (
 	firecracker "github.com/firecracker-microvm/firecracker-go-sdk"
 	"github.com/firecracker-microvm/firecracker-go-sdk/client/models"
 	ctrlclient "sigs.k8s.io/controller-runtime/pkg/client"
+	logf "sigs.k8s.io/controller-runtime/pkg/log"
 
 	impdevv1alpha1 "github.com/syscode-labs/imp/api/v1alpha1"
+	"github.com/syscode-labs/imp/internal/agent/network"
 	"github.com/syscode-labs/imp/internal/agent/rootfs"
 )
 
@@ -31,6 +34,7 @@ type fcProc struct {
 	machine *firecracker.Machine
 	pid     int64
 	socket  string
+	netInfo *network.NetworkInfo // nil when NetworkRef is absent
 }
 
 // FirecrackerDriver is a VMDriver that launches real Firecracker microVMs.
@@ -48,6 +52,11 @@ type FirecrackerDriver struct {
 	Cache *rootfs.Builder
 	// Client is the controller-runtime Kubernetes client.
 	Client ctrlclient.Client
+	// Net manages host-level networking (bridge, TAP, NAT).
+	// May be nil for VMs that do not reference an ImpNetwork.
+	Net network.NetManager
+	// Alloc manages in-memory IP allocation per ImpNetwork.
+	Alloc *network.Allocator
 
 	// mu guards procs. Must be held for any read or write of the procs map.
 	mu    sync.Mutex
@@ -97,13 +106,14 @@ func NewFirecrackerDriver(client ctrlclient.Client) (*FirecrackerDriver, error)
 		KernelArgs: kernelArgs,
 		Cache:      &rootfs.Builder{CacheDir: cacheDir},
 		Client:     client,
+		Alloc:      network.NewAllocator(),
 		procs:      make(map[string]*fcProc),
 	}, nil
 }
 
 // Start implements VMDriver. Fetches the ImpVMClass for compute specs, builds
-// an ext4 rootfs from the OCI image, then boots a Firecracker microVM.
-// Phase 1: loopback networking only. Returns the VMM process PID.
+// an ext4 rootfs from the OCI image, sets up networking if NetworkRef is set,
+// then boots a Firecracker microVM. Returns the VMM process PID.
 func (d *FirecrackerDriver) Start(ctx context.Context, vm *impdevv1alpha1.ImpVM) (int64, error) {
 	if vm.Spec.ClassRef == nil {
 		return 0, fmt.Errorf("vm %s/%s has no classRef", vm.Namespace, vm.Name)
@@ -121,19 +131,29 @@ func (d *FirecrackerDriver) Start(ctx context.Context, vm *impdevv1alpha1.ImpVM)
 		return 0, fmt.Errorf("build rootfs for %s: %w", vm.Spec.Image, err)
 	}
 
-	// 3. Ensure socket directory exists.
+	// 3. Set up networking if a NetworkRef is specified.
+	var netInfo *network.NetworkInfo
+	if vm.Spec.NetworkRef != nil && d.Net != nil {
+		ni, err := d.setupNetwork(ctx, vm)
+		if err != nil {
+			return 0, fmt.Errorf("setup network: %w", err)
+		}
+		netInfo = ni
+	}
+
+	// 4. Ensure socket directory exists.
 	if err := os.MkdirAll(d.SocketDir, 0o750); err != nil {
 		return 0, fmt.Errorf("socket dir: %w", err)
 	}
 	sockPath := d.socketPath(vm)
 
-	// 4. Build Firecracker config.
-	cfg := d.buildConfig(&class, rootfsPath, sockPath)
+	// 5. Build Firecracker config.
+	cfg := d.buildConfig(&class, rootfsPath, sockPath, netInfo)
 
-	// 5. Build the VMM command.
+	// 6. Build the VMM command.
 	cmd := exec.CommandContext(ctx, d.BinPath, "--api-sock", sockPath) //nolint:gosec // G204: BinPath validated in NewFirecrackerDriver
 
-	// 6. Create and start the machine.
+	// 7. Create and start the machine.
 	m, err := firecracker.NewMachine(ctx, cfg, firecracker.WithProcessRunner(cmd))
 	if err != nil {
 		return 0, fmt.Errorf("create machine: %w", err)
@@ -152,7 +172,7 @@ func (d *FirecrackerDriver) Start(ctx context.Context, vm *impdevv1alpha1.ImpVM)
 	}
 
 	d.mu.Lock()
-	d.procs[vmKey(vm)] = &fcProc{machine: m, pid: int64(pid), socket: sockPath}
+	d.procs[vmKey(vm)] = &fcProc{machine: m, pid: int64(pid), socket: sockPath, netInfo: netInfo}
 	d.mu.Unlock()
 
 	return int64(pid), nil
@@ -172,17 +192,32 @@ func (d *FirecrackerDriver) Stop(ctx context.Context, vm *impdevv1alpha1.ImpVM)
 		return nil // already stopped or never started
 	}
 
-	// Attempt graceful ACPI shutdown with a timeout.
-	shutdownCtx, cancel := context.WithTimeout(ctx, shuttingDownTimeout)
-	defer cancel()
-	_ = proc.machine.Shutdown(shutdownCtx) //nolint:errcheck // best-effort graceful stop
+	if proc.machine != nil {
+		// Attempt graceful ACPI shutdown with a timeout.
+		shutdownCtx, cancel := context.WithTimeout(ctx, shuttingDownTimeout)
+		defer cancel()
+		_ = proc.machine.Shutdown(shutdownCtx) //nolint:errcheck // best-effort graceful stop
 
-	// Force-kill the VMM process regardless of shutdown result.
-	_ = proc.machine.StopVMM() //nolint:errcheck // best-effort force stop
+		// Force-kill the VMM process regardless of shutdown result.
+		_ = proc.machine.StopVMM() //nolint:errcheck // best-effort force stop
+	}
 
 	// Remove the API socket file.
 	_ = os.Remove(proc.socket) //nolint:errcheck // best-effort cleanup
 
+	// Tear down networking if this VM had a network attached.
+	// NOTE: NAT rules are not torn down in Phase 1 (they are shared across VMs).
+	if proc.netInfo != nil {
+		if d.Net != nil {
+			if err := d.Net.TeardownVM(ctx, proc.netInfo.TAPName); err != nil {
+				logf.FromContext(ctx).Error(err, "TeardownVM failed", "tap", proc.netInfo.TAPName)
+			}
+		}
+		if d.Alloc != nil {
+			d.Alloc.Release(proc.netInfo.NetworkKey, proc.netInfo.IP)
+		}
+	}
+
 	d.mu.Lock()
 	delete(d.procs, key)
 	d.mu.Unlock()
@@ -192,7 +227,7 @@ func (d *FirecrackerDriver) Stop(ctx context.Context, vm *impdevv1alpha1.ImpVM)
 
 // Inspect implements VMDriver. Uses kill(pid,0) to check if the Firecracker
 // process is still alive. Returns Running=false for VMs not launched by this driver.
-// Phase 1: IP is always empty (loopback only, no TAP).
+// IP is populated from NetworkInfo when the VM was started with a NetworkRef.
 func (d *FirecrackerDriver) Inspect(_ context.Context, vm *impdevv1alpha1.ImpVM) (VMState, error) {
 	key := vmKey(vm)
 
@@ -224,8 +259,11 @@ func (d *FirecrackerDriver) Inspect(_ context.Context, vm *impdevv1alpha1.ImpVM)
 		return VMState{}, fmt.Errorf("inspect %s: %w", key, err)
 	}
 
-	// Phase 1: IP is empty (no TAP networking).
-	return VMState{Running: true, PID: proc.pid}, nil
+	ip := ""
+	if proc.netInfo != nil {
+		ip = proc.netInfo.IP
+	}
+	return VMState{Running: true, PID: proc.pid, IP: ip}, nil
 }
 
 // socketPath returns the Unix socket path for the given VM.
@@ -237,8 +275,9 @@ func (d *FirecrackerDriver) socketPath(vm *impdevv1alpha1.ImpVM) string {
 func (d *FirecrackerDriver) buildConfig(
 	class *impdevv1alpha1.ImpVMClass,
 	rootfsPath, socketPath string,
+	netInfo *network.NetworkInfo,
 ) firecracker.Config {
-	return firecracker.Config{
+	cfg := firecracker.Config{
 		SocketPath:      socketPath,
 		KernelImagePath: d.KernelPath,
 		KernelArgs:      d.KernelArgs,
@@ -255,6 +294,92 @@ func (d *FirecrackerDriver) buildConfig(
 			MemSizeMib: firecracker.Int64(int64(class.Spec.MemoryMiB)),
 		},
 	}
+	if netInfo != nil {
+		cfg.NetworkInterfaces = firecracker.NetworkInterfaces{{
+			StaticConfiguration: &firecracker.StaticNetworkConfiguration{
+				MacAddress:  netInfo.MACAddr,
+				HostDevName: netInfo.TAPName,
+				IPConfiguration: &firecracker.IPConfiguration{
+					IPAddr: gonet.IPNet{
+						IP:   gonet.ParseIP(netInfo.IP).To4(),
+						Mask: gonet.CIDRMask(netInfo.PrefixLen, 32),
+					},
+					Gateway:     gonet.ParseIP(netInfo.Gateway),
+					Nameservers: netInfo.DNS,
+				},
+			},
+		}}
+	}
+	return cfg
+}
+
+// setupNetwork fetches the ImpNetwork, allocates an IP, creates the bridge+TAP,
+// and optionally installs NAT rules. Returns the NetworkInfo for this VM.
+func (d *FirecrackerDriver) setupNetwork(ctx context.Context, vm *impdevv1alpha1.ImpVM) (*network.NetworkInfo, error) {
+	var impNet impdevv1alpha1.ImpNetwork
+	if err := d.Client.Get(ctx, ctrlclient.ObjectKey{
+		Namespace: vm.Namespace,
+		Name:      vm.Spec.NetworkRef.Name,
+	}, &impNet); err != nil {
+		return nil, fmt.Errorf("get network %q: %w", vm.Spec.NetworkRef.Name, err)
+	}
+
+	netKey := impNet.Namespace + "/" + impNet.Name
+	vKey := vmKey(vm)
+	bridgeName := network.BridgeName(netKey)
+	tapName := network.TAPName(vKey)
+	macAddr := network.MACAddr(vKey)
+
+	_, cidr, err := gonet.ParseCIDR(impNet.Spec.Subnet)
+	if err != nil {
+		return nil, fmt.Errorf("parse subnet %q: %w", impNet.Spec.Subnet, err)
+	}
+	prefixLen, _ := cidr.Mask.Size()
+
+	gateway := impNet.Spec.Gateway
+	if gateway == "" {
+		gw := make(gonet.IP, 4)
+		copy(gw, cidr.IP.To4())
+		gw[3]++
+		gateway = gw.String()
+	}
+
+	// Allocate VM IP.
+	ip, err := d.Alloc.Allocate(netKey, impNet.Spec.Subnet, gateway)
+	if err != nil {
+		return nil, fmt.Errorf("allocate IP: %w", err)
+	}
+
+	// Ensure bridge exists with gateway IP.
+	if err := d.Net.EnsureNetwork(ctx, bridgeName, gateway, prefixLen); err != nil {
+		d.Alloc.Release(netKey, ip)
+		return nil, fmt.Errorf("ensure bridge: %w", err)
+	}
+
+	// Create TAP and attach to bridge.
+	if err := d.Net.SetupVM(ctx, tapName, bridgeName, macAddr); err != nil {
+		d.Alloc.Release(netKey, ip)
+		return nil, fmt.Errorf("setup tap: %w", err)
+	}
+
+	// Install NAT if requested (best-effort — don't block VM start on NAT failure).
+	if impNet.Spec.NAT.Enabled {
+		if natErr := d.Net.EnsureNAT(ctx, impNet.Spec.Subnet, impNet.Spec.NAT.EgressInterface); natErr != nil {
+			logf.FromContext(ctx).Error(natErr, "EnsureNAT failed — VM will start without NAT")
+		}
+	}
+
+	return &network.NetworkInfo{
+		TAPName:    tapName,
+		BridgeName: bridgeName,
+		MACAddr:    macAddr,
+		IP:         ip,
+		PrefixLen:  prefixLen,
+		Gateway:    gateway,
+		DNS:        impNet.Spec.DNS,
+		Subnet:     impNet.Spec.Subnet,
+		NetworkKey: netKey,
+	}, nil
 }
 
 // compile-time interface check.

internal/agent/firecracker_driver_test.go

@@ -12,6 +12,7 @@ import (
 	"sigs.k8s.io/controller-runtime/pkg/client/fake"
 
 	impdevv1alpha1 "github.com/syscode-labs/imp/api/v1alpha1"
+	"github.com/syscode-labs/imp/internal/agent/network"
 	"github.com/syscode-labs/imp/internal/agent/rootfs"
 )
 
@@ -132,7 +133,7 @@ func TestFirecrackerDriver_BuildConfig(t *testing.T) {
 	class.Spec.VCPU = 2
 	class.Spec.MemoryMiB = 512
 
-	cfg := d.buildConfig(class, "/cache/abc.ext4", "/run/imp/sockets/default-vm.sock")
+	cfg := d.buildConfig(class, "/cache/abc.ext4", "/run/imp/sockets/default-vm.sock", nil)
 
 	if cfg.SocketPath != "/run/imp/sockets/default-vm.sock" {
 		t.Errorf("SocketPath = %q, want %q", cfg.SocketPath, "/run/imp/sockets/default-vm.sock")
@@ -239,3 +240,111 @@ func TestFirecrackerDriver_Start_Integration(t *testing.T) {
 	}
 	t.Skip("integration test — run manually on KVM-capable node")
 }
+
+func TestFirecrackerDriver_BuildConfig_WithNetInfo(t *testing.T) {
+	d := &FirecrackerDriver{
+		KernelPath: "/boot/vmlinux",
+		KernelArgs: "console=ttyS0 reboot=k panic=1 pci=off",
+	}
+
+	class := &impdevv1alpha1.ImpVMClass{}
+	class.Spec.VCPU = 1
+	class.Spec.MemoryMiB = 256
+
+	ni := &network.NetworkInfo{
+		TAPName:   "imptap-aabbccdd",
+		MACAddr:   "02:aa:bb:cc:dd:ee",
+		IP:        "192.168.100.2",
+		PrefixLen: 24,
+		Gateway:   "192.168.100.1",
+		DNS:       []string{"8.8.8.8"},
+	}
+
+	cfg := d.buildConfig(class, "/cache/root.ext4", "/run/imp/s/vm.sock", ni)
+
+	if len(cfg.NetworkInterfaces) != 1 {
+		t.Fatalf("len(NetworkInterfaces) = %d, want 1", len(cfg.NetworkInterfaces))
+	}
+	iface := cfg.NetworkInterfaces[0]
+	if iface.StaticConfiguration == nil {
+		t.Fatal("StaticConfiguration is nil")
+	}
+	if iface.StaticConfiguration.HostDevName != "imptap-aabbccdd" {
+		t.Errorf("HostDevName = %q, want %q", iface.StaticConfiguration.HostDevName, "imptap-aabbccdd")
+	}
+	if iface.StaticConfiguration.MacAddress != "02:aa:bb:cc:dd:ee" {
+		t.Errorf("MacAddress = %q, want %q", iface.StaticConfiguration.MacAddress, "02:aa:bb:cc:dd:ee")
+	}
+	if iface.StaticConfiguration.IPConfiguration == nil {
+		t.Fatal("IPConfiguration is nil")
+	}
+	if iface.StaticConfiguration.IPConfiguration.IPAddr.IP.String() != "192.168.100.2" {
+		t.Errorf("IP = %q, want 192.168.100.2", iface.StaticConfiguration.IPConfiguration.IPAddr.IP)
+	}
+}
+
+func TestFirecrackerDriver_BuildConfig_WithoutNetInfo(t *testing.T) {
+	d := &FirecrackerDriver{KernelPath: "/boot/vmlinux", KernelArgs: "console=ttyS0"}
+	class := &impdevv1alpha1.ImpVMClass{}
+	class.Spec.VCPU = 1
+	class.Spec.MemoryMiB = 256
+
+	cfg := d.buildConfig(class, "/cache/root.ext4", "/run/imp/s/vm.sock", nil)
+
+	if len(cfg.NetworkInterfaces) != 0 {
+		t.Errorf("expected no NetworkInterfaces when netInfo is nil, got %d", len(cfg.NetworkInterfaces))
+	}
+}
+
+func TestFirecrackerDriver_Inspect_ReturnsNetworkIP(t *testing.T) {
+	d := &FirecrackerDriver{procs: make(map[string]*fcProc)}
+
+	vm := &impdevv1alpha1.ImpVM{}
+	vm.Namespace = "default"
+	vm.Name = "net-vm"
+
+	d.procs[vmKey(vm)] = &fcProc{
+		pid:     int64(os.Getpid()),
+		netInfo: &network.NetworkInfo{IP: "192.168.1.5"},
+	}
+
+	state, err := d.Inspect(context.Background(), vm)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !state.Running {
+		t.Error("expected Running=true")
+	}
+	if state.IP != "192.168.1.5" {
+		t.Errorf("IP = %q, want %q", state.IP, "192.168.1.5")
+	}
+}
+
+func TestFirecrackerDriver_Stop_TeardownVMCalled(t *testing.T) {
+	stub := &network.StubNetManager{}
+	d := &FirecrackerDriver{
+		Net:   stub,
+		Alloc: network.NewAllocator(),
+		procs: make(map[string]*fcProc),
+	}
+
+	vm := &impdevv1alpha1.ImpVM{}
+	vm.Namespace = "default"
+	vm.Name = "net-vm-stop"
+
+	d.procs[vmKey(vm)] = &fcProc{
+		pid: 99999, // not running, but we are only testing teardown logic
+		netInfo: &network.NetworkInfo{
+			TAPName:    "imptap-deadbeef",
+			NetworkKey: "default/mynet",
+			IP:         "10.0.0.2",
+		},
+	}
+
+	if err := d.Stop(context.Background(), vm); err != nil {
+		t.Fatalf("unexpected Stop error: %v", err)
+	}
+	if len(stub.TeardownVMCalls) != 1 || stub.TeardownVMCalls[0] != "imptap-deadbeef" {
+		t.Errorf("TeardownVMCalls = %v, want [imptap-deadbeef]", stub.TeardownVMCalls)
+	}
+}