Fix the build argument syntax in the BuildKit proxy example

José M. Requena Plensrequested to merge
gitlab-community/gitlab-org/gitlab:jmrp-buildkit-proxy-build-arg-syntax into master

What does this MR do?

The Configure proxy settings example on the BuildKit page passes the proxy variables to buildctl-daemonless.sh with --build-arg. That flag belongs to docker build and docker buildx build. buildctl has no such flag: it takes build arguments as frontend options, --opt build-arg:<name>=<value>, as the BuildKit README and buildctl build --help both show. buildctl-daemonless.sh starts buildkitd and hands its arguments to buildctl, so a job copied from the page stops with error: flag provided but not defined: -build-arg before it builds anything.

This MR changes the three lines to --opt build-arg:http_proxy=$http_proxy, and the same for https_proxy and no_proxy. Nothing else on the page changes. No other page in doc/ passes --build-arg to buildctl: the other --build-arg examples are docker build commands and one Auto DevOps variable, so this MR leaves them alone. The translated copies of this page under doc-locale/ (fr-fr, ja-jp and ko-kr) carry the same three lines. I left them alone too, since translations are updated by automation from the English source.

The build arguments themselves are still needed. The job variables reach buildkitd, which pulls the base image through the proxy, but a RUN step does not inherit the daemon's environment, so it sees the proxy only if the build passes it in, which is what these three arguments do. The third run below shows the difference.

How I checked it

I ran the page's own job script in moby/buildkit:rootless (buildctl v0.34.0, digest sha256:65eca3c01cd1) on Docker 29.8.1, with --privileged and BUILDKITD_FLAGS=--oci-worker-no-process-sandbox. The job container sat on a Docker network created with --internal, which has no route out. A Squid proxy (ubuntu/squid) sat on that network and on an ordinary one, so the proxy was the job's only way to the internet, as on a runner behind a proxy. Before each build, a busybox container on the internal network tried example.com directly and got wget: bad address 'example.com'.

A script read the build-behind-proxy block from the page at master b00391b1ec3 and at this branch, and ran it with the job variables set as the example sets them: http_proxy and https_proxy pointing at Squid, and no_proxy=localhost,127.0.0.1. Two things differ from the page: push=false in --output, since there is no registry to push to, and --progress=plain, so that the RUN output shows. The before_script only writes registry credentials, so I skipped it.

The Dockerfile:

FROM busybox:1.37
RUN echo "http_proxy=$http_proxy https_proxy=$https_proxy no_proxy=$no_proxy" \
 && wget -O /dev/null http://example.com/

The logs below keep the output of the RUN step, the end of the job and the Squid access log. They leave out the step and time prefix BuildKit puts on each line, the progress bar wget prints, and the summary of the failed step that BuildKit repeats before its final error.

The page on master (--build-arg http_proxy=$http_proxy and so on):

Incorrect Usage: flag provided but not defined: -build-arg
[buildctl build usage, including:]
   --opt string [ --opt string ]   Define custom options for frontend, e.g. --opt target=foo --opt build-arg:foo=bar
error: flag provided but not defined: -build-arg
job script exit status: 1

Squid access log: empty

The page on this branch (--opt build-arg:http_proxy=$http_proxy and so on):

http_proxy=http://192.168.16.2:3128 https_proxy=http://192.168.16.2:3128 no_proxy=localhost,127.0.0.1
Connecting to 192.168.16.2:3128 (192.168.16.2:3128)
saving to '/dev/null'
'/dev/null' saved
job script exit status: 0

Squid access log:
TCP_MISS/200 GET http://example.com/
TCP_TUNNEL/200 CONNECT auth.docker.io:443
TCP_TUNNEL/200 CONNECT production.cloudfront.docker.com:443
TCP_TUNNEL/200 CONNECT registry-1.docker.io:443

The RUN step sees the three values, and its request to example.com goes through the proxy. The daemon pulls busybox through the proxy too.

The page on this branch without the three build argument lines, to show why they are there:

http_proxy= https_proxy= no_proxy=
wget: bad address 'example.com'
error: failed to solve: process "/bin/sh -c echo \"http_proxy=$http_proxy https_proxy=$https_proxy no_proxy=$no_proxy\"  && wget -O /dev/null http://example.com/" did not complete successfully: exit code: 1
job script exit status: 1

Squid access log:
TCP_TUNNEL/200 CONNECT auth.docker.io:443
TCP_TUNNEL/200 CONNECT production.cloudfront.docker.com:443
TCP_TUNNEL/200 CONNECT registry-1.docker.io:443

The daemon still pulls through the proxy, but the RUN step has no proxy variables. It tries example.com directly, which it cannot reach, and the build fails.

Lint
  • markdownlint-cli2, scripts/lint-doc.sh and lychee --offline --no-progress --include-fragments on doc/ci/docker/using_buildkit.md, in the image the docs-lint jobs use (markdownlint-cli2 0.23.2, Vale 3.21.0, lychee 0.24.2): all passed, with no markdownlint issues and no link errors.
  • Vale at suggestion level gives the same three suggestions, word for word, on this branch and on master: the page's reading level (10.02 on both) and two lines this MR does not touch. This MR adds none.
  • The commit message passes scripts/lint/commit_linter.rb and the Danger commit linter (gitlab-dangerfiles 4.12.0).

Related issues

Closes #576283 (closed)

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

Merge request reports