Let a guest runtime own workload identity across restore

A runtime that runs several independent workloads has no single workload
process or per-workload machine ID to publish. It may now create the regular
file /run/nvx/runtime-workload-identity before capture. The native helper
then requires neither single-workload identity on a workload-start restore
and leaves every workload hostname to the runtime hook, which remains
mandatory. The guest's own identity is still refreshed. Capture and restore
reject a marker that is not a regular file, and the helper is unchanged when
the marker is absent.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: esaurez

doc/design/snapshot-and-restore.md

@@ -64,6 +64,16 @@ identities to be absent only for this explicit image format; the runtime hook
 remains mandatory. This does not make workload snapshots safe to share outside
 their trust domain.
 
+A guest runtime that runs several independent workloads may instead create the
+regular file `/run/nvx/runtime-workload-identity` before capture. The marker
+declares that the runtime's post-restore hook refreshes or deliberately
+preserves each workload's identity. The native helper then requires neither a
+single workload process nor a per-workload machine ID on a `workload-start`
+restore, and it does not rewrite any workload hostname. It still refreshes the
+guest's own identity, and the runtime hook remains mandatory. Capture and
+restore reject a marker that is not a regular file. Without the marker, the
+helper's behavior is unchanged.
+
 1. gate host input and defer completion of the snapshot-port write;
 2. stop the vCPU at the I/O boundary while completing the write, so saved state
    starts at the instruction immediately after `out`;

guest/common/nvx-snapshot

@@ -87,8 +87,23 @@ cmdline_value() {
     return 1
 }
 
+workload_identity_marker=$runtime/runtime-workload-identity
+
+# A guest runtime that runs several independent workloads creates this regular
+# file before capture. Its post-restore hook then refreshes every workload's
+# identity, so no single workload process or machine ID is published.
+workload_identity_owner() {
+    if [ ! -e "$workload_identity_marker" ] && [ ! -L "$workload_identity_marker" ]; then
+        printf 'single\n'
+    elif [ -f "$workload_identity_marker" ] && [ ! -L "$workload_identity_marker" ]; then
+        printf 'runtime\n'
+    else
+        return 1
+    fi
+}
+
 workload_identity_required() {
-    [ "$image_format" != flat-ext4 ]
+    [ "$image_format" != flat-ext4 ] && [ "$identity_owner" != runtime ]
 }
 
 read_port_byte() {
@@ -435,6 +450,8 @@ post_restore() {
 
     if [ "$snapshot_tier" != instance-checkpoint ]; then
         console_status "NVX-POST-RESTORE-STAGE: identity"
+        identity_owner=$(workload_identity_owner) ||
+            fail_closed "runtime workload identity marker is invalid"
         machine_id=$(sha256sum "$entropy" | cut -c1-32)
         printf '%s\n' "$machine_id" >/etc/machine-id ||
             fail_closed "failed to refresh machine identity"
@@ -450,7 +467,10 @@ post_restore() {
         hostname_value=$(cmdline_value nvx_hostname || true)
         [ -n "$hostname_value" ] || hostname_value=nvx-sandbox
         hostname "$hostname_value" || fail_closed "failed to refresh hostname"
-        if [ -s "$workload_pid_file" ]; then
+        if [ "$identity_owner" = runtime ]; then
+            # Each workload keeps its own hostname; the runtime hook owns refresh.
+            :
+        elif [ -s "$workload_pid_file" ]; then
             IFS= read -r workload_pid <"$workload_pid_file"
             case "$workload_pid" in
                 '' | *[!0-9]*) fail_closed "workload PID is invalid" ;;
@@ -498,6 +518,11 @@ if [ "$snapshot_tier" = workload-start ] &&
     exit 1
 fi
 
+if ! workload_identity_owner >/dev/null; then
+    echo "nvx-snapshot: runtime workload identity marker is invalid" >&2
+    exit 1
+fi
+
 if [ "$has_scratch" = true ]; then
     if [ "$scratch_policy" = paired ] && [ "$scratch_mounted" = false ]; then
         echo "nvx-snapshot: paired capture requires mounted scratch" >&2

scripts/test_microvm_tests.py

@@ -1469,15 +1469,16 @@ def test_filesystem_only_clone_does_not_require_a_workload_process(self):
             snapshot.count("workload_identity_required; then"),
             2,
         )
-        for image_format, outcome in (
-            ("", "required"),
-            ("flat-ext4", "optional"),
+        for image_format, identity_owner, outcome in (
+            ("", "single", "required"),
+            ("flat-ext4", "single", "optional"),
+            ("", "runtime", "optional"),
         ):
             result = subprocess.run(
                 [shell, "-c",
-                 "set -eu\nimage_format=$1\n" + required
+                 "set -eu\nimage_format=$1\nidentity_owner=$2\n" + required
                  + "\nif workload_identity_required; then echo required; else echo optional; fi",
-                 "_", image_format],
+                 "_", image_format, identity_owner],
                 text=True,
                 capture_output=True,
                 timeout=5,
@@ -1486,6 +1487,59 @@ def test_filesystem_only_clone_does_not_require_a_workload_process(self):
             self.assertEqual(result.returncode, 0, result.stderr)
             self.assertEqual(result.stdout.strip(), outcome)
 
+    def test_runtime_owned_workload_identity_marker_is_a_regular_file(self):
+        if sys.platform == "win32":
+            self.skipTest("native POSIX guest helper test requires Linux")
+        shell = _posix_shell()
+        if shell is None:
+            self.skipTest("POSIX shell is unavailable")
+        snapshot = (
+            Path(__file__).parents[1] / "guest" / "common" / "nvx-snapshot"
+        ).read_text(encoding="utf-8")
+        begin = snapshot.index("workload_identity_owner() {")
+        end = snapshot.index("\n}\n", begin) + 2
+        owner = snapshot[begin:end]
+        capture_check = snapshot.index("if ! workload_identity_owner >/dev/null; then")
+        freeze = snapshot.index('echo 1 >"$container_cgroup/cgroup.freeze"')
+        self.assertLess(capture_check, freeze)
+        restore_check = snapshot.index(
+            'fail_closed "runtime workload identity marker is invalid"'
+        )
+        hostname_reset = snapshot.index('nsenter -t "$workload_pid" -u hostname')
+        self.assertLess(restore_check, hostname_reset)
+        self.assertIn('if [ "$identity_owner" = runtime ]; then', snapshot)
+
+        with tempfile.TemporaryDirectory() as directory:
+            marker = Path(directory) / "runtime-workload-identity"
+
+            def resolve() -> subprocess.CompletedProcess[str]:
+                return subprocess.run(
+                    [shell, "-c",
+                     "set -eu\nworkload_identity_marker=$1\n" + owner
+                     + "\nworkload_identity_owner",
+                     "_", str(marker)],
+                    text=True,
+                    capture_output=True,
+                    timeout=5,
+                    check=False,
+                )
+
+            result = resolve()
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertEqual(result.stdout.strip(), "single")
+            marker.write_bytes(b"")
+            result = resolve()
+            self.assertEqual(result.returncode, 0, result.stderr)
+            self.assertEqual(result.stdout.strip(), "runtime")
+            marker.unlink()
+            marker.mkdir()
+            self.assertNotEqual(resolve().returncode, 0)
+            marker.rmdir()
+            target = Path(directory) / "target"
+            target.write_bytes(b"")
+            marker.symlink_to(target)
+            self.assertNotEqual(resolve().returncode, 0)
+
     def test_snapshot_console_diagnostics_are_nonfatal_and_ordered(self):
         shell = _posix_shell()
         if shell is None: