[main] Update common Docker engineering infrastructure with latest (#1310)

Author: dotnet-docker-bot

eng/docker-tools/CHANGELOG.md

@@ -4,6 +4,36 @@ All breaking changes and new features in `eng/docker-tools` will be documented i
 
 ---
 
+## 2026-06-11: Configurable per-registry referrer-lookup rate limit
+
+- Issue: [#2141](https://github.com/dotnet/docker-tools/issues/2141)
+
+ImageBuilder now rate limits only OCI referrer lookups (the ACR
+`/v2/<repo>/referrers/<digest>` endpoint), instead of throttling and bounding the concurrency of all
+ACR operations. All other ACR operations rely on the standard HTTP retry behavior, which retries on
+HTTP 429 and respects `Retry-After` headers. This significantly speeds up image copying during
+publishing.
+
+The referrer-lookup limit defaults to 250 requests per 60-second window and can be configured per
+registry via an optional `referrerRequestsPerMinute` field on each `RegistryAuthentication` entry in
+`publishConfig`:
+
+```yaml
+RegistryAuthentication:
+  - server: $(acr.server)
+    resourceGroup: $(acr.resourceGroup)
+    subscription: $(acr.subscription)
+    referrerRequestsPerMinute: 1000
+    serviceConnection:
+      name: $(publish.serviceConnectionName)
+      ...
+```
+
+This field is optional; when omitted, the 250/60s default is used. No action is required for
+existing configurations.
+
+---
+
 ## 2026-04-02: Extra Docker build options can be passed through ImageBuilder
 
 - Pull request: [#2063](https://github.com/dotnet/docker-tools/pull/2063)

eng/docker-tools/DEV-GUIDE.md

@@ -143,6 +143,7 @@ Build Stage
               ▼
           Post_Build Stage
             ├── Merge image info files
+            ├── Create multi-arch manifests
             └── Consolidate SBOMs
                     │
                     ▼
@@ -191,13 +192,35 @@ Common patterns:
 - `"publish"` - Publish only (when re-running a failed publish from a previous build)
 - `"build,test,sign,publish"` - Full pipeline
 
-**Note:** The `Post_Build` stage is implicitly included whenever `build` is in the stages list. You don't need to specify it separately—it automatically runs after Build to merge image info files and consolidate SBOMs.
+**Note:** The `Post_Build` stage is implicitly included whenever `build` is in the stages list. You don't need to specify it separately—it automatically runs after Build to merge image info files, create and validate multi-arch manifests, and consolidate SBOMs.
 
 The stages variable is useful for:
 - Re-running just the publish stage after fixing a transient failure
 - Skipping tests during initial development
 - Running isolated stages for debugging
 
+### Decoupling build OS from the base image OS
+
+By default, a platform's `osVersion` represents the base image OS version, but also determines what
+build leg an image is built in. This can cause problems when build image and base image don't match
+up. For example, building a .NET app on Windows Server 2025 and copying the artifacts into a
+Windows Server 2019 base image won't work, because the build matrix generation will attempt to
+build the image on the Server 2019 build leg (which can't run Server 2025 images).
+
+To fix this, set the optional `buildOsVersion` field in order to override only the OS used in the
+build matrix generation. Here is an example of building a Windows Server 2019 image using Windows
+Server 2025:
+
+```jsonc
+{
+  // ...
+  "os": "windows",
+  "osVersion": "windowsservercore-ltsc2019",
+  "buildOsVersion": "windowsservercore-ltsc2025"
+  // ...
+}
+```
+
 ### Image Info Files: The Build's Memory
 
 Image info files (defined by [`ImageArtifactDetails`](https://github.com/dotnet/docker-tools/blob/main/src/ImageBuilder/Models/Image/ImageArtifactDetails.cs)) are the mechanism that tracks what was built:

eng/docker-tools/templates/variables/docker-images.yml

@@ -1,5 +1,5 @@
 variables:
-  imageNames.imageBuilderName: mcr.microsoft.com/dotnet-buildtools/image-builder:2986591
+  imageNames.imageBuilderName: mcr.microsoft.com/dotnet-buildtools/image-builder:3002630
   imageNames.imageBuilder: $(imageNames.imageBuilderName)
   imageNames.imageBuilder.withrepo: imagebuilder-withrepo:$(Build.BuildId)-$(System.JobId)
   imageNames.testRunner: mcr.microsoft.com/dotnet-buildtools/prereqs:azurelinux3.0-docker-testrunner