feat: Support --empty-ns checkpoint/restore option (#3700)

* Support `--empty-ns` checkpoint option

Pass --empty-ns from the CLI to CRIU so the network namespace is
created empty on restore instead of being dumped. Youki does not
manage network devices, so their external dependencies cannot be
described to CRIU. Runc sets this unconditionally for the same reason.
To verifty the functionality, contest check the existence of
netdev-*.img which holds the network devices of a dumped namespace.

Signed-off-by: donkomura <koiru3822fs@gmail.com>

* Reject unsupported namespaces for --empty-ns

Only `network` namespace is supported for empty-ns option,
but the given value was not validated. Add the check and
reject others to match runc. Also document that `network`
applies even without the flag.

Signed-off-by: donkomura <koiru3822fs@gmail.com>

---------

Signed-off-by: donkomura <koiru3822fs@gmail.com>

Author: donkomura

crates/libcontainer/src/container/container.rs

@@ -244,6 +244,7 @@ pub struct CheckpointOptions {
     pub work_path: Option<PathBuf>,
     pub manage_cgroups_mode: rust_criu::CgMode,
     pub link_remap: bool,
+    pub empty_net_ns: bool,
 }
 
 #[cfg(test)]

crates/libcontainer/src/container/container_checkpoint.rs

@@ -170,6 +170,11 @@ impl Container {
         );
         criu.cgroups_mode(opts.manage_cgroups_mode.clone());
         criu.set_link_remap(opts.link_remap);
+        // youki does not manage network devices, so external dependencies such as the
+        // host side of a veth pair cannot be described to CRIU. Dumping them makes
+        // restore fail with "Unknown peer net namespace", so runc sets this unconditionally.
+        // See: https://github.com/opencontainers/runc/commit/8187fb740c202f5d29f1717bb933143c10dae8a1
+        criu.set_empty_net_ns(opts.empty_net_ns);
 
         // Register network and PID namespaces as external to CRIU.
         //

crates/liboci-cli/src/checkpoint.rs

@@ -51,9 +51,12 @@ pub struct Checkpoint {
     // pub pre_dump: bool,
     #[arg(long, default_value = "soft", value_parser = clap::builder::PossibleValuesParser::new(["ignore", "full", "strict", "soft"]))]
     pub manage_cgroups_mode: String,
-    // TODO: Checkpoint a namespace, but don't save its properties
-    // #[arg(long)]
-    // pub empty_ns: bool,
+    /// Checkpoint a namespace, but don't save its properties
+    ///
+    /// Only `network` is accepted, and it applies even without this flag: youki does not manage
+    /// network devices, so their external dependencies cannot be described to CRIU.
+    #[arg(long, default_value = "network")]
+    pub empty_ns: String,
     // TODO: Enable auto-deduplication
     // #[arg(long)]
     // pub auto_dedup: bool,

crates/youki/src/commands/checkpoint.rs

@@ -6,6 +6,8 @@ use liboci_cli::Checkpoint;
 
 use crate::commands::load_container;
 
+const NETWORK_NS: &str = "network";
+
 pub fn checkpoint(args: Checkpoint, root_path: PathBuf) -> Result<()> {
     tracing::debug!("start checkpointing container {}", args.container_id);
     let mut container = load_container(root_path, &args.container_id)?;
@@ -20,12 +22,20 @@ pub fn checkpoint(args: Checkpoint, root_path: PathBuf) -> Result<()> {
         work_path: args.work_path,
         manage_cgroups_mode: parse_cgroups_mode(&args.manage_cgroups_mode)?,
         link_remap: args.link_remap,
+        empty_net_ns: parse_empty_ns(&args.empty_ns)?,
     };
     container
         .checkpoint(&opts)
         .with_context(|| format!("failed to checkpoint container {}", args.container_id))
 }
 
+fn parse_empty_ns(s: &str) -> Result<bool, anyhow::Error> {
+    match s {
+        NETWORK_NS => Ok(true),
+        _ => Err(anyhow::anyhow!("namespace {s:?} is not supported")),
+    }
+}
+
 fn parse_cgroups_mode(s: &str) -> Result<rust_criu::CgMode, anyhow::Error> {
     match s {
         "ignore" => Ok(rust_criu::CgMode::IGNORE),
@@ -67,4 +77,22 @@ mod tests {
         assert!(parse_cgroups_mode("unknown").is_err());
         assert!(parse_cgroups_mode("").is_err());
     }
+
+    #[test]
+    fn test_parse_empty_ns_ok() {
+        assert!(matches!(parse_empty_ns("network"), Ok(true)));
+    }
+
+    #[test]
+    fn test_parse_empty_ns_ng() {
+        for ns in [
+            "pid", "mount", "ipc", "user", "uts", "cgroup", "Network", "",
+        ] {
+            let err = parse_empty_ns(ns).unwrap_err();
+            assert_eq!(
+                err.to_string(),
+                format!("namespace {ns:?} is not supported")
+            );
+        }
+    }
 }

tests/contest/contest/src/tests/checkpoint_restore/mod.rs

@@ -1532,6 +1532,81 @@ fn checkpoint_and_restore_with_link_remap() -> TestResult {
     }
 }
 
+fn checkpoint_and_restore_empty_net_ns() -> TestResult {
+    let ctx = match setup_cr_test(|_, _| {}) {
+        Ok(c) => c,
+        Err(e) => return e,
+    };
+    if let Err(e) = ctx.start() {
+        return e;
+    }
+
+    let id = &ctx.id;
+    let bundle = &ctx.bundle;
+    let image_dir = &ctx.image_dir;
+    let work_dir = &ctx.work_dir;
+
+    if let Err(e) = checkpoint_container(
+        bundle.path(),
+        id,
+        image_dir,
+        Some(work_dir),
+        &["--empty-ns", "network"],
+        &[],
+    ) {
+        return TestResult::Failed(anyhow!("checkpoint with --empty-ns network failed: {e}"));
+    }
+
+    // netdev-<id>.img holds the network devices of a dumped namespace
+    match std::fs::read_dir(image_dir) {
+        Ok(entries) => {
+            let netdev_img = entries.flatten().find(|entry| {
+                let name = entry.file_name().to_string_lossy().into_owned();
+                name.starts_with("netdev-") && name.ends_with(".img")
+            });
+            if let Some(entry) = netdev_img {
+                return TestResult::Failed(anyhow!(
+                    "{:?} was written: the network namespace was dumped although it must be emptied",
+                    entry.path()
+                ));
+            }
+        }
+        Err(e) => return TestResult::Failed(anyhow!("failed to read image-dir: {e}")),
+    }
+
+    if let Err(e) = wait_for_state(
+        id,
+        bundle,
+        WaitTarget::Deleted,
+        Duration::from_secs(5),
+        Duration::from_millis(100),
+    ) {
+        return TestResult::Failed(anyhow!(
+            "container state still accessible after checkpoint: {e}"
+        ));
+    }
+
+    if let Err(e) = restore_container(bundle.path(), id, image_dir, Some(work_dir), &[], &[]) {
+        return TestResult::Failed(anyhow!("restore failed: {e}"));
+    }
+
+    if let Err(e) = wait_for_state(
+        id,
+        bundle,
+        WaitTarget::Status(LifecycleStatus::Running),
+        Duration::from_secs(10),
+        Duration::from_millis(100),
+    ) {
+        return TestResult::Failed(anyhow!("not running after restore: {e}"));
+    }
+
+    if let Err(e) = ping_container(bundle.path()) {
+        return TestResult::Failed(anyhow!("ping container failed after restore: {e}"));
+    }
+
+    TestResult::Passed
+}
+
 pub fn get_checkpoint_restore_tests() -> TestGroup {
     let mut tg = TestGroup::new("checkpoint_restore");
     // Run sequentially: CRIU uses global kernel resources and parallel
@@ -1600,5 +1675,9 @@ pub fn get_checkpoint_restore_tests() -> TestGroup {
         "checkpoint_and_restore_with_link_remap",
         checkpoint_and_restore_with_link_remap
     ))]);
+    tg.add(vec![Box::new(cr_test!(
+        "checkpoint_and_restore_empty_net_ns",
+        checkpoint_and_restore_empty_net_ns
+    ))]);
     tg
 }

tests/contest/contest/src/tests/lifecycle/checkpoint.rs

@@ -663,3 +663,46 @@ pub fn checkpoint_with_external_namespaces(project_path: &Path, id: &str) -> Tes
 
     TestResult::Passed
 }
+
+/// Checkpoint a container and verify that the content of its network namespace
+/// was not dumped.
+pub fn checkpoint_empty_net_ns(project_path: &Path, id: &str) -> TestResult {
+    let (_temp_dir, image_path) = match create_checkpoint_image_dir() {
+        Ok(v) => v,
+        Err(e) => return e,
+    };
+
+    let result = checkpoint(
+        project_path,
+        id,
+        &image_path,
+        vec!["--leave-running", "--empty-ns", "network"],
+        None,
+    );
+    if !matches!(result, TestResult::Passed) {
+        return result;
+    }
+
+    // netdev-<id>.img holds the network devices of a dumped namespace
+    let netdev_img = match std::fs::read_dir(&image_path) {
+        Ok(entries) => entries
+            .flatten()
+            .find(|entry| {
+                let name = entry.file_name().to_string_lossy().into_owned();
+                name.starts_with("netdev-") && name.ends_with(".img")
+            })
+            .map(|entry| entry.path()),
+        Err(e) => {
+            return TestResult::Failed(anyhow::anyhow!("failed to read {:?}: {}", &image_path, e));
+        }
+    };
+
+    if let Some(img) = netdev_img {
+        return TestResult::Failed(anyhow::anyhow!(
+            "{:?} was written: the network namespace was dumped although it must be emptied",
+            img,
+        ));
+    }
+
+    TestResult::Passed
+}

tests/contest/contest/src/tests/lifecycle/container_lifecycle.rs

@@ -196,6 +196,14 @@ impl ContainerLifecycle {
         )
     }
 
+    pub fn checkpoint_empty_net_ns(&self) -> TestResult {
+        if !criu_installed() {
+            return TestResult::Skipped("CRIU is not installed".to_string());
+        }
+
+        checkpoint::checkpoint_empty_net_ns(self.project_path.path(), &self.container_id)
+    }
+
     // NOTE: The following two methods (`checkpoint_link_remap` and
     // `checkpoint_with_external_namespaces`) deviate from the pattern used by
     // the other checkpoint methods in this impl block. The typical pattern is:
@@ -333,6 +341,10 @@ impl TestableGroup for ContainerLifecycle {
                 "checkpoint with cgroups-mode soft",
                 self.checkpoint_manage_cgroups_mode_soft(),
             ),
+            (
+                "checkpoint with empty network namespace",
+                self.checkpoint_empty_net_ns(),
+            ),
             ("checkpoint with link-remap", Self::checkpoint_link_remap()),
             (
                 "checkpoint with tcp-skip-in-flight",
@@ -370,6 +382,10 @@ impl TestableGroup for ContainerLifecycle {
                     "checkpoint with cgroups-mode soft",
                     self.checkpoint_manage_cgroups_mode_soft(),
                 )),
+                "checkpoint_empty_net_ns" => ret.push((
+                    "checkpoint with empty network namespace",
+                    self.checkpoint_empty_net_ns(),
+                )),
                 "checkpoint_link_remap" => {
                     ret.push(("checkpoint with link-remap", Self::checkpoint_link_remap()))
                 }