Merge branch '3.5.x'

Closes gh-48099

Author: philwebb

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

@@ -106,17 +106,25 @@ public void build(BuildRequest request) throws DockerEngineException, IOExceptio
 		this.log.start(request);
 		validateBindings(request.getBindings());
 		PullPolicy pullPolicy = request.getPullPolicy();
-		ImageFetcher imageFetcher = new ImageFetcher(this.dockerConfiguration.builderRegistryAuthentication(),
-				pullPolicy, request.getImagePlatform());
-		Image builderImage = imageFetcher.fetchImage(ImageType.BUILDER, request.getBuilder());
+		ImagePlatform platform = request.getImagePlatform();
+		boolean specifiedPlatform = request.getImagePlatform() != null;
+		DockerRegistryAuthentication registryAuthentication = this.dockerConfiguration.builderRegistryAuthentication();
+		ImageFetcher imageFetcher = new ImageFetcher(registryAuthentication, pullPolicy);
+		Image builderImage = imageFetcher.fetchImage(ImageType.BUILDER, request.getBuilder(), platform);
 		BuilderMetadata builderMetadata = BuilderMetadata.fromImage(builderImage);
 		request = withRunImageIfNeeded(request, builderMetadata);
 		Assert.state(request.getRunImage() != null, "'request.getRunImage()' must not be null");
-		Image runImage = imageFetcher.fetchImage(ImageType.RUNNER, request.getRunImage());
+		platform = (platform != null) ? platform : ImagePlatform.from(builderImage);
+		Image runImage = imageFetcher.fetchImage(ImageType.RUNNER, request.getRunImage(), platform);
+		if (specifiedPlatform && runImage.getPrimaryDigest() != null) {
+			request = request.withRunImage(request.getRunImage().withDigest(runImage.getPrimaryDigest()));
+			runImage = imageFetcher.fetchImage(ImageType.RUNNER, request.getRunImage(), platform);
+		}
 		assertStackIdsMatch(runImage, builderImage);
 		BuildOwner buildOwner = BuildOwner.fromEnv(builderImage.getConfig().getEnv());
 		BuildpackLayersMetadata buildpackLayersMetadata = BuildpackLayersMetadata.fromImage(builderImage);
-		Buildpacks buildpacks = getBuildpacks(request, imageFetcher, builderMetadata, buildpackLayersMetadata);
+		Buildpacks buildpacks = getBuildpacks(request, imageFetcher, platform, builderMetadata,
+				buildpackLayersMetadata);
 		EphemeralBuilder ephemeralBuilder = new EphemeralBuilder(buildOwner, builderImage, request.getName(),
 				builderMetadata, request.getCreator(), request.getEnv(), buildpacks);
 		executeLifecycle(request, ephemeralBuilder);
@@ -160,9 +168,9 @@ private void assertStackIdsMatch(Image runImage, Image builderImage) {
 		}
 	}
 
-	private Buildpacks getBuildpacks(BuildRequest request, ImageFetcher imageFetcher, BuilderMetadata builderMetadata,
-			BuildpackLayersMetadata buildpackLayersMetadata) {
-		BuildpackResolverContext resolverContext = new BuilderResolverContext(imageFetcher, builderMetadata,
+	private Buildpacks getBuildpacks(BuildRequest request, ImageFetcher imageFetcher, ImagePlatform platform,
+			BuilderMetadata builderMetadata, BuildpackLayersMetadata buildpackLayersMetadata) {
+		BuildpackResolverContext resolverContext = new BuilderResolverContext(imageFetcher, platform, builderMetadata,
 				buildpackLayersMetadata);
 		return BuildpackResolvers.resolveAll(resolverContext, request.getBuildpacks());
 	}
@@ -225,49 +233,74 @@ private class ImageFetcher {
 
 		private final PullPolicy pullPolicy;
 
-		private @Nullable ImagePlatform defaultPlatform;
-
-		ImageFetcher(@Nullable DockerRegistryAuthentication registryAuthentication, PullPolicy pullPolicy,
-				@Nullable ImagePlatform platform) {
+		ImageFetcher(@Nullable DockerRegistryAuthentication registryAuthentication, PullPolicy pullPolicy) {
 			this.registryAuthentication = registryAuthentication;
 			this.pullPolicy = pullPolicy;
-			this.defaultPlatform = platform;
 		}
 
-		Image fetchImage(ImageType type, ImageReference reference) throws IOException {
+		Image fetchImage(ImageType type, ImageReference reference, @Nullable ImagePlatform platform)
+				throws IOException {
 			Assert.notNull(type, "'type' must not be null");
 			Assert.notNull(reference, "'reference' must not be null");
 			if (this.pullPolicy == PullPolicy.ALWAYS) {
-				return checkPlatformMismatch(pullImage(reference, type), reference);
+				return pullImageAndCheckForPlatformMismatch(type, reference, platform);
 			}
 			try {
-				return checkPlatformMismatch(Builder.this.docker.image().inspect(reference), reference);
+				Image image = Builder.this.docker.image().inspect(reference, platform);
+				return checkPlatformMismatch(image, reference, platform);
 			}
 			catch (DockerEngineException ex) {
 				if (this.pullPolicy == PullPolicy.IF_NOT_PRESENT && ex.getStatusCode() == 404) {
-					return checkPlatformMismatch(pullImage(reference, type), reference);
+					return pullImageAndCheckForPlatformMismatch(type, reference, platform);
 				}
 				throw ex;
 			}
 		}
 
-		private Image pullImage(ImageReference reference, ImageType imageType) throws IOException {
+		private Image pullImageAndCheckForPlatformMismatch(ImageType type, ImageReference reference,
+				@Nullable ImagePlatform platform) throws IOException {
+			try {
+				Image image = pullImage(reference, type, platform);
+				return checkPlatformMismatch(image, reference, platform);
+			}
+			catch (DockerEngineException ex) {
+				// Try to throw our own exception for consistent log output. Matching
+				// on the message is a little brittle, but it doesn't matter too much
+				// if it fails as the original exception is still enough to stop the build
+				if (platform != null && ex.getMessage() != null
+						&& ex.getMessage().contains("does not provide the specified platform")) {
+					throwAsPlatformMismatchException(type, reference, platform, ex);
+				}
+				throw ex;
+			}
+		}
+
+		private void throwAsPlatformMismatchException(ImageType type, ImageReference reference, ImagePlatform platform,
+				@Nullable Throwable cause) throws IOException {
+			try {
+				Image image = pullImage(reference, type, null);
+				throw new PlatformMismatchException(reference, platform, ImagePlatform.from(image), cause);
+			}
+			catch (DockerEngineException ex) {
+			}
+		}
+
+		private Image pullImage(ImageReference reference, ImageType imageType, @Nullable ImagePlatform platform)
+				throws IOException {
 			TotalProgressPullListener listener = new TotalProgressPullListener(
-					Builder.this.log.pullingImage(reference, this.defaultPlatform, imageType));
+					Builder.this.log.pullingImage(reference, platform, imageType));
 			String authHeader = authHeader(this.registryAuthentication, reference);
-			Image image = Builder.this.docker.image().pull(reference, this.defaultPlatform, listener, authHeader);
+			Image image = Builder.this.docker.image().pull(reference, platform, listener, authHeader);
 			Builder.this.log.pulledImage(image, imageType);
-			if (this.defaultPlatform == null) {
-				this.defaultPlatform = ImagePlatform.from(image);
-			}
 			return image;
 		}
 
-		private Image checkPlatformMismatch(Image image, ImageReference imageReference) {
-			if (this.defaultPlatform != null) {
-				ImagePlatform imagePlatform = ImagePlatform.from(image);
-				if (!imagePlatform.equals(this.defaultPlatform)) {
-					throw new PlatformMismatchException(imageReference, this.defaultPlatform, imagePlatform);
+		private Image checkPlatformMismatch(Image image, ImageReference reference,
+				@Nullable ImagePlatform requestedPlatform) {
+			if (requestedPlatform != null) {
+				ImagePlatform actualPlatform = ImagePlatform.from(image);
+				if (!actualPlatform.equals(requestedPlatform)) {
+					throw new PlatformMismatchException(reference, requestedPlatform, actualPlatform, null);
 				}
 			}
 			return image;
@@ -278,9 +311,9 @@ private Image checkPlatformMismatch(Image image, ImageReference imageReference)
 	private static final class PlatformMismatchException extends RuntimeException {
 
 		private PlatformMismatchException(ImageReference imageReference, ImagePlatform requestedPlatform,
-				ImagePlatform actualPlatform) {
+				ImagePlatform actualPlatform, @Nullable Throwable cause) {
 			super("Image platform mismatch detected. The configured platform '%s' is not supported by the image '%s'. Requested platform '%s' but got '%s'"
-				.formatted(requestedPlatform, imageReference, requestedPlatform, actualPlatform));
+				.formatted(requestedPlatform, imageReference, requestedPlatform, actualPlatform), cause);
 		}
 
 	}
@@ -326,13 +359,16 @@ private class BuilderResolverContext implements BuildpackResolverContext {
 
 		private final ImageFetcher imageFetcher;
 
+		private final ImagePlatform platform;
+
 		private final BuilderMetadata builderMetadata;
 
 		private final BuildpackLayersMetadata buildpackLayersMetadata;
 
-		BuilderResolverContext(ImageFetcher imageFetcher, BuilderMetadata builderMetadata,
+		BuilderResolverContext(ImageFetcher imageFetcher, ImagePlatform platform, BuilderMetadata builderMetadata,
 				BuildpackLayersMetadata buildpackLayersMetadata) {
 			this.imageFetcher = imageFetcher;
+			this.platform = platform;
 			this.builderMetadata = builderMetadata;
 			this.buildpackLayersMetadata = buildpackLayersMetadata;
 		}
@@ -349,7 +385,7 @@ public BuildpackLayersMetadata getBuildpackLayersMetadata() {
 
 		@Override
 		public Image fetchImage(ImageReference reference, ImageType imageType) throws IOException {
-			return this.imageFetcher.fetchImage(imageType, reference);
+			return this.imageFetcher.fetchImage(imageType, reference, this.platform);
 		}
 
 		@Override

buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/DockerApi.java

@@ -66,6 +66,8 @@ public class DockerApi {
 
 	static final ApiVersion PLATFORM_API_VERSION = ApiVersion.of(1, 41);
 
+	static final ApiVersion PLATFORM_INSPECT_API_VERSION = ApiVersion.of(1, 49);
+
 	static final ApiVersion UNKNOWN_API_VERSION = ApiVersion.of(0, 0);
 
 	static final String API_VERSION_HEADER_NAME = "API-Version";
@@ -237,7 +239,7 @@ public Image pull(ImageReference reference, @Nullable ImagePlatform platform,
 						listener.onUpdate(event);
 					});
 				}
-				return inspect((platform != null) ? PLATFORM_API_VERSION : API_VERSION, reference);
+				return inspect(reference, platform);
 			}
 			finally {
 				listener.onFinish();
@@ -339,17 +341,36 @@ public void remove(ImageReference reference, boolean force) throws IOException {
 		 * @throws IOException on IO error
 		 */
 		public Image inspect(ImageReference reference) throws IOException {
-			return inspect(API_VERSION, reference);
+			return inspect(reference, null);
 		}
 
-		private Image inspect(ApiVersion apiVersion, ImageReference reference) throws IOException {
+		/**
+		 * Inspect an image.
+		 * @param reference the image reference
+		 * @param platform the platform (os/architecture/variant) of the image to inspect.
+		 * Ignored on older versions of Docker.
+		 * @return the image from the local repository
+		 * @throws IOException on IO error
+		 * @since 3.4.12
+		 */
+		public Image inspect(ImageReference reference, @Nullable ImagePlatform platform) throws IOException {
+			// The Docker documentation is incomplete but platform parameters
+			// are supported since 1.49 (see https://github.com/moby/moby/pull/49586)
 			Assert.notNull(reference, "'reference' must not be null");
-			URI imageUri = buildUrl(apiVersion, "/images/" + reference + "/json");
-			try (Response response = http().get(imageUri)) {
+			URI inspectUrl = inspectUrl(reference, platform);
+			try (Response response = http().get(inspectUrl)) {
 				return Image.of(response.getContent());
 			}
 		}
 
+		private URI inspectUrl(ImageReference reference, @Nullable ImagePlatform platform) {
+			String path = "/images/" + reference + "/json";
+			if (platform != null && getApiVersion().supports(PLATFORM_INSPECT_API_VERSION)) {
+				return buildUrl(PLATFORM_INSPECT_API_VERSION, path, "platform", platform.toJson());
+			}
+			return buildUrl(path);
+		}
+
 		public void tag(ImageReference sourceReference, ImageReference targetReference) throws IOException {
 			Assert.notNull(sourceReference, "'sourceReference' must not be null");
 			Assert.notNull(targetReference, "'targetReference' must not be null");

buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/ImagePlatform.java

@@ -22,6 +22,7 @@
 
 import org.springframework.boot.buildpack.platform.docker.type.Image;
 import org.springframework.util.Assert;
+import org.springframework.util.StringUtils;
 
 /**
  * A platform specification for a Docker image.
@@ -102,4 +103,24 @@ public static ImagePlatform from(Image image) {
 		return new ImagePlatform(image.getOs(), image.getArchitecture(), image.getVariant());
 	}
 
+	/**
+	 * Return a JSON-encoded representation of this platform.
+	 * @return the JSON string
+	 */
+	public String toJson() {
+		StringBuilder json = new StringBuilder("{");
+		json.append(jsonPair("os", this.os));
+		if (StringUtils.hasText(this.architecture)) {
+			json.append(",").append(jsonPair("architecture", this.architecture));
+		}
+		if (StringUtils.hasText(this.variant)) {
+			json.append(",").append(jsonPair("variant", this.variant));
+		}
+		return json.append("}").toString();
+	}
+
+	private String jsonPair(String name, String value) {
+		return "\"%s\":\"%s\"".formatted(name, value);
+	}
+
 }

buildpack/spring-boot-buildpack-platform/src/main/java/org/springframework/boot/buildpack/platform/docker/type/Image.java

@@ -22,11 +22,13 @@
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.List;
+import java.util.Objects;
 
 import org.jspecify.annotations.Nullable;
 import tools.jackson.databind.JsonNode;
 
 import org.springframework.boot.buildpack.platform.json.MappedObject;
+import org.springframework.util.CollectionUtils;
 import org.springframework.util.StringUtils;
 
 /**
@@ -52,6 +54,8 @@ public class Image extends MappedObject {
 
 	private final @Nullable String created;
 
+	private final @Nullable Descriptor descriptor;
+
 	Image(JsonNode node) {
 		super(node, MethodHandles.lookup());
 		this.digests = childrenAt("/RepoDigests", JsonNode::asString);
@@ -61,6 +65,9 @@ public class Image extends MappedObject {
 		this.architecture = valueAt("/Architecture", String.class);
 		this.variant = valueAt("/Variant", String.class);
 		this.created = valueAt("/Created", String.class);
+		JsonNode descriptorNode = getNode().path("Descriptor");
+		this.descriptor = (descriptorNode.isMissingNode() || descriptorNode.isNull()) ? null
+				: new Descriptor(descriptorNode);
 	}
 
 	private List<LayerId> extractLayers(String @Nullable [] layers) {
@@ -126,6 +133,35 @@ public String getOs() {
 		return this.created;
 	}
 
+	/**
+	 * Return the descriptor for this image as reported by Docker Engine inspect.
+	 * @return the image descriptor or {@code null}
+	 */
+	public @Nullable Descriptor getDescriptor() {
+		return this.descriptor;
+	}
+
+	/**
+	 * Return the primary digest of the image or {@code null}. Checks the
+	 * {@code Descriptor.digest} first, falling back to {@code RepoDigest}.
+	 * @return the primary digest or {@code null}
+	 * @since 3.4.12
+	 */
+	public @Nullable String getPrimaryDigest() {
+		if (this.descriptor != null && StringUtils.hasText(this.descriptor.getDigest())) {
+			return this.descriptor.getDigest();
+		}
+		if (!CollectionUtils.isEmpty(this.digests)) {
+			try {
+				String digest = this.digests.get(0);
+				return (digest != null) ? ImageReference.of(digest).getDigest() : null;
+			}
+			catch (RuntimeException ex) {
+			}
+		}
+		return null;
+	}
+
 	/**
 	 * Create a new {@link Image} instance from the specified JSON content.
 	 * @param content the JSON content
@@ -136,4 +172,24 @@ public static Image of(InputStream content) throws IOException {
 		return of(content, Image::new);
 	}
 
+	/**
+	 * Descriptor details as reported in the {@code Docker inspect} response.
+	 *
+	 * @since 3.4.12
+	 */
+	public final class Descriptor extends MappedObject {
+
+		private final String digest;
+
+		Descriptor(JsonNode node) {
+			super(node, MethodHandles.lookup());
+			this.digest = Objects.requireNonNull(valueAt("/digest", String.class));
+		}
+
+		public String getDigest() {
+			return this.digest;
+		}
+
+	}
+
 }