BuildKit and buildx Architecture, Builders, Frontends, Progress, Outputs, and Modern Build Workflows: Concepts, Architecture, and Mental Model

1. The problem: “the build succeeded” is not a complete state

Chapter 08 bounded the source inputs a builder may read. Chapter 09 follows those inputs through the build execution system. The phrase “Docker built my image” hides several independent decisions: which Buildx client version submitted the request, which builder instance was selected, which driver owns that builder, which Dockerfile frontend translated the Dockerfile, which BuildKit worker executed the graph, which cache records were reused, and which exporter received the result.

A completed BuildKit solve can therefore be real even when docker image ls shows no new image. With a non-default driver such as docker-container, a result can remain only in BuildKit cache until an exporter such as --load, --push, or --output is requested. Operationally, execution success and output availability are different states.

2. Mental model: request → graph → worker → exporter

flowchart TD
  A[Docker CLI / buildx] --> B[Selected builder instance]
  B --> C[Driver: docker / docker-container / remote / kubernetes / cloud]
  C --> D[BuildKit daemon + worker]
  A --> E[Dockerfile frontend]
  E --> F[LLB build graph]
  F --> D
  D --> G[Content + result cache]
  D --> H[Exporter]
  H --> I[Docker image store]
  H --> J[Registry]
  H --> K[OCI/Docker archive]
  H --> L[Local filesystem / tar]
            

Buildx is the Docker CLI plugin/orchestration layer. A builder instance is a named configuration that can contain one or more nodes. A driver decides how BuildKit runs. A frontend converts a high-level build definition such as a Dockerfile into BuildKit's lower-level build graph. A worker executes that graph. An exporter decides where the result goes.

3. Separate the versions before debugging

4. The driver chooses where BuildKit runs

The default docker driver uses BuildKit components integrated with Docker Engine and prioritizes convenience. It normally loads compatible image results into the local image store automatically. The docker-container driver runs a dedicated BuildKit container and is more configurable; it supports advanced exporters and multi-platform workflows, but it does not automatically put a successful result into the local Docker image store unless an output is requested.

Remote, Kubernetes, and cloud drivers move the worker boundary elsewhere. That changes trust, network, storage, cache ownership, platform capacity, and operational responsibility even if the Dockerfile is identical.

5. Frontend and LLB: the Dockerfile is translated before workers execute it

The Dockerfile frontend parses Dockerfile syntax and produces an LLB graph: a content-addressed, dependency-aware representation BuildKit can schedule and cache. The frontend is therefore part of the build toolchain. If a newer Dockerfile feature works on one builder but not another, first record the effective frontend and BuildKit versions instead of assuming the Dockerfile text alone determines behavior.

6. Cache is execution evidence, not release identity

BuildKit's cache allows graph operations to be reused when their inputs match. A CACHED progress line means BuildKit reused a prior result for that operation under the current cache model; it does not prove that the final image was loaded, pushed, signed, scanned, or deployed. Cache can accelerate reproducible builds, but it must remain separate from the immutable identity of a released image.

7. Exporters define output state

8. Progress is a diagnostic surface

--progress=plain is useful in teaching and CI because it produces durable, line-oriented step evidence. Interactive tty is easier to read live. rawjson is suitable for machine processing. A progress mode changes presentation, not the semantic build graph.

docker buildx ls
docker buildx version
docker buildx inspect --bootstrap
docker buildx build --progress=plain .

Run the last command only against a disposable source tree. If the selected builder does not auto-load results, lack of a local image is not proof that the solve failed.

9. Evidence map for one build

10. Small challenge: local image missing after a green build

A colleague uses a docker-container builder. BuildKit prints DONE, but docker image inspect team/app:test says the image does not exist. Name the first three pieces of evidence you would capture, and explain why adding --load can be the correct fix while deleting the builder cache is not.

Knowledge check

Official references and version notes

• Builders — Buildx builder instances, nodes, drivers, and builder selection.
• Build drivers — current docker, docker-container, cloud, kubernetes, and remote driver behavior and capabilities.
• Docker container driver — isolated BuildKit container lifecycle, driver options, and explicit output behavior.
• Docker Buildx CLI — builder override, subcommands, and current Buildx surface.
• docker buildx build — progress modes, exporters, metadata, --load, --push, and output semantics.
• docker buildx inspect — builder/driver/nodes/status/platform and bootstrap evidence.
• Build history — recorded build IDs, status, time, duration, logs, and record inspection.
• Exporters — image, registry, local, tar, OCI, and Docker build-result destinations.
• OCI and Docker exporters — OCI/Docker archive semantics and compatible drivers.
• Dockerfile reference — Dockerfile frontend syntax and build instruction semantics.
• Buildx releases — upstream Buildx release history.
• BuildKit releases — BuildKit and built-in Dockerfile frontend release history.
• Docker Engine 29 release notes — current Engine baseline and bundled component updates.