打包 OCI 镜像

该插件可以使用 Cloud Native Buildpacks (CNB) 从 jar 或 war 文件创建 OCI 镜像。 可以使用 bootBuildImage 任务来构建镜像。

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

当应用 javawar 插件时,该任务会自动创建,它是 BootBuildImage 的一个实例。

Docker 守护进程

bootBuildImage 任务需要访问 Docker 守护进程。 该任务将检查本地 Docker CLI 配置文件 以确定当前的 上下文,并使用上下文连接信息与 Docker 守护进程通信。 如果无法确定当前上下文或上下文没有连接信息,则任务将使用默认的本地连接。 这可以在所有支持的平台上与 Docker Engine 一起使用,无需配置。

可以设置环境变量来配置 bootBuildImage 任务使用替代的本地或远程连接。 下表显示了环境变量及其值:

环境变量 描述

DOCKER_CONFIG

Docker CLI 配置文件 的位置,用于确定当前上下文(默认为 $HOME/.docker

DOCKER_CONTEXT

上下文 的名称,用于从 Docker CLI 配置文件中检索主机信息(覆盖 DOCKER_HOST

DOCKER_HOST

包含 Docker 守护进程主机和端口的 URL - 例如 tcp://192.168.99.100:2376

DOCKER_TLS_VERIFY

设置为 1 时启用安全 HTTPS 协议(可选)

DOCKER_CERT_PATH

HTTPS 证书和密钥文件的路径(如果 DOCKER_TLS_VERIFY=1 则需要,否则忽略)

Docker 守护进程连接信息也可以通过插件配置中的 docker 属性提供。 下表总结了可用的属性:

属性 描述

context

上下文 的名称,用于从 Docker CLI 配置文件 中检索主机信息

host

包含 Docker 守护进程主机和端口的 URL - 例如 tcp://192.168.99.100:2376

tlsVerify

设置为 true 时启用安全 HTTPS 协议(可选)

certPath

HTTPS 证书和密钥文件的路径(如果 tlsVerifytrue 则需要,否则忽略)

bindHostToBuilder

当为 true 时,host 属性的值将提供给为 CNB builder 创建的容器(可选)

有关更多详细信息,另请参阅 示例

Docker 镜像仓库

如果 builderrunImage 属性指定的 Docker 镜像存储在需要身份验证的私有 Docker 镜像仓库中,可以使用 docker.builderRegistry 属性提供身份验证凭据。

如果生成的 Docker 镜像要发布到 Docker 镜像仓库,可以使用 docker.publishRegistry 属性提供身份验证凭据。

提供了用户身份验证或身份令牌身份验证的属性。 请查阅用于存储镜像的 Docker 仓库的文档,以获取有关支持的身份验证方法的更多信息。

下表总结了 docker.builderRegistrydocker.publishRegistry 的可用属性:

属性 描述

username

Docker 镜像仓库用户的用户名。用户身份验证需要。

password

Docker 镜像仓库用户的密码。用户身份验证需要。

url

Docker 镜像仓库的地址。用户身份验证可选。

email

Docker 镜像仓库用户的电子邮件地址。用户身份验证可选。

token

Docker 镜像仓库用户的身份令牌。令牌身份验证需要。

有关更多详细信息,另请参阅 示例

镜像自定义

该插件调用 builder 来协调镜像的生成。 builder 包含多个 buildpack,它们可以检查应用程序以影响生成的镜像。 默认情况下,插件会选择 builder 镜像。 生成的镜像名称是从项目属性中推导出来的。

可以使用任务属性来配置 builder 应该如何操作项目。 下表总结了可用属性及其默认值:

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

builder

--builder

要使用的 builder 镜像名称。

paketobuildpacks/builder-jammy-java-tiny:latest

trustBuilder

--trustBuilder

是否将 builder 视为 受信任的

如果 builder 是 paketobuildpacks/builder-jammy-java-tinypaketobuildpacks/builder-noble-java-tinypaketobuildpacks/builder-jammy-tinypaketobuildpacks/builder-jammy-basepaketobuildpacks/builder-jammy-fullpaketobuildpacks/builder-jammy-buildpackless-tinypaketobuildpacks/builder-jammy-buildpackless-basepaketobuildpacks/builder-jammy-buildpackless-fullgcr.io/buildpacks/builderheroku/builder 之一则为 true;否则为 false

imagePlatform

--imagePlatform

要拉取的任何 builder、run 和 buildpack 镜像的平台(操作系统和架构)。 必须采用 OS[/architecture[/variant]] 的形式,例如 linux/amd64linux/arm64linux/arm/v5。 请参阅正在使用的 builder 的文档以确定可用的镜像操作系统和架构选项。

无默认值,表示应使用主机机器的平台。

runImage

--runImage

要使用的 run 镜像名称。

无默认值,表示应使用 Builder 元数据中指定的 run 镜像。

imageName

--imageName

镜像名称 用于生成的镜像。

docker.io/library/${project.name}:${project.version}

pullPolicy

--pullPolicy

策略 用于确定何时从仓库拉取 builder 和 run 镜像。 可接受的值是 ALWAYSNEVERIF_NOT_PRESENT

ALWAYS

environment

应该传递给 builder 的环境变量。

空。

buildpacks

builder 在构建镜像时应使用的 buildpack。 将仅使用指定的 buildpack,覆盖 builder 中包含的默认 buildpack。 buildpack 引用必须采用以下形式之一:

  • builder 中的 buildpack - [urn:cnb:builder:]<buildpack ID>[@<version>]

  • 文件系统上目录中的 buildpack - [file://]<path>

  • 文件系统上 gzip 压缩的 tar (.tgz) 文件中的 buildpack - [file://]<path>/<file name>

  • OCI 镜像中的 buildpack - [docker://]<host>/<repo>[:<tag>][@<digest>]

无,表示 builder 应使用其中包含的 buildpack。

bindings

卷绑定挂载 应该在构建镜像时挂载到 builder 容器。 绑定将在创建 builder 容器时未解析和未验证地传递给 Docker。 绑定必须采用以下形式之一:

  • <host source path>:<container destination path>[:<options>]

  • <host volume name>:<container destination path>[:<options>]

其中 <options> 可以包含:

  • ro 将卷以只读方式挂载到容器中

  • rw 将卷以可读写方式挂载到容器中

  • volume-opt=key=value 指定由选项名称及其值组成的键值对

network

--network

builder 容器将配置使用的 网络驱动程序。 提供的值将在创建 builder 容器时未验证地传递给 Docker。

cleanCache

--cleanCache

是否在构建前清理缓存。

false

verboseLogging

启用 builder 操作的详细日志记录。

false

publish

--publishImage

是否将生成的镜像发布到 Docker 仓库。

false

tags

要应用于生成的镜像的一个或多个附加标签的列表。 提供给 tags 选项的值应该是*完整*的镜像引用。 有关更多详细信息,请参阅 标签部分

buildWorkspace

builder 和 buildpack 在镜像构建期间用于存储文件的临时工作空间。 该值可以是命名卷或绑定挂载位置。

Docker 守护进程中的命名卷,名称从镜像名称派生。

buildCache

包含由 buildpack 创建并由镜像构建过程使用的层的缓存。 该值可以是命名卷或绑定挂载位置。

Docker 守护进程中的命名卷,名称从镜像名称派生。

launchCache

包含由 buildpack 创建并由镜像启动过程使用的层的缓存。 该值可以是命名卷或绑定挂载位置。

Docker 守护进程中的命名卷,名称从镜像名称派生。

createdDate

--createdDate

将用于设置生成的镜像元数据中 Created 字段的日期。 该值必须是 ISO 8601 即时格式的字符串,或 now 以使用当前日期和时间。

启用 构建可重现性 的固定日期。

applicationDirectory

--applicationDirectory

应用程序内容将上传到 builder 镜像中的目录路径。 应用程序内容在生成的镜像中也将位于此位置。

/workspace

securityOptions

--securityOptions

将应用于 builder 容器的 安全选项,作为字符串值数组提供

Linux 和 macOS 上为 ["label=disable"],Windows 上为 []

注意:该插件使用 JavaPlugin 的 targetCompatibility 属性检测项目的目标 Java 兼容性。 使用默认的 Paketo builder 和 buildpack 时,插件会指示 buildpack 安装相同的 Java 版本。 您可以按照 builder 配置 示例中所示覆盖此行为。

注意:默认的 builder 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]

如果缺少域名,则默认为 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 将按原样使用

示例

自定义镜像 Builder 和 Run 镜像

如果您需要自定义用于创建镜像的 builder 或用于启动构建镜像的 run 镜像,请按照以下示例配置任务:

  • 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 的 builder 镜像,以及名称为 mine/java-cnb-run 和标签 latest 的 run 镜像。

也可以在命令行上指定 builder 和 run 镜像,如以下示例所示:

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

Builder 配置

如果 builder 暴露配置选项,可以使用 environment 属性设置这些选项。

  • Groovy

  • Kotlin

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

如果 Docker 守护进程和 buildpack 下载工件的网络位置之间存在网络代理,您需要配置 builder 使用代理。 使用 Paketo builder 时,可以通过设置 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 环境变量来配置 JVM 运行时环境。 可以修改 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"
	))
}

自定义镜像名称

默认情况下,镜像名称是从项目的 nameversion 推断出来的,类似于 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

Buildpacks

默认情况下,builder 将使用 builder 镜像中包含的 buildpack 并按预定义的顺序应用它们。 可以提供替代的 buildpack 集来应用 builder 中未包含的 buildpack,或更改包含的 buildpack 的顺序。 当提供一个或多个 buildpack 时,将仅应用指定的 buildpack。

以下示例指示 builder 使用打包在 .tgz 文件中的自定义 buildpack,后跟 builder 中包含的 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(如果 builder 中只有一个匹配 buildpack-id 的 buildpack,则可以省略版本):

  • urn:cnb:builder:buildpack-id

  • urn:cnb:builder:buildpack-id@0.0.1

  • buildpack-id

  • buildpack-id@0.0.1

包含 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 仓库需要身份验证,可以使用 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")
		}
	}
}

也可以在命令行上指定发布选项,如以下示例所示:

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

Builder 缓存和工作空间配置

CNB builder 缓存用于构建和启动镜像的层。 默认情况下,这些缓存作为命名卷存储在 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")
		}
	}
}

builder 和 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 上,可以在启动 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 身份验证配置

如果 builder 或 run 镜像存储在支持用户身份验证的私有 Docker 仓库中,可以使用 docker.builderRegistry 属性提供身份验证详细信息,如以下示例所示:

  • Groovy

  • Kotlin

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

如果 builder 或 run 镜像存储在支持令牌身份验证的私有 Docker 仓库中,可以使用 docker.builderRegistry 提供令牌值,如以下示例所示:

  • Groovy

  • Kotlin

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