ko-build / ko-build/ko

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

Open Beginner friendly
#1,708 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.