refactor: reduce parameter sprawl and complete docs

- printCHDebug: replace 14 positional params with vmCfg struct
- restoreAndResumeClone: replace 12 positional params with cloneResumeOpts
- README: add --bridge and --disk-queue-size to flags tables
- KNOWN_ISSUES: document clone disk num_queues immutability

Author: CMGS

KNOWN_ISSUES.md

@@ -27,6 +27,16 @@ OCI VMs use the kernel `ip=` boot parameter for network configuration. While mul
 
 **Workaround**: the post-clone setup hints write persistent MAC-based systemd-networkd configs for **all** NICs. These survive reboots and correctly configure every interface regardless of the kernel `ip=` limitation.
 
+## Clone/restore disk queue count is immutable
+
+When cloning or restoring a VM with a different `--cpu` value, the disk `num_queues` (one queue per vCPU) retains the snapshot's original value. This is because `num_queues` is part of the virtio-blk device state baked into the binary snapshot — changing it in `config.json` causes Cloud Hypervisor to crash on `vm.restore`.
+
+`--disk-queue-size` (ring depth per queue) **is** correctly patched on clone/restore, since it is a software-layer configuration that CH re-reads from `config.json` during restore.
+
+**Consequence**: a VM cloned with `--cpu 8` from a 2-vCPU snapshot still runs disks with 2 queues (not 8). Disk I/O is functional but does not scale to the new vCPU count.
+
+**Workaround**: none — this is a CH architectural limitation. Create a fresh VM with the desired CPU count instead of cloning if disk multi-queue scaling is critical.
+
 ## Cloud image UEFI boot compatibility
 
 Cocoon uses [rust-hypervisor-firmware](https://github.com/cloud-hypervisor/rust-hypervisor-firmware) (`CLOUDHV.fd`) for cloud image UEFI boot. This firmware implements a minimal EFI specification and does **not** support the `InstallMultipleProtocolInterfaces()` call required by newer distributions.

README.md

@@ -181,6 +181,7 @@ Applies to `cocoon vm create`, `cocoon vm run`, and `cocoon vm debug`:
 | `--queue-size` | `0` (default 512) | Virtio-net ring depth per queue (larger = better bulk throughput, smaller = better RPC latency; CH only, ignored by FC) |
 | `--disk-queue-size` | `0` (default 512) | Virtio-blk ring depth per device (CH only, ignored by FC) |
 | `--network` | empty (default)  | CNI conflist name (empty = first conflist)     |
+| `--bridge`  | empty            | TAP-on-bridge mode (value is bridge device, e.g. `cni0`); mutually exclusive with `--network` |
 | `--windows` | `false`          | Windows guest (UEFI boot, kvm_hyperv=on, no cidata) |
 
 ### Clone Flags
@@ -197,6 +198,7 @@ Applies to `cocoon vm clone`:
 | `--queue-size` | `0` (inherit)         | Virtio-net ring depth per queue (0 = inherit from snapshot) |
 | `--disk-queue-size` | `0` (inherit)    | Virtio-blk ring depth per device (0 = inherit from snapshot; CH only) |
 | `--network` | empty (inherit)          | CNI conflist name (empty = inherit from source VM)       |
+| `--bridge`  | empty                    | TAP-on-bridge mode (value is bridge device); mutually exclusive with `--network` |
 
 ### Snapshot Flags
 

cmd/vm/debug.go

@@ -61,7 +61,7 @@ func (h Handler) Debug(cmd *cobra.Command, args []string) error {
 		if balloon == 0 {
 			balloon = memoryMB / 2 //nolint:mnd
 		}
-		printCHDebug(storageConfigs, boot, vmCfg.Name, vmCfg.Image, cowPath, chBin, vmCfg.CPU, maxCPU, memoryMB, balloon, cowSizeGB, vmCfg.DiskQueueSize, vmCfg.Windows, boot.KernelPath != "")
+		printCHDebug(storageConfigs, boot, vmCfg, cowPath, chBin, maxCPU, memoryMB, balloon, cowSizeGB, boot.KernelPath != "")
 	}
 	return nil
 }
@@ -137,10 +137,13 @@ func printFCDebug(configs []*types.StorageConfig, boot *types.BootConfig, vmCfg
 	fmt.Printf("  -d '{\"action_type\": \"InstanceStart\"}'\n")
 }
 
-func printCHDebug(configs []*types.StorageConfig, boot *types.BootConfig, vmName, image, cowPath, chBin string, cpu, maxCPU, memory, balloon, cowSize, diskQueueSize int, windows, directBoot bool) {
+func printCHDebug(configs []*types.StorageConfig, boot *types.BootConfig, vmCfg *types.VMConfig, cowPath, chBin string, maxCPU, memory, balloon, cowSize int, directBoot bool) {
+	cpu := vmCfg.CPU
+	diskQueueSize := vmCfg.DiskQueueSize
+
 	if directBoot {
 		if cowPath == "" {
-			cowPath = fmt.Sprintf("cow-%s.raw", vmName)
+			cowPath = fmt.Sprintf("cow-%s.raw", vmCfg.Name)
 		}
 		debugConfigs := append(append([]*types.StorageConfig(nil), configs...),
 			&types.StorageConfig{Path: cowPath, RO: false, Serial: hypervisor.CowSerial})
@@ -154,7 +157,7 @@ func printCHDebug(configs []*types.StorageConfig, boot *types.BootConfig, vmName
 		fmt.Printf("truncate -s %dG %s\n", cowSize, cowPath)
 		fmt.Printf("mkfs.ext4 -F -m 0 -q -E lazy_itable_init=1,lazy_journal_init=1,discard %s\n", cowPath)
 		fmt.Println()
-		fmt.Printf("# Launch VM: %s (image: %s, boot: direct kernel)\n", vmName, image)
+		fmt.Printf("# Launch VM: %s (image: %s, boot: direct kernel)\n", vmCfg.Name, vmCfg.Image)
 		fmt.Printf("%s \\\n", chBin)
 		fmt.Printf("  --kernel %s \\\n", boot.KernelPath)
 		fmt.Printf("  --initramfs %s \\\n", boot.InitrdPath)
@@ -166,7 +169,7 @@ func printCHDebug(configs []*types.StorageConfig, boot *types.BootConfig, vmName
 		fmt.Printf("  --cmdline \"%s\" \\\n", cmdline)
 	} else {
 		if cowPath == "" {
-			cowPath = fmt.Sprintf("cow-%s.qcow2", vmName)
+			cowPath = fmt.Sprintf("cow-%s.qcow2", vmCfg.Name)
 		}
 		basePath := configs[0].Path
 		fmt.Println("# Prepare COW overlay")
@@ -175,14 +178,14 @@ func printCHDebug(configs []*types.StorageConfig, boot *types.BootConfig, vmName
 			fmt.Printf("qemu-img resize %s %dG\n", cowPath, cowSize)
 		}
 		fmt.Println()
-		fmt.Printf("# Launch VM: %s (image: %s, boot: UEFI firmware)\n", vmName, image)
+		fmt.Printf("# Launch VM: %s (image: %s, boot: UEFI firmware)\n", vmCfg.Name, vmCfg.Image)
 		fmt.Printf("%s \\\n", chBin)
 		fmt.Printf("  --firmware %s \\\n", boot.FirmwarePath)
 		fmt.Printf("  --disk \\\n")
 		diskArgs := cloudhypervisor.DebugDiskCLIArgs([]*types.StorageConfig{{Path: cowPath, RO: false}}, cpu, diskQueueSize)
 		fmt.Printf("    \"%s\" \\\n", diskArgs[0])
 	}
-	printCommonCHArgs(cpu, maxCPU, memory, balloon, windows)
+	printCommonCHArgs(cpu, maxCPU, memory, balloon, vmCfg.Windows)
 }
 
 func printCommonCHArgs(cpu, maxCPU, memory, balloon int, windows bool) {

hypervisor/cloudhypervisor/clone.go

@@ -123,7 +123,16 @@ func (ch *CloudHypervisor) cloneAfterExtract(ctx context.Context, vmID string, v
 		return nil, fmt.Errorf("launch CH: %w", err)
 	}
 
-	if err := ch.restoreAndResumeClone(ctx, pid, sockPath, runDir, directBoot, vmCfg.Windows, hadCidataInSnapshot, storageConfigs, networkConfigs, chCfg, vmCfg.CPU, vmCfg.DiskQueueSize); err != nil {
+	if err := ch.restoreAndResumeClone(ctx, pid, sockPath, runDir, &cloneResumeOpts{
+		directBoot:          directBoot,
+		windows:             vmCfg.Windows,
+		hadCidataInSnapshot: hadCidataInSnapshot,
+		storageConfigs:      storageConfigs,
+		networkConfigs:      networkConfigs,
+		snapshotCfg:         chCfg,
+		cpu:                 vmCfg.CPU,
+		diskQueueSize:       vmCfg.DiskQueueSize,
+	}); err != nil {
 		return nil, err
 	}
 
@@ -158,15 +167,22 @@ func (ch *CloudHypervisor) cloneAfterExtract(ctx context.Context, vmID string, v
 	return &info, nil
 }
 
+type cloneResumeOpts struct {
+	directBoot          bool
+	windows             bool
+	hadCidataInSnapshot bool
+	storageConfigs      []*types.StorageConfig
+	networkConfigs      []*types.NetworkConfig
+	snapshotCfg         *chVMConfig
+	cpu                 int
+	diskQueueSize       int
+}
+
 func (ch *CloudHypervisor) restoreAndResumeClone(
 	ctx context.Context,
 	pid int,
 	sockPath, runDir string,
-	directBoot, windows, hadCidataInSnapshot bool,
-	storageConfigs []*types.StorageConfig,
-	networkConfigs []*types.NetworkConfig,
-	snapshotCfg *chVMConfig,
-	cpu, diskQueueSize int,
+	opts *cloneResumeOpts,
 ) (err error) {
 	defer func() {
 		if err != nil {
@@ -179,16 +195,15 @@ func (ch *CloudHypervisor) restoreAndResumeClone(
 	}
 	hc := utils.NewSocketHTTPClient(sockPath)
 
-	// Replace snapshot NICs so the guest resumes with the clone's MACs.
-	if err = hotSwapNets(ctx, hc, snapshotCfg.Nets, networkConfigs); err != nil {
+	if err = hotSwapNets(ctx, hc, opts.snapshotCfg.Nets, opts.networkConfigs); err != nil {
 		return fmt.Errorf("hot-swap NICs: %w", err)
 	}
 
-	if !directBoot && !windows && !hadCidataInSnapshot {
-		if len(storageConfigs) == 0 {
+	if !opts.directBoot && !opts.windows && !opts.hadCidataInSnapshot {
+		if len(opts.storageConfigs) == 0 {
 			return fmt.Errorf("vm.add-disk (cidata): missing storage config")
 		}
-		cidataDisk := storageConfigToDisk(storageConfigs[len(storageConfigs)-1], cpu, diskQueueSize)
+		cidataDisk := storageConfigToDisk(opts.storageConfigs[len(opts.storageConfigs)-1], opts.cpu, opts.diskQueueSize)
 		if err = addDiskVM(ctx, hc, cidataDisk); err != nil {
 			return fmt.Errorf("vm.add-disk (cidata): %w", err)
 		}