From f3053809ff8f2f1250969445f26e4cb0aa9526d6 Mon Sep 17 00:00:00 2001
From: dotnet-docker-bot <60522487+dotnet-docker-bot@users.noreply.github.com>
Date: Fri, 10 Apr 2026 14:39:28 -0700
Subject: [PATCH] Update common Docker engineering infrastructure with latest

---
 eng/docker-tools/CHANGELOG.md                 | 21 +++++++++++++++++++
 eng/docker-tools/DEV-GUIDE.md                 | 11 +++++++++-
 .../templates/variables/docker-images.yml     |  2 +-
 3 files changed, 32 insertions(+), 2 deletions(-)

diff --git a/eng/docker-tools/CHANGELOG.md b/eng/docker-tools/CHANGELOG.md
index 76a9ec60..99dbceb6 100644
--- a/eng/docker-tools/CHANGELOG.md
+++ b/eng/docker-tools/CHANGELOG.md
@@ -4,6 +4,27 @@ All breaking changes and new features in `eng/docker-tools` will be documented i
 
 ---
 
+## 2026-04-02: Extra Docker build options can be passed through ImageBuilder
+
+- Pull request: [#2063](https://github.com/dotnet/docker-tools/pull/2063)
+
+ImageBuilder's `build` command now accepts repeated `--build-option` arguments and forwards them directly to
+`docker build`. This allows repos to pass options such as `--ulimit nofile=65536:65536` or `--network host`
+through `imageBuilderBuildArgs`, in addition to standard Dockerfile `--build-arg` values.
+
+**How to use:**
+
+```yaml
+customBuildInitSteps:
+- powershell: |
+    $args = '--build-option "--ulimit nofile=65536:65536"'
+    echo "##vso[task.setvariable variable=imageBuilderBuildArgs]$args"
+```
+
+Repeat `--build-option` for multiple Docker arguments, and quote values that contain spaces.
+
+---
+
 ## 2026-03-25: Manifest list creation moved to Post_Build
 
 - Issue: [#2002](https://github.com/dotnet/docker-tools/issues/2002)
diff --git a/eng/docker-tools/DEV-GUIDE.md b/eng/docker-tools/DEV-GUIDE.md
index 8297a6e6..f834566d 100644
--- a/eng/docker-tools/DEV-GUIDE.md
+++ b/eng/docker-tools/DEV-GUIDE.md
@@ -370,7 +370,7 @@ To force a rebuild regardless of cache state, set the `noCache` parameter to `tr
 
 ### Pattern: Adding Build Arguments
 
-Pass additional arguments to Docker builds via ImageBuilder:
+Pass Dockerfile `ARG` values via ImageBuilder:
 
 ```yaml
 customBuildInitSteps:
@@ -379,6 +379,15 @@ customBuildInitSteps:
     echo "##vso[task.setvariable variable=imageBuilderBuildArgs]$args"
 ```
 
+To pass raw options directly to `docker build`, use `--build-option`. Quote values that contain spaces:
+
+```yaml
+customBuildInitSteps:
+- powershell: |
+    $args = '--build-option "--ulimit nofile=65536:65536"'
+    echo "##vso[task.setvariable variable=imageBuilderBuildArgs]$args"
+```
+
 ### Pattern: Re-running Stages with `stages` and `sourceBuildPipelineRunId`
 
 A powerful pattern is combining the `stages` variable with the `sourceBuildPipelineRunId` pipeline parameter to run specific stages using artifacts from a previous build. This is useful for:
diff --git a/eng/docker-tools/templates/variables/docker-images.yml b/eng/docker-tools/templates/variables/docker-images.yml
index f9ef46fc..e88babbf 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:2941471
+  imageNames.imageBuilderName: mcr.microsoft.com/dotnet-buildtools/image-builder:2948340
   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