コンテナーイメージ
コンテナーイメージのエクステンション
Jib
エクステンション quarkus-container-image-jib
は、コンテナーイメージのビルドを実行するために Jib を使用しています。Jib を Quarkus で使用する主な利点は、すべての依存関係 (target/lib
の下にあるすべてのもの) が実際のアプリケーションとは別のレイヤーにキャッシュされるため、リビルドが非常に高速かつ小規模に (プッシュする場合) 行えることです。このエクステンションを使用するもう 1 つの重要な利点は、コンテナーイメージレジストリーにプッシュする機能さえあれば、専用のクライアントサイドツール (Docker など) やデーモンプロセス (Docker デーモンなど) を実行しなくてもコンテナーイーメージを作成できることです。
この機能を使用するには、以下のエクステンションをプロジェクトに追加します。
quarkus extension add container-image-jib
./mvnw quarkus:add-extension -Dextensions='container-image-jib'
./gradlew addExtension --extensions='container-image-jib'
必要なことがコンテナーイメージを構築するだけで、レジストリーへのプッシュが不要な場合 (基本的には quarkus.container-image.build=true を設定して quarkus.container-image.push のままにしておくことで、デフォルトは false になります)、このエクステンションはコンテナーイメージを作成し、Docker デーモンに登録します。これは、Docker がイメージのビルドには使われなくても必要であることを意味します。また、このモードを使用すると、docker images を実行するとコンテナーイメージが表示されます。
|
追加ファイルの追加
コンテナーイメージに追加のファイル(Quarkus のビルドで作成されたもの以外)を追加する必要がある場合があります。このような場合に対応するため、Quarkus は、src/main/jib
以下のファイルをすべてビルドされたコンテナーイメージにコピーします (これは、Jib Maven や Gradle プラグインがサポートしているのと基本的に同じ考え方です)。例えば、src/main/jib/foo/bar
が存在すると、/foo/bar
がコンテナファイルシステムに追加されます。
JVM デバッグ
ビルドしたコンテナイメージでは、実行時に条件付きでJavaデバッグを有効にする必要がある場合があります。
ベース・イメージが変更されていない場合(したがって ubi8/openjdk-11-runtime
、 ubi8/openjdk-17-runtime
、または ubi8/openjdk-21-runtime
が使用されている場合)、起動時にJVMをデバッグ・ポートでリッスンさせるために、 quarkus.jib.jvm-additional-arguments
設定プロパティを使用できます。
具体的な構成例:
quarkus.jib.jvm-additional-arguments=-agentlib:jdwp=transport=dt_socket\\,server=y\\,suspend=n\\,address=*:5005
他のベースイメージでは、環境変数の設定によりデバッグが可能になる起動スクリプトが提供されている場合があり、その場合はコンテナの起動時に環境変数を設定します。
カスタムエントリーポイント
最後に、 quarkus.jib.jvm-entrypoint
設定プロパティを使用すると、コンテナのエントリポイントを完全にオーバーライドすることができるため、JVMのデバッグ構成をハードコードするか、詳細を処理するスクリプトを指定することができます。
たとえば、ベースイメージ ubi8/openjdk-11-runtime
、 ubi8/openjdk-17-runtime
、 ubi8/openjdk-21-runtime
を使用してコンテナをビルドする場合、アプリケーションのプロパティファイルにエントリポイントをハードコードすることができます。
quarkus.jib.jvm-entrypoint=java,-Dcustom.param=custom_value,-jar,quarkus-run.jar
または、カスタムスタートアップスクリプトを作成し、プロパティファイルで参照することもできます。この方法は、環境変数を使用してアプリケーションのパラメータを設定する必要がある場合に有効です。
quarkus.jib.jvm-entrypoint=/bin/sh,run-java.sh
java \
-Djavax.net.ssl.trustStore=/deployments/truststore \
-Djavax.net.ssl.trustStorePassword="$TRUST_STORE_PASSWORD" \
-jar quarkus-run.jar
/home/jboss は、ベースイメージ ubi8/openjdk-11-runtime , ubi8/openjdk-17-runtime , ubi8/openjdk-21-runtime ( ubi8/openjdk-17-runtime 用の Dockerfile ) にある Quarkus バイナリすべての WORKDIR です。
|
マルチモジュールプロジェクトとレイヤリング
Quarkusアプリケーションを1つのモジュールとし、さらにさまざまなサポートプロジェクトの依存関係を他のモジュールとして含むマルチモジュールプロジェクトを構築する場合、Quarkusでは、サポートモジュールが通常のアプリケーション依存関係よりも頻繁に変更されることを想定して、それらのサポートモジュールを他のアプリケーション依存関係とは別のコンテナイメージレイヤーに配置することをサポートしています。このため、アプリケーションの依存関係に変更がない場合は、リビルドを高速に行うことができます。
この機能を有効にするには、ビルドツール起動時にシステムプロパティとして、またはビルドツールプロパティとして、プロパティ quarkus.bootstrap.workspace-discovery
を true
に設定する必要があります。このプロパティは、ビルドプロセスの非常に早い段階で認識される必要があるため、 application.properties
で設定しても正しく 機能しません 。
AppCDS
Quarkusは、Jibを使用したコンテナイメージの生成時に、 アプリケーションクラスデータ共有 アーカイブを生成して含めることをサポートしています。詳細については、 AppCDSのドキュメント を参照してください。
Docker
エクステンション quarkus-container-image-docker
は、Docker ビルドを実行するために src/main/docker
下で Docker バイナリーと生成された Dockerfiles を使用しています。
この機能を使用するには、以下のエクステンションをプロジェクトに追加します。
quarkus extension add container-image-docker
./mvnw quarkus:add-extension -Dextensions='container-image-docker'
./gradlew addExtension --extensions='container-image-docker'
quarkus-container-image-docker
エクスンテンションは、docker buildx build
を使って、 マルチプラットフォーム (またはマルチアーキ) イメージを作成することができます。以下の Dockerオプション のセクションにある quarkus.docker.buildx.*
の設定項目を参照してください。
つまり、一度に複数のプラットフォーム用のイメージをビルドしたい場合(例: |
Podman
拡張機能 quarkus-container-image-podman
は、コンテナビルドを実行するために Podman と src/main/docker
の下に生成された Dockerfiles
を使用します。
この機能を使用するには、以下のエクステンションをプロジェクトに追加します。
quarkus extension add container-image-podman
./mvnw quarkus:add-extension -Dextensions='container-image-podman'
./gradlew addExtension --extensions='container-image-podman'
DockerとPodmanエクステンションの使い分け
Podmanは Docker互換のAPIを 公開しているため、 Docker拡張 機能はPodmanと常に下位互換性があります。Docker拡張機能を使用して、Podmanでコンテナイメージを構築できます( QuarkusでPodmanを使用するガイド を参照してください)。 DockerとPodmanのどちらかに特化した処理を行う場合は、それぞれ 例えば、マルチプラットフォームイメージのビルドはDockerとPodmanで実装が異なります。Dockerは buildxプラグイン を使用しますが、Podmanはマルチプラットフォームイメージを ネイティブに ビルドできます。このため、その機能を実行するには特定の拡張機能を使用する必要があります。 |
OpenShift
エクステンション quarkus-container-image-openshift
は、OpenShift クラスタ内でコンテナのビルドを実行するために OpenShift バイナリビルドを使用しています。バイナリビルドの背景にある考え方は、アーティファクトとその依存関係をクラスタにアップロードするだけで、ビルド中にそれらがビルダーイメージ(デフォルトは fabric8/s2i-java
)にマージされるというものです。
このアプローチの利点は、クラスターへの変更を簡単にロールアウトできる OpenShift の DeploymentConfig
と組み合わせることができることです。
この機能を使用するには、以下のエクステンションをプロジェクトに追加します。
quarkus extension add container-image-openshift
./mvnw quarkus:add-extension -Dextensions='container-image-openshift'
./gradlew addExtension --extensions='container-image-openshift'
OpenShiftのビルドでは、 BuildConfig
、ビルダーイメージ用と出力イメージ用の2つの ImageStream
リソースを作成する必要があります。このようなオブジェクトの作成は、Quarkus Kubernetesエクステンションによって行われます。
Buildpack
quarkus-container-image-buildpack
は、コンテナイメージのビルドを行うために buildpacks を使用しています。buildpacksは、実際のビルドにDockerデーモンを使用します。buildpacksはDockerの代替品をサポートしていますが、このエクステンションはDockerでのみ動作します。
さらに、ユーザーはどのビルドイメージを使用するかを設定する必要があります(デフォルトのイメージは提供されていません)。例えば、以下のようになります。
quarkus.buildpack.jvm-builder-image=<jvm builder image>
またはネイティブの場合、
quarkus.buildpack.native-builder-image=<native builder image>
この機能を使用するには、以下のエクステンションをプロジェクトに追加します。
quarkus extension add container-image-buildpack
./mvnw quarkus:add-extension -Dextensions='container-image-buildpack'
./gradlew addExtension --extensions='container-image-buildpack'
buildpack コンテナイメージエクステンションを使用する際には、プロパティ設定に quarkus.container-image.build=true を追加しないことを強くお勧めします。代わりにビルドコマンドのオプションとして渡すことをお勧めします。
|
ビルド
プロジェクト用のコンテナーイメージを作成するには、Quarkus がサポートしている方法のいずれかで、 quarkus.container-image.build=true
を設定する必要があります。
quarkus build -Dquarkus.container-image.build=true
./mvnw install -Dquarkus.container-image.build=true
./gradlew build -Dquarkus.container-image.build=true
ネイティブコンテナイメージをビルドしたいときに、すでに既存のネイティブイメージがある場合は、 -Dquarkus.native.reuse-existing=true を設定すれば、ネイティブイメージのビルドは再実行されません。
|
@QuarkusIntegrationTest の利用
作成されたイメージでテストを実行するためには、Quarkus がサポートしている方法のいずれかで、 quarkus.container-image.build=true
を設定する必要があります。
./mvnw verify -Dquarkus.container-image.build=true
./gradlew quarkusIntTest -Dquarkus.container-image.build=true
プッシュ
プロジェクトにコンテナーイメージをプッシュするには、Quarkus がサポートしている方法のいずれかで、quarkus.container-image.push=true
を設定する必要があります。
quarkus build -Dquarkus.container-image.push=true
./mvnw install -Dquarkus.container-image.push=true
./gradlew build -Dquarkus.container-image.push=true
レジストリーが設定されていない場合 (quarkus.container-image.registry を使用) は、 docker.io がデフォルトとして使用されます。
|
複数のエクステンションから選択する
複数のエクステンションを同じビルドの一部として使用することは意味がありません。複数のコンテナイメージエクステンションが存在する場合は、エラーが発生してユーザーに通知されます。ユーザーは、不要なエクステンションを削除するか、 application.properties
を使用してエクステンションを選択することができます。
例えば、 container-image-docker
と container-image-podman
の両方が存在し、ユーザーが container-image-docker
を使用する必要がある場合:
quarkus.container-image.builder=docker
systemd-notify
との統合
QuarkusアプリケーションをPodmanとSystemdでLinuxサービスとしてデプロイするためにコンテナイメージをビルドする場合、 次のように Quarkus Systemd Notify Extension をアプリケーションの一部として含めることを検討するとよいかもしれません:
quarkus extension add io.quarkiverse.systemd.notify:quarkus-systemd-notify
./mvnw quarkus:add-extension -Dextensions='io.quarkiverse.systemd.notify:quarkus-systemd-notify'
./gradlew addExtension --extensions='io.quarkiverse.systemd.notify:quarkus-systemd-notify'
カスタマイズ
以下のプロパティーを使用して、コンテナーイメージのビルドプロセスをカスタマイズすることができます。
コンテナーイメージオプション
ビルド時に固定される構成プロパティ - 他のすべての構成プロパティは実行時にオーバーライド可能
Configuration property |
型 |
デフォルト |
---|---|---|
The group the container image will be part of Environment variable: Show more |
string |
|
The name of the container image. If not set defaults to the application name Environment variable: Show more |
string |
|
The tag of the container image. If not set defaults to the application version Environment variable: Show more |
string |
|
Additional tags of the container image. Environment variable: Show more |
list of string |
|
Custom labels to add to the generated image. Environment variable: Show more |
Map<String,String> |
|
The container registry to use Environment variable: Show more |
string |
|
Represents the entire image string. If set, then Environment variable: Show more |
string |
|
The username to use to authenticate with the registry where the built image will be pushed Environment variable: Show more |
string |
|
The password to use to authenticate with the registry where the built image will be pushed Environment variable: Show more |
string |
|
Whether or not insecure registries are allowed Environment variable: Show more |
boolean |
|
Whether or not a image build will be performed. Environment variable: Show more |
boolean |
|
Whether or not an image push will be performed. Environment variable: Show more |
boolean |
|
The name of the container image extension to use (e.g. docker, podman, jib, s2i). The option will be used in case multiple extensions are present. Environment variable: Show more |
string |
CI 環境の利用
さまざまな CI 環境では、Quarkus アプリケーションを作成してレジストリーをプッシュするために、コンテナーイメージ Quarkus エクステンションと組み合わせることで、すぐに使えるコンテナーイメージレジストリ-を利用できます。
例えば、 GitLab はこのようなレジストリーを提供しており、提供されている CI 環境では、環境変数 CI_REGISTRY_IMAGE
(詳しくは GitLab の ドキュメント を参照) を利用できるようになっています。なお、Quarkus ではこのように利用できます。
quarkus.container-image.image=${CI_REGISTRY_IMAGE}
プロパティと環境変数を組み合わせる方法については、 こちらをご覧ください。 |
Jib オプション
一般的なコンテナーイメージのオプションに加えて、container-image-jib
では以下のオプションも用意されています。
ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能
Configuration property |
型 |
デフォルト |
---|---|---|
The base image to be used when a container image is being produced for the jar build. When the application is built against Java 21 or higher, Environment variable: Show more |
string |
|
The base image to be used when a container image is being produced for the native binary build. The default is "quay.io/quarkus/quarkus-micro-image". You can also use "registry.access.redhat.com/ubi8/ubi-minimal" which is a bigger base image, but provide more built-in utilities such as the microdnf package manager. Environment variable: Show more |
string |
|
The JVM arguments to pass to the JVM when starting the application Environment variable: Show more |
list of string |
|
Additional JVM arguments to pass to the JVM when starting the application Environment variable: Show more |
list of string |
|
Additional arguments to pass when starting the native application Environment variable: Show more |
list of string |
|
If this is set, then it will be used as the entry point of the container image. There are a few things to be aware of when creating an entry point
Environment variable: Show more |
list of string |
|
If this is set, then it will be used as the entry point of the container image. There are a few things to be aware of when creating an entry point
Environment variable: Show more |
list of string |
|
Environment variables to add to the container image Environment variable: Show more |
Map<String,String> |
|
The username to use to authenticate with the registry used to pull the base JVM image Environment variable: Show more |
string |
|
The password to use to authenticate with the registry used to pull the base JVM image Environment variable: Show more |
string |
|
list of int |
|
|
The user to use in generated image Environment variable: Show more |
string |
|
The working directory to use in the generated image. The default value is chosen to work in accordance with the default base image. Environment variable: Show more |
string |
|
Controls the optimization which skips downloading base image layers that exist in a target registry. If the user does not set this property, then read as false. If Environment variable: Show more |
boolean |
|
List of target platforms. Each platform is defined using the pattern:
for example:
If not specified, OS default is linux and architecture default is Environment variable: Show more |
list of string |
|
The path of a file in which the digest of the generated image will be written. If the path is relative, the base path is the output directory of the build tool. Environment variable: Show more |
string |
|
The path of a file in which the id of the generated image will be written. If the path is relative, the base path is the output directory of the build tool. Environment variable: Show more |
string |
|
Whether or not to operate offline. Environment variable: Show more |
boolean |
|
Name of binary used to execute the docker commands. This is only used by Jib when the container image is being built locally. Environment variable: Show more |
string |
|
Sets environment variables used by the Docker executable. This is only used by Jib when the container image is being built locally. Environment variable: Show more |
Map<String,String> |
|
Whether to set the creation time to the actual build time. Otherwise, the creation time will be set to the Unix epoch (00:00:00, January 1st, 1970 in UTC). See Jib FAQ for more information Environment variable: Show more |
boolean |
|
Whether to set the modification time (last modified time) of the files put by Jib in the image to the actual build time. Otherwise, the modification time will be set to the Unix epoch (00:00:00, January 1st, 1970 in UTC). If the modification time is constant (flag is set to false so Unix epoch is used) across two consecutive builds, the docker layer sha256 digest will be different only if the actual files added by Jib to the docker layer were changed. More exactly, having 2 consecutive builds will generate different docker layers only if the actual content of the files within the docker layer was changed. If the current timestamp is used the sha256 digest of the docker layer will always be different even if the content of the files didn’t change. Environment variable: Show more |
boolean |
|
The directory to use for caching base image layers. If not specified, the Jib default directory is used. Environment variable: Show more |
string |
|
The directory to use for caching application layers. If not specified, the Jib default directory is used. Environment variable: Show more |
string |
Docker オプション
一般的なコンテナーイメージのオプションに加えて、container-image-docker
では以下のオプションも用意されています。
ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能
Configuration property |
型 |
デフォルト |
---|---|---|
Environment variable: |
string |
|
Environment variable: |
string |
|
Environment variable: |
Map<String,String> |
|
Environment variable: |
list of string |
|
Environment variable: |
string |
|
Environment variable: |
string |
|
Environment variable: |
list of string |
|
型 |
デフォルト |
|
Which platform(s) to target during the build. See https://docs.docker.com/engine/reference/commandline/buildx_build/#platform Environment variable: Show more |
list of string |
|
Sets the export action for the build result. See https://docs.docker.com/engine/reference/commandline/buildx_build/#output. Note that any filesystem paths need to be absolute paths, not relative from where the command is executed from. Environment variable: Show more |
string |
|
Set type of progress output ( Environment variable: Show more |
string |
Podman オプション
一般的なコンテナ・イメージ・オプションに加えて、 container-image-podman
には以下のオプションもあります:
ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能
Configuration property |
タイプ |
デフォルト |
---|---|---|
Environment variable: |
string |
|
Environment variable: |
string |
|
Environment variable: |
Map<String,String> |
|
Environment variable: |
list of string |
|
Environment variable: |
string |
|
Environment variable: |
string |
|
Environment variable: |
list of string |
|
Which platform(s) to target during the build. See https://docs.podman.io/en/latest/markdown/podman-build.1.html#platform-os-arch-variant Environment variable: Show more |
list of string |
OpenShift オプション
一般的なコンテナ・イメージ・オプションに加えて、 container-image-openshift
は以下のオプションも用意されています。
ビルド時に固定される設定プロパティ - 他のすべての設定プロパティは、実行時にオーバーライド可能
Configuration property |
タイプ |
デフォルト |
---|---|---|
The build config strategy to use. Environment variable: Show more |
|
|
The base image to be used when a container image is being produced for the jar build. The value of this property is used to create an ImageStream for the builder image used in the Openshift build. When it references images already available in the internal Openshift registry, the corresponding streams are used instead. When the application is built against Java 21 or higher, Environment variable: Show more |
string |
|
The base image to be used when a container image is being produced for the native binary build. The value of this property is used to create an ImageStream for the builder image used in the Openshift build. When it references images already available in the internal Openshift registry, the corresponding streams are used instead. Environment variable: Show more |
string |
|
The default Dockerfile to use for jvm builds Environment variable: Show more |
string |
|
The default Dockerfile to use for native builds Environment variable: Show more |
string |
|
The JVM arguments to pass to the JVM when starting the application Environment variable: Show more |
list of string |
|
Additional arguments to pass when starting the native application Environment variable: Show more |
list of string |
|
The directory where the jar is added during the assemble phase. This is dependent on the S2I image and should be supplied if a non default image is used. Environment variable: Show more |
string |
|
The resulting filename of the jar in the S2I image. This option may be used if the selected S2I image uses a fixed name for the jar. Environment variable: Show more |
string |
|
The directory where the native binary is added during the assemble phase. This is dependent on the S2I image and should be supplied if a non-default image is used. Environment variable: Show more |
string |
|
The resulting filename of the native binary in the S2I image. This option may be used if the selected S2I image uses a fixed name for the native binary. Environment variable: Show more |
string |
|
The build timeout. Environment variable: Show more |
|
|
The log level of OpenShift build log. Environment variable: Show more |
|
|
The image push secret to use for pushing to external registries. (see: https://cloud.redhat.com/blog/pushing-application-images-to-an-external-registry) Environment variable: Show more |
string |
期間フォーマットについて
To write duration values, use the standard 数字で始まる簡略化した書式を使うこともできます:
その他の場合は、簡略化されたフォーマットが解析のために
|