From da5b172766cbd1a418a85628f3415fea0cc946f0 Mon Sep 17 00:00:00 2001 From: Grzegorz Szczepanczyk Date: Fri, 19 Jun 2026 10:36:31 +0200 Subject: [PATCH 1/2] docs: fix --image-volume default and accepted values The docs, the create/run --help text and the shell completion all show "bind" as the main/default value for --image-volume. That's wrong: the accepted values are ignore | tmpfs | anonymous (pkg/specgen/container_validate.go), the default is anonymous (pkg/specgen/specgen.go), and "bind" is only a deprecated alias the code maps to anonymous (pkg/specgenutil/specgen.go, pkg/specgen/generate/kube/kube.go). Show "anonymous" everywhere (options man page, the Quadlet ImageVolume= key, --help, completion) and note that "bind" still works as a deprecated alias. Behavior is unchanged. Fixes: #27674 Signed-off-by: Grzegorz Szczepanczyk --- cmd/podman/common/completion.go | 4 ++-- cmd/podman/common/create.go | 2 +- docs/source/markdown/options/image-volume.md | 8 +++++--- docs/source/markdown/podman-systemd.unit.5.md | 3 ++- 4 files changed, 10 insertions(+), 7 deletions(-) diff --git a/cmd/podman/common/completion.go b/cmd/podman/common/completion.go index 73f1adf651..43913640b3 100644 --- a/cmd/podman/common/completion.go +++ b/cmd/podman/common/completion.go @@ -1151,9 +1151,9 @@ func AutocompleteCgroupMode(_ *cobra.Command, _ []string, _ string) ([]string, c } // AutocompleteImageVolume - Autocomplete image volume options. -// -> "bind", "tmpfs", "ignore" +// -> "anonymous", "tmpfs", "ignore" func AutocompleteImageVolume(_ *cobra.Command, _ []string, _ string) ([]string, cobra.ShellCompDirective) { - imageVolumes := []string{"bind", "tmpfs", "ignore"} + imageVolumes := []string{"anonymous", "tmpfs", "ignore"} return imageVolumes, cobra.ShellCompDirectiveNoFileComp } diff --git a/cmd/podman/common/create.go b/cmd/podman/common/create.go index 9e48a24d3c..4db7ff9934 100644 --- a/cmd/podman/common/create.go +++ b/cmd/podman/common/create.go @@ -174,7 +174,7 @@ func DefineCreateFlags(cmd *cobra.Command, cf *entities.ContainerCreateOptions, imageVolumeFlagName := "image-volume" createFlags.String( imageVolumeFlagName, cf.ImageVolume, - `Tells podman how to handle the builtin image volumes ("bind"|"tmpfs"|"ignore")`, + `Tells podman how to handle the builtin image volumes ("anonymous"|"tmpfs"|"ignore")`, ) _ = cmd.RegisterFlagCompletionFunc(imageVolumeFlagName, AutocompleteImageVolume) diff --git a/docs/source/markdown/options/image-volume.md b/docs/source/markdown/options/image-volume.md index 56a123f68e..4364ae1d3f 100644 --- a/docs/source/markdown/options/image-volume.md +++ b/docs/source/markdown/options/image-volume.md @@ -5,12 +5,14 @@ << if is_quadlet >> ### `ImageVolume=mode` << else >> -#### **--image-volume**=**bind** | *tmpfs* | *ignore* +#### **--image-volume**=**anonymous** | *tmpfs* | *ignore* << endif >> -Tells Podman how to handle the builtin image volumes. Default is **bind**. +Tells Podman how to handle the builtin image volumes. Default is **anonymous**. -- **bind**: An anonymous named volume is created and mounted into the container. +- **anonymous**: An anonymous named volume is created and mounted into the container. - **tmpfs**: The volume is mounted onto the container as a tmpfs, which allows the users to create content that disappears when the container is stopped. - **ignore**: All volumes are just ignored and no action is taken. + +In the past, a **bind** option was accepted as well. This is deprecated, and currently aliased to **anonymous**. diff --git a/docs/source/markdown/podman-systemd.unit.5.md b/docs/source/markdown/podman-systemd.unit.5.md index 8d9499eabb..b8b091b6de 100644 --- a/docs/source/markdown/podman-systemd.unit.5.md +++ b/docs/source/markdown/podman-systemd.unit.5.md @@ -724,7 +724,8 @@ Special Cases: ### `ImageVolume=` -Tells Podman how to handle the builtin image volumes. Default is **bind**. +Tells Podman how to handle the builtin image volumes. Default is **anonymous**. +In the past, a **bind** option was accepted as well. This is deprecated, and currently aliased to **anonymous**. Equivalent to the Podman `--image-volume` option. ### `IP=` From 44284406aa9012a6bf79dfdf8fbd14e740c89893 Mon Sep 17 00:00:00 2001 From: Grzegorz Szczepanczyk Date: Mon, 29 Jun 2026 16:20:47 +0200 Subject: [PATCH 2/2] podman: warn on deprecated --image-volume=bind "bind" is a deprecated alias for "anonymous" (documented in the preceding commit). Emit a warning from CreateInit so that "podman create" and "podman run" nudge users who pass --image-volume=bind toward --image-volume=anonymous. The warning only fires when the value is explicitly set to "bind"; the resulting behavior is otherwise unchanged. Signed-off-by: Grzegorz Szczepanczyk --- cmd/podman/containers/create.go | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/cmd/podman/containers/create.go b/cmd/podman/containers/create.go index 97c1a409fa..a7fcd4b96d 100644 --- a/cmd/podman/containers/create.go +++ b/cmd/podman/containers/create.go @@ -243,6 +243,10 @@ func CreateInit(c *cobra.Command, vals entities.ContainerCreateOptions, isInfra logrus.Warnf("The --kernel-memory flag is no longer supported. This flag is a noop.") } + if c.Flag("image-volume") != nil && c.Flag("image-volume").Changed && c.Flag("image-volume").Value.String() == "bind" { + logrus.Warnf("The --image-volume=bind value is deprecated, use --image-volume=anonymous instead") + } + if cliVals.LogDriver == define.PassthroughLogging { if term.IsTerminal(0) || term.IsTerminal(1) || term.IsTerminal(2) { return vals, errors.New("the '--log-driver passthrough' option cannot be used on a TTY. If you really want it, use '--log-driver passthrough-tty'")