Skip to content

Commit e194430

Browse files
scottfrederickscottfrederick
committed
Document runtime JVM configuration when building an image
Fixes gh-21478
1 parent 0bc5c2b commit e194430

File tree

7 files changed

+116
-12
lines changed

7 files changed

+116
-12
lines changed

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,8 @@ Andy Wilkinson, Scott Frederick
3434
:boot-run-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/run/BootRun.html
3535
:github-code: https://github.com/spring-projects/spring-boot/tree/{github-tag}
3636
:buildpacks-reference: https://buildpacks.io/docs
37-
:paketo-java-reference: https://paketo.io/docs/buildpacks/language-family-buildpacks/java
37+
:paketo-reference: https://paketo.io/docs
38+
:paketo-java-reference: {paketo-reference}/buildpacks/language-family-buildpacks/java
3839

3940

4041
[[introduction]]

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -139,9 +139,6 @@ include::../gradle/packaging/boot-build-image-env.gradle[tags=env]
139139
include::../gradle/packaging/boot-build-image-env.gradle.kts[tags=env]
140140
----
141141

142-
In a similar way, Paketo Java buildpacks support {paketo-java-reference}/#runtime-jvm-configuration[configuring JVM runtime behavior].
143-
Refer to the {paketo-java-reference}[Paketo documentation] for additional configuration options supported by Paketo Java buildpacks.
144-
145142
If there is a network proxy between the Docker daemon the builder runs in and network locations that buildpacks download artifacts from, you will need to configure the builder to use the proxy.
146143
When using the Paketo builder, this can be accomplished by setting the `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables as show in the following example:
147144

@@ -159,6 +156,27 @@ include::../gradle/packaging/boot-build-image-env-proxy.gradle.kts[tags=env]
159156

160157

161158

159+
[[build-image-example-runtime-jvm-configuration]]
160+
==== Runtime JVM Configuration
161+
Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable.
162+
The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container.
163+
164+
Environment variable modifications that should be stored in the image and applied to every deployment can be set as described in the {paketo-reference}/buildpacks/configuration/#environment-variables[Paketo documentation] and shown in the following example:
165+
166+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
167+
.Groovy
168+
----
169+
include::../gradle/packaging/boot-build-image-env-runtime.gradle[tags=env-runtime]
170+
----
171+
172+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
173+
.Kotlin
174+
----
175+
include::../gradle/packaging/boot-build-image-env-runtime.gradle.kts[tags=env-runtime]
176+
----
177+
178+
179+
162180
[[build-image-example-custom-image-name]]
163181
==== Custom Image Name
164182
By default, the image name is inferred from the `name` and the `version` of the project, something like `docker.io/library/${project.name}:${project.version}`.

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
plugins {
2+
id 'java'
3+
id 'org.springframework.boot' version '{gradle-project-version}'
4+
}
5+
6+
bootJar {
7+
mainClassName 'com.example.ExampleApplication'
8+
}
9+
10+
// tag::env-runtime[]
11+
bootBuildImage {
12+
environment = [
13+
"BPE_DELIM_JAVA_TOOL_OPTIONS" : " ",
14+
"BPE_APPEND_JAVA_TOOL_OPTIONS" : "-XX:+HeapDumpOnOutOfMemoryError"
15+
]
16+
}
17+
// end::env-runtime[]
18+
19+
task bootBuildImageEnvironment {
20+
doFirst {
21+
bootBuildImage.environment.each { name, value -> println "$name=$value" }
22+
}
23+
}

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle.kts

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import org.springframework.boot.gradle.tasks.bundling.BootBuildImage
2+
3+
plugins {
4+
java
5+
id("org.springframework.boot") version "{gradle-project-version}"
6+
}
7+
8+
// tag::env-runtime[]
9+
tasks.getByName<BootBuildImage>("bootBuildImage") {
10+
environment = mapOf(
11+
"BPE_DELIM_JAVA_TOOL_OPTIONS" to " ",
12+
"BPE_APPEND_JAVA_TOOL_OPTIONS" to "-XX:+HeapDumpOnOutOfMemoryError"
13+
)
14+
}
15+
// end::env-runtime[]
16+
17+
tasks.register("bootBuildImageEnvironment") {
18+
doFirst {
19+
for((name, value) in tasks.getByName<BootBuildImage>("bootBuildImage").environment) {
20+
print(name + "=" + value)
21+
}
22+
}
23+
}
24+

‎spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/docs/PackagingDocumentationTests.java

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
/*
2-
* Copyright 2012-2020 the original author or authors.
2+
* Copyright 2012-2021 the original author or authors.
33
*
44
* Licensed under the Apache License, Version 2.0 (the "License");
55
* you may not use this file except in compliance with the License.
@@ -43,6 +43,7 @@
4343
*
4444
* @author Andy Wilkinson
4545
* @author Jean-Baptiste Nizet
46+
* @author Scott Frederick
4647
*/
4748
@ExtendWith(GradleMultiDslExtension.class)
4849
class PackagingDocumentationTests {
@@ -223,22 +224,30 @@ void bootJarLayeredExcludeTools() throws IOException {
223224
}
224225

225226
@TestTemplate
226-
void bootBuildImageWithCustomBuildpackJvmVersion() throws IOException {
227+
void bootBuildImageWithCustomBuildpackJvmVersion() {
227228
BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-env")
228229
.build("bootBuildImageEnvironment");
229230
assertThat(result.getOutput()).contains("BP_JVM_VERSION=8.*");
230231
}
231232

232233
@TestTemplate
233-
void bootBuildImageWithCustomProxySettings() throws IOException {
234+
void bootBuildImageWithCustomProxySettings() {
234235
BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-env-proxy")
235236
.build("bootBuildImageEnvironment");
236237
assertThat(result.getOutput()).contains("HTTP_PROXY=http://proxy.example.com")
237238
.contains("HTTPS_PROXY=https://proxy.example.com");
238239
}
239240

240241
@TestTemplate
241-
void bootBuildImageWithCustomImageName() throws IOException {
242+
void bootBuildImageWithCustomRuntimeConfiguration() {
243+
BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-env-runtime")
244+
.build("bootBuildImageEnvironment");
245+
assertThat(result.getOutput()).contains("BPE_DELIM_JAVA_TOOL_OPTIONS= ")
246+
.contains("BPE_APPEND_JAVA_TOOL_OPTIONS=-XX:+HeapDumpOnOutOfMemoryError");
247+
}
248+
249+
@TestTemplate
250+
void bootBuildImageWithCustomImageName() {
242251
BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-name")
243252
.build("bootBuildImageName");
244253
assertThat(result.getOutput()).contains("example.com/library/" + this.gradleBuild.getProjectDir().getName());

‎spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,8 @@ Stephane Nicoll, Andy Wilkinson, Scott Frederick
1414
:spring-boot-api: {spring-boot-docs}/api/org/springframework/boot
1515
:spring-boot-reference: {spring-boot-docs}/reference/htmlsingle
1616
:version-properties-appendix: {spring-boot-reference}/#dependency-versions-properties
17-
:paketo-java-reference: https://paketo.io/docs/buildpacks/language-family-buildpacks/java
17+
:paketo-reference: https://paketo.io/docs
18+
:paketo-java-reference: {paketo-reference}/buildpacks/language-family-buildpacks/java
1819

1920

2021
[[introduction]]

‎spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc

Lines changed: 31 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -182,9 +182,6 @@ The following is an example of {paketo-java-reference}/#configuring-the-jvm-vers
182182
</project>
183183
----
184184

185-
In a similar way, Paketo Java buildpacks support {paketo-java-reference}/#runtime-jvm-configuration[configuring JVM runtime behavior].
186-
Refer to the {paketo-java-reference}[Paketo documentation] for additional configuration options supported by Paketo Java buildpacks.
187-
188185
If there is a network proxy between the Docker daemon the builder runs in and network locations that buildpacks download artifacts from, you will need to configure the builder to use the proxy.
189186
When using the Paketo builder, this can be accomplished by setting the `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables as show in the following example:
190187

@@ -212,6 +209,37 @@ When using the Paketo builder, this can be accomplished by setting the `HTTPS_PR
212209

213210

214211

212+
[[build-image-example-runtime-jvm-configuration]]
213+
==== Runtime JVM Configuration
214+
Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable.
215+
The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container.
216+
217+
Environment variable modifications that should be stored in the image and applied to every deployment can be set as described in the {paketo-reference}/buildpacks/configuration/#environment-variables[Paketo documentation] and shown in the following example:
218+
219+
[source,xml,indent=0,subs="verbatim,attributes"]
220+
----
221+
<project>
222+
<build>
223+
<plugins>
224+
<plugin>
225+
<groupId>org.springframework.boot</groupId>
226+
<artifactId>spring-boot-maven-plugin</artifactId>
227+
<configuration>
228+
<image>
229+
<env>
230+
<BPE_DELIM_JAVA_TOOL_OPTIONS xml:space="preserve"> </BPE_DELIM_JAVA_TOOL_OPTIONS>
231+
<BPE_APPEND_JAVA_TOOL_OPTIONS>-XX:+HeapDumpOnOutOfMemoryError</BPE_APPEND_JAVA_TOOL_OPTIONS>
232+
</env>
233+
</image>
234+
</configuration>
235+
</plugin>
236+
</plugins>
237+
</build>
238+
</project>
239+
----
240+
241+
242+
215243
[[build-image-example-custom-image-name]]
216244
==== Custom Image Name
217245
By default, the image name is inferred from the `artifactId` and the `version` of the project, something like `docker.io/library/${project.artifactId}:${project.version}`.

0 commit comments

Comments
 (0)