打包 OCI 映象

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

出於安全原因,映象以非 root 使用者身份構建和執行。有關更多詳細資訊,請參閱 CNB 規範

當應用 javawar 外掛時,該任務會自動建立,並且是 BootBuildImage 的例項。

Docker Daemon

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

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

環境變數 描述

DOCKER_CONFIG

Docker CLI 配置檔案 的位置,用於確定當前上下文(預設為 $HOME/.docker

DOCKER_CONTEXT

應用於從 Docker CLI 配置檔案中檢索主機資訊的 上下文 名稱(覆蓋 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 配置檔案 中檢索主機資訊的 上下文 名稱

host

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

tlsVerify

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

certPath

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

bindHostToBuilder

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

更多詳細資訊,另請參閱 示例

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 映象登錄檔使用者的身份令牌。令牌身份驗證必需。

更多詳細資訊,另請參閱 示例

如果未提供憑據,外掛將讀取使用者的現有 Docker 配置檔案(通常位於 $HOME/.docker/config.json)以確定身份驗證方法。使用這些方法,外掛嘗試為請求的映象提供身份驗證憑據。

該外掛支援以下身份驗證方法

  • 憑據助手:Docker 配置檔案中配置的外部工具,用於為特定登錄檔提供憑據。例如,osxkeychainecr-login 等工具處理某些登錄檔的身份驗證。

  • 憑據儲存:一種預設的後備機制,用於安全地儲存和檢索憑據(例如,Docker Desktop 的 desktop)。

  • 靜態憑據:直接儲存在 Docker 配置檔案 auths 部分下的憑據。

映象定製

該外掛呼叫 構建器 來協調映象的生成。構建器包含多個 buildpack,可以檢查應用程式以影響生成的映象。預設情況下,外掛選擇一個構建器映象。生成的映象名稱從專案屬性中推匯出來。

任務屬性可用於配置構建器應如何操作專案。下表總結了可用屬性及其預設值

財產 命令列選項 描述 預設值

builder

--builder

要使用的構建器映象名稱。

paketobuildpacks/builder-noble-java-tiny:latest

trustBuilder

--trustBuilder

是否將構建器視為受信任的

如果構建器是 paketobuildpacks/builder-noble-java-tinypaketobuildpacks/builder-jammy-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 中的一個,則為 true;否則為 false

imagePlatform

--imagePlatform

任何拉取的構建器、執行和構建包映象的平臺(作業系統和架構)。必須採用 OS[/architecture[/variant]] 的形式,例如 linux/amd64linux/arm64linux/arm/v5。請參閱所用構建器的文件以確定可用的映象作業系統和架構選項。

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

runImage

--runImage

要使用的執行映象名稱。

無預設值,表示應使用構建器元資料中指定的執行映象。

imageName

--imageName

生成的映象的映象名稱

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

pullPolicy

--pullPolicy

用於確定何時從登錄檔拉取構建器和執行映象的策略。可接受的值為 ALWAYSNEVERIF_NOT_PRESENT

ALWAYS

environment

應傳遞給構建器的環境變數。

空。

buildpacks

構建器在構建映象時應使用的 Buildpack。只使用指定的 Buildpack,覆蓋構建器中包含的預設 Buildpack。Buildpack 引用必須是以下形式之一

  • 構建器中的 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>]

無,表示構建器應使用其中包含的 Buildpack。

bindings

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

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

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

其中 <選項> 可以包含

  • ro 將卷以只讀方式掛載到容器中

  • rw 將卷以可讀寫方式掛載到容器中

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

network

--network

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

cleanCache

--cleanCache

是否在構建前清理快取。

verboseLogging

啟用構建器操作的詳細日誌記錄。

publish

--publishImage

是否將生成的映象釋出到 Docker 登錄檔。

tags

應用於生成的映象的一個或多個附加標籤列表。提供給 tags 選項的值應為完整的映象引用。有關更多詳細資訊,請參閱標籤部分

buildWorkspace

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

Docker daemon 中的命名卷,名稱派生自映象名稱。

buildCache

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

Docker daemon 中的命名卷,名稱派生自映象名稱。

launchCache

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

Docker daemon 中的命名卷,名稱派生自映象名稱。

createdDate

--createdDate

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

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

applicationDirectory

--applicationDirectory

在構建器映象中上傳應用程式內容的目錄路徑。應用程式內容也將位於生成的映象中的此位置。

/workspace

securityOptions

--securityOptions

將應用於構建器容器的安全選項,以字串值陣列的形式提供

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

該外掛使用 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"
	))
}

自定義映象名稱

預設情況下,映象名稱從專案的 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

預設情況下,構建器將使用構建器映象中包含的 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,則版本可以省略)

包含 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...")
		}
	}
}
© . This site is unofficial and not affiliated with VMware.