fix(image): pin the image a container runs to its digest

`nerdctl images` marks an image as in use by resolving the image name stored on the
container, which follows the tag wherever it points now. After `nerdctl tag` moves a tag
onto another image, the container gets attributed to an image it never ran: the U
indicator lands on the wrong row.

Record the image target digest on the container at creation time, in a new
nerdctl/image-digest label, and use it for the in-use lookup. Containers created before
this label existed, or created outside nerdctl, are still resolved by name; an unparsable
value falls back the same way rather than dropping the container from the set.

This also matters for the ACTIVE and RECLAIMABLE columns of `nerdctl system df`, which
build on the same lookup.

Signed-off-by: Eugene Kalinin <e.v.kalinin@gmail.com>

Author: ekalinin

cmd/nerdctl/image/image_list_test.go

@@ -207,6 +207,56 @@ func TestImages(t *testing.T) {
 					}
 				},
 			},
+			{
+				Description: "In use survives a retag",
+				Setup: func(data test.Data, helpers test.Helpers) {
+					// Run a container off a private tag, then move that tag onto another image.
+					// The container still runs the original image, so that is the one that must
+					// stay marked as in use.
+					helpers.Ensure("tag", commonImage.String(), data.Identifier()+":moving")
+					helpers.Ensure("run", "-d", "--quiet", "--name", data.Identifier(),
+						data.Identifier()+":moving", "sleep", nerdtest.Infinity)
+					helpers.Ensure("tag", testutil.NginxAlpineImage, data.Identifier()+":moving")
+
+					nginx, _ := referenceutil.Parse(testutil.NginxAlpineImage)
+					data.Labels().Set("retaggedTo", nginx.FamiliarName()+":"+nginx.Tag)
+				},
+				Cleanup: func(data test.Data, helpers test.Helpers) {
+					helpers.Anyhow("rm", "-f", data.Identifier())
+					helpers.Anyhow("rmi", "-f", data.Identifier()+":moving")
+				},
+				Command: test.Command("images"),
+				Expected: func(data test.Data, helpers test.Helpers) *test.Expected {
+					return &test.Expected{
+						Output: func(stdout string, t tig.T) {
+							lines := strings.Split(strings.TrimSpace(stdout), "\n")
+							assert.Assert(t, len(lines) >= 2, "there should be at least two lines\n")
+							tab := tabutil.NewReader("IMAGE\tID\tDISK USAGE\tCONTENT SIZE\tEXTRA")
+							err := tab.ParseHeader(lines[0])
+							assert.NilError(t, err, "ParseHeader should not fail\n")
+
+							original := commonImage.FamiliarName() + ":" + commonImage.Tag
+							retagged := data.Labels().Get("retaggedTo")
+							seen := 0
+							for _, line := range lines[1:] {
+								image, _ := tab.ReadRow(line, "IMAGE")
+								extra, _ := tab.ReadRow(line, "EXTRA")
+								switch image {
+								case original:
+									assert.Equal(t, extra, "U",
+										"the image the container runs must stay in use: "+image)
+									seen++
+								case retagged:
+									assert.Equal(t, extra, "",
+										"the image the tag now points at is not in use: "+image)
+									seen++
+								}
+							}
+							assert.Equal(t, seen, 2, "both images should be listed\n")
+						},
+					}
+				},
+			},
 		},
 	}
 

pkg/cmd/container/create.go

@@ -215,6 +215,12 @@ func Create(ctx context.Context, client *containerd.Client, args []string, netMa
 		internalLabels.user = ensuredImage.ImageConfig.User
 	}
 
+	// Pin the image the container is created from. containerd only records the image name, and a
+	// name can later be retagged onto a different image.
+	if ensuredImage != nil && ensuredImage.Image != nil {
+		internalLabels.imageDigest = ensuredImage.Image.Target().Digest.String()
+	}
+
 	// Override it if User is passed
 	if options.User != "" {
 		internalLabels.user = options.User
@@ -811,6 +817,8 @@ type internalLabels struct {
 	domainname string
 	// automatically generated
 	stateDir string
+	// the digest of the image target the container was created from
+	imageDigest string
 	// network
 	networks             []string
 	ipAddress            string
@@ -919,6 +927,10 @@ func withInternalLabels(internalLabels internalLabels) (containerd.NewContainerO
 		return nil, err
 	}
 
+	if internalLabels.imageDigest != "" {
+		m[labels.ImageDigest] = internalLabels.imageDigest
+	}
+
 	if len(internalLabels.mountPoints) > 0 {
 		mounts := dockercompatMounts(internalLabels.mountPoints)
 		jsonMountBytes, err := json.Marshal(mounts)

pkg/cmd/image/list.go

@@ -48,6 +48,7 @@ import (
 	"github.com/containerd/nerdctl/v2/pkg/containerdutil"
 	"github.com/containerd/nerdctl/v2/pkg/formatter"
 	"github.com/containerd/nerdctl/v2/pkg/imgutil"
+	"github.com/containerd/nerdctl/v2/pkg/labels"
 	"github.com/containerd/nerdctl/v2/pkg/referenceutil"
 )
 
@@ -575,15 +576,50 @@ func imagesInUse(ctx context.Context, client *containerd.Client) map[digest.Dige
 		return inUse
 	}
 	for _, container := range containerList {
-		image, err := container.Image(ctx)
-		if err != nil {
-			continue
+		if dgst, ok := containerImageDigest(ctx, container); ok {
+			inUse[dgst] = true
 		}
-		inUse[image.Target().Digest] = true
 	}
 	return inUse
 }
 
+// containerImageDigest returns the image target a container was created from.
+//
+// The digest is read from the label nerdctl records at creation time. Resolving the image name
+// instead would follow the tag wherever it points now: after `nerdctl tag` moves a tag onto another
+// image, the container would be attributed to an image it never ran. Containers created before this
+// label existed, or outside nerdctl, still have to be resolved by name.
+func containerImageDigest(ctx context.Context, container containerd.Container) (digest.Digest, bool) {
+	// The already-loaded metadata carries the labels, so this costs no extra round trip.
+	if info, err := container.Info(ctx, containerd.WithoutRefreshedMetadata); err == nil {
+		if dgst, ok := pinnedImageDigest(info.Labels); ok {
+			return dgst, true
+		}
+	}
+
+	image, err := container.Image(ctx)
+	if err != nil {
+		return "", false
+	}
+	return image.Target().Digest, true
+}
+
+// pinnedImageDigest returns the image target digest a container pinned at creation time. An
+// unparsable value is treated as absent, so that a hand-edited label degrades to resolving the
+// image by name rather than dropping the container from the in-use set.
+func pinnedImageDigest(containerLabels map[string]string) (digest.Digest, bool) {
+	value := containerLabels[labels.ImageDigest]
+	if value == "" {
+		return "", false
+	}
+	dgst, err := digest.Parse(value)
+	if err != nil {
+		log.L.Debugf("ignoring invalid %s label value %q", labels.ImageDigest, value)
+		return "", false
+	}
+	return dgst, true
+}
+
 func isAttestationManifestDescriptor(desc ocispec.Descriptor) bool {
 	const manifestReferenceType = "vnd.docker.reference.type"
 	const attestationManifest = "attestation-manifest"

pkg/cmd/image/list_test.go

@@ -22,6 +22,8 @@ import (
 	"gotest.tools/v3/assert"
 
 	"github.com/containerd/containerd/v2/core/images"
+
+	"github.com/containerd/nerdctl/v2/pkg/labels"
 )
 
 func TestNewViewImageRef(t *testing.T) {
@@ -75,3 +77,46 @@ func TestSortByImageRef(t *testing.T) {
 		assert.Equal(t, img.Name, expected[i])
 	}
 }
+
+func TestPinnedImageDigest(t *testing.T) {
+	t.Parallel()
+
+	const pinned = "sha256:09538a1f51d3ec5af0449a1640937dfdf79b0e9b8c4da5b8a883086d5c1492ef"
+
+	testCases := []struct {
+		name            string
+		containerLabels map[string]string
+		expected        string
+	}{
+		{
+			name:            "pinned at creation",
+			containerLabels: map[string]string{labels.ImageDigest: pinned},
+			expected:        pinned,
+		},
+		{
+			// Containers created before the label existed, or outside nerdctl, have to be resolved
+			// by image name instead.
+			name:            "no label",
+			containerLabels: map[string]string{labels.Platform: "linux/amd64"},
+		},
+		{
+			name:            "empty label",
+			containerLabels: map[string]string{labels.ImageDigest: ""},
+		},
+		{
+			// Falling back to the name is better than dropping the container from the in-use set.
+			name:            "unparsable label",
+			containerLabels: map[string]string{labels.ImageDigest: "not-a-digest"},
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			t.Parallel()
+
+			dgst, ok := pinnedImageDigest(tc.containerLabels)
+			assert.Equal(t, ok, tc.expected != "")
+			assert.Equal(t, string(dgst), tc.expected)
+		})
+	}
+}

pkg/labels/labels.go

@@ -87,6 +87,11 @@ const (
 	// Platform is the normalized platform string like "linux/ppc64le".
 	Platform = Prefix + "platform"
 
+	// ImageDigest is the digest of the image target the container was created from. The image name
+	// stored by containerd can be retagged to point at something else, so it is not enough to tell
+	// which image a container actually uses.
+	ImageDigest = Prefix + "image-digest"
+
 	// Mounts is the mount points for the container.
 	Mounts = Prefix + "mounts"