#1708·ko

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

Author: dronenbCreated Jul 14, 2026Updated Jul 14, 2026

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:

Related prior issues:

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.