打包 OCI 映象
該外掛可以使用 Cloud Native Buildpacks (CNB) 從 jar 或 war 檔案建立 OCI 映象。可以使用 bootBuildImage 任務構建映象。
| 出於安全原因,映象以非 root 使用者身份構建和執行。有關更多詳細資訊,請參閱 CNB 規範。 |
當應用 java 或 war 外掛時,該任務會自動建立,並且是 BootBuildImage 的例項。
Docker Daemon
bootBuildImage 任務需要訪問 Docker daemon。該任務將檢查本地 Docker CLI 配置檔案 以確定當前 上下文,並使用上下文連線資訊與 Docker daemon 通訊。如果無法確定當前上下文,或者上下文沒有連線資訊,則該任務將使用預設的本地連線。這適用於所有支援平臺上的 Docker Engine,無需配置。
可以設定環境變數以配置 bootBuildImage 任務以使用備用本地或遠端連線。下表顯示了環境變數及其值
| 環境變數 | 描述 |
|---|---|
DOCKER_CONFIG |
Docker CLI 配置檔案 的位置,用於確定當前上下文(預設為 |
DOCKER_CONTEXT |
應用於從 Docker CLI 配置檔案中檢索主機資訊的 上下文 名稱(覆蓋 |
DOCKER_HOST |
包含 Docker daemon 主機和埠的 URL - 例如 |
DOCKER_TLS_VERIFY |
設定為 |
DOCKER_CERT_PATH |
HTTPS 的證書和金鑰檔案路徑(如果 |
Docker daemon 連線資訊也可以透過外掛配置中的 docker 屬性提供。下表總結了可用屬性
| 財產 | 描述 |
|---|---|
|
|
|
包含 Docker daemon 主機和埠的 URL - 例如 |
|
設定為 |
|
HTTPS 的證書和金鑰檔案路徑(如果 |
|
當為 |
更多詳細資訊,另請參閱 示例。
Docker Registry
如果 builder 或 runImage 屬性指定的 Docker 映象儲存在需要身份驗證的私有 Docker 映象登錄檔中,則可以使用 docker.builderRegistry 屬性提供身份驗證憑據。
如果生成的 Docker 映象要釋出到 Docker 映象登錄檔,則可以使用 docker.publishRegistry 屬性提供身份驗證憑據。
提供了用於使用者身份驗證或身份令牌身份驗證的屬性。請查閱所用 Docker 登錄檔的文件,以獲取有關受支援的身份驗證方法的更多資訊。
下表總結了 docker.builderRegistry 和 docker.publishRegistry 的可用屬性
| 財產 | 描述 |
|---|---|
|
Docker 映象登錄檔使用者的使用者名稱。使用者身份驗證必需。 |
|
Docker 映象登錄檔使用者的密碼。使用者身份驗證必需。 |
|
Docker 映象登錄檔的地址。使用者身份驗證可選。 |
|
Docker 映象登錄檔使用者的電子郵件地址。使用者身份驗證可選。 |
|
Docker 映象登錄檔使用者的身份令牌。令牌身份驗證必需。 |
更多詳細資訊,另請參閱 示例。
|
如果未提供憑據,外掛將讀取使用者的現有 Docker 配置檔案(通常位於 該外掛支援以下身份驗證方法
|
映象定製
任務屬性可用於配置構建器應如何操作專案。下表總結了可用屬性及其預設值
| 財產 | 命令列選項 | 描述 | 預設值 |
|---|---|---|---|
|
|
要使用的構建器映象名稱。 |
|
|
|
是否將構建器視為受信任的。 |
如果構建器是 |
|
|
任何拉取的構建器、執行和構建包映象的平臺(作業系統和架構)。必須採用 |
無預設值,表示應使用主機機器的平臺。 |
|
|
要使用的執行映象名稱。 |
無預設值,表示應使用構建器元資料中指定的執行映象。 |
|
|
生成的映象的映象名稱。 |
|
|
|
用於確定何時從登錄檔拉取構建器和執行映象的策略。可接受的值為 |
|
|
應傳遞給構建器的環境變數。 |
空。 |
|
|
構建器在構建映象時應使用的 Buildpack。只使用指定的 Buildpack,覆蓋構建器中包含的預設 Buildpack。Buildpack 引用必須是以下形式之一
|
無,表示構建器應使用其中包含的 Buildpack。 |
|
|
在構建映象時應掛載到構建器容器的卷繫結掛載。繫結將不經解析和驗證地傳遞給 Docker,以建立構建器容器。繫結必須採用以下形式之一
其中
|
||
|
|
構建器容器將配置使用的網路驅動程式。提供的值將在建立構建器容器時未經驗證地傳遞給 Docker。 |
|
|
|
是否在構建前清理快取。 |
|
|
啟用構建器操作的詳細日誌記錄。 |
|
|
|
|
是否將生成的映象釋出到 Docker 登錄檔。 |
|
|
應用於生成的映象的一個或多個附加標籤列表。提供給 |
||
|
構建器和 buildpack 在映象構建期間用於儲存檔案的臨時工作區。該值可以是命名卷或繫結掛載位置。 |
Docker daemon 中的命名卷,名稱派生自映象名稱。 |
|
|
包含 buildpack 建立並由映象構建過程使用的層快取。該值可以是命名卷或繫結掛載位置。 |
Docker daemon 中的命名卷,名稱派生自映象名稱。 |
|
|
包含 buildpack 建立並由映象啟動過程使用的層快取。該值可以是命名卷或繫結掛載位置。 |
Docker daemon 中的命名卷,名稱派生自映象名稱。 |
|
|
|
用於設定生成的映象元資料中的 |
一個固定日期,可實現構建可重現性。 |
|
|
在構建器映象中上傳應用程式內容的目錄路徑。應用程式內容也將位於生成的映象中的此位置。 |
|
|
|
將應用於構建器容器的安全選項,以字串值陣列的形式提供 |
在 Linux 和 macOS 上為 |
該外掛使用 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"
))
}
自定義映象名稱
預設情況下,映象名稱從專案的 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 時,只應用指定的 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,則版本可以省略)
-
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 登錄檔需要身份驗證,則可以使用 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...")
}
}
}