Add container run from oci-archive

Signed-off-by: Austin Vazquez <[email protected]>

Author: austinvazquez

cmd/nerdctl/container/container_create_linux_test.go

@@ -29,6 +29,7 @@ import (
 
 	"github.com/containerd/containerd/v2/defaults"
 
+	"github.com/containerd/nerdctl/v2/cmd/nerdctl/helpers"
 	"github.com/containerd/nerdctl/v2/pkg/testutil"
 	"github.com/containerd/nerdctl/v2/pkg/testutil/nerdtest"
 	"github.com/containerd/nerdctl/v2/pkg/testutil/nettestutil"
@@ -306,3 +307,34 @@ func TestIssue2993(t *testing.T) {
 
 	testCase.Run(t)
 }
+
+func TestCreateFromOCIArchive(t *testing.T) {
+	testutil.RequiresBuild(t)
+	testutil.RegisterBuildCacheCleanup(t)
+
+	// Docker does not support creating containers from OCI archive.
+	testutil.DockerIncompatible(t)
+
+	base := testutil.NewBase(t)
+	imageName := testutil.Identifier(t)
+	containerName := testutil.Identifier(t)
+
+	teardown := func() {
+		base.Cmd("rm", "-f", containerName).Run()
+		base.Cmd("rmi", "-f", imageName).Run()
+	}
+	defer teardown()
+	teardown()
+
+	const sentinel = "test-nerdctl-create-from-oci-archive"
+	dockerfile := fmt.Sprintf(`FROM %s
+	CMD ["echo", "%s"]`, testutil.CommonImage, sentinel)
+
+	buildCtx := helpers.CreateBuildContext(t, dockerfile)
+	tag := fmt.Sprintf("%s:latest", imageName)
+	tarPath := fmt.Sprintf("%s/%s.tar", buildCtx, imageName)
+
+	base.Cmd("build", "--tag", tag, fmt.Sprintf("--output=type=oci,dest=%s", tarPath), buildCtx).AssertOK()
+	base.Cmd("create", "--rm", "--name", containerName, fmt.Sprintf("oci-archive://%s", tarPath)).AssertOK()
+	base.Cmd("start", "--attach", containerName).AssertOutContains("test-nerdctl-create-from-oci-archive")
+}

cmd/nerdctl/container/container_run_test.go

@@ -658,3 +658,31 @@ func TestRunQuiet(t *testing.T) {
 
 	assert.Assert(t, wasQuiet(result.Combined(), sentinel), "Found %s in container run output", sentinel)
 }
+
+func TestRunFromOCIArchive(t *testing.T) {
+	testutil.RequiresBuild(t)
+	testutil.RegisterBuildCacheCleanup(t)
+
+	// Docker does not support running container images from OCI archive.
+	testutil.DockerIncompatible(t)
+
+	base := testutil.NewBase(t)
+	imageName := testutil.Identifier(t)
+
+	teardown := func() {
+		base.Cmd("rmi", "-f", imageName).Run()
+	}
+	defer teardown()
+	teardown()
+
+	const sentinel = "test-nerdctl-run-from-oci-archive"
+	dockerfile := fmt.Sprintf(`FROM %s
+	CMD ["echo", "%s"]`, testutil.CommonImage, sentinel)
+
+	buildCtx := helpers.CreateBuildContext(t, dockerfile)
+	tag := fmt.Sprintf("%s:latest", imageName)
+	tarPath := fmt.Sprintf("%s/%s.tar", buildCtx, imageName)
+
+	base.Cmd("build", "--tag", tag, fmt.Sprintf("--output=type=oci,dest=%s", tarPath), buildCtx).AssertOK()
+	base.Cmd("run", "--rm", fmt.Sprintf("oci-archive://%s", tarPath)).AssertOutContainsAll(fmt.Sprintf("Loaded image: %s", tag), sentinel)
+}

docs/command-reference.md

@@ -134,6 +134,7 @@ Run a command in a new container.
 Usage: `nerdctl run [OPTIONS] IMAGE [COMMAND] [ARG...]`
 
 :nerd_face: `ipfs://` prefix can be used for `IMAGE` to pull it from IPFS. See [`ipfs.md`](./ipfs.md) for details.
+:nerd_face: `oci-archive://` prefix can be used for `IMAGE` to specify a local file system path to an OCI formatted tarball.
 
 Basic flags:
 
@@ -423,6 +424,7 @@ Create a new container.
 Usage: `nerdctl create [OPTIONS] IMAGE [COMMAND] [ARG...]`
 
 :nerd_face: `ipfs://` prefix can be used for `IMAGE` to pull it from IPFS. See [`ipfs.md`](./ipfs.md) for details.
+:nerd_face: `oci-archive://` prefix can be used for `IMAGE` to specify a local file system path to an OCI formatted tarball.
 
 The `nerdctl create` command similar to `nerdctl run -d` except the container is never started. You can then use the `nerdctl start <container_id>` command to start the container at any point.
 

pkg/cmd/container/create.go

@@ -50,6 +50,7 @@ import (
 	"github.com/containerd/nerdctl/v2/pkg/flagutil"
 	"github.com/containerd/nerdctl/v2/pkg/idgen"
 	"github.com/containerd/nerdctl/v2/pkg/imgutil"
+	"github.com/containerd/nerdctl/v2/pkg/imgutil/load"
 	"github.com/containerd/nerdctl/v2/pkg/inspecttypes/dockercompat"
 	"github.com/containerd/nerdctl/v2/pkg/ipcutil"
 	"github.com/containerd/nerdctl/v2/pkg/labels"
@@ -123,6 +124,39 @@ func Create(ctx context.Context, client *containerd.Client, args []string, netMa
 	}
 	opts = append(opts, platformOpts...)
 
+	if _, err := referenceutil.Parse(args[0]); errors.Is(err, referenceutil.ErrLoadOCIArchiveRequired) {
+		imageRef := args[0]
+
+		// Load and create the platform specified by the user.
+		// If none specified, fallback to the default platform.
+		platform := []string{}
+		if options.Platform != "" {
+			platform = append(platform, options.Platform)
+		}
+
+		images, err := load.FromOCIArchive(ctx, client, imageRef, types.ImageLoadOptions{
+			Stdout:       options.Stdout,
+			GOptions:     options.GOptions,
+			Platform:     platform,
+			AllPlatforms: false,
+			Quiet:        options.ImagePullOpt.Quiet,
+		})
+		if err != nil {
+			return nil, nil, err
+		} else if len(images) == 0 {
+			// This is a regression and should not occur.
+			return nil, nil, errors.New("OCI archive did not contain any images")
+		}
+
+		image := images[0].Name
+		// Multiple images loaded from the provided archive. Default to the first image found.
+		if len(images) != 1 {
+			log.L.Warnf("multiple images are found for the platform, defaulting to image %s...", image)
+		}
+
+		args[0] = image
+	}
+
 	var ensuredImage *imgutil.EnsuredImage
 	if !options.Rootfs {
 		var platformSS []string // len: 0 or 1

pkg/imgutil/load/load.go

@@ -22,6 +22,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"strings"
 
 	containerd "github.com/containerd/containerd/v2/client"
 	"github.com/containerd/containerd/v2/core/images"
@@ -76,6 +77,25 @@ func FromArchive(ctx context.Context, client *containerd.Client, options types.I
 	return unpackedImages, nil
 }
 
+// FromOCIArchive loads and unpacks the images from the OCI formatted archive at the provided file system path.
+func FromOCIArchive(ctx context.Context, client *containerd.Client, pathToOCIArchive string, options types.ImageLoadOptions) ([]images.Image, error) {
+	const ociArchivePrefix = "oci-archive://"
+	pathToOCIArchive = strings.TrimPrefix(pathToOCIArchive, ociArchivePrefix)
+
+	const separator = ":"
+	if strings.Contains(pathToOCIArchive, separator) {
+		subs := strings.Split(pathToOCIArchive, separator)
+		if len(subs) != 2 {
+			return nil, errors.New("too many seperators found in oci-archive path")
+		}
+		pathToOCIArchive = subs[0]
+	}
+
+	options.Input = pathToOCIArchive
+
+	return FromArchive(ctx, client, options)
+}
+
 type readCounter struct {
 	io.Reader
 	N int

pkg/referenceutil/referenceutil.go

@@ -17,6 +17,7 @@
 package referenceutil
 
 import (
+	"errors"
 	"path"
 	"strings"
 
@@ -31,6 +32,8 @@ const IPFSProtocol Protocol = "ipfs"
 const IPNSProtocol Protocol = "ipns"
 const shortIDLength = 5
 
+var ErrLoadOCIArchiveRequired = errors.New("image must be loaded from archive before parsing image reference")
+
 type ImageReference struct {
 	Protocol    Protocol
 	Digest      digest.Digest
@@ -97,6 +100,10 @@ func Parse(rawRef string) (*ImageReference, error) {
 	} else if strings.HasPrefix(rawRef, "ipns://") {
 		ir.Protocol = IPNSProtocol
 		rawRef = rawRef[7:]
+	} else if strings.HasPrefix(rawRef, "oci-archive://") {
+		// The image must be loaded from the specified archive path first
+		// before parsing the image reference specified in its OCI image manifest.
+		return nil, ErrLoadOCIArchiveRequired
 	}
 	if decodedCID, err := cid.Decode(rawRef); err == nil {
 		ir.Protocol = IPFSProtocol

pkg/referenceutil/referenceutil_test.go

@@ -273,6 +273,9 @@ func TestReferenceUtil(t *testing.T) {
 			Tag:          "latest",
 			ExplicitTag:  "",
 		},
+		"oci-archive:///tmp/build/saved-image.tar": {
+			Error: "image must be loaded from archive before parsing image reference",
+		},
 	}
 
 	for k, v := range needles {