Add documentation for gradle bootBuildImage task

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

@@ -1,5 +1,5 @@
 = Spring Boot Gradle Plugin Reference Guide
-Andy Wilkinson
+Andy Wilkinson, Scott Frederick
 :doctype: book
 :toc: left
 :toclevels: 4
@@ -25,6 +25,7 @@ Andy Wilkinson
 :spring-boot-docs: https://docs.spring.io/spring-boot/docs/{gradle-project-version}
 :api-documentation: {spring-boot-docs}/gradle-plugin/api
 :spring-boot-reference: {spring-boot-docs}/reference/htmlsingle
+:spring-boot-api: {spring-boot-docs}/api/org/springframework/boot
 :version-properties-appendix: {spring-boot-reference}/#dependency-versions-coordinates
 :build-info-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/buildinfo/BuildInfo.html
 :boot-build-image-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootBuildImage.html
@@ -32,7 +33,7 @@ Andy Wilkinson
 :boot-war-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootWar.html
 :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
 
 
 [[introduction]]
@@ -47,6 +48,7 @@ In addition to this user guide, {api-documentation}[API documentation] is also a
 include::getting-started.adoc[]
 include::managing-dependencies.adoc[]
 include::packaging.adoc[]
+include::packaging-oci-image.adoc[]
 include::publishing.adoc[]
 include::running.adoc[]
 include::integrating-with-actuator.adoc[]

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

@@ -0,0 +1,99 @@
+[[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].
+Images can be built using the `bootBuildImage` task and a local Docker installation.
+The task is automatically created when the `java` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`].
+
+[[build-image-customization]]
+=== Image Customizations
+The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
+The builder includes multiple {buildpacks-reference}/concepts/components/buildpack[buildpacks] that can inspect the application to influence the generated image.
+By default, the plugin chooses a builder image.
+The name of the generated image is deduced from project properties.
+
+Task properties can be used to configure how the builder should operate on the project.
+The following table summarizes the available properties and their default values:
+
+|===
+| Property | Description | Default value
+
+| `builder`
+| Name of the Builder image to use.
+| `cloudfoundry/cnb:0.0.43-bionic`
+
+| `imageName`
+| {spring-boot-api}/buildpack/platform/docker/type/ImageReference.html#of-java.lang.String-[Image name] for the generated image.
+| `docker.io/library/${project.artifactId}:${project.version}`
+
+| `environment`
+| Environment variables that should be passed to the builder.
+|
+
+| `cleanCache`
+| Whether to clean the cache before building.
+| `false`
+
+| `verboseLogging`
+| Enables verbose logging of builder operations.
+| `false`
+
+|===
+
+[[build-image-examples]]
+=== Examples
+
+[[build-image-example-custom-image-builder]]
+==== Custom Image Builder
+If you need to customize the builder used to create the image, configure the task as shown in the following example:
+
+[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
+.Groovy
+----
+include::../gradle/packaging/boot-build-image-builder.gradle[tags=builder]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.Kotlin
+----
+include::../gradle/packaging/boot-build-image-builder.gradle.kts[tags=builder]
+----
+
+This configuration will use a builder image with the name `mine/java-cnb-builder` and the tag `latest`.
+
+If the builder exposes configuration options, those can be set using the `environment` property, as shown in the following example:
+
+[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
+.Groovy
+----
+include::../gradle/packaging/boot-build-image-env.gradle[tags=env]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.Kotlin
+----
+include::../gradle/packaging/boot-build-image-env.gradle.kts[tags=env]
+----
+
+The example above assumes that the builder defines a `BP_JAVA_VERSION` property (typically used to customize the JDK version the image should use).
+
+
+[[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}`.
+You can take control over the name by setting task properties, as shown in the following example:
+
+[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
+.Groovy
+----
+include::../gradle/packaging/boot-build-image-name.gradle[tags=image-name]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.Kotlin
+----
+include::../gradle/packaging/boot-build-image-name.gradle.kts[tags=image-name]
+----
+
+Note that this configuration does not provide an explicit tag so `latest` is used.
+It is possible to specify a tag as well, either using `${project.version}`, any property available in the build or a hardcoded version.

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

@@ -299,11 +299,3 @@ The jar will then be split into layer folders which may include:
 * `snapshots-dependencies`
 * `dependencies`
 
-
-
-[[packaging-oci-images]]
-== Packaging OCI images
-
-The plugin can create OCI images from executable jars using a https://buildpacks.io[buildpack].
-Images can be built using the `bootBuildImage` task and a local Docker installation.
-The task is automatically created when the `java` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`].

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-builder.gradle

@@ -0,0 +1,14 @@
+plugins {
+	id 'java'
+	id 'org.springframework.boot' version '{version}'
+}
+
+bootJar {
+	mainClassName 'com.example.ExampleApplication'
+}
+
+// tag::builder[]
+bootBuildImage {
+	builder = "mine/java-cnb-builder"
+}
+// end::builder[]

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-builder.gradle.kts

@@ -0,0 +1,16 @@
+import org.springframework.boot.gradle.tasks.bundling.BootJar
+
+plugins {
+	java
+	id("org.springframework.boot") version "{version}"
+}
+
+tasks.getByName<BootJar>("bootJar") {
+	mainClassName = "com.example.ExampleApplication"
+}
+
+// tag::builder[]
+tasks.getByName<BootBuildImage>("bootBuildImage") {
+	builder = "mine/java-cnb-builder"
+}
+// end::builder[]

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

@@ -0,0 +1,14 @@
+plugins {
+	id 'java'
+	id 'org.springframework.boot' version '{version}'
+}
+
+bootJar {
+	mainClassName 'com.example.ExampleApplication'
+}
+
+// tag::env[]
+bootBuildImage {
+	environment = ["BP_JAVA_VERSION" : "13.0.1"]
+}
+// end::env[]

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

@@ -0,0 +1,16 @@
+import org.springframework.boot.gradle.tasks.bundling.BootJar
+
+plugins {
+	java
+	id("org.springframework.boot") version "{version}"
+}
+
+tasks.getByName<BootJar>("bootJar") {
+	mainClassName = "com.example.ExampleApplication"
+}
+
+// tag::env[]
+tasks.getByName<BootBuildImage>("bootBuildImage") {
+	environment = ["BP_JAVA_VERSION" : "13.0.1"]
+}
+// end::env[]

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-name.gradle

@@ -0,0 +1,14 @@
+plugins {
+	id 'java'
+	id 'org.springframework.boot' version '{version}'
+}
+
+bootJar {
+	mainClassName 'com.example.ExampleApplication'
+}
+
+// tag::image-name[]
+bootBuildImage {
+	imageName = "example.com/library/${project.artifactId}"
+}
+// end::image-name[]

spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-name.gradle.kts

@@ -0,0 +1,16 @@
+import org.springframework.boot.gradle.tasks.bundling.BootJar
+
+plugins {
+	java
+	id("org.springframework.boot") version "{version}"
+}
+
+tasks.getByName<BootJar>("bootJar") {
+	mainClassName = "com.example.ExampleApplication"
+}
+
+// tag::image-name[]
+tasks.getByName<BootBuildImage>("bootBuildImage") {
+	imageName = "example.com/library/${project.artifactId}"
+}
+// end::image-name[]