moby / moby/buildkit

WCOW: support for linux layers

Open
#4,537 3 comments 2 reactions 1 assignee View on GitHub

@profnandaa is already working on this.

Since Jun 19, 2025.

area/windows area/windows-lcow area/windows-wcow kind/enhancement
Dominant language
Go
Stars
10.3k
Forks
1.5k
Avg merge
1d 23h
Merged PRs (30d)
48

Description

Although I believe this behavior is completely undocumented (please provide link if it exists) the contents of the tar layers in images is completely different for Windows and Linux layers. All runtimes (docker, containerd) that support WCOW know this and have different implementations for WCOW layer extraction (and generation in buildkit's case).

In Linux layer tarball contains rootfs files directly that are extracted into a directory, as one would expect tar xvf to do.

In Windows this is not the case. Every tarball contains directories Hives and Files, with the Files directory containing the actual rootfs (similar to / is Linux). Afaics Hives sometimes contains some Windows custom internal (registry) files.

Additionally, all the files in Windows tarball need to have the Windows-specific ACL properties set. If they are not then these layers do not work when pulled by container runtime in Windows system.

To bring some sanity into this, and to support cross compiling WCOW images in Linux (that buildkit has supported for a long time), BuildKit has some wrapper hacks on extraction/generation of layers. https://github.com/moby/buildkit/blob/master/util/winlayers/applier.go#L78 Essentially, these skip or add the Hives/Files to the tarball when it is processing depending on the image platform that layer is coming from.

It is likely that OCI specs should provide some way of defining what layout tarball layer is using. Our current detection in finicky and if there is ever a layer shared in two images with different platforms, we would not know what to do. If we have ideas for this we should propose them to OCI image spec.

With WCOW support emerging, this logic should also work the opposite way. The WCOW BuildKit should be able to pull Linux images and perform file operations on them. Container runs for different OS will fail as they do now. As (afaik) wcow requires the Hives/Files to work, they should be generated on apply type and discarded on generation time. Similarly the default Windows ACL should be added automatically on apply and removed on generation.

Currently we have some runtime.GOOS checks in the winlayers code https://github.com/moby/buildkit/blob/8a7e5c73174063ce5482b49b5316e4706534c1d3/source/containerimage/pull.go#L233 and https://github.com/moby/buildkit/blob/8a7e5c73174063ce5482b49b5316e4706534c1d3/util/winlayers/applier.go#L24 that should be avoided and missing the reverse transformation logic.

If people wish then theoretically this could also be attempted in containerd repository(assuming containerd maintainers approve design). There is no need for these hacks to be buildkit-specific.

@gabriel-samfira @profnandaa @TBBle

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.