root
/
spring-boot
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity

Document runtime JVM configuration when building an image

Browse Source 
Fixes gh-21478
pull/27078/head
Scott Frederick 4 years ago
parent 0bc5c2ba8c
commit e19443093d
7 changed files with 116 additions and 12 deletions
Show Stats Download Patch File Download Diff File

3
spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc
Unescape Escape View File

@ -34,7 +34,8 @@ Andy Wilkinson, Scott Frederick
:boot-run-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/run/BootRun.html
:github-code: https://github.com/spring-projects/spring-boot/tree/{github-tag}
:buildpacks-reference: https://buildpacks.io/docs
:paketo-java-reference: https://paketo.io/docs/buildpacks/language-family-buildpacks/java
:paketo-reference: https://paketo.io/docs
:paketo-java-reference: {paketo-reference}/buildpacks/language-family-buildpacks/java
[[introduction]]

24
spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc
Unescape Escape View File

@ -139,9 +139,6 @@ include::../gradle/packaging/boot-build-image-env.gradle[tags=env]
include::../gradle/packaging/boot-build-image-env.gradle.kts[tags=env]
----
In a similar way, Paketo Java buildpacks support {paketo-java-reference}/#runtime-jvm-configuration[configuring JVM runtime behavior].
Refer to the {paketo-java-reference}[Paketo documentation] for additional configuration options supported by Paketo Java buildpacks.
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.
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:
@ -159,6 +156,27 @@ include::../gradle/packaging/boot-build-image-env-proxy.gradle.kts[tags=env]
[[build-image-example-runtime-jvm-configuration]]
==== Runtime JVM Configuration
Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable.
The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container.
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:
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
.Groovy
----
include::../gradle/packaging/boot-build-image-env-runtime.gradle[tags=env-runtime]
----
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
.Kotlin
----
include::../gradle/packaging/boot-build-image-env-runtime.gradle.kts[tags=env-runtime]
----
[[build-image-example-custom-image-name]]
==== Custom Image Name
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}`.

23
spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle
Unescape Escape View File

@ -0,0 +1,23 @@
plugins {
id 'java'
id 'org.springframework.boot' version '{gradle-project-version}'
}
bootJar {
mainClassName 'com.example.ExampleApplication'
}
// tag::env-runtime[]
bootBuildImage {
environment = [
"BPE_DELIM_JAVA_TOOL_OPTIONS" : " ",
"BPE_APPEND_JAVA_TOOL_OPTIONS" : "-XX:+HeapDumpOnOutOfMemoryError"
]
}
// end::env-runtime[]
task bootBuildImageEnvironment {
doFirst {
bootBuildImage.environment.each { name, value -> println "$name=$value" }
}
}

24
spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env-runtime.gradle.kts
Unescape Escape View File

@ -0,0 +1,24 @@
import org.springframework.boot.gradle.tasks.bundling.BootBuildImage
plugins {
java
id("org.springframework.boot") version "{gradle-project-version}"
}
// tag::env-runtime[]
tasks.getByName<BootBuildImage>("bootBuildImage") {
environment = mapOf(
"BPE_DELIM_JAVA_TOOL_OPTIONS" to " ",
"BPE_APPEND_JAVA_TOOL_OPTIONS" to "-XX:+HeapDumpOnOutOfMemoryError"
)
}
// end::env-runtime[]
tasks.register("bootBuildImageEnvironment") {
doFirst {
for((name, value) in tasks.getByName<BootBuildImage>("bootBuildImage").environment) {
print(name + "=" + value)
}
}
}

17
spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/test/java/org/springframework/boot/gradle/docs/PackagingDocumentationTests.java
Unescape Escape View File

@ -1,5 +1,5 @@
/*
* Copyright 2012-2020 the original author or authors.
* Copyright 2012-2021 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.
@ -43,6 +43,7 @@ import static org.assertj.core.api.Assertions.assertThat;
*
* @author Andy Wilkinson
* @author Jean-Baptiste Nizet
* @author Scott Frederick
*/
@ExtendWith(GradleMultiDslExtension.class)
class PackagingDocumentationTests {
@ -223,14 +224,14 @@ class PackagingDocumentationTests {
}
@TestTemplate
void bootBuildImageWithCustomBuildpackJvmVersion() throws IOException {
void bootBuildImageWithCustomBuildpackJvmVersion() {
BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-env")
.build("bootBuildImageEnvironment");
assertThat(result.getOutput()).contains("BP_JVM_VERSION=8.*");
}
@TestTemplate
void bootBuildImageWithCustomProxySettings() throws IOException {
void bootBuildImageWithCustomProxySettings() {
BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-env-proxy")
.build("bootBuildImageEnvironment");
assertThat(result.getOutput()).contains("HTTP_PROXY=http://proxy.example.com")
@ -238,7 +239,15 @@ class PackagingDocumentationTests {
}
@TestTemplate
void bootBuildImageWithCustomImageName() throws IOException {
void bootBuildImageWithCustomRuntimeConfiguration() {
BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-env-runtime")
.build("bootBuildImageEnvironment");
assertThat(result.getOutput()).contains("BPE_DELIM_JAVA_TOOL_OPTIONS= ")
.contains("BPE_APPEND_JAVA_TOOL_OPTIONS=-XX:+HeapDumpOnOutOfMemoryError");
}
@TestTemplate
void bootBuildImageWithCustomImageName() {
BuildResult result = this.gradleBuild.script("src/docs/gradle/packaging/boot-build-image-name")
.build("bootBuildImageName");
assertThat(result.getOutput()).contains("example.com/library/" + this.gradleBuild.getProjectDir().getName());

3
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc
Unescape Escape View File

@ -14,7 +14,8 @@ Stephane Nicoll, Andy Wilkinson, Scott Frederick
:spring-boot-api: {spring-boot-docs}/api/org/springframework/boot
:spring-boot-reference: {spring-boot-docs}/reference/htmlsingle
:version-properties-appendix: {spring-boot-reference}/#dependency-versions-properties
:paketo-java-reference: https://paketo.io/docs/buildpacks/language-family-buildpacks/java
:paketo-reference: https://paketo.io/docs
:paketo-java-reference: {paketo-reference}/buildpacks/language-family-buildpacks/java
[[introduction]]

34
spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc
Unescape Escape View File

@ -182,9 +182,6 @@ The following is an example of {paketo-java-reference}/#configuring-the-jvm-vers
</project>
----
In a similar way, Paketo Java buildpacks support {paketo-java-reference}/#runtime-jvm-configuration[configuring JVM runtime behavior].
Refer to the {paketo-java-reference}[Paketo documentation] for additional configuration options supported by Paketo Java buildpacks.
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.
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:
@ -212,6 +209,37 @@ When using the Paketo builder, this can be accomplished by setting the `HTTPS_PR
[[build-image-example-runtime-jvm-configuration]]
==== Runtime JVM Configuration
Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable.
The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container.
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:
[source,xml,indent=0,subs="verbatim,attributes"]
----
<project>
<build>
<plugins>
<plugin>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-maven-plugin</artifactId>
<configuration>
<image>
<env>
<BPE_DELIM_JAVA_TOOL_OPTIONS xml:space="preserve"> </BPE_DELIM_JAVA_TOOL_OPTIONS>
<BPE_APPEND_JAVA_TOOL_OPTIONS>-XX:+HeapDumpOnOutOfMemoryError</BPE_APPEND_JAVA_TOOL_OPTIONS>
</env>
</image>
</configuration>
</plugin>
</plugins>
</build>
</project>
----
[[build-image-example-custom-image-name]]
==== Custom Image Name
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}`.

Write Preview
Loading…
Cancel
Save