Add support for extra Docker build options (#2064)

Ports #2063 to my fork since
I don't have access to Premeks

---------

Co-authored-by: Premek Vysoky <premek.vysoky@microsoft.com>
Co-authored-by: Logan Bussell <loganbussell@microsoft.com>

Author: 3 people

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)

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:

src/ImageBuilder.Tests/BuildCommandTests.cs

@@ -527,6 +527,7 @@ public async Task BuildCommand_Publish()
                         TagInfo.GetFullyQualifiedName(repoName, sharedTag)
                     },
                     It.IsAny<IDictionary<string, string>>(),
+                    It.IsAny<IEnumerable<string>>(),
                     It.IsAny<bool>(),
                     It.IsAny<bool>()));
 
@@ -694,6 +695,61 @@ public async Task BuildCommand_BuildArgs()
                     It.IsAny<List<string>>(),
                     It.Is<Dictionary<string, string>>(
                         args => args.Count == 3 && args["arg1"] == "val1" && args["arg2"] == "val2b" && args["arg3"] == "val3"),
+                    It.IsAny<IEnumerable<string>>(),
+                    It.IsAny<bool>(),
+                    It.IsAny<bool>()));
+            dockerServiceMock.Verify(
+                o => o.GetImageSize(It.IsAny<string>(), false));
+        }
+
+        /// <summary>
+        /// Verifies that Docker build options can be passed through to the Docker build command.
+        /// </summary>
+        [Fact]
+        public async Task BuildCommand_DockerBuildOptions()
+        {
+            const string repoName = "runtime";
+            const string tag = "tag";
+            const string baseImageRepo = "baserepo";
+            string baseImageTag = $"{baseImageRepo}:basetag";
+
+            using TempFolderContext tempFolderContext = TestHelper.UseTempFolder();
+            Mock<IDockerService> dockerServiceMock = CreateDockerServiceMock();
+
+            BuildCommand command = CreateBuildCommand(
+                dockerService: dockerServiceMock.Object,
+                copyImageService: Mock.Of<ICopyImageService>(),
+                manifestServiceFactory: CreateManifestServiceFactoryMock().Object,
+                imageCacheService: new ImageCacheService(Mock.Of<ILogger<ImageCacheService>>(), Mock.Of<IGitService>()));
+            command.Options.Manifest = Path.Combine(tempFolderContext.Path, "manifest.json");
+            command.Options.DockerBuildOptions = ["--ulimit nofile=65536:65536", "--network host"];
+
+            Platform platform = CreatePlatform(
+                DockerfileHelper.CreateDockerfile("1.0/runtime/os", tempFolderContext, baseImageTag),
+                new string[] { tag });
+
+            Manifest manifest = CreateManifest(
+                CreateRepo(repoName,
+                    CreateImage(
+                        new Platform[]
+                        {
+                            platform
+                        }))
+            );
+
+            File.WriteAllText(Path.Combine(tempFolderContext.Path, command.Options.Manifest), JsonConvert.SerializeObject(manifest));
+
+            command.LoadManifest();
+            await command.ExecuteAsync();
+
+            dockerServiceMock.Verify(
+                o => o.BuildImage(
+                    It.IsAny<string>(),
+                    It.IsAny<string>(),
+                    It.IsAny<string>(),
+                    It.IsAny<List<string>>(),
+                    It.IsAny<IDictionary<string, string>>(),
+                    It.Is<IEnumerable<string>>(args => args.SequenceEqual(command.Options.DockerBuildOptions)),
                     It.IsAny<bool>(),
                     It.IsAny<bool>()));
             dockerServiceMock.Verify(
@@ -757,6 +813,7 @@ public async Task BuildCommand_NoBaseImage_Build()
                         TagInfo.GetFullyQualifiedName(repoName, sharedTag)
                     },
                     It.IsAny<IDictionary<string, string>>(),
+                    It.IsAny<IEnumerable<string>>(),
                     It.IsAny<bool>(),
                     It.IsAny<bool>()));
             dockerServiceMock.Verify(
@@ -949,7 +1006,7 @@ public async Task BuildCommand_NoBaseImage_Cached()
                 o.BuildImage(
                     PathHelper.NormalizePath(Path.Combine(tempFolderContext.Path, runtimeDepsLinuxDockerfileRelativePath)),
                     It.IsAny<string>(), It.IsAny<string>(), It.IsAny<IEnumerable<string>>(), It.IsAny<IDictionary<string, string>>(),
-                    It.IsAny<bool>(), It.IsAny<bool>()),
+                    It.IsAny<IEnumerable<string>>(), It.IsAny<bool>(), It.IsAny<bool>()),
                 Times.Never);
             dockerServiceMock.Verify(
                 o => o.GetImageSize(It.IsAny<string>(), false),
@@ -1679,7 +1736,7 @@ public async Task BuildCommand_Caching_SharedDockerfile_MissingSourceImageInfoEn
             dockerServiceMock.Verify(o =>
                 o.BuildImage(
                     It.IsAny<string>(), It.IsAny<string>(), It.IsAny<string>(), It.IsAny<IEnumerable<string>>(),
-                    It.IsAny<IDictionary<string, string>>(), It.IsAny<bool>(), It.IsAny<bool>()),
+                    It.IsAny<IDictionary<string, string>>(), It.IsAny<IEnumerable<string>>(), It.IsAny<bool>(), It.IsAny<bool>()),
                 Times.Never);
 
             dockerServiceMock.VerifyNoOtherCalls();
@@ -1987,6 +2044,7 @@ public async Task BuildCommand_Caching_SharedDockerfile_MissingSourceImageInfoEn
                     It.IsAny<string>(),
                     It.IsAny<IEnumerable<string>>(),
                     It.IsAny<IDictionary<string, string>>(),
+                    It.IsAny<IEnumerable<string>>(),
                     It.IsAny<bool>(),
                     It.IsAny<bool>()));
             dockerServiceMock.Verify(o => o.GetImageSize($"{runtimeDeps3Repo}:{tag}", false));
@@ -2193,6 +2251,7 @@ public async Task BuildCommand_Caching_SharedDockerfile_NoExistingImageInfoEntri
                         It.IsAny<string>(),
                         new string[] { expectedTag },
                         It.IsAny<IDictionary<string, string>>(),
+                        It.IsAny<IEnumerable<string>>(),
                         It.IsAny<bool>(),
                         It.IsAny<bool>()),
                     Times.Once);
@@ -2436,6 +2495,7 @@ public async Task BuildCommand_SharedDockerfile()
                         It.IsAny<string>(),
                         new string[] { expectedTag },
                         It.IsAny<IDictionary<string, string>>(),
+                        It.IsAny<IEnumerable<string>>(),
                         It.IsAny<bool>(),
                         It.IsAny<bool>()),
                     Times.Once);
@@ -2653,7 +2713,7 @@ public async Task BuildCommand_Caching_TagUpdate()
                 o.BuildImage(
                     PathHelper.NormalizePath(Path.Combine(tempFolderContext.Path, runtimeDepsLinuxDockerfileRelativePath)),
                     It.IsAny<string>(), It.IsAny<string>(), It.IsAny<IEnumerable<string>>(), It.IsAny<IDictionary<string, string>>(),
-                    It.IsAny<bool>(), It.IsAny<bool>()),
+                    It.IsAny<IEnumerable<string>>(), It.IsAny<bool>(), It.IsAny<bool>()),
                 Times.Never);
             dockerServiceMock.Verify(
                 o => o.GetImageSize(It.IsAny<string>(), false),
@@ -2912,7 +2972,7 @@ public async Task BuildCommand_Caching_SharedDockerfile_TagUpdate()
             dockerServiceMock.Verify(o =>
                 o.BuildImage(
                     It.IsAny<string>(), It.IsAny<string>(), It.IsAny<string>(), It.IsAny<IEnumerable<string>>(),
-                    It.IsAny<IDictionary<string, string>>(), It.IsAny<bool>(), It.IsAny<bool>()),
+                    It.IsAny<IDictionary<string, string>>(), It.IsAny<IEnumerable<string>>(), It.IsAny<bool>(), It.IsAny<bool>()),
                 Times.Never);
             dockerServiceMock.Verify(o => o.GetCreatedDate(It.IsAny<string>(), false));
 
@@ -3272,6 +3332,7 @@ public async Task BuildCommand_MirroredImages(bool hasCachedImage, string srcBas
                     It.IsAny<string>(),
                     It.IsAny<IEnumerable<string>>(),
                     It.IsAny<IDictionary<string, string>>(),
+                    It.IsAny<IEnumerable<string>>(),
                     It.IsAny<bool>(),
                     It.IsAny<bool>()));
 
@@ -3417,6 +3478,7 @@ public async Task BuildCommand_MirroredImages_External(string baseImageRegistry,
                     It.IsAny<string>(),
                     It.IsAny<IEnumerable<string>>(),
                     It.IsAny<IDictionary<string, string>>(),
+                    It.IsAny<IEnumerable<string>>(),
                     It.IsAny<bool>(),
                     It.IsAny<bool>()));
             dockerServiceMock.Verify(o => o.GetImageSize($"{RegistryOverride}/{SamplesRepo}:{Tag}", false));
@@ -3558,6 +3620,7 @@ public async Task BuildCommand_MirroredImages_BaseImageTagOverride()
                     It.IsAny<string>(),
                     It.IsAny<IEnumerable<string>>(),
                     It.IsAny<IDictionary<string, string>>(),
+                    It.IsAny<IEnumerable<string>>(),
                     It.IsAny<bool>(),
                     It.IsAny<bool>()));
             dockerServiceMock.Verify(
@@ -3621,6 +3684,7 @@ private static Mock<IDockerService> CreateDockerServiceMock(string buildOutput =
                         It.IsAny<string>(),
                         It.IsAny<IEnumerable<string>>(),
                         It.IsAny<IDictionary<string, string>>(),
+                        It.IsAny<IEnumerable<string>>(),
                         It.IsAny<bool>(),
                         It.IsAny<bool>()))
                 .Returns(buildOutput ?? string.Empty);

src/ImageBuilder/Commands/BuildCommand.cs

@@ -493,6 +493,7 @@ private void BuildImage(PlatformInfo platform, IEnumerable<string> allTags)
                     platform.PlatformLabel,
                     allTags,
                     GetBuildArgs(platform),
+                    GetDockerBuildOptions(),
                     Options.IsRetryEnabled,
                     Options.IsDryRun);
 
@@ -554,6 +555,9 @@ private void BuildImage(PlatformInfo platform, IEnumerable<string> allTags)
             return buildArgs;
         }
 
+        private IEnumerable<string> GetDockerBuildOptions() =>
+            Options.DockerBuildOptions.Where(option => !string.IsNullOrWhiteSpace(option));
+
         private async Task OnCacheHitAsync(RepoInfo repo, IEnumerable<TagInfo> allTags, bool pullImage, string sourceDigest)
         {
             _logger.LogInformation(string.Empty);

src/ImageBuilder/Commands/BuildOptions.cs

@@ -26,6 +26,7 @@ public class BuildOptions : ManifestOptions, IFilterableOptions
         public bool NoCache { get; set; }
         public string? SourceRepoPrefix { get; set; }
         public IDictionary<string, string> BuildArgs { get; set; } = new Dictionary<string, string>();
+        public string[] DockerBuildOptions { get; set; } = [];
         public bool SkipPlatformCheck { get; set; }
         public string? OutputVariableName { get; set; }
         public bool Internal { get; set; }
@@ -67,6 +68,8 @@ public override IEnumerable<Option> GetCliOptions() =>
                 "Prefix to add to the external base image names when pulling them"),
             CreateDictionaryOption("build-arg", nameof(BuildOptions.BuildArgs),
                 "Build argument to pass to the Dockerfiles (<name>=<value>)"),
+            CreateMultiOption<string>("build-option", nameof(BuildOptions.DockerBuildOptions),
+                "Additional argument to pass directly to docker build. Repeat for multiple arguments and quote values containing spaces."),
             CreateOption<bool>("skip-platform-check", nameof(BuildOptions.SkipPlatformCheck),
                 "Skips validation that ensures the Dockerfile's base image's platform matches the manifest configuration"),
             CreateOption<string>("digests-out-var", nameof(BuildOptions.OutputVariableName),

src/ImageBuilder/DockerService.cs

@@ -34,6 +34,7 @@ public void CreateManifestList(string manifestListTag, IEnumerable<string> image
             string platform,
             IEnumerable<string> tags,
             IDictionary<string, string?> buildArgs,
+            IEnumerable<string> dockerBuildOptions,
             bool isRetryEnabled,
             bool isDryRun)
         {
@@ -43,7 +44,12 @@ public void CreateManifestList(string manifestListTag, IEnumerable<string> image
                 .Select(buildArg => $" --build-arg {buildArg.Key}={buildArg.Value}");
             string buildArgsString = string.Join(string.Empty, buildArgList);
 
-            string dockerArgs = $"build --platform {platform} {tagArgs} -f {dockerfilePath}{buildArgsString} {buildContextPath}";
+            IEnumerable<string> dockerBuildOptionList = dockerBuildOptions
+                .Where(option => !string.IsNullOrWhiteSpace(option))
+                .Select(option => $" {option}");
+            string dockerBuildOptionsString = string.Join(string.Empty, dockerBuildOptionList);
+
+            string dockerArgs = $"build --platform {platform} {tagArgs} -f {dockerfilePath}{buildArgsString}{dockerBuildOptionsString} {buildContextPath}";
 
             if (isRetryEnabled)
             {

src/ImageBuilder/DockerServiceCache.cs

@@ -32,8 +32,8 @@ public DockerServiceCache(IDockerService inner)
 
         public string? BuildImage(
             string dockerfilePath, string buildContextPath, string platform, IEnumerable<string> tags,
-            IDictionary<string, string?> buildArgs, bool isRetryEnabled, bool isDryRun) =>
-            _inner.BuildImage(dockerfilePath, buildContextPath, platform, tags, buildArgs, isRetryEnabled, isDryRun);
+            IDictionary<string, string?> buildArgs, IEnumerable<string> dockerBuildOptions, bool isRetryEnabled, bool isDryRun) =>
+            _inner.BuildImage(dockerfilePath, buildContextPath, platform, tags, buildArgs, dockerBuildOptions, isRetryEnabled, isDryRun);
 
         public (Architecture Arch, string? Variant) GetImageArch(string image, bool isDryRun) =>
             _architectureCache.GetOrAdd(image, _ =>_inner.GetImageArch(image, isDryRun));

src/ImageBuilder/IDockerService.cs

@@ -29,6 +29,7 @@ public interface IDockerService
             string platform,
             IEnumerable<string> tags,
             IDictionary<string, string?> buildArgs,
+            IEnumerable<string> dockerBuildOptions,
             bool isRetryEnabled,
             bool isDryRun);