Merge pull request #1974 from saschagrunert/fix-1911-rmi-multi-tag-warning

Add warning and documentation for crictl rmi multi-tag behavior

Author: k8s-ci-robot

cmd/crictl/image.go

@@ -390,9 +390,16 @@ func outputImageStatusTable(r *pb.ImageStatusResponse, verbose bool) {
 }
 
 var removeImageCommand = &cli.Command{
-	Name:                   "rmi",
-	Usage:                  "Remove one or more images",
-	ArgsUsage:              "IMAGE-ID [IMAGE-ID...]",
+	Name:      "rmi",
+	Usage:     "Remove one or more images",
+	ArgsUsage: "IMAGE-ID [IMAGE-ID...]",
+	Description: `Remove one or more images by ID or reference.
+
+NOTE: Due to CRI API limitations, when you specify an image by tag (e.g., 'localhost/test:latest'),
+the entire image will be removed along with ALL of its tags, not just the specified tag.
+This behavior differs from 'docker rmi', 'nerdctl rmi', and 'ctr image rm', which only remove
+the specified tag. To remove only a specific tag, use the container runtime's native CLI tool
+(e.g., 'nerdctl', 'ctr', or 'podman').`,
 	UseShortOptionHandling: true,
 	Flags: []cli.Flag{
 		&cli.BoolFlag{
@@ -496,6 +503,20 @@ var removeImageCommand = &cli.Command{
 					return fmt.Errorf("no such image %s", id)
 				}
 
+				// Warn if the user specified a tag and multiple tags would be removed
+				repoTags := status.GetImage().GetRepoTags()
+				if len(repoTags) > 1 {
+					// Check if user specified a tag (contains ':' but doesn't start with 'sha256:')
+					// or a repo name (contains '/' or is a name like 'localhost')
+					isLikelyTag := !strings.HasPrefix(id, "sha256:") && (strings.Contains(id, ":") || strings.Contains(id, "/"))
+					if isLikelyTag {
+						logrus.Warnf("Image %q has multiple tags. Removing this image will delete all of the following tags:", id)
+						for _, tag := range repoTags {
+							logrus.Warnf("  %s", tag)
+						}
+					}
+				}
+
 				if err := RemoveImage(cliCtx.Context, imageClient, id); err != nil {
 					// We ignore further errors on prune because there might be
 					// races

docs/crictl.1

@@ -401,6 +401,51 @@ busybox             latest              8c811b4aec35f       1.15MB
 k8s.gcr.io/pause    3.1                 da86e6ba6ca19       742kB
 .EE
 
+.SS Remove images
+The \fBcrictl rmi\fR command removes one or more images by ID or reference:
+
+.EX
+$ crictl rmi busybox:latest
+.EE
+
+.PP
+\fBImportant Note\fP: Due to CRI API limitations, when you specify an image by tag (e.g., \fBlocalhost/test:latest\fR), the entire image will be removed along with \fBall\fP of its tags, not just the specified tag. This behavior differs from \fBdocker rmi\fR, \fBnerdctl rmi\fR, and \fBctr image rm\fR, which only remove the specified tag.
+
+.PP
+If you need to remove only a specific tag while keeping the image and other tags, use the container runtime's native CLI tool instead:
+.IP \(bu 2
+For containerd: \fBnerdctl image rm <tag>\fR or \fBctr image rm <tag>\fR
+.IP \(bu 2
+For CRI-O, use Podman: \fBpodman rmi <tag>\fR
+.IP \(bu 2
+For Docker: \fBdocker rmi <tag>\fR
+
+.PP
+Example showing the difference:
+
+.EX
+# Image with multiple tags
+$ crictl images
+IMAGE                TAG                 IMAGE ID            SIZE
+localhost/test       latest              abc123def456        10MB
+localhost/test       v1.0                abc123def456        10MB
+localhost/base       latest              abc123def456        10MB
+
+# Running crictl rmi will remove ALL tags
+$ crictl rmi localhost/test:latest
+WARN[0000] Image "localhost/test:latest" has multiple tags. Removing this image will delete all of the following tags:
+WARN[0000]   localhost/test:latest
+WARN[0000]   localhost/test:v1.0
+WARN[0000]   localhost/base:latest
+Deleted: localhost/test:latest
+Deleted: localhost/test:v1.0
+Deleted: localhost/base:latest
+
+# All tags are now gone
+$ crictl images
+IMAGE                TAG                 IMAGE ID            SIZE
+.EE
+
 .SS Filter images
 The following filters are available \fB--filter\fR, \fB-f\fR:
 .IP "  1." 5

docs/crictl.md

@@ -293,6 +293,47 @@ busybox             latest              8c811b4aec35f       1.15MB
 k8s.gcr.io/pause    3.1                 da86e6ba6ca19       742kB
 ```
 
+### Remove images
+
+The `crictl rmi` command removes one or more images by ID or reference:
+
+```sh
+$ crictl rmi busybox:latest
+```
+
+**Important Note**: Due to CRI API limitations, when you specify an image by tag (e.g., `localhost/test:latest`), the entire image will be removed along with **all** of its tags, not just the specified tag. This behavior differs from `docker rmi`, `nerdctl rmi`, and `ctr image rm`, which only remove the specified tag.
+
+If you need to remove only a specific tag while keeping the image and other tags, use the container runtime's native CLI tool instead:
+
+- For containerd: `nerdctl image rm <tag>` or `ctr image rm <tag>`
+- For CRI-O, use Podman: `podman rmi <tag>`
+- For Docker: `docker rmi <tag>`
+
+Example showing the difference:
+
+```sh
+# Image with multiple tags
+$ crictl images
+IMAGE                TAG                 IMAGE ID            SIZE
+localhost/test       latest              abc123def456        10MB
+localhost/test       v1.0                abc123def456        10MB
+localhost/base       latest              abc123def456        10MB
+
+# Running crictl rmi will remove ALL tags
+$ crictl rmi localhost/test:latest
+WARN[0000] Image "localhost/test:latest" has multiple tags. Removing this image will delete all of the following tags:
+WARN[0000]   localhost/test:latest
+WARN[0000]   localhost/test:v1.0
+WARN[0000]   localhost/base:latest
+Deleted: localhost/test:latest
+Deleted: localhost/test:v1.0
+Deleted: localhost/base:latest
+
+# All tags are now gone
+$ crictl images
+IMAGE                TAG                 IMAGE ID            SIZE
+```
+
 ### Filter images
 
 The following filters are available `--filter`, `-f`: