容器镜像
容器镜像扩展
Jib
quarkus-container-image-jib
扩展由 Jib 提供支持,用于执行容器镜像构建。使用 Jib 与 Quarkus 的主要好处是,所有依赖项(target/lib
下的所有内容)都缓存在与实际应用程序不同的层中,从而使重建非常快速和小巧(在推送时)。使用此扩展的另一个重要好处是,它提供了创建容器镜像的能力,而无需拥有任何专用的客户端工具(如 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 调试。
当基本镜像未更改时(因此使用 ubi9/openjdk-17-runtime
或 ubi9/openjdk-21-runtime
),可以使用 quarkus.jib.jvm-additional-arguments
配置属性,以便 JVM 在启动时侦听调试端口。
确切的配置是
quarkus.jib.jvm-additional-arguments=-agentlib:jdwp=transport=dt_socket\\,server=y\\,suspend=n\\,address=*:5005
其他基本镜像可能提供启动脚本,这些脚本在设置环境变量时启用调试,在这种情况下,您可以在启动容器时设置该环境变量。
自定义入口点
quarkus.jib.jvm-entrypoint
配置属性可用于完全覆盖容器入口点,因此可用于硬编码 JVM 调试配置或指向处理详细信息的脚本。
例如,如果使用基本镜像 ubi9/openjdk-17-runtime
或 ubi9/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 是基本镜像 ubi9/openjdk-17-runtime 和 ubi9/openjdk-21-runtime 中所有 quarkus 二进制文件的 WORKDIR(ubi9/openjdk-17-runtime 的 Dockerfile) |
多模块项目和分层
在构建包含 Quarkus 应用程序作为一个模块和各种支持项目依赖项作为其他模块的多模块项目时,Quarkus 支持将这些支持模块放在与其余应用程序依赖项不同的容器镜像层中,期望这些支持模块比常规应用程序依赖项更频繁地更改 - 因此,如果应用程序依赖项没有更改,则可以更快地重建。
要启用此功能,需要将属性 quarkus.bootstrap.workspace-discovery
设置为 true
,无论是在调用构建工具时作为系统属性,还是作为构建工具属性。在 application.properties
中设置此属性**不起作用**,因为此属性需要在构建过程的早期阶段才知道。
Docker
quarkus-container-image-docker
扩展使用 Docker 二进制文件和 src/main/docker
下生成的 Dockerfiles 以执行 Docker 构建。
要使用此功能,请将以下扩展添加到您的项目中。
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 构建容器镜像(请参见 将 Podman 与 Quarkus 一起使用指南)。 当执行特定于 Docker 或 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
和两个 ImageStream
资源,一个用于构建器镜像,一个用于输出镜像。此类对象的创建由 Quarkus Kubernetes 扩展负责。
Buildpack
quarkus-container-image-buildpack
扩展使用 buildpacks 以执行容器镜像构建。在底层,buildpacks 将使用 Docker 守护进程进行实际构建。虽然 buildpacks 支持 Docker 的替代方案,但此扩展仅适用于 Docker。
此外,用户将必须配置要使用的构建镜像(不提供默认镜像)。例如
quarkus.buildpack.jvm-builder-image=<jvm builder image>
或对于 native
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 quarkus deploy openshift
./mvnw install -Dquarkus.container-image.build=true
./gradlew build -Dquarkus.container-image.build=true
如果您想构建 native 容器镜像并且已经有一个现有的 native 镜像,则可以设置 -Dquarkus.native.reuse-existing=true ,并且不会重新运行 native 镜像构建。 |
使用 @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 quarkus deploy openshift
./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
集成
如果您正在构建容器镜像以使用 Podman 和 Systemd 将 Quarkus 应用程序部署为 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'
自定义
以下属性可用于自定义容器镜像构建过程。
容器镜像选项
构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖
配置属性 |
类型 |
默认 |
---|---|---|
字符串 |
||
字符串 |
|
|
字符串 |
|
|
容器镜像的附加标签。 环境变量: 显示更多 |
字符串列表 |
|
要添加到生成的镜像的自定义标签。 环境变量: 显示更多 |
Map<String,String> |
|
字符串 |
||
表示整个镜像字符串。如果设置,则忽略 环境变量: 显示更多 |
字符串 |
|
用于向将推送构建镜像的注册表进行身份验证的用户名 环境变量: 显示更多 |
字符串 |
|
字符串 |
||
布尔值 |
|
|
布尔值 |
||
布尔值 |
||
要使用的容器镜像扩展的名称(例如,docker、podman、jib、s2i)。如果存在多个扩展,则将使用此选项。 环境变量: 显示更多 |
字符串 |
Jib 选项
除了通用的容器镜像选项外,container-image-jib
还提供了以下选项
构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖
配置属性 |
类型 |
默认 |
---|---|---|
为 jar 构建生成容器镜像时要使用的基本镜像。当应用程序针对 Java 21 或更高版本构建时,默认使用 环境变量: 显示更多 |
字符串 |
|
为 native 二进制文件构建生成容器镜像时要使用的基本镜像。默认值为 "quay.io/quarkus/ubi9-quarkus-micro-image:2.0"。您还可以使用 "registry.access.redhat.com/ubi9/ubi-minimal",这是一个更大的基本镜像,但提供了更多内置实用程序,例如 microdnf 包管理器。 环境变量: 显示更多 |
字符串 |
|
字符串列表 |
|
|
启动应用程序时要传递给 JVM 的其他 JVM 参数 环境变量: 显示更多 |
字符串列表 |
|
字符串列表 |
||
如果设置了此项,则将用作容器镜像的入口点。在创建入口点时,需要注意以下几点
如果未设置此项,则将构建适当的默认入口点。最后,一个非常有用的工具,用于检查容器镜像层,可以大大有助于调试端点问题,是 dive 环境变量: 显示更多 |
字符串列表 |
|
如果设置了此项,则将用作容器镜像的入口点。在创建入口点时,需要注意以下几点
如果未设置此项,则将构建适当的默认入口点。最后,一个非常有用的工具,用于检查容器镜像层,可以大大有助于调试端点问题,是 dive 环境变量: 显示更多 |
字符串列表 |
|
要添加到容器镜像的环境变量 环境变量: 显示更多 |
Map<String,String> |
|
用于向注册表进行身份验证的用户名,该注册表用于提取基本 JVM 镜像 环境变量: 显示更多 |
字符串 |
|
用于向注册表进行身份验证的密码,该注册表用于提取基本 JVM 镜像 环境变量: 显示更多 |
字符串 |
|
int 列表 |
|
|
字符串 |
||
要在生成的镜像中使用的工作目录。选择默认值是为了与默认基本镜像配合使用。 环境变量: 显示更多 |
字符串 |
|
控制优化,该优化跳过下载目标注册表中已存在的基本镜像层。如果用户未设置此属性,则读取为 false。如果为 环境变量: 显示更多 |
布尔值 |
|
目标平台列表。每个平台都使用模式定义
例如
如果未指定,则操作系统默认为 linux,架构默认为 环境变量: 显示更多 |
字符串列表 |
|
将在其中写入生成的镜像摘要的文件路径。如果该路径是相对的,则基本路径是构建工具的输出目录。 环境变量: 显示更多 |
字符串 |
|
将在其中写入生成的镜像 ID 的文件路径。如果该路径是相对的,则基本路径是构建工具的输出目录。 环境变量: 显示更多 |
字符串 |
|
布尔值 |
|
|
用于执行 docker 命令的二进制文件的名称。仅当在本地构建容器镜像时,Jib 才会使用此名称。 环境变量: 显示更多 |
字符串 |
|
设置 Docker 可执行文件使用的环境变量。仅当在本地构建容器镜像时,Jib 才会使用此环境变量。 环境变量: 显示更多 |
Map<String,String> |
|
是否将创建时间设置为实际构建时间。否则,创建时间将设置为 Unix epoch(UTC 时间 1970 年 1 月 1 日 00:00:00)。有关更多信息,请参见 Jib FAQ 环境变量: 显示更多 |
布尔值 |
|
是否将 Jib 放入镜像中的文件的修改时间(上次修改时间)设置为实际构建时间。否则,修改时间将设置为 Unix epoch(UTC 时间 1970 年 1 月 1 日 00:00:00)。如果修改时间在两个连续构建中是恒定的(标志设置为 false,因此使用 Unix epoch),则仅当 Jib 添加到 docker 层的实际文件发生更改时,docker 层 sha256 摘要才会不同。更准确地说,只有在 docker 层中文件的实际内容发生更改时,2 个连续构建才会生成不同的 docker 层。如果使用当前时间戳,则即使文件的内容没有更改,docker 层的 sha256 摘要也总是不同。 环境变量: 显示更多 |
布尔值 |
|
用于缓存基础镜像层的目录。如果未指定,则使用 Jib 默认目录。 环境变量: 显示更多 |
字符串 |
|
用于缓存应用层的目录。如果未指定,则使用 Jib 默认目录。 环境变量: 显示更多 |
字符串 |
Docker 选项
除了通用的容器镜像选项外,container-image-docker
还提供了以下选项
构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖
配置属性 |
类型 |
默认 |
---|---|---|
JVM Dockerfile 的路径。如果设置为绝对路径,则将使用该绝对路径,否则该路径将被视为相对于项目根目录。如果未设置,则将使用 src/main/docker/Dockerfile.jvm。 环境变量: 显示更多 |
字符串 |
|
Native Dockerfile 的路径。如果设置为绝对路径,则将使用该绝对路径,否则该路径将被视为相对于项目根目录。如果未设置,则将使用 src/main/docker/Dockerfile.native。 环境变量: 显示更多 |
字符串 |
|
通过 环境变量: 显示更多 |
Map<String,String> |
|
要视为缓存源的镜像。这些值通过 环境变量: 显示更多 |
字符串列表 |
|
字符串 |
||
用于执行 docker/podman 命令的二进制文件的名称。此设置可以覆盖全局容器运行时检测。 环境变量: 显示更多 |
字符串 |
|
字符串列表 |
||
类型 |
默认 |
|
环境变量: 显示更多 |
字符串列表 |
|
设置构建结果的导出操作。参见 https://docs.dockerd.com.cn/engine/reference/commandline/buildx_build/#output。请注意,任何文件系统路径都需要是绝对路径,而不是相对于命令执行位置的路径。 环境变量: 显示更多 |
字符串 |
|
设置进度输出的类型( 环境变量: 显示更多 |
字符串 |
Podman 选项
除了通用的容器镜像选项外,container-image-podman
还提供了以下选项
构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖
配置属性 |
类型 |
默认 |
---|---|---|
JVM Dockerfile 的路径。如果设置为绝对路径,则将使用该绝对路径,否则该路径将被视为相对于项目根目录。如果未设置,则将使用 src/main/docker/Dockerfile.jvm。 环境变量: 显示更多 |
字符串 |
|
Native Dockerfile 的路径。如果设置为绝对路径,则将使用该绝对路径,否则该路径将被视为相对于项目根目录。如果未设置,则将使用 src/main/docker/Dockerfile.native。 环境变量: 显示更多 |
字符串 |
|
通过 环境变量: 显示更多 |
Map<String,String> |
|
要视为缓存源的镜像。这些值通过 环境变量: 显示更多 |
字符串列表 |
|
字符串 |
||
用于执行 docker/podman 命令的二进制文件的名称。此设置可以覆盖全局容器运行时检测。 环境变量: 显示更多 |
字符串 |
|
字符串列表 |
||
构建期间要定位的平台。参见 https://docs.podman.org.cn/en/latest/markdown/podman-build.1.html#platform-os-arch-variant 环境变量: 显示更多 |
字符串列表 |
|
布尔值 |
|
OpenShift 选项
除了通用的容器镜像选项外,container-image-openshift
还提供了以下选项
构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖
配置属性 |
类型 |
默认 |
---|---|---|
|
|
|
为 jar 构建生成容器镜像时要使用的基础镜像。此属性的值用于为 Openshift 构建中使用的构建器镜像创建 ImageStream。当它引用 Openshift 内部注册表中已有的镜像时,将使用相应的流。当应用程序针对 Java 21 或更高版本构建时, 环境变量: 显示更多 |
字符串 |
|
为 native binary 构建生成容器镜像时要使用的基础镜像。此属性的值用于为 Openshift 构建中使用的构建器镜像创建 ImageStream。当它引用 Openshift 内部注册表中已有的镜像时,将使用相应的流。 环境变量: 显示更多 |
字符串 |
|
字符串 |
|
|
用于 native 构建的默认 Dockerfile 环境变量: 显示更多 |
字符串 |
|
字符串列表 |
||
启动 native 应用程序时要传递的其他参数 环境变量: 显示更多 |
字符串列表 |
|
在组装阶段添加 jar 的目录。这取决于 S2I 镜像,如果使用非默认镜像,则应提供。 环境变量: 显示更多 |
字符串 |
|
S2I 镜像中 jar 的最终文件名。如果所选 S2I 镜像对 jar 使用固定名称,则可以使用此选项。 环境变量: 显示更多 |
字符串 |
|
在组装阶段添加 native binary 的目录。这取决于 S2I 镜像,如果使用非默认镜像,则应提供。 环境变量: 显示更多 |
字符串 |
|
S2I 镜像中 native binary 的最终文件名。如果所选 S2I 镜像对 native binary 使用固定名称,则可以使用此选项。 环境变量: 显示更多 |
字符串 |
|
|
||
|
|
|
用于推送到外部注册表的镜像推送密钥。(参见:https://cloud.redhat.com/blog/pushing-application-images-to-an-external-registry) 环境变量: 显示更多 |
字符串 |
关于 Duration 格式
要写入 duration 值,请使用标准的 您还可以使用简化的格式,以数字开头
在其他情况下,简化格式将被转换为
|
Buildpack 选项
除了通用的容器镜像选项外,container-image-buildpack
还提供了以下选项
构建时固定的配置属性 - 所有其他配置属性都可以在运行时覆盖
配置属性 |
类型 |
默认 |
---|---|---|
在 jvm 模式下构建项目时要使用的 buildpacks 构建器镜像。 环境变量: 显示更多 |
字符串 |
|
在 native 模式下构建项目时要使用的 buildpacks 构建器镜像。 环境变量: 显示更多 |
字符串 |
|
构建项目时要使用的生命周期镜像。这是可选的,但可以用于覆盖构建器镜像中存在的生命周期。 环境变量: 显示更多 |
字符串 |
|
要强制构建的平台级别。通常,平台级别由构建器镜像支持的级别与平台实现支持的级别的交集确定。有时,强制平台到特定版本以强制构建期间的行为可能是有益的。 环境变量: 显示更多 |
字符串 |
|
构建器镜像是否应该被“信任”? 信任的构建器允许尝试使用 环境变量: 显示更多 |
布尔值 |
|
要传递给 buildpacks 的环境变量键/值。 环境变量: 显示更多 |
Map<String,String> |
|
要与注册表主机一起使用的用户名 环境变量: 显示更多 |
Map<String,String> |
|
要与注册表主机一起使用的密码 环境变量: 显示更多 |
Map<String,String> |
|
要与注册表主机一起使用的令牌 环境变量: 显示更多 |
Map<String,String> |
|
构建项目时要使用的 buildpacks 运行镜像。如果未提供,则运行镜像由构建器镜像确定。如果构建器镜像使用了扩展,它们可能会覆盖运行镜像。 环境变量: 显示更多 |
字符串 |
|
构建器/运行镜像的初始拉取超时(以秒为单位) 环境变量: 显示更多 |
整数 |
|
失败后增加构建器/运行镜像的拉取超时(以秒为单位) 环境变量: 显示更多 |
整数 |
|
整数 |
|
|
要使用的 DOCKER_HOST 值。此值通常是自动确定的,并且可以在需要时进行覆盖。如果未设置,则使用环境变量 DOCKER_HOST,如果未设置,则平台将测试 环境变量: 显示更多 |
字符串 |
|
要使用的 Docker 套接字的路径。此值通常是自动确定的,并且可以在需要时进行覆盖。套接字的路径可能会有所不同,尤其是在 docker/podman 守护程序在 VM 中运行时,如果 useDaemon 模式为 true,则此路径必须引用可用于在容器内部挂载套接字的路径,因此可能引用 VM 中套接字的路径,而不是主机中的路径。 环境变量: 显示更多 |
字符串 |
|
使用守护程序模式?buildpack 构建是否应该将 docker 套接字挂载到构建容器中。如果这是 false,则镜像将直接构建为远程注册表中的图层,这可能需要传递注册表凭据。默认为“true” 环境变量: 显示更多 |
布尔值 |
|
在构建期间使用指定的 docker 网络。当针对本地托管的 docker 注册表进行构建时,这可能很方便,在这种情况下,您将需要构建容器成为“主机”网络的一部分,以使其能够访问本地注册表。 环境变量: 显示更多 |
字符串 |
|
要使用的日志级别。在容器中执行构建阶段时要使用的日志级别。默认为“info”,支持的值为“info”、“warn”和“debug” 环境变量: 显示更多 |
字符串 |
|
布尔值 |
|