打包 OCI 映象

該外掛可以使用 Cloud Native Buildpacks (CNB) 從 jar 或 war 檔案建立 OCI 映象。映象可以使用 bootBuildImage 任務構建。

出於安全原因,映象構建和執行都使用非 root 使用者。更多詳情請參閱 CNB 規範

當應用了 javawar 外掛時,會自動建立此任務,並且它是 BootBuildImage 的一個例項。

Docker 守護程序

bootBuildImage 任務需要訪問 Docker 守護程序。任務將檢查本地 Docker CLI 配置檔案 以確定當前的 context,並使用 context 連線資訊與 Docker 守護程序通訊。如果無法確定當前 context 或 context 沒有連線資訊,則任務將使用預設的本地連線。這適用於所有支援的平臺上的 Docker Engine,無需配置。

可以設定環境變數來配置 bootBuildImage 任務使用替代的本地或遠端連線。下表顯示了環境變數及其值

環境變數 描述

DOCKER_CONFIG

用於確定當前 context 的 Docker CLI 配置檔案 位置 (預設為 $HOME/.docker)

DOCKER_CONTEXT

用於從 Docker CLI 配置檔案中檢索主機資訊的 context 名稱 (覆蓋 DOCKER_HOST)

DOCKER_HOST

包含 Docker 守護程序主機和埠的 URL - 例如 tcp://192.168.99.100:2376

DOCKER_TLS_VERIFY

設定為 1 時啟用安全的 HTTPS 協議 (可選)

DOCKER_CERT_PATH

HTTPS 證書和金鑰檔案的路徑 (如果 DOCKER_TLS_VERIFY=1 則必需,否則忽略)

還可以使用外掛配置中的 docker 屬性提供 Docker 守護程序連線資訊。下表總結了可用的屬性。

屬性 描述

context

用於從 Docker CLI 配置檔案中檢索主機資訊的 context 名稱

host

包含 Docker 守護程序主機和埠的 URL - 例如 tcp://192.168.99.100:2376

tlsVerify

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

certPath

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

bindHostToBuilder

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

更多詳情,另請參閱 示例

Docker 註冊中心

如果 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 包含多個 buildpacks,可以檢查應用以影響生成的映象。預設情況下,外掛會選擇一個 builder 映象。生成的映象名稱是根據專案屬性推斷的。

任務屬性可以用來配置 builder 應如何操作專案。下表總結了可用的屬性及其預設值。

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

builder

--builder

要使用的 builder 映象的名稱。

paketobuildpacks/builder-jammy-java-tiny:latest

trustBuilder

--trustBuilder

是否將 builder 視為信任的

如果 builder 是以下之一則為 truepaketobuildpacks/builder-jammy-java-tinypaketobuildpacks/builder-noble-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;否則為 false

imagePlatform

--imagePlatform

拉取的任何 builder、run 和 buildpack 映象的平臺(作業系統和架構)。必須採用 OS[/architecture[/variant]] 的形式,例如 linux/amd64linux/arm64linux/arm/v5。請參考正在使用的 builder 的文件以確定可用的映象 OS 和架構選項。

無預設值,表示應使用宿主機的平臺。

runImage

--runImage

要使用的 run 映象的名稱。

無預設值,表示應使用 Builder 元資料中指定的 run 映象。

imageName

--imageName

生成映象的映象名稱

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

pullPolicy

--pullPolicy

用於確定何時從註冊中心拉取 builder 和 run 映象的策略。可接受的值有 ALWAYSNEVERIF_NOT_PRESENT

ALWAYS

environment

應該傳遞給 builder 的環境變數。

空。

buildpacks

builder 在構建映象時應使用的 buildpacks。只會使用指定的 buildpacks,覆蓋 builder 中包含的預設 buildpacks。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 應使用其包含的 buildpacks。

bindings

卷繫結掛載,在構建映象時應掛載到 builder 容器。建立 builder 容器時,這些繫結將未解析和未驗證地傳遞給 Docker。繫結必須採用以下形式之一:

  • <宿主機源路徑>:<容器目標路徑>[:<選項>]

  • <宿主機卷名稱>:<容器目標路徑>[:<選項>]

其中 <選項> 可以包含:

  • ro 在容器中將卷掛載為只讀

  • rw 在容器中將卷掛載為可讀寫

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

network

--network

配置 builder 容器使用的網路驅動。提供的值在建立 builder 容器時將未經驗證地傳遞給 Docker。

cleanCache

--cleanCache

是否在構建前清理快取。

false

verboseLogging

啟用 builder 操作的詳細日誌記錄。

false

publish

--publishImage

是否將生成的映象釋出到 Docker 註冊中心。

false

tags

應用於生成的映象的一個或多個附加標籤列表。提供給 tags 選項的值應該是完整的映象引用。更多詳情請參閱tags 部分

buildWorkspace

builder 和 buildpacks 在映象構建期間用於儲存臨時檔案的臨時工作空間。該值可以是一個命名卷或一個繫結掛載位置。

Docker 守護程序中的一個命名卷,其名稱派生自映象名稱。

buildCache

包含由 buildpacks 建立並在映象構建過程中使用的層的快取。該值可以是一個命名卷或一個繫結掛載位置。

Docker 守護程序中的一個命名卷,其名稱派生自映象名稱。

launchCache

包含由 buildpacks 建立並在映象啟動過程中使用的層的快取。該值可以是一個命名卷或一個繫結掛載位置。

Docker 守護程序中的一個命名卷,其名稱派生自映象名稱。

createdDate

--createdDate

一個日期,將用於設定生成的映象元資料中的 Created 欄位。該值必須是 ISO 8601 即時格式的字串,或 now 表示使用當前日期和時間。

一個固定日期,用於實現構建的可重現性

applicationDirectory

--applicationDirectory

應用內容將被上傳到 builder 映象中某個目錄的路徑。應用內容在生成的映象中也會在此位置。

/workspace

securityOptions

--securityOptions

將應用於 builder 容器的安全選項,作為字串陣列提供。

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

外掛使用 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:latestpaketobuildpacks/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 屬性進行設定。

  • 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"
	))
}

自定義映象名稱

預設情況下,映象名稱根據專案的 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}")
}

注意,此配置未提供顯式 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,則可以省略版本)

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