このドキュメントでは Paketo Buildpack を使用して Java アプリケーションのコンテナイメージを作成する方法を説明します。 Buildpack の振る舞いや設定方法を詳しく知りたいときは、Paketo Java Buildpack や Paketo Java Native Image Buildpack のリファレンスを参照してください。
このドキュメントでは Paketo Buildpacs サンプルアプリ を使用します。
それぞれの例では、リポジトリ直下を作業ディレクトリとしています。
git clone https://github.com/paketo-buildpacks/samples cd samplesCopied!
pack コマンド も使用します。
pack は Java Buildpack でビルドを実行できる Cloud Native Buildpack [platform][platform] の1つです。
例えば、Spring Boot アプリケーションの開発者なら Spring Boot Maven Plugin や Spring Boot Gradle Plugin を使用できます。
それぞれの例では、 Paketo Base ビルダー を初期値にしています。
pack config default-builder paketobuildpacks/builder:baseCopied!
Java アプリケーションのサンプルは、どれも actuator health endpoint で {"status":"UP"} を返すようになっています。
docker run --rm --tty --publish 8080:8080 samples/java curl -s http://localhost:8080/actuator/health | jq .Copied!
Java Buildpack は次のようなビルドツールでソースコードをビルドできるようになっています。
使用するビルドツールはアプリケーションディレクトリの内容に基づいて検出します。
ビルド処理は 対応しているいずれかの形式のアーティファクト を生成しなければなりません。 完了すると、buildpack は展開したアーカイブの内容でアプリケーションのソースコードを置き換えます。 その後の処理については コンパイル済みアーティファクトからのビルド を参照してください。
例：Maven でビルドする
次のコマンドは Maven プロジェクトのソースコードからコンテナイメージを作成します。
pack build samples/java \ --path java/mavenCopied!
注意：以降の内容は全ての設定項目を網羅したものではありません。設定項目について、詳しくはビルドツールに対応する Buildpack のリファレンスを参照してください。
以降の説明に登場する <TOOL> には MAVEN や GRADLE や LEIN や SBT のいずれかで置き換えることになります。
モジュールやアーティファクトを選択するには、次のような環境変数をビルド時に指定します。
BP_<TOOL>_BUILT_MODULE
BP_MAVEN_BUILT_MODULE=api と指定すると、Paketo Maven Buildpack は target/api/*.[jw]ar に対応するファイル名のアーティファクトを選択します。BP_<TOOL>_BUILT_ARTIFACT
target/*.[jw]ar、Gradle なら build/libs/*.[jw]ar）。ビルドツールに対応する Buildpack のリファレンスを参照してください。BP_<TOOL>_BUILT_MODULE に初期値以外が設定されているとしても、こちらの設定を優先します。BP_MAVEN_BUILT_ARTIFACT=out/api-*.jar と指定すると、Paketo Maven Buildpack は out/api-1.0.0.jar を発見します。以降の説明に登場する <TOOL> には MAVEN や GRADLE や LEIN や SBT のいずれかで置き換えることになります。
モジュールやアーティファクトを選択するには、次のような環境変数をビルド時に指定します。
BP_<TOOL>_BUILD_ARGUMENTS-Dmaven.test.skip=true package、Gradle なら --no-daemon assemble）。ビルドツールに対応する Buildpack のリファレンスを参照してください。BP_GRADLE_BUILD_ARGUMENTS=war と指定すると、Paketo Gradle Buildpack は ./gradlew war か gradle war を実行します（Gradle Wrapper の有無によって変化します）。maven バインディング のキーに settings.xml を指定すると、独自の Maven settings を使用できます。
<binding-name>
├── settings.xml
└── type
settings.xml ファイルには、プライベート Maven リポジトリへ接続するための資格情報を記述できます。
例: 独自の Maven Settings を構成する
作業 PC の settings.xml を使用して、pack コマンドでアプリケーションをビルドする手順を説明します。
mkdir java/maven/bindingCopied!
maven を含む type ファイルを作成します。
echo -n "maven" > java/maven/binding/typeCopied!
settings.xml を複製します。
cp ~/.m2/settings.xml java/maven/binding/settings.xmlCopied!
pack build コマンドの --volume フラグに指定します。
pack build samples/java \ --path java/maven \ --volume $(pwd)/java/maven/binding:/platform/bindings/my-maven-settingsCopied!
Buildpack を利用するアプリケーション開発者は、次のようなアーカイブ（の形式）からコンテナイメージをビルドできます。
Java Buildpack はアーカイブを展開した場所をアプリケーションディレクトリとして扱います。 指定されたアーカイブが何であれ、ほとんどのプラットフォームでは自動的に展開します。
Java Buildpack は war ファイルを検出すると Apache Tomcat(apache tomcat) をインストールします。 Java Buildpack の使用する Tomcat のバージョンについては、Paketo Java Buildpack のリリースノート を参照してください。 Tomcat の設定項目については Apache Tomcat Buildpack を参照してください。
指定したアーティファクトの形式に対応する Buildpack は、作成するコンテナイメージの起動コマンドを指定してくれます。
注意：アーティファクトの形式に応じて、 Apache Tomcat Buildpack 、Executable Jar Buildpack 、 Dist Zip Buildpack の3種類から1つ以上の Buildpack を選択します。しかし、最終的なコンテナイメージを作成するのはどれか1つの Buildpack です。ソースコードからビルドした場合 等、アーティファクトの形式を検出できない場合があります。
例：実行可能 jar ファイルをビルドする
Maven でビルドした実行可能 jar ファイルを使用して、pack コマンドでアプリケーションをビルドするには、次のように実行します。
cd java/maven ./mvnw package pack build samples/java \ --path /target/demo-0.0.1-SNAPSHOT.jarCopied!
作成したコンテナイメージは、「Maven でビルドする」でビルドしたイメージと同じになっているはずです。
作成したコンテナイメージに含まれる正確な JRE のバージョンは、BOM（Bill-of-Materials） から読み取ることができます。
例 JRE のバージョンを確認する
サンプルプロジェクトから作成したコンテナイメージ samples/java について、インストールされている JRE のバージョンを表示するには、次のように実行します。
pack inspect-image samples/app --bom | jq '.local[] | select(.name=="jre") | .metadata.version'Copied!
JVM のバージョンを指定するときは、ビルド時に次の環境変数を指定します。
BP_JVM_VERSION
BP_JVM_VERSION=8 あるいは BP_JVM_VERSION=8.* とした場合、Buildpack は Java 8 の JDK あるいは JRE の、最新のパッチリリースをインストールします。Java Buildpack では環境変数 JAVA_TOOL_OPTIONS で JVM の動作を調整するようになっています。
JVM の動作を調整する方法は2種類あります。
JAVA_TOOL_OPTIONS へ設定する内容を算出するために使用されます。
BPL_JVM_HEAD_ROOMBPL_JVM_LOADED_CLASS_COUNTBPL_JVM_THREAD_COUNTJAVA_TOOL_OPTIONS を指定します。ユーザーの指定した内容は Buildpack の構成した内容の最後に追加されます。同じ項目を指定した場合、ユーザーの指定した値を優先します。全ての設定項目については Bellsoft Liberica Buildpack のリファレンス を参照してください。
初期設定の Paketo Java Buildpack は Liberica JVM を使用します。 Liberica の代わりに使用できる JVM （と対応する Buildpack） は次のとおりです。
別の JVM を使用するときは、pack build コマンドに2つの --buildpack フラグを指定しなければなりません。
最初に JVM Buildpack を指定し、次に Paketo Java Buildpack を指定します（順番が重要です）。
そうすると、pack build は2つの JVM Buildpack を使用することになるのですが、最初に指定した Buildpack がビルドプランの要素として登録され、後に指定した Buildpack は何もしない状態になります。
次の例は Azul Zulu Buikdpack を使用しています。
pack build samples/jar \ --buildpack gcr.io/paketo-buildpacks/azul-zulu \ --buildpack paketo-buildpacks/javaCopied!
この方法には1つ欠点があります。 CA Certs Buildpack より先に JVM Buildpack を取得するので、JVM ベンダーの提供するコンテンツを取得するとき、CA 証明局は最新化されておらず、信頼できないコンテンツを取得してしまう場合があるのです。 ですが、ほとんどのユーザーには影響しないものだと考えています。 ほとんどの JVM Buildpack はデフォルトのシステムトラストストアに含まれている CA が書名した証明書を使用するURL（ドメイン）で提供されているはずだからです。
カスタマイズした JVM Buildpack を、既存の CA 認証局が署名してない証明書を使用する URL からダウンロードさせるときは、最初に CA Certs Buildpack を実行するといいでしょう。 CA Cert Buildpack を重複して実行することになりますが、ライフサイクルは2回目の実行を無視できるくらい簡潔なままです。
具体的には次のように実行します。
pack build samples/jar \ --buildpack paketo-buildpacks/ca-certificates \ --buildpack gcr.io/paketo-buildpacks/azul-zulu \ --buildpack paketo-buildpacks/javaCopied!
常にこのような使い方をしていても、メッセージや処理が冗長になるだけで特に問題はありません。 また、ほとんどのユーザーは CA Cert Buildpack を先頭にしなくても問題になりません。
初期設定の [Paketo Java Native Image Buildpack][bp/java-ntive-image] は GraalVM Native Image Toolkit を使用します。 代わりに使用できる Native Image Toolkit （と対応する Buildpack） は次のとおりです。
| JVM | Buildpack |
|---|---|
| Bellsoft Liberica | Paketo Bellsoft Liberica Buildpack |
別の Java Native Image Toolkit を使用するときは、pack build コマンドに2つの --buildpack フラグを指定しなければなりません。
最初に Java Native Image Toolkit Buildpack を指定し、次に Paketo Java Native Image Buildpack を指定します（順番が重要です）。
そうすると、pack build は2つの Native Image Toolkit Buildpack を使用することになるのですが、最初に指定した Buildpack がビルドプランの要素として登録され、後に指定した Buildpack は何もしない状態になります。
Bellsoft Liberica Buildpack を使う場合は次のように実行します。
pack build samples/native-image \ --buildpack paketo-buildpacks/bellsoft-liberica \ --buildpack paketo-buildpacks/java-native-imageCopied!
次のコマンドを実行すると、サンプルアプリケーションで作成したコンテナイメージの依存ライブラリを確認できます。
pack inspect-image samples/java --bom | \ jq '.local[] | select(.name=="dependencies") | .metadata.dependencies[].name'Copied!
Spring Boot Buildpack はクラスパスに Spring Cloud Bindings を追加します。
Spring CloudBindings は、バインディングに配置した資格情報と接続設定に基づいて、外部サービスへ接続するための設定を、実行時に自動的に構成します。
初期設定で自動構成機能は有効になっていますが、環境変数 BPL_SPRING_CLOUD_BINDINGS_ENABLED を指定すると無効にできます。
Java Buildpack は次のような APM と連携できるようになっています。
APM 連携機能は バインディング で有効にします。 ビルド時に適切なバインディング種類が存在する場合、対応する Java エージェントをコンテナイメージに埋め込みます。 APM へ接続するための資格情報は、実行時にバインディングから読み取ります。
例：Azure Application Insights に接続する
次のコマンドは、Azure Application Insights の Java エージェントをコンテナイメージに埋め込みます。
pack build samples/java \ --volume "$(pwd)/java/application-insights/binding:/platform/bindings/application-insights"Copied!
アプリケーションが Azure Application Insights へ接続するには正式な Instrumentation Key が必要です。
echo "<Instrumentation Key>" > java/application-insights/binding/InstrumentationKey docker run --rm --tty \ --env SERVICE_BINDING_ROOT=/bindings \ --volume "$(pwd)/java/application-insights/binding:/bindings/app-insights" \ samples/javaCopied!
ビルド時に環境変数 BP_DEBUG_ENABLED を指定すると、 Debug Buildpack により、Java アプリケーションがデバッグ接続を待ち受けるように設定します。
そして、実行時に環境変数 BPL_DEBUG_ENABLED を指定すると、Java アプリケーションがデバッグ接続を待ち受けるようになります。
デバッグ接続用の TCP ポート番号の初期値は 8000 ですが、実行時に環境変数 BPL_DEBUG_PORT で変更できます。
実行時に環境変数で BPL_DEBUG_SUSPEND を指定すると、デバッガがアタッチするまで JVM プロセスは実行を中断するようになります。
例：リモートデバッグ
リモートデバッグできるコンテナイメージを作成するには次のように実行します。
pack build samples/java \ --path java/jar \ --env BP_DEBUG_ENABLED=trueCopied!
デバッグ接続用の TCP ポートを公開するには次のようにコンテナイメージを実行します。
docker run --env BPL_DEBUG_ENABLED=true --publish 8000:8000 samples/javaCopied!
IDE のデバッガで公開した TCP ポートに接続できます。
ビルド時に環境変数 BP_JMX_ENABLED を指定すると、 JMX Buildpack が JMX を有効にします。
そして、実行時に環境変数 BPL_JMX_ENABLED を指定すると、Java アプリケーションへ JMX で接続できるようになります。
JMX 接続に使用する TCP ポート番号の初期値は 5000 ですが、環境変数 BPL_JMX_PORT で変更できます。
例: JMX を有効にする
JMX 接続できるコンテナイメージを作成するには次のように実行します。
pack build samples/java \ --path java/jar \ --env BP_JMX_ENABLED=trueCopied!
JMX 接続用の TCP ポートを公開するには次のようにコンテナイメージを実行します。
docker run --env BPL_JMX_ENABLED=true --publish 5000:5000 samples/javaCopied!
JConsole で公開した TCP ポートに接続できます。
コンテナイメージの CMD に、起動コマンドの引数を追加できます。
Kubernetes では container リソースの args フィールドへ指定します。
例: サーバーポート番号を指定する
アプリケーションの起動コマンドの引数で、待ち受けポート番号として 8081 を指定するには次のように実行します。
docker run --rm --publish 8081:8081 samples/java --server.port=8081 curl -s http://localhost:8081/actuator/healthCopied!
Buildpack の構成した起動コマンドは、コンテナイメージの ENTRYPOINT で変更できます。
例: 対話形式のシェルを実行する
対話形式で Bash を起動するには次のように実行します。
docker run --rm --entrypoint bash samples/javaCopied!
Buildpack で作成したコンテナイメージには、実行可能ファイル launcher が必ず存在します。
このファイルは、Buildpack の構成する環境変数を設定した状態で指定したコマンドを実行するために使用できます。
launcher は指定したコマンドを実行する前に、Buildpack の配置した全てのプロファイルスクリプトを実行します。
環境変数の値を実行時に計算するためです。
コンテナイメージの ENTRYPOINT に launcher を指定し、CMD に実行したいコマンドを指定すれば、Buildpack の構成した環境で指定したコマンドを実行できます。
例: Buildpack の構成した JAVA_TOOL_OPTIONS を確認する
Buildpack の構成した JAVA_TOOL_OPTIONS の値を表示するには次のように実行します。
docker run --rm --entrypoint launcher samples/java echo 'JAVA_TOOL_OPTIONS: $JAVA_TOOL_OPTIONS'Copied!
launcher に指定したコマンドは実行前にシェルで評価しますが、元のトークン区切りを保持します。
例えば、'JAVA_TOOL_OPTIONS: $JAVA_TOOL_OPTIONS' という文字列はシングルクォートで囲まれているため、$JAVA_TOOL_OPTIONS の部分はホストのシェルではなく、コンテナ上で評価されます。
Paketo Java Native Image Buildpack は、GraalVM の native image でビルドしたアプリケーションを含む、コンテナイメージを作成します。
Java Native Buildpack は 合成 Buildpack です。
build コマンドのそれぞれの段階は、それぞれの コンポーネント が制御するようになっています。
以降の説明では、基本的な設定項目を説明します。
全ての設定項目や、利用できる機能については対応するコンポーネント（Buildpack）のリファレンスを参照してください。
Java Native Image Buildpack では Java Buildpack と同じ ビルドツールや設定項目 を使用できます。 ただし、実行可能形式のjarファイル を生成しなければなりません。
Buildpack はコンパイルとパッケージングを完了すると、作成した jar ファイルを展開してアプリケーションのソースコードを置き換えます。 そして、 [実行可能形式の jar ファイルからビルド][building-from-an-executable-jar] します。
例： Maven で Native Image をビルドする
次のコマンドは Maven プロジェクトのソースコードからコンテナイメージを作成します。
pack build samples/java-native \ --env BP_NATIVE_IMAGE=true \ --path java/native-image/java-native-image-sampleCopied!
実行可能形式の jar ファイル を展開する方法でコンテナイメージを作成できます。 ほとんどのプラットフォームは指定されたファイルのアーカイブ形式を自動的に判断し、展開できます。
例：実行可能形式の jar ファイルから Native Image をビルドする
Maven プロジェクトのソースコードからビルドした実行可能形式の jar ファイルを pack コマンドに指定して、コンテナイメージを作成するときは次のように実行します。
cd samples/java/native-image ./mvnw package pack build samples/java-native \ --env BP_NATIVE_IMAGE=true \ --path java/native-image/java-native-image-sample/target/demo-0.0.1-SNAPSHOT.jarCopied!
作成したコンテナイメージは「Maven で Native Image をビルドする」でビルドしたイメージと同じになっているはずです。
作成したコンテナイメージに含まれる正確な Substrate VM のバージョンは、BOM（Bill-of-Materials） から読み取ることができます。
例 JRE のバージョンを確認する
サンプルプロジェクトから作成したコンテナイメージ samples/java-native について、インストールされている Substrate VM のバージョンを表示するには、次のように実行します。
pack inspect-image samples/java-native --bom | \ jq '.local[] | select(.name=="native-image-svm") | .metadata.version'Copied!
GraalVM は急速に進歩しているので、互換性を保証しなければならない場合は、コンテナイメージをビルドする GraalVM や関連するツールのバージョンを指定するといいでしょう。 JVM のバージョンのように直接指定することはできないのですが、代わりに Java Native Image Buildpack のバージョンを指定すれば、対応する GraalVM のバージョンを指定できます。
GraalVM と Java Native Image Buildpack のバージョンの対応関係は次のとおりです。
| GraalVM Version | Java Native Image Buildpack Version |
|---|---|
| 21.2 | 5.5.0 |
| 21.1 | 5.4.0 |
| 21.0 | 5.3.0 |
GraalVM 21.1 を使用するには次のように実行します。
pack build samples/native \ -e BP_NATIVE_IMAGE=true \ --buildpack gcr.io/paketo-buildpacks/ca-certificates \ --buildpack gcr.io/paketo-buildpacks/java-native-image:5.4.0Copied!
Last modified: September 13, 2021