feat(server): build via BuildKit client when buildkitd address is set

[vmrm]

Summary

Add an alternative build path that talks to an already running buildkitd directly through the BuildKit client (github.com/moby/buildkit/client), instead of shelling out to the docker CLI. The address is set per project via configure (buildkitd_address) or process-wide via TRDL_BUILDKITD_ADDRESS; with no address set, the existing docker buildx path is byte-for-byte unchanged. Follow-up to #398.

Key changes

• server/pkg/docker/buildkit.go (new): the release build mapped onto a single Solve against an external buildkitd:
  • frontend dockerfile.v0, in-context service Dockerfile via the filename attr, no-cache, image-resolve-mode=pull (the equivalents of --no-cache/--pull);
  • the context tar (previously streamed to docker buildx build stdin) is streamed through the session upload provider;
  • build secrets and mac-signing credentials are served by secretsprovider.FromMap under the same ids the generated Dockerfile mounts (--mount=type=secret,id=…), so the mac-signing signer stage keeps working; unlike the CLI path, they are no longer exported into the plugin's process environment;
  • the tar exporter writes into the same pipe the buildx path writes to, and build progress goes through the same logger (PlainMode progress display), including the existing error recommendations.
• Transport is chosen by the address scheme, as built into the BuildKit client: unix:// and tcp:// are direct gRPC (no external binaries), docker-container:// and kube-pod:// go through docker exec/kubectl exec (connhelpers registered via blank imports).
• server/pkg/docker/builder.go: NewBuilder returns a BuildKit-mode builder when an address is resolved — no buildx create, and Remove is a no-op (nothing is provisioned per build). Otherwise the previous exec path runs unchanged.
• server/path_configure.go: new optional configure field buildkitd_address, validated at configure time (scheme allowlist, fail-closed like the feat(server): make buildx driver configurable via env #398 driver allowlist). Per-project config wins over the TRDL_BUILDKITD_ADDRESS env fallback.
• Tests:
  • exec path unchanged with no address set (TestSetCliArgs_ExecPathUnchanged, TestResolveBuildkitdAddress_EmptyKeepsExecPath, plus the pre-existing TestBuildxCreateArgs_* suite);
  • address resolution precedence and scheme allowlist; frontend attrs; secrets id mapping incl. the empty-mac-password case; configure-endpoint round-trip and rejection of an invalid address;
  • TestAI_BuildkitSmoke (opt-in, ai_tests tag, skips without TRDL_SMOKE_BUILDKITD_ADDRESS): end-to-end against a real buildkitd — tar context in, secret mount readable in a RUN, artifacts tar out.
• Docs: QUICKSTART (en/ru) section on building against an external buildkitd; regenerated configure API partial. Also corrects the kubernetes driver note added in feat(server): make buildx driver configurable via env #398, which said rootless BuildKit requires PodSecurity baseline — buildx's rootless pod spec sets seccompProfile: Unconfined plus the unconfined AppArmor annotation (driver/kubernetes/manifest/manifest.go), and Unconfined is rejected by both the Seccomp and the AppArmor control at baseline, so that namespace has to be privileged or exempt from PodSecurity admission.

Why

The trdl secret engine is also compiled into host processes and shipped in distroless images that contain no docker binary (Deckhouse Stronghold ships /usr/bin/stronghold alone, read-only root fs, no docker socket). There, exec.CommandContext(ctx, "docker", …) fails with executable file not found before the buildx driver choice from #398 can even matter. Pointing the plugin at an external buildkitd removes the CLI dependency entirely for unix:///tcp://, while keeping the docker CLI as the default for every existing installation.

The address lives in per-project configure (not only env) because in module-based deployments there is no way to inject env vars into the Vault pod, while configure is already the per-project channel for s3/git/quorum settings.

Dependencies

Honest numbers, since the server module previously had zero docker/moby/buildkit dependencies:

• direct: + github.com/moby/buildkit v0.31.2, golang.org/x/sync promoted from indirect;
• 46 new modules in go.mod overall, notably containerd/* (API types), docker/cli (connhelper/commandconn only), tonistiigi/fsutil, opentelemetry-* (buildkit client instrumentation), in-toto, grpc-gateway;
• plugin binary (linux/amd64, CGO off): 42.6 MB → 51.5 MB (+8.9 MB, +21%);
• go directive 1.25.0 → 1.25.9 (required by buildkit); toolchain go1.25.12 unchanged. buildkit v0.32.x was deliberately not taken — it requires go 1.26.3, which would break the Go 1.25.12 builder image pinned in trdl.yaml;
• containerd/v2 pinned to v2.2.5 instead of the v2.2.4 buildkit requires: govulncheck reports five advisories against v2.2.4 (GO-2026-5064/5338/5475/5622/5758), all fixed in v2.2.5;
• the only MPL-2.0 delta is the forced patch bump of the pre-existing indirect hashicorp/go-retryablehttp v0.7.7 → v0.7.8 (required by every buildkit release since v0.28); every newly added module is Apache-2.0/MIT/BSD (checked with go-licenses);
• govulncheck: after bumping klauspost/compress v1.18.6 → v1.18.7 (buildkit pulls in v1.18.6, which carries GO-2026-5841; the symbol is unreachable from trdl), the module-level advisory set is identical to main — GO-2026-5932 (x/crypto/openpgp, unmaintained) and GO-2022-0646 / GO-2022-0635 (aws-sdk-go v1 S3 crypto), none of which have a fixed version. The two symbol-level findings it also reports are stdlib on the scanning host's go1.26.4 toolchain, not properties of this module;
• the Snyk PR checks flag one license and one security issue; the finding details are only visible inside the werf Snyk org, so they need maintainer triage;
• for host binaries that already link docker/cli, docker/docker and containerd (e.g. Stronghold), the marginal cost is smaller than for trdl itself.

Review focus / risks

• server/pkg/docker/buildkit.go — the Solve mapping. Verified live against buildkitd v0.31.2 over both docker-container:// (connhelper) and tcp:// (direct gRPC): streamed tar context, .trdl/Dockerfile picked by filename, a secret mount read back out of the exported artifacts tar. The smoke test in the PR reproduces exactly that; run it with TRDL_SMOKE_BUILDKITD_ADDRESS=docker-container://<buildkitd-container> go test -tags ai_tests -run TestAI_BuildkitSmoke ./pkg/docker/.
• Behavior differences vs the CLI path when (and only when) an address is set: no per-build builder lifecycle, so concurrent releases share one buildkitd (its own gc/parallelism limits apply); secrets are no longer set as process env vars.
• The mac-signing path is exercised only at the secrets-transport level here (id mapping unit tests + a secret mount in the live smoke test); the full quill-stub e2e from feat(server): make buildx driver configurable via env #398 was not re-run against a buildkitd address.
• Deploying buildkitd is the operator's business (dedicated namespace with PodSecurity labels set by the cluster owner — BuildKit needs a relaxed seccomp/AppArmor profile even rootless, so no PSS level below privileged is claimed anywhere in these docs).
• go.sum churn: MVS bumps of a handful of existing indirect deps alongside the new modules.

🤖 Generated with Claude Code

[vmrm]

Dependency delta, re-measured

Since "this module had zero docker/moby/buildkit dependencies before" is the main thing to weigh here, the exact numbers, measured on 73a6cbf against main at f567b92. go mod tidy is a no-op on this branch — go.mod/go.sum are already tidy.

	main	this branch	Δ
require entries in server/go.mod	111	157	+46, none dropped
modules actually linked into vault-plugin-secrets-trdl (go list -deps)	94	141	+47
full module graph (go list -m all)	316	508	+203 nodes, 11 dropped
binary, CGO_ENABLED=0 GOOS=linux GOARCH=amd64 -trimpath	42 481 463 B	51 399 712 B	+8 918 249 B (+21.0 %)

The two numbers differ because gotest.tools/v3 is test-only, while go-logr/logr and google/go-cmp were already in go.mod and only now get linked.

Direct additions — two: github.com/moby/buildkit v0.31.2, and golang.org/x/sync promoted from indirect to direct.

The other 45 are indirect, and they are not 45 independent decisions — they are four clusters plus a tail:

• containerd/* — 10 (containerd/v2, containerd/api, console, continuity, errdefs, errdefs/pkg, log, platforms, ttrpc, typeurl/v2): the OCI/API types buildkit's client-side structs are declared in.
• go.opentelemetry.io/* — 10 (otel, otel/{trace,metric,sdk}, otel/exporters/otlp/otlptrace, auto/sdk, proto/otlp, three contrib/instrumentation/*): the buildkit client instruments its own gRPC/HTTP calls. Pulled in transitively; trdl configures no exporter, so nothing is emitted.
• tonistiigi/* — 4 (fsutil, units, vt100, go-csvvalue): context transfer and the progress display.
• in-toto/* + planetscale/vtprotobuf + grpc-ecosystem/grpc-gateway/v2 — 4: provenance/attestation types and the generated-code runtimes buildkit's protos depend on.
• tail — 17: docker/cli (only the connhelper/commandconn packages, i.e. only the docker-container:// and kube-pod:// code paths), klauspost/compress, moby/{locker,patternmatcher,sys/signal}, morikuni/aec, opencontainers/image-spec, google/{shlex,uuid}, cespare/xxhash/v2, felixge/httpsnoop, gofrs/flock, go-logr/stdr, shibumi/go-pathspec, sirupsen/logrus, youmark/pkcs8, plus test-only gotest.tools/v3.

Nothing was dropped from go.mod; the 11 modules that leave the graph (gorilla/mux, urfave/cli, mattn/go-sqlite3, etcd/*, the v1 grpc-gateway, …) leave because MVS bumps of existing deps pruned them, and none of them were linked before.

None of this is reachable when buildkitd_address is unset: NewBuilder returns the exec-path builder and pkg/docker/buildkit.go is never entered. It is a binary-size and supply-chain cost, not a behavioural one — hence the size number above rather than a "no impact" claim.

On the two red Snyk checks

license/snyk and security/snyk are red, and their findings are only readable inside the werf Snyk org, so I cannot see what they name — that part needs maintainer triage. What I can report from the outside:

• License. Reading the license file of each of the 46 new modules: 32 Apache-2.0, 9 MIT, 5 BSD — permissive across the board. The only MPL-2.0 movement is a patch bump of the pre-existing indirect hashicorp/go-retryablehttp, v0.7.7 → v0.7.8, which every buildkit release since v0.28 requires. No new MPL/GPL/AGPL module enters the graph.

• Security. govulncheck now reports the same module-level advisory set as main — GO-2026-5932 (x/crypto/openpgp, unmaintained) and GO-2022-0646 / GO-2022-0635 (aws-sdk-go v1 S3 crypto), none of which has a fixed version. Getting there took two pins, both already in the branch:

  • containerd/v2 at v2.2.5 rather than the v2.2.4 buildkit asks for (v2.2.4 carries GO-2026-5064/5338/5475/5622/5758, all fixed in v2.2.5);
  • klauspost/compress at v1.18.7 rather than the v1.18.6 buildkit asks for (v1.18.6 carries GO-2026-5841, an OOB read in the s2 decoder; unreachable from trdl, but it was the only module-level advisory this branch added over main, so it is gone now).

  The two remaining symbol-level items govulncheck prints are stdlib on the scanning host's go1.26.4 toolchain, not properties of this module — trdl builds on the go1.25.12 toolchain pinned in trdl.yaml.

For precedent on shipping with these two checks red: #389 was merged with the same pair failing.

CI

The Tests, Lint, Broken links checker and Test website workflows are sitting at action_required and have never run on this PR — they need a maintainer to approve workflows for a first-time fork contributor. Locally, on 73a6cbf: go test ./... passes (9 packages), task server:lint reports 0 issues with Prettier clean, task docs:gen produces no diff for this PR's partial, and go mod tidy changes nothing.

The only docs:gen drift I do see is pre-existing and unrelated — docs/_includes/reference/cli/trdl_use.md is stale on main relative to the client help text changed in #391. Happy to fix it here or leave it for a separate PR, whichever you prefer.

[vmrm]

@alexey-igrychev could you take a look when you get a chance, or point me at whoever should?

Two concrete asks:

1. Approve the workflow runs. Tests, Lint, Broken links checker and Test website are all stuck at action_required — as a first-time fork contributor I cannot trigger them, so this PR has never actually been through CI here. Everything passes locally (details in the comment above), but that is my word, not a run you can click on.
2. Triage the two Snyk checks, or tell me they are expected to stay red. Their findings are only visible inside the werf Snyk org, so I have no way to see what they name. The comment above lays out what I could verify from the outside — licenses of all 46 new modules are permissive, and govulncheck now shows the same module-level advisory set as main.

On the design itself, the one question genuinely worth your call is whether buildkitd_address belongs in per-project configure at all, or whether the env variable alone would do. It is in configure because in module-based deployments there is no way to inject env vars into the Vault pod, but that is a public API surface, so it is your decision rather than mine. Happy to cut it back to env-only if you would rather not widen configure.

[vmrm]

Superseded by #409, which carries these four commits unchanged (a3929420, c562b8a6, 5e3e8a10, 73a6cbf9 — same SHAs, now on a branch in this repo) and adds registry credentials for the BuildKit session, the context-reader and log-tail fixes, endpoint validation, the security section in QUICKSTART, and — the part missing here — CI that runs the release cycle against a real buildkitd. Approved it there; closing this one so review happens in one place.

Nothing from this PR is lost: the branch vmrm/trdl:feat/server/buildkit-client-builder stays for reference, but #409 is the one to merge.

[alexey-igrychev]

Merged as #409 — thank you, this is the shape it landed in.

Your four commits are the base of that PR. The squash merge collapsed them into 43912ab, so main carries one commit that names this PR and you in its body rather than your commits individually.

What changed on top of your work:

• Registry credentials. The Solve session attached only the context uploader and the secrets provider, so no registry auth reached buildkitd — with image-resolve-mode=pull and no cache, a private base image could not be resolved at all, while the CLI path receives those credentials from the docker config through buildx. The same docker-config auth provider is now attached.
• Build context release. The upload provider closes the reader only once buildkitd pulls the context, so a Solve failing before that left the goroutine streaming the context blocked on write forever, holding its 64 MiB buffer. Builder.Build now closes the reader on return, which covers the exec path too.
• Coverage. The unit tests asserted the maps the same helpers had just built: removing the context uploader from the session — which breaks every build — kept the whole suite green. They now assert by interface that the session serves the context, the secrets and the registry credentials. server:test:ai and a CI job were added because no task passed -tags ai_tests, so TestAI_BuildkitSmoke had never run anywhere; it now runs against a buildkitd container on every PR, and so does the full release cycle through the flow_vault suite with TRDL_TEST_BUILDKITD_ADDRESS.
• Docs. The plaintext and unauthenticated tcp:// transport, the address as a trust boundary for whoever can write configure, and the shared daemon are stated as the administrator's responsibility. That is a documented risk rather than a code mitigation; TLS options are the follow-up if a deployment needs a remote daemon over an untrusted network.
• Smaller: an address whose scheme carries no endpoint is rejected at configure time, the build log drains before the build returns, ValidateBuildkitdAddress takes a context, ContextPath is renamed after what it holds.

On your two asks: both Snyk checks came out green on #409 (No license issues in 3 tests, 3 security tests have passed), so there was nothing left to triage — your containerd/v2 and klauspost/compress pins did their job. The one thing this PR could not have known, since its own workflows never ran: the e2e module consumes the server module through replace, so the BuildKit dependency chain left e2e/go.mod incomplete, and both lint and the e2e suite failed until go mod tidy ran there.

Two pre-existing defects surfaced while reviewing this and are fixed in #416: #410 (a passwordless mac signing certificate takes the signer stage down) and #411 (a build log line above 64 KB hangs the release task). #413 proposes dropping the ai_tests convention that kept your smoke test out of CI in the first place.

#412 covers the "no environment variables in the pod" half of the motivation without any of this dependency cost, and is being handled separately — it will need a rebase now that #409 has landed.