487 lines
22 KiB
Plaintext
487 lines
22 KiB
Plaintext
[[build-image]]
|
|
= Packaging OCI Images
|
|
The plugin can create an https://github.com/opencontainers/image-spec[OCI image] from a jar or war file using https://buildpacks.io/[Cloud Native Buildpacks] (CNB).
|
|
Images can be built on the command-line using the `build-image` goal.
|
|
This makes sure that the package lifecycle has run before the image is created.
|
|
|
|
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:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/pom.xml[tags=packaging-oci-image]
|
|
----
|
|
|
|
NOTE: Use `build-image-no-fork` when binding the goal to the package lifecycle.
|
|
This goal is similar to `build-image` but does not fork the lifecycle to make sure `package` has run.
|
|
In the rest of this section, `build-image` is used to refer to either the `build-image` or `build-image-no-fork` goals.
|
|
|
|
TIP: While the buildpack runs from an <<packaging,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, that is dependencies can be excluded using one of the exclude options.
|
|
The `spring-boot-devtools` and `spring-boot-docker-compose` modules are automatically excluded by default (you can control this using the `excludeDevtools` and `excludeDockerCompose` properties).
|
|
|
|
|
|
|
|
[[build-image.docker-daemon]]
|
|
== Docker Daemon
|
|
The `build-image` goal requires access to a Docker daemon.
|
|
The goal will inspect local Docker CLI https://docs.docker.com/engine/reference/commandline/cli/#configuration-files[configuration files] to determine the current https://docs.docker.com/engine/context/working-with-contexts/[context] and use the context connection information to communicate with a Docker daemon.
|
|
If the current context can not be determined or the context does not have connection information, then the goal will use a default 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 an alternative local or remote connection.
|
|
The following table shows the environment variables and their values:
|
|
|
|
|===
|
|
| Environment variable | Description
|
|
|
|
| DOCKER_CONFIG
|
|
| Location of Docker CLI https://docs.docker.com/engine/reference/commandline/cli/#configuration-files[configuration files] used to determine the current context (defaults to `$HOME/.docker`)
|
|
|
|
| DOCKER_CONTEXT
|
|
| Name of a https://docs.docker.com/engine/context/working-with-contexts/[context] that should be used to retrieve host information from Docker CLI configuration files (overrides `DOCKER_HOST`)
|
|
|
|
| DOCKER_HOST
|
|
| URL containing the host and port for the Docker daemon - for example `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)
|
|
|===
|
|
|
|
Docker daemon connection information can also be provided using `docker` parameters in the plugin configuration.
|
|
The following table summarizes the available parameters:
|
|
|
|
|===
|
|
| Parameter | Description
|
|
|
|
| `context`
|
|
| Name of a https://docs.docker.com/engine/context/working-with-contexts/[context] that should be used to retrieve host information from Docker CLI https://docs.docker.com/engine/reference/commandline/cli/#configuration-files[configuration files]
|
|
|
|
| `host`
|
|
| URL containing the host and port for the Docker daemon - for example `tcp://192.168.99.100:2376`
|
|
|
|
| `tlsVerify`
|
|
| Enable secure HTTPS protocol when set to `true` (optional)
|
|
|
|
| `certPath`
|
|
| Path to certificate and key files for HTTPS (required if `tlsVerify` is `true`, ignored otherwise)
|
|
|
|
| `bindHostToBuilder`
|
|
| When `true`, the value of the `host` property will be provided to the container that is created for the CNB builder (optional)
|
|
|===
|
|
|
|
For more details, see also <<build-image.examples.docker,examples>>.
|
|
|
|
|
|
|
|
[[build-image.docker-registry]]
|
|
== Docker Registry
|
|
If the Docker images specified by the `builder` or `runImage` parameters are stored in a private Docker image registry that requires authentication, the authentication credentials can be provided using `docker.builderRegistry` parameters.
|
|
|
|
If the generated Docker image is to be published to a Docker image registry, the authentication credentials can be provided using `docker.publishRegistry` parameters.
|
|
|
|
Parameters are provided for user authentication or identity token authentication.
|
|
Consult the documentation for the Docker registry being used to store images for further information on supported authentication methods.
|
|
|
|
The following table summarizes the available parameters for `docker.builderRegistry` and `docker.publishRegistry`:
|
|
|
|
|===
|
|
| Parameter | Description
|
|
|
|
| `username`
|
|
| Username for the Docker image registry user. Required for user authentication.
|
|
|
|
| `password`
|
|
| Password for the Docker image registry user. Required for user authentication.
|
|
|
|
| `url`
|
|
| Address of the Docker image registry. Optional for user authentication.
|
|
|
|
| `email`
|
|
| E-mail address for the Docker image registry user. Optional for user authentication.
|
|
|
|
| `token`
|
|
| Identity token for the Docker image registry user. Required for token authentication.
|
|
|===
|
|
|
|
For more details, see also <<build-image.examples.docker,examples>>.
|
|
|
|
|
|
|
|
[[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 configuration of the builder and how it should operate on the project.
|
|
The following table summarizes the available parameters and their default values:
|
|
|
|
[cols="1,4,1"]
|
|
|===
|
|
| Parameter / (User Property)| Description | Default value
|
|
|
|
| `builder` +
|
|
(`spring-boot.build-image.builder`)
|
|
| Name of the Builder image to use.
|
|
| `paketobuildpacks/builder-jammy-base:latest`
|
|
|
|
| `runImage` +
|
|
(`spring-boot.build-image.runImage`)
|
|
| Name of the run image to use.
|
|
| No default value, indicating the run image specified in Builder metadata should be used.
|
|
|
|
| `name` +
|
|
(`spring-boot.build-image.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}`
|
|
|
|
| `pullPolicy` +
|
|
(`spring-boot.build-image.pullPolicy`)
|
|
| {spring-boot-api}/buildpack/platform/build/PullPolicy.html[Policy] used to determine when to pull the builder and run images from the registry.
|
|
Acceptable values are `ALWAYS`, `NEVER`, and `IF_NOT_PRESENT`.
|
|
| `ALWAYS`
|
|
|
|
| `env`
|
|
| Environment variables that should be passed to the builder.
|
|
|
|
|
|
|
| `buildpacks`
|
|
a|Buildpacks that the builder should use when building the image.
|
|
Only the specified buildpacks will be used, overriding the default buildpacks included in the builder.
|
|
Buildpack references must be in one of the following forms:
|
|
|
|
* Buildpack in the builder - `[urn:cnb:builder:]<buildpack ID>[@<version>]`
|
|
* Buildpack in a directory on the file system - `[file://]<path>`
|
|
* Buildpack in a gzipped tar (.tgz) file on the file system - `[file://]<path>/<file name>`
|
|
* Buildpack in an OCI image - `[docker://]<host>/<repo>[:<tag>][@<digest>]`
|
|
| None, indicating the builder should use the buildpacks included in it.
|
|
|
|
| `bindings`
|
|
a|https://docs.docker.com/storage/bind-mounts/[Volume bind mounts] that should be mounted to the builder container when building the image.
|
|
The bindings will be passed unparsed and unvalidated to Docker when creating the builder container.
|
|
Bindings must be in one of the following forms:
|
|
|
|
* `<host source path>:<container destination path>[:<options>]`
|
|
* `<host volume name>:<container destination path>[:<options>]`
|
|
|
|
Where `<options>` can contain:
|
|
|
|
* `ro` to mount the volume as read-only in the container
|
|
* `rw` to mount the volume as readable and writable in the container
|
|
* `volume-opt=key=value` to specify key-value pairs consisting of an option name and its value
|
|
|
|
|
|
|
| `network` + (`spring-boot.build-image.network`)
|
|
| The https://docs.docker.com/network/#network-drivers[network driver] the builder container will be configured to use.
|
|
The value supplied will be passed unvalidated to Docker when creating the builder container.
|
|
|
|
|
|
|
| `cleanCache` + (`spring-boot.build-image.cleanCache`)
|
|
| Whether to clean the cache before building.
|
|
| `false`
|
|
|
|
| `verboseLogging`
|
|
| Enables verbose logging of builder operations.
|
|
| `false`
|
|
|
|
| `publish` + (`spring-boot.build-image.publish`)
|
|
| Whether to publish the generated image to a Docker registry.
|
|
| `false`
|
|
|
|
| `tags`
|
|
| One or more additional tags to apply to the generated image.
|
|
The values provided to the `tags` option should be full image references in the form of `[image name]:[tag]` or `[repository]/[image name]:[tag]`.
|
|
|
|
|
|
|
| `buildWorkspace`
|
|
| A temporary workspace that will be used by the builder and buildpacks to store files during image building.
|
|
The value can be a named volume or a bind mount location.
|
|
| A named volume in the Docker daemon, with a name derived from the image name.
|
|
|
|
| `buildCache`
|
|
| A cache containing layers created by buildpacks and used by the image building process.
|
|
The value can be a named volume or a bind mount location.
|
|
| A named volume in the Docker daemon, with a name derived from the image name.
|
|
|
|
| `launchCache`
|
|
| A cache containing layers created by buildpacks and used by the image launching process.
|
|
The value can be a named volume or a bind mount location.
|
|
| A named volume in the Docker daemon, with a name derived from the image name.
|
|
|
|
| `createdDate` +
|
|
(`spring-boot.build-image.createdDate`)
|
|
| A date that will be used to set the `Created` field in the generated image's metadata.
|
|
The value must be a string in the ISO 8601 instant format, or `now` to use the current date and time.
|
|
| A fixed date that enables https://buildpacks.io/docs/features/reproducibility/[build reproducibility].
|
|
|
|
|
|
| `applicationDirectory` +
|
|
(`spring-boot.build-image.applicationDirectory`)
|
|
| The path to a directory that application contents will be uploaded to in the builder image.
|
|
Application contents will also be in this location in the generated image.
|
|
| `/workspace`
|
|
|
|
| `securityOptions`
|
|
| https://docs.docker.com/engine/reference/run/#security-configuration[Security options] that will be applied to the builder container, provided as an array of string values
|
|
| `["label=disable"]` on Linux and macOS, `[]` on Windows
|
|
|
|
|===
|
|
|
|
NOTE: The plugin detects the target Java compatibility of the project using the compiler's plugin configuration or the `maven.compiler.target` property.
|
|
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 <<build-image.examples.builder-configuration,builder configuration>> examples.
|
|
|
|
For more details, see also <<build-image.examples,examples>>.
|
|
|
|
include::goals/build-image.adoc[leveloffset=+1]
|
|
include::goals/build-image-no-fork.adoc[leveloffset=+1]
|
|
|
|
|
|
|
|
[[build-image.examples]]
|
|
== Examples
|
|
|
|
|
|
|
|
[[build-image.examples.custom-image-builder]]
|
|
=== Custom Image Builder
|
|
If you need to customize the builder used to create the image or the run image used to launch the built image, configure the plugin as shown in the following example:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/custom-image-builder-pom.xml[tags=custom-image-builder]
|
|
----
|
|
|
|
This configuration will use a builder image with the name `mine/java-cnb-builder` and the tag `latest`, and the run image named `mine/java-cnb-run` and the tag `latest`.
|
|
|
|
The builder and run image 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 -Dspring-boot.build-image.runImage=mine/java-cnb-run
|
|
----
|
|
|
|
|
|
|
|
[[build-image.examples.builder-configuration]]
|
|
=== Builder Configuration
|
|
If the builder exposes configuration options using environment variables, those can be set using the `env` attributes.
|
|
|
|
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",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/build-image-example-builder-configuration-pom.xml[tags=build-image-example-builder-configuration]
|
|
----
|
|
|
|
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 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",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/paketo-pom.xml[tags=paketo]
|
|
----
|
|
|
|
|
|
|
|
[[build-image.examples.runtime-jvm-configuration]]
|
|
=== Runtime JVM Configuration
|
|
Paketo Java buildpacks {paketo-java-reference}/#runtime-jvm-configuration[configure the JVM runtime environment] by setting the `JAVA_TOOL_OPTIONS` environment variable.
|
|
The buildpack-provided `JAVA_TOOL_OPTIONS` value can be modified to customize JVM runtime behavior when the application image is launched in a container.
|
|
|
|
Environment variable modifications that should be stored in the image and applied to every deployment can be set as described in the {paketo-reference}/buildpacks/configuration/#environment-variables[Paketo documentation] and shown in the following example:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/runtime-jvm-configuration-pom.xml[tags=runtime-jvm-configuration]
|
|
----
|
|
|
|
|
|
|
|
[[build-image.examples.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",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/custom-image-name-pom.xml[tags=custom-image-name]
|
|
----
|
|
|
|
NOTE: 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
|
|
----
|
|
|
|
|
|
|
|
[[build-image.examples.buildpacks]]
|
|
=== Buildpacks
|
|
By default, the builder will use buildpacks included in the builder image and apply them in a pre-defined order.
|
|
An alternative set of buildpacks can be provided to apply buildpacks that are not included in the builder, or to change the order of included buildpacks.
|
|
When one or more buildpacks are provided, only the specified buildpacks will be applied.
|
|
|
|
The following example instructs the builder to use a custom buildpack packaged in a `.tgz` file, followed by a buildpack included in the builder.
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/buildpacks-pom.xml[tags=buildpacks]
|
|
----
|
|
|
|
Buildpacks can be specified in any of the forms shown below.
|
|
|
|
A buildpack located in a CNB Builder (version may be omitted if there is only one buildpack in the builder matching the `buildpack-id`):
|
|
|
|
* `urn:cnb:builder:buildpack-id`
|
|
* `urn:cnb:builder:buildpack-id@0.0.1`
|
|
* `buildpack-id`
|
|
* `buildpack-id@0.0.1`
|
|
|
|
A path to a directory containing buildpack content (not supported on Windows):
|
|
|
|
* `\file:///path/to/buildpack/`
|
|
* `/path/to/buildpack/`
|
|
|
|
A path to a gzipped tar file containing buildpack content:
|
|
|
|
* `\file:///path/to/buildpack.tgz`
|
|
* `/path/to/buildpack.tgz`
|
|
|
|
An OCI image containing a https://buildpacks.io/docs/buildpack-author-guide/package-a-buildpack/[packaged buildpack]:
|
|
|
|
* `docker://example/buildpack`
|
|
* `docker:///example/buildpack:latest`
|
|
* `docker:///example/buildpack@sha256:45b23dee08...`
|
|
* `example/buildpack`
|
|
* `example/buildpack:latest`
|
|
* `example/buildpack@sha256:45b23dee08...`
|
|
|
|
|
|
|
|
[[build-image.examples.publish]]
|
|
=== Image Publishing
|
|
The generated image can be published to a Docker registry by enabling a `publish` option.
|
|
|
|
If the Docker registry requires authentication, the credentials can be configured using `docker.publishRegistry` parameters.
|
|
If the Docker registry does not require authentication, the `docker.publishRegistry` configuration can be omitted.
|
|
|
|
NOTE: The registry that the image will be published to is determined by the registry part of the image name (`docker.example.com` in these examples).
|
|
If `docker.publishRegistry` credentials are configured and include a `url` parameter, this value is passed to the registry but is not used to determine the publishing registry location.
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/docker-pom.xml[tags=docker]
|
|
----
|
|
|
|
The `publish` option 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=docker.example.com/library/my-app:v1 -Dspring-boot.build-image.publish=true
|
|
----
|
|
|
|
When using the `publish` option on the command line with authentication, you can provide credentials using properties as in this example:
|
|
|
|
[indent=0]
|
|
----
|
|
$ mvn spring-boot:build-image \
|
|
-Ddocker.publishRegistry.username=user \
|
|
-Ddocker.publishRegistry.password=secret \
|
|
-Ddocker.publishRegistry.url=docker.example.com \
|
|
-Dspring-boot.build-image.publish=true \
|
|
-Dspring-boot.build-image.imageName=docker.example.com/library/my-app:v1
|
|
----
|
|
|
|
and reference the properties in the XML configuration:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/docker-pom-authentication-command-line.xml[tags=docker]
|
|
----
|
|
|
|
[[build-image.examples.caches]]
|
|
=== Builder Cache and Workspace Configuration
|
|
|
|
The CNB builder caches layers that are used when building and launching an image.
|
|
By default, these caches are stored as named volumes in the Docker daemon with names that are derived from the full name of the target image.
|
|
If the image name changes frequently, for example when the project version is used as a tag in the image name, then the caches can be invalidated frequently.
|
|
|
|
The cache volumes can be configured to use alternative names to give more control over cache lifecycle as shown in the following example:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/caches-pom.xml[tags=caches]
|
|
----
|
|
|
|
Builders and buildpacks need a location to store temporary files during image building.
|
|
By default, this temporary build workspace is stored in a named volume.
|
|
|
|
The caches and the build workspace can be configured to use bind mounts instead of named volumes, as shown in the following example:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/bind-caches-pom.xml[tags=caches]
|
|
----
|
|
|
|
[[build-image.examples.docker]]
|
|
=== Docker Configuration
|
|
|
|
[[build-image.examples.docker.minikube]]
|
|
==== Docker Configuration for minikube
|
|
|
|
The plugin can communicate with the https://minikube.sigs.k8s.io/docs/tasks/docker_daemon/[Docker daemon provided by minikube] instead of the default local connection.
|
|
|
|
On Linux and macOS, environment variables can be set using the command `eval $(minikube docker-env)` after minikube has been started.
|
|
|
|
The plugin can also be configured to use the minikube daemon by providing connection details similar to those shown in the following example:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/docker-minikube-pom.xml[tags=docker-minikube]
|
|
----
|
|
|
|
[[build-image.examples.docker.podman]]
|
|
==== Docker Configuration for podman
|
|
|
|
The plugin can communicate with a https://podman.io/[podman container engine].
|
|
|
|
The plugin can be configured to use podman local connection by providing connection details similar to those shown in the following example:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/docker-podman-pom.xml[tags=docker-podman]
|
|
----
|
|
|
|
TIP: With the `podman` CLI installed, the command `podman info --format='{{.Host.RemoteSocket.Path}}'` can be used to get the value for the `docker.host` configuration property shown in this example.
|
|
|
|
[[build-image.examples.docker.auth]]
|
|
==== Docker Configuration for Authentication
|
|
|
|
If the builder or run image are stored in a private Docker registry that supports user authentication, authentication details can be provided using `docker.builderRegistry` parameters as shown in the following example:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/docker-registry-authentication-pom.xml[tags=docker-registry-authentication]
|
|
----
|
|
|
|
If the builder or run image is stored in a private Docker registry that supports token authentication, the token value can be provided using `docker.builderRegistry` parameters as shown in the following example:
|
|
|
|
[source,xml,indent=0,subs="verbatim,attributes",tabsize=4]
|
|
----
|
|
include::../maven/packaging-oci-image/docker-token-authentication-pom.xml[tags=docker-token-authentication]
|
|
----
|