Invoking a frontend using the gRPC API

[cowwoc]

Description

I am trying to build a Java client for BuildKit using the gRPC API.

The "dockerfile.v0" frontend seems to expect us to pass inputs in LLB format, but (as far as I can tell) there is no way to generate LLB outside of the Go code.

Is this functionality that needs to be added or am I missing something?

To be clear, I am looking for an API to invoke as opposed to running buildkitd over command-line. Thank you.

[jsternberg]

Hi. If I'm understanding correctly, you're attempting to invoke the gRPC API for Buildkit as a client. There are two APIs that use gRPC and I suspect you might be looking at the wrong one.

There's the frontend API which is very heavily based on the current Go implementation. It's possible to use that API from outside of Go, but it's primarily meant as a way to create custom frontends. A custom frontend is invoked by buildkit and buildkit acts as the client to your frontend which is the server. The most typical usage of this is with the # syntax line at the top of a dockerfile.

I suspect you may be looking for the control API which is the outwards facing API. That's the gRPC API where buildkit is the server and your client is making an outside request for a build. This API is located in api/services/control/control.proto and you can use a standard gRPC client to connect with it over a Unix socket. This API also has a Solve method and, while you can send LLB directly, you can also specify a frontend in the solve request.

Rather than looking at anything in the frontend package, you might want to look at the implementation of buildctl. buildctl is a generic client for buildkit that uses the gRPC API directly while docker buildx is a very opinionated usage of buildkit to match with how people used the docker build command.

I hope that helps. If I've misunderstood your intention, please correct me. Thanks.

[cowwoc]

Hi @jsternberg

Thank you for the detailed response.

I am actually already using api/services/control/control.proto. The problem was that I couldn't figure out how to access the buildkit instance that is bundled with Docker for Desktop. Fortunately, I was able to reach Tonis on Slack and he told me about a undocumented (!!) /grpc endpoint in the Docker REST API. That was the missing piece.

I still have some open questions about the BuildKit gRPC API. If you take a look at https://github.com/cowwoc/docker/blob/3c7aa4849e63d188c45c5e94d9819cf0238ba56a/pom.xml#L403 I am totally guessing at what proto files I need to download, especially when it comes to dependencies of BuildKit's proto files.

Where can I find a list of all the proto files used to build BuildKit (and any dependent proto files) to make sure that I'm using the same versions as you guys?

For example, I'm not sure if this is the right version of ext.proto: https://github.com/cowwoc/docker/blob/3c7aa4849e63d188c45c5e94d9819cf0238ba56a/pom.xml#L692

And as you can see at https://github.com/cowwoc/docker/blob/3c7aa4849e63d188c45c5e94d9819cf0238ba56a/pom.xml#L723 I am having to modify the downloaded proto file to avoid a compile-time error... so something doesn't smell right.

[jsternberg]

I think the easiest way to get the correct protobuf files may be to use our builder at hack/dockerfiles/generated-files.Dockerfile and then copy/paste them into your own repository after retrieving them and then manually updating them when you need to. Updating them should be very infrequent as you would also only need to do that when you add a new feature since, even if we add a new feature, the old protobuf is compatible with any new protobuf.

I modified the file a little bit to hopefully make things easier for you.

#5911

The file previously copied the protobuf files for generation into a golang based image so it could then run the generator. It aggregated multiple different dependencies. I've modified it so it now aggregates into a separate stage so you can do something like:

docker buildx build -f hack/dockerfiles/generated-files.Dockerfile --target protobuf -o ../protobuf-out

This will also include the bin/protoc binary but you can just ignore that.

[cowwoc]

@jsternberg Thanks for this update. Can you please add .gitattributes entries for hack/dockerfiles that run on Linux? When I checked out the code under Windows, they ended up containing CRLF line endings and the build failed as follows:

docker buildx build -f hack/dockerfiles/generated-files.Dockerfile --target protobuf -o ../protobuf-out .
[+] Building 70.9s (15/15) FINISHED                                                                                                                                                                                                                      docker:desktop-linux
 => [internal] load build definition from generated-files.Dockerfile                                                                                                                                                                                                     0.0s
 => => transferring dockerfile: 3.56kB                                                                                                                                                                                                                                   0.0s
 => resolve image config for docker-image://docker.io/docker/dockerfile-upstream:master                                                                                                                                                                                  1.2s
 => [auth] docker/dockerfile-upstream:pull token for registry-1.docker.io                                                                                                                                                                                                0.0s
 => docker-image://docker.io/docker/dockerfile-upstream:master@sha256:8278de13b9dad719c1fb912efe971702ab6fe6c8d901b54b7c01b9811cdfc69b                                                                                                                                   3.8s
 => => resolve docker.io/docker/dockerfile-upstream:master@sha256:8278de13b9dad719c1fb912efe971702ab6fe6c8d901b54b7c01b9811cdfc69b                                                                                                                                       0.0s
 => => sha256:1d338253a0f1397ba42e36574871c22712b48e7e011c0374ff8e1857e14389b9 13.18MB / 13.18MB                                                                                                                                                                         3.6s
 => => extracting sha256:1d338253a0f1397ba42e36574871c22712b48e7e011c0374ff8e1857e14389b9                                                                                                                                                                                0.2s
 => [internal] load metadata for docker.io/library/golang:1.23-bookworm                                                                                                                                                                                                  0.6s
 => [auth] library/golang:pull token for registry-1.docker.io                                                                                                                                                                                                            0.0s
 => [internal] load .dockerignore                                                                                                                                                                                                                                        0.0s
 => => transferring context: 59B                                                                                                                                                                                                                                         0.0s
 => [base 1/2] FROM docker.io/library/golang:1.23-bookworm@sha256:1a73e15c5a17855b58014aab45df0fdf8be778f12a62ed2a48009fe2c0022091                                                                                                                                      57.9s
 => => resolve docker.io/library/golang:1.23-bookworm@sha256:1a73e15c5a17855b58014aab45df0fdf8be778f12a62ed2a48009fe2c0022091                                                                                                                                            0.0s
 => => sha256:4f4fb700ef54461cfa02571ae0db9a0dc1e0cdb5577484a6d75e68dc38e8acc1 32B / 32B                                                                                                                                                                                 0.1s
 => => sha256:3f145dc58038c8f67e2684884cf66f7c9cbb0ccafffda0058dfff459a636262d 125B / 125B                                                                                                                                                                               0.1s
 => => sha256:70eabb1d9476e2a74ca18f982fa2cd1a722047e0ac01f746221f76c65893fe80 74.06MB / 74.06MB                                                                                                                                                                        48.0s
 => => sha256:2b3f8110af4110e38260f97dcc20c0681bbf3412ae022875e8635bfaf95996b6 92.33MB / 92.33MB                                                                                                                                                                        46.4s
 => => sha256:1eb98adba0eb44a2e4facf9ca3626a4a66feedd0dd56d159cca90a35205744e7 64.40MB / 64.40MB                                                                                                                                                                        38.1s
 => => sha256:07d1b5af933d2dfc3d0dd509d6e20534825e4a537f7b006a6cb5b8e5a1f20905 24.01MB / 24.01MB                                                                                                                                                                        17.8s
 => => sha256:23b7d26ef1d294256da0d70ce374277b9aab5ca683015073316005cb63d33849 48.49MB / 48.49MB                                                                                                                                                                        31.0s
 => => extracting sha256:23b7d26ef1d294256da0d70ce374277b9aab5ca683015073316005cb63d33849                                                                                                                                                                                1.6s
 => => extracting sha256:07d1b5af933d2dfc3d0dd509d6e20534825e4a537f7b006a6cb5b8e5a1f20905                                                                                                                                                                                0.5s
 => => extracting sha256:1eb98adba0eb44a2e4facf9ca3626a4a66feedd0dd56d159cca90a35205744e7                                                                                                                                                                                1.8s
 => => extracting sha256:2b3f8110af4110e38260f97dcc20c0681bbf3412ae022875e8635bfaf95996b6                                                                                                                                                                                1.6s
 => => extracting sha256:70eabb1d9476e2a74ca18f982fa2cd1a722047e0ac01f746221f76c65893fe80                                                                                                                                                                                3.4s
 => => extracting sha256:3f145dc58038c8f67e2684884cf66f7c9cbb0ccafffda0058dfff459a636262d                                                                                                                                                                                0.0s
 => => extracting sha256:4f4fb700ef54461cfa02571ae0db9a0dc1e0cdb5577484a6d75e68dc38e8acc1                                                                                                                                                                                0.0s
 => [internal] load build context                                                                                                                                                                                                                                        2.2s
 => => transferring context: 44.47MB                                                                                                                                                                                                                                     2.2s
 => [base 2/2] RUN apt-get update && apt-get --no-install-recommends install -y git unzip                                                                                                                                                                                6.2s
 => ERROR [googleapis 1/1] RUN <<EOT (set -e...)                                                                                                                                                                                                                         0.5s
 => CANCELED [protoc 1/1] RUN <<EOT (set -e...)                                                                                                                                                                                                                          1.2s
 => [gobuild-base 1/1] WORKDIR /app                                                                                                                                                                                                                                      0.0s
 => CANCELED [vtprotobuf 1/1] RUN --mount=type=bind,source=go.mod,target=/app/go.mod     --mount=type=bind,source=go.sum,target=/app/go.sum     --mount=type=cache,target=/root/.cache     --mount=type=cache,target=/go/pkg/mod <<EOT (set -e...)                       1.7s
 => ERROR [vendored 1/1] RUN --mount=type=bind,source=vendor,target=/app <<EOT (set -e...)                                                                                                                                                                               1.6s
------
 > [googleapis 1/1] RUN <<EOT (set -e...):
0.473 /bin/sh: 1: set: Illegal option -
------
------
 > [vendored 1/1] RUN --mount=type=bind,source=vendor,target=/app <<EOT (set -e...):
1.554 /bin/sh: 1: set: Illegal option -
------
generated-files.Dockerfile:51
--------------------
  50 |     FROM gobuild-base AS vendored
  51 | >>> RUN --mount=type=bind,source=vendor,target=/app <<EOT
  52 | >>>   set -e
  53 | >>>   mkdir -p /opt/vendored/include
  54 | >>>   find . -name '*.proto' | tar -cf - --files-from - | tar -C /opt/vendored/include -xf -
  55 | >>> EOT
  56 |
--------------------
ERROR: failed to solve: process "/bin/sh -c   set -e\r\n  mkdir -p /opt/vendored/include\r\n  find . -name '*.proto' | tar -cf - --files-from - | tar -C /opt/vendored/include -xf -\r\n" did not complete successfully: exit code: 2

Converting the line ending to LF manually fixed the problem.