Add port machine restart primitive

Expose `port_runtime::restart_machine` and a matching CLI subcommand
that stops and immediately relaunches a Port-managed machine under the
same runtime root. The rootfs overlay (and therefore in-VM state —
etcd, kubelet/containerd state, pulled images) is preserved across
the swap, so a guest-image change between stop and relaunch is picked
up without losing state.

This is the building block for rolling guest-image upgrades — for
example, K3s patch bumps where the binary lives in the read-only base
image and the data dirs live in the per-machine overlay. Higher
layers (infra) drive cordon/drain orchestration on top of this
primitive.

Author: rupurt

crates/port-cli/src/lib.rs

@@ -425,6 +425,19 @@ pub enum MachineCommand {
         #[arg(long, default_value_t = 3)]
         wait_secs: u64,
     },
+    #[command(
+        about = "Restart a Port-managed machine in place, preserving the rootfs overlay so in-VM state survives the swap"
+    )]
+    Restart {
+        #[arg(long)]
+        machine: String,
+        #[arg(long, default_value = "runtime")]
+        runtime_root: PathBuf,
+        #[arg(long, default_value_t = 3)]
+        stop_wait_secs: u64,
+        #[arg(long, default_value_t = 3)]
+        boot_wait_secs: u64,
+    },
 }
 
 #[derive(Debug, Subcommand)]
@@ -2230,6 +2243,44 @@ fn run_machine(command: MachineCommand, config_path: Option<PathBuf>) -> Result<
             }
             println!("detail: {}", result.detail);
         }
+        MachineCommand::Restart {
+            machine,
+            runtime_root,
+            stop_wait_secs,
+            boot_wait_secs,
+        } => {
+            let ssh_context = ssh_machine_route_context(&config, &machine)?;
+            let result = port_runtime::restart_machine(
+                &config,
+                &runtime_root,
+                &machine,
+                Duration::from_secs(stop_wait_secs),
+                Duration::from_secs(boot_wait_secs),
+            )?;
+            println!("machine: {}", result.launch.machine_name);
+            if let Some(context) = ssh_context.as_ref() {
+                print_ssh_machine_route_context(context, "restart route");
+            }
+            println!("previous state: {}", result.stop.previous_state);
+            println!("relaunched pid: {}", result.launch.pid);
+            println!("runtime dir: {}", result.launch.runtime_dir.display());
+            println!("config path: {}", result.launch.config_path.display());
+            println!(
+                "hypervisor binary: {}",
+                result.launch.firecracker_binary.display()
+            );
+            println!("hypervisor log: {}", result.launch.log_path.display());
+            println!("console stdout: {}", result.launch.stdout_path.display());
+            println!("console stderr: {}", result.launch.stderr_path.display());
+            println!("manifest: {}", result.launch.manifest_path.display());
+            output_runtime_class(&result.launch.runtime_class);
+            if !result.launch.attached_volumes.is_empty() {
+                print!(
+                    "{}",
+                    format_attached_volumes(&result.launch.attached_volumes)
+                );
+            }
+        }
     }
 
     Ok(())
@@ -4446,6 +4497,52 @@ mod tests {
             other => panic!("unexpected command: {other:?}"),
         }
 
+        let restart = Cli::parse_from([
+            "port",
+            "machine",
+            "restart",
+            "--machine",
+            "demo",
+            "--runtime-root",
+            "/tmp/runtime",
+            "--stop-wait-secs",
+            "5",
+            "--boot-wait-secs",
+            "7",
+        ]);
+
+        match restart.command {
+            Command::Machine(MachineCommand::Restart {
+                machine,
+                runtime_root,
+                stop_wait_secs,
+                boot_wait_secs,
+            }) => {
+                assert_eq!(machine, "demo");
+                assert_eq!(runtime_root, std::path::Path::new("/tmp/runtime"));
+                assert_eq!(stop_wait_secs, 5);
+                assert_eq!(boot_wait_secs, 7);
+            }
+            other => panic!("unexpected command: {other:?}"),
+        }
+
+        let restart_defaults = Cli::parse_from(["port", "machine", "restart", "--machine", "demo"]);
+
+        match restart_defaults.command {
+            Command::Machine(MachineCommand::Restart {
+                machine,
+                runtime_root,
+                stop_wait_secs,
+                boot_wait_secs,
+            }) => {
+                assert_eq!(machine, "demo");
+                assert_eq!(runtime_root, std::path::Path::new("runtime"));
+                assert_eq!(stop_wait_secs, 3);
+                assert_eq!(boot_wait_secs, 3);
+            }
+            other => panic!("unexpected command: {other:?}"),
+        }
+
         let monitor = Cli::parse_from([
             "port",
             "machine",

crates/port-runtime/src/lib.rs

@@ -6708,6 +6708,37 @@ pub fn stop_machine(
     firecracker_local_stop_machine(runtime_root, machine_name, timeout)
 }
 
+#[derive(Debug, Clone)]
+pub struct RestartResult {
+    pub stop: StopResult,
+    pub launch: LaunchMetadata,
+}
+
+/// Stop a Port-managed machine and immediately relaunch it under the same
+/// runtime root, preserving the rootfs overlay (and therefore in-VM state).
+/// The relaunch picks up any change in the machine's guest image — making
+/// this the primitive that supports rolling guest-image upgrades (e.g. K3s
+/// patch bumps) without losing etcd, kubelet state, or pulled container
+/// images held in the overlay.
+pub fn restart_machine(
+    config: &PortConfig,
+    runtime_root: &Path,
+    machine_name: &str,
+    stop_timeout: Duration,
+    boot_wait: Duration,
+) -> Result<RestartResult> {
+    let stop = stop_machine(config, runtime_root, machine_name, stop_timeout)?;
+    let launch = launch_local_machine(
+        config,
+        &LaunchRequest {
+            machine_name,
+            runtime_root,
+            boot_wait,
+        },
+    )?;
+    Ok(RestartResult { stop, launch })
+}
+
 fn firecracker_local_stop_machine(
     runtime_root: &Path,
     machine_name: &str,