Optimize image loading for Podman machines

Add support for loading images directly from machine paths to avoid
unnecessary file transfers when the image archive is already accessible
on the running machine through mounted directories.

Changes include:
- New /libpod/local/images/load API endpoint for direct machine loading
- Machine detection and path mapping functionality
- Fallback in tunnel mode to try optimized loading first

This optimization significantly speeds up image loading operations
when working with remote Podman machines by eliminating redundant
file transfers for already-accessible image archives.

Fixes: https://issues.redhat.com/browse/RUN-3249
Fixes: #26321

Signed-off-by: Jan Rodák <[email protected]>

Author: Honny1

internal/local_utils/local_types.go

@@ -0,0 +1,7 @@
+package local_utils
+
+// LocalAPIMap is a map of local paths to their target paths in the VM
+type LocalAPIMap struct {
+	ClientPath string `json:"ClientPath,omitempty"`
+	RemotePath string `json:"RemotePath,omitempty"`
+}

internal/local_utils/local_utils.go

@@ -0,0 +1,81 @@
+//go:build remote && (amd64 || arm64)
+
+package local_utils
+
+import (
+	"context"
+	"errors"
+	"io/fs"
+	"path/filepath"
+	"strings"
+
+	"github.com/containers/podman/v5/pkg/bindings"
+	machine "github.com/containers/podman/v5/pkg/machine"
+	"github.com/containers/podman/v5/pkg/machine/provider"
+	"github.com/containers/podman/v5/pkg/machine/shim"
+	"github.com/containers/storage/pkg/fileutils"
+	"github.com/sirupsen/logrus"
+)
+
+// isPathAvailableOnMachine checks if a local path is available on the machine through mounted directories.
+// If the path is available, it returns a LocalAPIMap with the corresponding remote path.
+func isPathAvailableOnMachine(machineInfo *machine.InternalInspectInfo, path string) (*LocalAPIMap, bool) {
+	if machineInfo == nil || path == "" {
+		return nil, false
+	}
+
+	pathABS, err := filepath.Abs(path)
+	if err != nil {
+		logrus.Debugf("Failed to get absolute path for %s: %v", path, err)
+		return nil, false
+	}
+
+	for _, mount := range machineInfo.Mounts {
+		mountSource := filepath.Clean(mount.Source)
+		if strings.HasPrefix(pathABS, mountSource) {
+			// Ensure we're matching directory boundaries, not just prefixes
+			// e.g., /home/user should not match /home/username
+			if len(pathABS) > len(mountSource) && pathABS[len(mountSource)] != filepath.Separator {
+				continue
+			}
+
+			relPath, err := filepath.Rel(mountSource, pathABS)
+			if err != nil {
+				logrus.Debugf("Failed to get relative path: %v", err)
+				continue
+			}
+			target := filepath.Join(mount.Target, relPath)
+			return &LocalAPIMap{
+				ClientPath: pathABS,
+				RemotePath: target,
+			}, true
+		}
+	}
+	return nil, false
+}
+
+// CheckPathOnRunningMachine is a convenience function that checks if a path is available
+// on any currently running machine. It combines machine inspection and path checking.
+func CheckPathOnRunningMachine(ctx context.Context, path string) (*LocalAPIMap, bool) {
+	if err := fileutils.Exists(path); errors.Is(err, fs.ErrNotExist) {
+		logrus.Debugf("Path %s does not exist locally, skipping machine check", path)
+		return nil, false
+	}
+
+	if machineMode := bindings.GetMachineMode(ctx); !machineMode {
+		logrus.Debug("Machine mode is not enabled, skipping machine check")
+		return nil, false
+	}
+
+	allProviders := provider.GetAll()
+	machineInfo, err := shim.InspectRunningMachine(allProviders, machine.ListOptions{})
+	if err != nil {
+		logrus.Debugf("Error inspecting running machine: %v", err)
+		return nil, false
+	}
+	if machineInfo == nil {
+		logrus.Debug("No running machine found")
+		return nil, false
+	}
+	return isPathAvailableOnMachine(machineInfo, path)
+}

internal/local_utils/local_utils_unsupported.go

@@ -0,0 +1,11 @@
+//go:build !remote || (!amd64 && !arm64)
+
+package local_utils
+
+import (
+	"context"
+)
+
+func CheckPathOnRunningMachine(ctx context.Context, path string) (*LocalAPIMap, bool) {
+	return nil, false
+}

pkg/api/handlers/libpod/images.go

@@ -8,8 +8,10 @@ import (
 	"errors"
 	"fmt"
 	"io"
+	"io/fs"
 	"net/http"
 	"os"
+	"path/filepath"
 	"strconv"
 	"strings"
 
@@ -36,6 +38,7 @@ import (
 	"github.com/containers/storage"
 	"github.com/containers/storage/pkg/archive"
 	"github.com/containers/storage/pkg/chrootarchive"
+	"github.com/containers/storage/pkg/fileutils"
 	"github.com/containers/storage/pkg/idtools"
 	"github.com/docker/docker/pkg/jsonmessage"
 	"github.com/gorilla/schema"
@@ -374,6 +377,44 @@ func ImagesLoad(w http.ResponseWriter, r *http.Request) {
 	utils.WriteResponse(w, http.StatusOK, loadReport)
 }
 
+func ImagesLocalLoad(w http.ResponseWriter, r *http.Request) {
+	runtime := r.Context().Value(api.RuntimeKey).(*libpod.Runtime)
+	decoder := r.Context().Value(api.DecoderKey).(*schema.Decoder)
+	query := struct {
+		Path string `schema:"path"`
+	}{}
+
+	if err := decoder.Decode(&query, r.URL.Query()); err != nil {
+		utils.Error(w, http.StatusBadRequest, fmt.Errorf("failed to parse parameters for %s: %w", r.URL.String(), err))
+		return
+	}
+
+	if query.Path == "" {
+		utils.Error(w, http.StatusBadRequest, fmt.Errorf("path query parameter is required"))
+		return
+	}
+
+	cleanPath := filepath.Clean(query.Path)
+	switch err := fileutils.Exists(cleanPath); {
+	case err == nil:
+	case errors.Is(err, fs.ErrNotExist):
+		utils.Error(w, http.StatusNotFound, fmt.Errorf("file does not exist: %q", cleanPath))
+		return
+	default:
+		utils.Error(w, http.StatusInternalServerError, fmt.Errorf("failed to access file: %w", err))
+		return
+	}
+
+	imageEngine := abi.ImageEngine{Libpod: runtime}
+	loadOptions := entities.ImageLoadOptions{Input: cleanPath}
+	loadReport, err := imageEngine.Load(r.Context(), loadOptions)
+	if err != nil {
+		utils.Error(w, http.StatusInternalServerError, fmt.Errorf("unable to load image: %w", err))
+		return
+	}
+	utils.WriteResponse(w, http.StatusOK, loadReport)
+}
+
 func ImagesImport(w http.ResponseWriter, r *http.Request) {
 	runtime := r.Context().Value(api.RuntimeKey).(*libpod.Runtime)
 	decoder := r.Context().Value(api.DecoderKey).(*schema.Decoder)

pkg/api/server/register_images.go

@@ -941,6 +941,30 @@ func (s *APIServer) registerImagesHandlers(r *mux.Router) error {
 	//   500:
 	//     $ref: '#/responses/internalError'
 	r.Handle(VersionedPath("/libpod/images/load"), s.APIHandler(libpod.ImagesLoad)).Methods(http.MethodPost)
+	// swagger:operation POST /libpod/local/images/load libpod LocalImagesLibpod
+	// ---
+	// tags:
+	//  - images
+	// summary: Load image from local path
+	// description: Load an image (oci-archive or docker-archive) from a file path accessible on the server.
+	// parameters:
+	//   - in: query
+	//     name: path
+	//     type: string
+	//     required: true
+	//     description: Path to the image archive file on the server filesystem
+	// produces:
+	// - application/json
+	// responses:
+	//   200:
+	//     $ref: "#/responses/imagesLoadResponseLibpod"
+	//   400:
+	//     $ref: "#/responses/badParamError"
+	//   404:
+	//     $ref: "#/responses/imageNotFound"
+	//   500:
+	//     $ref: '#/responses/internalError'
+	r.Handle(VersionedPath("/libpod/local/images/load"), s.APIHandler(libpod.ImagesLocalLoad)).Methods(http.MethodPost)
 	// swagger:operation POST /libpod/images/import libpod ImageImportLibpod
 	// ---
 	// tags:

pkg/bindings/connection.go

@@ -38,8 +38,9 @@ type Connection struct {
 type valueKey string
 
 const (
-	clientKey  = valueKey("Client")
-	versionKey = valueKey("ServiceVersion")
+	clientKey      = valueKey("Client")
+	versionKey     = valueKey("ServiceVersion")
+	machineModeKey = valueKey("MachineMode")
 )
 
 type ConnectError struct {
@@ -66,6 +67,13 @@ func GetClient(ctx context.Context) (*Connection, error) {
 	return nil, fmt.Errorf("%s not set in context", clientKey)
 }
 
+func GetMachineMode(ctx context.Context) bool {
+	if v, ok := ctx.Value(machineModeKey).(bool); ok {
+		return v
+	}
+	return false
+}
+
 // ServiceVersion from context build by NewConnection()
 func ServiceVersion(ctx context.Context) *semver.Version {
 	if v, ok := ctx.Value(versionKey).(*semver.Version); ok {
@@ -142,6 +150,8 @@ func NewConnectionWithIdentity(ctx context.Context, uri string, identity string,
 		return nil, newConnectError(err)
 	}
 	ctx = context.WithValue(ctx, versionKey, serviceVersion)
+
+	ctx = context.WithValue(ctx, machineModeKey, machine)
 	return ctx, nil
 }
 

pkg/bindings/images/images.go

@@ -10,6 +10,7 @@ import (
 	"strconv"
 
 	imageTypes "github.com/containers/image/v5/types"
+	"github.com/containers/podman/v5/internal/local_utils"
 	handlersTypes "github.com/containers/podman/v5/pkg/api/handlers/types"
 	"github.com/containers/podman/v5/pkg/auth"
 	"github.com/containers/podman/v5/pkg/bindings"
@@ -139,6 +140,25 @@ func Load(ctx context.Context, r io.Reader) (*types.ImageLoadReport, error) {
 	return &report, response.Process(&report)
 }
 
+func LoadLocal(ctx context.Context, m *local_utils.LocalAPIMap) (*types.ImageLoadReport, error) {
+	var report types.ImageLoadReport
+	conn, err := bindings.GetClient(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	params := url.Values{}
+	params.Set("path", m.RemotePath)
+
+	response, err := conn.DoRequest(ctx, nil, http.MethodPost, "/local/images/load", params, nil)
+	if err != nil {
+		return nil, err
+	}
+	defer response.Body.Close()
+
+	return &report, response.Process(&report)
+}
+
 // Export saves images from local storage as a tarball or image archive.  The optional format
 // parameter is used to change the format of the output.
 func Export(ctx context.Context, nameOrIDs []string, w io.Writer, options *ExportOptions) error {

pkg/domain/infra/tunnel/images.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"errors"
 	"fmt"
+	"net/http"
 	"os"
 	"strconv"
 	"strings"
@@ -14,6 +15,7 @@ import (
 	"github.com/containers/common/pkg/config"
 	"github.com/containers/image/v5/docker/reference"
 	"github.com/containers/image/v5/types"
+	"github.com/containers/podman/v5/internal/local_utils"
 	"github.com/containers/podman/v5/libpod/define"
 	"github.com/containers/podman/v5/pkg/bindings/images"
 	"github.com/containers/podman/v5/pkg/domain/entities"
@@ -221,6 +223,22 @@ func (ir *ImageEngine) Inspect(ctx context.Context, namesOrIDs []string, opts en
 }
 
 func (ir *ImageEngine) Load(ctx context.Context, opts entities.ImageLoadOptions) (*entities.ImageLoadReport, error) {
+	if localMap, ok := local_utils.CheckPathOnRunningMachine(ir.ClientCtx, opts.Input); ok {
+		report, err := images.LoadLocal(ir.ClientCtx, localMap)
+		if err == nil {
+			return report, nil
+		}
+		errModel, ok := err.(*errorhandling.ErrorModel)
+		if !ok {
+			return nil, err
+		}
+		switch errModel.ResponseCode {
+		case http.StatusNotFound, http.StatusMethodNotAllowed:
+		default:
+			return nil, err
+		}
+	}
+
 	f, err := os.Open(opts.Input)
 	if err != nil {
 		return nil, err

pkg/machine/config.go

@@ -116,6 +116,11 @@ type InspectInfo struct {
 	Rosetta            bool
 }
 
+type InternalInspectInfo struct {
+	InspectInfo
+	Mounts []*vmconfigs.Mount
+}
+
 // ImageConfig describes the bootable image for the VM
 type ImageConfig struct {
 	// IgnitionFile is the path to the filesystem where the

pkg/machine/shim/host.go

@@ -840,3 +840,59 @@ func validateDestinationPaths(dest string) error {
 	}
 	return nil
 }
+
+// InspectRunningMachine finds and returns information about the currently running machine.
+// It searches across all VM providers to find a machine in the running state.
+// Returns nil if no running machine is found.
+func InspectRunningMachine(vmstubbers []vmconfigs.VMProvider, _ machine.ListOptions) (*machine.InternalInspectInfo, error) {
+	for _, s := range vmstubbers {
+		dirs, err := env.GetMachineDirs(s.VMType())
+		if err != nil {
+			return nil, err
+		}
+		mcs, err := vmconfigs.LoadMachinesInDir(dirs)
+		if err != nil {
+			return nil, err
+		}
+		for _, mc := range mcs {
+			state, err := s.State(mc, false)
+			if err != nil {
+				return nil, err
+			}
+			if state != machineDefine.Running {
+				continue
+			}
+
+			podmanSocket, podmanPipe, err := mc.ConnectionInfo(s.VMType())
+			if err != nil {
+				return nil, err
+			}
+
+			rosetta, err := s.GetRosetta(mc)
+			if err != nil {
+				return nil, err
+			}
+
+			return &machine.InternalInspectInfo{
+				InspectInfo: machine.InspectInfo{
+					ConfigDir: *dirs.ConfigDir,
+					ConnectionInfo: machine.ConnectionConfig{
+						PodmanSocket: podmanSocket,
+						PodmanPipe:   podmanPipe,
+					},
+					Created:            mc.Created,
+					LastUp:             mc.LastUp,
+					Name:               mc.Name,
+					Resources:          mc.Resources,
+					SSHConfig:          mc.SSH,
+					State:              state,
+					UserModeNetworking: s.UserModeNetworkEnabled(mc),
+					Rootful:            mc.HostUser.Rootful,
+					Rosetta:            rosetta,
+				},
+				Mounts: mc.Mounts,
+			}, nil
+		}
+	}
+	return nil, nil
+}