此版本仍在开发中,尚未被视为稳定版本。对于最新的稳定版本,请使用 Spring Boot 3.4.0! |
打包 OCI 映像
该插件可以使用 Cloud Native Buildpacks (CNB) 从 jar 或 war 文件创建 OCI 映像。
可以使用bootBuildImage
任务。
出于安全原因,映像以非 root 用户身份构建和运行。 有关更多详细信息,请参阅 CNB 规范。 |
当java
或war
plugin 的实例,并且是BootBuildImage
.
Docker 守护程序
这bootBuildImage
任务需要访问 Docker 守护程序。
该任务将检查本地 Docker CLI 配置文件以确定当前上下文,并使用上下文连接信息与 Docker 守护程序通信。
如果无法确定当前上下文或上下文没有连接信息,则任务将使用默认的本地连接。
这适用于所有受支持的平台上的 Docker Engine,无需配置。
可以设置环境变量来配置bootBuildImage
task 使用备用本地或远程连接。
下表显示了环境变量及其值:
环境变量 | 描述 |
---|---|
DOCKER_CONFIG |
用于确定当前上下文的 Docker CLI 配置文件的位置(默认为 |
DOCKER_CONTEXT |
应该用于从 Docker CLI 配置文件中检索主机信息的上下文的名称(覆盖 |
DOCKER_HOST |
包含 Docker 守护程序的主机和端口的 URL - 例如 |
DOCKER_TLS_VERIFY |
启用安全 HTTPS 协议(当设置为 |
DOCKER_CERT_PATH |
HTTPS 的证书和密钥文件的路径(如果满足以下条件,则需要 |
Docker 守护进程连接信息也可以使用docker
属性。
下表总结了可用的属性:
财产 | 描述 |
---|---|
|
|
|
包含 Docker 守护程序的主机和端口的 URL - 例如 |
|
启用安全 HTTPS 协议(当设置为 |
|
HTTPS 的证书和密钥文件的路径(如果满足以下条件,则需要 |
|
什么时候 |
有关更多详细信息,另请参阅示例。
Docker 注册表
如果builder
或runImage
属性存储在需要身份验证的私有 Docker 镜像注册表中,可以使用docker.builderRegistry
性能。
如果要将生成的 Docker 镜像发布到 Docker 镜像注册表,则可以使用docker.publishRegistry
性能。
提供了用于用户身份验证或身份令牌身份验证的属性。 有关支持的身份验证方法的更多信息,请参阅用于存储映像的 Docker 注册表的文档。
下表总结了docker.builderRegistry
和docker.publishRegistry
:
财产 | 描述 |
---|---|
|
Docker 镜像注册表用户的用户名。用户身份验证是必需的。 |
|
Docker 镜像注册表用户的密码。用户身份验证是必需的。 |
|
Docker 镜像注册表的地址。对于用户身份验证,可选。 |
|
Docker 镜像注册表用户的电子邮件地址。对于用户身份验证,可选。 |
|
Docker 镜像注册表用户的身份令牌。令牌身份验证是必需的。 |
有关更多详细信息,另请参阅示例。
图像自定义
该插件调用构建器来编排映像的生成。 构建器包含多个 buildpack,这些 buildpack 可以检查应用程序以影响生成的映像。 默认情况下,插件会选择一个构建器镜像。 生成的映像的名称是从项目属性中推导出来的。
任务属性可用于配置生成器应如何作项目。 下表总结了可用属性及其默认值:
财产 | 命令行选项 | 描述 | 默认值 |
---|---|---|---|
|
|
要使用的 Builder 映像的名称。 |
|
|
|
要使用的运行映像的名称。 |
无默认值,指示应使用生成器元数据中指定的运行映像。 |
|
|
生成的镜像的镜像名称。 |
|
|
|
用于确定何时从注册表中提取生成器和运行镜像的策略。
可接受的值为 |
|
|
应传递给生成器的环境变量。 |
Empty 或 |
|
|
构建者在构建镜像时应使用的 Buildpack。 将仅使用指定的 buildpack,覆盖构建器中包含的默认 buildpack。 Buildpack 引用必须采用以下形式之一:
|
None,表示构建器应使用其中包含的 buildpack。 |
|
|
在构建镜像时应挂载到构建器容器的卷绑定挂载。 在创建构建器容器时,绑定将未经解析和验证地传递给 Docker。 绑定必须采用以下形式之一:
哪里
|
||
|
|
生成器容器将配置为使用的网络驱动程序。 在创建生成器容器时,提供的值将在未经验证的情况下传递给 Docker。 |
|
|
|
是否在构建前清理缓存。 |
|
|
启用生成器作的详细日志记录。 |
|
|
|
|
是否将生成的镜像发布到 Docker 注册表。 |
|
|
要应用于生成的图像的一个或多个其他标记的列表。
提供给 |
||
|
一个临时工作区,构建器和 buildpack 将使用它来在映像构建期间存储文件。 该值可以是命名卷或绑定挂载位置。 |
Docker 守护程序中的命名卷,其名称派生自映像名称。 |
|
|
包含由 buildpack 创建并由映像构建过程使用的层的缓存。 该值可以是命名卷或绑定挂载位置。 |
Docker 守护程序中的命名卷,其名称派生自映像名称。 |
|
|
包含由 buildpack 创建并由映像启动进程使用的层的缓存。 该值可以是命名卷或绑定挂载位置。 |
Docker 守护程序中的命名卷,其名称派生自映像名称。 |
|
|
|
将用于设置 |
启用构建可重现性的固定日期。 |
|
|
应用程序内容将在生成器映像中上传到的目录的路径。 应用程序内容也将位于生成的映像中的此位置。 |
|
|
|
将应用于生成器容器的安全选项,以字符串值数组的形式提供 |
|
该插件使用 JavaPlugin 的targetCompatibility 财产。
当使用默认的 Paketo 构建器和 buildpack 时,该插件会指示 buildpack 安装相同的 Java 版本。
您可以覆盖此行为,如 builder 配置示例所示。 |
标签格式
提供给tags
选项应为完整图像引用。
接受的格式为[domainHost:port/][path/]name[:tag][@digest]
.
如果缺少域,则默认为docker.io
.
如果缺少路径,则默认为library
.
如果缺少标签,则默认为latest
.
一些例子:
-
my-image
指向图像引用docker.io/library/my-image:latest
-
my-repository/my-image
导致docker.io/my-repository/my-image:latest
-
example.com/my-repository/my-image:1.0.0
将按原样使用
例子
自定义映像生成器和运行映像
如果您需要自定义用于创建映像的生成器或用于启动构建映像的运行映像,请配置任务,如以下示例所示:
-
Groovy
-
Kotlin
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
.
也可以在命令行上指定 builder 和 run image,如以下示例所示:
$ gradle bootBuildImage --builder=mine/java-cnb-builder --runImage=mine/java-cnb-run
Builder 配置
如果构建器公开了配置选项,则可以使用environment
财产。
以下是在构建时配置 Paketo Java buildpack 使用的 JVM 版本的示例:
-
Groovy
-
Kotlin
tasks.named("bootBuildImage") {
environment["BP_JVM_VERSION"] = "17"
}
tasks.named<BootBuildImage>("bootBuildImage") {
environment.put("BP_JVM_VERSION", "17")
}
如果构建器运行的 Docker 守护进程与 buildpack 下载工件的网络位置之间存在网络代理,则需要将构建器配置为使用该代理。
使用 Paketo 构建器时,可以通过设置HTTPS_PROXY
和/或HTTP_PROXY
环境变量,如以下示例所示:
-
Groovy
-
Kotlin
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 buildpack 通过设置JAVA_TOOL_OPTIONS
环境变量。
buildpack 提供的JAVA_TOOL_OPTIONS
值,以自定义在容器中启动应用程序映像时的 JVM 运行时行为。
应存储在映像中并应用于每个部署的环境变量修改可以按照 Paketo 文档中所述进行设置,如以下示例所示:
-
Groovy
-
Kotlin
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"
))
}
自定义镜像名称
默认情况下,镜像名称是从name
和version
中,类似于docker.io/library/${project.name}:${project.version}
.
您可以通过设置任务属性来控制名称,如以下示例所示:
-
Groovy
-
Kotlin
tasks.named("bootBuildImage") {
imageName = "example.com/library/${project.name}"
}
tasks.named<BootBuildImage>("bootBuildImage") {
imageName.set("example.com/library/${project.name}")
}
请注意,此配置不提供显式标记,因此latest
被使用。
也可以指定标签,使用${project.version}
、内部版本或硬编码版本中可用的任何属性。
也可以在命令行上指定映像名称,如以下示例所示:
$ gradle bootBuildImage --imageName=example.com/library/my-app:v1
构建包
默认情况下,构建器将使用构建器镜像中包含的 buildpack,并按预定义的顺序应用它们。 可以提供一组替代的 buildpack 来应用未包含在构建器中的 buildpack,或更改包含的 buildpack 的顺序。 当提供一个或多个 buildpack 时,将仅应用指定的 buildpack。
以下示例指示构建器使用打包在.tgz
文件,后跟构建器中包含的 buildpack。
-
Groovy
-
Kotlin
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"))
}
Buildpack 可以采用下面显示的任何形式指定。
位于 CNB Builder 中的 buildpack(如果构建器中只有一个 buildpack 与buildpack-id
):
-
urn:cnb:builder:buildpack-id
-
urn:cnb:builder:[email protected]
-
buildpack-id
包含 buildpack 内容的目录的路径(在 Windows 上不受支持):
-
file:///path/to/buildpack/
-
/path/to/buildpack/
包含 buildpack 内容的 gzip 压缩 tar 文件的路径:
-
file:///path/to/buildpack.tgz
-
/path/to/buildpack.tgz
包含打包的 buildpack 的 OCI 映像:
-
docker://example/buildpack
-
docker:///example/buildpack:latest
-
docker:///example/buildpack@sha256:45b23dee08…
-
example/buildpack
-
example/buildpack:latest
-
example/buildpack@sha256:45b23dee08…
图像发布
生成的镜像可以通过启用publish
选择。
如果 Docker 注册表需要身份验证,则可以使用docker.publishRegistry
性能。
如果 Docker 注册表不需要身份验证,则docker.publishRegistry
configuration 可以省略。
映像将发布到的注册表由映像名称的注册表部分 (docker.example.com 在这些例子中)。
如果docker.publishRegistry 凭证已配置并包括url 属性,此值将传递给 Registry,但不用于确定发布 Registry 位置。 |
-
Groovy
-
Kotlin
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")
}
}
}
也可以在命令行上指定 publish 选项,如以下示例所示:
$ gradle bootBuildImage --imageName=docker.example.com/library/my-app:v1 --publishImage
Builder 缓存和工作区配置
CNB 构建器缓存构建和启动映像时使用的层。 默认情况下,这些缓存作为命名卷存储在 Docker 守护程序中,其名称派生自目标映像的全名。 如果映像名称频繁更改,例如,当项目版本用作映像名称中的标记时,则缓存可能会频繁失效。
缓存卷可以配置为使用备用名称,以便更好地控制缓存生命周期,如以下示例所示:
-
Groovy
-
Kotlin
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")
}
}
}
在映像构建期间,构建器和 buildpack 需要一个位置来存储临时文件。 默认情况下,此临时构建工作区存储在命名卷中。
缓存和构建工作区可以配置为使用绑定挂载而不是命名卷,如以下示例所示:
-
Groovy
-
Kotlin
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 守护进程通信,而不是默认的本地连接。
在 Linux 和 macOS 上,可以使用命令eval $(minikube docker-env)
在 Minikube 启动后。
还可以通过提供类似于以下示例中所示的连接详细信息,将插件配置为使用 minikube 守护进程:
-
Groovy
-
Kotlin
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 容器引擎通信。
通过提供类似于以下示例中所示的连接详细信息,可以将插件配置为使用 podman 本地连接:
-
Groovy
-
Kotlin
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)
}
}
使用podman CLI 安装后,命令podman info --format='{{.Host.RemoteSocket.Path}}' 可用于获取docker.host configuration 属性。 |
Colima 的 Docker 配置
该插件可以与 Colima 提供的 Docker 守护程序通信。
这DOCKER_HOST
可以使用以下命令设置环境变量:
$ export DOCKER_HOST=$(docker context inspect colima -f '{{.Endpoints.docker.Host}}')
还可以通过提供类似于以下示例中所示的连接详细信息,将插件配置为使用 Colima 守护程序:
-
Groovy
-
Kotlin
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
属性,如以下示例所示:
-
Groovy
-
Kotlin
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]")
}
}
}
如果构建器或运行镜像存储在支持令牌身份验证的私有 Docker 注册表中,则可以使用docker.builderRegistry
如以下示例所示:
-
Groovy
-
Kotlin
tasks.named("bootBuildImage") {
docker {
builderRegistry {
token = "9cbaf023786cd7..."
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
builderRegistry {
token.set("9cbaf023786cd7...")
}
}
}