update port expose docker style

Author: ccheshirecat

docs/3_guides/1_networking.md

@@ -71,3 +71,94 @@ For bridged mode, the orchestrator computes:
 - netmask derived from subnet mask (formatNetmask)
 
 This is passed to the runtime; the guest should configure eth0 accordingly on boot.
+
+## Port Mapping (Docker-Style)
+
+Volant supports Docker-style port mapping to expose VM services to the host. Port exposure works in two phases:
+
+### 1. Image Manifest (Declaration)
+
+Images declare what ports the application listens on inside the VM using the `network.expose` array in `manifest.json`:
+
+```toml
+[[network.expose]]
+port = 3000
+protocol = "tcp"
+
+[[network.expose]]
+port = 8080
+protocol = "tcp"
+host_port = 9000  # Optional: explicit host port mapping
+```
+
+This is similar to Docker's `EXPOSE` directive - it's documentation about what ports the app uses, but doesn't actually map them.
+
+### 2. VM Creation (Runtime Mapping)
+
+At VM creation time, you can:
+
+**Auto-assign host ports** (default behavior):
+```bash
+volar vms create myvm --image myapp
+# Manifest ports get auto-assigned: 3000→2234, 8080→2235
+```
+
+**Explicitly map host ports** using `--expose`:
+```bash
+# Docker-style syntax: [HOST_PORT:]CONTAINER_PORT[:PROTOCOL]
+volar vms create myvm --image myapp --expose 8080:3000:tcp --expose 9090:8080:tcp
+```
+
+**Disable all port exposure** (secure by default):
+```bash
+volar vms create myvm --image myapp --no-expose
+```
+
+### Host Port Auto-Allocation
+
+When ports are not explicitly mapped:
+- Host ports are auto-assigned sequentially starting from **2234**
+- Volant tracks all allocated ports across VMs to prevent conflicts
+- If an explicit port is already in use, VM creation will fail
+
+### Integration with driftd
+
+Port mappings are automatically programmed into driftd's eBPF TC dataplane:
+- NAT rules forward `host_ip:host_port` → `vm_ip:vm_port`
+- Stateful connection tracking for TCP and UDP
+- Routes persist across VM restarts
+- No manual configuration required
+
+### Examples
+
+**Web application with auto-assigned ports:**
+```toml
+# manifest.toml
+[[network.expose]]
+port = 80
+protocol = "tcp"
+```
+```bash
+volar vms create web --image nginx
+# Access via http://host_ip:2234 (auto-assigned)
+```
+
+**Database with explicit port:**
+```bash
+volar vms create postgres --image postgres:alpine --expose 5432:5432:tcp
+# Access via postgresql://host_ip:5432
+```
+
+**Multi-port service:**
+```bash
+volar vms create app --image myapp \
+  --expose 8080:3000:tcp \
+  --expose 8081:3001:tcp \
+  --expose 9000:9000:udp
+```
+
+**Secure deployment (no external ports):**
+```bash
+volar vms create internal-service --image worker --no-expose
+# Only accessible via vsock or internal VM network
+```

docs/6_reference/1_manifest-schema.md

@@ -30,7 +30,7 @@ Optional fields:
 - image, image_digest (for OCI lineage)
 - disks[]: { name, source, format?: raw|qcow2, checksum?, readonly, target? }
 - cloud_init: { datasource, seed_mode (default vfat), user_data/meta_data/network_config }
-- network: { mode: vsock|bridged|dhcp, subnet?, gateway?, auto_assign? }
+- network: { mode: vsock|bridged|dhcp, subnet?, gateway?, auto_assign?, expose?: [{port, protocol?, host_port?}, ...] }
 - devices: { pci_passthrough?: ["0000:01:00.0"...], allowlist?: ["vendor:device" or "vendor:*"] }
 - actions: map<string, { description?, method, path, timeout_ms? }>
 - health_check: { endpoint, timeout_ms }

docs/6_reference/3_manifest-toml.md

@@ -135,9 +135,16 @@ Network modes:
 - **vsock**: No Ethernet, vsock-only communication
 - **dhcp**: Tap device provided, VM runs DHCP client
 
-Port exposures:
-- Defines which ports the workload listens on
-- Can be completely replaced with `--port` flags at VM creation
+Port exposures (Docker-style):
+- **Declaration**: Defines which ports the workload listens on inside the VM
+- **Like Docker EXPOSE**: Documents what ports the app uses, but doesn't actually map them
+- **Runtime mapping**: At VM creation, use `--expose` to map host ports
+  - Auto-assigned: `--expose 3000` → host port 2234 (auto)
+  - Explicit: `--expose 8080:3000:tcp` → host:8080 → vm:3000
+  - Disable all: `--no-expose` → no ports mapped (secure by default)
+- **host_port field**: Optional static host port in manifest (rare, usually auto-assigned)
+- **Auto-allocation**: Host ports start from 2234 and increment, tracked across all VMs
+- **Integration**: Automatically programmed into driftd's eBPF TC NAT dataplane
 
 ### Actions
 

docs/6_reference/cli-volar.md

@@ -21,6 +21,9 @@ Source: internal/cli/standard.
     - --runtime <type>
     - --cpu <n>
     - --memory <mb>
+    - --env KEY=VALUE (repeatable) — set environment variables
+    - --expose [HOST_PORT:]CONTAINER_PORT[:PROTOCOL] (repeatable) — Docker-style port mapping
+    - --no-expose — disable all port exposure (secure by default)
     - --kernel-cmdline <extra>
     - --config <path to JSON>
     - --api-host <host> / --api-port <port>

internal/cli/standard/vms.go

@@ -288,6 +288,14 @@ func newVMsCreateCmd() *cobra.Command {
 			if err != nil {
 				return err
 			}
+			exposeFlags, err := cmd.Flags().GetStringSlice("expose")
+			if err != nil {
+				return err
+			}
+			noExposeFlag, err := cmd.Flags().GetBool("no-expose")
+			if err != nil {
+				return err
+			}
 
 			// Build Overrides struct
 			var overrides vmconfig.Overrides
@@ -311,7 +319,7 @@ func newVMsCreateCmd() *cobra.Command {
 				}
 			}
 
-			// Parse port exposures from PORT or HOST_PORT:CONTAINER_PORT format
+			// Parse port exposures from PORT or HOST_PORT:CONTAINER_PORT format (legacy flag)
 			if len(portFlags) > 0 {
 				overrides.ExposePorts = make([]vmconfig.Expose, 0, len(portFlags))
 				for _, p := range portFlags {
@@ -341,6 +349,90 @@ func newVMsCreateCmd() *cobra.Command {
 				}
 			}
 
+			// Parse Docker-style port exposures: [HOST_PORT:]CONTAINER_PORT[:PROTOCOL]
+			// Examples: 8080:3000:tcp, 8080:3000, 3000:tcp, 3000
+			if len(exposeFlags) > 0 {
+				if len(portFlags) > 0 {
+					return fmt.Errorf("cannot use both --port and --expose flags together")
+				}
+				overrides.ExposePorts = make([]vmconfig.Expose, 0, len(exposeFlags))
+				for _, e := range exposeFlags {
+					var expose vmconfig.Expose
+					expose.Protocol = "tcp" // default protocol
+
+					parts := strings.Split(e, ":")
+					switch len(parts) {
+					case 1:
+						// Format: CONTAINER_PORT (auto-assign host port)
+						containerPort, err := strconv.Atoi(parts[0])
+						if err != nil {
+							return fmt.Errorf("invalid port in %q: %w", e, err)
+						}
+						expose.Port = containerPort
+						expose.HostPort = 0 // Auto-assign
+
+					case 2:
+						// Could be: HOST_PORT:CONTAINER_PORT or CONTAINER_PORT:PROTOCOL
+						// Try to parse second part as protocol first
+						protocol := strings.ToLower(parts[1])
+						if protocol == "tcp" || protocol == "udp" {
+							// Format: CONTAINER_PORT:PROTOCOL
+							containerPort, err := strconv.Atoi(parts[0])
+							if err != nil {
+								return fmt.Errorf("invalid port in %q: %w", e, err)
+							}
+							expose.Port = containerPort
+							expose.Protocol = protocol
+							expose.HostPort = 0 // Auto-assign
+						} else {
+							// Format: HOST_PORT:CONTAINER_PORT
+							hostPort, err := strconv.Atoi(parts[0])
+							if err != nil {
+								return fmt.Errorf("invalid host port in %q: %w", e, err)
+							}
+							containerPort, err := strconv.Atoi(parts[1])
+							if err != nil {
+								return fmt.Errorf("invalid container port in %q: %w", e, err)
+							}
+							expose.HostPort = hostPort
+							expose.Port = containerPort
+						}
+
+					case 3:
+						// Format: HOST_PORT:CONTAINER_PORT:PROTOCOL
+						hostPort, err := strconv.Atoi(parts[0])
+						if err != nil {
+							return fmt.Errorf("invalid host port in %q: %w", e, err)
+						}
+						containerPort, err := strconv.Atoi(parts[1])
+						if err != nil {
+							return fmt.Errorf("invalid container port in %q: %w", e, err)
+						}
+						protocol := strings.ToLower(parts[2])
+						if protocol != "tcp" && protocol != "udp" {
+							return fmt.Errorf("invalid protocol in %q: must be tcp or udp", e)
+						}
+						expose.HostPort = hostPort
+						expose.Port = containerPort
+						expose.Protocol = protocol
+
+					default:
+						return fmt.Errorf("invalid expose format %q: expected [HOST_PORT:]CONTAINER_PORT[:PROTOCOL]", e)
+					}
+
+					overrides.ExposePorts = append(overrides.ExposePorts, expose)
+				}
+			}
+
+			// Handle --no-expose flag: explicitly disable all port exposure (secure by default)
+			if noExposeFlag {
+				if len(portFlags) > 0 || len(exposeFlags) > 0 {
+					return fmt.Errorf("cannot use --no-expose with --port or --expose flags")
+				}
+				// Set to empty slice to override manifest ports
+				overrides.ExposePorts = []vmconfig.Expose{}
+			}
+
 			req := client.CreateVMRequest{
 				Name:          args[0],
 				Image:         imageName,
@@ -439,7 +531,9 @@ func newVMsCreateCmd() *cobra.Command {
 	cmd.Flags().Int("cpu", 0, "Number of virtual CPU cores (overrides manifest default)")
 	cmd.Flags().Int("memory", 0, "Memory in MB (overrides manifest default)")
 	cmd.Flags().StringSlice("env", nil, "Environment variables in KEY=VALUE format (repeatable, overrides manifest defaults)")
-	cmd.Flags().StringSlice("port", nil, "Expose ports in format PORT or HOST_PORT:CONTAINER_PORT (repeatable)")
+	cmd.Flags().StringSlice("port", nil, "Expose ports in format PORT or HOST_PORT:CONTAINER_PORT (repeatable, legacy)")
+	cmd.Flags().StringSlice("expose", nil, "Expose ports in Docker format: [HOST_PORT:]CONTAINER_PORT[:PROTOCOL] (repeatable)")
+	cmd.Flags().Bool("no-expose", false, "Disable all port exposure (overrides manifest defaults for secure-by-default)")
 	cmd.Flags().String("kernel-cmdline", "", "Additional kernel cmdline parameters")
 	cmd.Flags().String("kernel", "", "Override kernel image path (vmlinux)")
 	cmd.Flags().String("initramfs", "", "Override initramfs image path (.cpio.gz)")