打包 OCI 镜像
| 出于安全原因,图像以非根用户身份构建和运行。 有关更多详细信息,请参阅 CNB 规范。 |
当应用 java 或 war 插件时,该任务会自动创建,并且是 BootBuildImage 的一个实例。
Docker 守护进程
bootBuildImage 任务需要访问 Docker 守护进程。
该任务会检查本地 Docker CLI 配置文件 以确定当前 上下文,并使用上下文的连接信息与 Docker 守护进程进行通信。
如果无法确定当前上下文或上下文没有连接信息,该任务将使用默认的本地连接。
此功能可在所有支持的平台上与 Docker Engine 无需配置即可正常工作。
可以设置环境变量来配置 bootBuildImage 任务,以使用替代的本地或远程连接。
下表显示了这些环境变量及其值:
| 环境变量 | 描述 |
|---|---|
DOCKER_CONFIG |
Docker CLI 的位置 配置文件 用于确定当前上下文(默认为 |
DOCKER_CONTEXT |
一个应从中检索主机信息的 上下文 名称,用于 Docker CLI 配置文件(覆盖 |
DOCKER_HOST |
包含 Docker 守护进程主机和端口的 URL - 例如 |
DOCKER_TLS_VERIFY |
设置为 |
DOCKER_CERT_PATH |
HTTPS 的证书和密钥文件路径(如果为 |
Docker 守护进程的连接信息也可以通过插件配置中的 docker 属性来提供。
下表总结了可用的属性:
| 属性 | 描述 |
|---|---|
|
|
|
包含 Docker 守护进程主机和端口的 URL - 例如 |
|
设置为 |
|
HTTPS 的证书和密钥文件路径(如果 |
|
当 |
有关更多详细信息,请参阅 示例。
Docker 注册表
如果由 builder 或 runImage 属性指定的 Docker 镜像存储在需要身份验证的私有 Docker 镜像注册表中,则可以使用 docker.builderRegistry 属性提供身份验证凭据。
如果要将生成的 Docker 镜像发布到 Docker 镜像仓库,可以使用 docker.publishRegistry 属性提供身份验证凭据。
属性用于用户身份验证或身份Tokens身份验证。 请查阅所使用的Docker仓库的文档,以获取有关支持的身份验证方法的更多信息。
下表总结了 docker.builderRegistry 和 docker.publishRegistry 的可用属性:
| 属性 | 描述 |
|---|---|
|
Docker 镜像仓库用户的用户名。用户身份验证所需。 |
|
Docker 镜像仓库用户的密码。用于用户身份验证,必填。 |
|
Docker 镜像仓库的地址。用于用户身份验证,可选。 |
|
Docker 镜像仓库用户的电子邮件地址。用于用户身份验证时可选。 |
|
Docker 镜像仓库用户的身份Tokens。进行Tokens认证时必需。 |
有关更多详细信息,请参阅 示例。
|
如果未提供凭据,插件将读取用户现有的 Docker 配置文件(通常位于 该插件支持以下身份验证方法:
|
镜像自定义
任务属性可用于配置构建器在项目上的操作方式。 以下表格总结了可用属性及其默认值:
| 属性 | 命令行选项 | 描述 | 默认值 |
|---|---|---|---|
|
|
要使用的构建器镜像名称。 |
|
|
|
是否将构建器视为 可信。 |
|
|
|
所拉取的任意 builder、run 和 buildpack 镜像的平台(操作系统和架构)。
必须采用 |
无默认值,表示应使用宿主机的平台。 |
|
|
要使用的运行镜像名称。 |
无默认值,表示应使用 Builder 元数据中指定的运行镜像。 |
|
|
|
|
|
|
策略 用于确定何时从注册表中拉取构建器和运行镜像。
可接受的值为 |
|
|
应传递给构建器的环境变量。 |
Empty. |
|
|
构建镜像时,builder 应该使用的 Buildpack。 只有指定的 Buildpack 会被使用,覆盖 builder 中包含的默认 Buildpack。 Buildpack 的引用必须采用以下形式之一:
|
无,表示构建器应使用其中包含的 buildpacks。 |
|
|
卷绑定挂载 在构建镜像时应挂载到构建器容器。 这些绑定将未经解析和验证直接传递给Docker以创建构建器容器。 绑定必须采用以下形式之一:
其中
|
||
|
|
该 网络驱动程序 将配置构建器容器使用的网络驱动程序。 提供的值在创建构建器容器时将未经验证地传递给 Docker。 |
|
|
|
是否在构建前清理缓存。 |
|
|
启用构建器操作的详细日志记录。 |
|
|
|
|
是否将生成的镜像发布到 Docker 注册表。 |
|
|
要应用到生成的映像上的一个或多个附加标签列表。
提供给 |
||
|
一个临时工作区,构建器和构建包将使用它在图像构建期间存储文件。 该值可以是命名卷或绑定挂载位置。 |
Docker 守护进程中的一个命名卷,其名称派生自镜像名称。 |
|
|
一个包含由buildpack创建的层并被镜像构建过程使用的缓存。 该值可以是命名卷或绑定挂载位置。 |
Docker 守护进程中的一个命名卷,其名称派生自镜像名称。 |
|
|
一个包含由buildpack创建的层以及由镜像启动过程使用的缓存。 该值可以是命名卷或绑定挂载位置。 |
Docker 守护进程中的一个命名卷,其名称派生自镜像名称。 |
|
|
|
用于设置生成图像元数据中 |
一个固定的日期,可实现 构建可重复性。 |
|
|
应用内容在构建器镜像中将被上传到的目录路径。 生成的镜像中,应用内容也将位于此位置。 |
|
|
|
安全选项 将应用于构建器容器,作为字符串值的数组提供 |
在 Linux 和 macOS 上为 |
该插件使用 JavaPlugin 的 targetCompatibility 属性检测项目的目标 Java 兼容性。
当使用默认的 Paketo 构建器和构建包时,该插件会指示构建包安装相同版本的 Java。
您可以按照 构建器配置 示例中的方法覆盖此行为。 |
默认的构建器 paketobuildpacks/builder-noble-java-tiny:latest 包含一组精简的系统库,并不包含一个 shell。
需要 shell 来运行启动脚本的应用程序,例如当 application 插件 被应用以生成一个分布 zip 归档文件时,或者依赖于不存在的系统库的应用程序,应覆盖 runImage 配置,以使用一个包含 shell 和更广泛的系统库的配置,例如 paketobuildpacks/ubuntu-noble-run:latest。 |
标签格式
提供给 tags 选项的值应为 完整 的图像引用。
接受的格式为 [domainHost:port/][path/]name[:tag][@digest]。
如果缺少 domain,则默认为 docker.io。
如果缺少 path,则默认为 library。
如果缺少 tag,则默认为 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 的运行器镜像。
构建器和运行镜像也可以在命令行中指定,如下例所示:
$ gradle bootBuildImage --builder=mine/java-cnb-builder --runImage=mine/java-cnb-run
构建器配置
如果构建器暴露了配置选项,可以使用 environment 属性进行设置。
以下是在构建时配置Paketo Java构建包使用的JVM版本的示例:
-
Groovy
-
Kotlin
tasks.named("bootBuildImage") {
environment["BP_JVM_VERSION"] = "17"
}
tasks.named<BootBuildImage>("bootBuildImage") {
environment.put("BP_JVM_VERSION", "17")
}
如果 Docker 守护进程(构建器运行于其中)与构建包下载工件的网络位置之间存在网络代理,则需要配置构建器以使用该代理。
使用 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 构建包 通过设置 JAVA_TOOL_OPTIONS 环境变量来配置 JVM 运行时环境。
构建包提供的 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
构建包
默认情况下,构建器将使用构建器镜像中包含的构建包,并按预定义的顺序应用它们。 可以提供一组替代的构建包,以应用构建器中不包含的构建包,或者更改包含的构建包的顺序。 当提供一个或多个构建包时,仅应用指定的构建包。
以下示例指示构建器使用打包在 .tgz 文件中的自定义 buildpack,然后使用构建器中包含的 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"))
}
构建包可以以下面所示的任何形式指定。
位于 CNB Builder 中的构建包(如果构建包中只有一个与 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
一个包含 打包的构建包 的 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 注册表需要身份验证,可以使用 docker.publishRegistry 属性来配置凭据。
如果 Docker 注册表不需要身份验证,则可以省略 docker.publishRegistry 配置。
镜像将被发布到的注册表由镜像名称中的注册表部分决定(在这些示例中为 docker.example.com)。
如果配置了 docker.publishRegistry 凭据并包含 url 属性,则该值会传递给注册表,但不会用于确定发布注册表的位置。 |
-
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
构建器缓存与工作区配置
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")
}
}
}
构建器和构建包在生成镜像期间需要一个位置来存储临时文件。 默认情况下,此临时构建工作区存储在命名卷中。
缓存和构建工作区可以配置为使用绑定挂载(bind mounts)而非命名卷(named volumes),如下例所示:
-
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 上,可以在 minikube 启动后使用命令 eval $(minikube docker-env) 设置环境变量。
该插件还可以通过提供类似于以下示例中所示的连接详情,配置为使用 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 配置属性的值。 |
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]")
}
}
}
如果构建器或运行镜像存储在支持Tokens认证的私有 Docker 注册表中,则可以使用 docker.builderRegistry 提供Tokens值,如下例所示:
-
Groovy
-
Kotlin
tasks.named("bootBuildImage") {
docker {
builderRegistry {
token = "9cbaf023786cd7..."
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
builderRegistry {
token.set("9cbaf023786cd7...")
}
}
}