Skip to content

Add support for building with buildkit #3344

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add support for building with buildkit #3344

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
77bd2e9
Add support for building with buildkit
felipecrs Jun 27, 2025
b7d2af3
Clarify test intention
felipecrs Jun 30, 2025
0a93263
Clarify version='2' limitations
felipecrs Jun 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 12 additions & 1 deletion docker/api/build.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ def build(self, path=None, tag=None, quiet=False, fileobj=None,
decode=False, buildargs=None, gzip=False, shmsize=None,
labels=None, cache_from=None, target=None, network_mode=None,
squash=None, extra_hosts=None, platform=None, isolation=None,
use_config_proxy=True):
version=None, use_config_proxy=True):
"""
Similar to the ``docker build`` command. Either ``path`` or ``fileobj``
needs to be set. ``path`` can be a local path (to a directory
Expand Down Expand Up @@ -101,6 +101,10 @@ def build(self, path=None, tag=None, quiet=False, fileobj=None,
platform (str): Platform in the format ``os[/arch[/variant]]``
isolation (str): Isolation technology used during build.
Default: `None`.
version (str): Version of the builder backend to use.
- `1` is the first generation classic (deprecated) builder in the Docker daemon (default)
- `2` is [BuildKit](https://github.com/moby/buildkit) over the REST API endpoint provided by the Docker daemon. This mode doesn't use the BuildKit gRPC API, and lacks support for advanced features such as secret mounts.
Default: `None`.
use_config_proxy (bool): If ``True``, and if the docker client
configuration file (``~/.docker/config.json`` by default)
contains a proxy configuration, the corresponding environment
Expand Down Expand Up @@ -253,6 +257,13 @@ def build(self, path=None, tag=None, quiet=False, fileobj=None,
)
params['isolation'] = isolation

if version is not None:
if utils.version_lt(self._version, '1.38'):
raise errors.InvalidVersion(
'version was only introduced in API version 1.38'
)
params['version'] = version
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Bumping up the version number doesn't magically implement the BuildKit API.
You have to dial /grpc to call the BuildKit gRPC API.
https://github.com/docker/buildx/blob/v0.25.0/driver/docker/driver.go
https://github.com/moby/buildkit/blob/v0.23.1/api/services/control/control.proto

In addition to implementing the gRPC client, you also have to implement several "attachable" servers (auth, secret, ssh) via the reverse-gRPC connection.
https://github.com/moby/buildkit/blob/v0.23.1/cmd/buildctl/build.go#L191-L214

This is quite complicated than you might imagine; I suggest just shelling out docker buildx and call it a day.

Copy link
Author

@felipecrs felipecrs Jun 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks a lot for reviewing it.

Bumping up the version number doesn't magically implement the BuildKit API.

Tests prove you are wrong. No?

In addition to implementing the gRPC client, you also have to implement several "attachable" servers (auth, secret, ssh) via the reverse-gRPC connection.

Exposing additional options can be done in follow-up PRs. This PR is sufficient for my use case which is building Dockerfiles that depend on BuilKit-features that are not auth, secret, or ssh.

I suggest just shelling out docker buildx and call it a day.

That means installing docker buildx, which means installing docker cli. It's a big downside comparing to just calling the Rest API.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Only basic BuildKit features can be enabled by just bumping up the version:
https://github.com/moby/moby/blob/v28.3.0/api/server/backend/build/backend.go#L55-L73

The scope of the available features should be documented

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you mean I should clarify that squash and forcerm will error when version=2?

Otherwise, I expect all options currently supported by client.build() to be supported.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will test it more, and let you know.

Copy link
Author

@felipecrs felipecrs Jun 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, this is worse than I expected.

I got lucky with the tests because I only tried with FROM scratch.

Even a basic Dockerfile like below does not work:

    @requires_api_version('1.38')
    def test_build_buildkit_alpine(self):
        script = io.BytesIO('\n'.join([
            'FROM alpine',
        ]).encode('ascii'))

        self.tmp_imgs.append('buildkitalpine')

        stream = self.client.build(
            fileobj=script, tag='buildkitalpine',
            version='2'
        )

        for _chunk in stream:
            pass

        assert self.client.inspect_image('buildkitalpine')

But it's because of a bug:

Still, it means not even basic use cases like pulling an image that doesn't require auth will not be able to use this feature.

@AkihiroSuda do you have any idea? Otherwise, I think it may be the end of this PR (and a dream). :(

This comment says creating a basic session is enough for pull to work. Do you think it would be acceptable to build a solution around it?

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This moby/moby#48112 (comment) says creating a basic session is enough for pull to work. Do you think it would be acceptable to build a solution around it?

SGTM

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I haven't been able to build anything so far, but I will update when I have any news.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FYI I found some gRPC references from an unfinished buildkit implementation in this library from @shin-:


if context is not None:
headers = {'Content-Type': 'application/tar'}
if encoding:
Expand Down
21 changes: 21 additions & 0 deletions tests/integration/api_build_test.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -201,6 +201,27 @@ def test_build_isolation(self):
for _chunk in stream:
pass

@requires_api_version('1.38')
def test_build_buildkit_heredoc(self):
script = io.BytesIO('\n'.join([
'FROM scratch',
'COPY <<EOF greeting.txt',
'hello world',
'EOF'
]).encode('ascii'))

self.tmp_imgs.append('buildkit-heredoc')

stream = self.client.build(
fileobj=script, tag='buildkit-heredoc',
version='2'
)

for _chunk in stream:
pass

assert self.client.inspect_image('buildkit-heredoc')

@requires_api_version('1.23')
def test_build_labels(self):
script = io.BytesIO('\n'.join([
Expand Down