feat!: add multi arch support

[AustinAbro321]

Breaking changes

Breaking changes are only in the SDK. ImagesWithManifests->PulledImage. This removes manifests from the struct. Instead of having to collect the manifest in several places (indexes, image archives, daemon) we check the manifest before we create the SBOM, this was our only use case for it The name PulledImage should be more resistant to future breaking changes. Unpack and Pull return PulledImage now.

Description

This adds multi arch support thorough a special package architecture "multi"

We may want to change zarf package pull so that if a multi platform exists for a Zarf OCI package, when running zarf package pull <package-oci-ref> we fallback to pull multi. This PR is already large so I didn't change anything atm.

This adds a minimum version check for v0.76.0. Also worth noting that if a multi arch package is pulled from an earlier version of Zarf then Zarf will panic, since it assumed the index.json in an OCI layout will only have manifests.

Related Issue

Relates to #2425 (arguably fixes though we may want to keep it open or break it out into other issues such as packaging only x and y architecture).

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	b023297
🔍 Latest deploy log	https://app.netlify.com/projects/zarf-docs/deploys/69f8fca32e19c900087db296

[codecov]

Codecov Report

❌ Patch coverage is 61.58445% with 257 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/pkg/images/pull.go	66.84%	48 Missing and 15 partials ⚠️
src/pkg/packager/layout/sbom.go	46.84%	42 Missing and 17 partials ⚠️
src/pkg/images/common.go	44.15%	35 Missing and 8 partials ⚠️
src/pkg/images/unpack.go	63.01%	18 Missing and 9 partials ⚠️
src/pkg/zoci/pull.go	65.45%	14 Missing and 5 partials ⚠️
src/cmd/package.go	25.00%	12 Missing ⚠️
src/pkg/packager/deploy.go	0.00%	10 Missing ⚠️
src/pkg/images/push.go	63.15%	6 Missing and 1 partial ⚠️
src/pkg/packager/layout/assemble.go	77.41%	6 Missing and 1 partial ⚠️
src/pkg/packager/load/load.go	40.00%	1 Missing and 2 partials ⚠️
... and 4 more

Files with missing lines	Coverage Δ
src/cmd/utils.go	100.00% <100.00%> (ø)
src/config/config.go	60.86% <100.00%> (+60.86%)	⬆️
src/internal/api/v1alpha1/validate.go	91.21% <100.00%> (+0.49%)	⬆️
src/pkg/packager/create.go	54.54% <100.00%> (+0.46%)	⬆️
src/pkg/packager/filters/arch.go	100.00% <100.00%> (ø)
src/pkg/packager/layout/package.go	66.34% <100.00%> (+0.92%)	⬆️
src/pkg/packager/load.go	62.89% <100.00%> (ø)
src/pkg/packager/load/import.go	50.60% <100.00%> (+1.56%)	⬆️
src/pkg/packager/mirror.go	0.00% <ø> (ø)
src/pkg/packager/packager.go	84.46% <100.00%> (+1.13%)	⬆️
... and 16 more

... and 2 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.

[Femure]

Thanks for putting this together. I’d like to better understand the direction you’re taking with this PR, and whether it’s intended to resolve the problem described in issue #2425.

The move toward explicit architecture lists makes sense from a clarity and validation standpoint. However, I want to make sure a specific use case is considered, as it’s currently a blocker for me and may not be covered by architecture selection alone.

In my workflow with FluxCD, images are pinned to an OCI index digest (not a platform-specific image). Because of that, the registry must contain the OCI index object itself, with the same digest.

From what I understand, this PR focuses on selecting and validating architectures, but:

• selecting a single platform breaks the digest
• pulling multiple architectures without preserving the index also breaks the digest

So even with this change, the index SHA wouldn’t exist in the air-gapped registry, and deployments would still fail.

The key requirement on my side is the ability to pull, package, and push an OCI index as-is, preserving its digest.

Can you confirm whether this PR is expected to support that, or if this would need to be handled separately?

[AustinAbro321]

Good question @Femure. Index sha's will be supported for pulling and pushing index sha's when multiple architectures are selected. We definitely want to keep this case around, as it is the most secure route.

When a tag is used, then Zarf will pull only the architectures for that tag. When an index sha is used then Zarf will pull every platform to keep the index in sync

[Femure]

Thanks for the clarification, that makes things much clearer.

Glad to hear that OCI index SHAs will be preserved when using them, that fully addresses my use case.

I’m looking forward to seeing this PR progress and hopefully get merged soon 🙂

[AustinAbro321]

This PR has ballooned in size, and I feel it is hard to review. Going to break in into three parts:

• introduce the test util and migrating unit tests over so they no longer call a registry on the internet
• Introduce pulling and pushing indexes behind a feature flag
• Introduce defining multiple architectures and pulling those architectures by tag