Update Envoy build-image docs and Docker Hub role for toolshed envoy-build variants

[Copilot]

Envoy docs and helper code still referenced the retired envoy-build-ubuntu / envoy-build-tools setup. This PR updates references to the current toolshed-managed envoyproxy/envoy-build model with variant-prefixed tags and clarifies variant-specific image size expectations.

• CI docs (ci/README.md)

  • Renamed the Linux image section to distro-neutral wording.
  • Replaced envoy-build-ubuntu and envoy-build-tools references with:
    • envoyproxy/envoy-build:ci-<tag>
    • envoyproxy/toolshed/docker/build
  • Updated default Linux ENVOY_BUILD_IMAGE docs to envoyproxy/envoy-build (ci variant) and refreshed example commands to docker.io/envoyproxy/envoy-build:ci-<tag>.
  • Updated base/compiler statement to Debian trixie-slim + GCC 13 + Clang 18.

• Install docs (docs/root/start/install.rst)

  • Switched section heading/link to envoyproxy/envoy-build.
  • Replaced legacy variant rows with new tag scheme (build => ci, build-mobile).
  • Added pointer to toolshed for the full variant set.
  • Reworded disk guidance to be variant-specific (ci/gcc/mobile large; worker/devtools/docker/test smaller).

• Local Docker build docs (docs/root/start/building/local_docker_build.rst)

  • Updated warning link to the new build image tags page filtered for ci-.

• Sphinx Docker Hub role (docs/conf.py)

  • Reworked dockerhub_envoy build-image mapping to generate envoyproxy/envoy-build:<variant>-<build_sha> links.
  • Default mapping now treats :dockerhub_envoy:\build`asci`.
  • Preserved compatibility for legacy build-ubuntu* inputs by translating them to new variants.

Example of the role behavior after this change:

:dockerhub_envoy:`build`         # -> envoyproxy/envoy-build:ci-<build_sha>
:dockerhub_envoy:`build-mobile`  # -> envoyproxy/envoy-build:mobile-<build_sha>
# Docker Hub URL pattern:
# https://hub.docker.com/r/envoyproxy/envoy-build/tags?name=<variant>-

Original prompt

Background

Envoy CI's prebuilt Docker build images used to live in
envoyproxy/envoy-build-tools
and were Ubuntu-based (image name: envoyproxy/envoy-build-ubuntu).

They are now built in envoyproxy/toolshed,
are Debian-based, and use a single image repository envoyproxy/envoy-build
with variant-prefixed tags (semver-based, see docker/build/VERSION.txt — currently 0.1.1-dev):

variant	tag form	notes
ci	envoyproxy/envoy-build:ci-<ver>	default for Linux CI builds (was envoy-build-ubuntu). Contains LLVM/clang — large image.
gcc	envoyproxy/envoy-build:gcc-<ver>	GCC toolchain. Large.
mobile	envoyproxy/envoy-build:mobile-<ver>	Mobile build (was envoy-build-ubuntu:mobile). amd64 only. Large.
worker	envoyproxy/envoy-build:worker-<ver>	Slim CI worker.
devtools	envoyproxy/envoy-build:devtools-<ver>	Slim.
docker	envoyproxy/envoy-build:docker-<ver>	Slim, used for dind targets.
test	envoyproxy/envoy-build:test-<ver>	Slim, internal test only.

The variants/tag scheme are confirmed by
docker/build/linux/debian_build.sh
and used by the build-image SHA workflow already in this repo (.github/workflows/envoy-dependency.yml,
update-build-image job, which references docker.io/envoyproxy/envoy-build:ci-<tag>,
:devtools-<tag>, :docker-<tag>, :gcc-<tag>, :mobile-<tag>, :worker-<tag>).

A few docs and code comments in envoyproxy/envoy were not updated when this migration happened.

Task

Update all stale references to envoy-build-ubuntu and envoyproxy/envoy-build-tools so they
point at the new envoy-build image and at envoyproxy/toolshed. Also adjust disk-space warnings:
the new image is only large for variants that still bundle LLVM (ci, gcc, mobile); for
other variants (worker, devtools, docker, test) the image is small. Since the default
build variant (ci) still bundles LLVM, the existing 4-5GB warning is still appropriate for the
default user-facing build flow — but rewording is required (see below).

Files to change

1. ci/README.md

• Section "Ubuntu Envoy image" (around L4-L11): rename to something distro-neutral
  (e.g. "Linux build image"). Update the image name to envoyproxy/envoy-build:ci-<hash>,
  fix the Docker Hub link, and update the link that points developers at
  envoyproxy/envoy-build-tools/blob/main/toolchains/rbe_toolchains_config.bzl#L8 so it points
  to the equivalent location in envoyproxy/toolshed — the build images are now sourced from
  envoyproxy/toolshed/docker/build.
• Section "Build image base and compiler versions" (around L41):
  Replace the bullet
  * envoyproxy/envoy-build-ubuntu — based on Ubuntu 20.04 (Focal) with GCC 13 and Clang 18 compiler.
  with the equivalent for the current Debian image. Look up the actual base and toolchain versions
  from docker/build/linux/debian/Dockerfile
  and fun.sh
  in toolshed (likely Debian + currently shipped Clang/GCC versions). Also update the source-of-truth
  link from envoyproxy/envoy-build-tools to envoyproxy/toolshed. Fix the typo "theis" → "these".
• Section "Building and running tests as a developer" (around L72-L92):
  • Default ENVOY_BUILD_IMAGE on Linux: change envoyproxy/envoy-build-ubuntu → envoyproxy/envoy-build (variant ci).
  • Update the two example commands so they use docker.io/envoyproxy/envoy-build:ci-<tag>
    (or document that <tag> is now of the form ci-<sha> / ci-<semver>).

2. docs/root/start/install.rst (around L228-L257, the _install_tools section)

• Heading and dockerhub link: replace
  envoyproxy/envoy-build-ubuntu (and the link https://hub.docker.com/r/envoyproxy/envoy-build-ubuntu)
  with envoyproxy/envoy-build (link https://hub.docker.com/r/envoyproxy/envoy-build).
• Variant table currently lists envoy-build-ubuntu (default) and envoy-build-ubuntu:mobile.
  Replace with the new variants. At minimum show:
  • envoy-build:ci (default — what users will pull when ...

This pull request was created from Copilot chat.

[repokitteh-read-only]

As a reminder, PRs marked as draft will not be automatically assigned reviewers,
or be handled by maintainer-oncall triage.

Please mark your PR as ready when you want it to be reviewed!

🐱

Caused by: #44937 was opened by Copilot.

see: more, trace.