Rename term "protected" to "pinned"

see discussion in #23217

Author: tobwen

cmd/podman/system/prune.go

@@ -51,7 +51,7 @@ func init() {
 	flags.BoolVar(&pruneOptions.External, "external", false, "Remove container data in storage not controlled by podman")
 	flags.BoolVar(&pruneOptions.Build, "build", false, "Remove build containers")
 	flags.BoolVar(&pruneOptions.Volume, "volumes", false, "Prune volumes")
-	flags.BoolVar(&includeProtected, "include-protected", false, "Include protected volumes in prune operation")
+	flags.BoolVar(&includeProtected, "include-pinned", false, "Include pinned volumes in prune operation")
 	filterFlagName := "filter"
 	flags.StringArrayVar(&filters, filterFlagName, []string{}, "Provide filter values (e.g. 'label=<key>=<value>')")
 	_ = pruneCommand.RegisterFlagCompletionFunc(filterFlagName, common.AutocompletePruneFilters)
@@ -83,9 +83,9 @@ func prune(cmd *cobra.Command, args []string) error {
 		}
 	}
 
-	// Set the include protected flag for volume pruning
+	// Set the include pinned flag for volume pruning
 	if pruneOptions.Volume {
-		pruneOptions.VolumePruneOptions.IncludeProtected = includeProtected
+		pruneOptions.VolumePruneOptions.IncludePinned = includeProtected
 	}
 
 	// Remove all unused pods, containers, images, networks, and volume data.
@@ -94,9 +94,9 @@ func prune(cmd *cobra.Command, args []string) error {
 		return err
 	}
 
-	// Set the include protected flag for volume pruning
+	// Set the include pinned flag for volume pruning
 	if pruneOptions.Volume {
-		pruneOptions.VolumePruneOptions.IncludeProtected = includeProtected
+		pruneOptions.VolumePruneOptions.IncludePinned = includeProtected
 	}
 
 	response, err := registry.ContainerEngine().SystemPrune(context.Background(), pruneOptions)
@@ -138,9 +138,9 @@ func prune(cmd *cobra.Command, args []string) error {
 }
 
 func createPruneWarningMessage(pruneOpts entities.SystemPruneOptions) string {
-	protectedNote := ""
-	if pruneOpts.Volume && !pruneOpts.VolumePruneOptions.IncludeProtected {
-		protectedNote = " (excluding protected volumes)"
+	pinnedNote := ""
+	if pruneOpts.Volume && !pruneOpts.VolumePruneOptions.IncludePinned {
+		pinnedNote = " (excluding pinned volumes)"
 	}
 
 	if pruneOpts.All {
@@ -154,7 +154,7 @@ func createPruneWarningMessage(pruneOpts entities.SystemPruneOptions) string {
 	}
 	return `WARNING! This command removes:
 	- all stopped containers
-	- all networks not used by at least one container%s%s` + protectedNote + `
+	- all networks not used by at least one container%s%s` + pinnedNote + `
 	- all dangling images
 	- all dangling build cache
 

cmd/podman/volumes/create.go

@@ -70,9 +70,9 @@ func init() {
 	flags.IntVar(&opts.GID, gidFlagName, 0, "Set the GID of the volume owner")
 	_ = createCommand.RegisterFlagCompletionFunc(gidFlagName, completion.AutocompleteNone)
 
-	protectedFlagName := "protected"
-	flags.BoolVar(&opts.Protected, protectedFlagName, false, "Mark volume as protected (excluded from system prune by default)")
-	_ = createCommand.RegisterFlagCompletionFunc(protectedFlagName, completion.AutocompleteNone)
+	pinnedFlagName := "pinned"
+	flags.BoolVar(&opts.Protected, pinnedFlagName, false, "Mark volume as pinned (excluded from system prune by default)")
+	_ = createCommand.RegisterFlagCompletionFunc(pinnedFlagName, completion.AutocompleteNone)
 }
 
 func create(cmd *cobra.Command, args []string) error {
@@ -99,7 +99,7 @@ func create(cmd *cobra.Command, args []string) error {
 	if cmd.Flags().Changed("gid") {
 		createOpts.GID = &opts.GID
 	}
-	createOpts.Protected = opts.Protected
+	createOpts.Pinned = opts.Protected
 	response, err := registry.ContainerEngine().VolumeCreate(context.Background(), createOpts)
 	if err != nil {
 		return err

cmd/podman/volumes/pin.go

@@ -0,0 +1,66 @@
+package volumes
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/containers/podman/v5/cmd/podman/common"
+	"github.com/containers/podman/v5/cmd/podman/registry"
+	"github.com/containers/podman/v5/pkg/domain/entities"
+	"github.com/spf13/cobra"
+)
+
+var (
+	pinDescription = `Mark or unmark a volume as pinned.
+
+Pinned volumes are excluded from system prune operations by default.`
+
+	pinCommand = &cobra.Command{
+		Use:               "pin [options] VOLUME [VOLUME...]",
+		Short:             "Mark or unmark volume as pinned",
+		Long:              pinDescription,
+		RunE:              pin,
+		ValidArgsFunction: common.AutocompleteVolumes,
+		Example: `podman volume pin myvol
+  podman volume pin --unpin myvol
+  podman volume pin vol1 vol2 vol3`,
+	}
+)
+
+var (
+	pinOptions = entities.VolumePinOptions{}
+)
+
+func init() {
+	registry.Commands = append(registry.Commands, registry.CliCommand{
+		Command: pinCommand,
+		Parent:  volumeCmd,
+	})
+	flags := pinCommand.Flags()
+	flags.BoolVar(&pinOptions.Unpin, "unpin", false, "Remove pinning from volume")
+}
+
+func pin(cmd *cobra.Command, args []string) error {
+	if len(args) < 1 {
+		return fmt.Errorf("must specify at least one volume name")
+	}
+
+	responses, err := registry.ContainerEngine().VolumePin(context.Background(), args, pinOptions)
+	if err != nil {
+		return err
+	}
+
+	for _, r := range responses {
+		if r.Err != nil {
+			fmt.Printf("Error pinning volume %s: %v\n", r.Id, r.Err)
+		} else {
+			if pinOptions.Unpin {
+				fmt.Printf("Volume %s is now unpinned\n", r.Id)
+			} else {
+				fmt.Printf("Volume %s is now pinned\n", r.Id)
+			}
+		}
+	}
+
+	return nil
+}

cmd/podman/volumes/protect.go

@@ -46,7 +46,7 @@ func init() {
 	flags := rmCommand.Flags()
 	flags.BoolVarP(&rmOptions.All, "all", "a", false, "Remove all volumes")
 	flags.BoolVarP(&rmOptions.Force, "force", "f", false, "Remove a volume by force, even if it is being used by a container")
-	flags.BoolVar(&includeProtected, "include-protected", false, "Include protected volumes in removal operation")
+	flags.BoolVar(&includeProtected, "include-pinned", false, "Include pinned volumes in removal operation")
 	timeFlagName := "time"
 	flags.IntVarP(&stopTimeout, timeFlagName, "t", int(containerConfig.Engine.StopTimeout), "Seconds to wait for running containers to stop before killing the container")
 	_ = rmCommand.RegisterFlagCompletionFunc(timeFlagName, completion.AutocompleteNone)
@@ -66,7 +66,7 @@ func rm(cmd *cobra.Command, args []string) error {
 		timeout := uint(stopTimeout)
 		rmOptions.Timeout = &timeout
 	}
-	rmOptions.IncludeProtected = includeProtected
+	rmOptions.IncludePinned = includeProtected
 	responses, err := registry.ContainerEngine().VolumeRm(context.Background(), args, rmOptions)
 	if err != nil {
 		if rmOptions.Force && strings.Contains(err.Error(), define.ErrNoSuchVolume.Error()) {

cmd/podman/volumes/rm.go

@@ -63,9 +63,9 @@ type InspectVolumeData struct {
 	StorageID string `json:"StorageID,omitempty"`
 	// LockNumber is the number of the volume's Libpod lock.
 	LockNumber uint32
-	// Protected indicates that this volume should be excluded from
+	// Pinned indicates that this volume should be excluded from
 	// system prune operations by default.
-	Protected bool `json:"Protected,omitempty"`
+	Pinned bool `json:"Pinned,omitempty"`
 }
 
 type VolumeReload struct {

libpod/define/volume_inspect.go

@@ -1753,15 +1753,15 @@ func withSetAnon() VolumeCreateOption {
 	}
 }
 
-// WithVolumeProtected sets the protected flag for the volume.
-// Protected volumes are excluded from system prune operations by default.
-func WithVolumeProtected() VolumeCreateOption {
+// WithVolumePinned sets the pinned flag for the volume.
+// Pinned volumes are excluded from system prune operations by default.
+func WithVolumePinned() VolumeCreateOption {
 	return func(volume *Volume) error {
 		if volume.valid {
 			return define.ErrVolumeFinalized
 		}
 
-		volume.config.Protected = true
+		volume.config.Pinned = true
 
 		return nil
 	}

libpod/options.go

@@ -143,16 +143,16 @@ func (r *Runtime) PruneVolumes(ctx context.Context, filterFuncs []VolumeFilter)
 }
 
 // PruneVolumesWithOptions removes unused volumes from the system with options
-func (r *Runtime) PruneVolumesWithOptions(ctx context.Context, filterFuncs []VolumeFilter, includeProtected bool) ([]*reports.PruneReport, error) {
+func (r *Runtime) PruneVolumesWithOptions(ctx context.Context, filterFuncs []VolumeFilter, includePinned bool) ([]*reports.PruneReport, error) {
 	preports := make([]*reports.PruneReport, 0)
 	vols, err := r.Volumes(filterFuncs...)
 	if err != nil {
 		return nil, err
 	}
 
 	for _, vol := range vols {
-		// Skip protected volumes unless explicitly requested
-		if vol.Protected() && !includeProtected {
+		// Skip pinned volumes unless explicitly requested
+		if vol.Pinned() && !includePinned {
 			continue
 		}
 
@@ -179,9 +179,9 @@ func (r *Runtime) PruneVolumesWithOptions(ctx context.Context, filterFuncs []Vol
 	return preports, nil
 }
 
-// SetVolumeProtected sets the protected status of a volume by name.
-// Protected volumes are excluded from system prune operations by default.
-func (r *Runtime) SetVolumeProtected(volumeName string, protected bool) error {
+// SetVolumePinned sets the pinned status of a volume by name.
+// Pinned volumes are excluded from system prune operations by default.
+func (r *Runtime) SetVolumePinned(volumeName string, pinned bool) error {
 	if !r.valid {
 		return define.ErrRuntimeStopped
 	}
@@ -191,5 +191,5 @@ func (r *Runtime) SetVolumeProtected(volumeName string, protected bool) error {
 		return err
 	}
 
-	return vol.SetProtected(protected)
+	return vol.SetPinned(pinned)
 }

libpod/runtime_volume.go

@@ -76,9 +76,9 @@ type VolumeConfig struct {
 	StorageImageID string `json:"storageImageID,omitempty"`
 	// MountLabel is the SELinux label to assign to mount points
 	MountLabel string `json:"mountlabel,omitempty"`
-	// Protected indicates that this volume should be excluded from
+	// Pinned indicates that this volume should be excluded from
 	// system prune operations by default
-	Protected bool `json:"protected,omitempty"`
+	Pinned bool `json:"pinned,omitempty"`
 }
 
 // VolumeState holds the volume's mutable state.
@@ -286,15 +286,15 @@ func (v *Volume) UsesVolumeDriver() bool {
 	return v.config.Driver != define.VolumeDriverLocal && v.config.Driver != ""
 }
 
-// Protected returns whether this volume is marked as protected.
-// Protected volumes are excluded from system prune operations by default.
-func (v *Volume) Protected() bool {
-	return v.config.Protected
+// Pinned returns whether this volume is marked as pinned.
+// Pinned volumes are excluded from system prune operations by default.
+func (v *Volume) Pinned() bool {
+	return v.config.Pinned
 }
 
-// SetProtected sets the protected status of the volume.
-// Protected volumes are excluded from system prune operations by default.
-func (v *Volume) SetProtected(protected bool) error {
+// SetPinned sets the pinned status of the volume.
+// Pinned volumes are excluded from system prune operations by default.
+func (v *Volume) SetPinned(pinned bool) error {
 	if !v.valid {
 		return define.ErrVolumeRemoved
 	}
@@ -306,7 +306,7 @@ func (v *Volume) SetProtected(protected bool) error {
 		return err
 	}
 
-	v.config.Protected = protected
+	v.config.Pinned = pinned
 
 	return v.save()
 }

libpod/volume.go

@@ -75,7 +75,7 @@ func (v *Volume) Inspect() (*define.InspectVolumeData, error) {
 		data.Timeout = v.runtime.config.Engine.VolumePluginTimeout
 	}
 
-	data.Protected = v.config.Protected
+	data.Pinned = v.config.Pinned
 
 	return data, nil
 }