Allow image Created date to be configurable

A `createdDate` option on the Maven `spring-boot:build-image` goal
and the Gradle `bootBuildImage` task can be used to set the `Created`
metadata field on a generated OCI image to a specified date or to
the current date.

Closes gh-28798

Author: scottfrederick

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2021 the original author or authors.
+ * Copyright 2012-2023 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.
@@ -17,6 +17,8 @@
 package org.springframework.boot.buildpack.platform.build;
 
 import java.io.File;
+import java.time.Instant;
+import java.time.format.DateTimeParseException;
 import java.util.Arrays;
 import java.util.Collections;
 import java.util.LinkedHashMap;
@@ -79,6 +81,8 @@ public class BuildRequest {
 
 	private final Cache launchCache;
 
+	private final Instant createdDate;
+
 	BuildRequest(ImageReference name, Function<Owner, TarArchive> applicationContent) {
 		Assert.notNull(name, "Name must not be null");
 		Assert.notNull(applicationContent, "ApplicationContent must not be null");
@@ -98,12 +102,14 @@ public class BuildRequest {
 		this.tags = Collections.emptyList();
 		this.buildCache = null;
 		this.launchCache = null;
+		this.createdDate = null;
 	}
 
 	BuildRequest(ImageReference name, Function<Owner, TarArchive> applicationContent, ImageReference builder,
 			ImageReference runImage, Creator creator, Map<String, String> env, boolean cleanCache,
 			boolean verboseLogging, PullPolicy pullPolicy, boolean publish, List<BuildpackReference> buildpacks,
-			List<Binding> bindings, String network, List<ImageReference> tags, Cache buildCache, Cache launchCache) {
+			List<Binding> bindings, String network, List<ImageReference> tags, Cache buildCache, Cache launchCache,
+			Instant createdDate) {
 		this.name = name;
 		this.applicationContent = applicationContent;
 		this.builder = builder;
@@ -120,6 +126,7 @@ public class BuildRequest {
 		this.tags = tags;
 		this.buildCache = buildCache;
 		this.launchCache = launchCache;
+		this.createdDate = createdDate;
 	}
 
 	/**
@@ -131,7 +138,8 @@ public BuildRequest withBuilder(ImageReference builder) {
 		Assert.notNull(builder, "Builder must not be null");
 		return new BuildRequest(this.name, this.applicationContent, builder.inTaggedOrDigestForm(), this.runImage,
 				this.creator, this.env, this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish,
-				this.buildpacks, this.bindings, this.network, this.tags, this.buildCache, this.launchCache);
+				this.buildpacks, this.bindings, this.network, this.tags, this.buildCache, this.launchCache,
+				this.createdDate);
 	}
 
 	/**
@@ -142,7 +150,8 @@ public BuildRequest withBuilder(ImageReference builder) {
 	public BuildRequest withRunImage(ImageReference runImageName) {
 		return new BuildRequest(this.name, this.applicationContent, this.builder, runImageName.inTaggedOrDigestForm(),
 				this.creator, this.env, this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish,
-				this.buildpacks, this.bindings, this.network, this.tags, this.buildCache, this.launchCache);
+				this.buildpacks, this.bindings, this.network, this.tags, this.buildCache, this.launchCache,
+				this.createdDate);
 	}
 
 	/**
@@ -154,7 +163,7 @@ public BuildRequest withCreator(Creator creator) {
 		Assert.notNull(creator, "Creator must not be null");
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, creator, this.env,
 				this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish, this.buildpacks, this.bindings,
-				this.network, this.tags, this.buildCache, this.launchCache);
+				this.network, this.tags, this.buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -170,7 +179,8 @@ public BuildRequest withEnv(String name, String value) {
 		env.put(name, value);
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator,
 				Collections.unmodifiableMap(env), this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish,
-				this.buildpacks, this.bindings, this.network, this.tags, this.buildCache, this.launchCache);
+				this.buildpacks, this.bindings, this.network, this.tags, this.buildCache, this.launchCache,
+				this.createdDate);
 	}
 
 	/**
@@ -185,7 +195,7 @@ public BuildRequest withEnv(Map<String, String> env) {
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator,
 				Collections.unmodifiableMap(updatedEnv), this.cleanCache, this.verboseLogging, this.pullPolicy,
 				this.publish, this.buildpacks, this.bindings, this.network, this.tags, this.buildCache,
-				this.launchCache);
+				this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -196,7 +206,7 @@ public BuildRequest withEnv(Map<String, String> env) {
 	public BuildRequest withCleanCache(boolean cleanCache) {
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				cleanCache, this.verboseLogging, this.pullPolicy, this.publish, this.buildpacks, this.bindings,
-				this.network, this.tags, this.buildCache, this.launchCache);
+				this.network, this.tags, this.buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -207,7 +217,7 @@ public BuildRequest withCleanCache(boolean cleanCache) {
 	public BuildRequest withVerboseLogging(boolean verboseLogging) {
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				this.cleanCache, verboseLogging, this.pullPolicy, this.publish, this.buildpacks, this.bindings,
-				this.network, this.tags, this.buildCache, this.launchCache);
+				this.network, this.tags, this.buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -218,7 +228,7 @@ public BuildRequest withVerboseLogging(boolean verboseLogging) {
 	public BuildRequest withPullPolicy(PullPolicy pullPolicy) {
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				this.cleanCache, this.verboseLogging, pullPolicy, this.publish, this.buildpacks, this.bindings,
-				this.network, this.tags, this.buildCache, this.launchCache);
+				this.network, this.tags, this.buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -229,7 +239,7 @@ public BuildRequest withPullPolicy(PullPolicy pullPolicy) {
 	public BuildRequest withPublish(boolean publish) {
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				this.cleanCache, this.verboseLogging, this.pullPolicy, publish, this.buildpacks, this.bindings,
-				this.network, this.tags, this.buildCache, this.launchCache);
+				this.network, this.tags, this.buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -253,7 +263,7 @@ public BuildRequest withBuildpacks(List<BuildpackReference> buildpacks) {
 		Assert.notNull(buildpacks, "Buildpacks must not be null");
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish, buildpacks, this.bindings,
-				this.network, this.tags, this.buildCache, this.launchCache);
+				this.network, this.tags, this.buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -277,7 +287,7 @@ public BuildRequest withBindings(List<Binding> bindings) {
 		Assert.notNull(bindings, "Bindings must not be null");
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish, this.buildpacks, bindings,
-				this.network, this.tags, this.buildCache, this.launchCache);
+				this.network, this.tags, this.buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -289,7 +299,7 @@ public BuildRequest withBindings(List<Binding> bindings) {
 	public BuildRequest withNetwork(String network) {
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish, this.buildpacks, this.bindings,
-				network, this.tags, this.buildCache, this.launchCache);
+				network, this.tags, this.buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -311,7 +321,7 @@ public BuildRequest withTags(List<ImageReference> tags) {
 		Assert.notNull(tags, "Tags must not be null");
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish, this.buildpacks, this.bindings,
-				this.network, tags, this.buildCache, this.launchCache);
+				this.network, tags, this.buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -323,7 +333,7 @@ public BuildRequest withBuildCache(Cache buildCache) {
 		Assert.notNull(buildCache, "BuildCache must not be null");
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish, this.buildpacks, this.bindings,
-				this.network, this.tags, buildCache, this.launchCache);
+				this.network, this.tags, buildCache, this.launchCache, this.createdDate);
 	}
 
 	/**
@@ -335,7 +345,31 @@ public BuildRequest withLaunchCache(Cache launchCache) {
 		Assert.notNull(launchCache, "LaunchCache must not be null");
 		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
 				this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish, this.buildpacks, this.bindings,
-				this.network, this.tags, this.buildCache, launchCache);
+				this.network, this.tags, this.buildCache, launchCache, this.createdDate);
+	}
+
+	/**
+	 * Return a new {@link BuildRequest} with an updated created date.
+	 * @param createdDate the created date
+	 * @return an updated build request
+	 */
+	public BuildRequest withCreatedDate(String createdDate) {
+		Assert.notNull(createdDate, "CreatedDate must not be null");
+		return new BuildRequest(this.name, this.applicationContent, this.builder, this.runImage, this.creator, this.env,
+				this.cleanCache, this.verboseLogging, this.pullPolicy, this.publish, this.buildpacks, this.bindings,
+				this.network, this.tags, this.buildCache, this.launchCache, parseCreatedDate(createdDate));
+	}
+
+	private Instant parseCreatedDate(String createdDate) {
+		if ("now".equalsIgnoreCase(createdDate)) {
+			return Instant.now();
+		}
+		try {
+			return Instant.parse(createdDate);
+		}
+		catch (DateTimeParseException ex) {
+			throw new IllegalArgumentException("Error parsing '" + createdDate + "' as an image created date", ex);
+		}
 	}
 
 	/**
@@ -471,6 +505,14 @@ public Cache getLaunchCache() {
 		return this.launchCache;
 	}
 
+	/**
+	 * Return the custom created date that should be used by the lifecycle.
+	 * @return the created date
+	 */
+	public Instant getCreatedDate() {
+		return this.createdDate;
+	}
+
 	/**
 	 * Factory method to create a new {@link BuildRequest} from a JAR file.
 	 * @param jarFile the source jar file

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

@@ -50,6 +50,8 @@ class Lifecycle implements Closeable {
 
 	private static final String PLATFORM_API_VERSION_KEY = "CNB_PLATFORM_API";
 
+	private static final String SOURCE_DATE_EPOCH_KEY = "SOURCE_DATE_EPOCH";
+
 	private static final String DOMAIN_SOCKET_PATH = "/var/run/docker.sock";
 
 	private final BuildLog log;
@@ -184,6 +186,9 @@ private Phase createPhase() {
 		if (this.request.getNetwork() != null) {
 			phase.withNetworkMode(this.request.getNetwork());
 		}
+		if (this.request.getCreatedDate() != null) {
+			phase.withEnv(SOURCE_DATE_EPOCH_KEY, Long.toString(this.request.getCreatedDate().getEpochSecond()));
+		}
 		return phase;
 	}
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2012-2022 the original author or authors.
+ * Copyright 2012-2023 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.
@@ -44,12 +44,15 @@ public class Image extends MappedObject {
 
 	private final String os;
 
+	private final String created;
+
 	Image(JsonNode node) {
 		super(node, MethodHandles.lookup());
 		this.digests = getDigests(getNode().at("/RepoDigests"));
 		this.config = new ImageConfig(getNode().at("/Config"));
 		this.layers = extractLayers(valueAt("/RootFS/Layers", String[].class));
 		this.os = valueAt("/Os", String.class);
+		this.created = valueAt("/Created", String.class);
 	}
 
 	private List<String> getDigests(JsonNode node) {
@@ -100,6 +103,14 @@ public String getOs() {
 		return (this.os != null) ? this.os : "linux";
 	}
 
+	/**
+	 * Return the created date of the image.
+	 * @return the image created date
+	 */
+	public String getCreated() {
+		return this.created;
+	}
+
 	/**
 	 * Create a new {@link Image} instance from the specified JSON content.
 	 * @param content the JSON content

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/test/java/org/springframework/boot/buildpack/platform/build/BuildRequestTests.java

@@ -21,6 +21,9 @@
 import java.io.File;
 import java.io.IOException;
 import java.nio.charset.StandardCharsets;
+import java.time.Instant;
+import java.time.OffsetDateTime;
+import java.time.ZoneId;
 import java.util.LinkedHashMap;
 import java.util.List;
 import java.util.Map;
@@ -258,6 +261,37 @@ void withLaunchVolumeCacheWhenCacheIsNullThrowsException() throws IOException {
 			.withMessage("LaunchCache must not be null");
 	}
 
+	@Test
+	void withCreatedDateSetsCreatedDate() throws Exception {
+		Instant createDate = Instant.now();
+		BuildRequest request = BuildRequest.forJarFile(writeTestJarFile("my-app-0.0.1.jar"));
+		BuildRequest withCreatedDate = request.withCreatedDate(createDate.toString());
+		assertThat(withCreatedDate.getCreatedDate()).isEqualTo(createDate);
+	}
+
+	@Test
+	void withCreatedDateNowSetsCreatedDate() throws Exception {
+		OffsetDateTime now = OffsetDateTime.now();
+		BuildRequest request = BuildRequest.forJarFile(writeTestJarFile("my-app-0.0.1.jar"));
+		BuildRequest withCreatedDate = request.withCreatedDate("now");
+		OffsetDateTime createdDate = OffsetDateTime.ofInstant(withCreatedDate.getCreatedDate(), ZoneId.of("UTC"));
+		assertThat(createdDate.getYear()).isEqualTo(now.getYear());
+		assertThat(createdDate.getMonth()).isEqualTo(now.getMonth());
+		assertThat(createdDate.getDayOfMonth()).isEqualTo(now.getDayOfMonth());
+		withCreatedDate = request.withCreatedDate("NOW");
+		createdDate = OffsetDateTime.ofInstant(withCreatedDate.getCreatedDate(), ZoneId.of("UTC"));
+		assertThat(createdDate.getYear()).isEqualTo(now.getYear());
+		assertThat(createdDate.getMonth()).isEqualTo(now.getMonth());
+		assertThat(createdDate.getDayOfMonth()).isEqualTo(now.getDayOfMonth());
+	}
+
+	@Test
+	void withCreatedDateAndInvalidDateThrowsException() throws Exception {
+		BuildRequest request = BuildRequest.forJarFile(writeTestJarFile("my-app-0.0.1.jar"));
+		assertThatIllegalArgumentException().isThrownBy(() -> request.withCreatedDate("not a date"))
+			.withMessageContaining("'not a date'");
+	}
+
 	private void hasExpectedJarContent(TarArchive archive) {
 		try {
 			ByteArrayOutputStream outputStream = new ByteArrayOutputStream();

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/test/java/org/springframework/boot/buildpack/platform/build/EphemeralBuilderTests.java

@@ -116,7 +116,7 @@ void getArchiveHasTag() throws Exception {
 	}
 
 	@Test
-	void getArchiveHasFixedCreateDate() throws Exception {
+	void getArchiveHasFixedCreatedDate() throws Exception {
 		EphemeralBuilder builder = new EphemeralBuilder(this.owner, this.image, this.targetImage, this.metadata,
 				this.creator, this.env, this.buildpacks);
 		Instant createInstant = builder.getArchive().getCreateDate();

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/test/java/org/springframework/boot/buildpack/platform/build/LifecycleTests.java

@@ -218,6 +218,17 @@ void executeWithCacheVolumeNamesExecutesPhases() throws Exception {
 		assertThat(this.out.toString()).contains("Successfully built image 'docker.io/library/my-application:latest'");
 	}
 
+	@Test
+	void executeWithCreatedDateExecutesPhases() throws Exception {
+		given(this.docker.container().create(any())).willAnswer(answerWithGeneratedContainerId());
+		given(this.docker.container().create(any(), any())).willAnswer(answerWithGeneratedContainerId());
+		given(this.docker.container().wait(any())).willReturn(ContainerStatus.of(0, null));
+		BuildRequest request = getTestRequest().withCreatedDate("2020-07-01T12:34:56Z");
+		createLifecycle(request).execute();
+		assertPhaseWasRun("creator", withExpectedConfig("lifecycle-creator-created-date.json"));
+		assertThat(this.out.toString()).contains("Successfully built image 'docker.io/library/my-application:latest'");
+	}
+
 	@Test
 	void executeWithDockerHostAndRemoteAddressExecutesPhases() throws Exception {
 		given(this.docker.container().create(any())).willAnswer(answerWithGeneratedContainerId());

spring-boot-project/spring-boot-tools/spring-boot-buildpack-platform/src/test/java/org/springframework/boot/buildpack/platform/docker/type/ImageTests.java

@@ -67,6 +67,12 @@ void getOsReturnsOs() throws Exception {
 		assertThat(image.getOs()).isEqualTo("linux");
 	}
 
+	@Test
+	void getCreatedReturnsDate() throws Exception {
+		Image image = getImage();
+		assertThat(image.getCreated()).isEqualTo("2019-10-30T19:34:56.296666503Z");
+	}
+
 	private Image getImage() throws IOException {
 		return Image.of(getContent("image.json"));
 	}