Skip to content

Commit 63019ab

Browse files
snicollsnicoll
committed
Add documentation for Maven plugin's build-image support
Closes gh-19830
1 parent 6df5e7a commit 63019ab

File tree

3 files changed

+113
-2
lines changed

3 files changed

+113
-2
lines changed

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

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ It allows you to package executable jar or war archives, run Spring Boot applica
1717

1818
include::getting-started.adoc[]
1919
include::packaging.adoc[]
20+
include::packaging-oci-image.adoc[]
2021
include::running.adoc[]
2122
include::integration-tests.adoc[]
2223
include::build-info.adoc[]

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

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
[[build-image]]
2+
== Packaging OCI Images
3+
4+
The plugin can create https://github.com/opencontainers/image-spec[OCI images] using a https://buildpacks.io/[buildpack].
5+
Images can be built using the `build-image` goal and a local Docker installation.
6+
7+
It is possible to automate the creation of an image whenever the `package` phase is invoked, as shown in the following example:
8+
9+
[source,xml,indent=0,subs="verbatim,attributes"]
10+
----
11+
<build>
12+
<plugins>
13+
<plugin>
14+
<groupId>org.springframework.boot</groupId>
15+
<artifactId>spring-boot-maven-plugin</artifactId>
16+
<version>{version}</version>
17+
<executions>
18+
<execution>
19+
<goals>
20+
<goal>build-image</goal>
21+
</goals>
22+
</execution>
23+
</executions>
24+
</plugin>
25+
</plugins>
26+
</build>
27+
----
28+
29+
TIP: While the buildpack runs from an <<repackage,executable archive>>, it is not necessary to execute the `repackage` goal first as the executable archive is created automatically if necessary.
30+
When the `build-image` repackages the application, it applies the same settings as the `repackage` goal would, i.e. dependencies can be excluded using one of the exclude options, and Devtools is automatically excluded by default (you can control that using the `excludeDevtools` property).
31+
32+
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.
33+
Both these settings can be tuned via configuration, see <<build-image-example-custom-image-builder,custom image builder>> and <<build-image-example-custom-image-name,custom image name>>.
34+
35+
include::goals/build-image.adoc[leveloffset=+1]
36+
37+
38+
[[build-image-examples]]
39+
=== Examples
40+
41+
[[build-image-example-custom-image-builder]]
42+
==== Custom Image Builder
43+
If you need to customize the builder used to create the image, configure yours as shown in the following example:
44+
45+
[source,xml,indent=0,subs="verbatim,attributes"]
46+
----
47+
<project>
48+
<build>
49+
<plugins>
50+
<plugin>
51+
<groupId>org.springframework.boot</groupId>
52+
<artifactId>spring-boot-maven-plugin</artifactId>
53+
<version>{version}</version>
54+
<executions>
55+
<execution>
56+
<id>build-image</id>
57+
<goals>
58+
<goal>build-image</goal>
59+
</goals>
60+
<configuration>
61+
<image>
62+
<builder>mine/java-cnb-builder</builder>
63+
</image>
64+
</configuration>
65+
</execution>
66+
</executions>
67+
</plugin>
68+
</plugins>
69+
</build>
70+
</project>
71+
----
72+
73+
This configuration will use the `latest` version of the `mine/java-cnb-builder` builder.
74+
75+
76+
77+
[[build-image-example-custom-image-name]]
78+
==== Custom Image Name
79+
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}`.
80+
You can take control over the name, as shown in the following example:
81+
82+
[source,xml,indent=0,subs="verbatim,attributes"]
83+
----
84+
<project>
85+
<build>
86+
<plugins>
87+
<plugin>
88+
<groupId>org.springframework.boot</groupId>
89+
<artifactId>spring-boot-maven-plugin</artifactId>
90+
<version>{version}</version>
91+
<executions>
92+
<execution>
93+
<id>build-image</id>
94+
<goals>
95+
<goal>build-image</goal>
96+
</goals>
97+
<configuration>
98+
<image>
99+
<name>example.com/library/${project.artifactId}</builder>
100+
</image>
101+
</configuration>
102+
</execution>
103+
</executions>
104+
</plugin>
105+
</plugins>
106+
</build>
107+
</project>
108+
----
109+
110+
Note that this configuration does not provide an explicit version so `latest` is used.
111+
It is possible to specify a version as well, either using `${project.version}`, any property available in the build or an hardcoded version.

‎spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/main/java/org/springframework/boot/maven/BuildImageMojo.java

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,8 +50,7 @@
5050
import org.springframework.util.StringUtils;
5151

5252
/**
53-
* Package an application into a OCI image using a
54-
* <a href="https://buildpacks.io">buildpack</a>.
53+
* Package an application into a OCI image using a buildpack.
5554
*
5655
* @author Phillip Webb
5756
* @since 2.3.0

0 commit comments

Comments
 (0)