DOCS: Add volume pinning functionality

tobwen · tobwen · commit 3260d5b8300c · 2025-12-11T02:29:25.000+01:00
Signed-off-by: tobwen &lt;1864057+tobwen@users.noreply.github.com&gt;
diff --git a/docs/source/markdown/podman-system-prune.1.md b/docs/source/markdown/podman-system-prune.1.md
@@ -11,7 +11,7 @@ podman\-system\-prune - Remove all unused pods, containers, images, networks, an
 
 Use the **--all** option to delete all unused images.  Unused images are dangling images as well as any image that does not have any containers based on it.
 
-By default, volumes are not removed to prevent important data from being deleted if there is currently no container using the volume. Use the **--volumes** flag when running the command to prune volumes as well.
+By default, volumes are not removed to prevent important data from being deleted if there is currently no container using the volume. Use the **--volumes** flag when running the command to prune volumes as well. By default, pinned volumes are excluded from pruning even when **--volumes** is specified. Use the **--include-pinned** flag to include pinned volumes in the prune operation.
 
 By default, build containers are not removed to prevent interference with builds in progress. Use the **--build** flag when running the command to remove build containers as well.
 
@@ -59,6 +59,10 @@ Do not prompt for confirmation
 
 Print usage statement
 
+#### **--include-pinned**
+
+Include pinned volumes in the prune operation when **--volumes** is specified. By default, pinned volumes are excluded from pruning to protect important data. This flag only has an effect when **--volumes** is also used.
+
 #### **--volumes**
 
 Prune volumes currently unused by any container
diff --git a/docs/source/markdown/podman-system-reset.1.md b/docs/source/markdown/podman-system-reset.1.md
@@ -11,6 +11,8 @@ podman\-system\-reset - Reset storage back to initial state
 It also removes the configured graphRoot and runRoot directories. Make sure these are not set to
 some important directory.
 
+By default, pinned volumes are excluded from the reset operation to protect important data. Use the **--include-pinned** flag to include pinned volumes in the reset.
+
 This command must be run **before** changing any of the following fields in the
 `containers.conf` or `storage.conf` files: `driver`, `static_dir`, `tmp_dir`
 or `volume_path`.
@@ -30,6 +32,10 @@ Do not prompt for confirmation
 
 Print usage statement
 
+#### **--include-pinned**
+
+Include pinned volumes in the reset operation. By default, pinned volumes are excluded from the reset to protect important data.
+
 ## EXAMPLES
 
 Reset all storage back to a clean initialized state.
diff --git a/docs/source/markdown/podman-volume-create.1.md b/docs/source/markdown/podman-volume-create.1.md
@@ -73,6 +73,10 @@ This option is mandatory when using the **image** driver.
 
 When not using the **local** and **image** drivers, the given options are passed directly to the volume plugin. In this case, supported options are dictated by the plugin in question, not Podman.
 
+#### **--pinned**
+
+Mark the volume as pinned. Pinned volumes are excluded from **podman system prune** and **podman system reset** operations by default, protecting them from accidental deletion during cleanup operations. The pinned status can be changed later using **podman volume pin**.
+
 #### **--uid**=*uid*
 
 Set the UID that the volume will be created as. Differently than `--opt o=uid=*uid*`, the specified value is not passed to the mount operation. The specified UID will own the volume's mount point directory and affects the volume chown operation.
@@ -137,6 +141,11 @@ Create volume overriding the owner UID and GID.
 # podman volume create --uid 1000 --gid 1000 myvol
 ```
 
+Create a pinned volume that is protected from system prune operations.
+```
+$ podman volume create --pinned datavol
+```
+
 Create image named volume using the specified local image in containers/storage.
 ```
 # podman volume create --driver image --opt image=fedora:latest fedoraVol
@@ -214,7 +223,7 @@ If performance is the priority, please check out the more performant [goofys](ht
 
 
 ## SEE ALSO
-**[podman(1)](podman.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[podman-volume(1)](podman-volume.1.md)**, **mount(8)**, **xfs_quota(8)**, **xfs_quota(8)**, **projects(5)**, **projid(5)**
+**[podman(1)](podman.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**, **[podman-volume(1)](podman-volume.1.md)**, **[podman-volume-pin(1)](podman-volume-pin.1.md)**, **mount(8)**, **xfs_quota(8)**, **xfs_quota(8)**, **projects(5)**, **projid(5)**
 
 ## HISTORY
 January 2020, updated with information on volume plugins by Matthew Heon <mheon@redhat.com>
diff --git a/docs/source/markdown/podman-volume-inspect.1.md b/docs/source/markdown/podman-volume-inspect.1.md
@@ -45,6 +45,7 @@ Valid placeholders for the Go template are listed below:
 | .StorageID          | StorageID of the volume                                                     |
 | .Timeout            | Timeout of the volume                                                       |
 | .UID                | UID the volume was created with                                             |
+| .Pinned             | Whether the volume is pinned                                                |
 
 #### **--help**
 
diff --git a/docs/source/markdown/podman-volume-ls.1.md.in b/docs/source/markdown/podman-volume-ls.1.md.in
@@ -30,6 +30,7 @@ Volumes can be filtered by the following attributes:
 | label       | [Key] or [Key=Value] Label assigned to a volume                                       |
 | name        | [Name] Volume name (accepts regex)                                                    |
 | opt         | Matches a storage driver options                                                      |
+| pinned      | [Bool] Matches volumes based on their pinned status (true/false)                      |
 | scope       | Filters volume by scope                                                               |
 | after/since | Filter by volumes created after the given VOLUME (name or tag)                        |
 | until       | Only remove volumes created before given timestamp                                    |
@@ -60,6 +61,7 @@ Valid placeholders for the Go template are listed below:
 | .StorageID                | StorageID of the volume                      |
 | .Timeout                  | Timeout of the volume                        |
 | .UID                      | UID of volume                                |
+| .Pinned                   | Whether the volume is pinned                 |
 | .VolumeConfigResponse ... | Don't use                                    |
 
 #### **--help**
@@ -99,6 +101,16 @@ List volumes with the label key=value.
 $ podman volume ls --filter label=key=value
 ```
 
+List all pinned volumes.
+```
+$ podman volume ls --filter pinned=true
+```
+
+List all non-pinned volumes.
+```
+$ podman volume ls --filter pinned=false
+```
+
 ## SEE ALSO
 **[podman(1)](podman.1.md)**, **[podman-volume(1)](podman-volume.1.md)**
 
diff --git a/docs/source/markdown/podman-volume-pin.1.md b/docs/source/markdown/podman-volume-pin.1.md
@@ -0,0 +1,53 @@
+% podman-volume-pin 1
+
+## NAME
+podman\-volume\-pin - Mark or unmark volumes as pinned
+
+## SYNOPSIS
+**podman volume pin** [*options*] *volume* [*volume* ...]
+
+## DESCRIPTION
+
+Mark or unmark one or more volumes as pinned. Pinned volumes are excluded from **podman system prune** and **podman system reset** operations by default, protecting them from accidental deletion.
+
+This is useful for volumes containing important persistent data that should be preserved during cleanup operations.
+
+By default, **podman volume pin** marks volumes as pinned. Use the **--unpin** option to remove the pinned status from volumes.
+
+## OPTIONS
+
+#### **--unpin**
+
+Remove the pinned status from the specified volumes instead of pinning them.
+
+#### **--help**
+
+Print usage statement.
+
+## EXAMPLES
+
+Mark a volume as pinned.
+```
+$ podman volume pin myvol
+Volume myvol is now pinned
+```
+
+Mark multiple volumes as pinned.
+```
+$ podman volume pin vol1 vol2 vol3
+Volume vol1 is now pinned
+Volume vol2 is now pinned
+Volume vol3 is now pinned
+```
+
+Remove the pinned status from a volume.
+```
+$ podman volume pin --unpin myvol
+Volume myvol is now unpinned
+```
+
+## SEE ALSO
+**[podman(1)](podman.1.md)**, **[podman-volume(1)](podman-volume.1.md)**, **[podman-volume-create(1)](podman-volume-create.1.md)**, **[podman-volume-prune(1)](podman-volume-prune.1.md)**, **[podman-volume-rm(1)](podman-volume-rm.1.md)**, **[podman-system-prune(1)](podman-system-prune.1.md)**, **[podman-system-reset(1)](podman-system-reset.1.md)**
+
+## HISTORY
+October 2025, Originally compiled by TobWen
diff --git a/docs/source/markdown/podman-volume-prune.1.md b/docs/source/markdown/podman-volume-prune.1.md
@@ -12,6 +12,8 @@ Removes unused volumes. By default all unused volumes are removed, the **--filte
 be used to filter specific volumes. Users are prompted to confirm the removal of all the
 unused volumes. To bypass the confirmation, use the **--force** flag.
 
+By default, pinned volumes are excluded from pruning to protect important data. Use the **--include-pinned** flag to include pinned volumes in the prune operation.
+
 
 ## OPTIONS
 
@@ -46,6 +48,10 @@ Do not prompt for confirmation.
 
 Print usage statement
 
+#### **--include-pinned**
+
+Include pinned volumes in the prune operation. By default, pinned volumes are excluded from pruning to protect important data.
+
 
 ## EXAMPLES
 
@@ -66,7 +72,7 @@ $ podman volume prune --filter label=mylabel=mylabelvalue
 ```
 
 ## SEE ALSO
-**[podman(1)](podman.1.md)**, **[podman-volume(1)](podman-volume.1.md)**
+**[podman(1)](podman.1.md)**, **[podman-volume(1)](podman-volume.1.md)**, **[podman-volume-pin(1)](podman-volume-pin.1.md)**
 
 ## HISTORY
 November 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com>
diff --git a/docs/source/markdown/podman-volume-rm.1.md b/docs/source/markdown/podman-volume-rm.1.md
@@ -13,6 +13,8 @@ If a volume is being used by a container, an error is returned unless the **--fo
 flag is being used. To remove all volumes, use the **--all** flag.
 Volumes can be removed individually by providing their full name or a unique partial name.
 
+By default, pinned volumes are excluded from removal operations to protect important data. Use the **--include-pinned** flag to allow removal of pinned volumes.
+
 ## OPTIONS
 
 #### **--all**, **-a**
@@ -28,6 +30,10 @@ If it is being used by containers, the containers are removed first.
 
 Print usage statement
 
+#### **--include-pinned**
+
+Include pinned volumes in the removal operation. By default, pinned volumes are excluded from removal to protect important data. This flag must be used if you want to remove volumes that have been marked as pinned.
+
 #### **--time**, **-t**=*seconds*
 
 Seconds to wait before forcibly stopping running containers that are using the specified volume. The --force option must be specified to use the --time option. Use -1 for infinite wait.
@@ -59,7 +65,7 @@ $ podman volume rm --force myvol
   **125** The command fails for any other reason
 
 ## SEE ALSO
-**[podman(1)](podman.1.md)**, **[podman-volume(1)](podman-volume.1.md)**
+**[podman(1)](podman.1.md)**, **[podman-volume(1)](podman-volume.1.md)**, **[podman-volume-pin(1)](podman-volume-pin.1.md)**
 
 ## HISTORY
 November 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com>
diff --git a/docs/source/markdown/podman-volume.1.md b/docs/source/markdown/podman-volume.1.md
@@ -20,6 +20,7 @@ podman volume is a set of subcommands that manage volumes.
 | inspect | [podman-volume-inspect(1)](podman-volume-inspect.1.md) | Get detailed information on one or more volumes.                               |
 | ls      | [podman-volume-ls(1)](podman-volume-ls.1.md)           | List all the available volumes.                                                |
 | mount   | [podman-volume-mount(1)](podman-volume-mount.1.md)     | Mount a volume filesystem.                                                     |
+| pin     | [podman-volume-pin(1)](podman-volume-pin.1.md)         | Mark or unmark volumes as pinned.                                              |
 | prune   | [podman-volume-prune(1)](podman-volume-prune.1.md)     | Remove all unused volumes.                                                     |
 | reload  | [podman-volume-reload(1)](podman-volume-reload.1.md)   | Reload all volumes from volumes plugins.                                       |
 | rm      | [podman-volume-rm(1)](podman-volume-rm.1.md)           | Remove one or more volumes.                                                    |
