OCI イメージのパッケージ化

プラグインは、Cloud Native Buildpacks (英語) （CNB）を使用して jar または war ファイルから OCI イメージ [GitHub] (英語) を作成できます。bootBuildImage タスクを使用してイメージを構築できます。

セキュリティ上の理由から、イメージは root 以外のユーザーとしてビルドおよび実行されます。詳細については、CNB 仕様 (英語) を参照してください。

タスクは、java または war プラグインが適用されると自動的に作成され、BootBuildImage (Javadoc) のインスタンスです。

Docker デーモン

bootBuildImage タスクには、Docker デーモンへのアクセスが必要です。このタスクは、ローカルの Docker CLI 構成ファイル (英語) をインスペクションして現在のコンテキスト (英語) を特定し、そのコンテキスト接続情報を使用して Docker デーモンと通信します。現在のコンテキストを特定できない場合、またはコンテキストに接続情報がない場合、タスクはデフォルトのローカル接続を使用します。これは、サポートされているすべてのプラットフォーム上の Docker エンジン (英語) で構成なしで動作します。

環境変数を設定して、代替のローカル接続またはリモート接続を使用するように bootBuildImage タスクを構成できます。次の表に、環境変数とその値を示します。

環境変数 説明

DOCKER_CONFIG

現在のコンテキストを決定するために使用される Docker CLI 構成ファイル (英語) の場所 (デフォルトは $HOME/.docker)

DOCKER_CONTEXT

Docker CLI 構成ファイルからホスト情報を取得するために使用するコンテキスト (英語) の名前 (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 構成ファイル (英語) からホスト情報を取得するために使用するコンテキスト (英語) の名前

host

Docker デーモンのホストとポートを含む URL- 例: tcp://192.168.99.100:2376

tlsVerify

true に設定されている場合、安全な HTTPS プロトコルを有効にする (オプション)

certPath

HTTPS の証明書とキーファイルへのパス (tlsVerify が true の場合は必須、それ以外の場合は無視されます)

bindHostToBuilder

true の場合、host プロパティの値は、CNB ビルダー用に作成されたコンテナーに提供されます。(オプション)

詳細については、例も参照してください。

Docker レジストリ

builder または runImage プロパティで指定された Docker イメージが、認証を必要とするプライベート Docker イメージレジストリに格納されている場合、認証資格情報は docker.builderRegistry プロパティを使用して提供できます。

生成された Docker イメージを Docker イメージレジストリに公開する場合は、docker.publishRegistry プロパティを使用して認証資格情報を提供できます。

プロパティは、ユーザー認証または ID トークン認証用に提供されています。サポートされている認証方法の詳細については、イメージの保存に使用されている Docker レジストリのドキュメントを参照してください。

次の表は、docker.builderRegistry および docker.publishRegistry で使用可能なプロパティをまとめたものです。

プロパティ 説明

username

Docker イメージレジストリユーザーのユーザー名。ユーザー認証に必要です。

password

Docker イメージレジストリユーザーのパスワード。ユーザー認証に必要です。

url

Docker イメージレジストリのアドレス。ユーザー認証のオプション。

email

Docker イメージレジストリユーザーのメールアドレス。ユーザー認証のオプション。

token

Docker イメージレジストリユーザーの ID トークン。トークン認証に必要です。

詳細については、例も参照してください。

イメージのカスタマイズ

プラグインはビルダー (英語) を呼び出して、イメージの生成を調整します。ビルダーには、生成されたイメージに影響を与えるためにアプリケーションをインスペクションできる複数の buildpacks が含 (英語) まれています。デフォルトでは、プラグインはビルダーイメージを選択します。生成されたイメージの名前は、プロジェクトのプロパティから推測されます。

タスクプロパティを使用して、ビルダーがプロジェクトでどのように動作するかを構成できます。次の表は、使用可能なプロパティとそのデフォルト値をまとめたものです。

プロパティ コマンドラインオプション 説明 デフォルト値

builder

--builder

使用するビルダーイメージの名前。

paketobuildpacks/builder-jammy-java-tiny:latest

trustBuilder

--trustBuilder

ビルダーを信頼できる (英語) ものとして扱うかどうか。

true if the builder is one of paketobuildpacks/builder-jammy-java-tiny, paketobuildpacks/builder-noble-java-tiny, paketobuildpacks/builder-jammy-tiny, paketobuildpacks/builder-jammy-base, paketobuildpacks/builder-jammy-full, paketobuildpacks/builder-jammy-buildpackless-tiny, paketobuildpacks/builder-jammy-buildpackless-base, paketobuildpacks/builder-jammy-buildpackless-full, gcr.io/buildpacks/builder, heroku/builder; false otherwise.

imagePlatform

--imagePlatform

プルされるビルダー、実行、buildpack イメージのプラットフォーム (オペレーティングシステムとアーキテクチャ)。linux/amd64、linux/arm64、または linux/arm/v5 などの OS[/architecture[/variant]] 形式である必要があります。使用可能なイメージ OS およびアーキテクチャオプションを確認するには、使用しているビルダーのドキュメントを参照してください。

デフォルト値はありません。ホストマシンのプラットフォームを使用する必要があることを示します。

runImage

--runImage

使用する実行イメージの名前。

デフォルト値はなく、Builder メタデータで指定された実行イメージを使用する必要があることを示します。

imageName

--imageName

生成されたイメージのイメージ名: (Javadoc) 。

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

pullPolicy

--pullPolicy

ポリシー (Javadoc) は、ビルダーをプルしてレジストリからイメージを実行するタイミングを決定するために使用されます。許容値は ALWAYS、NEVER、IF_NOT_PRESENT です。

ALWAYS

environment

ビルダーに渡す必要のある環境変数。

空。

buildpacks

ビルダーがイメージをビルドするときに使用する必要がある Buildpacks。指定された buildpacks のみが使用され、ビルダーに含まれているデフォルトの buildpacks がオーバーライドされます。Buildpack 参照は、次のいずれかの形式である必要があります。

  • ビルダーの Buildpack - [urn:cnb:builder:]<buildpack ID>[@<version>]

  • ファイルシステム上のディレクトリ内の Buildpack- [file://]<path>

  • ファイルシステム上の gzip 圧縮された tar（.tgz）ファイル内の Buildpack- [file://]<path>/<file name>

  • OCI イメージの Buildpack- [docker://]<host>/<repo>[:<tag>][@<digest>]

なし。ビルダーがそれに含まれる buildpacks を使用する必要があることを示します。

bindings

イメージをビルドするときにビルダーコンテナーにマウントする必要があるボリュームバインドマウント (英語) 。バインディングは、ビルダーコンテナーの作成時に、解析されず、検証されずに Docker に渡されます。バインディングは、次のいずれかの形式である必要があります。

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

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

<options> に含めることができる場所:

  • ボリュームを読み取り専用としてコンテナーにマウントする ro 

  • ボリュームをコンテナー内で読み取り可能および書き込み可能としてマウントするための rw 

  • オプション名とその値で構成されるキーと値のペアを指定する volume-opt=key=value 

network

--network

ビルダーコンテナーが使用するように構成されたネットワークドライバー (英語) 。指定された値は、ビルダーコンテナーの作成時に、検証されずに Docker に渡されます。

cleanCache

--cleanCache

構築する前にキャッシュを消去するかどうか。

false

verboseLogging

ビルダー操作の詳細ログを有効にします。

false

publish

--publishImage

生成されたイメージを Docker レジストリに公開するかどうか。

false

tags

生成されたイメージに適用する 1 つ以上の追加タグのリスト。tags オプションに指定される値は、完全なイメージ参照である必要があります。詳細については、タグのセクションを参照してください。

buildWorkspace

ビルダーと buildpacks がイメージの構築中にファイルを保存するために使用する一時ワークスペース。値には、名前付きボリュームまたはバインドマウントの場所を指定できます。

イメージ名から派生した名前を持つ、Docker デーモン内の名前付きボリューム。

buildCache

buildpacks によって作成され、イメージ構築プロセスによって使用されるレイヤーを含むキャッシュ。値には、名前付きボリュームまたはバインドマウントの場所を指定できます。

イメージ名から派生した名前を持つ、Docker デーモン内の名前付きボリューム。

launchCache

buildpacks によって作成され、イメージ起動プロセスによって使用されるレイヤーを含むキャッシュ。値には、名前付きボリュームまたはバインドマウントの場所を指定できます。

イメージ名から派生した名前を持つ、Docker デーモン内の名前付きボリューム。

createdDate

--createdDate

生成されたイメージのメタデータで Created フィールドを設定するために使用される日付。値は、ISO 8601 インスタント形式の文字列、または現在の日付と時刻を使用する now である必要があります。

ビルドの再現性 (英語) を可能にする固定の日付。

applicationDirectory

--applicationDirectory

ビルダーイメージ内のアプリケーションコンテンツがアップロードされるディレクトリへのパス。アプリケーションのコンテンツも、生成されたイメージのこの場所に含まれます。

/workspace

securityOptions

--securityOptions

文字列値の配列として提供される、ビルダーコンテナーに適用されるセキュリティオプション (英語)

["label=disable"] on Linux and macOS, [] on Windows
The plugin detects the target Java compatibility of the project using the JavaPlugin’s targetCompatibility property. When using the default Paketo builder and buildpacks, the plugin instructs the buildpacks to install the same Java version. You can override this behavior as shown in the builder configuration examples.
The default builder paketobuildpacks/builder-jammy-java-tiny:latest does not include a shell. Applications that require a shell to run a start script, as might be the case when the application plugin (英語) has been applied to generate a distribution zip archive, should override the builder configuration to use one that includes a shell, such as paketobuildpacks/builder-jammy-base:latest or paketobuildpacks/builder-jammy-full:latest.

Tags Format

The values provided to the tags option should be full image references. The accepted format is [domainHost:port/][path/]name[:tag][@digest].

If the domain is missing, it defaults to docker.io. If the path is missing, it defaults to library. If the tag is missing, it defaults to latest.

Some examples:

  • my-image leads to the image reference 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 プロパティを使用して設定できます。

以下は、ビルド時に Paketo Java buildpacks によって使用される JVM バージョンを構成する例 (英語) です。

  • Groovy

  • Kotlin

tasks.named("bootBuildImage") {
	environment["BP_JVM_VERSION"] = "17"
}
tasks.named<BootBuildImage>("bootBuildImage") {
	environment.put("BP_JVM_VERSION", "17")
}

ビルダーが実行されている Docker デーモンと buildpacks がアーティファクトをダウンロードするネットワークの場所の間にネットワークプロキシがある場合は、プロキシを使用するようにビルダーを構成する必要があります。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 buildpacks は、JAVA_TOOL_OPTIONS 環境変数を設定することにより、JVM ランタイム環境を構成 (英語) します。ビルドパックが提供する 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 および docker.io/library/${project.name}:${project.version} のようなプロジェクトの 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

Buildpacks

デフォルトでは、ビルダーはビルダーイメージに含まれている buildpacks を使用し、事前定義された順序で適用します。buildpacks の代替セットを提供して、ビルダーに含まれていない buildpacks を適用したり、含まれている buildpacks の順序を変更したりできます。1 つ以上の buildpacks が提供されている場合、指定された buildpacks のみが適用されます。

次の例では、.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"))
}

Buildpacks は、以下に示す任意の形式で指定できます。

CNB ビルダーにある buildpack（ビルダーに buildpack-id に一致する buildpack が 1 つしかない場合は、バージョンを省略できます）:

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

この例に示すように、publish オプションはコマンドラインでも指定できます。

$ gradle bootBuildImage --imageName=docker.example.com/library/my-app:v1 --publishImage

ビルダーのキャッシュとワークスペースの構成

CNB ビルダーは、イメージのビルドおよび起動時に使用されるレイヤーをキャッシュします。デフォルトでは、これらのキャッシュは、ターゲットイメージのフルネームから派生した名前で Docker デーモンに名前付きボリュームとして保存されます。プロジェクトのバージョンがイメージ名のタグとして使用されている場合など、イメージ名が頻繁に変更される場合、キャッシュが頻繁に無効化される可能性があります。

次の例に示すように、キャッシュボリュームは、代替名を使用してキャッシュライフサイクルをより細かく制御できるように構成できます。

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

ビルダーと 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 デーモン (英語) と通信できます。

Linux および macOS では、minikube の起動後に、コマンド eval $(minikube docker-env) を使用して環境変数を設定できます。

次の例に示すような接続の詳細を提供することにより、プラグインを minikube デーモンを使用するように構成することもできます。

  • 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 構成

プラグインは、コリマ [GitHub] (英語) が提供する 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...")
		}
	}
}