diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc index 5c2a75f2425..7e8782676de 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/index.adoc +++ b/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[] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging-oci-image.adoc new file mode 100644 index 00000000000..9567dee86db --- /dev/null +++ b/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. \ No newline at end of file diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging.adoc b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging.adoc index e3c9e580dd2..e3addec7555 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/asciidoc/packaging.adoc +++ b/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`]. diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-builder.gradle b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-builder.gradle new file mode 100644 index 00000000000..481b9f16023 --- /dev/null +++ b/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[] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-builder.gradle.kts b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-builder.gradle.kts new file mode 100644 index 00000000000..ea225bd34bd --- /dev/null +++ b/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") { + mainClassName = "com.example.ExampleApplication" +} + +// tag::builder[] +tasks.getByName("bootBuildImage") { + builder = "mine/java-cnb-builder" +} +// end::builder[] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env.gradle b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env.gradle new file mode 100644 index 00000000000..8a231c81c6b --- /dev/null +++ b/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[] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env.gradle.kts b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-env.gradle.kts new file mode 100644 index 00000000000..774268830ab --- /dev/null +++ b/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") { + mainClassName = "com.example.ExampleApplication" +} + +// tag::env[] +tasks.getByName("bootBuildImage") { + environment = ["BP_JAVA_VERSION" : "13.0.1"] +} +// end::env[] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-name.gradle b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-name.gradle new file mode 100644 index 00000000000..d3f776235d0 --- /dev/null +++ b/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[] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-name.gradle.kts b/spring-boot-project/spring-boot-tools/spring-boot-gradle-plugin/src/docs/gradle/packaging/boot-build-image-name.gradle.kts new file mode 100644 index 00000000000..8ee6fdc6ada --- /dev/null +++ b/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") { + mainClassName = "com.example.ExampleApplication" +} + +// tag::image-name[] +tasks.getByName("bootBuildImage") { + imageName = "example.com/library/${project.artifactId}" +} +// end::image-name[] diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc index d7f5a255c78..79dc734e29d 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/index.adoc @@ -1,5 +1,5 @@ = Spring Boot Maven Plugin Documentation -Stephane Nicoll, Andy Wilkinson +Stephane Nicoll, Andy Wilkinson, Scott Frederick :doctype: book :toc: left :toclevels: 4 diff --git a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc index 29427438167..06d8ae62f7e 100644 --- a/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc +++ b/spring-boot-project/spring-boot-tools/spring-boot-maven-plugin/src/docs/asciidoc/packaging-oci-image.adoc @@ -1,7 +1,7 @@ [[build-image]] == Packaging OCI Images -The plugin can create https://github.com/opencontainers/image-spec[OCI images] using a https://buildpacks.io/[buildpack]. +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 and a local Docker installation. 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 org.springframework.boot spring-boot-maven-plugin - {version} + {gradle-project-version} @@ -32,7 +32,11 @@ When the `build-image` repackages the application, it applies the same settings [[build-image-customization]] === Image Customizations -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. +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 properties and their default values: @@ -40,15 +44,15 @@ The following table summarizes the available properties and their default values | Property | Description | Default value | `builder` -| {buildpacks-reference}/concepts/components/builder/[Builder image] name to use. +| Name of the Builder image to use. | `cloudfoundry/cnb:0.0.43-bionic` | `name` -| {spring-boot-api}/buildpack/platform/docker/type/ImageReference.html#of-java.lang.String-[Image name]. +| {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}` | `env` -| Environment properties that should be passed to the builder. +| Environment variables that should be passed to the builder. | | `cleanCache` @@ -56,7 +60,7 @@ The following table summarizes the available properties and their default values | `false` | `verboseLogging` -| Whether verbose logging is required. +| Enables verbose logging of builder operations. | `false` |=== @@ -81,7 +85,7 @@ If you need to customize the builder used to create the image, configure yours a org.springframework.boot spring-boot-maven-plugin - {version} + {gradle-project-version} mine/java-cnb-builder @@ -93,7 +97,7 @@ If you need to customize the builder used to create the image, configure yours a ---- -This configuration will use the `latest` version of the `mine/java-cnb-builder` 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 `env` attributes, as shown in the following example: @@ -105,7 +109,7 @@ If the builder exposes configuration options, those can be set using the `env` a org.springframework.boot spring-boot-maven-plugin - {version} + {gradle-project-version} mine/java-cnb-builder @@ -126,7 +130,7 @@ The example above assumes that `mine/java-cnb-builder` defines a `BP_JAVA_VERSIO [[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}`. +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"] @@ -137,7 +141,7 @@ You can take control over the name, as shown in the following example: org.springframework.boot spring-boot-maven-plugin - {version} + {gradle-project-version} example.com/library/${project.artifactId} @@ -149,5 +153,5 @@ You can take control over the name, as shown in the following example: ---- -Note that this configuration does not provide an explicit version so `latest` is used. -It is possible to specify a version as well, either using `${project.version}`, any property available in the build or an hardcoded version. \ No newline at end of file +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. \ No newline at end of file