feat(mount): support --mount type=image with image-subpath by mayur-tolexo · Pull Request #4993 · containerd/nerdctl

mayur-tolexo · 2026-06-22T16:44:21Z

What

Implements --mount type=image end-to-end, matching Docker's --mount type=image (moby/moby#48798), including the image-subpath option.

Part of #3867. Builds on #4990 (read-only whole-rootfs image mount); this squashes that MVP and the image-subpath work into a single commit.

--mount type=image,source=<image>,destination=<path>: mounts the image rootfs read-only at the destination.
--mount type=image,source=<image>,destination=<path>,image-subpath=<rel/path>: mounts only a subdirectory of the image rootfs.

Image mounts are read-only, matching Docker (verified against Docker 29.6.2: writes return Read-only file system).

How

Parser (pkg/mountutil): accepts image-subpath and normalizes it. Internal .. is collapsed (a/../b → b); an absolute path or a .. that escapes the rootfs is rejected; a value that normalizes to the rootfs itself (., or a/..) mounts the whole rootfs, which is what Docker does. Presence is tracked separately from the value, so an explicit empty image-subpath= is rejected rather than silently read as "unset", and image-subpath is rejected on any type other than image.
Whole-rootfs (no subpath): hands the snapshotter's read-only view straight to the OCI runtime, which owns the mount lifecycle. Unchanged from feat(mount): support --mount type=image #4990.
Subpath: an OCI overlay mount cannot select a subdirectory, so the read-only view is materialized on a host directory under the data root, and a read-only bind mount of the resolved subdirectory is added. The subpath is resolved with securejoin (so the bind source has its symlinks resolved, because mount(2) resolves the source against the host root) and then re-checked with os.OpenInRoot, the kernel's scoped lookup, which confirms the target exists and rejects absolute symlinks and escapes. The host materialization path is recorded on a container label and unmounted/removed on nerdctl rm, alongside the snapshot view.
Reserved labels: labels in the internal nerdctl/ namespace are now stripped from an image's config labels. --label already rejects that prefix, but image config labels bypassed it, which would let an image forge internal container state — including the image-mount host paths that nerdctl rm unmounts and deletes.

Not included (parity notes vs moby#48798)

Read-write image mounts: Docker presents image mounts read-only in practice, so this matches.
Daemon-restart layer restoration / image-layer refcounting: daemon-specific. nerdctl is daemonless; the snapshot view is protected from GC via a gc.root label. A subpath mount's host materialization persists across container restart but not across a host reboot.

Test

Unit: pkg/mountutil parser cases (subpath normalization, escaping-traversal / absolute / empty / non-image rejection, root-normalizing → whole rootfs).
Integration: cmd/nerdctl/container/container_run_mount_image_linux_test.go (subpath exposure, multiple subpaths, read-only, absolute-symlink rejection, safe relative-symlink resolution, error cases).
Manual e2e against Docker 29.6.2 — logs posted in a comment below.

mayur-tolexo · 2026-06-22T16:44:51Z

Did another round of manual testing against Docker 29.4.0 (nerdctl built from this branch) to check parity. Sharing the results.

Whole-rootfs and subpath read the same as Docker

$ nerdctl run --rm --mount type=image,source=alpine:latest,destination=/mnt/img alpine cat /mnt/img/etc/alpine-release
3.24.1
$ docker run --rm --mount type=image,source=alpine:latest,destination=/mnt/img alpine cat /mnt/img/etc/alpine-release
WARNING: Image mount is an experimental feature
3.24.1

$ nerdctl run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,image-subpath=etc alpine cat /mnt/img/alpine-release
3.24.1
$ docker run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,image-subpath=etc alpine cat /mnt/img/alpine-release
WARNING: Image mount is an experimental feature
3.24.1

Writes are rejected on both (read-only):

$ nerdctl run --rm --mount type=image,source=alpine:latest,destination=/mnt/img alpine touch /mnt/img/x
touch: /mnt/img/x: Read-only file system
$ docker run --rm --mount type=image,source=alpine:latest,destination=/mnt/img alpine touch /mnt/img/x
WARNING: Image mount is an experimental feature
touch: /mnt/img/x: Read-only file system

Bad mount specs are rejected, same as Docker

nerdctl:

$ nerdctl run --rm --mount type=image,destination=/mnt/img alpine true
time="2026-07-21T08:16:29Z" level=fatal msg="type=image requires a source (the image reference)"
$ nerdctl run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,subpath=etc alpine true
time="2026-07-21T08:16:29Z" level=fatal msg="unexpected key 'subpath' in 'subpath=etc'"
$ nerdctl run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,image-subpath=../etc alpine true
time="2026-07-21T08:16:29Z" level=fatal msg="image-subpath \"../etc\" escapes the image rootfs"
$ nerdctl run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,image-subpath=/etc alpine true
time="2026-07-21T08:16:29Z" level=fatal msg="image-subpath must be relative to the image rootfs, got \"/etc\""
$ nerdctl run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,image-subpath=nope alpine true
time="2026-07-21T08:16:29Z" level=fatal msg="image-subpath \"nope\" does not exist in image \"alpine:latest\""
$ nerdctl run --rm --mount type=bind,source=/tmp,destination=/mnt,image-subpath=etc alpine true
time="2026-07-21T08:16:29Z" level=fatal msg="image-subpath is only supported for type=image"

Docker on the same specs:

$ docker run --rm --mount type=image,destination=/mnt/img alpine true
docker: Error response from daemon: invalid mount config for type "image": field Source must not be empty
$ docker run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,subpath=etc alpine true
invalid argument "type=image,source=alpine:latest,destination=/mnt/img,subpath=etc" for "--mount" flag: unknown option 'subpath' in 'subpath=etc'
$ docker run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,image-subpath=../etc alpine true
docker: Error response from daemon: invalid mount config for type "image": subpath must be a relative path within the volume
$ docker run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,image-subpath=/etc alpine true
docker: Error response from daemon: invalid mount config for type "image": subpath must be a relative path within the volume
$ docker run --rm --mount type=image,source=alpine:latest,destination=/mnt/img,image-subpath=nope alpine true
docker: Error response from daemon: cannot access path /var/lib/docker/rootfs/overlayfs/b59a45207c4d.../nope: lstat ...: no such file or directory
$ docker run --rm --mount type=bind,source=/tmp,destination=/mnt,image-subpath=etc alpine true
invalid argument "..." for "--mount" flag: cannot mix 'image-*' options with mount type 'bind'

How the subpath mount is wired

nerdctl is daemonless, so for a subpath it materializes the image rootfs on the host (read-only) and bind-mounts the subdir into the container. For a container started with image-subpath=etc:

$ grep image-mounts /proc/mounts
/dev/vda1 /var/lib/nerdctl/image-mounts/8b71320c4cd1215df46c5a7da54744badbe10192ad2801d95d7a11494d9bb918-image-mount ext4 ro,relatime,discard 0 0

The OCI mount injected for /mnt/img (from the runtime config.json):

{
  "destination": "/mnt/img",
  "type": "bind",
  "source": "/var/lib/nerdctl/image-mounts/8b71320c4cd1215df46c5a7da54744badbe10192ad2801d95d7a11494d9bb918-image-mount/etc",
  "options": ["rbind", "ro"]
}

And inside the container:

$ grep ' /mnt/img ' /proc/<pid>/mountinfo
1969 1959 254:1 /docker/volumes/nerdctl-cd-data/_data/io.containerd.snapshotter.v1.overlayfs/snapshots/1/fs/etc /mnt/img ro,relatime master:1 - ext4 /dev/vda1 rw,discard

The snapshot view and host path are recorded on the container so they can be cleaned up on removal:

$ nerdctl inspect imgtest --format '{{json .Config.Labels}}' | tr ',' '\n' | grep image-mount
"nerdctl/image-mount-hostpaths":"[\"/var/lib/nerdctl/image-mounts/8b71320c4cd1215df46c5a7da54744badbe10192ad2801d95d7a11494d9bb918-image-mount\"]"
"nerdctl/image-mount-snapshots":"[\"8b71320c4cd1215df46c5a7da54744badbe10192ad2801d95d7a11494d9bb918-image-mount\"]"

On nerdctl rm both are torn down. With two subpath mounts:

$ grep -c image-mounts /proc/mounts   # while running
2
$ grep -c image-mounts /proc/mounts   # after stop + rm
0

One difference from Docker

rmi of an image used only as a mount source (not the container's base image) succeeds in nerdctl, and the running mount keeps working because the snapshot view is gc-rooted. Docker refuses unless forced. Not a safety issue, just a behavioral difference worth noting.

$ nerdctl rmi busybox:latest   # while a mount-only container runs
Untagged: docker.io/library/busybox:latest@sha256:fd8d9aa63ba2...
Deleted: sha256:66cb17eae60e...
$ nerdctl exec mntonly ls /mnt/bb/bin/busybox
/mnt/bb/bin/busybox

$ docker rmi busybox:latest   # while a mount-only container runs
Error response from daemon: conflict: unable to delete busybox:latest (must be forced) - container bf6231dbb625 is using its referenced image fd8d9aa63ba2

AkihiroSuda · 2026-06-22T17:39:11Z

This builds on #4990 (the first commit here is that MVP: read-only whole-rootfs image mount). The second commit adds image-subpath, completing the feature.

I only see a single commit

AkihiroSuda · 2026-06-22T17:39:48Z

If this PR is expected to be merged after #4990, please click Convert to draft

AkihiroSuda · 2026-07-20T08:05:19Z

Is this still a draft?

mayur-tolexo · 2026-07-23T05:22:24Z

Is this still a draft?

Yeah its ready for review.

jiwahn · 2026-08-01T03:41:49Z

I think images used by existing containers as image mounts should not be removed by rmi

jiwahn · 2026-08-01T03:49:24Z

+	// "." means the whole rootfs (e.g. from "a/.."); that is the no-subpath case,
+	// not a subdirectory selection, so reject it as a misuse of image-subpath.
+	if clean == "." {
+		return "", fmt.Errorf("image-subpath %q must select a subdirectory, not the image rootfs", p)
+	}


nit, but docker accepts this.

Good catch, fixed. A subpath that resolves to the rootfs (., or anything normalizing to it like a/..) now returns empty and mounts the whole image view like Docker, instead of erroring. Updated the two tests to match.

mayur-tolexo · 2026-08-04T12:31:41Z

Agreed it shouldn't be silently removable. The view is already pinned with a containerd.io/gc.root label on the snapshot, which is independent of the image record, so rmi can't pull the layers out from under a running or stopped container — the mount keeps working. What's missing is Docker's up-front rmi conflict ("image is being used by container"), which needs the mount's image ref recorded on the container and checked in rmi. That's rmi-side refcounting, separate from the mount feature this PR targets, so I'd rather track it as a follow-up than widen this PR. Happy to open an issue for it.

Copilot

Pull request overview

Adds image-subpath support for read-only image mounts, including secure resolution, persistent host materialization, cleanup, and tests.

Changes:

Parses and validates image subpaths.
Materializes subpath mounts and records cleanup metadata.
Adds documentation and unit/integration coverage.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
`pkg/mountutil/mountutil.go`	Adds image-subpath metadata fields.
`pkg/mountutil/mountutil_linux.go`	Parses and validates `image-subpath`.
`pkg/mountutil/mountutil_linux_test.go`	Tests parser behavior.
`pkg/labels/labels.go`	Defines the host-path cleanup label.
`pkg/cmd/container/run_mount.go`	Creates and cleans subpath mounts.
`pkg/cmd/container/remove.go`	Cleans image mount state on removal.
`pkg/cmd/container/create.go`	Persists and cleans mount metadata.
`docs/command-reference.md`	Documents `image-subpath`.
`cmd/nerdctl/container/container_run_mount_image_linux_test.go`	Adds integration coverage.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

+	if len(imageMountHostpaths) > 0 {
+		b, err := json.Marshal(imageMountHostpaths)
+		if err != nil {
+			return nil, err
+		}
+		m[labels.ImageMountHostpaths] = string(b)
+	}


+	// "." is the whole rootfs (e.g. from "a/.."); treat it as no subpath so the
+	// caller mounts the full image view, matching Docker.
+	if clean == "." {
+		return "", nil


+	if imageSubpath != "" && mountType != Image {
+		return nil, fmt.Errorf("image-subpath is only supported for type=image")


djdongjin · 2026-08-20T06:29:07Z

+// itself (empty, or one normalizing to ".", e.g. "a/..") returns empty, the
+// no-subpath case Docker also accepts. Image paths are always forward-slash, so
+// it uses path, not filepath.
+func validateImageSubpath(p string) (string, error) {


we can use os.OpenInRoot to make sure the subpath isn't escaped from the rootfs host path.

ref: image volume support in containerd cri

https://github.com/containerd/containerd/blob/f7302c343cfed1d4b773082272dd4ca884217e79/internal/cri/server/container_image_mount.go#L247

Done — resolveImageSubpath now re-checks with os.OpenInRoot after securejoin, so the scoped kernel lookup confirms existence and rejects absolute symlinks/escapes. Verified an absolute in-image symlink (bin/sh -> /bin/busybox) is rejected while a safe relative one (var/run -> ../run) resolves within the image; both match Docker. Thanks for the pointer.

Mount an image's filesystem into a container read-only, matching Docker: --mount type=image,source=<image>,destination=<path>. The source image is ensured and unpacked, a read-only snapshot view of its rootfs is created and mounted at the destination, and the view is removed when the container is deleted. The image-subpath option exposes 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, 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 subpath is normalized and bounded to the rootfs at parse time (rejecting absolute paths and traversal that escapes), then resolved against the materialized rootfs with securejoin so the bind source has its symlinks already resolved: mount(2) resolves the source against the host root, so an unresolved path would let a symlink in the image bind the host's copy of the target. os.OpenInRoot then confirms through the kernel that the subpath exists and rejects absolute symlinks and escapes. Docker rejects those same subpaths. The whole-rootfs path hands the snapshotter mount straight to the runtime, which owns its lifecycle. Labels in the reserved nerdctl/ namespace are stripped from an image's config labels. --label already rejects that prefix, but image config labels bypassed it, which would let an image forge internal container state - including the image-mount host paths that nerdctl rm unmounts and deletes. Mounting the same image at multiple destinations is supported; the corresponding tests are skipped on Docker, which rejects mounting the same image more than once. Signed-off-by: Mayur Das <mayur.das@neevcloud.com>

mayur-tolexo mentioned this pull request Jun 22, 2026

feat(mount): support --mount type=image #4990

Merged

mayur-tolexo force-pushed the feat/mount-type-image-full branch from 18a55fe to 870f56c Compare June 22, 2026 17:13

mayur-tolexo marked this pull request as draft June 22, 2026 18:28

AkihiroSuda mentioned this pull request Jun 24, 2026

Update the list of the unimplemented Docker features (and implement them) #3867

Open

7 tasks

mayur-tolexo force-pushed the feat/mount-type-image-full branch 2 times, most recently from b86abb8 to 7ee3b50 Compare July 19, 2026 06:37

mayur-tolexo marked this pull request as ready for review July 21, 2026 08:34

AkihiroSuda added this to the v2.4.0 milestone Jul 29, 2026

jiwahn reviewed Aug 1, 2026

View reviewed changes

mayur-tolexo force-pushed the feat/mount-type-image-full branch from 7ee3b50 to 35e7a07 Compare August 4, 2026 12:27

papidb mentioned this pull request Aug 17, 2026

Feature request: Add necessary support for new functionality(introduce volume.type=image) from compose-spec #4767

Open

AkihiroSuda requested a balanced review from Copilot August 20, 2026 05:39

Copilot started reviewing on behalf of AkihiroSuda August 20, 2026 05:40 View session

Copilot AI reviewed Aug 20, 2026

View reviewed changes

djdongjin reviewed Aug 20, 2026

View reviewed changes

papidb mentioned this pull request Aug 25, 2026

feat: support compose image volumes #5161

Open

mayur-tolexo force-pushed the feat/mount-type-image-full branch from 35e7a07 to f0a1e41 Compare August 25, 2026 14:26

Navigation Menu

Uh oh!

feat(mount): support --mount type=image with image-subpath - #4993

feat(mount): support --mount type=image with image-subpath#4993
mayur-tolexo wants to merge 1 commit into
containerd:mainfrom
mayur-tolexo:feat/mount-type-image-full

mayur-tolexo commented Jun 22, 2026 •

edited

Loading

Uh oh!

mayur-tolexo commented Jun 22, 2026 •

edited

Loading

Uh oh!

AkihiroSuda commented Jun 22, 2026

Uh oh!

AkihiroSuda commented Jun 22, 2026

Uh oh!

AkihiroSuda commented Jul 20, 2026

Uh oh!

mayur-tolexo commented Jul 23, 2026

Uh oh!

jiwahn commented Aug 1, 2026

Uh oh!

jiwahn Aug 1, 2026

Uh oh!

mayur-tolexo Aug 4, 2026

Uh oh!

mayur-tolexo commented Aug 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

djdongjin Aug 20, 2026

Uh oh!

mayur-tolexo Aug 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

		if imageSubpath != "" && mountType != Image {
		return nil, fmt.Errorf("image-subpath is only supported for type=image")

Uh oh!

Conversation

mayur-tolexo commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

How

Not included (parity notes vs moby#48798)

Test

Uh oh!

mayur-tolexo commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Whole-rootfs and subpath read the same as Docker

Bad mount specs are rejected, same as Docker

How the subpath mount is wired

One difference from Docker

Uh oh!

AkihiroSuda commented Jun 22, 2026

Uh oh!

AkihiroSuda commented Jun 22, 2026

Uh oh!

AkihiroSuda commented Jul 20, 2026

Uh oh!

mayur-tolexo commented Jul 23, 2026

Uh oh!

jiwahn commented Aug 1, 2026

Uh oh!

jiwahn Aug 1, 2026

Choose a reason for hiding this comment

Uh oh!

mayur-tolexo Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

mayur-tolexo commented Aug 4, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

djdongjin Aug 20, 2026

Choose a reason for hiding this comment

Uh oh!

mayur-tolexo Aug 25, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

mayur-tolexo commented Jun 22, 2026 •

edited

Loading

mayur-tolexo commented Jun 22, 2026 •

edited

Loading