docs: document that --tarball does not support multi-platform images

[dronenb]

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.go downcasts the build result to v1.Image, with a source comment stating there is no way to write an index to a tarball:

  ko/pkg/publish/tarball.go

  Lines 54 to 58 in e388f65

  	// There's no way to write an index to a tarball, so attempt to downcast it to an image.
  	img, ok := br.(v1.Image)
  	if !ok {
  	return nil, fmt.Errorf("failed to interpret %s result as image: %v", s, br)
  	}

• the tarball is written on Close via tarball.MultiRefWriteToFile:

  ko/pkg/publish/tarball.go

  Lines 95 to 98 in e388f65

  	func (t *tar) Close() error {
  	log.Printf("Saving %v", t.file)
  	if err := tarball.MultiRefWriteToFile(t.file, t.refs); err != nil {
  	// Bad practice, but we log this here because right now we just defer the Close.

Related prior issues:

• multi-platform build - unable to calculate manifest: set of images is empty #995
• Can Ko create multi-arch tarballs? #1565

Suggested Docs Change

Document the limitation wherever --tarball is described, for example:

--tarball writes Docker-save-style image tarballs for single-platform images. Multi-platform image indexes are not supported by the tarball publisher; use --oci-layout-path for multi-platform output.

This would help users understand when to use --tarball versus --oci-layout-path.