Add imagePlatform option for image building

An `imagePlatform` option for the Maven and Gradle image-building
goal/task can be used to specify the os/architecture of any
builder, run, and buildpack images that are pulled during image
building.

Closes gh-40944

Author: scottfrederick

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/dockerTest/java/org/springframework/boot/buildpack/platform/docker/DockerApiIntegrationTests.java

@@ -36,7 +36,7 @@ class DockerApiIntegrationTests {
 	@Test
 	void pullImage() throws IOException {
 		this.docker.image()
-			.pull(ImageReference.of("gcr.io/paketo-buildpacks/builder:base"),
+			.pull(ImageReference.of("gcr.io/paketo-buildpacks/builder:base"), null,
 					new TotalProgressPullListener(new TotalProgressBar("Pulling: ")));
 	}
 

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/build/AbstractBuildLog.java

@@ -22,6 +22,7 @@
 import org.springframework.boot.buildpack.platform.docker.LogUpdateEvent;
 import org.springframework.boot.buildpack.platform.docker.TotalProgressEvent;
 import org.springframework.boot.buildpack.platform.docker.type.Image;
+import org.springframework.boot.buildpack.platform.docker.type.ImagePlatform;
 import org.springframework.boot.buildpack.platform.docker.type.ImageReference;
 import org.springframework.boot.buildpack.platform.docker.type.VolumeName;
 
@@ -43,8 +44,17 @@ public void start(BuildRequest request) {
 	}
 
 	@Override
-	public Consumer<TotalProgressEvent> pullingImage(ImageReference imageReference, ImageType imageType) {
-		return getProgressConsumer(String.format(" > Pulling %s '%s'", imageType.getDescription(), imageReference));
+	public Consumer<TotalProgressEvent> pullingImage(ImageReference imageReference, ImagePlatform platform,
+			ImageType imageType) {
+		String message;
+		if (platform != null) {
+			message = String.format(" > Pulling %s '%s' for platform '%s'", imageType.getDescription(), imageReference,
+					platform);
+		}
+		else {
+			message = String.format(" > Pulling %s '%s'", imageType.getDescription(), imageReference);
+		}
+		return getProgressConsumer(message);
 	}
 
 	@Override

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/build/ApiVersions.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2023 the original author or authors.
+ * Copyright 2012-2024 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -19,6 +19,7 @@
 import java.util.Arrays;
 import java.util.stream.IntStream;
 
+import org.springframework.boot.buildpack.platform.docker.type.ApiVersion;
 import org.springframework.util.StringUtils;
 
 /**

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/build/BuildLog.java

@@ -22,6 +22,7 @@
 import org.springframework.boot.buildpack.platform.docker.LogUpdateEvent;
 import org.springframework.boot.buildpack.platform.docker.TotalProgressEvent;
 import org.springframework.boot.buildpack.platform.docker.type.Image;
+import org.springframework.boot.buildpack.platform.docker.type.ImagePlatform;
 import org.springframework.boot.buildpack.platform.docker.type.ImageReference;
 import org.springframework.boot.buildpack.platform.docker.type.VolumeName;
 
@@ -46,10 +47,12 @@ public interface BuildLog {
 	/**
 	 * Log that an image is being pulled.
 	 * @param imageReference the image reference
+	 * @param platform the platform of the image
 	 * @param imageType the image type
 	 * @return a consumer for progress update events
 	 */
-	Consumer<TotalProgressEvent> pullingImage(ImageReference imageReference, ImageType imageType);
+	Consumer<TotalProgressEvent> pullingImage(ImageReference imageReference, ImagePlatform platform,
+			ImageType imageType);
 
 	/**
 	 * Log that an image has been pulled.

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/build/BuildRequest.java

@@ -29,6 +29,7 @@
 import org.springframework.boot.buildpack.platform.docker.configuration.ResolvedDockerHost;
 import org.springframework.boot.buildpack.platform.docker.transport.DockerEngineException;
 import org.springframework.boot.buildpack.platform.docker.type.Image;
+import org.springframework.boot.buildpack.platform.docker.type.ImagePlatform;
 import org.springframework.boot.buildpack.platform.docker.type.ImageReference;
 import org.springframework.boot.buildpack.platform.io.IOBiConsumer;
 import org.springframework.boot.buildpack.platform.io.TarArchive;
@@ -99,7 +100,8 @@ public void build(BuildRequest request) throws DockerEngineException, IOExceptio
 		this.log.start(request);
 		String domain = request.getBuilder().getDomain();
 		PullPolicy pullPolicy = request.getPullPolicy();
-		ImageFetcher imageFetcher = new ImageFetcher(domain, getBuilderAuthHeader(), pullPolicy);
+		ImageFetcher imageFetcher = new ImageFetcher(domain, getBuilderAuthHeader(), pullPolicy,
+				request.getImagePlatform());
 		Image builderImage = imageFetcher.fetchImage(ImageType.BUILDER, request.getBuilder());
 		BuilderMetadata builderMetadata = BuilderMetadata.fromImage(builderImage);
 		request = withRunImageIfNeeded(request, builderMetadata);
@@ -208,10 +210,13 @@ private class ImageFetcher {
 
 		private final PullPolicy pullPolicy;
 
-		ImageFetcher(String domain, String authHeader, PullPolicy pullPolicy) {
+		private ImagePlatform defaultPlatform;
+
+		ImageFetcher(String domain, String authHeader, PullPolicy pullPolicy, ImagePlatform platform) {
 			this.domain = domain;
 			this.authHeader = authHeader;
 			this.pullPolicy = pullPolicy;
+			this.defaultPlatform = platform;
 		}
 
 		Image fetchImage(ImageType type, ImageReference reference) throws IOException {
@@ -236,9 +241,12 @@ Image fetchImage(ImageType type, ImageReference reference) throws IOException {
 
 		private Image pullImage(ImageReference reference, ImageType imageType) throws IOException {
 			TotalProgressPullListener listener = new TotalProgressPullListener(
-					Builder.this.log.pullingImage(reference, imageType));
-			Image image = Builder.this.docker.image().pull(reference, listener, this.authHeader);
+					Builder.this.log.pullingImage(reference, this.defaultPlatform, imageType));
+			Image image = Builder.this.docker.image().pull(reference, this.defaultPlatform, listener, this.authHeader);
 			Builder.this.log.pulledImage(image, imageType);
+			if (this.defaultPlatform == null) {
+				this.defaultPlatform = ImagePlatform.from(image);
+			}
 			return image;
 		}
 

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/build/Builder.java

@@ -29,6 +29,7 @@
 import org.springframework.boot.buildpack.platform.docker.DockerApi;
 import org.springframework.boot.buildpack.platform.docker.LogUpdateEvent;
 import org.springframework.boot.buildpack.platform.docker.configuration.ResolvedDockerHost;
+import org.springframework.boot.buildpack.platform.docker.type.ApiVersion;
 import org.springframework.boot.buildpack.platform.docker.type.Binding;
 import org.springframework.boot.buildpack.platform.docker.type.ContainerConfig;
 import org.springframework.boot.buildpack.platform.docker.type.ContainerContent;
@@ -363,15 +364,16 @@ private void run(Phase phase) throws IOException {
 
 	private ContainerReference createContainer(ContainerConfig config, boolean requiresAppUpload) throws IOException {
 		if (!requiresAppUpload || this.applicationVolumePopulated) {
-			return this.docker.container().create(config);
+			return this.docker.container().create(config, this.request.getImagePlatform());
 		}
 		try {
 			if (this.application.getBind() != null) {
 				Files.createDirectories(Path.of(this.application.getBind().getSource()));
 			}
 			TarArchive applicationContent = this.request.getApplicationContent(this.builder.getBuildOwner());
 			return this.docker.container()
-				.create(config, ContainerContent.of(applicationContent, this.applicationDirectory));
+				.create(config, this.request.getImagePlatform(),
+						ContainerContent.of(applicationContent, this.applicationDirectory));
 		}
 		finally {
 			this.applicationVolumePopulated = true;

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/build/Lifecycle.java

@@ -28,17 +28,20 @@
 import java.util.List;
 import java.util.Objects;
 
+import org.apache.hc.core5.http.Header;
 import org.apache.hc.core5.net.URIBuilder;
 
 import org.springframework.boot.buildpack.platform.docker.configuration.DockerConfiguration.DockerHostConfiguration;
 import org.springframework.boot.buildpack.platform.docker.transport.HttpTransport;
 import org.springframework.boot.buildpack.platform.docker.transport.HttpTransport.Response;
+import org.springframework.boot.buildpack.platform.docker.type.ApiVersion;
 import org.springframework.boot.buildpack.platform.docker.type.ContainerConfig;
 import org.springframework.boot.buildpack.platform.docker.type.ContainerContent;
 import org.springframework.boot.buildpack.platform.docker.type.ContainerReference;
 import org.springframework.boot.buildpack.platform.docker.type.ContainerStatus;
 import org.springframework.boot.buildpack.platform.docker.type.Image;
 import org.springframework.boot.buildpack.platform.docker.type.ImageArchive;
+import org.springframework.boot.buildpack.platform.docker.type.ImagePlatform;
 import org.springframework.boot.buildpack.platform.docker.type.ImageReference;
 import org.springframework.boot.buildpack.platform.docker.type.VolumeName;
 import org.springframework.boot.buildpack.platform.io.IOBiConsumer;
@@ -61,7 +64,9 @@ public class DockerApi {
 
 	private static final List<String> FORCE_PARAMS = Collections.unmodifiableList(Arrays.asList("force", "1"));
 
-	static final String API_VERSION = "v1.24";
+	static final ApiVersion MINIMUM_API_VERSION = ApiVersion.parse("1.24");
+
+	static final String API_VERSION_HEADER_NAME = "API-Version";
 
 	private final HttpTransport http;
 
@@ -73,6 +78,10 @@ public class DockerApi {
 
 	private final VolumeApi volume;
 
+	private final SystemApi system;
+
+	private ApiVersion apiVersion = null;
+
 	/**
 	 * Create a new {@link DockerApi} instance.
 	 */
@@ -100,6 +109,7 @@ public DockerApi(DockerHostConfiguration dockerHost) {
 		this.image = new ImageApi();
 		this.container = new ContainerApi();
 		this.volume = new VolumeApi();
+		this.system = new SystemApi();
 	}
 
 	private HttpTransport http() {
@@ -116,7 +126,10 @@ private URI buildUrl(String path, Collection<?> params) {
 
 	private URI buildUrl(String path, Object... params) {
 		try {
-			URIBuilder builder = new URIBuilder("/" + API_VERSION + path);
+			if (this.apiVersion == null) {
+				this.apiVersion = this.system.getApiVersion();
+			}
+			URIBuilder builder = new URIBuilder("/v" + this.apiVersion + path);
 			int param = 0;
 			while (param < params.length) {
 				builder.addParameter(Objects.toString(params[param++]), Objects.toString(params[param++]));
@@ -128,6 +141,13 @@ private URI buildUrl(String path, Object... params) {
 		}
 	}
 
+	private void verifyApiVersionForPlatform() {
+		ApiVersion minimumPlatformApiVersion = ApiVersion.of(1, 41);
+		Assert.isTrue(this.apiVersion.supports(minimumPlatformApiVersion),
+				"Docker API version must be at least " + minimumPlatformApiVersion
+						+ " to support the 'imagePlatform' option, but current API version is " + this.apiVersion);
+	}
+
 	/**
 	 * Return the Docker API for image operations.
 	 * @return the image API
@@ -148,6 +168,10 @@ public VolumeApi volume() {
 		return this.volume;
 	}
 
+	SystemApi system() {
+		return this.system;
+	}
+
 	/**
 	 * Docker API for image operations.
 	 */
@@ -159,27 +183,37 @@ public class ImageApi {
 		/**
 		 * Pull an image from a registry.
 		 * @param reference the image reference to pull
+		 * @param platform the platform (os/architecture/variant) of the image to pull
 		 * @param listener a pull listener to receive update events
 		 * @return the {@link ImageApi pulled image} instance
 		 * @throws IOException on IO error
 		 */
-		public Image pull(ImageReference reference, UpdateListener<PullImageUpdateEvent> listener) throws IOException {
-			return pull(reference, listener, null);
+		public Image pull(ImageReference reference, ImagePlatform platform,
+				UpdateListener<PullImageUpdateEvent> listener) throws IOException {
+			return pull(reference, platform, listener, null);
 		}
 
 		/**
 		 * Pull an image from a registry.
 		 * @param reference the image reference to pull
+		 * @param platform the platform (os/architecture/variant) of the image to pull
 		 * @param listener a pull listener to receive update events
 		 * @param registryAuth registry authentication credentials
 		 * @return the {@link ImageApi pulled image} instance
 		 * @throws IOException on IO error
 		 */
-		public Image pull(ImageReference reference, UpdateListener<PullImageUpdateEvent> listener, String registryAuth)
-				throws IOException {
+		public Image pull(ImageReference reference, ImagePlatform platform,
+				UpdateListener<PullImageUpdateEvent> listener, String registryAuth) throws IOException {
 			Assert.notNull(reference, "Reference must not be null");
 			Assert.notNull(listener, "Listener must not be null");
-			URI createUri = buildUrl("/images/create", "fromImage", reference);
+			URI createUri;
+			if (platform != null) {
+				createUri = buildUrl("/images/create", "fromImage", reference, "platform", platform);
+				verifyApiVersionForPlatform();
+			}
+			else {
+				createUri = buildUrl("/images/create", "fromImage", reference);
+			}
 			DigestCaptureUpdateListener digestCapture = new DigestCaptureUpdateListener();
 			listener.onStart();
 			try {
@@ -348,22 +382,32 @@ public class ContainerApi {
 		/**
 		 * Create a new container a {@link ContainerConfig}.
 		 * @param config the container config
+		 * @param platform the platform (os/architecture/variant) of the image the
+		 * container should be created from
 		 * @param contents additional contents to include
 		 * @return a {@link ContainerReference} for the newly created container
 		 * @throws IOException on IO error
 		 */
-		public ContainerReference create(ContainerConfig config, ContainerContent... contents) throws IOException {
+		public ContainerReference create(ContainerConfig config, ImagePlatform platform, ContainerContent... contents)
+				throws IOException {
 			Assert.notNull(config, "Config must not be null");
 			Assert.noNullElements(contents, "Contents must not contain null elements");
-			ContainerReference containerReference = createContainer(config);
+			ContainerReference containerReference = createContainer(config, platform);
 			for (ContainerContent content : contents) {
 				uploadContainerContent(containerReference, content);
 			}
 			return containerReference;
 		}
 
-		private ContainerReference createContainer(ContainerConfig config) throws IOException {
-			URI createUri = buildUrl("/containers/create");
+		private ContainerReference createContainer(ContainerConfig config, ImagePlatform platform) throws IOException {
+			URI createUri;
+			if (platform != null) {
+				createUri = buildUrl("/containers/create", "platform", platform);
+				verifyApiVersionForPlatform();
+			}
+			else {
+				createUri = buildUrl("/containers/create");
+			}
 			try (Response response = http().post(createUri, "application/json", config::writeTo)) {
 				return ContainerReference
 					.of(SharedObjectMapper.get().readTree(response.getContent()).at("/Id").asText());
@@ -460,6 +504,39 @@ public void delete(VolumeName name, boolean force) throws IOException {
 
 	}
 
+	/**
+	 * Docker API for system operations.
+	 */
+	class SystemApi {
+
+		SystemApi() {
+		}
+
+		/**
+		 * Get the API version supported by the Docker daemon.
+		 * @return the Docker daemon API version
+		 */
+		ApiVersion getApiVersion() {
+			try {
+				URI uri = new URIBuilder("/_ping").build();
+				try (Response response = http().head(uri)) {
+					Header apiVersionHeader = response.getHeader(API_VERSION_HEADER_NAME);
+					if (apiVersionHeader != null) {
+						return ApiVersion.parse(apiVersionHeader.getValue());
+					}
+				}
+				catch (Exception ex) {
+					// fall through to return default value
+				}
+				return MINIMUM_API_VERSION;
+			}
+			catch (URISyntaxException ex) {
+				throw new IllegalStateException(ex);
+			}
+		}
+
+	}
+
 	/**
 	 * {@link UpdateListener} used to capture the image digest.
 	 */