From 49b0707f1a14e4a005f8a2a898ecd82bbb530d53 Mon Sep 17 00:00:00 2001 From: Scott Frederick Date: Thu, 8 Oct 2020 17:02:17 -0500 Subject: [PATCH] Clarify image builder configuration documentation This commit qualifies examples of configuring the CNB builder to clarify that the examples apply to use of the default Paketo builder, and adds links to the official Paketo docs for more details. Fixes gh-19967 --- .../src/docs/asciidoc/index.adoc | 1 + .../src/docs/asciidoc/packaging-oci-image.adoc | 16 +++++++++------- .../src/docs/asciidoc/index.adoc | 1 + .../src/docs/asciidoc/packaging-oci-image.adoc | 16 +++++++++------- 4 files changed, 20 insertions(+), 14 deletions(-) diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc index 69a1d51b1dd..a34f42ffebb 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc @@ -34,6 +34,7 @@ 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 [[introduction]] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc index 44e3df42a4a..ee625c3a958 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc @@ -1,9 +1,10 @@ [[build-image]] == Packaging OCI Images -The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from executable jars using https://buildpacks.io[Cloud Native Buildpacks]. +The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from executable jars using https://buildpacks.io[Cloud Native Buildpacks] (CNB). Images can be built using the `bootBuildImage` task. -NOTE: For security reasons, images build and run as non-root users, see https://buildpacks.io/docs/reference/spec/platform-api/#users[this section fore more details]. +NOTE: For security reasons, images build and run as non-root users. +See the {buildpacks-reference}/reference/spec/platform-api/#users[CNB specification] for more details. The task is automatically created when the `java` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`]. @@ -81,8 +82,8 @@ The following table summarizes the available properties and their default values |=== NOTE: The plugin detects the target Java compatibility of the project using the JavaPlugin's `targetCompatibility` property. -By default, the plugin instructs the buildpacks to install the same Java version. -You can override this behaviour by setting the `BP_JVM_VERSION` environment variable, see <>. +When using the default Paketo builder and buildpacks, the plugin instructs the buildpacks to install the same Java version. +You can override this behaviour as shown in the <> examples. @@ -122,8 +123,7 @@ $ gradle bootBuildImage --builder=mine/java-cnb-builder --runImage=mine/java-cnb ==== Builder Configuration If the builder exposes configuration options, those can be set using the `environment` property. -The following example assumes that the default builder recognizes a `BP_JVM_VERSION` property. -This property is typically used to customize the JDK version the image should use by specifying the major version and a wildcard for the rest of the version: +The following is an example of {paketo-java-reference}/#configuring-the-jvm-version[configuring the JVM version] used by the Paketo Java buildpacks at build time: [source,groovy,indent=0,subs="verbatim,attributes",role="primary"] .Groovy @@ -137,8 +137,10 @@ include::../gradle/packaging/boot-build-image-env.gradle[tags=env] include::../gradle/packaging/boot-build-image-env.gradle.kts[tags=env] ---- +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 default builder, this can be accomplished by setting the `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables as show in the following example: +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: [source,groovy,indent=0,subs="verbatim,attributes",role="primary"] .Groovy diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc index 65c1a77dbb7..e621e7b1008 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc @@ -14,6 +14,7 @@ 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 [[introduction]] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc index dd0605f86d6..fc7bac3cc92 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc @@ -1,9 +1,10 @@ [[build-image]] == Packaging OCI Images -The plugin can create an https://github.com/opencontainers/image-spec[OCI image] using https://buildpacks.io/[Cloud Native Buildpacks]. +The plugin can create an https://github.com/opencontainers/image-spec[OCI image] using https://buildpacks.io/[Cloud Native Buildpacks] (CNB). Images can be built using the `build-image` goal. -NOTE: For security reasons, images build and run as non-root users, see https://buildpacks.io/docs/reference/spec/platform-api/#users[this section fore more details]. +NOTE: For security reasons, images build and run as non-root users. +See the {buildpacks-reference}/reference/spec/platform-api/#users[CNB specification] for more details. The easiest way to get started is to invoke `mvn spring-boot:build-image` on a project. It is possible to automate the creation of an image whenever the `package` phase is invoked, as shown in the following example: @@ -104,8 +105,8 @@ The following table summarizes the available parameters and their default values |=== NOTE: The plugin detects the target Java compatibility of the project using the compiler's plugin configuration or the `maven.compiler.target` property. -By default, the plugin instructs the buildpacks to install the same Java version. -You can override this behaviour by setting the `BP_JVM_VERSION` environment variable, see <>. +When using the default Paketo builder and buildpacks, the plugin instructs the buildpacks to install the same Java version. +You can override this behaviour as shown in the <> examples. For more details, see also <> and <>. @@ -158,8 +159,7 @@ The builder and run image can be specified on the command line as well, as shown ==== Builder Configuration If the builder exposes configuration options using environment variables, those can be set using the `env` attributes. -The following example assumes that the default builder recognizes a `BP_JVM_VERSION` property. -This property is typically used to customize the JDK version the image should use by specifying the major version and a wildcard for the rest of the version: +The following is an example of {paketo-java-reference}/#configuring-the-jvm-version[configuring the JVM version] used by the Paketo Java buildpacks at build time: [source,xml,indent=0,subs="verbatim,attributes"] ---- @@ -183,8 +183,10 @@ This property is typically used to customize the JDK version the image should us ---- +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 default builder, this can be accomplished by setting the `HTTPS_PROXY` and/or `HTTP_PROXY` environment variables as show in the following example: +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: [source,xml,indent=0,subs="verbatim,attributes"] ----