打包 OCI 镜像

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

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

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

Docker Daemon

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

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

环境变量 描述

DOCKER_CONFIG

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

DOCKER_CONTEXT

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

DOCKER_HOST

包含 Docker daemon 主机和端口的 URL - 例如 tcp://192.168.99.100:2376

DOCKER_TLS_VERIFY

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

DOCKER_CERT_PATH

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

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

财产 描述

context

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

host

包含 Docker daemon 主机和端口的 URL - 例如 tcp://192.168.99.100:2376

tlsVerify

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

certPath

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

bindHostToBuilder

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

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

Docker Registry

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

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

提供了用于用户身份验证或身份令牌身份验证的属性。请查阅所用 Docker 注册表的文档,以获取有关受支持的身份验证方法的更多信息。

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

财产 描述

username

Docker 镜像注册表用户的用户名。用户身份验证必需。

password

Docker 镜像注册表用户的密码。用户身份验证必需。

url

Docker 镜像注册表的地址。用户身份验证可选。

email

Docker 镜像注册表用户的电子邮件地址。用户身份验证可选。

token

Docker 镜像注册表用户的身份令牌。令牌身份验证必需。

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

如果未提供凭据,插件将读取用户的现有 Docker 配置文件(通常位于 $HOME/.docker/config.json)以确定身份验证方法。使用这些方法,插件尝试为请求的镜像提供身份验证凭据。

该插件支持以下身份验证方法

  • 凭据助手:Docker 配置文件中配置的外部工具,用于为特定注册表提供凭据。例如,osxkeychainecr-login 等工具处理某些注册表的身份验证。

  • 凭据存储:一种默认的后备机制,用于安全地存储和检索凭据(例如,Docker Desktop 的 desktop)。

  • 静态凭据:直接存储在 Docker 配置文件 auths 部分下的凭据。

镜像定制

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

任务属性可用于配置构建器应如何操作项目。下表总结了可用属性及其默认值

财产 命令行选项 描述 默认值

builder

--builder

要使用的构建器镜像名称。

paketobuildpacks/builder-noble-java-tiny:latest

trustBuilder

--trustBuilder

是否将构建器视为受信任的

如果构建器是 paketobuildpacks/builder-noble-java-tinypaketobuildpacks/builder-jammy-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

任何拉取的构建器、运行和构建包镜像的平台(操作系统和架构)。必须采用 OS[/architecture[/variant]] 的形式,例如 linux/amd64linux/arm64linux/arm/v5。请参阅所用构建器的文档以确定可用的镜像操作系统和架构选项。

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

runImage

--runImage

要使用的运行镜像名称。

无默认值,表示应使用构建器元数据中指定的运行镜像。

imageName

--imageName

生成的镜像的镜像名称

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

pullPolicy

--pullPolicy

用于确定何时从注册表拉取构建器和运行镜像的策略。可接受的值为 ALWAYSNEVERIF_NOT_PRESENT

ALWAYS

environment

应传递给构建器的环境变量。

空。

buildpacks

构建器在构建镜像时应使用的 Buildpack。只使用指定的 Buildpack,覆盖构建器中包含的默认 Buildpack。Buildpack 引用必须是以下形式之一

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

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

  • 文件系统上 gzipped tar (.tgz) 文件中的 Buildpack - [file://]<path>/<file name>

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

无,表示构建器应使用其中包含的 Buildpack。

bindings

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

  • <宿主源路径>:<容器目标路径>[:<选项>]

  • <宿主卷名称>:<容器目标路径>[:<选项>]

其中 <选项> 可以包含

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

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

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

network

--network

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

cleanCache

--cleanCache

是否在构建前清理缓存。

verboseLogging

启用构建器操作的详细日志记录。

publish

--publishImage

是否将生成的镜像发布到 Docker 注册表。

tags

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

buildWorkspace

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

Docker daemon 中的命名卷,名称派生自镜像名称。

buildCache

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

Docker daemon 中的命名卷,名称派生自镜像名称。

launchCache

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

Docker daemon 中的命名卷,名称派生自镜像名称。

createdDate

--createdDate

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

一个固定日期,可实现构建可重现性

applicationDirectory

--applicationDirectory

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

/workspace

securityOptions

--securityOptions

将应用于构建器容器的安全选项,以字符串值数组的形式提供

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

该插件使用 JavaPlugin 的 targetCompatibility 属性检测项目的目标 Java 兼容性。使用默认的 Paketo 构建器和 buildpack 时,插件指示 buildpack 安装相同的 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]

如果缺少域,则默认为 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 的运行镜像。

构建器和运行镜像也可以在命令行上指定,如本例所示

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

构建器配置

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

  • Groovy

  • Kotlin

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

如果 Docker daemon 运行的构建器与 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 环境变量来配置 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

Buildpack

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

以下示例指示构建器使用打包在 .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"))
}

Buildpack 可以采用以下所示的任何形式指定。

位于 CNB Builder 中的 buildpack(如果构建器中只有一个与 buildpack-id 匹配的 buildpack,则版本可以省略)

包含 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

构建器缓存和工作区配置

CNB 构建器缓存构建和启动镜像时使用的层。默认情况下,这些缓存作为命名卷存储在 Docker daemon 中,其名称派生自目标镜像的完整名称。如果镜像名称频繁更改,例如当项目版本用作镜像名称中的标签时,则缓存可能会频繁失效。

缓存卷可以配置为使用替代名称,以便更好地控制缓存生命周期,如以下示例所示

  • 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 daemon 通信,而不是默认的本地连接。

在 Linux 和 macOS 上,启动 minikube 后,可以使用命令 eval $(minikube docker-env) 设置环境变量。

该插件也可以通过提供类似于以下示例所示的连接详细信息来配置为使用 minikube daemon

  • 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 daemon 通信。可以使用以下命令设置 DOCKER_HOST 环境变量

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

该插件也可以通过提供类似于以下示例所示的连接详细信息来配置为使用 Colima daemon

  • 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...")
		}
	}
}
© . This site is unofficial and not affiliated with VMware.