feat: Support configuring Docker API version (#1576)

HofmeisterAn · web-flow · commit 1666ac2820ac · 2025-11-14T15:58:36.000+01:00
diff --git a/docs/custom_configuration/index.md b/docs/custom_configuration/index.md
@@ -4,6 +4,7 @@ Testcontainers supports various configurations to set up your test environment.
 
 | Properties File                 | Environment Variable                           | Description                                                                                                               | Default                      |
 |---------------------------------|------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|------------------------------|
+| `docker.api.version`            | `DOCKER_API_VERSION`                           | The Docker API version to use.                                                                                            | `1.44`                       |
 | `docker.config`                 | `DOCKER_CONFIG`                                | The directory path that contains the Docker configuration (`config.json`) file.                                           | `~/.docker/`                 |
 | `docker.host`                   | `DOCKER_HOST`                                  | The Docker daemon socket to connect to.                                                                                   | -                            |
 | `docker.context`                | `DOCKER_CONTEXT`                               | The Docker context to connect to.                                                                                         | -                            |
diff --git a/src/Testcontainers/Builders/DockerDesktopEndpointAuthenticationProvider.cs b/src/Testcontainers/Builders/DockerDesktopEndpointAuthenticationProvider.cs
@@ -25,6 +25,12 @@ public override bool IsApplicable()
       return !RuntimeInformation.IsOSPlatform(OSPlatform.Windows) && DockerEngine != null;
     }
 
+    /// <inheritdoc />
+    public Version GetDockerApiVersion()
+    {
+      return null;
+    }
+
     /// <inheritdoc />
     public string GetDockerConfig()
     {
diff --git a/src/Testcontainers/Builders/DockerEndpointAuthenticationProvider.cs b/src/Testcontainers/Builders/DockerEndpointAuthenticationProvider.cs
@@ -41,7 +41,7 @@ public virtual bool IsAvailable()
         {
           using (var dockerClientConfiguration = authConfig.GetDockerClientConfiguration(ResourceReaper.DefaultSessionId))
           {
-            using (var dockerClient = dockerClientConfiguration.CreateClient())
+            using (var dockerClient = dockerClientConfiguration.CreateClient(authConfig.Version))
             {
               try
               {
diff --git a/src/Testcontainers/Builders/TestcontainersEndpointAuthenticationProvider.cs b/src/Testcontainers/Builders/TestcontainersEndpointAuthenticationProvider.cs
@@ -57,6 +57,12 @@ public override IDockerEndpointAuthenticationConfiguration GetAuthConfig()
       return new DockerEndpointAuthenticationConfiguration(_dockerEngine);
     }
 
+    /// <inheritdoc />
+    public Version GetDockerApiVersion()
+    {
+      return _customConfiguration.GetDockerApiVersion();
+    }
+
     /// <inheritdoc />
     public string GetDockerConfig()
     {
diff --git a/src/Testcontainers/Clients/DockerApiClient.cs b/src/Testcontainers/Clients/DockerApiClient.cs
@@ -134,7 +134,7 @@ private static IDockerClient GetDockerClient(Guid sessionId, IDockerEndpointAuth
     {
       using (var dockerClientConfiguration = dockerEndpointAuthConfig.GetDockerClientConfiguration(sessionId))
       {
-        return dockerClientConfiguration.CreateClient();
+        return dockerClientConfiguration.CreateClient(dockerEndpointAuthConfig.Version);
       }
     }
   }
diff --git a/src/Testcontainers/Configurations/AuthConfigs/DockerEndpointAuthenticationConfiguration.cs b/src/Testcontainers/Configurations/AuthConfigs/DockerEndpointAuthenticationConfiguration.cs
@@ -10,6 +10,9 @@ namespace DotNet.Testcontainers.Configurations
   [PublicAPI]
   public readonly struct DockerEndpointAuthenticationConfiguration : IDockerEndpointAuthenticationConfiguration
   {
+    // https://github.com/moby/moby/releases/tag/docker-v29.0.0.
+    private static readonly Version DockerEngineApi = EnvironmentConfiguration.Instance.GetDockerApiVersion() ?? PropertiesFileConfiguration.Instance.GetDockerApiVersion() ?? new Version(1, 44);
+
     // Since the static `TestcontainersSettings` class holds the detected container
     // runtime information from the auto-discovery mechanism, we can't add a static
     // `NamedPipeConnectionTimeout` property to it because that would create a
@@ -30,6 +33,9 @@ public DockerEndpointAuthenticationConfiguration(Uri endpoint, Credentials crede
       Credentials = credentials;
     }
 
+    /// <inheritdoc />
+    public Version Version => DockerEngineApi;
+
     /// <inheritdoc />
     public Uri Endpoint { get; }
 
diff --git a/src/Testcontainers/Configurations/AuthConfigs/IDockerEndpointAuthenticationConfiguration.cs b/src/Testcontainers/Configurations/AuthConfigs/IDockerEndpointAuthenticationConfiguration.cs
@@ -10,6 +10,12 @@ namespace DotNet.Testcontainers.Configurations
   [PublicAPI]
   public interface IDockerEndpointAuthenticationConfiguration
   {
+    /// <summary>
+    /// Gets the Docker API version.
+    /// </summary>
+    [CanBeNull]
+    Version Version { get; }
+
     /// <summary>
     /// Gets the Docker API endpoint.
     /// </summary>
diff --git a/src/Testcontainers/Configurations/CustomConfiguration.cs b/src/Testcontainers/Configurations/CustomConfiguration.cs
@@ -15,6 +15,11 @@ protected CustomConfiguration(IReadOnlyDictionary<string, string> properties)
       _properties = properties;
     }
 
+    protected virtual Version GetDockerApiVersion(string propertyName)
+    {
+      return _properties.TryGetValue(propertyName, out var propertyValue) && !string.IsNullOrEmpty(propertyValue) && Version.TryParse(propertyValue, out var dockerApiVersion) ? dockerApiVersion : null;
+    }
+
     protected virtual string GetDockerConfig(string propertyName)
     {
       return GetPropertyValue<string>(propertyName);
diff --git a/src/Testcontainers/Configurations/EnvironmentConfiguration.cs b/src/Testcontainers/Configurations/EnvironmentConfiguration.cs
@@ -10,6 +10,8 @@ namespace DotNet.Testcontainers.Configurations
   /// </summary>
   internal class EnvironmentConfiguration : CustomConfiguration, ICustomConfiguration
   {
+    private const string DockerApiVersion = "DOCKER_API_VERSION";
+
     private const string DockerConfig = "DOCKER_CONFIG";
 
     private const string DockerHost = "DOCKER_HOST";
@@ -54,11 +56,12 @@ static EnvironmentConfiguration()
     public EnvironmentConfiguration()
       : base(new[]
         {
-          DockerAuthConfig,
-          DockerCertPath,
+          DockerApiVersion,
           DockerConfig,
           DockerHost,
           DockerContext,
+          DockerAuthConfig,
+          DockerCertPath,
           DockerTls,
           DockerTlsVerify,
           DockerHostOverride,
@@ -82,6 +85,12 @@ public EnvironmentConfiguration()
     public static ICustomConfiguration Instance { get; }
       = new EnvironmentConfiguration();
 
+    /// <inheritdoc />
+    public Version GetDockerApiVersion()
+    {
+      return GetDockerApiVersion(DockerApiVersion);
+    }
+
     /// <inheritdoc />
     public string GetDockerConfig()
     {
diff --git a/src/Testcontainers/Configurations/ICustomConfiguration.cs b/src/Testcontainers/Configurations/ICustomConfiguration.cs
@@ -10,6 +10,14 @@ namespace DotNet.Testcontainers.Configurations
   /// </summary>
   internal interface ICustomConfiguration
   {
+    /// <summary>
+    /// Gets the Docker API version custom configuration.
+    /// </summary>
+    /// <returns>The Docker API version custom configuration.</returns>
+    /// <remarks>https://dotnet.testcontainers.org/custom_configuration/.</remarks>
+    [CanBeNull]
+    Version GetDockerApiVersion();
+
     /// <summary>
     /// Gets the Docker config custom configuration.
     /// </summary>
diff --git a/src/Testcontainers/Configurations/PropertiesFileConfiguration.cs b/src/Testcontainers/Configurations/PropertiesFileConfiguration.cs
@@ -56,6 +56,13 @@ public PropertiesFileConfiguration(params string[] lines)
     public static ICustomConfiguration Instance { get; }
       = new PropertiesFileConfiguration();
 
+    /// <inheritdoc />
+    public Version GetDockerApiVersion()
+    {
+      const string propertyName = "docker.api.version";
+      return GetDockerApiVersion(propertyName);
+    }
+
     /// <inheritdoc />
     public string GetDockerConfig()
     {
diff --git a/tests/Testcontainers.Tests/Fixtures/Containers/Unix/DockerTlsFixture.cs b/tests/Testcontainers.Tests/Fixtures/Containers/Unix/DockerTlsFixture.cs
@@ -9,7 +9,7 @@ public sealed class DockerTlsFixture : ProtectDockerDaemonSocket
   {
     public DockerTlsFixture()
       : base(new ContainerBuilder()
-        .WithCommand("--tlsverify=false"), "20.10.18")
+        .WithCommand("--tlsverify=false"), "29.0.0")
     {
     }
 
diff --git a/tests/Testcontainers.Tests/Fixtures/Containers/Unix/OpenSsl3_1Fixture.cs b/tests/Testcontainers.Tests/Fixtures/Containers/Unix/OpenSsl3_1Fixture.cs
@@ -5,7 +5,7 @@ namespace DotNet.Testcontainers.Tests.Fixtures
   [UsedImplicitly]
   public sealed class OpenSsl3_1Fixture : DockerMTls
   {
-    public OpenSsl3_1Fixture() : base("24.0.5")
+    public OpenSsl3_1Fixture() : base("29.0.0")
     {
     }
   }
diff --git a/tests/Testcontainers.Tests/Unit/Configurations/CustomConfigurationTest.cs b/tests/Testcontainers.Tests/Unit/Configurations/CustomConfigurationTest.cs
@@ -15,6 +15,7 @@ public sealed class EnvironmentConfigurationTest : IDisposable
 
       static EnvironmentConfigurationTest()
       {
+        EnvironmentVariables.Add("DOCKER_API_VERSION");
         EnvironmentVariables.Add("DOCKER_CONFIG");
         EnvironmentVariables.Add("DOCKER_HOST");
         EnvironmentVariables.Add("DOCKER_CONTEXT");
@@ -34,6 +35,18 @@ static EnvironmentConfigurationTest()
         EnvironmentVariables.Add("TESTCONTAINERS_NAMED_PIPE_CONNECTION_TIMEOUT");
       }
 
+      [Theory]
+      [InlineData("", "", null)]
+      [InlineData("DOCKER_API_VERSION", "", null)]
+      [InlineData("DOCKER_API_VERSION", "version", null)]
+      [InlineData("DOCKER_API_VERSION", "1.52", "1.52")]
+      public void GetDockerApiVersionCustomConfiguration(string propertyName, string propertyValue, string expected)
+      {
+        SetEnvironmentVariable(propertyName, propertyValue);
+        ICustomConfiguration customConfiguration = new EnvironmentConfiguration();
+        Assert.Equal(expected, customConfiguration.GetDockerApiVersion()?.ToString());
+      }
+
       [Theory]
       [InlineData("", "", null)]
       [InlineData("DOCKER_CONFIG", "", null)]
@@ -259,6 +272,17 @@ private static void SetEnvironmentVariable(string propertyName, string propertyV
 
     public sealed class PropertiesFileConfigurationTest
     {
+      [Theory]
+      [InlineData("", null)]
+      [InlineData("docker.api.version=", null)]
+      [InlineData("docker.api.version=version", null)]
+      [InlineData("docker.api.version=1.52", "1.52")]
+      public void GetDockerApiVersionCustomConfiguration(string configuration, string expected)
+      {
+        ICustomConfiguration customConfiguration = new PropertiesFileConfiguration(new[] { configuration });
+        Assert.Equal(expected, customConfiguration.GetDockerApiVersion()?.ToString());
+      }
+
       [Theory]
       [InlineData("", null)]
       [InlineData("docker.config=", null)]
diff --git a/tests/Testcontainers.Tests/Unit/Containers/Unix/ProtectDockerDaemonSocketTest.cs b/tests/Testcontainers.Tests/Unit/Containers/Unix/ProtectDockerDaemonSocketTest.cs
@@ -3,6 +3,7 @@ namespace DotNet.Testcontainers.Tests.Unit
   using System;
   using System.Linq;
   using System.Threading.Tasks;
+  using Docker.DotNet;
   using DotNet.Testcontainers.Builders;
   using DotNet.Testcontainers.Clients;
   using DotNet.Testcontainers.Configurations;
@@ -20,7 +21,7 @@ private static IDockerEndpointAuthenticationConfiguration GetAuthConfig(ProtectD
       return new IDockerEndpointAuthenticationProvider[] { new MTlsEndpointAuthenticationProvider(customConfiguration), new TlsEndpointAuthenticationProvider(customConfiguration) }.First(authProvider => authProvider.IsApplicable()).GetAuthConfig();
     }
 
-    public sealed class MTlsOpenSsl1_1_1 : IClassFixture<OpenSsl1_1_1Fixture>
+    public sealed class MTlsOpenSsl1_1_1 : IClassFixture<OpenSsl1_1_1Fixture>, IDockerEndpointAuthenticationConfiguration
     {
       private readonly ProtectDockerDaemonSocket _fixture;
 
@@ -32,11 +33,25 @@ public MTlsOpenSsl1_1_1(OpenSsl1_1_1Fixture dockerMTlsFixture)
         _authConfig = GetAuthConfig(dockerMTlsFixture);
       }
 
+      // The outdated image isn't compatible with the default Docker Engine API version.
+      // For this test, we're overriding the version.
+      public Version Version
+        => null;
+
+      public Uri Endpoint
+        => _authConfig.Endpoint;
+
+      public Credentials Credentials
+        => _authConfig.Credentials;
+
+      public DockerClientConfiguration GetDockerClientConfiguration(Guid sessionId = default)
+        => _authConfig.GetDockerClientConfiguration(sessionId);
+
       [Fact]
       public async Task GetVersionReturnsVersion()
       {
         // Given
-        var client = new TestcontainersClient(Guid.Empty, _authConfig, NullLogger.Instance);
+        var client = new TestcontainersClient(Guid.Empty, this, NullLogger.Instance);
 
         // When
         var version = await client.System.GetVersionAsync(TestContext.Current.CancellationToken)

Original file line number	Diff line number	Diff line change
`@@ -25,6 +25,12 @@ public override bool IsApplicable()`
`25`	`25`	`return !RuntimeInformation.IsOSPlatform(OSPlatform.Windows) && DockerEngine != null;`
`26`	`26`	`}`
`27`	`27`
	`28`	`+ /// <inheritdoc />`
	`29`	`+ public Version GetDockerApiVersion()`
	`30`	`+ {`
	`31`	`+ return null;`
	`32`	`+ }`
	`33`	`+`
`28`	`34`	`/// <inheritdoc />`
`29`	`35`	`public string GetDockerConfig()`
`30`	`36`	`{`
Original file line number	Diff line number	Diff line change
`@@ -41,7 +41,7 @@ public virtual bool IsAvailable()`
`41`	`41`	`{`
`42`	`42`	`using (var dockerClientConfiguration = authConfig.GetDockerClientConfiguration(ResourceReaper.DefaultSessionId))`
`43`	`43`	`{`
`44`		`- using (var dockerClient = dockerClientConfiguration.CreateClient())`
	`44`	`+ using (var dockerClient = dockerClientConfiguration.CreateClient(authConfig.Version))`
`45`	`45`	`{`
`46`	`46`	`try`
`47`	`47`	`{`
Original file line number	Diff line number	Diff line change
`@@ -57,6 +57,12 @@ public override IDockerEndpointAuthenticationConfiguration GetAuthConfig()`
`57`	`57`	`return new DockerEndpointAuthenticationConfiguration(_dockerEngine);`
`58`	`58`	`}`
`59`	`59`
	`60`	`+ /// <inheritdoc />`
	`61`	`+ public Version GetDockerApiVersion()`
	`62`	`+ {`
	`63`	`+ return _customConfiguration.GetDockerApiVersion();`
	`64`	`+ }`
	`65`	`+`
`60`	`66`	`/// <inheritdoc />`
`61`	`67`	`public string GetDockerConfig()`
`62`	`68`	`{`
Original file line number	Diff line number	Diff line change
`@@ -134,7 +134,7 @@ private static IDockerClient GetDockerClient(Guid sessionId, IDockerEndpointAuth`
`134`	`134`	`{`
`135`	`135`	`using (var dockerClientConfiguration = dockerEndpointAuthConfig.GetDockerClientConfiguration(sessionId))`
`136`	`136`	`{`
`137`		`- return dockerClientConfiguration.CreateClient();`
	`137`	`+ return dockerClientConfiguration.CreateClient(dockerEndpointAuthConfig.Version);`
`138`	`138`	`}`
`139`	`139`	`}`
`140`	`140`	`}`
Original file line number	Diff line number	Diff line change
`@@ -15,6 +15,11 @@ protected CustomConfiguration(IReadOnlyDictionary<string, string> properties)`
`15`	`15`	`_properties = properties;`
`16`	`16`	`}`
`17`	`17`
	`18`	`+ protected virtual Version GetDockerApiVersion(string propertyName)`
	`19`	`+ {`
	`20`	`+ return _properties.TryGetValue(propertyName, out var propertyValue) && !string.IsNullOrEmpty(propertyValue) && Version.TryParse(propertyValue, out var dockerApiVersion) ? dockerApiVersion : null;`
	`21`	`+ }`
	`22`	`+`
`18`	`23`	`protected virtual string GetDockerConfig(string propertyName)`
`19`	`24`	`{`
`20`	`25`	`return GetPropertyValue<string>(propertyName);`