feat(mount): support image-subpath for --mount type=image

Add the image-subpath option to --mount type=image, exposing a single
directory of the image rootfs at the destination instead of the whole
rootfs.

An OCI overlay mount cannot select a subdirectory, so a subpath mount
materializes the read-only view on a host directory under the data root,
resolves the subpath with securejoin (blocking absolute paths and
parent traversal, including via symlinks), and bind-mounts the resolved
directory read-only into the container. The host materialization path is
recorded on a container label and unmounted and removed on container
deletion, alongside the snapshot view.

The whole-rootfs path is unchanged: it still hands the snapshotter mount
straight to the runtime, which owns its lifecycle.

Signed-off-by: Mayur Das <mayur.das@neevcloud.com>

Author: mayur-tolexo

cmd/nerdctl/container/container_run_mount_image_linux_test.go

@@ -93,9 +93,76 @@ func TestRunMountTypeImageReadOnly(t *testing.T) {
 	testCase.Run(t)
 }
 
+// TestRunMountTypeImageSubpath verifies that image-subpath exposes only the
+// selected directory of the image rootfs at the destination: the image's
+// /etc/os-release is reachable as <destination>/os-release.
+func TestRunMountTypeImageSubpath(t *testing.T) {
+	testCase := nerdtest.Setup()
+
+	testCase.Command = func(data test.Data, helpers test.Helpers) test.TestableCommand {
+		return helpers.Command("run", "--rm",
+			"--mount", fmt.Sprintf("type=image,source=%s,destination=/mnt/img,image-subpath=etc", testutil.CommonImage),
+			testutil.CommonImage, "cat", "/mnt/img/os-release")
+	}
+
+	testCase.Expected = func(data test.Data, helpers test.Helpers) *test.Expected {
+		return &test.Expected{
+			ExitCode: expect.ExitCodeSuccess,
+			Output:   expect.Contains("Alpine"),
+		}
+	}
+
+	testCase.Run(t)
+}
+
+// TestRunMountTypeImageSubpathMultiple verifies that two image-subpath mounts of
+// the same image at different destinations each expose their own subdirectory,
+// exercising the multi-mount label round-trip and cleanup.
+func TestRunMountTypeImageSubpathMultiple(t *testing.T) {
+	testCase := nerdtest.Setup()
+
+	testCase.Command = func(data test.Data, helpers test.Helpers) test.TestableCommand {
+		return helpers.Command("run", "--rm",
+			"--mount", fmt.Sprintf("type=image,source=%s,destination=/mnt/etc,image-subpath=etc", testutil.CommonImage),
+			"--mount", fmt.Sprintf("type=image,source=%s,destination=/mnt/bin,image-subpath=bin", testutil.CommonImage),
+			testutil.CommonImage, "ls", "/mnt/etc", "/mnt/bin")
+	}
+
+	testCase.Expected = func(data test.Data, helpers test.Helpers) *test.Expected {
+		return &test.Expected{
+			ExitCode: expect.ExitCodeSuccess,
+		}
+	}
+
+	testCase.Run(t)
+}
+
+// TestRunMountTypeImageSubpathReadOnly verifies that an image-subpath mount is
+// read-only. nerdctl-only: Docker mounts images read-write by default.
+func TestRunMountTypeImageSubpathReadOnly(t *testing.T) {
+	testCase := nerdtest.Setup()
+	testCase.Require = require.Not(nerdtest.Docker)
+
+	testCase.Command = func(data test.Data, helpers test.Helpers) test.TestableCommand {
+		return helpers.Command("run", "--rm",
+			"--mount", fmt.Sprintf("type=image,source=%s,destination=/mnt/img,image-subpath=etc", testutil.CommonImage),
+			testutil.CommonImage, "touch", "/mnt/img/should-fail")
+	}
+
+	testCase.Expected = func(data test.Data, helpers test.Helpers) *test.Expected {
+		return &test.Expected{
+			ExitCode: expect.ExitCodeGenericFail,
+			Errors:   []error{fmt.Errorf("Read-only file system")},
+		}
+	}
+
+	testCase.Run(t)
+}
+
 // TestRunMountTypeImageErrors verifies that an image mount missing its source,
-// or using the not-yet-supported subpath option, is rejected. subpath is
-// nerdctl-specific behaviour here, so the test is not run against Docker.
+// or using the not-yet-supported subpath option, or an image-subpath that
+// escapes the rootfs, is rejected. These are nerdctl-specific behaviours here,
+// so the test is not run against Docker.
 func TestRunMountTypeImageErrors(t *testing.T) {
 	testCase := nerdtest.Setup()
 	testCase.Require = require.Not(nerdtest.Docker)
@@ -128,6 +195,34 @@ func TestRunMountTypeImageErrors(t *testing.T) {
 				}
 			},
 		},
+		{
+			Description: "image-subpath parent traversal rejected",
+			Command: func(data test.Data, helpers test.Helpers) test.TestableCommand {
+				return helpers.Command("run", "--rm",
+					"--mount", fmt.Sprintf("type=image,source=%s,destination=/mnt/img,image-subpath=../etc", testutil.CommonImage),
+					testutil.CommonImage, "true")
+			},
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: expect.ExitCodeGenericFail,
+					Errors:   []error{fmt.Errorf("escapes")},
+				}
+			},
+		},
+		{
+			Description: "image-subpath absolute rejected",
+			Command: func(data test.Data, helpers test.Helpers) test.TestableCommand {
+				return helpers.Command("run", "--rm",
+					"--mount", fmt.Sprintf("type=image,source=%s,destination=/mnt/img,image-subpath=/etc", testutil.CommonImage),
+					testutil.CommonImage, "true")
+			},
+			Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+				return &test.Expected{
+					ExitCode: expect.ExitCodeGenericFail,
+					Errors:   []error{fmt.Errorf("relative")},
+				}
+			},
+		},
 	}
 
 	testCase.Run(t)

docs/command-reference.md

@@ -314,7 +314,7 @@ Volume flags:
     - unimplemented options: `volume-nocopy`, `volume-label`, `volume-driver`, `volume-opt`
   - Options specific to `image`:
     - :whale: `src`, `source`: image reference (mandatory). The image filesystem is mounted read-only.
-    - unimplemented options: `subpath`
+    - :whale: `image-subpath`: relative path inside the image rootfs to mount instead of the whole rootfs. Must stay within the rootfs (no absolute paths or `..` traversal).
 - :whale: `--volumes-from`: Mount volumes from the specified container(s), e.g. "--volumes-from my-container".
 
 Rootfs flags:

pkg/cmd/container/create.go

@@ -94,20 +94,24 @@ func Create(ctx context.Context, client *containerd.Client, args []string, netMa
 	internalLabels.platform = options.Platform
 	internalLabels.namespace = options.GOptions.Namespace
 
-	// If creation fails after image-mount views are created, remove them so the
-	// snapshots do not leak (the cleanup label is only persisted on success).
+	// If creation fails after image-mount state is created, tear it down so the
+	// snapshots and host mounts do not leak (the cleanup labels are only persisted
+	// on success).
 	defer func() {
 		if retErr == nil {
 			return
 		}
-		var keys []string
+		var keys, hostpaths []string
 		for _, mp := range internalLabels.mountPoints {
 			if mp.ImageMountSnapshot != "" {
 				keys = append(keys, mp.ImageMountSnapshot)
 			}
+			if mp.ImageMountHostpath != "" {
+				hostpaths = append(hostpaths, mp.ImageMountHostpath)
+			}
 		}
-		if len(keys) > 0 {
-			removeImageMountViews(ctx, client.SnapshotService(options.GOptions.Snapshotter), keys)
+		if len(keys) > 0 || len(hostpaths) > 0 {
+			removeImageMounts(ctx, client.SnapshotService(options.GOptions.Snapshotter), hostpaths, keys)
 		}
 	}()
 
@@ -823,13 +827,16 @@ func withInternalLabels(internalLabels internalLabels) (containerd.NewContainerO
 		m[labels.AnonymousVolumes] = string(anonVolumeJSON)
 	}
 
-	// Record the snapshot keys of any type=image mount views so they can be
-	// removed when the container is deleted.
-	var imageMountSnapshots []string
+	// Record the snapshot keys and host materialization paths of any type=image
+	// mounts so they can be removed when the container is deleted.
+	var imageMountSnapshots, imageMountHostpaths []string
 	for _, mp := range internalLabels.mountPoints {
 		if mp.ImageMountSnapshot != "" {
 			imageMountSnapshots = append(imageMountSnapshots, mp.ImageMountSnapshot)
 		}
+		if mp.ImageMountHostpath != "" {
+			imageMountHostpaths = append(imageMountHostpaths, mp.ImageMountHostpath)
+		}
 	}
 	if len(imageMountSnapshots) > 0 {
 		b, err := json.Marshal(imageMountSnapshots)
@@ -838,6 +845,13 @@ func withInternalLabels(internalLabels internalLabels) (containerd.NewContainerO
 		}
 		m[labels.ImageMountSnapshots] = string(b)
 	}
+	if len(imageMountHostpaths) > 0 {
+		b, err := json.Marshal(imageMountHostpaths)
+		if err != nil {
+			return nil, err
+		}
+		m[labels.ImageMountHostpaths] = string(b)
+	}
 
 	if internalLabels.pidFile != "" {
 		m[labels.PIDFile] = internalLabels.pidFile

pkg/cmd/container/remove.go

@@ -283,15 +283,22 @@ func RemoveContainer(ctx context.Context, c containerd.Container, globalOptions
 			}
 		}
 
-		// Remove the read-only views backing type=image mounts - soft failure.
+		// Tear down type=image mount state (host materializations and read-only
+		// views) backing this container - soft failure.
+		var imageMountKeys, imageMountHostpaths []string
 		if snapshotsJSON, ok := containerLabels[labels.ImageMountSnapshots]; ok {
-			var keys []string
-			if err = json.Unmarshal([]byte(snapshotsJSON), &keys); err != nil {
+			if err = json.Unmarshal([]byte(snapshotsJSON), &imageMountKeys); err != nil {
 				log.G(ctx).WithError(err).Warnf("failed to unmarshal image-mount snapshots for container %q", id)
-			} else {
-				removeImageMountViews(ctx, client.SnapshotService(imageMountSnapshotter), keys)
 			}
 		}
+		if hostpathsJSON, ok := containerLabels[labels.ImageMountHostpaths]; ok {
+			if err = json.Unmarshal([]byte(hostpathsJSON), &imageMountHostpaths); err != nil {
+				log.G(ctx).WithError(err).Warnf("failed to unmarshal image-mount host paths for container %q", id)
+			}
+		}
+		if len(imageMountKeys) > 0 || len(imageMountHostpaths) > 0 {
+			removeImageMounts(ctx, client.SnapshotService(imageMountSnapshotter), imageMountHostpaths, imageMountKeys)
+		}
 	}()
 
 	// Get the task.