add new artifact mount type

Add a new option to allow for mounting artifacts in the container, the
syntax is added to the existing --mount option:
type=artifact,src=$artifactName,dest=/path[,digest=x][,title=x]

This works very similar to image mounts. The name is passed down into
the container config and then on each start we lookup the artifact and
the figure out which blobs to mount. There is no protaction against a
user removing the artifact while still being used in a container. When
the container is running the bind mounted files will stay there (as the
kernel keeps the mounts active even if the bind source was deleted).
On the next start it will fail to start as if it does not find the
artifact. The good thing is that this technically allows someone to
update the artifact with the new file by creating a new artifact with
the same name.

Signed-off-by: Paul Holzinger <[email protected]>

Author: Luap99

docs/source/markdown/options/mount.md

@@ -6,12 +6,12 @@
 
 Attach a filesystem mount to the container
 
-Current supported mount TYPEs are **bind**, **devpts**, **glob**, **image**, **ramfs**, **tmpfs** and **volume**.
+Current supported mount TYPEs are **artifact**, **bind**, **devpts**, **glob**, **image**, **ramfs**, **tmpfs** and **volume**.
 
 Options common to all mount types:
 
 - *src*, *source*: mount source spec for **bind**, **glob**, and **volume**.
-  Mandatory for **bind** and **glob**.
+  Mandatory for **artifact**, **bind**, **glob**, **image** and **volume**.
 
 - *dst*, *destination*, *target*: mount destination spec.
 
@@ -24,6 +24,25 @@ on the destination directory are mounted. The option
 to mount host files matching /foo* to the /tmp/bar/
 directory in the container.
 
+Options specific to type=**artifact**:
+
+- *digest*: If the artifact source contains multiple blobs a digest can be
+  specified to only mount the one specific blob with the digest.
+
+- *title*: If the artifact source contains multiple blobs a title can be set
+  which is compared against `org.opencontainers.image.title` annotation.
+
+The *src* argument contains the name of the artifact, it must already exist locally.
+The *dst* argument contains the target path, if the path in the container is a
+directory or does not exist the blob title (`org.opencontainers.image.title`
+annotation) will be used as filename and joined to the path. If the annotation
+does not exist the digest will be used as filename instead. This results in all blobs
+of the artifact mounted into the container at the given path.
+
+However if the *dst* path is a existing file in the container then the blob will be
+mounted directly on it. This only works when the artifact contains of a single blob
+or when either *digest* or *title* are specified.
+
 Options specific to type=**volume**:
 
 - *ro*, *readonly*: *true* or *false* (default if unspecified: *false*).
@@ -104,4 +123,6 @@ Examples:
 
 - `type=tmpfs,destination=/path/in/container,noswap`
 
-- `type=volume,source=vol1,destination=/path/in/container,ro=true`
+- `type=artifact,src=quay.io/libpod/testartifact:20250206-single,dst=/data`
+
+- `type=artifact,src=quay.io/libpod/testartifact:20250206-multi,dst=/data,title=test1`

libpod/container.go

@@ -280,6 +280,28 @@ type ContainerImageVolume struct {
 	SubPath string `json:"subPath,omitempty"`
 }
 
+// ContainerArtifactVolume is a volume based on a artifact. The artifact blobs will
+// be bind mounted directly as files and must always be read only.
+type ContainerArtifactVolume struct {
+	// Source is the name or digest of the artifact that should be mounted
+	Source string `json:"source"`
+	// Dest is the absolute path of the mount in the container.
+	// If path is a file in the container, then the artifact must consist of a single blob.
+	// Otherwise if it is a directory or does not exists all artifact blobs will be mounted
+	// into this path as files. As name the "org.opencontainers.image.title" will be used if
+	// available otherwise the digest is used as name.
+	Dest string `json:"dest"`
+	// Title can be used for multi blob artifacts to only mount the one specific blob that
+	// matches the "org.opencontainers.image.title" annotation.
+	// Optional. Conflicts with Digest.
+	Title string `json:"title"`
+	// Digest can be used to filter a single blob from a multi blob artifact by the given digest.
+	// When this option is set the file name in the container defaults to the digest even when
+	// the title annotation exist.
+	// Optional. Conflicts with Title.
+	Digest string `json:"digest"`
+}
+
 // ContainerSecret is a secret that is mounted in a container
 type ContainerSecret struct {
 	// Secret is the secret

libpod/container_config.go

@@ -162,6 +162,8 @@ type ContainerRootFSConfig struct {
 	// moved out of Libpod into pkg/specgen).
 	// Please DO NOT reuse the `imageVolumes` name in container JSON again.
 	ImageVolumes []*ContainerImageVolume `json:"ctrImageVolumes,omitempty"`
+	// ArtifactVolumes lists the artifact volumes to mount into the container.
+	ArtifactVolumes []*ContainerArtifactVolume `json:"artifactVolumes,omitempty"`
 	// CreateWorkingDir indicates that Libpod should create the container's
 	// working directory if it does not exist. Some OCI runtimes do this by
 	// default, but others do not.

libpod/container_internal_common.go

@@ -41,6 +41,7 @@ import (
 	"github.com/containers/podman/v5/pkg/annotations"
 	"github.com/containers/podman/v5/pkg/checkpoint/crutils"
 	"github.com/containers/podman/v5/pkg/criu"
+	libartTypes "github.com/containers/podman/v5/pkg/libartifact/types"
 	"github.com/containers/podman/v5/pkg/lookup"
 	"github.com/containers/podman/v5/pkg/rootless"
 	"github.com/containers/podman/v5/pkg/util"
@@ -483,6 +484,52 @@ func (c *Container) generateSpec(ctx context.Context) (s *spec.Spec, cleanupFunc
 		g.AddMount(overlayMount)
 	}
 
+	if len(c.config.ArtifactVolumes) > 0 {
+		artStore, err := c.runtime.ArtifactStore()
+		if err != nil {
+			return nil, nil, err
+		}
+		for _, artifactMount := range c.config.ArtifactVolumes {
+			paths, err := artStore.BlobMountPaths(ctx, artifactMount.Source, &libartTypes.BlobMountPathOptions{
+				FilterBlobOptions: libartTypes.FilterBlobOptions{
+					Title:  artifactMount.Title,
+					Digest: artifactMount.Digest,
+				},
+			})
+			if err != nil {
+				return nil, nil, err
+			}
+
+			// Ignore the error, destIsFile will return false with errors so if the file does not exist
+			// we treat it as dir, the oci runtime will always create the target bind mount path.
+			destIsFile, _ := containerPathIsFile(c.state.Mountpoint, artifactMount.Dest)
+			if destIsFile && len(paths) > 1 {
+				return nil, nil, fmt.Errorf("artifact %q contains more than one blob and container path %q is a file", artifactMount.Source, artifactMount.Dest)
+			}
+
+			for _, path := range paths {
+				var dest string
+				if destIsFile {
+					dest = artifactMount.Dest
+				} else {
+					dest = filepath.Join(artifactMount.Dest, path.Name)
+				}
+
+				logrus.Debugf("Mounting artifact %q in container %s, mount blob %q to %q", artifactMount.Source, c.ID(), path.SourcePath, dest)
+
+				g.AddMount(spec.Mount{
+					Destination: dest,
+					Source:      path.SourcePath,
+					Type:        define.TypeBind,
+					// Important: This must always be mounted read only here, we are using
+					// the source in the artifact store directly and because that is digest
+					// based a write will break the layout.
+					Options: []string{define.TypeBind, "ro"},
+				})
+			}
+		}
+	}
+
 	err = c.setHomeEnvIfNeeded()
 	if err != nil {
 		return nil, nil, err

libpod/container_internal_freebsd.go

@@ -13,6 +13,7 @@ import (
 
 	"github.com/containers/common/libnetwork/types"
 	"github.com/containers/podman/v5/pkg/rootless"
+	securejoin "github.com/cyphar/filepath-securejoin"
 	spec "github.com/opencontainers/runtime-spec/specs-go"
 	"github.com/opencontainers/runtime-tools/generate"
 	"github.com/sirupsen/logrus"
@@ -415,3 +416,20 @@ func (c *Container) hasPrivateUTS() bool {
 func hasCapSysResource() (bool, error) {
 	return true, nil
 }
+
+// containerPathIsFile returns true if the given containerPath is a file
+func containerPathIsFile(unsafeRoot string, containerPath string) (bool, error) {
+	// Note freebsd does not have support for OpenInRoot() so us the less safe way
+	// with the old SecureJoin(), but given this is only called before the container
+	// is started it is not subject to race conditions with the container process.
+	path, err := securejoin.SecureJoin(unsafeRoot, containerPath)
+	if err != nil {
+		return false, err
+	}
+
+	st, err := os.Lstat(path)
+	if err == nil && !st.IsDir() {
+		return true, nil
+	}
+	return false, err
+}

libpod/container_internal_linux.go

@@ -21,6 +21,7 @@ import (
 	"github.com/containers/podman/v5/libpod/define"
 	"github.com/containers/podman/v5/libpod/shutdown"
 	"github.com/containers/podman/v5/pkg/rootless"
+	securejoin "github.com/cyphar/filepath-securejoin"
 	"github.com/moby/sys/capability"
 	spec "github.com/opencontainers/runtime-spec/specs-go"
 	"github.com/opencontainers/runtime-tools/generate"
@@ -848,3 +849,18 @@ var hasCapSysResource = sync.OnceValues(func() (bool, error) {
 	}
 	return currentCaps.Get(capability.EFFECTIVE, capability.CAP_SYS_RESOURCE), nil
 })
+
+// containerPathIsFile returns true if the given containerPath is a file
+func containerPathIsFile(unsafeRoot string, containerPath string) (bool, error) {
+	f, err := securejoin.OpenInRoot(unsafeRoot, containerPath)
+	if err != nil {
+		return false, err
+	}
+	defer f.Close()
+
+	st, err := f.Stat()
+	if err == nil && !st.IsDir() {
+		return true, nil
+	}
+	return false, err
+}

libpod/options.go

@@ -1515,6 +1515,19 @@ func WithImageVolumes(volumes []*ContainerImageVolume) CtrCreateOption {
 	}
 }
 
+// WithImageVolumes adds the given image volumes to the container.
+func WithArtifactVolumes(volumes []*ContainerArtifactVolume) CtrCreateOption {
+	return func(ctr *Container) error {
+		if ctr.valid {
+			return define.ErrCtrFinalized
+		}
+
+		ctr.config.ArtifactVolumes = volumes
+
+		return nil
+	}
+}
+
 // WithHealthCheck adds the healthcheck to the container config
 func WithHealthCheck(healthCheck *manifest.Schema2HealthConfig) CtrCreateOption {
 	return func(ctr *Container) error {

pkg/specgen/generate/container_create.go

@@ -507,6 +507,19 @@ func createContainerOptions(rt *libpod.Runtime, s *specgen.SpecGenerator, pod *l
 		options = append(options, libpod.WithImageVolumes(vols))
 	}
 
+	if len(s.ArtifactVolumes) != 0 {
+		vols := make([]*libpod.ContainerArtifactVolume, 0, len(s.ArtifactVolumes))
+		for _, v := range s.ArtifactVolumes {
+			vols = append(vols, &libpod.ContainerArtifactVolume{
+				Dest:   v.Destination,
+				Source: v.Source,
+				Digest: v.Digest,
+				Title:  v.Title,
+			})
+		}
+		options = append(options, libpod.WithArtifactVolumes(vols))
+	}
+
 	if s.Command != nil {
 		options = append(options, libpod.WithCommand(s.Command))
 	}

pkg/specgen/specgen.go

@@ -305,6 +305,8 @@ type ContainerStorageConfig struct {
 	// Image volumes bind-mount a container-image mount into the container.
 	// Optional.
 	ImageVolumes []*ImageVolume `json:"image_volumes,omitempty"`
+	// ArtifactVolumes volumes based on an existing artifact.
+	ArtifactVolumes []*ArtifactVolume `json:"artifact_volumes,omitempty"`
 	// Devices are devices that will be added to the container.
 	// Optional.
 	Devices []spec.LinuxDevice `json:"devices,omitempty"`

pkg/specgen/volumes.go

@@ -58,6 +58,28 @@ type ImageVolume struct {
 	SubPath string `json:"subPath,omitempty"`
 }
 
+// ArtifactVolume is a volume based on a artifact. The artifact blobs will
+// be bind mounted directly as files and must always be read only.
+type ArtifactVolume struct {
+	// Source is the name or digest of the artifact that should be mounted
+	Source string `json:"source"`
+	// Destination is the absolute path of the mount in the container.
+	// If path is a file in the container, then the artifact must consist of a single blob.
+	// Otherwise if it is a directory or does not exists all artifact blobs will be mounted
+	// into this path as files. As name the "org.opencontainers.image.title" will be used if
+	// available otherwise the digest is used as name.
+	Destination string `json:"destination"`
+	// Title can be used for multi blob artifacts to only mount the one specific blob that
+	// matches the "org.opencontainers.image.title" annotation.
+	// Optional. Conflicts with Digest.
+	Title string `json:"title,omitempty"`
+	// Digest can be used to filter a single blob from a multi blob artifact by the given digest.
+	// When this option is set the file name in the container defaults to the digest even when
+	// the title annotation exist.
+	// Optional. Conflicts with Title.
+	Digest string `json:"digest,omitempty"`
+}
+
 // GenVolumeMounts parses user input into mounts, volumes and overlay volumes
 func GenVolumeMounts(volumeFlag []string) (map[string]spec.Mount, map[string]*NamedVolume, map[string]*OverlayVolume, error) {
 	mounts := make(map[string]spec.Mount)

pkg/specgenutil/specgen.go

@@ -790,6 +790,9 @@ func FillOutSpecGen(s *specgen.SpecGenerator, c *entities.ContainerCreateOptions
 	if len(s.ImageVolumes) == 0 {
 		s.ImageVolumes = containerMounts.imageVolumes
 	}
+	if len(s.ArtifactVolumes) == 0 {
+		s.ArtifactVolumes = containerMounts.artifactVolumes
+	}
 
 	devices := c.Devices
 	for _, gpu := range c.GPUs {