feat!: allow pulling images by index sha

[AustinAbro321]

Breaking Changes

Breaking changes are limited to the SDK in src/pkg/images

• ImageWithManifest type removed → replaced by PulledImage. Pull and UnPack now return this type.
  • Old: struct { Image transform.Image; Manifest ocispec.Manifest }
  • New: struct { Image transform.Image } — the Manifest field is gone. SDK users who relied on the returned manifest must fetch it themselves from the OCI store.
• PushOptions.Arch field removed. I believe this was never actually needed, we can just push the architectures that the layout includes.

Description

This implements pulling image indexes. It adds a version requirements so that Zarf can correctly pull the sha'd images. It also changes the deploy check to allow deploying to any node when an index sha image exists in the package.

When there are multiple container images pointed to an index, Zarf will create an SBOM for each image.

Pulling Indexes place a minimumVersionRequirement of v0.76.0. Also due to our pull logic not properly handling indexes, Zarf will panic if it tries to pull a package with indexes before this change.

I considered adding a metadata field, or requiring .metadata.architecture: multi for index pulls, but I think that will cause more confusion than improvements to the UX. We don't block users from pulling sha's of different digests. I'm hoping the log of the platform during pull will be enough of an indicator to those using index sha's mistakenly.

Related Issue

Relates to #2425. I'll probably close this is merged, but I want to comment on how this doesn't implement tags or specific architectures and ask the issue thread to make an issue if this is a feature they desire.

Checklist before merging

• Test, docs, adr added or updated as needed
• Contributor Guide Steps followed
• [ ]

[netlify]

✅ Deploy Preview for zarf-docs canceled.

Name	Link
🔨 Latest commit	e939b27
🔍 Latest deploy log	https://app.netlify.com/projects/zarf-docs/deploys/6a04c3d914dcc80008babced

[codecov]

Codecov Report

❌ Patch coverage is 47.91667% with 200 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/pkg/packager/layout/sbom.go	10.90%	94 Missing and 4 partials ⚠️
src/pkg/images/common.go	58.75%	23 Missing and 10 partials ⚠️
src/pkg/zoci/pull.go	58.62%	17 Missing and 7 partials ⚠️
src/pkg/images/pull.go	60.00%	11 Missing and 3 partials ⚠️
src/pkg/packager/layout/assemble.go	79.24%	7 Missing and 4 partials ⚠️
src/pkg/images/push.go	43.75%	8 Missing and 1 partial ⚠️
src/pkg/packager/deploy.go	25.00%	8 Missing and 1 partial ⚠️
src/pkg/packager/layout/package.go	0.00%	2 Missing ⚠️

Files with missing lines	Coverage Δ
src/pkg/images/unpack.go	57.14% <100.00%> (+3.04%)	⬆️
src/pkg/packager/mirror.go	0.00% <ø> (ø)
src/pkg/packager/layout/package.go	66.78% <0.00%> (+1.35%)	⬆️
src/pkg/images/push.go	48.80% <43.75%> (-0.50%)	⬇️
src/pkg/packager/deploy.go	3.98% <25.00%> (+0.11%)	⬆️
src/pkg/packager/layout/assemble.go	45.18% <79.24%> (+2.00%)	⬆️
src/pkg/images/pull.go	50.13% <60.00%> (-0.27%)	⬇️
src/pkg/zoci/pull.go	51.64% <58.62%> (-0.53%)	⬇️
src/pkg/images/common.go	43.07% <58.75%> (+8.36%)	⬆️
src/pkg/packager/layout/sbom.go	37.83% <10.90%> (-10.38%)	⬇️

... and 14 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[brandtkeller]

More for my education looking at the OCI spec -

1. do we need to consider OS? Variety of implications here
2. seems unlikely but will there ever be a case of a shared layer?

[AustinAbro321]

1. For now no, we hardcode os: linux when pulling packages.
2. It's technically possible, this function should have had unit tests anyhow. Added logic to handle this