Skip to content

Commit 653cabe

Browse files
scottfrederickscottfrederick
committed
Add documentation for gradle bootBuildImage task
1 parent bceed13 commit 653cabe

File tree

11 files changed

+212
-25
lines changed

11 files changed

+212
-25
lines changed

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

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
= Spring Boot Gradle Plugin Reference Guide
2-
Andy Wilkinson
2+
Andy Wilkinson, Scott Frederick
33
:doctype: book
44
:toc: left
55
:toclevels: 4
@@ -25,14 +25,15 @@ Andy Wilkinson
2525
:spring-boot-docs: https://docs.spring.io/spring-boot/docs/{gradle-project-version}
2626
:api-documentation: {spring-boot-docs}/gradle-plugin/api
2727
:spring-boot-reference: {spring-boot-docs}/reference/htmlsingle
28+
:spring-boot-api: {spring-boot-docs}/api/org/springframework/boot
2829
:version-properties-appendix: {spring-boot-reference}/#dependency-versions-coordinates
2930
:build-info-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/buildinfo/BuildInfo.html
3031
:boot-build-image-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootBuildImage.html
3132
:boot-jar-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootJar.html
3233
:boot-war-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/bundling/BootWar.html
3334
:boot-run-javadoc: {api-documentation}/org/springframework/boot/gradle/tasks/run/BootRun.html
3435
:github-code: https://github.com/spring-projects/spring-boot/tree/{github-tag}
35-
36+
:buildpacks-reference: https://buildpacks.io/docs
3637

3738

3839
[[introduction]]
@@ -47,6 +48,7 @@ In addition to this user guide, {api-documentation}[API documentation] is also a
4748
include::getting-started.adoc[]
4849
include::managing-dependencies.adoc[]
4950
include::packaging.adoc[]
51+
include::packaging-oci-image.adoc[]
5052
include::publishing.adoc[]
5153
include::running.adoc[]
5254
include::integrating-with-actuator.adoc[]

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

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
[[build-image]]
2+
== Packaging OCI images
3+
4+
The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from executable jars using https://buildpacks.io[Cloud Native Buildpacks].
5+
Images can be built using the `bootBuildImage` task and a local Docker installation.
6+
The task is automatically created when the `java` plugin is applied and is an instance of {boot-build-image-javadoc}[`BootBuildImage`].
7+
8+
[[build-image-customization]]
9+
=== Image Customizations
10+
The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
11+
The builder includes multiple {buildpacks-reference}/concepts/components/buildpack[buildpacks] that can inspect the application to influence the generated image.
12+
By default, the plugin chooses a builder image.
13+
The name of the generated image is deduced from project properties.
14+
15+
Task properties can be used to configure how the builder should operate on the project.
16+
The following table summarizes the available properties and their default values:
17+
18+
|===
19+
| Property | Description | Default value
20+
21+
| `builder`
22+
| Name of the Builder image to use.
23+
| `cloudfoundry/cnb:0.0.43-bionic`
24+
25+
| `imageName`
26+
| {spring-boot-api}/buildpack/platform/docker/type/ImageReference.html#of-java.lang.String-[Image name] for the generated image.
27+
| `docker.io/library/${project.artifactId}:${project.version}`
28+
29+
| `environment`
30+
| Environment variables that should be passed to the builder.
31+
|
32+
33+
| `cleanCache`
34+
| Whether to clean the cache before building.
35+
| `false`
36+
37+
| `verboseLogging`
38+
| Enables verbose logging of builder operations.
39+
| `false`
40+
41+
|===
42+
43+
[[build-image-examples]]
44+
=== Examples
45+
46+
[[build-image-example-custom-image-builder]]
47+
==== Custom Image Builder
48+
If you need to customize the builder used to create the image, configure the task as shown in the following example:
49+
50+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
51+
.Groovy
52+
----
53+
include::../gradle/packaging/boot-build-image-builder.gradle[tags=builder]
54+
----
55+
56+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
57+
.Kotlin
58+
----
59+
include::../gradle/packaging/boot-build-image-builder.gradle.kts[tags=builder]
60+
----
61+
62+
This configuration will use a builder image with the name `mine/java-cnb-builder` and the tag `latest`.
63+
64+
If the builder exposes configuration options, those can be set using the `environment` property, as shown in the following example:
65+
66+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
67+
.Groovy
68+
----
69+
include::../gradle/packaging/boot-build-image-env.gradle[tags=env]
70+
----
71+
72+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
73+
.Kotlin
74+
----
75+
include::../gradle/packaging/boot-build-image-env.gradle.kts[tags=env]
76+
----
77+
78+
The example above assumes that the builder defines a `BP_JAVA_VERSION` property (typically used to customize the JDK version the image should use).
79+
80+
81+
[[build-image-example-custom-image-name]]
82+
==== Custom Image Name
83+
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}`.
84+
You can take control over the name by setting task properties, as shown in the following example:
85+
86+
[source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
87+
.Groovy
88+
----
89+
include::../gradle/packaging/boot-build-image-name.gradle[tags=image-name]
90+
----
91+
92+
[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
93+
.Kotlin
94+
----
95+
include::../gradle/packaging/boot-build-image-name.gradle.kts[tags=image-name]
96+
----
97+
98+
Note that this configuration does not provide an explicit tag so `latest` is used.
99+
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

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -299,11 +299,3 @@ The jar will then be split into layer folders which may include:
299299
* `snapshots-dependencies`
300300
* `dependencies`
301301

302-
303-
304-
[[packaging-oci-images]]
305-
== Packaging OCI images
306-
307-
The plugin can create OCI images from executable jars using a https://buildpacks.io[buildpack].
308-
Images can be built using the `bootBuildImage` task and a local Docker installation.
309-
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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
plugins {
2+
id 'java'
3+
id 'org.springframework.boot' version '{version}'
4+
}
5+
6+
bootJar {
7+
mainClassName 'com.example.ExampleApplication'
8+
}
9+
10+
// tag::builder[]
11+
bootBuildImage {
12+
builder = "mine/java-cnb-builder"
13+
}
14+
// end::builder[]

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import org.springframework.boot.gradle.tasks.bundling.BootJar
2+
3+
plugins {
4+
java
5+
id("org.springframework.boot") version "{version}"
6+
}
7+
8+
tasks.getByName<BootJar>("bootJar") {
9+
mainClassName = "com.example.ExampleApplication"
10+
}
11+
12+
// tag::builder[]
13+
tasks.getByName<BootBuildImage>("bootBuildImage") {
14+
builder = "mine/java-cnb-builder"
15+
}
16+
// end::builder[]

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
plugins {
2+
id 'java'
3+
id 'org.springframework.boot' version '{version}'
4+
}
5+
6+
bootJar {
7+
mainClassName 'com.example.ExampleApplication'
8+
}
9+
10+
// tag::env[]
11+
bootBuildImage {
12+
environment = ["BP_JAVA_VERSION" : "13.0.1"]
13+
}
14+
// end::env[]

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import org.springframework.boot.gradle.tasks.bundling.BootJar
2+
3+
plugins {
4+
java
5+
id("org.springframework.boot") version "{version}"
6+
}
7+
8+
tasks.getByName<BootJar>("bootJar") {
9+
mainClassName = "com.example.ExampleApplication"
10+
}
11+
12+
// tag::env[]
13+
tasks.getByName<BootBuildImage>("bootBuildImage") {
14+
environment = ["BP_JAVA_VERSION" : "13.0.1"]
15+
}
16+
// end::env[]

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

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
plugins {
2+
id 'java'
3+
id 'org.springframework.boot' version '{version}'
4+
}
5+
6+
bootJar {
7+
mainClassName 'com.example.ExampleApplication'
8+
}
9+
10+
// tag::image-name[]
11+
bootBuildImage {
12+
imageName = "example.com/library/${project.artifactId}"
13+
}
14+
// end::image-name[]

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

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
import org.springframework.boot.gradle.tasks.bundling.BootJar
2+
3+
plugins {
4+
java
5+
id("org.springframework.boot") version "{version}"
6+
}
7+
8+
tasks.getByName<BootJar>("bootJar") {
9+
mainClassName = "com.example.ExampleApplication"
10+
}
11+
12+
// tag::image-name[]
13+
tasks.getByName<BootBuildImage>("bootBuildImage") {
14+
imageName = "example.com/library/${project.artifactId}"
15+
}
16+
// end::image-name[]

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
= Spring Boot Maven Plugin Documentation
2-
Stephane Nicoll, Andy Wilkinson
2+
Stephane Nicoll, Andy Wilkinson, Scott Frederick
33
:doctype: book
44
:toc: left
55
:toclevels: 4

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

Lines changed: 18 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
[[build-image]]
22
== Packaging OCI Images
33

4-
The plugin can create https://github.com/opencontainers/image-spec[OCI images] using a https://buildpacks.io/[buildpack].
4+
The plugin can create an https://github.com/opencontainers/image-spec[OCI image] using https://buildpacks.io/[Cloud Native Buildpacks].
55
Images can be built using the `build-image` goal and a local Docker installation.
66

77
The easiest way to get started is to to invoke `mvn spring-boot:build-image` on a project.
@@ -14,7 +14,7 @@ It is possible to automate the creation of an image whenever the `package` phase
1414
<plugin>
1515
<groupId>org.springframework.boot</groupId>
1616
<artifactId>spring-boot-maven-plugin</artifactId>
17-
<version>{version}</version>
17+
<version>{gradle-project-version}</version>
1818
<executions>
1919
<execution>
2020
<goals>
@@ -32,31 +32,35 @@ When the `build-image` repackages the application, it applies the same settings
3232

3333
[[build-image-customization]]
3434
=== Image Customizations
35-
By default, the image is built using the `cloudfoundry/cnb:0.0.43-bionic` builder and its name is deduced from the `artifactId` of the project.
35+
The plugin invokes a {buildpacks-reference}/concepts/components/builder/[builder] to orchestrate the generation of an image.
36+
The builder includes multiple {buildpacks-reference}/concepts/components/buildpack[buildpacks] that can inspect the application to influence the generated image.
37+
By default, the plugin chooses a builder image.
38+
The name of the generated image is deduced from project properties.
39+
3640
The `image` parameter allows to configure how the builder should operate on the project.
3741
The following table summarizes the available properties and their default values:
3842

3943
|===
4044
| Property | Description | Default value
4145

4246
| `builder`
43-
| {buildpacks-reference}/concepts/components/builder/[Builder image] name to use.
47+
| Name of the Builder image to use.
4448
| `cloudfoundry/cnb:0.0.43-bionic`
4549

4650
| `name`
47-
| {spring-boot-api}/buildpack/platform/docker/type/ImageReference.html#of-java.lang.String-[Image name].
51+
| {spring-boot-api}/buildpack/platform/docker/type/ImageReference.html#of-java.lang.String-[Image name] for the generated image.
4852
| `docker.io/library/${project.artifactId}:${project.version}`
4953

5054
| `env`
51-
| Environment properties that should be passed to the builder.
55+
| Environment variables that should be passed to the builder.
5256
|
5357

5458
| `cleanCache`
5559
| Whether to clean the cache before building.
5660
| `false`
5761

5862
| `verboseLogging`
59-
| Whether verbose logging is required.
63+
| Enables verbose logging of builder operations.
6064
| `false`
6165

6266
|===
@@ -81,7 +85,7 @@ If you need to customize the builder used to create the image, configure yours a
8185
<plugin>
8286
<groupId>org.springframework.boot</groupId>
8387
<artifactId>spring-boot-maven-plugin</artifactId>
84-
<version>{version}</version>
88+
<version>{gradle-project-version}</version>
8589
<configuration>
8690
<image>
8791
<builder>mine/java-cnb-builder</builder>
@@ -93,7 +97,7 @@ If you need to customize the builder used to create the image, configure yours a
9397
</project>
9498
----
9599

96-
This configuration will use the `latest` version of the `mine/java-cnb-builder` builder.
100+
This configuration will use a builder image with the name `mine/java-cnb-builder` and the tag `latest`.
97101

98102
If the builder exposes configuration options, those can be set using the `env` attributes, as shown in the following example:
99103

@@ -105,7 +109,7 @@ If the builder exposes configuration options, those can be set using the `env` a
105109
<plugin>
106110
<groupId>org.springframework.boot</groupId>
107111
<artifactId>spring-boot-maven-plugin</artifactId>
108-
<version>{version}</version>
112+
<version>{gradle-project-version}</version>
109113
<configuration>
110114
<image>
111115
<builder>mine/java-cnb-builder</builder>
@@ -126,7 +130,7 @@ The example above assumes that `mine/java-cnb-builder` defines a `BP_JAVA_VERSIO
126130

127131
[[build-image-example-custom-image-name]]
128132
==== Custom Image Name
129-
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}`.
133+
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}`.
130134
You can take control over the name, as shown in the following example:
131135

132136
[source,xml,indent=0,subs="verbatim,attributes"]
@@ -137,7 +141,7 @@ You can take control over the name, as shown in the following example:
137141
<plugin>
138142
<groupId>org.springframework.boot</groupId>
139143
<artifactId>spring-boot-maven-plugin</artifactId>
140-
<version>{version}</version>
144+
<version>{gradle-project-version}</version>
141145
<configuration>
142146
<image>
143147
<name>example.com/library/${project.artifactId}</name>
@@ -149,5 +153,5 @@ You can take control over the name, as shown in the following example:
149153
</project>
150154
----
151155

152-
Note that this configuration does not provide an explicit version so `latest` is used.
153-
It is possible to specify a version as well, either using `${project.version}`, any property available in the build or an hardcoded version.
156+
Note that this configuration does not provide an explicit tag so `latest` is used.
157+
It is possible to specify a tag as well, either using `${project.version}`, any property available in the build or a hardcoded version.

0 commit comments

Comments
 (0)