Document builder configuration for HTTP proxy

This commit adds examples for configuring the default builder to use
an HTTP/HTTPS proxy when building OCI images using the Maven or Gradle
plugin.

Fixes gh-19984

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

@@ -33,7 +33,7 @@ On Linux and macOS, these environment variables can be set using the command `ev
 
 
 [[build-image-customization]]
-=== Image Customizations
+=== 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.
@@ -79,7 +79,7 @@ The following table summarizes the available properties and their default values
 
 
 [[build-image-example-custom-image-builder]]
-==== 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"]
@@ -96,7 +96,14 @@ 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:
+
+
+[[build-image-example-builder-configuration]]
+==== Builder configuration
+
+If the builder exposes configuration options, those can be set using the `environment` property.
+
+The following example assumes that the default builder defines a `BP_JAVA_VERSION` property (typically used to customize the JDK version the image should use):
 
 [source,groovy,indent=0,subs="verbatim,attributes",role="primary"]
 .Groovy
@@ -110,12 +117,25 @@ include::../gradle/packaging/boot-build-image-env.gradle[tags=env]
 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).
+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,groovy,indent=0,subs="verbatim,attributes",role="primary"]
+.Groovy
+----
+include::../gradle/packaging/boot-build-image-env-proxy.gradle[tags=env]
+----
+
+[source,kotlin,indent=0,subs="verbatim,attributes",role="secondary"]
+.Kotlin
+----
+include::../gradle/packaging/boot-build-image-env-proxy.gradle.kts[tags=env]
+----
 
 
 
 [[build-image-example-custom-image-name]]
-==== 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:
 

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

@@ -0,0 +1,17 @@
+plugins {
+	id 'java'
+	id 'org.springframework.boot' version '{version}'
+}
+
+bootJar {
+	mainClassName 'com.example.ExampleApplication'
+}
+
+// tag::env[]
+bootBuildImage {
+	environment = [
+			"HTTP_PROXY" : "http://proxy.example.com",
+			"HTTPS_PROXY": "https://proxy.example.com"
+	]
+}
+// end::env[]

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

@@ -0,0 +1,19 @@
+import org.springframework.boot.gradle.tasks.bundling.BootJar
+
+plugins {
+	java
+	id("org.springframework.boot") version "{version}"
+}
+
+tasks.getByName<BootJar>("bootJar") {
+	mainClassName = "com.example.ExampleApplication"
+}
+
+// tag::env[]
+tasks.getByName<BootBuildImage>("bootBuildImage") {
+	environment = [
+		"HTTP_PROXY" : "http://proxy.example.com",
+		"HTTPS_PROXY" : "https://proxy.example.com"
+	]
+}
+// end::env[]

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

@@ -1,5 +1,5 @@
 [[build-image]]
-== Packaging OCI Images
+== 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.
 
@@ -58,7 +58,7 @@ On Linux and macOS, these environment variables can be set using the command `ev
 
 
 [[build-image-customization]]
-=== Image Customizations
+=== 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.
@@ -108,7 +108,7 @@ include::goals/build-image.adoc[leveloffset=+1]
 
 
 [[build-image-example-custom-image-builder]]
-==== 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"]
@@ -140,7 +140,11 @@ The builder can be specified on the command line as well, as shown in this examp
 	$ mvn spring-boot:build-image -Dspring-boot.build-image:builder=mine/java-cnb-builder
 ----
 
-If the builder exposes configuration options, those can be set using the `env` attributes, as shown in the following example:
+[[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_JAVA_VERSION` property (typically used to customize the JDK version the image should use):
 
 [source,xml,indent=0,subs="verbatim,attributes"]
 ----
@@ -153,7 +157,6 @@ If the builder exposes configuration options, those can be set using the `env` a
 					<version>{gradle-project-version}</version>
 					<configuration>
 						<image>
-							<builder>mine/java-cnb-builder</builder>
 							<env>
 								<BP_JAVA_VERSION>13.0.1</BP_JAVA_VERSION>
 							</env>
@@ -165,12 +168,36 @@ If the builder exposes configuration options, those can be set using the `env` a
 	</project>
 ----
 
-The example above assumes that `mine/java-cnb-builder` defines a `BP_JAVA_VERSION` property (typically used to customize the JDK version the image should use).
+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
+==== 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: