diff --git a/eng/docker-tools/CHANGELOG.md b/eng/docker-tools/CHANGELOG.md index 99dbceb6..0936f6fe 100644 --- a/eng/docker-tools/CHANGELOG.md +++ b/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//referrers/` 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) diff --git a/eng/docker-tools/DEV-GUIDE.md b/eng/docker-tools/DEV-GUIDE.md index 28ddc471..d47fb3eb 100644 --- a/eng/docker-tools/DEV-GUIDE.md +++ b/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: diff --git a/eng/docker-tools/templates/variables/docker-images.yml b/eng/docker-tools/templates/variables/docker-images.yml index edeb54f1..4a68f55a 100644 --- a/eng/docker-tools/templates/variables/docker-images.yml +++ b/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