feat: support multi-arch image indexes (upstream GoogleContainerTools#503)

Adapts upstream PR GoogleContainerTools#503 ("Add support for multi-arch image indexes") to
the fork. Upstream placed the index-selection logic inline in test.go,
but the fork's GoogleContainerTools#554 since centralized OCI-layout loading into
pkgutil.ImageFromOCILayout (shared by the Docker daemon path and the Tar
driver). The platform-based selection is added there instead, so both
drivers gain multi-arch support. ImageFromOCILayout now takes a platform
string; callers pass opts.Platform / args.Platform.

Two fork-authored changes beyond the upstream diff:

- Nil-platform guard: v1.Descriptor.Platform is a nil-able *v1.Platform
  (OCI permits an index descriptor with no platform), and Satisfies has
  a value receiver, so the upstream desc.Platform.Satisfies(...) call
  panics with a nil dereference on such descriptors. findImageInIndex
  now skips any descriptor whose Platform is nil. Covered by a unit test
  that panics without the guard and passes with it.

- parsePlatform replaced with go-containerregistry's v1.ParsePlatform,
  which accepts variants (e.g. linux/arm/v7) that the hand-rolled parser
  rejected.

Also fixes the bundled shell test: numeric comparison uses -lt instead
of the string operator <, and the multi-arch temp dir no longer clobbers
the $tmp used by the following tar-driver test.

Co-authored-by: Joel Sing <jsing@canva.com>
Upstream-PR: GoogleContainerTools#503

Author: thomasdesr

cmd/container-structure-test/app/cmd/test.go

@@ -113,7 +113,7 @@ func run(out io.Writer) error {
 		if opts.Driver == drivers.Tar {
 			args.OCILayout = opts.ImageFromLayout
 		} else {
-			img, desc, err := pkgutil.ImageFromOCILayout(opts.ImageFromLayout)
+			img, desc, err := pkgutil.ImageFromOCILayout(opts.ImageFromLayout, opts.Platform)
 			if err != nil {
 				logrus.Fatalf("loading OCI layout %s: %v", opts.ImageFromLayout, err)
 			}

internal/pkgutil/image_utils.go

@@ -18,6 +18,7 @@ package pkgutil
 
 import (
 	"archive/tar"
+	stderrors "errors"
 	"fmt"
 	"io"
 	"io/ioutil"
@@ -204,10 +205,20 @@ func ImageFromV1(img v1.Image, source string) (Image, error) {
 	}, nil
 }
 
+// maxSubIndexes caps how deep findImageInIndex recurses into nested image
+// indexes, guarding against malicious or malformed layouts.
+const maxSubIndexes = 5
+
+// errNoImageFound reports that no descriptor in an index satisfied the
+// requested platform. It is used as a sentinel so recursion can distinguish
+// "this subtree had no match" from a real error.
+var errNoImageFound = stderrors.New("no compatible image found")
+
 // ImageFromOCILayout loads a single image from an OCI image layout directory.
-// It returns the image and its descriptor (for access to annotations).
-// The layout must contain exactly one non-index manifest entry.
-func ImageFromOCILayout(path string) (v1.Image, v1.Descriptor, error) {
+// It returns the image and its descriptor (for access to annotations). The
+// layout must contain exactly one entry. When that entry is a multi-arch image
+// index, the descriptor matching platform (e.g. "linux/amd64") is selected.
+func ImageFromOCILayout(path, platform string) (v1.Image, v1.Descriptor, error) {
 	l, err := layout.ImageIndexFromPath(path)
 	if err != nil {
 		return nil, v1.Descriptor{}, errors.Wrapf(err, "loading %s as OCI layout", path)
@@ -222,7 +233,19 @@ func ImageFromOCILayout(path string) (v1.Image, v1.Descriptor, error) {
 
 	desc := m.Manifests[0]
 	if desc.MediaType.IsIndex() {
-		return nil, v1.Descriptor{}, errors.New("multi-arch images are not supported yet")
+		requirements, err := v1.ParsePlatform(platform)
+		if err != nil {
+			return nil, v1.Descriptor{}, errors.Wrapf(err, "parsing platform %q", platform)
+		}
+		childIndex, err := l.ImageIndex(desc.Digest)
+		if err != nil {
+			return nil, v1.Descriptor{}, errors.Wrapf(err, "reading image index from %s", path)
+		}
+		img, err := findImageInIndex(childIndex, requirements, 0)
+		if err != nil {
+			return nil, v1.Descriptor{}, errors.Wrapf(err, "selecting image for platform %q from %s", platform, path)
+		}
+		return img, desc, nil
 	}
 
 	img, err := l.Image(desc.Digest)
@@ -233,6 +256,45 @@ func ImageFromOCILayout(path string) (v1.Image, v1.Descriptor, error) {
 	return img, desc, nil
 }
 
+// findImageInIndex walks an image index, recursing into nested sub-indexes up
+// to maxSubIndexes deep, and returns the first image whose platform satisfies
+// requirements. Descriptors without a platform field (which OCI permits) are
+// skipped rather than dereferenced, since Descriptor.Platform is a nil-able
+// pointer and Satisfies has a value receiver.
+func findImageInIndex(index v1.ImageIndex, requirements *v1.Platform, depth int) (v1.Image, error) {
+	if depth > maxSubIndexes {
+		return nil, errors.Errorf("too many sub-indexes (>%d)", maxSubIndexes)
+	}
+
+	manifest, err := index.IndexManifest()
+	if err != nil {
+		return nil, errors.Wrap(err, "reading index manifest")
+	}
+
+	for _, desc := range manifest.Manifests {
+		if desc.MediaType.IsImage() {
+			if desc.Platform == nil {
+				continue
+			}
+			if desc.Platform.Satisfies(*requirements) {
+				return index.Image(desc.Digest)
+			}
+		}
+		if desc.MediaType.IsIndex() {
+			childIndex, err := index.ImageIndex(desc.Digest)
+			if err != nil {
+				return nil, err
+			}
+			img, err := findImageInIndex(childIndex, requirements, depth+1)
+			if !stderrors.Is(err, errNoImageFound) {
+				return img, err
+			}
+		}
+	}
+
+	return nil, errNoImageFound
+}
+
 func getExtractPathForName(name string, cacheDir string) (string, error) {
 	path := cacheDir
 	var err error

internal/pkgutil/image_utils_test.go

@@ -64,6 +64,95 @@ func writeOCILayout(t *testing.T, imgs ...v1.Image) string {
 	return dir
 }
 
+// platformedImage pairs an image with the platform descriptor it should be
+// indexed under. A nil platform produces an index entry whose Descriptor.Platform
+// is nil, which OCI permits and which must not panic Satisfies.
+type platformedImage struct {
+	img      v1.Image
+	platform *v1.Platform
+}
+
+// writeMultiArchOCILayout writes a single multi-arch image index (built from the
+// given images and platforms) as the sole entry of a fresh OCI layout directory.
+// This mirrors the shape produced by `crane pull --format=oci` of a manifest list.
+func writeMultiArchOCILayout(t *testing.T, entries ...platformedImage) string {
+	t.Helper()
+
+	idx := v1.ImageIndex(empty.Index)
+	for _, e := range entries {
+		add := mutate.IndexAddendum{Add: e.img}
+		if e.platform != nil {
+			add.Descriptor = v1.Descriptor{Platform: e.platform}
+		}
+		idx = mutate.AppendManifests(idx, add)
+	}
+
+	dir := t.TempDir()
+	l, err := layout.Write(dir, empty.Index)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if err := l.AppendIndex(idx); err != nil {
+		t.Fatal(err)
+	}
+	return dir
+}
+
+func TestImageFromOCILayoutSelectsMatchingPlatform(t *testing.T) {
+	amd64 := testImageWithFile(t, "etc/amd64.txt", "amd64-data")
+	arm64 := testImageWithFile(t, "etc/arm64.txt", "arm64-data")
+	dir := writeMultiArchOCILayout(t,
+		platformedImage{img: amd64, platform: &v1.Platform{OS: "linux", Architecture: "amd64"}},
+		platformedImage{img: arm64, platform: &v1.Platform{OS: "linux", Architecture: "arm64"}},
+	)
+
+	gotImg, _, err := ImageFromOCILayout(dir, "linux/arm64")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	wantDigest, err := arm64.Digest()
+	if err != nil {
+		t.Fatal(err)
+	}
+	gotDigest, err := gotImg.Digest()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if gotDigest != wantDigest {
+		t.Fatalf("selected image digest = %v, want arm64 image %v", gotDigest, wantDigest)
+	}
+}
+
+// TestImageFromOCILayoutSkipsNilPlatform guards the nil-deref fix: an index
+// descriptor without a platform field must be skipped rather than passed to the
+// value-receiver Satisfies, which would panic on a nil *v1.Platform.
+func TestImageFromOCILayoutSkipsNilPlatform(t *testing.T) {
+	noPlatform := testImageWithFile(t, "etc/nop.txt", "no-platform-data")
+	amd64 := testImageWithFile(t, "etc/amd64.txt", "amd64-data")
+	dir := writeMultiArchOCILayout(t,
+		platformedImage{img: noPlatform, platform: nil},
+		platformedImage{img: amd64, platform: &v1.Platform{OS: "linux", Architecture: "amd64"}},
+	)
+
+	gotImg, _, err := ImageFromOCILayout(dir, "linux/amd64")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	wantDigest, err := amd64.Digest()
+	if err != nil {
+		t.Fatal(err)
+	}
+	gotDigest, err := gotImg.Digest()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if gotDigest != wantDigest {
+		t.Fatalf("selected image digest = %v, want amd64 image %v", gotDigest, wantDigest)
+	}
+}
+
 func TestImageFromV1ExtractsFilesystem(t *testing.T) {
 	img := testImageWithFile(t, "etc/known.txt", "image-data")
 
@@ -100,7 +189,7 @@ func TestImageFromOCILayoutLoadsSingleImage(t *testing.T) {
 	img := testImageWithFile(t, "etc/known.txt", "image-data")
 	dir := writeOCILayout(t, img)
 
-	gotImg, _, err := ImageFromOCILayout(dir)
+	gotImg, _, err := ImageFromOCILayout(dir, "linux/amd64")
 	if err != nil {
 		t.Fatal(err)
 	}
@@ -121,7 +210,7 @@ func TestImageFromOCILayoutLoadsSingleImage(t *testing.T) {
 func TestImageFromOCILayoutMissingPath(t *testing.T) {
 	missing := filepath.Join(t.TempDir(), "does-not-exist")
 
-	_, _, err := ImageFromOCILayout(missing)
+	_, _, err := ImageFromOCILayout(missing, "linux/amd64")
 	if err == nil {
 		t.Fatal("ImageFromOCILayout accepted a missing layout path")
 	}
@@ -133,7 +222,7 @@ func TestImageFromOCILayoutRejectsMultipleEntries(t *testing.T) {
 		testImageWithFile(t, "etc/b.txt", "b-data"),
 	)
 
-	_, _, err := ImageFromOCILayout(dir)
+	_, _, err := ImageFromOCILayout(dir, "linux/amd64")
 	if err == nil {
 		t.Fatal("ImageFromOCILayout accepted a layout with multiple entries")
 	}

pkg/drivers/tar_driver.go

@@ -35,7 +35,7 @@ type TarDriver struct {
 
 func NewTarDriver(args DriverConfig) (Driver, error) {
 	if args.OCILayout != "" {
-		image, err := imageFromOCILayout(args.OCILayout)
+		image, err := imageFromOCILayout(args.OCILayout, args.Platform)
 		if err != nil {
 			return nil, errors.Wrap(err, "processing OCI layout")
 		}
@@ -77,8 +77,8 @@ func NewTarDriver(args DriverConfig) (Driver, error) {
 	}, nil
 }
 
-func imageFromOCILayout(path string) (pkgutil.Image, error) {
-	img, _, err := pkgutil.ImageFromOCILayout(path)
+func imageFromOCILayout(path, platform string) (pkgutil.Image, error) {
+	img, _, err := pkgutil.ImageFromOCILayout(path, platform)
 	if err != nil {
 		return pkgutil.Image{}, err
 	}

tests/amd64/fluent_bit_test.yaml

@@ -0,0 +1,19 @@
+schemaVersion: '2.0.0' # Make sure to test the latest schema version
+commandTests:
+- name: 'fluent-bit'
+  command: '/fluent-bit/bin/fluent-bit'
+  args: ['--version']
+  expectedOutput: ['Fluent Bit v4.0.4']
+fileContentTests:
+- name: 'Passwd file'
+  expectedContents: ['root:x:0:0:root:/root:/sbin/nologin']
+  path: '/etc/passwd'
+fileExistenceTests:
+- name: 'Root'
+  path: '/'
+  shouldExist: true
+  uid: 0
+  gid: 0
+- name: 'libc'
+  path: '/lib/x86_64-linux-gnu/libc.so.6'
+  shouldExist: true

tests/arm64/fluent_bit_test.yaml

@@ -0,0 +1,19 @@
+schemaVersion: '2.0.0' # Make sure to test the latest schema version
+commandTests:
+- name: 'fluent-bit'
+  command: '/fluent-bit/bin/fluent-bit'
+  args: ['--version']
+  expectedOutput: ['Fluent Bit v4.0.4']
+fileContentTests:
+- name: 'Passwd file'
+  expectedContents: ['root:x:0:0:root:/root:/sbin/nologin']
+  path: '/etc/passwd'
+fileExistenceTests:
+- name: 'Root'
+  path: '/'
+  shouldExist: true
+  uid: 0
+  gid: 0
+- name: 'libc'
+  path: '/lib/aarch64-linux-gnu/libc.so.6'
+  shouldExist: true

tests/structure_test_tests.sh

@@ -268,6 +268,41 @@ else
   echo "PASS: oci success test case"
 fi
 
+HEADER "OCI multi-arch image index test case"
+
+if [[ "$go_architecture" == "amd64" || "$go_architecture" == "arm64" ]]; then
+  test_index="cr.fluentbit.io/fluent/fluent-bit:4.0.4"
+
+  manifest=$(docker manifest inspect "$test_index")
+  if [[ $(echo "$manifest" | jq '.mediaType') != '"application/vnd.docker.distribution.manifest.list.v2+json"' ]]; then
+     echo "FAIL: multi-arch image index test case - $test_index is not an image index"
+     echo "$manifest" | jq '.mediaType'
+     failures=$((failures +1))
+  fi
+  image_count=$(echo "$manifest" | jq '.manifests | length')
+  if [[ $image_count -lt 2 ]]; then
+     echo "FAIL: multi-arch image index test case - $test_index only has $image_count image(s)"
+     failures=$((failures +1))
+  fi
+
+  tmp_index="$(mktemp -d)"
+  crane pull "$test_index" --format=oci "$tmp_index"
+
+  res=$(./out/container-structure-test test --image-from-oci-layout="$tmp_index" --default-image-tag="test.local/$test_index" --config "${test_config_dir}/fluent_bit_test.yaml" 2>&1)
+  code=$?
+  if ! [[ ("$res" =~ "PASS" && "$code" == "0") ]];
+  then
+    echo "FAIL: oci image index success test case"
+    echo "$res"
+    echo "$code"
+    failures=$((failures +1))
+  else
+    echo "PASS: oci image index test case"
+  fi
+else
+  echo "SKIP: oci image index test case not supported on $go_architecture"
+fi
+
 HEADER "OCI layout with tar driver test case"
 
 res=$(./out/container-structure-test test --driver tar --image-from-oci-layout="$tmp" --config "${test_config_dir}/ubuntu_22_04_tar_test.yaml" 2>&1)