236 lines
7.6 KiB
Plaintext
236 lines
7.6 KiB
Plaintext
[[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].
|
|
Images can be built using the `build-image` goal.
|
|
|
|
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:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes"]
|
|
----
|
|
<build>
|
|
<plugins>
|
|
<plugin>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-maven-plugin</artifactId>
|
|
<version>{gradle-project-version}</version>
|
|
<executions>
|
|
<execution>
|
|
<goals>
|
|
<goal>build-image</goal>
|
|
</goals>
|
|
</execution>
|
|
</executions>
|
|
</plugin>
|
|
</plugins>
|
|
</build>
|
|
----
|
|
|
|
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.
|
|
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).
|
|
|
|
|
|
|
|
[[build-image-docker-daemon]]
|
|
=== Docker Daemon
|
|
The `build-image` goal requires access to a Docker daemon.
|
|
By default, it will communicate with a Docker daemon over a local connection.
|
|
This works with https://docs.docker.com/install/[Docker Engine] on all supported platforms without configuration.
|
|
|
|
Environment variables can be set to configure the `build-image` goal to use the https://minikube.sigs.k8s.io/docs/tasks/docker_daemon/[Docker daemon provided by minikube].
|
|
The following table shows the environment variables and their values:
|
|
|
|
|===
|
|
| Environment variable | Description
|
|
|
|
| DOCKER_HOST
|
|
| URL containing the host and port for the Docker daemon - e.g. `tcp://192.168.99.100:2376`
|
|
|
|
| DOCKER_TLS_VERIFY
|
|
| Enable secure HTTPS protocol when set to `1` (optional)
|
|
|
|
| DOCKER_CERT_PATH
|
|
| Path to certificate and key files for HTTPS (required if `DOCKER_TLS_VERIFY=1`, ignored otherwise)
|
|
|===
|
|
|
|
On Linux and macOS, these environment variables can be set using the command `eval $(minikube docker-env)` after minikube has been started.
|
|
|
|
|
|
|
|
[[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.
|
|
|
|
The `image` parameter allows to configure how the builder should operate on the project.
|
|
The following table summarizes the available parameters and their default values:
|
|
|
|
|===
|
|
| Parameter | Description | User property | Default value
|
|
|
|
| `builder`
|
|
| Name of the Builder image to use.
|
|
| `spring-boot.build-image.builder`
|
|
| `gcr.io/paketo-buildpacks/builder:base-platform-api-0.3`
|
|
|
|
| `name`
|
|
| {spring-boot-api}/buildpack/platform/docker/type/ImageReference.html#of-java.lang.String-[Image name] for the generated image.
|
|
| `spring-boot.build-image.imageName`
|
|
| `docker.io/library/${project.artifactId}:${project.version}`
|
|
|
|
| `env`
|
|
| 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`
|
|
|===
|
|
|
|
For more details, see <<build-image-example-custom-image-builder,custom image builder>> and <<build-image-example-custom-image-name,custom image name>>.
|
|
|
|
include::goals/build-image.adoc[leveloffset=+1]
|
|
|
|
|
|
|
|
[[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 plugin as 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>
|
|
<version>{gradle-project-version}</version>
|
|
<configuration>
|
|
<image>
|
|
<builder>mine/java-cnb-builder</builder>
|
|
</image>
|
|
</configuration>
|
|
</plugin>
|
|
</plugins>
|
|
</build>
|
|
</project>
|
|
----
|
|
|
|
This configuration will use a builder image with the name `mine/java-cnb-builder` and the tag `latest`.
|
|
|
|
The builder can be specified on the command line as well, as shown in this example:
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn spring-boot:build-image -Dspring-boot.build-image.builder=mine/java-cnb-builder
|
|
----
|
|
|
|
|
|
|
|
[[build-image-example-builder-configuration]]
|
|
==== 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 defines a `BP_JVM_VERSION` property (typically used to customize the JDK version the image should use):
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes"]
|
|
----
|
|
<project>
|
|
<build>
|
|
<plugins>
|
|
<plugin>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-maven-plugin</artifactId>
|
|
<version>{gradle-project-version}</version>
|
|
<configuration>
|
|
<image>
|
|
<env>
|
|
<BP_JVM_VERSION>13.0.1</BP_JVM_VERSION>
|
|
</env>
|
|
</image>
|
|
</configuration>
|
|
</plugin>
|
|
</plugins>
|
|
</build>
|
|
</project>
|
|
----
|
|
|
|
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:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes"]
|
|
----
|
|
<project>
|
|
<build>
|
|
<plugins>
|
|
<plugin>
|
|
<groupId>org.springframework.boot</groupId>
|
|
<artifactId>spring-boot-maven-plugin</artifactId>
|
|
<version>{gradle-project-version}</version>
|
|
<configuration>
|
|
<image>
|
|
<env>
|
|
<HTTP_PROXY>http://proxy.example.com</HTTP_PROXY>
|
|
<HTTPS_PROXY>https://proxy.example.com</HTTPS_PROXY>
|
|
</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}`.
|
|
You can take control over the name, as 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>
|
|
<version>{gradle-project-version}</version>
|
|
<configuration>
|
|
<image>
|
|
<name>example.com/library/${project.artifactId}</name>
|
|
</image>
|
|
</configuration>
|
|
</plugin>
|
|
</plugins>
|
|
</build>
|
|
</project>
|
|
----
|
|
|
|
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.
|
|
|
|
The image name can be specified on the command line as well, as shown in this example:
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn spring-boot:build-image -Dspring-boot.build-image.imageName=example.com/library/my-app:v1
|
|
----
|
|
|