封裝 OCI 映像檔

此外掛程式可以使用 Cloud Native Buildpacks (CNB) 從 jar 或 war 檔案建立 OCI 映像檔。映像檔可以使用 bootBuildImage 任務來建置。

基於安全考量,映像檔會以非 root 使用者身分建置和執行。如需更多詳細資訊,請參閱 CNB 規格

當套用 javawar 外掛程式時,會自動建立此任務,並且是 BootBuildImage 的實例。

Docker Daemon

bootBuildImage 任務需要存取 Docker daemon。此任務將檢查本機 Docker CLI 組態檔,以判斷目前的 context,並使用 context 連線資訊與 Docker daemon 通訊。如果無法判斷目前的 context,或 context 沒有連線資訊,則任務將使用預設的本機連線。這適用於所有支援平台上的 Docker Engine,無需組態。

可以設定環境變數,以組態 bootBuildImage 任務以使用替代的本機或遠端連線。下表顯示環境變數及其值

環境變數 描述

DOCKER_CONFIG

Docker CLI 組態檔的位置,用於判斷目前的 context (預設為 $HOME/.docker)

DOCKER_CONTEXT

應該用來從 Docker CLI 組態檔中檢索主機資訊的 context 名稱 (覆寫 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 組態檔中檢索主機資訊的 context 名稱

host

包含 Docker daemon 的主機和連接埠的 URL - 例如 tcp://192.168.99.100:2376

tlsVerify

設定為 true 時啟用安全 HTTPS 協定 (選用)

certPath

HTTPS 的憑證和金鑰檔案路徑 (如果 tlsVerifytrue 則為必要,否則忽略)

bindHostToBuilder

true 時,host 屬性的值將提供給為 CNB builder 建立的容器 (選用)

如需更多詳細資訊,另請參閱 範例

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 映像檔登錄檔使用者的身分識別權杖。權杖驗證為必要項目。

如需更多詳細資訊,另請參閱 範例

映像檔自訂

此外掛程式會調用 builder 來協調映像檔的產生。builder 包含多個 buildpack,可以檢查應用程式以影響產生的映像檔。依預設,此外掛程式會選擇 builder 映像檔。產生的映像檔名稱是從專案屬性推導而來。

任務屬性可用於組態 builder 應如何對專案進行操作。下表總結了可用的屬性及其預設值

屬性 命令列選項 描述 預設值

builder

--builder

要使用的 Builder 映像檔名稱。

當套用 GraalVM Native Image 外掛程式 時,為 paketobuildpacks/builder-jammy-base:latestpaketobuildpacks/builder-jammy-tiny:latest

runImage

--runImage

要使用的執行映像檔名稱。

無預設值,表示應使用 Builder 中繼資料中指定的執行映像檔。

imageName

--imageName

產生映像檔的 映像檔名稱

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

pullPolicy

--pullPolicy

用於判斷何時從登錄檔提取 builder 和執行映像檔的策略。可接受的值為 ALWAYSNEVERIF_NOT_PRESENT

ALWAYS

environment

應傳遞至 builder 的環境變數。

當套用 GraalVM Native Image 外掛程式 時,為空或 ['BP_NATIVE_IMAGE': 'true']

buildpacks

builder 在建置映像檔時應使用的 Buildpack。僅會使用指定的 buildpack,覆寫 builder 中包含的預設 buildpack。Buildpack 參考必須採用以下其中一種形式

  • builder 中的 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>]

無,表示 builder 應使用其中包含的 buildpack。

bindings

在建置映像檔時,應掛載到 builder 容器的 磁碟區繫結掛載。繫結將在建立 builder 容器時以未剖析且未驗證的方式傳遞至 Docker。繫結必須採用以下其中一種形式

  • <host source path>:<container destination path>[:<options>]

  • <host volume name>:<container destination path>[:<options>]

其中 <options> 可以包含

  • ro 將磁碟區掛載為容器中的唯讀

  • rw 將磁碟區掛載為容器中的可讀寫

  • volume-opt=key=value 指定由選項名稱及其值組成的鍵值對

network

--network

builder 容器將組態為使用的 網路驅動程式。提供的值將在建立 builder 容器時以未驗證的方式傳遞至 Docker。

cleanCache

--cleanCache

是否在建置前清除快取。

false

verboseLogging

啟用 builder 操作的詳細記錄。

false

publish

--publishImage

是否將產生的映像檔發布到 Docker 登錄檔。

false

tags

要套用至產生映像檔的一個或多個額外標籤的清單。提供給 tags 選項的值應為完整映像檔參考。如需更多詳細資訊,請參閱 標籤章節

buildWorkspace

builder 和 buildpack 將用於在映像檔建置期間儲存檔案的暫時工作區。此值可以是具名磁碟區或繫結掛載位置。

Docker daemon 中的具名磁碟區,其名稱衍生自映像檔名稱。

buildCache

包含由 buildpack 建立且由映像檔建置程序使用的圖層的快取。此值可以是具名磁碟區或繫結掛載位置。

Docker daemon 中的具名磁碟區,其名稱衍生自映像檔名稱。

launchCache

包含由 buildpack 建立且由映像檔啟動程序使用的圖層的快取。此值可以是具名磁碟區或繫結掛載位置。

Docker daemon 中的具名磁碟區,其名稱衍生自映像檔名稱。

createdDate

--createdDate

將用於設定產生映像檔中繼資料中 Created 欄位的日期。此值必須是 ISO 8601 instant 格式的字串,或 now 以使用目前的日期和時間。

啟用 建置再現性 的固定日期。

applicationDirectory

--applicationDirectory

應用程式內容將上傳到 builder 映像檔中的目錄路徑。應用程式內容也將位於產生映像檔中的此位置。

/workspace

securityOptions

--securityOptions

將套用至 builder 容器的 安全性選項,以字串值陣列的形式提供

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

此外掛程式會使用 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"
	))
}

自訂映像檔名稱

依預設,映像檔名稱是從專案的 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

依預設,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,則可以省略版本)

包含 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...")
		}
	}
}