打包 OCI 映象
該外掛可以使用 Cloud Native Buildpacks (CNB) 從 jar 或 war 檔案建立 OCI 映象。映象可以使用 bootBuildImage
任務構建。
出於安全原因,映象構建和執行都使用非 root 使用者。更多詳情請參閱 CNB 規範。 |
當應用了 java
或 war
外掛時,會自動建立此任務,並且它是 BootBuildImage
的一個例項。
Docker 守護程序
bootBuildImage
任務需要訪問 Docker 守護程序。任務將檢查本地 Docker CLI 配置檔案 以確定當前的 context,並使用 context 連線資訊與 Docker 守護程序通訊。如果無法確定當前 context 或 context 沒有連線資訊,則任務將使用預設的本地連線。這適用於所有支援的平臺上的 Docker Engine,無需配置。
可以設定環境變數來配置 bootBuildImage
任務使用替代的本地或遠端連線。下表顯示了環境變數及其值
環境變數 | 描述 |
---|---|
DOCKER_CONFIG |
用於確定當前 context 的 Docker CLI 配置檔案 位置 (預設為 |
DOCKER_CONTEXT |
用於從 Docker CLI 配置檔案中檢索主機資訊的 context 名稱 (覆蓋 |
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
屬性提供認證憑據。
提供了用於使用者認證或身份令牌認證的屬性。有關支援的認證方法的更多資訊,請查閱用於儲存映象的 Docker 註冊中心的文件。
下表總結了 docker.builderRegistry
和 docker.publishRegistry
的可用屬性。
屬性 | 描述 |
---|---|
|
Docker 映象註冊中心使用者的使用者名稱。使用者認證必需。 |
|
Docker 映象註冊中心使用者的密碼。使用者認證必需。 |
|
Docker 映象註冊中心的地址。使用者認證可選。 |
|
Docker 映象註冊中心使用者的電子郵件地址。使用者認證可選。 |
|
Docker 映象註冊中心使用者的身份令牌。令牌認證必需。 |
更多詳情,另請參閱 示例。
映象自定義
該外掛會呼叫一個 builder 來協調映象的生成。builder 包含多個 buildpacks,可以檢查應用以影響生成的映象。預設情況下,外掛會選擇一個 builder 映象。生成的映象名稱是根據專案屬性推斷的。
任務屬性可以用來配置 builder 應如何操作專案。下表總結了可用的屬性及其預設值。
屬性 | 命令列選項 | 描述 | 預設值 |
---|---|---|---|
|
|
要使用的 builder 映象的名稱。 |
|
|
|
是否將 builder 視為信任的。 |
如果 builder 是以下之一則為 |
|
|
拉取的任何 builder、run 和 buildpack 映象的平臺(作業系統和架構)。必須採用 |
無預設值,表示應使用宿主機的平臺。 |
|
|
要使用的 run 映象的名稱。 |
無預設值,表示應使用 Builder 元資料中指定的 run 映象。 |
|
|
生成映象的映象名稱。 |
|
|
|
用於確定何時從註冊中心拉取 builder 和 run 映象的策略。可接受的值有 |
|
|
應該傳遞給 builder 的環境變數。 |
空。 |
|
|
builder 在構建映象時應使用的 buildpacks。只會使用指定的 buildpacks,覆蓋 builder 中包含的預設 buildpacks。Buildpack 引用必須採用以下形式之一:
|
無,表示 builder 應使用其包含的 buildpacks。 |
|
|
卷繫結掛載,在構建映象時應掛載到 builder 容器。建立 builder 容器時,這些繫結將未解析和未驗證地傳遞給 Docker。繫結必須採用以下形式之一:
其中
|
||
|
|
配置 builder 容器使用的網路驅動。提供的值在建立 builder 容器時將未經驗證地傳遞給 Docker。 |
|
|
|
是否在構建前清理快取。 |
|
|
啟用 builder 操作的詳細日誌記錄。 |
|
|
|
|
是否將生成的映象釋出到 Docker 註冊中心。 |
|
|
應用於生成的映象的一個或多個附加標籤列表。提供給 |
||
|
builder 和 buildpacks 在映象構建期間用於儲存臨時檔案的臨時工作空間。該值可以是一個命名卷或一個繫結掛載位置。 |
Docker 守護程序中的一個命名卷,其名稱派生自映象名稱。 |
|
|
包含由 buildpacks 建立並在映象構建過程中使用的層的快取。該值可以是一個命名卷或一個繫結掛載位置。 |
Docker 守護程序中的一個命名卷,其名稱派生自映象名稱。 |
|
|
包含由 buildpacks 建立並在映象啟動過程中使用的層的快取。該值可以是一個命名卷或一個繫結掛載位置。 |
Docker 守護程序中的一個命名卷,其名稱派生自映象名稱。 |
|
|
|
一個日期,將用於設定生成的映象元資料中的 |
一個固定日期,用於實現構建的可重現性。 |
|
|
應用內容將被上傳到 builder 映象中某個目錄的路徑。應用內容在生成的映象中也會在此位置。 |
|
|
|
將應用於 builder 容器的安全選項,作為字串陣列提供。 |
在 Linux 和 macOS 上為 |
外掛使用 JavaPlugin 的 targetCompatibility 屬性檢測專案的目標 Java 相容性。使用預設的 Paketo builder 和 buildpacks 時,外掛會指示 buildpacks 安裝相同的 Java 版本。你可以覆蓋此行為,如builder 配置示例所示。 |
預設的 builder paketobuildpacks/builder-jammy-java-tiny:latest 包含精簡的系統庫集,並且不包含 shell。需要 shell 來執行啟動指令碼的應用(例如,當應用了 application 外掛 以生成分發 zip 歸檔時),或者依賴於不存在的系統庫的應用,應該覆蓋 builder 配置,使用包含 shell 和更廣泛的系統庫集的 builder,例如 paketobuildpacks/builder-jammy-base:latest 或 paketobuildpacks/builder-jammy-full:latest 。 |
Tags 格式
提供給 tags
選項的值應該是完整的映象引用。可接受的格式是 [domainHost:port/][path/]name[:tag][@digest]
。
如果缺少域,則預設為 docker.io
。如果缺少路徑,則預設為 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
將按原樣使用
示例
自定義映象 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
、tag 為 latest
的 builder 映象,以及名稱為 mine/java-cnb-run
、tag 為 latest
的 run 映象。
builder 和 run 映象也可以在命令列上指定,如本例所示:
$ gradle bootBuildImage --builder=mine/java-cnb-builder --runImage=mine/java-cnb-run
Builder 配置
如果 builder 暴露了配置選項,可以使用 environment
屬性進行設定。
以下是構建時配置 Paketo Java buildpacks 使用的 JVM 版本 的示例:
-
Groovy
-
Kotlin
tasks.named("bootBuildImage") {
environment["BP_JVM_VERSION"] = "17"
}
tasks.named<BootBuildImage>("bootBuildImage") {
environment.put("BP_JVM_VERSION", "17")
}
如果 builder 執行的 Docker 守護程序與 buildpacks 下載工件的網路位置之間存在網路代理,你需要配置 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 buildpacks 透過設定 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}")
}
注意,此配置未提供顯式 tag,因此使用了 latest
。也可以指定 tag,可以使用 ${project.version}
、構建中可用的任何屬性或硬編碼版本。
映象名稱也可以在命令列上指定,如本例所示:
$ gradle bootBuildImage --imageName=example.com/library/my-app:v1
Buildpacks
預設情況下,builder 將使用 builder 映象中包含的 buildpacks 並按預定義的順序應用它們。可以提供一組替代的 buildpacks,以應用未包含在 builder 中的 buildpacks,或更改包含的 buildpacks 的順序。當提供一個或多個 buildpacks 時,只會應用指定的 buildpacks。
以下示例指示 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"))
}
Buildpacks 可以以下述任一形式指定。
位於 CNB Builder 中的 buildpack (如果 builder 中只有一個與 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 內容的 gzipped 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")
}
}
}
publish 選項也可以在命令列上指定,如本例所示:
$ gradle bootBuildImage --imageName=docker.example.com/library/my-app:v1 --publishImage
Builder 快取和工作空間配置
CNB builder 會快取構建和啟動映象時使用的層。預設情況下,這些快取作為命名卷儲存在 Docker 守護程序中,其名稱派生自目標映象的完整名稱。如果映象名稱頻繁更改(例如將專案版本用作映象名稱中的 tag),則快取可能會頻繁失效。
可以配置快取卷使用其他名稱,以便更好地控制快取生命週期,如下例所示:
-
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")
}
}
}
Builders 和 buildpacks 在映象構建期間需要一個位置來儲存臨時檔案。預設情況下,此臨時構建工作空間儲存在命名卷中。
可以配置快取和構建工作空間使用繫結掛載而不是命名卷,如下例所示:
-
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 配置
如果 builder 或 run 映象儲存在支援使用者身份驗證的私有 Docker registry 中,可以使用 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]")
}
}
}
如果 builder 或 run 映象儲存在支援令牌身份驗證的私有 Docker registry 中,可以使用 docker.builderRegistry
提供令牌值,如以下示例所示
-
Groovy
-
Kotlin
tasks.named("bootBuildImage") {
docker {
builderRegistry {
token = "9cbaf023786cd7..."
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
builderRegistry {
token.set("9cbaf023786cd7...")
}
}
}