fix(k3s): fix cross platform image loading

[LaurentGoderre]

What does this PR do?

This PR adds more robust error handling around image loading and replaces the LoadImagesWithOpt that uses --all-platform to a LoadImagesWithPlatform function that allows loading the platform correctly.

This is required because --all-platform fails when some digests for some platform are missing.

Why is it important?

This is important because loading an image without specifying a platform is now broken.

[netlify[bot]]

✅ Deploy Preview for testcontainers-go ready!

Name	Link
🔨 Latest commit	fa8dec8e7c61d085914757fe8cb274e1a888f1d5
🔍 Latest deploy log	https://app.netlify.com/projects/testcontainers-go/deploys/691203b030811e000829de6b
😎 Deploy Preview	https://deploy-preview-3437--testcontainers-go.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[coderabbitai[bot]]

Summary by CodeRabbit

Release Notes

• New Features
  • Added platform and architecture-specific image loading support for K3s clusters
  • Added platform-aware image pulling capabilities for Docker containers
  • Extended image management APIs to support multi-platform architecture scenarios
  • Enhanced error reporting for image import and pull operations

Walkthrough

Adds platform-aware image load and pull APIs: K3s gains LoadImagesWithPlatform and platform-aware import flow (ctr with optional --platform); DockerProvider gains PullImageWithOpts and a platform pull option; tests updated for architecture-specific scenarios; module deps updated for containerd/platforms and OCI image-spec.

Changes

Cohort / File(s)	Summary
K3s image loading logic modules/k3s/k3s.go	Add LoadImagesWithPlatform(ctx, images, platform *v1.Platform); make LoadImages delegate to it; implement platform-aware save/import (use platform-aware save when provided), copy tar into container, run ctr images import with optional --platform, capture and return ctr output on non-zero exit; retain LoadImagesWithOpts.
K3s tests modules/k3s/k3s_test.go	Add Test_LoadImagesWithPlatform and update tests to pull/load architecture-specific image tags using containerd platforms.DefaultSpec; add mismatched-architecture failure test and in-cluster verification using platform-aware images.
Docker image pull options / provider API docker.go, image.go	Add PullImageWithOpts(ctx, img, ...PullImageOption) to DockerProvider; add PullDockerImageWithPlatform option constructor; introduce PullImageOption type and internal pullImageOptions (wrapping image.PullOptions); validate/apply options and propagate option-application errors; expand permanent client error checks.
Module dependencies modules/k3s/go.mod	Add direct requires for github.com/containerd/platforms v0.2.1 and github.com/opencontainers/image-spec v1.1.1 (removed from indirect block).

Sequence Diagram(s)

sequenceDiagram
  participant Caller as Caller
  participant K3s as K3sContainer
  participant Saver as ImageSaver
  participant Host as HostFS
  participant Ctr as k3s-ctr

  Note over Caller,K3s: Platform-aware image load request
  Caller->>K3s: LoadImagesWithPlatform(images, platform?)
  K3s->>Saver: Save image (with or without platform metadata)
  Saver->>Host: write tar file
  Host-->>K3s: tar path
  K3s->>Ctr: exec "ctr images import [--platform os/arch] <tar>"
  Ctr-->>K3s: exit code + output
  alt success
    K3s-->Caller: success
  else failure
    K3s-->Caller: error (includes ctr output)
  end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Potential review hotspots:

• modules/k3s/k3s.go: platform-aware save/import logic and error handling (ctr output capture).
• docker.go / image.go: option accumulation and application, and expanded permanent client error conditions.
• modules/k3s/k3s_test.go: new architecture-specific tests (flaky/integration concerns) — verify test reliability and platform derivation.

Poem

I’m a rabbit in code, I hop through tar and tray,
I tuck platform paws when images come to play.
I copy, import, and whisper the log,
If ctr grumbles, I return the fog.
Little hops, big builds — carrots at break of day. 🐇

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: fixing cross-platform image loading in k3s by introducing platform-aware image loading.
Description check	✅ Passed	The description is directly related to the changeset, explaining what the PR does and why it matters for platform-specific image loading.

✨ Finishing touches

• [ ] 📝 Generate docstrings

🧪 Generate unit tests (beta)

• [ ] Create PR with unit tests
• [ ] Post copyable unit tests in a comment

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e2b9db1b7dd408d9bdf1ff5863132bf0880105e6 and fa8dec8e7c61d085914757fe8cb274e1a888f1d5.

📒 Files selected for processing (2)

• docker.go (1 hunks)
• modules/k3s/go.mod (1 hunks)

🚧 Files skipped from review as they are similar to previous changes (2)

• modules/k3s/go.mod
• docker.go

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (11)

• GitHub Check: lint (modules/meilisearch) / lint: modules/meilisearch
• GitHub Check: lint (modules/dockermcpgateway) / lint: modules/dockermcpgateway
• GitHub Check: lint (modules/mongodb) / lint: modules/mongodb
• GitHub Check: lint (modules/artemis) / lint: modules/artemis
• GitHub Check: lint (modules/nebulagraph) / lint: modules/nebulagraph
• GitHub Check: lint (modules/inbucket) / lint: modules/inbucket
• GitHub Check: lint (modules/weaviate) / lint: modules/weaviate
• GitHub Check: lint (modules/scylladb) / lint: modules/scylladb
• GitHub Check: lint (modules/azurite) / lint: modules/azurite
• GitHub Check: lint (modules/azure) / lint: modules/azure
• GitHub Check: Analyze (go)

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}