feat(builder): Add rootfs implementation for reading OCI images by craciunoiuc · Pull Request #413 · unikraft-cloud/cli

craciunoiuc · 2026-07-09T11:43:16Z

Tested work and it seemed fine. Pasting again uses:
Case 1:

rootfs:
  format: erofs
  type: oci
  source: index.unikraft.io/test/check-pr:latest

Case 2:

rootfs:
  format: erofs
  type: oci
  source: index.docker.io/hello-world:latest

~~You can use these prefixes: oci://, oci-layout://, oci-archive:// taken from image-spec:~~

case imagespec.URISchemeOCI, imagespec.URISchemeOCILayout, imagespec.URISchemeOCIArchive:

We decided to use only the oci type variable.

~~Also needs another bump to the gomod.~~

Closes: TOOL-1073

craciunoiuc · 2026-07-09T11:44:32Z

let me know if these single use functions you want to inline

I found them significant enough to keep separate for now

Copilot

Pull request overview

Adds support in the builder to treat OCI image references (registry, OCI layout, OCI archive) as rootfs sources, including logic to unpack regular OCI layers into a rootfs and to use a Unikraft-specific initrd component when present.

Changes:

Detect OCI rootfs sources via URI schemes and route BuildRootfs to a new OCI implementation.
Implement buildRootfsOCI to load OCI images per requested platform, flatten layers into a directory, and package into CPIO/EROFS.
Update kraftfile-to-buildopts translation and expand unit/integration-style tests for OCI sources.

Reviewed changes

Copilot reviewed 6 out of 7 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
internal/builder/rootfs.go	Adds OCI source detection + `buildRootfsOCI` (load, platform match, layer flatten, repack).
internal/builder/rootfs_test.go	Adds DetectSourceType tests for OCI schemes and integration-style rootfs OCI tests.
internal/builder/rootfs_oci_test.go	Adds helpers to generate local OCI archives used by tests.
internal/builder/kraftfile.go	Avoids filepath-joining when rootfs/ROM source is an OCI reference or explicitly typed OCI.
internal/builder/kraftfile_test.go	Adds coverage for OCI paths/types in kraftfile-to-buildopts conversion.
go.mod	Pulls in new (indirect) deps required by containerd/v2 usage.
go.sum	Updates sums for newly introduced transitive dependencies.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

craciunoiuc · 2026-07-31T07:25:43Z

+			return nil, fmt.Errorf("could not open flattened rootfs image as filesystem: %w", err)
+		}
+
+		f, err := os.CreateTemp("", "unikraft-rootfs-*."+string(opts.Rootfs.Format))


We need to start to think if we want to start moving these image build operations into the local directory

Tmpfs gets really crowded when we chuck so many image artifacts into it

Copilot

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

internal/builder/rootfs.go:57

cfg.Labels = opts.Labels overwrites any labels coming from the base image config even when opts.Labels is nil/unset, which loses inherited labels for OCI-rootfs builds (and any other path that uses applyConfigOverrides). Consider only overriding labels when the caller actually provided them (e.g., if opts.Labels != nil { ... }), or merge maps so explicitly-provided keys override while preserving the rest.

func applyConfigOverrides(base ocispec.ImageConfig, opts BuildOpts) ocispec.ImageConfig {
	cfg := base
	if opts.Cmd != nil {
		cfg.Cmd = opts.Cmd
	}
	if opts.Env != nil {
		env := make([]string, 0, len(opts.Env)+len(cfg.Env))
		for _, kv := range opts.Env {
			env = append(env, fmt.Sprintf("%s=%s", kv.Key, kv.Value))
		}
		cfg.Env = append(env, cfg.Env...)
	}
	cfg.Labels = opts.Labels
	return cfg
}

internal/builder/rootfs_oci_test.go:90

In OCI image config, RootFS.DiffIDs are expected to be the digests of the uncompressed layer tar streams (diffIDs), while the manifest layer descriptors typically use the digest of the (often compressed) blob. Here diffIDs are derived from desc.Digest (from tarGzipLayer), which makes the fixture OCI config non-spec-compliant and could break consumers that validate diffIDs. Consider computing diffIDs from the uncompressed tar bytes (or streaming hasher before gzip) while keeping desc.Digest for the compressed blob.

	diffIDs := make([]digest.Digest, 0, len(layerDescs))
	for _, desc := range layerDescs {
		diffIDs = append(diffIDs, desc.Digest)
	}

	config := ocispec.Image{
		Platform: ocispec.Platform{
			Architecture: "amd64",
			OS:           "linux",
		},
		Config: ocispec.ImageConfig{
			Cmd: []string{"/bin/sh"},
		},
		RootFS: ocispec.RootFS{
			Type:    "layers",
			DiffIDs: diffIDs,
		},
	}

Uses buildkit to download and use OCI images. Works with both regular images, and Unikraft images. Unikraft images have their rootfs already packaged so we fast forward. Signed-off-by: Cezar Craciunoiu <cezar@unikraft.io>

jedevc · 2026-08-07T15:44:58Z

+
+// errSourceNotExist is returned by DetectSourceType when the source path is not
+// present on disk.
+var errSourceNotExist = errors.New("rootfs path does not exist")


fs.ErrFileNotFound or whatever it's called 🤔

jedevc · 2026-08-07T15:46:12Z

+// detectPackagedFormat reports the rootfs format of an already-packaged file.
+func detectPackagedFormat(path string) (kraftfile.FsType, error) {
+	switch {
+	case gocpio.IsValidPath(path):
+		return kraftfile.FsTypeCpio, nil
+	case goerofs.IsValidPath(path):
+		return kraftfile.FsTypeErofs, nil
+	default:
+		return "", fmt.Errorf("could not detect rootfs format of %q", path)
+	}
+}


We can use this in DetectSourceType too.

jedevc · 2026-08-07T15:48:47Z

 		opts.Rootfs.Format = kf.Rootfs.Format
 		opts.Rootfs.Type = kf.Rootfs.Source.Type
 		opts.Rootfs.Dockerfile = kf.Rootfs.Source.Dockerfile
-		if opts.Rootfs.Dockerfile != "" && opts.Rootfs.Type == "" {


I think it makes sense to call resolveSource here? Why do we defer it?

The opts are invalid, we should make them valid here.

jedevc · 2026-08-07T15:51:10Z

+	}
+
+	if root != "" {
+		fsOpts.Path = filepath.Join(root, fsOpts.Path)


This feels a bit icky. Instead, the caller should resolve these, it should determine these, instead of magically combining them here.

jedevc · 2026-08-07T15:51:46Z

 type BuildOpts struct {
-	Rootfs FSOpts
-	Roms   []FSOpts
+	RootPath string


Add a comment explaining what this is for.

jedevc · 2026-08-07T16:11:43Z

+		ref += "@" + src.Descriptor.Digest.String()
+	}
+
+	imagePlatform := getPlatforms([]ocispec.Platform{src.Image.Platform})[0].Platform


Split this to getPlatform, then this reads a lot better.

jedevc · 2026-08-07T16:12:50Z

+// nopWriteCloser adapts a writer we do not own into an io.WriteCloser.
+type nopWriteCloser struct {
+	io.Writer
+}
+
+func (nopWriteCloser) Close() error { return nil }


Make this an x/io helper.

jedevc · 2026-08-07T16:13:55Z

-	sourceType, err := builder.DetectSourceType(c.Source)
-	if err != nil {
-		return fmt.Errorf("detecting source type for %q: %w", c.Source, err)
-	}


👀 this feels weird to remove.

I really liked the previous property of opts passed in that once we passed them in they were ready to go. Not anything left to be resolved, or defaults.

jedevc · 2026-08-07T16:15:33Z

+func digestHex(dgst digest.Digest) string {
+	return strings.TrimPrefix(string(dgst), "sha256:")
+}


replace with dgst.Encoded().

jedevc · 2026-08-07T16:16:22Z

+// runBuildRootfsOCI calls BuildRootfs against a local oci-archive source. Only
+// usable for unikraft images, whose initrd component is read directly and so
+// needs no BuildKit.
+func runBuildRootfsOCI(t *testing.T, opts BuildOpts) []*imagespec.Image {
+	t.Helper()
+
+	imgs, err := BuildRootfs(rootfsOCIUnitContext(t), opts)
+	require.NoError(t, err)
+	t.Cleanup(func() {
+		for _, img := range imgs {
+			_ = img.Close()
+		}
+	})
+	return imgs
+}
+
+// runBuildRootfsOCIBuildkit calls BuildRootfs with BuildKit wired up, which
+// flattening the layers of a regular OCI image requires. Since those are read
+// from a registry, this needs network access too.
+func runBuildRootfsOCIBuildkit(t *testing.T, opts BuildOpts) []*imagespec.Image {
+	t.Helper()
+
+	return runBuildRootfsIntegration(t, rootfsIntegrationContext(t), opts)
+}


What are these helpers 😓

craciunoiuc requested review from Copilot and jedevc July 9, 2026 11:43

Copilot started reviewing on behalf of craciunoiuc July 9, 2026 11:43 View session

Copilot AI reviewed Jul 9, 2026

View reviewed changes

Comment thread internal/builder/rootfs_oci_test.go Outdated

jedevc reviewed Jul 10, 2026

View reviewed changes

Comment thread internal/builder/rootfs.go Outdated

Comment thread internal/builder/kraftfile.go Outdated

Comment thread internal/builder/rootfs.go Outdated

Comment thread internal/builder/rootfs.go Outdated

craciunoiuc force-pushed the craciunoiuc/handle-oci-type branch from 90f96a2 to ae59715 Compare July 30, 2026 14:34

craciunoiuc commented Jul 30, 2026

View reviewed changes

Comment thread internal/builder/rootfs.go Outdated

craciunoiuc marked this pull request as draft July 30, 2026 14:59

craciunoiuc force-pushed the craciunoiuc/handle-oci-type branch 3 times, most recently from c3ae0df to fe4bd3f Compare July 30, 2026 18:59

craciunoiuc commented Jul 31, 2026

View reviewed changes

Comment thread internal/builder/rootfs.go Outdated

craciunoiuc commented Jul 31, 2026

View reviewed changes

craciunoiuc force-pushed the craciunoiuc/handle-oci-type branch 3 times, most recently from 4ba3dbf to e7d40aa Compare July 31, 2026 09:03

craciunoiuc requested a review from Copilot July 31, 2026 09:08

Copilot started reviewing on behalf of craciunoiuc July 31, 2026 09:08 View session

Copilot stopped reviewing on behalf of craciunoiuc due to an error July 31, 2026 09:11
An unexpected error occurred. For more details, see the detailed logs in GitHub Actions.

Copilot AI reviewed Jul 31, 2026

View reviewed changes

Comment thread internal/builder/rootfs.go

feat(builder): Add rootfs implementation for reading OCI images

5efd1e1

Uses buildkit to download and use OCI images. Works with both regular images, and Unikraft images. Unikraft images have their rootfs already packaged so we fast forward. Signed-off-by: Cezar Craciunoiu <cezar@unikraft.io>

craciunoiuc force-pushed the craciunoiuc/handle-oci-type branch from e7d40aa to 5efd1e1 Compare July 31, 2026 09:32

craciunoiuc marked this pull request as ready for review July 31, 2026 15:21

jedevc self-requested a review July 31, 2026 15:29

jedevc reviewed Aug 7, 2026

View reviewed changes

Uh oh!

Conversation

craciunoiuc commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

craciunoiuc commented Jul 9, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

craciunoiuc commented Jul 9, 2026 •

edited

Loading