docs: document that --tarball does not support multi-platform images
Summary
ko build --tarball does not currently support multi-platform image indexes, but the reference docs only describe the flag as:
File to save images tarballs
This makes it look like --tarball should work with the same multi-platform builds that ko otherwise supports.
Current Behavior
A multi-platform build with --tarball fails because the native tarball publisher only supports v1.Image, not v1.ImageIndex.
Related source:
pkg/publish/tarball.godowncasts the build result tov1.Image, with a source comment stating there is no way to write an index to a tarball: https://github.com/ko-build/ko/blob/e388f65a1f036f19703b8aff13e1aa5521bc6988/pkg/publish/tarball.go#L54-L58- the tarball is written on
Closeviatarball.MultiRefWriteToFile: https://github.com/ko-build/ko/blob/e388f65a1f036f19703b8aff13e1aa5521bc6988/pkg/publish/tarball.go#L95-L98
Related prior issues:
Suggested Docs Change
Document the limitation wherever --tarball is described, for example:
--tarballwrites Docker-save-style image tarballs for single-platform images. Multi-platform image indexes are not supported by the tarball publisher; use--oci-layout-pathfor multi-platform output.
This would help users understand when to use --tarball versus --oci-layout-path.
Source: ko-build/ko