Refactor image management to use transfer service #4583

ChengyuZhu6 · 2025-11-05T15:36:40Z

Fixes: #4573

cmd/nerdctl/image/image_import.go

ChengyuZhu6 · 2025-11-25T12:08:45Z

Most image management operations now use the transfer service:

Standard image pull/push operations
Multi-platform image handling
Progress reporting and streaming
Basic registry authentication
Image import/export (load/save)

Limitations

Due to current transfer API constraints, the following features continue to use the legacy implementation:

1. IPFS Registry and Nondistributable Artifacts

Reason: The transfer service API does not support custom registry resolver implementations.

Affected features:

IPFS registry functionality (ipfs:// protocol)
Nondistributable artifact handling (e.g., Windows base layers)

Status: These features remain on the legacy resolver-based approach until the transfer API supports custom resolvers.

2. Containerd 1.7.x Compatibility Issue

Issue: When using containerd 1.7.x daemons, registry options like WithDefaultScheme("http") and WithHostDir() are silently ignored.

Technical details:

nerdctl uses containerd v2.2 client library which supports these options
Options are properly serialized into protobuf messages
However, containerd 1.7.x's UnmarshalAny() implementation doesn't process these fields
Only authorizer and headers are handled in 1.7.x

Impact:

Localhost registry operations may fail with: "http: server gave HTTP response to HTTPS client"
Custom hosts.toml configurations are not applied on 1.7.x

ChengyuZhu6 · 2025-11-25T12:15:25Z

For limitation 2, there are two potential solutions:

Implement containerd version detection in nerdctl to use different code paths;
Backport to containerd 1.7.x

For limitation 1, there are two potential solutions:

IPFS Registry and Nondistributable Artifacts remain on the legacy resolver-based approach.
containerd transfer API supports custom resolvers

ChengyuZhu6 · 2025-11-25T12:15:41Z

@AkihiroSuda @ktock

AkihiroSuda · 2025-11-26T00:45:27Z

Thanks @ChengyuZhu6

For limitation 2, there are two potential solutions:

Implement containerd version detection in nerdctl to use different code paths;

Backport to containerd 1.7.x

For limitation 1, there are two potential solutions:

IPFS Registry and Nondistributable Artifacts remain on the legacy resolver-based approach.

containerd transfer API supports custom resolvers

2 in the long term, 1 in the short term

Switch image operations to the transfer API with structured progress reporting and improved TLS/HTTP fallback behavior. Introduce shared helpers for credentials, error classification, progress rendering, and transfer-based import/tag/save flows, updating tests to reflect the new UX. Signed-off-by: ChengyuZhu6 <hudson@cyzhu.com>

Add remote snapshot annotations and transfer unpack config for stargz, soci, and fuse-overlayfs snapshotter plugins. Signed-off-by: ChengyuZhu6 <hudson@cyzhu.com>

Add version detection to automatically select Transfer service (2.0+) or legacy resolver methods (< 2.0) for better compatibility. Signed-off-by: ChengyuZhu6 <hudson@cyzhu.com>

AkihiroSuda · 2025-11-28T07:05:40Z

Dockerfile.d/etc_containerd_config.toml

+    enable_remote_snapshot_annotations = "true"
+[[plugins."io.containerd.transfer.v1.local".unpack_config]]
+  platform = "linux"
+  snapshotter = "overlayfs"


What happens if this config is not specified?
i.e., what happens with the default config?

By default, it would be

[[plugins."io.containerd.transfer.v1.local".unpack_config]] platform = "linux/amd64"(matches the host's OS/Architecture) snapshotter = "overlayfs" differ = "walking"

AkihiroSuda · 2025-11-28T07:06:56Z

pkg/transferutil/progress.go

+	"github.com/containerd/containerd/v2/pkg/progress"
+)
+
+// From https://github.com/containerd/containerd/blob/v2.2.0-rc.0/cmd/ctr/commands/image/pull.go#L240-L473


Can't we import the package from containerd/containerd to reduce code clones?

The progress handling code is in cmd/ctr/commands/images, not in pkg/ or core/, so it cannot be imported directly.
And I removed displayName() function that splits names by '-':

func displayName(name string) string { parts := strings.Split(name, "-") for i := range parts { parts[i] = shortenName(parts[i]) } return strings.Join(parts, " ") }

which would break display for image names containing - (e.g., ubuntu-base )

pkg/infoutil/infoutil.go

AkihiroSuda · 2025-11-28T07:22:46Z

pkg/containerdutil/version.go

+}
+
+// SupportsFullTransferService checks if the containerd version fully supports the Transfer service.
+// While containerd 1.7 has Transfer service, full support is only available in 2.0+.


Suggested change

// While containerd 1.7 has Transfer service, full support is only available in 2.0+.

// While containerd 1.7 has Transfer service, full support is only available in 2.0+.

// The following features are missing in containerd 1.7:

// - [ADD MISSING FEATURES]

AkihiroSuda · 2025-11-28T07:23:54Z

extras/rootless/containerd-rootless-setuptool.sh

+			snapshotter = "fuse-overlayfs"
+		[[plugins."io.containerd.transfer.v1.local".unpack_config]]
+			platform = "linux"
+			snapshotter = "overlayfs"


Not a fan of complicating the config.
What happens if these lines are missing?
ctr doesn't need them AFAICS?

By default, it would be

[[plugins."io.containerd.transfer.v1.local".unpack_config]] platform = "linux/amd64"(matches the host's OS/Architecture) snapshotter = "overlayfs" differ = "walking"

This config is required to specify which snapshotter the transfer service should use when unpacking images. We define multiple unpack targets:

overlayfs for standard OCI images

stargz / soci for lazy-pulling support

Without this, containerd defaults to basic unpacking and won't leverage stargz/soci snapshotters needed for lazy-pulling.

And if we only configure stargz in unpack_config, then all images would be forced to use the stargz snapshotter during transfer/unpacking, even standard OCI images that don't support lazy-pulling.

ChengyuZhu6 force-pushed the transfer branch 2 times, most recently from 285c273 to 156a92a Compare November 5, 2025 15:51

AkihiroSuda reviewed Nov 5, 2025

View reviewed changes

cmd/nerdctl/image/image_import.go Outdated Show resolved Hide resolved

AkihiroSuda added this to the v2.3.0 milestone Nov 6, 2025

ChengyuZhu6 force-pushed the transfer branch 21 times, most recently from b5584fe to 18b0448 Compare November 14, 2025 03:54

ChengyuZhu6 force-pushed the transfer branch 5 times, most recently from a49ea0a to f66db0d Compare November 23, 2025 14:43

ChengyuZhu6 force-pushed the transfer branch from f66db0d to d36732a Compare November 24, 2025 06:20

ChengyuZhu6 force-pushed the transfer branch from d36732a to c5552d0 Compare November 27, 2025 07:01

ChengyuZhu6 marked this pull request as ready for review November 27, 2025 07:19

ChengyuZhu6 force-pushed the transfer branch from c5552d0 to 95e03e0 Compare November 27, 2025 07:20

ChengyuZhu6 requested a review from AkihiroSuda November 27, 2025 07:41

ChengyuZhu6 force-pushed the transfer branch 7 times, most recently from f2e210d to d3b9cab Compare November 27, 2025 10:59

ChengyuZhu6 added 2 commits November 28, 2025 07:05

configure containerd config with remote snapshotter

cae3023

Add remote snapshot annotations and transfer unpack config for stargz, soci, and fuse-overlayfs snapshotter plugins. Signed-off-by: ChengyuZhu6 <hudson@cyzhu.com>

ChengyuZhu6 force-pushed the transfer branch from d3b9cab to d099f97 Compare November 27, 2025 23:05

Support legacy push/pull for containerd 1.7.x

3341fbd

Add version detection to automatically select Transfer service (2.0+) or legacy resolver methods (< 2.0) for better compatibility. Signed-off-by: ChengyuZhu6 <hudson@cyzhu.com>

ChengyuZhu6 force-pushed the transfer branch from d099f97 to 3341fbd Compare November 28, 2025 01:38

AkihiroSuda reviewed Nov 28, 2025

View reviewed changes

pkg/infoutil/infoutil.go Show resolved Hide resolved

AkihiroSuda requested review from dmcgowan and ktock November 28, 2025 07:07

AkihiroSuda reviewed Nov 28, 2025

View reviewed changes

Refactor image management to use transfer service #4583

Are you sure you want to change the base?

Refactor image management to use transfer service #4583

Conversation

ChengyuZhu6 commented Nov 5, 2025

Uh oh!

Uh oh!

ChengyuZhu6 commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Limitations

1. IPFS Registry and Nondistributable Artifacts

2. Containerd 1.7.x Compatibility Issue

Uh oh!

ChengyuZhu6 commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ChengyuZhu6 commented Nov 25, 2025

Uh oh!

AkihiroSuda commented Nov 26, 2025

Uh oh!

AkihiroSuda Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

ChengyuZhu6 Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

ChengyuZhu6 Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

AkihiroSuda Nov 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

AkihiroSuda Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

ChengyuZhu6 Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

ChengyuZhu6 Nov 28, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ChengyuZhu6 commented Nov 25, 2025 •

edited

Loading

ChengyuZhu6 commented Nov 25, 2025 •

edited

Loading

ChengyuZhu6 Nov 28, 2025 •

edited

Loading

AkihiroSuda Nov 28, 2025 •

edited

Loading