コンテナーイメージ
コンテナーイメージのエクステンション
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 デバッグ
There are cases where the built container image may need to have Java debugging conditionally enabled at runtime.
When the base image has not been changed (and therefore ubi8/openjdk-11-runtime
or ubi8/openjdk-17-runtime
is used), then the quarkus.jib.jvm-arguments
configuration property can be used in order to make the JVM listen on the debug port at startup.
The exact configuration is:
quarkus.jib.jvm-arguments=-agentlib:jdwp=transport=dt_socket\\,server=y\\,suspend=n\\,address=*:5005
Other base images might provide launch scripts that enable debugging when an environment variable is set, in which case you would set than environment variable when launching the container.
Finally, the quarkus.jib.jvm-entrypoint
configuration property can be used to completely override the container entry point and can thus be used to either hard code the JVM debug configuration or point to a script that handles the details.
Multi-module projects and layering
When building a multi-module project containing a Quarkus application as one module and various supporting project dependencies as other modules, Quarkus supports placing these supporting modules in a separate container image layer from the rest of the application dependencies, with the expectation that these supporting modules will change more frequently than the regular application dependencies - thus making a rebuild faster if the application dependencies have not changed.
To enable this feature, the property quarkus.bootstrap.workspace-discovery
needs to be set to true
either as a system property when invoking the build tool, either as a build tool property. Setting this property in application.properties
will not work because this property needs to be known very early on in the build process.
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"
The quarkus-container-image-docker
extension is capable of creating multi-platform (or multi-arch) images using docker buildx build
. See the quarkus.docker.buildx.*
configuration items in the Docker Options section below.
docker buildx build ONLY supports loading the result of a build to docker images when building for a single platform. Therefore, if you specify more than one argument in the quarkus.docker.buildx.platform property, the resulting images will not be loaded into docker images . If quarkus.docker.buildx.platform is omitted or if only a single platform is specified, it will then be loaded into docker images .
|
S2I
エクステンション quarkus-container-image-s2i
は、OpenShift クラスター内でコンテナービルドを実行するために S2I バイナリービルドを使用しています。バイナリービルドの考え方は、アーティファクトとその依存関係をクラスタにアップロードするだけで、ビルド中にそれらがビルダーイメージにマージされます (デフォルトは fabric8/s2i-java
)。
このアプローチの利点は、クラスターへの変更を簡単にロールアウトできる OpenShift の DeploymentConfig
と組み合わせることができることです。
この機能を使用するには、以下のエクステンションをプロジェクトに追加します。
quarkus extension add 'container-image-s2i'
./mvnw quarkus:add-extension -Dextensions="container-image-s2i"
./gradlew addExtension --extensions="container-image-s2i"
S2I のビルドでは、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"
When using the buildpack container image extension it is strongly advised to avoid adding quarkus.container-image.build=true in your properties configuration as it might trigger nesting builds within builds. It’s preferable to pass it as an option to the build command instead.
|
ビルド
プロジェクト用のコンテナーイメージを作成するには、Quarkus がサポートしている方法のいずれかで、 quarkus.container-image.build=true
を設定する必要があります。
quarkus build -Dquarkus.container-image.build=true
./mvnw clean package -Dquarkus.container-image.build=true
./gradlew build -Dquarkus.container-image.build=true
ネイティブコンテナイメージをビルドしたいときに、すでに既存のネイティブイメージがある場合は、 -Dquarkus.native.reuse-existing=true を設定すれば、ネイティブイメージのビルドは再実行されません。
|
Using @QuarkusIntegrationTest
To run tests on the resulting image, quarkus.container-image.build=true
needs to be set using any of the ways that Quarkus supports.
./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 clean package -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-s2i
の両方が存在し、ユーザーが container-image-docker
を使用する場合:
quarkus.container-image.builder=docker
カスタマイズ
以下のプロパティーを使用して、コンテナーイメージのビルドプロセスをカスタマイズすることができます。
コンテナーイメージオプション
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
---|---|---|
The group the container image will be part of Environment variable: |
string |
|
The name of the container image. If not set defaults to the application name Environment variable: |
string |
|
The tag of the container image. If not set defaults to the application version Environment variable: |
string |
|
Additional tags of the container image. Environment variable: |
list of string |
|
The container registry to use Environment variable: |
string |
|
Represents the entire image string. If set, then Environment variable: |
string |
|
The username to use to authenticate with the registry where the built image will be pushed Environment variable: |
string |
|
The password to use to authenticate with the registry where the built image will be pushed Environment variable: |
string |
|
Whether or not insecure registries are allowed Environment variable: |
boolean |
|
Whether or not a image build will be performed. Environment variable: |
boolean |
|
Whether or not an image push will be performed. Environment variable: |
boolean |
|
The name of the container image extension to use (e.g. docker, jib, s2i). The option will be used in case multiple extensions are present. Environment variable: |
string |
|
Custom labels to add to the generated image. Environment variable: |
|
CI 環境の利用
さまざまな CI 環境では、Quarkus アプリケーションを作成してレジストリーをプッシュするために、コンテナーイメージ Quarkus エクステンションと組み合わせることで、すぐに使えるコンテナーイメージレジストリ-を利用できます。
例えば、 GitLab はこのようなレジストリーを提供しており、提供されている CI 環境では、環境変数 CI_REGISTRY_IMAGE
(詳しくは GitLab の ドキュメント を参照) を利用できるようになっています。なお、Quarkus ではこのように利用できます。
quarkus.container-image.image=${CI_REGISTRY_IMAGE}
See this for more information on how to combine properties with environment variables. |
Jib オプション
一般的なコンテナーイメージのオプションに加えて、container-image-jib
では以下のオプションも用意されています。
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
---|---|---|
The base image to be used when a container image is being produced for the jar build. When the application is built against Java 17 or higher, Environment variable: |
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: |
string |
|
The JVM arguments to pass to the JVM when starting the application Environment variable: |
list of string |
|
Additional JVM arguments to pass to the JVM when starting the application Environment variable: |
list of string |
|
Additional arguments to pass when starting the native application Environment variable: |
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
- A valid entrypoint is jar package specific (see Environment variable: |
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
- A valid entrypoint depends on the location of both the launching scripts and the native binary file. To that end it’s helpful to remember that the native application is added to the Environment variable: |
list of string |
|
The username to use to authenticate with the registry used to pull the base JVM image Environment variable: |
string |
|
The password to use to authenticate with the registry used to pull the base JVM image Environment variable: |
string |
|
The ports to expose Environment variable: |
list of int |
|
The user to use in generated image Environment variable: |
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: |
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: |
boolean |
|
List of target platforms. Each platform is defined using the pattern: Environment variable: |
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: |
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: |
string |
|
Whether or not to operate offline. Environment variable: |
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: |
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: |
boolean |
|
Environment variables to add to the container image Environment variable: |
|
|
Sets environment variables used by the Docker executable. This is only used by Jib when the container image is being built locally. Environment variable: |
|
Docker オプション
一般的なコンテナーイメージのオプションに加えて、container-image-docker
では以下のオプションも用意されています。
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
---|---|---|
Path to the JVM Dockerfile. If not set ${project.root}/src/main/docker/Dockerfile.jvm will be used If set to an absolute path then the absolute path will be used, otherwise the path will be considered relative to the project root Environment variable: |
string |
|
Path to the JVM Dockerfile. If not set ${project.root}/src/main/docker/Dockerfile.native will be used If set to an absolute path then the absolute path will be used, otherwise the path will be considered relative to the project root Environment variable: |
string |
|
Images to consider as cache sources. Values are passed to Environment variable: |
list of string |
|
Environment variable: |
string |
|
Name of binary used to execute the docker commands. Environment variable: |
string |
|
Build args passed to docker via Environment variable: |
|
|
タイプ |
デフォルト |
|
Which platform(s) to target during the build. See https://docs.docker.com/engine/reference/commandline/buildx_build/#platform Environment variable: |
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: |
string |
|
Set type of progress output ( Environment variable: |
string |
S2I オプション
一般的なコンテナーイメージのオプションに加えて、container-image-s2i
では以下のオプションも用意されています。
ビルド時に固定される設定プロパティ - それ以外の設定プロパティは実行時に上書き可能
タイプ |
デフォルト |
|
---|---|---|
The base image to be used when a container image is being produced for the jar build Environment variable: |
string |
|
The base image to be used when a container image is being produced for the native binary build Environment variable: |
string |
|
The JVM arguments to pass to the JVM when starting the application Environment variable: |
list of string |
|
Additional JVM arguments to pass to the JVM when starting the application Environment variable: |
list of string |
|
Additional arguments to pass when starting the native application Environment variable: |
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: |
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: |
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: |
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: |
string |
|
The build timeout. Environment variable: |
|
期間フォーマットについて
期間のフォーマットは標準の 数値で始まる期間の値を指定することもできます。この場合、値が数値のみで構成されている場合、コンバーターは値を秒として扱います。そうでない場合は、 |