docs(docker): document dind MTU inheritance gap and workaround

Rehabrequested to merge
rehab/gitlab-runner:rehab/docs-dind-mtu-blackhole into main

What does this MR do?

Adds a subsection to docs/executors/docker.md under Overriding the MTU of the created network, documenting a failure mode that surfaces when a runner's Docker bridge MTU is lowered below 1500 and users run jobs through a docker:dind service.

The inner dockerd inside docker:dind does not inherit the runner's outer bridge MTU and defaults to 1500. When the outer bridge is lower (for example 1360), large packets from build containers inside dind are dropped at the inner/outer bridge boundary. Because ICMP fragmentation needed replies are commonly filtered along egress paths to CDN-fronted endpoints, the sender never learns to shrink, and connections hang silently.

A common observable symptom: dotnet restore or curl https://api.nuget.org/v3/index.json timing out from inside docker build. Forum thread: https://forum.gitlab.com/t/docker-in-docker-network-issue-nuget-hang/133841

Why now

GitLab.com SaaS small-amd64 runners lowered their host Docker bridge MTU from 1460 to 1360 on 2026-05-13 to mitigate a PMTUD blackhole to Microsoft Front Door (NuGet's CDN). Users hitting that path from inside docker:dind continued to fail because the inner dind daemon defaults to 1500, and the failure mode is silent.

The behavior is not SaaS-specific. Any self-managed runner with a non-1500 host bridge MTU (OpenStack, ISP-induced tunnel overheads, IPSec VPN egress, etc.) will hit the same gap. The doc placement under the existing "Overriding the MTU" section keeps related guidance together.

Verification

Reproduced empirically:

  • docker:dind without --mtu: 5/5 curl https://api.nuget.org/v3/index.json attempts timed out (code=000). Inner docker0 reported MTU 1500.
  • docker:dind with command: ["--mtu=1360"]: 5/5 attempts returned HTTP 200 in ~260 ms.

Public diagnostic project + full sweep: https://gitlab.com/rehab/nuget-connectivity-test/-/pipelines/2523136475

Style

Follows the prose-first pattern used in nearby subsections (How the runner creates a network for each job, Overriding the MTU of the created network): short paragraph describing the issue, code example, single-line note about acceptable values. No new shortcodes or callouts introduced.

Related

Closes gitlab-com/gl-infra/production-engineering#29049 (closed)

Merge request reports