对于最新的稳定版本,请使用 Spring Boot 3.5.5spring-doc.cadn.net.cn

打包 OCI 映像

该插件可以使用云原生 Buildpack (CNB) 从 jar 或 war 文件创建 OCI 映像。 可以使用bootBuildImage任务。spring-doc.cadn.net.cn

出于安全原因,镜像以非 root 用户身份构建和运行。 有关更多详细信息,请参阅 CNB 规范

javawarplugin 被应用,并且是BootBuildImage.spring-doc.cadn.net.cn

Docker 守护进程

bootBuildImage任务需要访问 Docker 守护进程。 该任务将检查本地 Docker CLI 配置文件以确定当前上下文,并使用上下文连接信息与 Docker 守护进程进行通信。 如果无法确定当前上下文或上下文没有连接信息,则任务将使用默认的本地连接。 这适用于所有受支持平台上的 Docker 引擎,无需配置。spring-doc.cadn.net.cn

可以设置环境变量来配置bootBuildImage任务以使用备用的本地或远程连接。 下表显示了环境变量及其值:spring-doc.cadn.net.cn

环境变量 描述

DOCKER_CONFIGspring-doc.cadn.net.cn

用于确定当前上下文的 Docker CLI 配置文件的位置(默认为$HOME/.docker)spring-doc.cadn.net.cn

DOCKER_CONTEXTspring-doc.cadn.net.cn

应用于从 Docker CLI 配置文件中检索主机信息的上下文的名称(覆盖DOCKER_HOST)spring-doc.cadn.net.cn

DOCKER_HOSTspring-doc.cadn.net.cn

包含 Docker 守护程序的主机和端口的 URL - 例如tcp://192.168.99.100:2376spring-doc.cadn.net.cn

DOCKER_TLS_VERIFYspring-doc.cadn.net.cn

启用安全 HTTPS 协议 设置为1(可选)spring-doc.cadn.net.cn

DOCKER_CERT_PATHspring-doc.cadn.net.cn

HTTPS 的证书和密钥文件的路径(如果DOCKER_TLS_VERIFY=1,否则忽略)spring-doc.cadn.net.cn

Docker 守护进程连接信息也可以使用docker插件配置中的属性。 下表汇总了可用的属性:spring-doc.cadn.net.cn

属性 描述

contextspring-doc.cadn.net.cn

应用于从 Docker CLI 配置文件中检索主机信息的上下文的名称spring-doc.cadn.net.cn

hostspring-doc.cadn.net.cn

包含 Docker 守护程序的主机和端口的 URL - 例如tcp://192.168.99.100:2376spring-doc.cadn.net.cn

tlsVerifyspring-doc.cadn.net.cn

启用安全 HTTPS 协议 设置为true(可选)spring-doc.cadn.net.cn

certPathspring-doc.cadn.net.cn

HTTPS 的证书和密钥文件的路径(如果tlsVerifytrue,否则忽略)spring-doc.cadn.net.cn

bindHostToBuilderspring-doc.cadn.net.cn

什么时候true,则host属性将提供给为 CNB 构建器创建的容器(可选)spring-doc.cadn.net.cn

有关更多详细信息,另请参阅示例spring-doc.cadn.net.cn

Docker 注册表

如果 Docker 镜像由builderrunImage属性存储在需要身份验证的私有 Docker 镜像注册表中,可以使用docker.builderRegistry性能。spring-doc.cadn.net.cn

如果要将生成的 Docker 镜像发布到 Docker 镜像注册表,则可以使用docker.publishRegistry性能。spring-doc.cadn.net.cn

为用户身份验证或身份Tokens身份验证提供属性。 有关支持的身份验证方法的更多信息,请参阅用于存储映像的 Docker 注册表的文档。spring-doc.cadn.net.cn

下表汇总了docker.builderRegistrydocker.publishRegistry:spring-doc.cadn.net.cn

属性 描述

usernamespring-doc.cadn.net.cn

Docker 映像注册表用户的用户名。用户身份验证所必需的。spring-doc.cadn.net.cn

passwordspring-doc.cadn.net.cn

Docker 映像注册表用户的密码。用户身份验证所必需的。spring-doc.cadn.net.cn

urlspring-doc.cadn.net.cn

Docker 镜像注册表的地址。用户身份验证可选。spring-doc.cadn.net.cn

emailspring-doc.cadn.net.cn

Docker 映像注册表用户的电子邮件地址。用户身份验证可选。spring-doc.cadn.net.cn

tokenspring-doc.cadn.net.cn

Docker 映像注册表用户的标识Tokens。Tokens身份验证所必需的。spring-doc.cadn.net.cn

有关更多详细信息,另请参阅示例spring-doc.cadn.net.cn

图像自定义

该插件调用构建器来编排图像的生成。 构建器包括多个构建包,可以检查应用程序以影响生成的映像。 默认情况下,插件会选择构建器映像。 生成的图像的名称是从项目属性中推断出来的。spring-doc.cadn.net.cn

任务属性可用于配置构建器应如何对项目进行作。 下表汇总了可用属性及其默认值:spring-doc.cadn.net.cn

属性 命令行选项 描述 默认值

builderspring-doc.cadn.net.cn

--builderspring-doc.cadn.net.cn

要使用的构建器映像的名称。spring-doc.cadn.net.cn

paketobuildpacks/builder-jammy-java-tiny:latestspring-doc.cadn.net.cn

trustBuilderspring-doc.cadn.net.cn

--trustBuilderspring-doc.cadn.net.cn

是否将构建者视为受信任的spring-doc.cadn.net.cn

true如果构建者是paketobuildpacks/builder-jammy-java-tiny,paketobuildpacks/builder-noble-java-tiny,paketobuildpacks/builder-jammy-tiny,paketobuildpacks/builder-jammy-base,paketobuildpacks/builder-jammy-full,paketobuildpacks/builder-jammy-buildpackless-tiny,paketobuildpacks/builder-jammy-buildpackless-base,paketobuildpacks/builder-jammy-buildpackless-full,gcr.io/buildpacks/builder,heroku/builder; false否则。spring-doc.cadn.net.cn

imagePlatformspring-doc.cadn.net.cn

--imagePlatformspring-doc.cadn.net.cn

拉取的任何构建器、运行和构建包映像的平台(作系统和体系结构)。 必须采用OS[/architecture[/variant]]linux/amd64,linux/arm64linux/arm/v5. 请参阅用于确定可用映像作系统和体系结构选项的构建器的文档。spring-doc.cadn.net.cn

无默认值,表示应使用主机的平台。spring-doc.cadn.net.cn

runImagespring-doc.cadn.net.cn

--runImagespring-doc.cadn.net.cn

要使用的运行映像的名称。spring-doc.cadn.net.cn

没有默认值,表示应使用构建器元数据中指定的运行映像。spring-doc.cadn.net.cn

imageNamespring-doc.cadn.net.cn

--imageNamespring-doc.cadn.net.cn

生成的图像的图像名称spring-doc.cadn.net.cn

docker.io/library/${project.name}:${project.version}spring-doc.cadn.net.cn

pullPolicyspring-doc.cadn.net.cn

--pullPolicyspring-doc.cadn.net.cn

用于确定何时从注册表中拉取构建器和运行映像的策略。 可接受的值是ALWAYS,NEVERIF_NOT_PRESENT.spring-doc.cadn.net.cn

ALWAYSspring-doc.cadn.net.cn

environmentspring-doc.cadn.net.cn

应传递给构建器的环境变量。spring-doc.cadn.net.cn

空。spring-doc.cadn.net.cn

buildpacksspring-doc.cadn.net.cn

构建器在构建映像时应使用的构建包。 将仅使用指定的 buildpack,覆盖构建器中包含的默认 buildpack。 Buildpack 引用必须采用以下形式之一:spring-doc.cadn.net.cn

None,表示构建器应使用其中包含的构建包。spring-doc.cadn.net.cn

bindingsspring-doc.cadn.net.cn

在生成映像时应装载到构建器容器的卷绑定挂载。 创建构建器容器时,绑定将未经解析和验证传递给 Docker。 绑定必须采用以下形式之一:spring-doc.cadn.net.cn

哪里<options>可以包含:spring-doc.cadn.net.cn

networkspring-doc.cadn.net.cn

--networkspring-doc.cadn.net.cn

构建器容器将配置为使用的网络驱动程序。 在创建构建器容器时,提供的值将未经验证地传递给 Docker。spring-doc.cadn.net.cn

cleanCachespring-doc.cadn.net.cn

--cleanCachespring-doc.cadn.net.cn

是否在构建前清理缓存。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

verboseLoggingspring-doc.cadn.net.cn

启用构建器作的详细日志记录。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

publishspring-doc.cadn.net.cn

--publishImagespring-doc.cadn.net.cn

是否将生成的镜像发布到 Docker 注册表。spring-doc.cadn.net.cn

falsespring-doc.cadn.net.cn

tagsspring-doc.cadn.net.cn

要应用于生成图像的一个或多个附加标记的列表。 提供给tags选项应该是完整的图像引用。 有关更多详细信息,请参阅标签部分spring-doc.cadn.net.cn

buildWorkspacespring-doc.cadn.net.cn

构建器和构建包将用于在映像构建期间存储文件的临时工作区。 该值可以是命名卷或绑定挂载位置。spring-doc.cadn.net.cn

Docker 守护程序中的命名卷,其名称派生自映像名称。spring-doc.cadn.net.cn

buildCachespring-doc.cadn.net.cn

包含由 buildpack 创建并由映像构建过程使用的层的缓存。 该值可以是命名卷或绑定挂载位置。spring-doc.cadn.net.cn

Docker 守护程序中的命名卷,其名称派生自映像名称。spring-doc.cadn.net.cn

launchCachespring-doc.cadn.net.cn

包含由 buildpack 创建并由映像启动过程使用的层的缓存。 该值可以是命名卷或绑定挂载位置。spring-doc.cadn.net.cn

Docker 守护程序中的命名卷,其名称派生自映像名称。spring-doc.cadn.net.cn

createdDatespring-doc.cadn.net.cn

--createdDatespring-doc.cadn.net.cn

将用于设置Created字段。 该值必须是 ISO 8601 即时格式的字符串,或者now以使用当前日期和时间。spring-doc.cadn.net.cn

实现生成可重现性的固定日期。spring-doc.cadn.net.cn

applicationDirectoryspring-doc.cadn.net.cn

--applicationDirectoryspring-doc.cadn.net.cn

应用程序内容将在构建器映像中上传到的目录的路径。 应用程序内容也将位于生成图像中的此位置。spring-doc.cadn.net.cn

/workspacespring-doc.cadn.net.cn

securityOptionsspring-doc.cadn.net.cn

--securityOptionsspring-doc.cadn.net.cn

将应用于构建器容器的安全选项,作为字符串值数组提供spring-doc.cadn.net.cn

["label=disable"]在 Linux 和 macOS 上,在 Windows 上[]spring-doc.cadn.net.cn

该插件使用 JavaPlugin 的targetCompatibility财产。 当使用默认的 Paketo 构建器和构建包时,该插件会指示构建包安装相同的 Java 版本。 您可以覆盖此行为,如构建器配置示例所示。
默认构建器paketobuildpacks/builder-jammy-java-tiny:latest包含一组缩减的系统库,并且不包括 shell。 需要 shell 来运行启动脚本的应用程序,就像application插件已应用于生成分发 zip 存档,或者依赖于不存在的系统库,则应覆盖builder配置以使用包含 shell 和更广泛的系统库集的库,例如paketobuildpacks/builder-jammy-base:latestpaketobuildpacks/builder-jammy-full:latest.

标签格式

提供给tags选项应该是完整的图像引用。 接受的格式是[domainHost:port/][path/]name[:tag][@digest].spring-doc.cadn.net.cn

如果缺少域,则默认为docker.io. 如果缺少路径,则默认为library. 如果缺少标记,则默认为latest.spring-doc.cadn.net.cn

一些例子:spring-doc.cadn.net.cn

例子

自定义映像生成器和运行映像

如果需要自定义用于创建映像的构建器或用于启动构建的映像的运行映像,请配置任务,如以下示例所示:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	builder = "mine/java-cnb-builder"
	runImage = "mine/java-cnb-run"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	builder.set("mine/java-cnb-builder")
	runImage.set("mine/java-cnb-run")
}

此配置将使用名为mine/java-cnb-builder和标签latest,运行映像名为mine/java-cnb-run和标签latest.spring-doc.cadn.net.cn

构建器和运行映像也可以在命令行上指定,如以下示例所示:spring-doc.cadn.net.cn

$ gradle bootBuildImage --builder=mine/java-cnb-builder --runImage=mine/java-cnb-run

构建器配置

如果构建器公开配置选项,则可以使用environment财产。spring-doc.cadn.net.cn

以下是在构建时配置 Paketo Java 构建包使用的 JVM 版本的示例:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	environment["BP_JVM_VERSION"] = "17"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	environment.put("BP_JVM_VERSION", "17")
}

如果构建器运行的 Docker 守护程序与构建包从中下载工件的网络位置之间存在网络代理,则需要将构建器配置为使用该代理。使用 Paketo 构建器时,这可以通过将HTTPS_PROXY和/或HTTP_PROXY环境变量,如以下示例所示:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	environment["HTTP_PROXY"] = "http://proxy.example.com"
	environment["HTTPS_PROXY"] = "https://proxy.example.com"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	environment.putAll(mapOf("HTTP_PROXY" to "http://proxy.example.com",
						"HTTPS_PROXY" to "https://proxy.example.com"))
}

运行时 JVM 配置

Paketo Java 构建包通过设置JAVA_TOOL_OPTIONS环境变量。 buildpack-providedJAVA_TOOL_OPTIONS可以修改值,以自定义在容器中启动应用程序映像时的 JVM 运行时行为。spring-doc.cadn.net.cn

应存储在映像中并应用于每个部署的环境变量修改可以按照 Paketo 文档中的说明进行设置,并如以下示例所示:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	environment["BPE_DELIM_JAVA_TOOL_OPTIONS"] = " "
	environment["BPE_APPEND_JAVA_TOOL_OPTIONS"] = "-XX:+HeapDumpOnOutOfMemoryError"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	environment.putAll(mapOf(
		"BPE_DELIM_JAVA_TOOL_OPTIONS" to " ",
		"BPE_APPEND_JAVA_TOOL_OPTIONS" to "-XX:+HeapDumpOnOutOfMemoryError"
	))
}

自定义映像名称

默认情况下,图像名称是从nameversion项目的,类似于docker.io/library/${project.name}:${project.version}. 您可以通过设置任务属性来控制名称,如以下示例所示:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	imageName = "example.com/library/${project.name}"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	imageName.set("example.com/library/${project.name}")
}

请注意,此配置不提供显式标记,因此latest被使用。也可以指定标签,使用${project.version}、生成中可用的任何属性或硬编码版本。spring-doc.cadn.net.cn

也可以在命令行上指定图像名称,如以下示例所示:spring-doc.cadn.net.cn

$ gradle bootBuildImage --imageName=example.com/library/my-app:v1

构建包

默认情况下,构建器将使用构建器映像中包含的构建包,并按预定义的顺序应用它们。可以提供一组替代的构建包来应用构建器中未包含的构建包,或更改包含的构建包的顺序。当提供一个或多个构建包时,将仅应用指定的构建包。spring-doc.cadn.net.cn

以下示例指示构建器使用打包在.tgz文件,后跟构建器中包含的 buildpack。spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	buildpacks = ["file:///path/to/example-buildpack.tgz", "urn:cnb:builder:paketo-buildpacks/java"]
}
tasks.named<BootBuildImage>("bootBuildImage") {
	buildpacks.set(listOf("file:///path/to/example-buildpack.tgz", "urn:cnb:builder:paketo-buildpacks/java"))
}

构建包可以以如下所示的任何形式指定。spring-doc.cadn.net.cn

位于 CNB Builder 中的 buildpack(如果构建器中只有一个 buildpack 与buildpack-id):spring-doc.cadn.net.cn

包含 buildpack 内容的目录的路径(Windows 不支持):spring-doc.cadn.net.cn

包含 buildpack 内容的 gzip 压缩 tar 文件的路径:spring-doc.cadn.net.cn

包含打包构建包的 OCI 映像:spring-doc.cadn.net.cn

图片发布

生成的映像可以通过启用publish选择。spring-doc.cadn.net.cn

如果 Docker 注册表需要身份验证,则可以使用docker.publishRegistry性能。 如果 Docker 注册表不需要身份验证,则docker.publishRegistry配置可以省略。spring-doc.cadn.net.cn

映像将发布到的注册表由映像名称的注册表部分 (docker.example.com在这些示例中)。 如果docker.publishRegistry凭据已配置并包含url属性,则此值将传递到注册表,但不用于确定发布注册表位置。
tasks.named("bootBuildImage") {
	imageName.set("docker.example.com/library/${project.name}")
	publish = true
	docker {
		publishRegistry {
			username = "user"
			password = "secret"
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	imageName.set("docker.example.com/library/${project.name}")
	publish.set(true)
	docker {
		publishRegistry {
			username.set("user")
			password.set("secret")
		}
	}
}

也可以在命令行上指定发布选项,如以下示例所示:spring-doc.cadn.net.cn

$ gradle bootBuildImage --imageName=docker.example.com/library/my-app:v1 --publishImage

构建器缓存和工作区配置

CNB 构建器缓存构建和启动映像时使用的层。 默认情况下,这些缓存作为命名卷存储在 Docker 守护程序中,其名称派生自目标映像的全名。 如果镜像名称频繁更改,例如,当项目版本用作镜像名称中的标签时,缓存可能会频繁失效。spring-doc.cadn.net.cn

可以将缓存卷配置为使用备用名称,以更好地控制缓存生命周期,如以下示例所示:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	buildCache {
		volume {
			name = "cache-${rootProject.name}.build"
		}
	}
	launchCache {
		volume {
			name = "cache-${rootProject.name}.launch"
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	buildCache {
		volume {
			name.set("cache-${rootProject.name}.build")
		}
	}
	launchCache {
		volume {
			name.set("cache-${rootProject.name}.launch")
		}
	}
}

构建器和构建包需要一个位置来存储映像构建期间的临时文件。 默认情况下,此临时生成工作区存储在命名卷中。spring-doc.cadn.net.cn

缓存和构建工作区可以配置为使用绑定挂载而不是命名卷,如以下示例所示:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	buildWorkspace {
		bind {
			source = "/tmp/cache-${rootProject.name}.work"
		}
	}
	buildCache {
		bind {
			source = "/tmp/cache-${rootProject.name}.build"
		}
	}
	launchCache {
		bind {
			source = "/tmp/cache-${rootProject.name}.launch"
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	buildWorkspace {
		bind {
			source.set("/tmp/cache-${rootProject.name}.work")
		}
	}
	buildCache {
		bind {
			source.set("/tmp/cache-${rootProject.name}.build")
		}
	}
	launchCache {
		bind {
			source.set("/tmp/cache-${rootProject.name}.launch")
		}
	}
}

Docker 配置

minikube 的 Docker 配置

该插件可以与 minikube 提供的 Docker 守护进程进行通信,而不是默认的本地连接。spring-doc.cadn.net.cn

在 Linux 和 macOS 上,可以使用命令eval $(minikube docker-env)minikube 启动后。spring-doc.cadn.net.cn

该插件还可以通过提供类似于以下示例中所示的连接详细信息来配置为 minikube 守护进程:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	docker {
		host = "tcp://192.168.99.100:2376"
		tlsVerify = true
		certPath = "/home/user/.minikube/certs"
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		host.set("tcp://192.168.99.100:2376")
		tlsVerify.set(true)
		certPath.set("/home/user/.minikube/certs")
	}
}

podman 的 Docker 配置

该插件可以与 podman 容器引擎通信。spring-doc.cadn.net.cn

可以通过提供类似于以下示例中所示的连接详细信息,将插件配置为使用 podman 本地连接:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	docker {
		host = "unix:///run/user/1000/podman/podman.sock"
		bindHostToBuilder = true
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		host.set("unix:///run/user/1000/podman/podman.sock")
		bindHostToBuilder.set(true)
	}
}
使用podmanCLI 安装时,命令podman info --format='{{.Host.RemoteSocket.Path}}'可用于获取docker.host此示例中显示的 configuration 属性。

Colima 的 Docker 配置

该插件可以与 Colima 提供的 Docker 守护进程进行通信。 这DOCKER_HOST可以使用以下命令设置环境变量:spring-doc.cadn.net.cn

$ export DOCKER_HOST=$(docker context inspect colima -f '{{.Endpoints.docker.Host}}')

还可以通过提供类似于以下示例中所示的连接详细信息来将插件配置为使用 Colima 守护程序:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	docker {
		host = "unix://${System.properties['user.home']}/.colima/docker.sock"
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		host.set("unix://${System.getProperty("user.home")}/.colima/docker.sock")
	}
}

用于身份验证的 Docker 配置

如果构建器或运行映像存储在支持用户身份验证的私有 Docker 注册表中,则可以使用docker.builderRegistry属性,如以下示例所示:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	docker {
		builderRegistry {
			username = "user"
			password = "secret"
			url = "https://docker.example.com/v1/"
			email = "[email protected]"
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		builderRegistry {
			username.set("user")
			password.set("secret")
			url.set("https://docker.example.com/v1/")
			email.set("[email protected]")
		}
	}
}

如果构建器或运行镜像存储在支持Tokens身份验证的私有 Docker 注册表中,则可以使用docker.builderRegistry如以下示例所示:spring-doc.cadn.net.cn

tasks.named("bootBuildImage") {
	docker {
		builderRegistry {
			token = "9cbaf023786cd7..."
		}
	}
}
tasks.named<BootBuildImage>("bootBuildImage") {
	docker {
		builderRegistry {
			token.set("9cbaf023786cd7...")
		}
	}
}