封裝 OCI 映像檔
此外掛程式可以使用 Cloud Native Buildpacks (CNB) 從 jar 或 war 檔案建立 OCI 映像檔。映像檔可以使用 bootBuildImage
任務來建置。
基於安全考量,映像檔會以非 root 使用者身分建置和執行。如需更多詳細資訊,請參閱 CNB 規格。 |
當套用 java
或 war
外掛程式時,會自動建立此任務,並且是 BootBuildImage
的實例。
Docker Daemon
bootBuildImage
任務需要存取 Docker daemon。此任務將檢查本機 Docker CLI 組態檔,以判斷目前的 context,並使用 context 連線資訊與 Docker daemon 通訊。如果無法判斷目前的 context,或 context 沒有連線資訊,則任務將使用預設的本機連線。這適用於所有支援平台上的 Docker Engine,無需組態。
可以設定環境變數,以組態 bootBuildImage
任務以使用替代的本機或遠端連線。下表顯示環境變數及其值
環境變數 | 描述 |
---|---|
DOCKER_CONFIG |
Docker CLI 組態檔的位置,用於判斷目前的 context (預設為 |
DOCKER_CONTEXT |
應該用來從 Docker CLI 組態檔中檢索主機資訊的 context 名稱 (覆寫 |
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 映像檔登錄檔使用者的身分識別權杖。權杖驗證為必要項目。 |
如需更多詳細資訊,另請參閱 範例。
映像檔自訂
此外掛程式會調用 builder 來協調映像檔的產生。builder 包含多個 buildpack,可以檢查應用程式以影響產生的映像檔。依預設,此外掛程式會選擇 builder 映像檔。產生的映像檔名稱是從專案屬性推導而來。
任務屬性可用於組態 builder 應如何對專案進行操作。下表總結了可用的屬性及其預設值
屬性 | 命令列選項 | 描述 | 預設值 |
---|---|---|---|
|
|
要使用的 Builder 映像檔名稱。 |
當套用 GraalVM Native Image 外掛程式 時,為 |
|
|
要使用的執行映像檔名稱。 |
無預設值,表示應使用 Builder 中繼資料中指定的執行映像檔。 |
|
|
產生映像檔的 映像檔名稱。 |
|
|
|
用於判斷何時從登錄檔提取 builder 和執行映像檔的策略。可接受的值為 |
|
|
應傳遞至 builder 的環境變數。 |
當套用 GraalVM Native Image 外掛程式 時,為空或 |
|
|
builder 在建置映像檔時應使用的 Buildpack。僅會使用指定的 buildpack,覆寫 builder 中包含的預設 buildpack。Buildpack 參考必須採用以下其中一種形式
|
無,表示 builder 應使用其中包含的 buildpack。 |
|
|
在建置映像檔時,應掛載到 builder 容器的 磁碟區繫結掛載。繫結將在建立 builder 容器時以未剖析且未驗證的方式傳遞至 Docker。繫結必須採用以下其中一種形式
其中
|
||
|
|
builder 容器將組態為使用的 網路驅動程式。提供的值將在建立 builder 容器時以未驗證的方式傳遞至 Docker。 |
|
|
|
是否在建置前清除快取。 |
|
|
啟用 builder 操作的詳細記錄。 |
|
|
|
|
是否將產生的映像檔發布到 Docker 登錄檔。 |
|
|
要套用至產生映像檔的一個或多個額外標籤的清單。提供給 |
||
|
builder 和 buildpack 將用於在映像檔建置期間儲存檔案的暫時工作區。此值可以是具名磁碟區或繫結掛載位置。 |
Docker daemon 中的具名磁碟區,其名稱衍生自映像檔名稱。 |
|
|
包含由 buildpack 建立且由映像檔建置程序使用的圖層的快取。此值可以是具名磁碟區或繫結掛載位置。 |
Docker daemon 中的具名磁碟區,其名稱衍生自映像檔名稱。 |
|
|
包含由 buildpack 建立且由映像檔啟動程序使用的圖層的快取。此值可以是具名磁碟區或繫結掛載位置。 |
Docker daemon 中的具名磁碟區,其名稱衍生自映像檔名稱。 |
|
|
|
將用於設定產生映像檔中繼資料中 |
啟用 建置再現性 的固定日期。 |
|
|
應用程式內容將上傳到 builder 映像檔中的目錄路徑。應用程式內容也將位於產生映像檔中的此位置。 |
|
|
|
將套用至 builder 容器的 安全性選項,以字串值陣列的形式提供 |
Linux 和 macOS 上為 |
此外掛程式會使用 JavaPlugin 的 targetCompatibility 屬性偵測專案的目標 Java 相容性。使用預設 Paketo builder 和 buildpack 時,此外掛程式會指示 buildpack 安裝相同的 Java 版本。您可以覆寫此行為,如builder 組態範例所示。 |
標籤格式
提供給 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 和執行映像檔
如果您需要自訂用於建立映像檔的 builder 或用於啟動建置映像檔的執行映像檔,請組態任務,如下列範例所示
-
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
的執行映像檔。
builder 和執行映像檔也可以在命令列上指定,如此範例所示
$ 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 daemon (builder 在其中執行) 和 buildpack 從中下載構件的網路位置之間存在網路 Proxy,則您需要組態 builder 以使用 Proxy。使用 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"
))
}
自訂映像檔名稱
依預設,映像檔名稱是從專案的 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
依預設,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:[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")
}
}
}
發布選項也可以在命令列上指定,如此範例所示
$ gradle bootBuildImage --imageName=docker.example.com/library/my-app:v1 --publishImage
Builder 快取和工作區組態
CNB builder 會快取在建置和啟動映像檔時使用的圖層。依預設,這些快取會儲存為 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")
}
}
}
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 daemon 通訊,而不是預設的本機連線。
在 Linux 和 macOS 上,可以使用命令 eval $(minikube docker-env)
在 minikube 啟動後設定環境變數。
此外掛程式也可以組態為使用 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 守護進程進行通訊。可以使用以下指令來設定 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]")
}
}
}
如果建置器或執行映像檔儲存在支援令牌身分驗證的私有 Docker 映像檔倉庫中,則可以使用 docker.builderRegistry
來提供令牌值,如下列範例所示
-
Groovy
-
Kotlin
tasks.named("bootBuildImage") {
docker {
builderRegistry {
token = "9cbaf023786cd7..."
}
}
}
tasks.named<BootBuildImage>("bootBuildImage") {
docker {
builderRegistry {
token.set("9cbaf023786cd7...")
}
}
}