Skip to content

DRAFT: Add design doc for canonical tar#356

Draft
cgwalters wants to merge 1 commit into
composefs:mainfrom
cgwalters:spec-enhancements-more
Draft

DRAFT: Add design doc for canonical tar#356
cgwalters wants to merge 1 commit into
composefs:mainfrom
cgwalters:spec-enhancements-more

Conversation

@cgwalters

Copy link
Copy Markdown
Collaborator

Sketch two speculative follow-on proposals that build toward incremental container image pulls: a canonical, byte-reproducible tar serialization, and a composefs-chunked layer format with an external offset-map artifact for range-based fetching.

--

Moved from #224

@giuseppe

Copy link
Copy Markdown
Collaborator

could we split this even further?

I like the idea of a canonical tar, and that can be applied to zstd:chunked too, but I don't really see any advantage to split even more from what containers tools are doing, and if possible we should try to fix what is there

@alexlarsson

Copy link
Copy Markdown
Contributor

I'm interested in the idea of a canonical tar construction for another reason. If you mount a composefs image with --upperdir, it should be possible to "commit" it and create a new OCI image in the composefs repo with a new tarsplit splitstream for the new layer.

@alexlarsson

Copy link
Copy Markdown
Contributor

Basically, you'd be able to cfsrun commit.

Sketch a canonical, byte-reproducible tar serialization for composefs
filesystem trees: a deterministic dumpfile-to-tar mapping that
complements the standardized EROFS metadata work, letting a client
regenerate byte-identical tar layers (e.g. to verify diff_id) from
EROFS + object store alone.

Drop the previously-proposed composefs-chunked/incremental-pull sketch
for now; it can be revisited separately once the canonical tar format
itself has settled.

Signed-off-by: Colin Walters <walters@verbum.org>
@cgwalters cgwalters force-pushed the spec-enhancements-more branch from 97a86cb to 5badac9 Compare July 10, 2026 18:31
@cgwalters

Copy link
Copy Markdown
Collaborator Author

could we split this even further?

Done! Now this PR is only about the canonical tar spec.

I'm interested in the idea of a canonical tar construction for another reason. If you mount a composefs image with --upperdir, it should be possible to "commit" it and create a new OCI image in the composefs repo with a new tarsplit splitstream for the new layer.

We could do that today without canonical tar, it's just that conceptually different implementations might generate a different tar layer right?

I mean, it's a good idea to make that canonical, but nothing stops this project from synthesizing OCI images without it, it's what we do in the test suite with https://github.com/bootc-dev/ocidir-rs/

@cgwalters cgwalters changed the title DRAFT: Add design docs for canonical tar and incremental pulls DRAFT: Add design doc for canonical tar Jul 10, 2026
@alexlarsson

Copy link
Copy Markdown
Contributor

True, there is no real need for commit to produce guaranteed reproducible results. Its just that I do need to produce tar splitstreams from a Filesystem (while converting real whiteouts to .wh.* files), and having a pre-existing implementation for this would mean not having to duplicate such code.

@alexlarsson

Copy link
Copy Markdown
Contributor

I think this will also play well with the idea of also using composefs to efficiently store generic non-os-image content, while doing deduplication. You'd have cfsctl tar create /some/dir, which you can then extract with cfsctl tar cat, and easily convert to/from image if you ever want to mount it.

@alexlarsson

Copy link
Copy Markdown
Contributor

Or maybe the better approach is to always store as image, but allow to easily export it as a tar.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants