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
- Improved error handling for non-JSON API responses

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

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

Author: Honny1

pkg/api/handlers/libpod/images.go

@@ -10,6 +10,7 @@ import (
 	"io"
 	"net/http"
 	"os"
+	"path/filepath"
 	"strconv"
 	"strings"
 
@@ -31,6 +32,7 @@ import (
 	"github.com/containers/podman/v5/pkg/domain/infra/abi"
 	domainUtils "github.com/containers/podman/v5/pkg/domain/utils"
 	"github.com/containers/podman/v5/pkg/errorhandling"
+	"github.com/containers/podman/v5/pkg/machine"
 	"github.com/containers/podman/v5/pkg/util"
 	utils2 "github.com/containers/podman/v5/utils"
 	"github.com/containers/storage"
@@ -374,6 +376,41 @@ 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)
+
+	localMap := machine.LocalAPIMap{}
+	if err := json.NewDecoder(r.Body).Decode(&localMap); err != nil {
+		utils.Error(w, http.StatusBadRequest, fmt.Errorf("failed to decode request body: %w", err))
+		return
+	}
+
+	if localMap.RemotePath == "" {
+		utils.Error(w, http.StatusBadRequest, fmt.Errorf("RemotePath is required"))
+		return
+	}
+
+	cleanPath := filepath.Clean(localMap.RemotePath)
+	switch _, err := os.Stat(cleanPath); {
+	case err == nil:
+	case os.IsNotExist(err):
+		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

@@ -955,6 +955,40 @@ 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 ImageLoadLocalLibpod
+	// ---
+	// tags:
+	//  - images
+	// summary: Load image from path on remote
+	// description: Load an image (oci-archive or docker-archive) from a file path on the remote server.
+	// parameters:
+	//   - in: body
+	//     name: localMap
+	//     required: true
+	//     description: JSON object containing the file path on the remote server
+	//     schema:
+	//       type: object
+	//       properties:
+	//         RemotePath:
+	//           type: string
+	//           description: Path to the image archive file on the remote server
+	//           example: "/tmp/image.tar"
+	//       required:
+	//         - RemotePath
+	// consumes:
+	// - application/json
+	// 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/errors.go

@@ -47,9 +47,13 @@ func (h *APIResponse) ProcessWithError(unmarshalInto interface{}, unmarshalError
 	if h.IsConflictError() {
 		return handleError(data, unmarshalErrorInto)
 	}
-
-	// TODO should we add a debug here with the response code?
-	return handleError(data, &errorhandling.ErrorModel{})
+	if h.Response.Header.Get("Content-Type") == "application/json" {
+		return handleError(data, &errorhandling.ErrorModel{})
+	}
+	return &errorhandling.ErrorModel{
+		Message:      string(data),
+		ResponseCode: h.Response.StatusCode,
+	}
 }
 
 func CheckResponseCode(inError error) (int, error) {

pkg/bindings/images/images.go

@@ -8,13 +8,16 @@ import (
 	"net/http"
 	"net/url"
 	"strconv"
+	"strings"
 
 	imageTypes "github.com/containers/image/v5/types"
 	handlersTypes "github.com/containers/podman/v5/pkg/api/handlers/types"
 	"github.com/containers/podman/v5/pkg/auth"
 	"github.com/containers/podman/v5/pkg/bindings"
 	"github.com/containers/podman/v5/pkg/domain/entities/reports"
 	"github.com/containers/podman/v5/pkg/domain/entities/types"
+	"github.com/containers/podman/v5/pkg/machine"
+	jsoniter "github.com/json-iterator/go"
 )
 
 // Exists a lightweight way to determine if an image exists in local storage.  It returns a
@@ -139,6 +142,27 @@ func Load(ctx context.Context, r io.Reader) (*types.ImageLoadReport, error) {
 	return &report, response.Process(&report)
 }
 
+func LoadLocal(ctx context.Context, m *machine.LocalAPIMap) (*types.ImageLoadReport, error) {
+	var report types.ImageLoadReport
+	conn, err := bindings.GetClient(ctx)
+	if err != nil {
+		return nil, err
+	}
+
+	localAPImapString, err := jsoniter.MarshalToString(m)
+	if err != nil {
+		return nil, err
+	}
+
+	response, err := conn.DoRequest(ctx, strings.NewReader(localAPImapString), http.MethodPost, "/local/images/load", nil, 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"
@@ -20,6 +21,7 @@ import (
 	"github.com/containers/podman/v5/pkg/domain/entities/reports"
 	"github.com/containers/podman/v5/pkg/domain/utils"
 	"github.com/containers/podman/v5/pkg/errorhandling"
+	"github.com/containers/podman/v5/pkg/machine/shim"
 	"github.com/containers/storage/pkg/archive"
 )
 
@@ -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 := shim.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

@@ -114,6 +114,13 @@ type InspectInfo struct {
 	UserModeNetworking bool
 	Rootful            bool
 	Rosetta            bool
+	Mounts             []*vmconfigs.Mount
+}
+
+// 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"`
 }
 
 // ImageConfig describes the bootable image for the VM

pkg/machine/shim/host.go

@@ -2,6 +2,7 @@ package shim
 
 import (
 	"bufio"
+	"context"
 	"errors"
 	"fmt"
 	"io"
@@ -14,6 +15,8 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/containers/common/pkg/config"
+	"github.com/containers/podman/v5/pkg/bindings"
 	"github.com/containers/podman/v5/pkg/machine"
 	"github.com/containers/podman/v5/pkg/machine/connection"
 	machineDefine "github.com/containers/podman/v5/pkg/machine/define"
@@ -840,3 +843,159 @@ 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.InspectInfo, 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.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
+}
+
+// isConnectionToMachine checks if the current connection context is connected to the specified machine.
+// It compares connection URIs and socket paths to determine if they match.
+func isConnectionToMachine(ctx context.Context, machineInfo *machine.InspectInfo) bool {
+	conn, err := bindings.GetClient(ctx)
+	if err != nil {
+		logrus.Warnf("Error getting client connection: %v", err)
+		return false
+	}
+	logrus.Debugf("Checking connection URI: %s", conn.URI.String())
+	cfg, err := config.Default()
+	if err != nil {
+		logrus.Warnf("Error getting default config: %v", err)
+		return false
+	}
+	cons, err := cfg.GetAllConnections()
+	if err != nil {
+		logrus.Warnf("Error getting connections: %v", err)
+		return false
+	}
+
+	for _, con := range cons {
+		if con.URI == conn.URI.String() && con.IsMachine {
+			return true
+		}
+	}
+
+	if machineInfo.ConnectionInfo.PodmanSocket != nil {
+		if filepath.Clean(machineInfo.ConnectionInfo.PodmanSocket.Path) == filepath.Clean(conn.URI.Path) {
+			return true
+		}
+	}
+
+	if machineInfo.ConnectionInfo.PodmanPipe != nil {
+		if filepath.Clean(machineInfo.ConnectionInfo.PodmanPipe.Path) == filepath.Clean(conn.URI.Path) {
+			return true
+		}
+	}
+	return false
+}
+
+// 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(ctx context.Context, machineInfo *machine.InspectInfo, path string) (*machine.LocalAPIMap, bool) {
+	if machineInfo == nil || path == "" {
+		return nil, false
+	}
+
+	if !isConnectionToMachine(ctx, machineInfo) {
+		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 &machine.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) (*machine.LocalAPIMap, bool) {
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		logrus.Debugf("Path %s does not exist locally, skipping machine check", path)
+		return nil, false
+	}
+
+	allProviders := provider.GetAll()
+	machineInfo, err := 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(ctx, machineInfo, path)
+}