docs: document that --tarball does not support multi-platform images
- Dominant language
- Go
- Stars
- 8.5k
- Forks
- 447
- PR merge metrics
- No merged PRs in 30d
Description
## 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:
- the tarball is written on `Close` via `tarball.MultiRefWriteToFile`:
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`.
Contributor guide
Research direction
Start with the reference documentation entries that describe --tarball, then read pkg/publish/tarball.go and the related issues for context. Update every relevant description to state that multi-platform image indexes are unsupported and point users to --oci-layout-path; done means the limitation and alternative are clear wherever the flag is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- go
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100