Add WithFileBufferedOpener for file-backed daemon image buffering (#2214)

* Add WithFileBufferedOpener for file-backed daemon image buffering

See: kubernetes/minikube#17785
See: kubernetes/minikube#21103

* Reduce duplicate code in image_test

* Suppress G703 security warning in image.go

Added a #nosec comment to suppress security warning for file creation.

* Remove temp file using AddCleanup

* Remove confusing comment

* Code clean up

* Remove unused io import

Author: twdamhore

pkg/v1/daemon/bench_memory_test.go

@@ -0,0 +1,53 @@
+// Copyright 2026 Google LLC All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build bench_memory
+
+package daemon
+
+import (
+	"testing"
+
+	"github.com/google/go-containerregistry/pkg/name"
+)
+
+const benchImage = "elasticsearch:9.0.3"
+
+func loadAndAccess(t *testing.T, opts ...Option) {
+	t.Helper()
+	ref, err := name.ParseReference(benchImage)
+	if err != nil {
+		t.Fatalf("ParseReference: %v", err)
+	}
+
+	img, err := Image(ref, opts...)
+	if err != nil {
+		t.Fatalf("Image: %v", err)
+	}
+
+	// Access layers to trigger the docker save and buffering.
+	layers, err := img.Layers()
+	if err != nil {
+		t.Fatalf("Layers: %v", err)
+	}
+	t.Logf("loaded %d layers", len(layers))
+}
+
+func TestBenchMemoryBacked(t *testing.T) {
+	loadAndAccess(t, WithBufferedOpener())
+}
+
+func TestBenchFileBacked(t *testing.T) {
+	loadAndAccess(t, WithFileBufferedOpener())
+}

pkg/v1/daemon/image.go

@@ -18,6 +18,8 @@ import (
 	"bytes"
 	"context"
 	"io"
+	"os"
+	"runtime"
 	"sync"
 	"time"
 
@@ -46,12 +48,13 @@ type imageOpener struct {
 	ref name.Reference
 	ctx context.Context
 
-	buffered bool
-	client   Client
+	bufferMode bufferMode
+	client     Client
 
-	once  sync.Once
-	bytes []byte
-	err   error
+	once    sync.Once
+	bytes   []byte
+	tmpPath string
+	err     error
 }
 
 func (i *imageOpener) saveImage() (io.ReadCloser, error) {
@@ -76,13 +79,50 @@ func (i *imageOpener) bufferedOpener() (io.ReadCloser, error) {
 	return io.NopCloser(bytes.NewReader(i.bytes)), i.err
 }
 
+func (i *imageOpener) fileBackedOpener() (io.ReadCloser, error) {
+	i.once.Do(func() {
+		rc, err := i.saveImage()
+		if err != nil {
+			i.err = err
+			return
+		}
+		defer rc.Close()
+
+		f, err := os.CreateTemp("", "go-containerregistry-*.tar")
+		if err != nil {
+			i.err = err
+			return
+		}
+
+		if _, err := io.Copy(f, rc); err != nil {
+			f.Close()
+			os.Remove(f.Name())
+			i.err = err
+			return
+		}
+		f.Close()
+		i.tmpPath = f.Name()
+
+		runtime.AddCleanup(i, func(path string) {
+			_ = os.Remove(path)
+		}, i.tmpPath)
+	})
+
+	if i.err != nil {
+		return nil, i.err
+	}
+	return os.Open(i.tmpPath)
+}
+
 func (i *imageOpener) opener() tarball.Opener {
-	if i.buffered {
+	switch i.bufferMode {
+	case bufferMemory:
 		return i.bufferedOpener
+	case bufferFile:
+		return i.fileBackedOpener
+	default:
+		return i.saveImage
 	}
-
-	// To avoid storing the tarball in memory, do a save every time we need to access something.
-	return i.saveImage
 }
 
 // Image provides access to an image reference from the Docker daemon,
@@ -95,10 +135,10 @@ func Image(ref name.Reference, options ...Option) (v1.Image, error) {
 	}
 
 	i := &imageOpener{
-		ref:      ref,
-		buffered: o.buffered,
-		client:   o.client,
-		ctx:      o.ctx,
+		ref:        ref,
+		bufferMode: o.bufferMode,
+		client:     o.client,
+		ctx:        o.ctx,
 	}
 
 	img := &image{

pkg/v1/daemon/image_test.go

@@ -201,6 +201,89 @@ func TestImage(t *testing.T) {
 	}
 }
 
+func TestImageFileBuffered(t *testing.T) {
+	t.Run("success", func(t *testing.T) {
+		mc := &MockClient{
+			path:        imagePath,
+			inspectResp: inspectResp,
+		}
+
+		tag, err := name.NewTag("unused", name.WeakValidation)
+		if err != nil {
+			t.Fatalf("error creating test name: %s", err)
+		}
+
+		ref, err := tarball.ImageFromPath(imagePath, nil)
+		if err != nil {
+			t.Fatalf("error loading test image: %s", err)
+		}
+
+		dmn, err := Image(tag, WithClient(mc), WithFileBufferedOpener())
+		if err != nil {
+			t.Fatalf("Image(): %v", err)
+		}
+
+		if err := compare.Images(ref, dmn); err != nil {
+			t.Errorf("compare.Images: %v", err)
+		}
+		if err := validate.Image(dmn); err != nil {
+			t.Errorf("validate.Image: %v", err)
+		}
+
+		// The concrete *image should have a temp file after access.
+		img := dmn.(*image)
+		if img.opener.tmpPath == "" {
+			t.Fatal("expected tmpPath to be set after image access")
+		}
+		if _, err := os.Stat(img.opener.tmpPath); err != nil {
+			t.Fatalf("temp file should exist: %v", err)
+		}
+	})
+
+	t.Run("save error", func(t *testing.T) {
+		mc := &MockClient{
+			saveBody:    io.NopCloser(strings.NewReader("Loaded")),
+			saveErr:     fmt.Errorf("save failed"),
+			inspectResp: inspectResp,
+		}
+
+		tag, err := name.NewTag("unused", name.WeakValidation)
+		if err != nil {
+			t.Fatalf("error creating test name: %s", err)
+		}
+
+		dmn, err := Image(tag, WithClient(mc), WithFileBufferedOpener())
+		if err != nil {
+			t.Fatalf("Image(): %v", err)
+		}
+
+		if _, err := dmn.Layers(); err == nil || !strings.Contains(err.Error(), "save failed") {
+			t.Errorf("expected save error, got: %v", err)
+		}
+	})
+
+	t.Run("read error", func(t *testing.T) {
+		mc := &MockClient{
+			inspectResp: inspectResp,
+			saveBody:    io.NopCloser(&errReader{fmt.Errorf("read failed")}),
+		}
+
+		tag, err := name.NewTag("unused", name.WeakValidation)
+		if err != nil {
+			t.Fatalf("error creating test name: %s", err)
+		}
+
+		dmn, err := Image(tag, WithClient(mc), WithFileBufferedOpener())
+		if err != nil {
+			t.Fatalf("Image(): %v", err)
+		}
+
+		if _, err := dmn.Layers(); err == nil || !strings.Contains(err.Error(), "read failed") {
+			t.Errorf("expected read error, got: %v", err)
+		}
+	})
+}
+
 func TestImageDefaultClient(t *testing.T) {
 	wantErr := fmt.Errorf("bad client")
 	defaultClient = func() (Client, error) {

pkg/v1/daemon/options.go

@@ -29,10 +29,19 @@ type ImageOption Option
 // Option is a functional option for daemon operations.
 type Option func(*options)
 
+// bufferMode controls how the image tarball is buffered.
+type bufferMode int
+
+const (
+	bufferMemory bufferMode = iota // default: buffer entire image in memory
+	bufferNone                     // no buffering: re-save on each access
+	bufferFile                     // buffer to a temp file on disk
+)
+
 type options struct {
-	ctx      context.Context
-	client   Client
-	buffered bool
+	ctx        context.Context
+	client     Client
+	bufferMode bufferMode
 }
 
 var defaultClient = func() (Client, error) {
@@ -41,8 +50,8 @@ var defaultClient = func() (Client, error) {
 
 func makeOptions(opts ...Option) (*options, error) {
 	o := &options{
-		buffered: true,
-		ctx:      context.Background(),
+		bufferMode: bufferMemory,
+		ctx:        context.Background(),
 	}
 	for _, opt := range opts {
 		opt(o)
@@ -60,17 +69,28 @@ func makeOptions(opts ...Option) (*options, error) {
 	return o, nil
 }
 
-// WithBufferedOpener buffers the image.
+// WithBufferedOpener buffers the entire image into memory.
 func WithBufferedOpener() Option {
 	return func(o *options) {
-		o.buffered = true
+		o.bufferMode = bufferMemory
 	}
 }
 
-// WithUnbufferedOpener streams the image to avoid buffering.
+// WithUnbufferedOpener streams the image to avoid buffering it.
+// Each access triggers a new image save.
 func WithUnbufferedOpener() Option {
 	return func(o *options) {
-		o.buffered = false
+		o.bufferMode = bufferNone
+	}
+}
+
+// WithFileBufferedOpener buffers the image to a temporary file on disk.
+// This avoids holding the entire image in memory while still only
+// performing a single image save. The temporary file is cleaned up via
+// runtime.AddCleanup on the imageOpener.
+func WithFileBufferedOpener() Option {
+	return func(o *options) {
+		o.bufferMode = bufferFile
 	}
 }