Document runtime JVM configuration when building an image
Fixes gh-21478
This commit is contained in:
Scott Frederick
parent
0bc5c2ba8c
commit
e19443093d
|
|
@ -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]]
|
||||
|
|
|
|||
|
|
@ -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}`.
|
||||
|
|
|
|||
|
|
@ -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" }
|
||||
}
|
||||
}
|
||||
|
|
@ -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)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
|
@ -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());
|
||||
|
|
|
|||
|
|
@ -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]]
|
||||
|
|
|
|||
|
|
@ -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}`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue