Merge pull request #268 from Dstack-TEE/vmm-init-stopped

vmm-cli: Add --stopped and --user-config

Author: kvinwang

docs/vmm-cli-user-guide.md

@@ -250,8 +250,10 @@ Deploy your application with the compose file:
 - `--gpu`: GPU assignments
 - `--ppcie`: Enable PPCIE mode (attach ALL available GPUs and NVSwitches)
 - `--env-file`: Environment variables file
+- `--user-config`: Path to user config file (will be placed at `/dstack/.user-config` in the CVM)
 - `--kms-url`: KMS server URL
 - `--gateway-url`: Gateway server URL
+- `--stopped`: Create VM in stopped state (requires dstack-vmm >= 0.5.4)
 
 #### Port Mapping
 
@@ -390,6 +392,40 @@ export DSTACK_VMM_URL=http://ml-cluster:8080
   --env-file ./ml-secrets.env
 ```
 
+##### VM with User Configuration and Stopped State
+
+```bash
+# Create a user configuration file
+cat > user-config.json << EOF
+{
+  "timezone": "UTC",
+  "locale": "en_US.UTF-8",
+  "custom_settings": {
+    "debug_mode": false,
+    "log_level": "INFO"
+  }
+}
+EOF
+
+# Deploy VM in stopped state with user config
+./vmm-cli.py deploy \
+  --name "configured-vm" \
+  --image "dstack-0.5.4" \
+  --compose ./app-compose.json \
+  --vcpu 4 \
+  --memory 8G \
+  --disk 100G \
+  --user-config ./user-config.json \
+  --stopped
+
+# The VM is created but not started - start it manually when ready
+./vmm-cli.py start configured-vm
+```
+
+**Note:** The `--stopped` flag is useful for:
+- Pre-staging VMs for later use
+- Preparing VMs with specific configurations before startup
+
 ### Environment Variable Encryption
 
 The VMM CLI automatically encrypts sensitive environment variables before sending them to the server.

vmm/rpc/proto/vmm_rpc.proto

@@ -77,6 +77,8 @@ message VmConfiguration {
   repeated string kms_urls = 14;
   // Gateway URLs
   repeated string gateway_urls = 15;
+  // The VM is stopped
+  bool stopped = 16;
 }
 
 message GpuConfig {

vmm/src/app/qemu.rs

@@ -113,6 +113,7 @@ impl VmInfo {
                     .as_ref()
                     .map(|c| c.gateway_urls.clone())
                     .unwrap_or_default();
+                let stopped = !workdir.started().unwrap_or(false);
 
                 Some(pb::VmConfiguration {
                     name: self.manifest.name.clone(),
@@ -153,6 +154,7 @@ impl VmInfo {
                     }),
                     kms_urls,
                     gateway_urls,
+                    stopped,
                 })
             },
             app_url: self

vmm/src/main_service.rs

@@ -185,7 +185,7 @@ impl VmmRpc for RpcHandler {
             .put_manifest(&manifest)
             .context("Failed to write manifest")?;
         let work_dir = self.prepare_work_dir(&id, &request, &app_id)?;
-        if let Err(err) = vm_work_dir.set_started(true) {
+        if let Err(err) = vm_work_dir.set_started(!request.stopped) {
             warn!("Failed to set started: {}", err);
         }
 
@@ -195,7 +195,13 @@ impl VmmRpc for RpcHandler {
             .await
             .context("Failed to load VM");
         let result = match result {
-            Ok(()) => self.app.start_vm(&id).await,
+            Ok(()) => {
+                if !request.stopped {
+                    self.app.start_vm(&id).await
+                } else {
+                    Ok(())
+                }
+            }
             Err(err) => Err(err),
         };
         if let Err(err) = result {

vmm/src/tests/test-deployment.sh

@@ -3,7 +3,7 @@
 # Test script for vmm-cli.py deployment functionality
 # Tests the complete compose + deploy workflow with local VMM instance
 
-set -e  # Exit on any error
+set -e # Exit on any error
 
 # Colors for output
 RED='\033[0;31m'

vmm/src/vmm-cli.py

@@ -492,6 +492,14 @@ def create_vm(self, args) -> None:
 
         envs = parse_env_file(args.env_file)
 
+        # Read user config file if provided
+        user_config = ""
+        if args.user_config:
+            if not os.path.exists(args.user_config):
+                raise Exception(f"User config file not found: {args.user_config}")
+            with open(args.user_config, 'r') as f:
+                user_config = f.read()
+
         # Create VM request
         params = {
             "name": args.name,
@@ -501,9 +509,11 @@ def create_vm(self, args) -> None:
             "memory": args.memory,
             "disk_size": args.disk,
             "app_id": args.app_id,
+            "user_config": user_config,
             "ports": [parse_port_mapping(port) for port in args.port or []],
             "hugepages": args.hugepages,
             "pin_numa": args.pin_numa,
+            "stopped": args.stopped,
         }
 
         if args.ppcie:
@@ -884,6 +894,8 @@ def main():
         '--disk', type=parse_disk_size, default=20, help='Disk size (e.g. 1G, 100M)')
     deploy_parser.add_argument(
         '--env-file', help='File with environment variables to encrypt', default=None)
+    deploy_parser.add_argument(
+        '--user-config', help='Path to user config file', default=None)
     deploy_parser.add_argument('--app-id', help='Application ID', default=None)
     deploy_parser.add_argument('--port', action='append', type=str,
                                help='Port mapping in format: protocol[:address]:from:to')
@@ -899,6 +911,8 @@ def main():
                                help='KMS URL')
     deploy_parser.add_argument('--gateway-url', action='append', type=str,
                                help='Gateway URL')
+    deploy_parser.add_argument('--stopped', action='store_true',
+                               help='Create VM in stopped state (requires dstack-vmm >= 0.5.4)')
 
     # Images command
     _images_parser = subparsers.add_parser(