包装 OCI 图像
Docker 守护进程
这启动构建图像任务需要访问 Docker 守护进程。
该任务将检查本地 Docker CLI 配置文件以确定当前上下文,并利用上下文连接信息与 Docker 守护进程通信。
如果无法确定当前上下文或上下文没有连接信息,任务将使用默认的本地连接。
这在所有支持的平台上的 Docker Engine 无需配置即可运行。
环境变量可以设置为配置启动构建图像任务是使用替代的本地或远程连接。
下表展示了环境变量及其值:
| 环境变量 | 描述 |
|---|---|
DOCKER_CONFIG |
用于确定当前上下文的Docker CLI配置文件位置(默认为 |
DOCKER_CONTEXT |
应用于从 Docker CLI 配置文件中获取主机信息的上下文名称(覆盖 |
DOCKER_HOST |
包含 Docker 守护进程主机和端口的 URL - 例如。 |
DOCKER_TLS_VERIFY |
当设置为 时启用安全HTTPS协议 |
DOCKER_CERT_PATH |
HTTPS的证书和密钥文件路径(如果需要 |
Docker 守护进程连接信息也可以通过以下方式提供Jetty工人插件配置中的属性。
下表总结了可用的属性:
| 属性 | 描述 |
|---|---|
|
|
|
包含 Docker 守护进程主机和端口的 URL - 例如。 |
|
当设置为 时启用安全HTTPS协议 |
|
HTTPS的证书和密钥文件路径(如果需要 |
|
什么时候 |
更多细节,请参见示例。
Docker 注册表
如果 Docker 镜像由架构工人或runImage属性存储在需要认证的私有 Docker 映像注册表中,认证凭证可以通过以下方式提供docker.builderRegistry性能。
如果生成的 Docker 镜像要发布到 Docker 镜像注册表,认证凭证可以通过以下方式提供docker.publishRegistry性能。
为用户认证或身份Tokens认证提供了属性。 请参阅用于存储镜像的 Docker 注册表文档,了解更多支持的认证方法信息。
下表总结了可用的性质docker.builderRegistry和docker.publishRegistry:
| 属性 | 描述 |
|---|---|
|
Docker 映像注册用户的用户名。用户认证必修。 |
|
Docker 映像注册表用户的密码。用户认证必修。 |
|
Docker 镜像注册表的地址。用户认证时可选。 |
|
Docker 映像注册表用户的电子邮件地址。用户认证时可选。 |
|
为 Docker 映像注册表用户提供身份Tokens。Tokens认证必不可少。 |
更多细节,请参见示例。
|
如果未提供凭证,插件会读取用户现有的 Docker 配置文件(通常位于 该插件支持以下认证方法:
|
图像定制
任务属性可用于配置构建者在项目中的作方式。 下表总结了可用的属性及其默认值:
| 属性 | 命令行选项 | 描述 | 默认值 |
|---|---|---|---|
|
|
使用建造器镜像的名称。 |
|
|
|
是否应该把建造商当作值得信赖的人。 |
|
|
|
任何被拉取的构建器、运行和构建包镜像的平台(作系统和架构)。
必须以 的形式出现 |
没有默认值,表示应使用主机平台。 |
|
|
使用运行图像的名称。 |
不应使用构建器元数据中指定的运行镜像的默认值。 |
|
|
生成图像的图像名称。 |
|
|
|
用来决定何时拉取构建器并从注册表运行映像的策略。
可接受的值为 |
|
|
应该传递给构建者的环境变量。 |
空。 |
|
|
构建者在构建镜像时应该使用的构建包。 只会使用指定的构建包,覆盖构建者中包含的默认构建包。 构建包引用必须以以下形式之一进行:
|
没有,说明建造者应该使用其中的构建包。 |
|
|
卷绑定挂载应该挂载到构建器容器上,这样可以构建映像。 在创建构建容器时,绑定会未解析且未验证地传递给 Docker。 装订必须采用以下形式之一:
哪里
|
||
|
|
构建容器将被配置为使用的网络驱动。 在创建构建容器时,提供的值会在未验证的情况下传递给 Docker。 |
|
|
|
是否在建造前清理缓存。 |
|
|
支持对架构商作的详细记录。 |
|
|
|
|
是否将生成的镜像发布到Docker注册表。 |
|
|
一个或多个附加标签的列表,用于应用于生成图像。
提供给 |
||
|
一个临时工作区,供构建器和构建包在构建映像时存储文件。 该值可以是命名卷或绑定挂载位置。 |
Docker 守护进程中的一个命名卷,名称源自镜像名。 |
|
|
一个包含由构建包创建并用于图像构建过程的图层的缓存。 该值可以是命名卷或绑定挂载位置。 |
Docker 守护进程中的一个命名卷,名称源自镜像名。 |
|
|
一个包含由构建包创建并用于镜像启动过程的层的缓存。 该值可以是命名卷或绑定挂载位置。 |
Docker 守护进程中的一个命名卷,名称源自镜像名。 |
|
|
|
一个将用来设定 |
一个固定日期,以便构建可重复。 |
|
|
构建器镜像中应用内容将上传到的目录路径。 应用内容也会出现在生成图像的这个位置。 |
|
|
|
安全选项将应用到构建器容器,以字符串数组形式提供 |
|
该插件通过 JavaPlugin 的目标兼容性财产。
使用默认的 Paketo 构建器和构建包时,插件会指示构建包安装相同的 Java 版本。
你可以像构建器配置示例中那样覆盖这个行为。 |
默认构建器Paketobuildpacks/builder-noble-java-tiny:最新包含简化的系统库集,且不包含 shell。
需要shell来运行启动脚本的应用程序,比如当应用插件应用到生成分发式zip压缩,或依赖于不存在的系统库的应用,应覆盖runImage配置以使用包含壳层和更广泛的系统库集的配置,例如paketobuildpacks/ubuntu-noble-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")
}
该配置将使用带有名称的构建器镜像矿山/Java-CNB-构建器以及标签最近的,以及名为mine/java-cnb-run以及标签最近的.
构建器和运行镜像也可以在命令行中指定,如本例所示:
$ gradle bootBuildImage --builder=mine/java-cnb-builder --runImage=mine/java-cnb-run
建造者配置
如果构建者暴露了配置选项,这些选项可以通过环境财产。
以下是 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文档中的描述设置,并展示如下示例:
-
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"
))
}
自定义图片名称
默认情况下,图像名称是从以下名称以及版本项目中,类似这样的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}")
}
注意,这种配置不提供显式标签,因此最近的被使用。
也可以指定标签,比如${project.version},构建中可用的任何属性或硬编码版本。
图像名称也可以在命令行中指定,如示例所示:
$ gradle bootBuildImage --imageName=example.com/library/my-app:v1
构建包
默认情况下,构建器会使用构建器镜像中包含的构建包,并按预定义顺序应用。 还可以提供一套替代的构建包,用于应用未包含在构建包中的构建包,或改变包含构建包的顺序。 当提供一个或多个构建包时,只有指定的构建包会被应用。
以下示例指示构建者使用一个自定义构建包,封装在.tgz文件,接着是构建器中包含的构建包。
-
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构建器中的构建包(如果构建器中只有一个构建包与buildpack-id):
-
urn:cnb:builder:buildpack-id -
urn:cnb:builder:[email protected] -
buildpack-id
一个指向包含构建包内容目录的路径(Windows不支持):
-
file:///path/to/buildpack/ -
/path/to/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:latest -
example/buildpack@sha256:45b23dee08...
Image 出版
生成的镜像可以通过启用发布选择。
如果 Docker 注册表需要认证,凭证可以通过以下方式配置docker.publishRegistry性能。 如果 Docker 注册表不需要认证,那么docker.publishRegistry配置可以省略。
图像将被发布到的注册表由图像名称中的注册表部分决定(docker.example.com在这些例子中)。 如果docker.publishRegistry凭据配置包括网址该属性,该值传递给注册局,但不用于确定出版注册局的位置。 |
-
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
构建缓存与工作区配置
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")
}
}
}
构建器和构建包需要一个存放临时文件的地方,在构建映像时。默认情况下,这个临时构建工作区存储在一个命名卷中。
缓存和构建工作区可以配置为使用绑定挂载而非命名卷,如下示例所示:
-
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 配置
Docker Configuration for minikube
该插件可以与 minikube 提供的 Docker 守护进程通信,而非默认的本地连接。
在 Linux 和 macOS 上,环境变量可以通过以下命令设置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")
}
}
Docker Configuration for podman
该插件可以与 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)
}
}
与舱体人CLI安装了命令podman 信息 --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 注册表中,则可以通过以下方式提供Tokens值docker.builderRegistry如下例所示:
-
Groovy
-
Kotlin
tasks.named("bootBuildImage") {
docker {
builderRegistry {
token = "9cbaf023786cd7..."
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
builderRegistry {
token.set("9cbaf023786cd7...")
}
}
}