feat(instances): integrate devices with instance lifecycle

Wire up device management throughout the instance lifecycle:
- create.go: Validate devices, auto-bind to VFIO, pass to VM config
- delete.go: Detach devices, auto-unbind from VFIO
- configdisk.go: Add HAS_GPU config flag for GPU instances
- manager.go: Add deviceManager dependency
- providers.go: Add ProvideDeviceManager
- wire.go/wire_gen.go: Wire up DeviceManager in DI
- api.go: Add DeviceManager to ApiService struct

Author: Rafael Garcia

cmd/api/api/api.go

@@ -2,6 +2,7 @@ package api
 
 import (
 	"github.com/onkernel/hypeman/cmd/api/config"
+	"github.com/onkernel/hypeman/lib/devices"
 	"github.com/onkernel/hypeman/lib/images"
 	"github.com/onkernel/hypeman/lib/ingress"
 	"github.com/onkernel/hypeman/lib/instances"
@@ -17,6 +18,7 @@ type ApiService struct {
 	InstanceManager instances.Manager
 	VolumeManager   volumes.Manager
 	NetworkManager  network.Manager
+	DeviceManager   devices.Manager
 	IngressManager  ingress.Manager
 }
 
@@ -29,6 +31,7 @@ func New(
 	instanceManager instances.Manager,
 	volumeManager volumes.Manager,
 	networkManager network.Manager,
+	deviceManager devices.Manager,
 	ingressManager ingress.Manager,
 ) *ApiService {
 	return &ApiService{
@@ -37,6 +40,7 @@ func New(
 		InstanceManager: instanceManager,
 		VolumeManager:   volumeManager,
 		NetworkManager:  networkManager,
+		DeviceManager:   deviceManager,
 		IngressManager:  ingressManager,
 	}
 }

cmd/api/api/api_test.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/onkernel/hypeman/cmd/api/config"
+	"github.com/onkernel/hypeman/lib/devices"
 	"github.com/onkernel/hypeman/lib/images"
 	"github.com/onkernel/hypeman/lib/instances"
 	mw "github.com/onkernel/hypeman/lib/middleware"
@@ -34,11 +35,12 @@ func newTestService(t *testing.T) *ApiService {
 
 	systemMgr := system.NewManager(p)
 	networkMgr := network.NewManager(p, cfg, nil)
+	deviceMgr := devices.NewManager(p)
 	volumeMgr := volumes.NewManager(p, 0, nil) // 0 = unlimited storage
 	limits := instances.ResourceLimits{
 		MaxOverlaySize: 100 * 1024 * 1024 * 1024, // 100GB
 	}
-	instanceMgr := instances.NewManager(p, imageMgr, systemMgr, networkMgr, volumeMgr, limits, nil, nil)
+	instanceMgr := instances.NewManager(p, imageMgr, systemMgr, networkMgr, deviceMgr, volumeMgr, limits, nil, nil)
 
 	// Register cleanup for orphaned Cloud Hypervisor processes
 	t.Cleanup(func() {
@@ -50,6 +52,7 @@ func newTestService(t *testing.T) *ApiService {
 		ImageManager:    imageMgr,
 		InstanceManager: instanceMgr,
 		VolumeManager:   volumeMgr,
+		DeviceManager:   deviceMgr,
 	}
 }
 

cmd/api/wire.go

@@ -9,6 +9,7 @@ import (
 	"github.com/google/wire"
 	"github.com/onkernel/hypeman/cmd/api/api"
 	"github.com/onkernel/hypeman/cmd/api/config"
+	"github.com/onkernel/hypeman/lib/devices"
 	"github.com/onkernel/hypeman/lib/images"
 	"github.com/onkernel/hypeman/lib/ingress"
 	"github.com/onkernel/hypeman/lib/instances"
@@ -27,6 +28,7 @@ type application struct {
 	ImageManager    images.Manager
 	SystemManager   system.Manager
 	NetworkManager  network.Manager
+	DeviceManager   devices.Manager
 	InstanceManager instances.Manager
 	VolumeManager   volumes.Manager
 	IngressManager  ingress.Manager
@@ -44,6 +46,7 @@ func initializeApp() (*application, func(), error) {
 		providers.ProvideImageManager,
 		providers.ProvideSystemManager,
 		providers.ProvideNetworkManager,
+		providers.ProvideDeviceManager,
 		providers.ProvideInstanceManager,
 		providers.ProvideVolumeManager,
 		providers.ProvideIngressManager,

cmd/api/wire_gen.go

@@ -53,7 +53,7 @@ func (m *manager) createConfigDisk(inst *Instance, imageInfo *images.Image, netC
 	// Create ext4 disk with config files
 	// Use ext4 for now (can switch to erofs when kernel supports it)
 	diskPath := m.paths.InstanceConfigDisk(inst.Id)
-	
+
 	// Calculate size (config files are tiny, use 1MB minimum)
 	_, err = images.ExportRootfs(tmpDir, diskPath, images.FormatExt4)
 	if err != nil {
@@ -70,26 +70,26 @@ func (m *manager) generateConfigScript(inst *Instance, imageInfo *images.Image,
 	if len(imageInfo.Entrypoint) > 0 {
 		entrypoint = shellQuoteArray(imageInfo.Entrypoint)
 	}
-	
+
 	// Prepare cmd value
 	cmd := ""
 	if len(imageInfo.Cmd) > 0 {
 		cmd = shellQuoteArray(imageInfo.Cmd)
 	}
-	
+
 	// Prepare workdir value
 	workdir := shellQuote("/")
 	if imageInfo.WorkingDir != "" {
 		workdir = shellQuote(imageInfo.WorkingDir)
 	}
-	
+
 	// Build environment variable exports
 	var envLines strings.Builder
 	mergedEnv := mergeEnv(imageInfo.Env, inst.Env)
 	for key, value := range mergedEnv {
 		envLines.WriteString(fmt.Sprintf("export %s=%s\n", key, shellQuote(value)))
 	}
-	
+
 	// Build network configuration section
 	// Use netConfig directly instead of trying to derive it (VM hasn't started yet)
 	networkSection := ""
@@ -105,6 +105,13 @@ GUEST_DNS="%s"
 `, netConfig.IP, cidr, netConfig.Gateway, netConfig.DNS)
 	}
 
+	// GPU passthrough configuration
+	// When devices are attached, set HAS_GPU=1 to trigger NVIDIA module loading in init
+	gpuSection := ""
+	if len(inst.Devices) > 0 {
+		gpuSection = "\n# GPU passthrough\nHAS_GPU=1\n"
+	}
+
 	// Build volume mounts section
 	// Volumes are attached as /dev/vdd, /dev/vde, etc. (after vda=rootfs, vdb=overlay, vdc=config)
 	// For overlay volumes, two devices are used: base + overlay disk
@@ -137,7 +144,7 @@ GUEST_DNS="%s"
 		volumeLines.WriteString("\"\n")
 		volumeSection = volumeLines.String()
 	}
-	
+
 	// Generate script as a readable template block
 	// ENTRYPOINT and CMD contain shell-quoted arrays that will be eval'd in init
 	script := fmt.Sprintf(`#!/bin/sh
@@ -149,16 +156,17 @@ CMD="%s"
 WORKDIR=%s
 
 # Environment variables
-%s%s%s`, 
+%s%s%s%s`,
 		inst.Id,
 		entrypoint,
 		cmd,
 		workdir,
 		envLines.String(),
 		networkSection,
 		volumeSection,
+		gpuSection,
 	)
-	
+
 	return script
 }
 

lib/instances/configdisk.go

@@ -9,6 +9,7 @@ import (
 	"time"
 
 	"github.com/nrednav/cuid2"
+	"github.com/onkernel/hypeman/lib/devices"
 	"github.com/onkernel/hypeman/lib/images"
 	"github.com/onkernel/hypeman/lib/logger"
 	"github.com/onkernel/hypeman/lib/network"
@@ -141,7 +142,7 @@ func (m *manager) createInstance(
 		return nil, ErrAlreadyExists
 	}
 
-	// 5. Apply defaults
+	// 6. Apply defaults
 	size := req.Size
 	if size == 0 {
 		size = 1 * 1024 * 1024 * 1024 // 1GB default
@@ -191,16 +192,42 @@ func (m *manager) createInstance(
 		req.Env = make(map[string]string)
 	}
 
-	// 6. Determine network based on NetworkEnabled flag
+	// 7. Determine network based on NetworkEnabled flag
 	networkName := ""
 	if req.NetworkEnabled {
 		networkName = "default"
 	}
 
-	// 7. Get default kernel version
+	// 8. Get default kernel version
 	kernelVer := m.systemManager.GetDefaultKernelVersion()
 
-	// 8. Create instance metadata
+	// 9. Validate, resolve, and auto-bind devices (GPU passthrough)
+	var resolvedDeviceIDs []string
+	if len(req.Devices) > 0 && m.deviceManager != nil {
+		for _, deviceRef := range req.Devices {
+			device, err := m.deviceManager.GetDevice(ctx, deviceRef)
+			if err != nil {
+				log.ErrorContext(ctx, "failed to get device", "device", deviceRef, "error", err)
+				return nil, fmt.Errorf("device %s: %w", deviceRef, err)
+			}
+			if device.AttachedTo != nil {
+				log.ErrorContext(ctx, "device already attached", "device", deviceRef, "instance", *device.AttachedTo)
+				return nil, fmt.Errorf("device %s is already attached to instance %s", deviceRef, *device.AttachedTo)
+			}
+			// Auto-bind to VFIO if not already bound
+			if !device.BoundToVFIO {
+				log.InfoContext(ctx, "auto-binding device to VFIO", "device", deviceRef, "pci_address", device.PCIAddress)
+				if err := m.deviceManager.BindToVFIO(ctx, device.Id); err != nil {
+					log.ErrorContext(ctx, "failed to bind device to VFIO", "device", deviceRef, "error", err)
+					return nil, fmt.Errorf("bind device %s to VFIO: %w", deviceRef, err)
+				}
+			}
+			resolvedDeviceIDs = append(resolvedDeviceIDs, device.Id)
+		}
+		log.DebugContext(ctx, "validated devices for passthrough", "id", id, "devices", resolvedDeviceIDs)
+	}
+
+	// 10. Create instance metadata
 	stored := &StoredMetadata{
 		Id:             id,
 		Name:           req.Name,
@@ -220,6 +247,7 @@ func (m *manager) createInstance(
 		DataDir:        m.paths.InstanceDir(id),
 		VsockCID:       vsockCID,
 		VsockSocket:    vsockSocket,
+		Devices:        resolvedDeviceIDs,
 	}
 
 	// Setup cleanup stack for automatic rollback on errors
@@ -243,7 +271,7 @@ func (m *manager) createInstance(
 		return nil, fmt.Errorf("create overlay disk: %w", err)
 	}
 
-	// 10. Allocate network (if network enabled)
+	// 14. Allocate network (if network enabled)
 	var netConfig *network.NetworkConfig
 	if networkName != "" {
 		log.DebugContext(ctx, "allocating network", "instance_id", id, "network", networkName)
@@ -268,7 +296,7 @@ func (m *manager) createInstance(
 		})
 	}
 
-	// 10.5. Validate and attach volumes
+	// 15. Validate and attach volumes
 	if len(req.Volumes) > 0 {
 		log.DebugContext(ctx, "validating volumes", "instance_id", id, "count", len(req.Volumes))
 		for _, volAttach := range req.Volumes {
@@ -308,7 +336,7 @@ func (m *manager) createInstance(
 		stored.Volumes = req.Volumes
 	}
 
-	// 11. Create config disk (needs Instance for buildVMConfig)
+	// 16. Create config disk (needs Instance for buildVMConfig)
 	inst := &Instance{StoredMetadata: *stored}
 	log.DebugContext(ctx, "creating config disk", "instance_id", id)
 	if err := m.createConfigDisk(inst, imageInfo, netConfig); err != nil {
@@ -487,7 +515,7 @@ func (m *manager) startAndBootVM(
 
 	// Build VM configuration matching Cloud Hypervisor VmConfig
 	inst := &Instance{StoredMetadata: *stored}
-	vmConfig, err := m.buildVMConfig(inst, imageInfo, netConfig)
+	vmConfig, err := m.buildVMConfig(ctx, inst, imageInfo, netConfig)
 	if err != nil {
 		return fmt.Errorf("build vm config: %w", err)
 	}
@@ -537,7 +565,7 @@ func (m *manager) startAndBootVM(
 }
 
 // buildVMConfig creates the Cloud Hypervisor VmConfig
-func (m *manager) buildVMConfig(inst *Instance, imageInfo *images.Image, netConfig *network.NetworkConfig) (vmm.VmConfig, error) {
+func (m *manager) buildVMConfig(ctx context.Context, inst *Instance, imageInfo *images.Image, netConfig *network.NetworkConfig) (vmm.VmConfig, error) {
 	// Get system file paths
 	kernelPath, _ := m.systemManager.GetKernelPath(system.KernelVersion(inst.KernelVersion))
 	initrdPath, _ := m.systemManager.GetInitrdPath()
@@ -644,6 +672,22 @@ func (m *manager) buildVMConfig(inst *Instance, imageInfo *images.Image, netConf
 		Socket: inst.VsockSocket,
 	}
 
+	// Device passthrough configuration (GPU, etc.)
+	var deviceConfigs *[]vmm.DeviceConfig
+	if len(inst.Devices) > 0 && m.deviceManager != nil {
+		configs := make([]vmm.DeviceConfig, 0, len(inst.Devices))
+		for _, deviceID := range inst.Devices {
+			device, err := m.deviceManager.GetDevice(ctx, deviceID)
+			if err != nil {
+				return vmm.VmConfig{}, fmt.Errorf("get device %s: %w", deviceID, err)
+			}
+			configs = append(configs, vmm.DeviceConfig{
+				Path: devices.GetDeviceSysfsPath(device.PCIAddress),
+			})
+		}
+		deviceConfigs = &configs
+	}
+
 	return vmm.VmConfig{
 		Payload: payload,
 		Cpus:    &cpus,
@@ -653,6 +697,7 @@ func (m *manager) buildVMConfig(inst *Instance, imageInfo *images.Image, netConf
 		Console: &console,
 		Net:     nets,
 		Vsock:   &vsock,
+		Devices: deviceConfigs,
 	}, nil
 }