docker-maven-plugin

docker-maven-plugin

1. 引言

这是一个用于管理 Docker 镜像和容器的 Maven 插件，其核心功能围绕 Docker 构建集成的两大方面展开：

1.1. 构建镜像

该插件的一个目的是创建包含实际应用程序的 Docker 镜像，这通过 docker:build 目标实现。将构建产物及其依赖项纳入镜像中非常简便。

支持多种配置构建的方式：

• 可以使用自定义配置语法来创建 Dockerfile。为了指定构件和其他文件，该插件采用了 maven-assembly-plugin 中的汇编描述符格式，将这些文件复制到 Docker 镜像中。

• 可以在外部 Dockerfile 中指定可插入的 Maven 属性。如果只需构建单个镜像且存在顶层 Dockerfile，这也是默认模式。详情请参阅 简单 Dockerfile 构建 了解这种零 XML 配置模式。

使用此插件构建的镜像可以通过 docker:push 推送到公共或私有的 Docker Registry。

1.2. 运行容器

借助此插件，您可以运行完全隔离的集成测试，无需担心共享资源的问题。端口可动态映射，并作为 Maven 属性提供给您的集成测试代码使用。

可以同时管理多个容器，这些容器能够相互链接或通过数据卷共享数据。容器的创建和启动通过 docker:start 目标实现，而停止和销毁则使用 docker:stop 目标。在集成测试中，这两个目标通常分别绑定到 pre-integration-test 和 post-integration-test阶段。建议使用 maven-failsafe-plugin进行集成测试，以确保即使测试失败也能停止 Docker 容器。

为了实现良好的隔离性，容器暴露的端口可以动态且灵活地映射到本地主机端口。通过指定一个 Maven 属性，可以轻松实现在容器启动后自动填充动态分配的端口号。随后，该属性可作为集成测试参数，用于连接至应用程序。

1.3. 配置

插件配置包含全局部分和一个在 <images> 列表中的图像特定配置清单，其中每张图像都在 <image> 标签内定义。具体示例请参见 下方 。

全局部分 包含适用于所有镜像的配置，例如 Docker URL 或用于与 Docker 主机通信的 SSL 证书路径。

然后，每个具体的图像配置包含三个部分：

• 一个通用的镜像部分，包含镜像名称和别名。
• 一个 <build> 配置，用于指定镜像的构建方式
• 一个 <run> 配置，描述应如何创建和启动容器。
• 一个 <copy> 配置，描述如何将容器中的文件和目录复制到主机。

<build>、<run> 和 <copy> 部分为可选，可省略。

1.4. 示例

以下例子中指定了两个镜像。一个是来自 Docker Hub 的官方 PostgreSQL 9 镜像，内部通过别名 “database” 引用。它仅包含一个 <run> 部分，声明启动时应等待直到日志输出匹配给定的文本模式。接下来是一个 “service” 镜像，包含 <build> 部分。该镜像创建时会在 /maven 目录下存放构件和依赖项（这些内容通过汇编描述符指定）。此外，它还指定了容器的启动命令，本例中该命令会通过汇编描述符复制过来的 jar 文件启动一个微服务。同时该镜像还暴露了 8080 端口。在 <run> 部分，这个端口被映射到一个动态选择的端口，然后赋值给 Maven 属性 ${tomcat.port}。例如，集成测试可以利用这一属性来访问该微服务。其中关键部分在于 <links> 标签段，它表明别名为 “database” 的镜像被链接至 “service” 容器内，使得后者能够通过常规 Docker 方式（即通过以 DB_为前缀的环境变量）访问内部端口。

可以按任意顺序指定镜像，插件将负责处理正确的启动顺序（若检测到循环依赖关系，则会中止操作）。

示例插件配置

<configuration>
  <images>
    <image>
      <alias>service</alias> 
      <name>fabric8/docker-demo:${project.version}</name>
      <build>
        <from>java:8</from>
        <assembly>
          <descriptor>docker-assembly.xml</descriptor>
        </assembly>
        <cmd>
          <shell>java -jar /maven/service.jar</shell>
        </cmd>
      </build>

      <run>
        <ports>
          <port>tomcat.port:8080</port>
        </ports>
        <wait> 
          <http>
            <url>http://localhost:${tomcat.port}/access</url>
          </http>
          <time>10000</time>
        </wait>
        <links>
          <link>database:db</link>
        </links>
      </run>

      <copy> 
        <entries>
          <entry>
            <containerPath>/etc/hosts</containerPath> 
            <hostDirectory>${project.build.directory}</hostDirectory> 
          </entry>
        </entries>
      </copy>
    </image>

    <image>
      <alias>database</alias> 
      <name>postgres:9</name>
      <run>
        <wait> 
          <log>database system is ready to accept connections</log>
          <time>20000</time>
        </wait>
      </run>
    </image>
  </images>
</configuration>

1. Java 服务的镜像配置，别名为 “service”，名称为 fabric8/docker-demo:${project.version}
2. 构建配置 定义了如何创建 Docker 镜像
3. 基础镜像，此处为 java:8
4. 可以通过 装配描述符 指定镜像内容
5. 默认命令 创建容器时运行的命令。
6. 运行配置 定义了如何从此镜像创建容器
7. 端口映射 定义了容器端口应如何映射到主机端口
8. 等待 部分，这是服务启动时的就绪检查
9. 网络链接 描述了该服务的容器如何与数据库容器相连
10. 第二张图片是一个纯数据库镜像，仅用于运行（因此没有 <build> 部分）。别名用于上述网络链接部分。
11. 等待 Docker 容器启动时对应的输出出现在 stdout 上。
12. 复制配置 定义了容器的哪些文件和目录应通过 docker:copy 目标复制到主机
13. 定义应将容器中的哪个文件复制到主机
14. 定义将容器内文件复制到宿主机的目标目录

1.5. 功能特性

其他亮点，随机排列如下：

• 自动拉取镜像并显示进度指示器
• 等待容器启动的条件可以是基于时间、某个 URL 的可访问性，或是日志输出中的特定模式。
• 支持 SSL 认证 及 OpenShift 凭证
• Docker 机器支持
• 灵活的注册表处理（即注册表可作为元数据指定）
• 在～/.m2/settings.xml（即 pom.xml 之外）中指定用于推送和拉取的 加密 仓库密码的规范
• 彩色输出
• 监视 项目变更并自动重建镜像
• 属性 作为 XML 配置的替代方案
• 支持通过 TCP 接收 http 或 https 请求的 Docker 守护进程及 Unix 套接字

2. 安装

该插件可从 Maven 中央仓库获取，并可按如下方式连接至集成前 / 后阶段。配置参数及可用目标说明如下。

示例

<plugin>
  <groupId>io.fabric8</groupId>
  <artifactId>docker-maven-plugin</artifactId>
  <version>0.48.0</version>

  <configuration>
     ....
     <images>
        <!-- A single's image configuration -->
        <image>
           ....
        </image>
        ....
     </images>
  </configuration>

  <!-- Connect start/stop to pre- and
       post-integration-test phase, respectively if you want to start
       your docker containers during integration tests -->
  <executions>
    <execution>
       <id>start</id>
       <phase>pre-integration-test</phase>
       <goals>
         <!-- "build" should be used to create the images with the
              artifact -->
         <goal>build</goal>
         <goal>start</goal>
       </goals>
    </execution>
    <execution>
       <id>stop</id>
       <phase>post-integration-test</phase>
       <goals>
         <goal>stop</goal>
      </goals>
    </execution>
  </executions>
</plugin>

使用此插件时，您可采用自定义打包方式配合特定生命周期配置，以保持 pom 文件简洁。目前提供三种打包变体供选择：

• docker：这将 docker:build 绑定到 package 阶段，docker:start 和 docker:stop 分别绑定到 pre-integration 和 post-integration 阶段。同时，docker:push 被绑定到 deploy 阶段。
• docker-build：与 docker 打包方式类似，不同之处在于默认不配置集成测试。
• docker-tar：创建一个所谓的 Docker tar 归档文件，用作构建产物，后续可用于构建镜像。该归档主要包含一个 Dockerfile 及其支持文件。更多详情请参阅 docker:source。

这些打包定义包含了 jar 生命周期的相关方法，因此非常适合简单的微服务风格项目。

示例

<pom>
  <artifactId>demo</artifactId>
  <version>0.0.1</version>
  <packaging>docker</packaging>
  ...
  <build>
    <plugins>
      <plugin>
        <groupId>io.fabric8</groupId>
        <artifactId>docker-maven-plugin</artifactId>
        <extensions>true</extensions>
        <configuration>
          <images>
            <image>
            ...
            </image>
          </images>
        </configuration>
      </plugin>
    </plugins>
    ....
  </build>
</pom>

这将生成 jar 包（如有），构建 Docker 镜像，启动配置的 Docker 容器，运行集成测试，并在执行 mvn install命令时停止已配置的 Docker 容器。通过 mvn deploy命令，您还可以将镜像推送到 Docker 配置中。请注意，<extensions>true</extensions> 在使用自定义生命周期时是必需的配置项。

本手册剩余部分将介绍如何为您的镜像配置插件。

3. 全局配置

全局配置参数定义了整体行为，例如与 Docker 主机的连接方式。对应的系统属性（括号内标注）可用于从外部进行设置。

Docker Maven 插件通过 Docker 远程 API 进行通信，因此必须指定 Docker 守护进程的 URL。该 URL 可通过 dockerHost 或 machine 配置指定，也可通过 DOCKER_HOST 环境变量设置。

Docker 远程 API 支持通过 SSL 及证书认证进行通信。证书路径可通过 certPath 或机器配置指定，也可通过 DOCKER_CERT_PATH 环境变量设置。

表 1. 全局配置

示例

<configuration>
   <dockerHost>https://localhost:2376</dockerHost>
   <certPath>src/main/dockerCerts</certPath>
   <useColor>true</useColor>
   .....
</configuration>

Docker Machine

该插件同样支持 Docker Machine（当然，需在本地预先安装）。可通过顶级 <machine> 配置段来提供 Docker Machine 的配置。此配置段支持以下选项：

表 2. Docker Machine 选项

当未配置 Docker 主机或无法通过环境变量获取时，将使用已配置的 Docker 机器。若该机器存在但未运行，则会自动启动；若机器不存在但 autoCreate 参数为 true，则会创建并启动该机器。否则，将输出错误信息。请注意，由于 autoCreate 机制创建的机器不会被 docker-maven-plugin 自动删除，如需清理需手动操作。

若未配置 <machine> 部分，可使用 Maven 属性 docker.machine.name 指定 Docker 机器名称。同理，将属性 docker.machine.autoCreate 设为 true 亦可自动创建 Docker 机器。

若需覆盖内部检测机制以始终禁用 Docker 机器支持，可使用属性 docker.skip.machine。

示例

<!-- Work with a docker-machine -->
<configuration>
  <machine>
    <name>maven</name>
    <autoCreate>true</autoCreate>
    <createOptions>
      <driver>virtualbox</driver>
      <virtualbox-cpu-count>2</virtualbox-cpu-count>
    </createOptions>
  </machine>
   .....
</configuration>

4. 镜像配置

该插件的配置以镜像为核心。每个要使用的镜像在配置的 <images> 元素内通过单独的 <image> 元素进行指定。

<image> 元素可以包含以下子元素：

表 3. 镜像配置

必须存在一个 <build> 或 <run> 部分（除非您使用的是 简单 Dockerfile 构建 模式）。这些内容在相应的目标章节中有详细说明。

示例

<configuration>
  ....
  <images>
    <image>
      <name>%g/docker-demo:0.1</name>
      <alias>service</alias>
      <run>....</run>
      <build>....</build>
    </image>
  </images>
</configuration>

在使用 Maven profiles 时，覆盖特定镜像的设置可能非常有用。为此，可以在<images>元素旁使用<imagesMap>元素。<imagesMap>中的每个条目对应一个镜像配置，其中镜像的别名被设置为映射条目的键。上文及下文的示例将生成完全相同的镜像配置。

示例

<configuration>
  ....
  <imagesMap>
    <service>
      <name>%g/docker-demo:0.1</name>
      <run>....</run>
      <build>....</build>
    </service>
  </images>
</configuration>

4.1. 镜像名称

在配置中使用 <name> 字段指定镜像名称时，您可以使用多个占位符，这些占位符在运行时由本插件替换。此外，您还可以使用由 Maven 自身解析的常规 Maven 属性。

替换同样适用于任何构建配置的标签中的 <tag> 字段。

4.2. 容器名称

类似于图像名称占位符，为了启动和停止容器，可以配置另一组占位符来命名要创建的容器。

这些占位符可用于顶层配置值‘containerNamePattern‘中，该值全局应用于创建的每个容器。 此全局模式可被每个镜像的 运行 配置单独覆盖。 如果两者均未提供，则默认使用模式 % n-% i。

在指定容器名称模式时，可使用以下占位符：

您可以将占位符以任意组合方式结合，这些占位符将在执行 docker:start、docker:stop 和 docker:watch 命令时被解析。

以下示例使用的容器名称模式为 % n-% i，这也是默认模式。给定镜像 fabric8io/dmp-sample-jolokia:latest，在执行 mvn docker:start 命令时，系统会首先尝试使用名称 dmp-sample-jolokia-1 创建容器。若该名称已被占用，则会第二次尝试使用 dmp-sample-jolokia-2。此过程将持续进行，直到找到一个未被占用的 “空闲” 名称。

类似地，当使用‘mvn docker:stop‘命令停止容器时，默认仅停止索引最高的容器。但如果不通过‘% i‘指定索引，则会停止所有通过‘docker:start‘启动的容器。如需停止所有通过‘% i‘模式命名的容器，请使用‘mvn docker:stop -Ddocker.allContainers‘参数。

4.3. 命名模式

需要引用名称不固定的镜像或容器的目标可能支持使用名称模式进行匹配。模式可采用 Ant 式语法或 Java 正则表达式。

4.3.1. Ant 式名称模式

Ant 路径匹配模式在操作路径名时遵循的惯例是：单个星号 * 匹配单个路径组件，而双星号 ** 可匹配多个组件。

将此风格应用于镜像名称时需稍作调整，因为镜像名称可能包含注册表信息、类似路径的仓库名称以及标签。考虑以下镜像名称示例：

• alpine:latest
• fluent/fluentd:edge
• quay.io/operator-framework/helm-operator:v0.9.0
• company.local:5000/division/project/artifact:version

与 Ant 文件系统路径匹配不同，冒号是一个重要标记，但仅在其末尾用于分隔版本与仓库时有效。此外，匹配仓库名称的模式需预见到，若镜像已标记为推送到注册表，则开头可能包含注册表名称。

考虑到这一点，名称模式通配符为：

• ? 匹配单个字符
• * 匹配零个或多个字符，直到遇到下一个斜杠或标签分隔符
• ** 匹配零个或多个字符，直到遇到标签分隔符
• **/ 匹配零个或多个字符，直到遇到标签分隔符为止，并确保如果匹配到任何字符，则最后一个匹配的字符必须是斜杠

Ant-like 命名模式示例

4.3.2. Java 正则表达式模式

要表示名称模式为 Java 正则表达式，需在正则表达式前添加 % regex [并在其后加上]。

Java 正则表达式模式示例

4.3.3. 名称模式列表

在诸如 docker:stop 和 docker:remove 等支持多模式的目标中，请使用逗号分隔各模式。

5. Maven 目标

本插件支持以下目标，具体内容将在后续章节详细说明。

表 4. 插件目标

请注意，所有目标彼此正交。例如，要为应用程序启动容器，通常需要先构建其镜像。docker:start 并不隐含构建镜像的操作，因此您应将其与 docker:build 结合使用。

5.1. docker 构建

此目标将构建所有配置中包含 <build> 部分的镜像，或者，若设置了全局配置变量过滤器（属性：docker.filter），则仅构建该变量中列出的镜像（以逗号分隔）。

构建镜像有两种不同的模式：

• 内联插件配置

通过内联插件配置，构建镜像所需的全部信息都包含在插件配置中。默认情况下，它采用基于 XML 的标准插件配置，但也可以切换到基于属性的配置语法，如 外部配置 部分所述。由于 XML 配置语法更具结构化和类型化的特性，因此推荐使用。

在此模式下，Dockerfile 会根据配置中提取的所有指令动态生成。

• 外部 Dockerfile 或 Docker 归档文件

或者，也可以使用外部的 Dockerfile 模板或 Docker 存档。通过以下三种配置选项之一即可启用此模式。

• ContextDir 用于指定 Docker 构建上下文，当外部 Dockerfile 位于 Docker 构建上下文之外时使用。若未指定，则默认以 Dockerfile 所在父目录作为构建上下文。
• DockerFile 指定了特定的 Dockerfile 路径。若提供了 contextDir，则 Docker 构建上下文目录将设置为该路径；若未提供，则默认使用存储 Dockerfile 的目录作为上下文目录。
• DockerArchive 指定了一个直接加载的先前保存的镜像存档。此类 tar 存档可通过 docker save 命令或 docker:save 目标创建。如果提供了 dockerArchive，则不得同时指定 dockerFile 或 dockerFileDir。
• DockerFileDir（已弃用，请使用 contextDir）指定一个包含 Dockerfile 的目录，该文件将用于创建镜像。默认情况下，Dockerfile 的名称为 Dockerfile，但也可以通过 dockerFile 选项进行设置（见下文）。

所有路径既可以是绝对路径，也可以是相对路径（除非同时提供了 dockerFileDir 和 dockerFile，此时 dockerFile 不得为绝对路径）。默认情况下，相对路径会在 ${project.basedir}/src/main/docker 目录下查找。通过在配置中使用 ${project.basedir}，您可以轻松将其转换为绝对路径。

在 Dockerfile 模式下添加组件

位于 dockerFileDir 目录中的任何其他文件也将被添加到构建上下文中。 您还可以使用在 程序集配置 中指定的程序集。 不过，您需要在 Dockerfile 中自行通过 ADD 或 COPY 命令添加这些文件。 程序集的文件存储在构建上下文相对目录 maven / 中，但可以通过在程序集配置中使用 & lt;name> 选项更改程序集名称来修改此目录。

例如，可以通过以下方式添加文件：

示例

COPY maven/ /my/target/directory

这样，组装文件最终会被放置在容器内的 ‘/my/target/directory‘ 目录下。

如果该目录下存在.maven-dockerignore 文件（或替代的.maven-dockerexclude 文件），则此文件将用于构建时排除文件。该文件中的每一行均被视为 FileSet 排除模式 ，其用法与 maven-assembly-plugin 相同。虽然功能类似于使用 Docker 时的.dockerignore文件，但语法略有不同（因此采用了不同的命名）。 示例 .maven-dockerexclude 或.maven-dockerignore 展示了一个排除所有编译后 Java 类文件的范例。

示例 1. 示例.maven-dockerexclude 或.maven-dockerignore 文件

target/classes/** 
排除所有已编译的类

如果该目录下存在.maven-dockerinclude 文件，则该文件将用于仅包含构建所需的文件。此文件中的每一行均被视为 FileSet 排除模式 ，其用法与 maven-assembly-plugin 相同。 示例.maven-dockerinclude 展示了如何仅将构建生成的 jar 文件包含到 Docker 构建上下文中。

示例 2. .maven-dockerinclude 示例

target/*.jar
仅将 jar 文件添加到您的 Docker 构建上下文中。
除了 程序集配置 外，目前其他所有配置选项均被忽略。

简单的 Dockerfile 构建
当仅需通过 Dockerfile 构建单一镜像时，完全无需任何 XML 配置。 只需将 Dockerfile 置于顶层模块目录中，与 pom.xml 并列存放即可。 您仍可在插件配置中调整 全局参数 ，但一旦在 XML 配置中添加 & lt;image> 标签，就必须显式配置构建流程。

默认情况下，镜像名称根据 Maven 坐标（%g/%a:%l，有关参数的解释请参阅镜像名称，这些参数本质上是 Maven 的 GAV）设置。 此名称可通过属性 docker.name 进行设置。

若想为此镜像添加一些配置以便通过 docker:run 启动，您可以添加一个镜像配置，但不包含部分，这样 Dockerfile 也会被自动选用。不过，此方法仅适用于单一镜像场景。

过滤
fabric8-maven-plugin 能够像 maven-resource-plugin 那样，使用 Maven 属性对给定的 Dockerfile 进行过滤处理。默认情况下过滤功能处于开启状态，可通过构建配置 <filter>false</filter> 关闭。需要替换的属性需采用 ${...} 语法指定。替换范围涵盖 Maven 项目属性（如 ${project.artifactId}）、构建过程中设置的属性、命令行属性以及系统属性。未解析的属性将保持原样不变。

这种部分替换意味着您可以轻松地将其与 Docker 构建参数和环境变量引用混合使用，但需要谨慎操作。若想更明确地区分属性分隔符，以清晰分离 Docker 属性和 Maven 属性，您可以重新定义分隔符。通常，过滤选项的指定方式与资源插件中的分隔符相同。具体而言，若此配置包含 * 号，则星号左右两侧的部分将被用作分隔符。

例如，默认的${*}会以我们所熟知的格式解析 Maven 属性。 如果为指定单一字符，则该分隔符将同时用作起始和结束标记。 例如，一个@会触发以 @...@格式的参数，这与 maven-invoker-plugin 中的用法非常相似。 如果你想明确区分 Docker 构建参数，可以使用类似这样的方式。 这种财产替换形式仅适用于 Dockerfile。 如需替换 Docker 镜像目标文件中其他数据，请使用 maven-resource-plugin 或具有过滤功能的程序集配置，使其在 docker 构建上下文中可用。

示例
以下示例使用位于目录 src/main/docker/demo 中的 Dockerfile，并替换 Dockerfile 内所有格式为 @property@ 的属性。

user/demo demo @ ...

io.fabric8.runsh.RunShLoader
在 docker:build 构建过程中，这些类会被加载并调用特定的固定方法。

支持的方法如下：

方法
描述
添加额外文件

一个由 dmp 调用的静态方法，接受单个 File 参数。该方法指向一个名为 docker-extra 的目录，便于 Dockerfile 或程序集引用。通常，dmp 插件会创建自己的子目录，以避免与其他 dmp 插件发生冲突。

如果配置的插件未提供此名称和签名的方法，则该方法将被直接忽略。同时，无需实现任何接口以保持低耦合性。

以下是已知且受支持的官方 dmp 插件：

名称
G,A
描述
Run-java.sh

Fabric8.io，run-java

通用的 Java 应用程序启动脚本。dmp 插件会生成一个 target/docker-extra/run-java/run-java.sh 文件，可被包含在 Dockerfile 中（参见上述示例）。更多详情请参阅 run-java.sh 文档 。

查看 samples/run-java 获取一个完整可运行的示例。

5.1.1. 配置
所有与构建相关的配置都包含在镜像配置的 部分中。支持以下配置选项：

表 5. 构建配置（）
元素
描述
组件

指定多个装配配置，如 构建装配 中所述

装配

指定如 构建程序集 中所述的装配配置。

参数

指定在使用外部 Dockerfile 构建镜像时应使用的 Docker 构建参数 值的映射表。其键值语法与定义 Maven 属性（或标签、环境变量）时相同。当未使用外部 Dockerfile 时，此参数将被忽略。构建参数也可通过属性方式指定，具体说明见 构建参数 章节。

构建选项

指定构建镜像时提供给 Docker 守护进程的构建选项映射表。这些选项对应于 Docker 远程 API 中列出的查询参数，并仅限于简单选项（例如：内存、共享内存大小）。若使用构建配置原生支持的相应配置选项（如 squash、noCache、cleanup=remove 对应 buildoption forcerm=1，以及构建参数 args），则这些原生选项将覆盖此处提供的任何对应选项。键值语法与 设置环境变量和标签 中定义环境变量或标签时使用的语法相同。

Buildx

指定用于多架构镜像的 buildx 配置。请参阅 Buildx 选项

创建镜像选项

指定在拉取或导入镜像时提供给 Docker 守护进程的创建镜像选项的映射表。 这些选项对应于 Docker 远程 API 中列出的查询参数， 且仅限于简单选项（例如：fromImage、fromSrc、platform）。

清理

每次构建后清理悬空（未标记）镜像，包括由此类镜像创建的任何已停止容器。同时，清理因镜像重新标记、自动拉取基础镜像或自动拉取缓存来源镜像而产生的悬空镜像。默认值为 try，即尝试移除旧镜像，但若操作无法完成（例如因镜像仍被运行中的容器使用）不会导致构建失败。其他可选值为 remove（若希望构建因此失败）或 none（完全跳过清理步骤）。

上下文目录

指向构建上下文所用的目录路径。您可以通过‘dockerFile‘指定要使用的 Dockerfile，默认情况下会使用‘contextDir‘中找到的 Dockerfile。如果提供绝对文件路径，Dockerfile 也可以位于‘contextDir‘之外。详情请参阅 外部 Dockerfile。

命令

一个默认执行的命令（即启动此镜像的容器时若未提供命令则执行）。详情请参阅 启动参数 。

压缩

压缩模式决定了构建归档文件如何传输至 Docker 守护进程（docker:build）以及 Docker 构建归档如何作为源文件附加到此次构建中（docker:source）。可选值为 none（默认）、gzip 或 bzip2。

Dockerfile

指向 Dockerfile 的路径，该路径也会触发 Dockerfile 模式。详情请参阅 外部 Dockerfile。

DockerFileDir（已弃用，推荐使用 contextDir）

指向包含 Dockerfile 的目录路径并启用 Dockerfile 模式。详情请参阅 外部 Dockerfile。此选项已被_contextDir 取代，将在下一个主要版本中移除。

Docker 归档文件

指向已保存镜像存档的路径，随后进行导入。详情请参阅 Docker 存档 。

入口点

入口点允许您配置一个将作为可执行文件运行的容器。详情请参阅 启动参数 。

环境

如设置环境变量和标签中所述的环境。

过滤

启用并设置属性替换的分隔符。默认情况下，格式为${…}的属性会被替换为 Maven 属性。通过将此属性设为 false 可关闭属性替换功能。若使用单字符（如 @）作为分隔符，则采用该字符界定替换范围（例如 @...@）。更多详情请参阅过滤机制。

来自

此镜像应基于的基础镜像。若未指定，则默认使用 busybox:latest，适用于纯数据镜像场景。

来源扩展

基础镜像的扩展定义。此字段以value格式保存定义的映射。已知键包括：

：基础镜像名称

提供的标签优先级高于此处指定的名称。该标签对于此插件的扩展（如fabric8-maven-plugin）非常有用，这些扩展可以利用此处提供的附加信息进行评估。

健康检查

健康检查中描述的健康检查定义

镜像拉取策略

基础镜像的特定拉取策略。此设置将覆盖任何全局拉取策略。有关可能的值及默认设置，请参阅全局配置选项 imagePullPolicy。

加载名称模式

扫描 dockerArchive 中指定的归档文件，找到与该 名称模式 匹配的归档内实际仓库及标签。加载归档后，将 POM 中配置的 镜像名称 关联至归档内匹配到的仓库与标签。

标签

如 设置环境变量与标签 所述进行标签标注。

维护者

生成镜像的作者（MAINTAINER）字段

网络

为构建过程中的 RUN 指令设置网络模式

不使用缓存

不使用 Docker 的构建缓存。在运行 Maven 时，可通过设置系统属性 docker.noCache 来覆盖此选项。

压缩

将新构建的层压缩为单一新层。此设置可通过在运行 Maven 时设定系统属性 docker.squash 来覆盖。

缓存来源

一个指定用作缓存源的镜像名称的 元素列表。在构建镜像时，系统会尝试拉取这些镜像，但不会导致构建失败。遵循 imagePullPolicy 语义。

优化

若设为 true，则会将所有 runCmds 压缩为单个 RUN 指令，从而仅创建一个镜像层。

端口

暴露的端口列表由多个 元素组成，每个元素对应一个需开放的端口。各元素中的空白字符将被去除，空元素则会被忽略。端口格式可以是纯数字形式（如 “8080”），也可附带协议类型（如 “8080/tcp”）。

外壳

用于执行 runCmds 的 Shell。它包含 arg 元素，这些元素定义了可执行文件及其参数。

运行命令

构建过程中需要运行的命令。该部分包含传递给 shell 的 run 元素。每个元素的前后空白会被去除，空元素则被忽略。这些运行命令会紧接在 Dockerfile 中的 assembly 和 workdir 指令之后插入。请注意，此标签不应与指定容器启动时运行时行为的 部分混淆。

跳过

如果设为 true，则禁用镜像构建。此配置选项最好与 Maven 属性一起使用。

跳过推送

如果设为 true，则禁用镜像推送。此配置选项最好与 Maven 属性一起使用。

跳过标签

若设为 true，此插件将不会为镜像添加任何标签。属性：docker.skip.tag

标签

构建完成后为镜像添加的额外标签元素列表。每个元素的首尾空格将被去除，空元素将被忽略。

用户

Dockerfile 最终应切换到的用户（对应 Dockerfile 指令中的 USER）。

卷

创建容器卷的卷元素列表。每个元素的首尾空格将被去除，空元素将被忽略。

工作目录

启动容器时切换到的目录。

使用默认排除项

若设置为 true，此插件将不会在 Docker 镜像中包含任何隐藏文件。

根据此配置，该插件会创建一个内存中的 Dockerfile，复制已组装的文件，并通过其远程 API 调用 Docker 守护进程。

示例

java:8u40
john.doe@example.com

latest
${project.version}


8080


/path/to/expose


2147483648

5.1.2. 组装
在 内的 元素采用 XML 结构，定义了构建产物及其他文件如何进入 Docker 镜像。可以通过将多个 元素添加到 元素中来指定它们。如果在 中同时存在 和 ，则 元素会被视为 的最后一个子元素处理。

当提供多个程序集时，每个程序集会作为独立的层添加到镜像中。

表 6. 程序集配置（：）
元素
描述
名称

程序集名称，默认为 maven。此名称用于构建过程中创建的归档文件和目录。该目录存放由程序集指定的文件。若使用 外部 Dockerfile，此名称同时也是包含程序集文件的相对目录路径。 若提供多个程序集，则每个程序集必须具有唯一名称。

目标目录

将程序集内包含的文件和构件复制到容器中的目标目录。此选项的默认值为 /< 程序集名称 & gt;，因此若未设置不同名称，则为 /maven。当使用 外部 Dockerfile 时，此选项无意义。

内联

内联的装配描述符，如 装配描述符 所述。

描述符

指向一个程序集描述符文件的路径，其格式在 程序集描述符 下方有描述。

描述符引用

预定义程序集描述符的别名。可用别名同样在下方 Assembly Descriptor 中有所描述。

DockerFileDir

包含外部 Dockerfile 的目录。此选项已弃用，请直接在 部分使用 。

导出目标目录

指定是否应将 targetDir 导出为卷。默认情况下，此值为 true，除非 targetDir 设置为容器根目录（/）。当使用基础镜像（from）时，默认情况下也为 false，因为在这种情况下导出没有意义，且会不必要地浪费磁盘空间。

忽略权限

指定在创建带有模式目录的装配存档时是否应忽略现有文件权限。此值默认为 false。此属性已弃用，请改用忽略权限设置。

模式

模式：如何收集组装好的文件：

Dir : 文件直接复制（默认），

Tar：通过 tar 归档文件传输

Tgz : 通过压缩的 tar 归档文件传输

Zip : 通过 ZIP 压缩包传输

归档格式的优势在于能够更好地保留文件权限（因为复制过程独立于底层文件系统），但可能会触发 Maven 汇编器的内部错误（如 #171 中所述）。

权限

待添加文件的权限：

忽略文件现有权限，无视任何程序集配置

保持遵循程序集提供的权限设置，exec 用于为所有文件设置可执行位（在 Windows 系统下使用程序集模式目录时必须启用此选项）

auto to let the plugin select exec on Windows and keep on others.

keep is the default value.

tarLongFileMode

Sets the TarArchiver behaviour on file paths with more than 100 characters length. Valid values are: “warn”(default), “fail”, “truncate”, “gnu”, “posix”, “posix_warn” or “omit”

user

User and/or group under which the files should be added. The user must already exist in the base image.

It has the general format user[:group[:run-user]]. The user and group can be given either as numeric user- and group-id or as names. The group id is optional.

If a third part is given, then the build changes to user root before changing the ownerships, changes the ownerships and then change to user run-user which is then used for the final command to execute. This feature might be needed, if the base image already changed the user (e.g. to ‘jboss’) so that a chown from root to this user would fail. (This third user part has been marked as deprecated and will not be supported in future versions of this plugin.)

For example, the image jboss/wildfly use a “jboss” user under which all commands are executed. Adding files in Docker always happens under the UID root. These files can only be changed to “jboss” is the chown command is executed as root. For the following commands to be run again as “jboss” (like the final standalone.sh), the plugin switches back to user jboss (this is this “run-user”) after changing the file ownership. For this example a specification of jboss:jboss:jboss would be required.

In the event you do not need to include any artifacts with the image, you may safely omit this element from the configuration.

Assembly Descriptor
With using the inline, descriptor or descriptorRef option it is possible to bring local files, artifacts and dependencies into the running Docker container. A descriptor points to a file describing the data to put into an image to build. It has the same format as for creating assemblies with the maven-assembly-plugin with following exceptions:

are ignored, the assembly will allways use a directory when preparing the data container (i.e. the format is fixed to dir)

The is ignored since only a single assembly descriptor is used (no need to distinguish multiple descriptors)

Also you can inline the assembly description with a inline description directly into the pom file. Adding the proper namespace even allows for IDE autocompletion. As an example, refer to the profile inline in the data-jolokia-demo ‘s pom.xml.

Alternatively descriptorRef can be used with the name of a predefined assembly descriptor. The following symbolic names can be used for descriptorRef:

Table 7. Predefined Assembly Descriptors
Assembly Reference
Description
artifact-with-dependencies

Attaches project’s artifact and all its dependencies. Also, when a classpath file exists in the target directory, this will be added too.

artifact

Attaches only the project’s artifact but no dependencies.

dependencies

Attaches only the project’s dependencies. Also, when a classpath file exists in the target directory, this will be added too.

release-dependencies

Attaches only the project’s released (non-snapshot) dependencies.

snapshot-dependencies

Attaches only the project’s snapshot dependencies.

project

Attaches the whole Maven project but without the target/ directory.

rootWar

Copies the artifact as ROOT.war to the exposed directory. I.e. Tomcat will then deploy the war under the root context.

Examples




artifact-with-dependencies
…..
will add the created artifact with the name ${project.build.finalName}.${artifact.extension} and all jar dependencies in the targetDir (which is /maven by default).

All declared files end up in the configured targetDir (or /maven by default) in the created image.

deps-release release-dependencies /work/lib deps-snapshot snapshot-dependencies /work/lib artifact /work .....

Release dependencies (in jar format) added to /work/lib

Snapshot dependencies (in jar format) added to /work/lib

The created artifact with the name ${project.build.finalName}.${artifact.extension} added to /work

Maven peculiarities when including the artifact
If the assembly references the artifact to build with this pom, it is required that the package phase is included in the run. Otherwise the artifact file, can’t be found by docker:build. This is an old outstanding issue of the assembly plugin which probably can’t be fixed because of the way how Maven works. We tried hard to workaround this issue and in 90% of all cases, you won’t experience any problem. However, when the following warning happens which might lead to the given error:

[WARNING] Cannot include project artifact: io.fabric8:helloworld:jar:0.20.0; it doesn’t have an associated file or directory.
[WARNING] The following patterns were never triggered in this artifact inclusion filter:
o ‘io.fabric8:helloworld’

[ERROR] DOCKER> Failed to create assembly for docker image (with mode ‘dir’): Error creating assembly archive docker: You must set at least one file.
then you have two options to fix this:

Call mvn package docker:build to explicitly run “package” and “docker:build” in a chain.

Bind build to an to an execution phase in the plugin’s definition. By default docker:build will bind to the install phase is set in an execution. Then you can use a plain mvn install for building the artifact and creating the image.

If you are using the artifact or artifact-with-dependencies descriptor, it is possible to change the name of the final build artifact with the following:

Example

your-desired-final-name
…

Please note, based upon the following documentation listed here, there is no guarantee the plugin creating your artifact will honor it in which case you will need to use a custom descriptor like above to achieve the desired naming.

Currently the jar and war plugins properly honor the usage of finalName.

5.1.3. Startup Arguments
Using entrypoint and cmd it is possible to specify the entry point or cmd for a container.

The difference is, that an entrypoint is the command that always be executed, with the cmd as argument. If no entrypoint is provided, it defaults to /bin/sh -c so any cmd given is executed with a shell. The arguments given to docker run are always given as arguments to the entrypoint, overriding any given cmd option. On the other hand if no extra arguments are given to docker run the default cmd is used as argument to entrypoint.

See this stackoverflow question for a detailed explanation.

An entry point or command can be specified in two alternative formats:

Table 8. Entrypoint and Command Configuration
Mode
Description
shell

Shell form in which the whole line is given to shell -c for interpretation.

exec

List of arguments (with inner ) arguments which will be given to the exec call directly without any shell interpretation.

Either shell or params should be specified.

Example


java -jar $HOME/server.jar

or

Example



java
-jar
/opt/demo/server.jar


This can be formulated also more dense with:

Example

java -jar $HOME/server.jar
or

Example


java
-jar
/opt/demo/server.jar

5.1.4. Build Args
As described in section Configuration for external Dockerfiles Docker build arg can be used. In addition to the configuration within the plugin configuration you can also use properties to specify them:

Set a system property when running Maven, eg.: -Ddocker.buildArg.http_proxy=http://proxy:8001. This is especially useful when using predefined Docker arguments for setting proxies transparently.

Set a project property within the pom.xml, eg.:

Example
<docker.buildArg.myBuildArg>myValue</docker.buildArg.myBuildArg>
Please note that the system property setting will always override the project property. Also note that for all properties which are not Docker predefined properties, the external Dockerfile must contain an ARGS instruction.

5.1.5. Healthcheck
Healthchecks has been introduced since Docker 1.12 and are a way to tell Docker how to test a container to check that it’s still working. With a health check you specify a command which is periodically executed and checked for its return value. If the healtcheck return with an exit 0 the container is considered to be healthy, if it returns with 1 then the container is not working correctly.

The healtcheck configuration can have the following options

Table 9. Healthcheck Configuration
Element
Description
cmd

Command to execute, which can be given in an shell or exec format as described in Startup Arguments.

interval

Interval for how often to run the healthcheck. The time is specified in seconds, but a time unit can be appended to change this.

mode

Mode of the healthcheck. This can be cmd which is the default and specifies that the health check should be executed. Or none to disable a health check from the base image. Only use this option with none for disabling some healthcheck from the base image.

retries

How many retries should be performed before the container is to be considered unhealthy.

startPeriod

Initialization time for containers that need time to bootstrap. Probe failure during that period will not be counted towards the maximum number of retries. However, if a health check succeeds during the start period, the container is considered started and all consecutive failures will be counted towards the maximum number of retries. Given in seconds, but another time unit can be appended.

timeout

Timeout after which healthckeck should be stopped and considered to have failed. Given in seconds, but another time unit can be appended.

The following example queries an URL every 10s as an healthcheck:

Example


5m

3s

30m

3

curl -f http://localhost/ || exit 1

5.1.6. Multi-Architecture Build
Buildx is enabled when there is a non-empty element inside the configuration.

The local image cache cannot hold multi-architecture images nor can it have two platform specific images of the same name. Thus the build goal will build and save a single-architecture image to the local image cache if possible:

If the element contains a single platform, that image will be built.

If the element contains more than one platform including the native platform, the native platform be used.

If the element contains more than one platform not including the native platform, no image will be built.

These rules only apply to the image built and loaded into the local image cache with the build goal. They do not apply to the push goal which will always build and push either a single-architecture or multi-architecture image with whatever platforms are specified in the element.

The recommended configuration is to specify all supported platforms, including the native platform, in the element. This allows local integration testing of the build image from the local cache. During install or deploy phase, the build machine will build and push a multi-architecture image containing all specified platforms to the registry. Any downstream consumers, regardless of native architecture, will be able to use the multi-architecture image.

The element within defines how to build multi-architecture images.

Table 10. BuildX Options
Element
Description
builderName

Name of builder to use with buildx. If not supplied, the builder is named maven. The builder is created as necessary. The builder manages the build cache. Set to default to leverage the default buildx driver on local builds. This improves I/O performance, but will only work for the native platform.

driverOpts

Optional list of driverOpts to use with the builder. The driverOpts are passed to the builder when it is created.

nodeName

Specify the name of the node to be created or modified.

configFile

Configuration file for builder. Non-absolute files are relative to the maven project directory. If configFile starts with ~/, the configuration file is relative to the user’s home directory.

dockerStateDir

State directory for docker builder. This directory holds docker builder configurations and context state. Sharing a state directory across builds will share the cache and will decrease pull times. Non-absolute files are relative to the maven project directory. If dockerConfigDir starts with ~/, the configuration directory is relative to the user’s home directory.

平台

一个指定构建平台的 元素列表。平台遵循操作系统 / 架构的语法（例如 linux/amd64、linux/arm64、darwin/amd64）。每个 元素可包含以逗号分隔的平台列表。空的 元素将被忽略。若未指定平台架构，则不使用 buildx 功能。您可以使用

证明

证明模式的配置。‘‘元素可设置为 min、max 或 false；‘‘元素可设置为 true 或 false。其中，‘‘元素默认值为 min，‘‘元素默认值为 false。

缓存来源

一个传递给 docker buildx build 命令中 ——cache-from 选项的值。参见 docker buildx 参考文档 。

传递给 docker buildx build 命令中 ——cache-to 选项的值。请参阅 docker buildx 参考文档 。

一个传递给 docker buildx build 命令中 ——cache-to 选项的值。详见 docker buildx 参考文档 。

秘密

此选项允许 向 buildx 构建传递密钥 ，形式为 ——secret id=ID [,[env|src]=VALUE]。 对于环境变量，需添加一个 & lt;env> 元素，其中包含形如 & lt;secret name> 环境变量名 & lt;/secret name> 的变量列表（随后可在 Dockerfile 中引用该密钥名称）。 对于文件，则添加一个 & lt;files> 组件，其中包含形如 & lt;secret name> 文件路径 & lt;/secret name> 的路径列表。 具体示例可参阅 集成测试 部分。

示例
推荐配置是设置一个顶层属性，列出要构建的平台列表。

${project.groupId}.${project.artifactId} ${docker.platforms}

mvn clean deploy -Ddocker.platforms=linux/amd64,linux/arm64
5.2. docker: 启动
此目标负责创建并启动 Docker 容器。该目标会评估所有给定（且已启用）镜像配置中的 部分。

此外，您还可以将‘docker.follow‘指定为系统属性，这样‘docker:start‘命令将不会返回，而是会一直阻塞，直到按下 CTRL-C 为止。这类似于‘docker run‘命令的‘-i‘选项。此操作会自动启用‘showLogs‘，以便您查看容器内发生的情况。此外，在通过 CTRL-C 停止后，容器会被停止（但不会被移除，以便您进行事后分析）。‘docker:run‘是启用了‘docker.follow‘的‘docker:start‘的别名。

默认情况下，容器特定属性会作为 Maven 属性公开。这些属性的格式为‘docker.container..‘，其中‘‘是容器的名称（见下文），而‘‘是以下容器属性之一：

表 11. 提供的属性
属性
描述
IP 地址

容器的内部 IP 地址。

容器 ID

容器 ID

Net.<网络>.ip

容器在指定自定义网络中的内部 IP 地址。此功能仅适用于自定义网络。

可以不在 & lt;alias> 中使用固定属性键，而是通过镜像的 配置中的 exposedPropertyKey 选项进行设置。

例如，Maven 属性‘docker.container.tomcat.ip‘将保存别名为 “tomcat” 的容器的 Docker 内部 IP。您可以将全局配置‘exposeContainerInfo‘设置为空字符串，以不通过这种方式暴露容器信息，或者设置为其他字符串以使用不同于‘docker.container.‘的前缀。

5.2.1. 配置
除了 全局配置 外，此目标还支持以下全局配置选项。

表 12. 启动选项
元素
描述
属性
容器名称模式

所有容器创建时的默认命名模式。详情请参阅 容器名称 。

docker.containerNamePattern

显示日志

为了全局开启日志显示，‘showLogs‘可作为全局配置（即位于‘‘之外）。一旦设置，它将打印所有启动容器的标准输出和标准错误消息。其值可以提供一个以逗号分隔的镜像列表，指定哪些镜像的日志应被显示。这一功能在通过命令行使用系统属性‘docker.showLogs‘时尤为实用。

docker.showLogs

开始并行

在并行启动 Docker 镜像的同时，会遵守通过 链接 或 依赖关系 表达的依赖项。此选项可显著缩短启动时间，因为独立容器无需相互等待。

docker.startParallel

启动容器等待超时

覆盖所有容器的默认等待超时（）设置，单位为毫秒。当 docker-compose 配置中定义了健康检查，但默认的 10000 毫秒等待超时对于某些容器来说过短，无法达到健康状态时，重写此属性会显得尤为有用。

docker.startContainerWaitTimeout

配置元素包含以下子元素：

表 13. 运行配置（）
元素
描述
自动移除

如果为 true，容器退出时将自动移除。若已设置 重启策略 ，此设置无效。

CapAdd

添加元素列表，用于指定要加入容器的内核参数。

CapDrop

移除容器内核参数的 drop 元素列表。

系统控制参数

命名空间内核参数（sysctls）映射表，用于设置容器内的参数。

命令

容器启动完成后应执行的命令。若未指定，则使用镜像的默认命令。详情参见 启动参数 。

容器名称模式

容器创建时的命名模式。详情请参阅 容器命名策略 。

域名

容器的域名

域名

指定容器使用的 DNS 服务器的主机元素列表

DNS 搜索

指定 DNS 搜索域的主机元素列表

入口点

容器的入口点。详情请参阅 启动参数 。

环境

在容器启动时设置的环境变量作为子元素。它们以典型的 Maven 属性格式指定，如 环境与标签 中所述。

环境属性文件

指向包含环境变量的属性文件路径。若提供此文件，其中指定的变量将覆盖配置中定义的环境变量。

额外主机

需添加到容器‘/etc/hosts‘文件中的主机元素列表，格式为‘host:ip‘。此外，您也可以采用‘host:host‘格式指定主机元素，以便在容器启动时将右侧主机解析为 IP 地址。

暴露属性键

按照 上文 所述设置暴露容器属性的属性部分。这将优先于镜像别名（默认值）。例如，当此属性设置为 jboss 时，无论镜像如何命名，该容器的 IP 地址都会通过 Maven 属性 docker.container.jboss.ip 暴露出来。

主机名

容器的 hostname

镜像拉取策略

指定下载镜像时的拉取策略，此设置将覆盖全局拉取策略。有关可选值及默认设置，请参阅全局 imagePullPolicy 配置选项。

标签

应附加到容器的标签。这些标签以典型的 Maven 属性格式指定，如 环境与标签 中所述。

链接

用于连接容器的网络链接，如 网络链接 中所述。

日志

日志配置用于决定是否以及如何打印运行中容器产生的日志消息。此配置还可用于设置所使用的 日志驱动 。有关详细说明，请参阅 日志记录 章节。

隔离

此选项设置容器的隔离技术。有关详细说明，请参阅 隔离 。

内存

内存限制（以字节为单位）。

内存交换

总内存限制（内存 + 交换区）以字节为单位。将 memorySwap 设为与 memory 相同的值可禁用交换区。设为 - 1 则允许无限制的交换空间。

命名策略

此选项已弃用，请改用 containerNamePattern 作为容器名称的生成策略：

无：使用 Docker 随机分配的名称（默认）

Alias：使用镜像配置中指定的别名。如果已存在同名的容器，则会抛出错误。

网络

您容器的网络配置。

端口属性文件

映射端口属性写入的文件路径。该文件的格式及其用途也在 端口映射 中进行了说明。

端口

端口映射 用于将容器端口暴露给主机端口。

平台

指定启动 Docker 容器时使用的明确平台。可通过属性 docker.platform 设置，默认为本机平台。

特权模式

如果为真，则赋予容器对主机的完全访问权限

只读

如果为真，则将容器的根文件系统以只读方式挂载

重启策略

重启策略

安全选项

列出要添加到容器的内核安全选项的 元素列表。以下是一个示例。

共享内存大小

‘/dev/shm‘的大小（以字节为单位）。

跳过

若为真，则禁用容器的创建和启动。此选项最好与可从外部设置的 Maven 属性一起使用。

停止模式

指定如何停止正在运行的容器。支持的模式有 graceful（优雅）和 kill（强制），默认值为 graceful。

临时文件系统

列出包含 ‘‘ 元素的目录，这些目录将挂载临时文件系统。可选地，可以在冒号 ‘:‘ 后附加挂载选项。示例如下。

Ulimits

容器的 ulimits 设置。此列表包含 元素，每个元素包含三个子元素：

：要设置的 ulimit（例如 memlock）。请参阅 Docker 文档以了解可设置的可能值。

: 硬性限制

: 软限制

请参考以下示例。

用户

容器内使用的用户

用户命名空间

用户命名空间模式；例如，keep-id:uid=185

卷

用于绑定主机目录及其他容器卷的卷配置。详情请参阅 “卷” 部分。

等待

启动完成必须满足的条件。请参阅 等待 了解所有可能的启动条件等待方式。

工作目录

命令运行的工作目录

示例


-Xmx32m



development
${project.version}


jolokia.port:8080



memlock
-1
-1



/var/lib/mysql:size=10m
/opt/mydata


seccomp=unconfined


db



http://localhost:${jolokia.port}/jolokia

10000


DEMO
ISO8601
blue

java -jar /maven/docker-demo.jar

5.2.2. 环境与标签
在创建容器时，可以通过配置中的 env 参数设置一个或多个环境变量。

示例

/opt/jdk8
-Djava.security.egd=file:/dev/./urandom

若将此配置放入配置文件中，您便能轻松通过单一镜像创建多种测试变体（例如通过切换 JDK 或其他组件）。

此外，还可以通过参数‘envPropertyFile‘在插件配置外部设置环境变量。若指定此属性文件，系统将利用其中的键值对来设定环境变量。该文件中定义的环境变量会覆盖配置中指定的任何同名环境变量。

标签可以像环境变量一样以内联方式设置：

示例

<com.example.label-with-value>foo</com.example.label-with-value>
${project.version}
${project.artifactId}

5.2.3. 端口映射
配置包含一系列端口映射条目。每个元素的前后空格会被去除，空元素则被忽略。每条映射由多个部分组成，各部分间以冒号分隔，其格式与使用 Docker 命令行工具时通过 - p 选项指定的端口映射完全一致。

端口配置可以采用以下形式之一：

表 14. 端口映射格式
格式
描述
18080:8080

由两个数值组成的元组，以冒号分隔。这种形式将在 Docker 主机与容器内部对应端口之间建立明确的映射关系。在上述示例中，Docker 主机的 18080 端口将被暴露，并映射到运行中容器的 8080 端口。

主机端口：80

由字符串和数值组成的元组，以冒号分隔。在此形式中，元组的字符串部分对应一个 Maven 属性。若该属性在执行启动任务时未定义，Docker 将在临时端口范围内动态选择一个端口并分配给该属性，该属性随后可在同一 POM 文件中后续使用。临时端口范围由内核参数 /proc/sys/net/ipv4/ip_local_port_range 配置，通常范围从 32768 至 61000。若属性已存在且为数值，则该值将作为 docker 主机上的暴露端口使用，与前述形式相同。在上述示例中，docker 服务将选择新端口并将值赋给属性 host.port，之后可通过类似 ${host.port} 的属性表达式引用该值。这可用于在初始测试时从外部固定端口，类似于执行‘mvn -Dhost.port=10080 docker:start‘命令。

绑定至：host.port:80

由两个字符串和一个以冒号分隔的数值组成的元组。在此形式中，‘bindTo‘是容器应绑定到的主机上的 IP 地址。为方便起见，也可指定指向 Docker 主机的主机名。若无法解析该主机名，容器将无法启动。

• 主机 IP: 主机端口：80

由两个字符串和一个数值组成的元组，以冒号分隔。采用此形式时，容器的宿主 IP 将被填入名为‘host.ip‘的 Maven 属性。若 Docker 报告该值为‘0.0.0.0‘，则会改用‘docker.host.address‘的值替代。若需使用此形式并让容器绑定到特定主机名 / IP 地址，可声明同名 Maven 属性（本例中为‘host.ip‘）并填入要使用的值。‘host:port‘的运作方式与上述描述相同。

默认情况下使用 TCP 作为协议，但您也可以通过向端口号后附加 “/udp” 来使用 UDP。

以下是有效的配置条目示例：

示例

<bind.host.ip>1.2.3.4</bind.host.ip>
<bind.host.name>some.host.pvt</bind.host.name>

…

该属性文件可能对测试或其他 Maven 插件有所帮助，因为这些插件无法使用已解析的属性 —— 它们只能在容器启动后更新，而插件在其生命周期更早阶段就已解析了属性。

若无需编写此类属性文件，因而无需保留属性名称，亦可使用常规的 Maven 属性。例如，使用‘${host.var}:${port.var}:8080‘而非‘+host.var:port.var:8080‘。

5.2.4. 链接
配置包含一个容器列表，这些容器应根据 Docker 链接 链接到当前容器。每个链接可由两部分组成，其中可选的右侧部分通过冒号：分隔，将用作环境变量中的名称，而左侧部分则指向要链接到的容器名称。此配置等同于使用 Docker CLI 的 ——link 选项时的链接行为。

示例：链接到名为或别名为 postgres 的容器：

示例

postgres:db

这将创建以下环境变量，假设 postgres 镜像暴露了 TCP 端口 5432：

示例
DB_NAME=/web2/db
DB_PORT=tcp://172.17.0.5:5432
DB_PORT_5432_TCP=tcp://172.17.0.5:5432
DB_PORT_5432_TCP_PROTO=tcp
DB_PORT_5432_TCP_PORT=5432
DB_PORT_5432_TCP_ADDR=172.17.0.5
此外，每个 元素可以指定一组以逗号分隔的链接。由于有效的 Docker 链接名称 / 别名仅包含字母、数字、下划线、点号和破折号，因此可使用逗号（及空格）来分隔链接。

示例

postgres:db, search, saml:identity

若希望链接到未被此插件管理的现有容器，可通过在配置中指定通过‘docker ps‘命令获取的容器名称来实现。

请注意，链接的行为还取决于所选的网络模式。Docker 将上述描述的链接称为传统链接，未来可能会被移除。对于自定义网络，不会设置环境变量，链接仅会为被链接容器创建网络别名。若要在自定义网络中表达启动顺序依赖关系，请参考 dependsOn 配置。

如需了解更多关于新链接处理的详细文档，请参阅 Docker 网络文档 。

5.2.5. 网络
在 配置部分中的 & lt;network> 元素可用于配置容器的网络模式。这是目前连接容器首选的配置方式，它支持以下子元素：

表 15. 网络配置
元素
描述
模式

网络模式，可以是以下值之一：

Bridge : 使用默认的 Docker 网桥进行桥接模式（默认）

Host : 共享 Docker 主机的网络接口

Container : 连接到指定容器的网络。容器名称取自 元素。

自定义：使用自定义网络，该网络必须事先通过‘docker network create‘命令创建。或者，您可以将 全局配置参数 ‘docker.autoCreateCustomNetworks‘设置为‘true‘以自动创建自定义网络。自定义网络适用于 Docker 1.9 及更高版本。有关网络选项的更多信息，请参阅 Docker 文档 。

None : 不设置任何网络。

名称

在容器模式下，此为容器名称，即该镜像的别名。在自定义网络模式下，此为自定义网络的名称。

别名

可以提供一个或多个别名元素，使得容器能够通过特定网络范围内的任何其他容器以替代名称被发现。此配置仅在网络模式为自定义时生效。通过提供多个条目，可以指定多个别名。

如果未指定模式但提供了名称，则假定为自定义网络模式。对于不接受参数的简单模式（none、bridge 或 host），可以使用单个 模式 标签作为替代方案，而无需在 中使用 子元素。

示例

custom
my-network
box1
box2

或者对于一个简单的主机网络：

示例
host
5.2.6. 依赖项
自定义网络并不提供类似 的机制来表达容器间的强连接。通常这并非必需，因为 Docker 确保同一自定义网络内的所有容器最终都能通过 DNS 相互解析。

您的容器最好能够处理暂时无法解决的依赖关系，但在某些情况下，能够依赖其他基础设施容器的可用性会很有帮助。

配置可用于表达容器间的自定义网络依赖关系。docker:start 命令将确保在启动依赖容器之前，其所依赖的所有容器均已完全启动（满足所有 条件）。

此外，每个 元素可以指定一组以逗号分隔的容器。由于有效的 Docker 容器名称仅包含字母、数字、下划线、点号和短横线，因此可使用逗号（及空格）来分隔容器名称。

示例




postgres
logstash



5.2.7. 重启策略
指定容器退出时应采取的行为。这些值可在 部分中通过以下子元素进行配置：

表 16. 重启策略配置
元素
描述
名称

重启策略名称，可选自：

始终（v1.15）总是重启

On-failure (v1.15) 容器退出码非零时重启

重试

若使用 on-failure，则控制放弃前尝试重启的最大次数。

容器退出时应采取的行为。该值为一个对象，其 name 属性可为 “always” 表示始终重启，或 “on-failure” 表示仅在容器退出代码非零时重启。若使用 on-failure，MaximumRetryCount 将控制在放弃前尝试重启的最大次数。默认情况下不重启。（可选）

5.2.8. 卷
容器在启动时可以从多种来源绑定（或 “挂载”）卷：既可以是主机系统的目录，也可以是从另一个容器导出的一个或多个目录。挂载配置在运行配置的 部分中指定，它可以包含以下子元素：

表 17. 卷配置
元素
描述
来自

列出指定应导入其卷的容器镜像名称或别名的 ‘‘ 元素列表。

绑定

<卷> 规格列表（或主机挂载）。使用 /path 在容器中创建并暴露一个新卷，/host_path:/container_path 将主机路径挂载到容器内，而 /host_path:/container_path:ro 则以只读方式绑定。

卷册示例


/logs
/opt/host_export:/opt/container_import


jolokia/docker-demo


在此示例中，容器创建了一个名为 /logs 的新卷，并将主机上的 /opt/host_export 挂载为容器内的 /opt/container_import。此外，所有源自镜像 jolokia/docker-demo 所创建容器的导出卷，均直接挂载至该容器内（保持导出容器暴露这些目录时的相同路径名称）。此镜像也需为此插件进行配置。除了使用完整的镜像名称外，亦可使用别名替代。

如果在 & lt;bind> 中引用的是卷名而非路径，且存在一个 卷配置 与该名称对应，则会预先根据提供的选项创建此卷，而非使用默认选项。

您可以在路径规范中使用 Maven 变量。这甚至适用于 boot2docker 和 docker-machine 环境：

使用绝对路径的示例


${project.build.directory}/${project.artifactId}-${project.version}:/usr/local/tomcat/webapps/${project.name}
${project.basedir}/data:/data


您也可以使用相对路径。相对路径是相对于 Maven 项目基目录进行解析的。以～开头的路径则相对于 JVM 的 HOME 或 user.home 目录进行解析。

相对路径示例


src/main/webapps/foo:/usr/local/tomcat/webapps/foo
./target:/data
:/home/user
/.m2/repository:/home/user/.m2/repository


若需挂载由插件管理之外的现有容器中的卷，可通过在配置中指定通过docker ps命令获取的容器名称来实现。

5.2.9. 等待
在启动容器时，是否可以阻止执行，直到满足某些条件。这些条件可以在部分中指定，该部分包含以下子元素：

表 18. 等待配置
元素
描述
http

HTTP ping 检查，定期轮询一个 URL。它包含以下子元素：

url 包含一个 URL 且为必填项

方法 可选的 HTTP 方法使用。

状态 状态码，若返回则视为成功响应。此代码可以单独给出（如 200），也可以是一个范围（如 200..399）。默认值为 200..399。

allowAllHosts 如果 URL 为 HTTPS 链接且此选项被启用，则服务器证书将不会被验证。默认情况下，系统会检查证书是否具有正确的 CA 签名。

日志

应用于容器日志输出的正则表达式，该表达式会持续阻塞直至匹配到指定模式。在模式中使用 (?s) 可启用多行匹配功能。

时间

阻塞时间（毫秒）。

杀死

停止容器时，发送 SIGTERM 信号与 SIGKILL 信号之间的时间间隔（以毫秒计）。鉴于 Docker 本身采用秒级精度，建议该值至少设为 1000 毫秒。

关机

在停止容器与移除容器之间设置的等待时间（以毫秒计）。此设置适用于以下情况：当 Docker 在容器停止后过快尝试移除时，可能会因错误而崩溃，此时该延迟将有所帮助。

执行

在容器特定生命周期阶段执行的命令。它支持以下子元素：

PostStart 容器满足上述等待条件后要运行的命令

PreStop 在容器停止前要运行的命令。

BreakOnError 如果设置为 true，则在 postStart 或 preStop 命令返回非 0 退出码时中断构建；否则仅打印错误信息。

传输控制协议（TCP）

TCP 端口检查，定期轮询指定的 TCP 端口。它包含以下子元素：

模式可以是映射（mapped），即使用映射的端口；也可以是直接（direct），此时直接访问容器端口。在后一种情况下，主机字段应留空以选择容器 IP（必须可路由，仅当直接在 Docker 守护程序的主机上运行时才满足此条件）。默认情况下，若主机为 localhost 则采用直接模式，否则为映射模式。当 Docker 守护程序上启用了所谓的用户代理（user-proxy）时，直接模式可能有所帮助，因为即使容器尚未准备就绪，映射端口也能直接可用。

Host 为主机名或 IP 地址。在映射模式下默认为 ${docker.host.address}，在直接模式下则默认使用容器 IP 地址。

端口列表用于检查 TCP 端口，这些应为容器内部端口。

健康

检查等待直到容器健康状态变为 “健康”。当容器的 配置的健康检查 成功时，即认为该容器处于健康状态。

此行为模仿了 Docker Compose 中 dependsOn 条件：service_healthy。

退出

检查等待，直到容器以给定的退出代码完成。

一旦满足任一条件，构建流程将继续执行。若添加了 约束，其作用类似于对其他条件设置超时限制 —— 当等待 URL 响应或日志输出时若达到超时阈值，构建将被终止。若仅指定 参数，构建流程将在等待指定毫秒数后自动继续。

示例


http://localhost:${host.port}
GET
200..399

10000
1000
500

/opt/init_db.sh
/opt/notify_end.sh


192.168.99.100

3306
9999


true

此设置将等待给定 URL 可达，但最多只等待十秒。此外，它还会等待 TCP 端口 3306 和 9999 可用。同时，在集成测试结束后停止容器时，构建过程会先等待 500 毫秒再尝试移除容器（除非使用了 keepContainer 或 keepRunning 参数）。每种等待条件中均可使用 Maven 属性，例如示例中的 ${host.port} 属性可能已在端口映射章节预先定义。

属性 ${docker.host.address} 隐式设置为 Docker 主机的地址。若使用 HTTP 或 HTTPS 协议，该主机地址将从 docker.host 配置中获取；若通过 Unix 套接字与 docker 守护进程通信，则默认假定为 localhost。您始终可以通过显式设置此 Maven 属性来覆盖该默认值。

5.2.10. 日志记录
在运行容器时，容器的标准输出和标准错误可以被打印出来。有多种选项可用于配置日志输出：

表 19. 日志配置
元素
描述
启用

若设为 false，则禁用日志输出。这在您希望默认关闭日志输出但需通过命令行参数 -Ddocker.showLogs 启用时，同时利用其他配置选项的情况下非常有用。若配置中包含 节点，则默认启用日志记录功能。

前缀

用于标识容器的日志输出前缀。您可以在前缀中使用占位符，这些占位符会被动态替换：

% a: 镜像别名，若未设置，则为容器短 ID（即容器 ID 的前 6 个字符）。

% c：短容器 ID（即容器 ID 的前 6 个字符）

% C: 完整的容器 ID

% n: 镜像名称

% z: 空字符串

默认格式为 “% a> ”。

日期

日志时间戳使用的日期格式。若未提供 ，则不显示时间戳。日期规格可为常量或日期格式，可识别的常量包括：

NONE 关闭时间戳输出。在命令行中特别有用（-Ddocker.logDate=NONE），用于关闭原本启用的日志功能。

DEFAULT 默认格式为 HH:mm:ss.SSS

MEDIUM java.time 中等日期时间格式

SHORT java.time 短日期时间格式

长格式 java.time 长日期时间格式

ISO8601 完整的 ISO-8601 格式日期时间（含毫秒）

作为替代方案，可以使用 java.time 识别的日期时间格式字符串。为了设置一致的日期格式，可以利用全局配置参数 logDate。

颜色

启用着色功能时用于为前缀着色的颜色（例如，在控制台中运行且 useColor 设置为 true 时）。可用颜色包括黄色、青色、品红色、绿色、红色、蓝色。若启用着色但未指定颜色，系统将自动为您选取一种颜色。

文件

日志输出写入的文件路径。每次运行都会覆盖该文件，且颜色显示功能将被关闭。

驱动程序

可指定专用日志驱动程序的配置部分。在此部分内， 标签代表日志驱动程序，其选项由 标签内指定。具体使用方法请参见下方示例。

示例

TC
default
cyan

以下示例启用了 gelf 日志驱动 。 这等同于在使用 docker run 时添加选项 ——log-driver=gelf ——log-opt gelf-address=udp://localhost:12201。

会话下的以下配置选项等同于运行 docker 容器时的 ——isolation 参数。

示例

hyperv

此选项在 Windows 上运行 Docker 容器时非常有用。‘——isolation ‘参数用于设置容器的隔离技术。在 Linux 系统中，唯一支持的是默认选项，即使用 Linux 命名空间。

表 20. 在 Windows 系统上，隔离模式可选用以下任一值：
值
描述
默认

使用由 Docker 守护进程的 ——exec-opt 指定的值或系统默认值（见下文）。

进程

共享内核命名空间隔离（不支持早于 Windows 10 1809 版本的 Windows 客户端操作系统）。

Hyperv

基于 Hyper-V 管理程序分区的隔离。

Windows 服务器操作系统的默认隔离模式为进程隔离，而 Windows 客户端操作系统的默认隔离模式则是 Hyper-V 隔离。若在版本低于 Windows 10 1809 的客户端操作系统上尝试以‘——isolation process‘参数启动容器，操作将会失败。

请参阅 容器隔离技术 以获取详细说明。

5.3. docker: 停止
停止并移除一个 Docker 容器。此目标会停止所有通过 docker:start 启动的容器，无论是在同一构建过程中（例如，在集成测试时绑定到生命周期阶段）还是由之前调用 docker:start 创建的容器。

若在同一构建运行期间调用，仅会停止该运行期间显式启动的容器。使用 docker:start 为项目启动的现有容器将不受影响。

若作为独立调用执行，该插件将停止并移除所有在项目配置中定义镜像的容器。对于镜像名称匹配但非由插件启动的现有运行容器，则不受影响。

若图像的命名策略为别名（即容器名称设置为给定的别名），则仅停止具有该别名的容器。源自同一镜像的其他容器不受影响。

需要注意的是，在插件 0.13.7 版本之前创建的任何容器可能无法被插件正确停止，因为用于将容器与项目关联的必要标签可能不存在。若发生此情况，您需使用 Docker 命令行工具清理容器，或采用下文所述的 docker.allContainers 选项进行操作。

在调整停止操作的行为时，通常有四个全局参数作为系统属性使用：allContainers（所有容器）、keepContainer（保留容器）、keepRunning（保持运行）和 removeVolumes（移除卷）。

表 21. 停止配置
元素
描述
参数
所有容器

停止并移除当前项目配置中定义的任何匹配镜像的容器。这是该插件在 0.13.6 版本之前默认的行为。

docker.allContainers

容器名称模式

docker:start 在创建容器时使用的默认命名模式。详情请参阅 容器名称 部分。 若目标配置于独立的执行过程中，此设置应与 docker:start 目标中的配置保持一致。

docker.containerNamePattern

保留容器

若设为 true，则容器停止后不会被销毁。默认值为 false。

docker.keepContainer

保持运行

若设置为 true，实际上不会停止容器。此选项显然仅在命令行进行集成测试时（例如在生命周期绑定中调用 docker:stop）有意义，以便集成测试后容器仍保持运行状态。这对于分析容器（例如通过 docker exec 进入）非常有用。

docker.keepRunning

移除卷

若设为 true，将同时移除与容器关联的匿名卷。若 keepContainer 或 keepRunning 任一为 true，此选项将被忽略。

docker.removeVolumes

站点名称模式

如果提供了 名称模式 列表，任何匹配这些模式的容器将被停止并移除（具体取决于 keepContainer 和 keepRunning 的值），无论是否存在 镜像配置 。

docker.stopNamePattern

在虚拟机停机时执行停止操作

若为真，容器不会立即停止，而是在构建完成（无论成功或失败）后停止。

默认为 false。

docker.executeStopOnVMShutdown

示例
$ mvn -Ddocker.keepRunning clean install
5.4. docker: 推送
此目标将上传那些配置了 & lt;build> 部分的镜像至注册表。可通过全局选项过滤器（详见 全局配置 ）限制待推送的镜像。默认推送至 docker.io 注册表，但也可像 Docker 方式那样在镜像名称中指定。例如，docker.test.org:5000/data:1.5 会将标签为 1.5 的 data 镜像推送至端口 5000 上的 docker.test.org 注册表。安全信息（即 全局选项过滤器（详情请参阅 全局配置 ）。默认推送至 docker.io 的镜像仓库，但也可按照 Docker 的命名方式在镜像名称中指定。例如，docker.test.org:5000/data:1.5 会将标签为 1.5 的 data 镜像推送至端口 5000 上的 docker.test.org 仓库。安全信息（即用户名和密码）可通过多种方式指定，如 身份验证 章节所述。

默认情况下，控制台会显示一个进度条，但在使用 Maven 的批处理模式（即选项 - B）时会被省略。当禁用彩色输出（即使用 - Ddocker.useColor=false 参数）时，会提供一个极为简化的进度显示。

表 22. 推送选项
元素
描述
属性
跳过推送

如果设置为 true，该插件将不会推送任何已构建的镜像。

docker.skip.push

跳过标签

若设为 true，此插件将不会推送任何标签。

docker.skip.tag

推送注册表

推送镜像时使用的注册表。详情请参阅 注册表处理 。 更多详情。

docker.push.registry

重试次数

在放弃前，推送操作应重试多少次？这对于偶尔返回 500 错误代码的不稳定注册表非常有用。默认值为 0，表示完全不进行重试。

docker.push.retries

5.5. docker:watch
在开发和测试应用程序时，您经常需要重新构建 Docker 镜像并重启容器。频繁输入 docker:build 和 docker:start 命令相当繁琐。通过 docker:watch 功能，您可以在更新时启用自动重建镜像及重启容器的机制。

Docker:watch 是执行这些任务的顶层目标。它提供两种监控模式，可通过多种方式指定：

构建：当由程序集选定的任一文件发生变更时，自动重建一个或多个 Docker 镜像。此功能不仅适用于直接包含在 assembly.xml 中的所有文件，还能处理任意依赖项。

示例
$ mvn package docker:build docker:watch -Ddocker.watchMode=build
此模式仅在镜像配置中存在 部分时生效。若镜像仅包含 部分，则不会触发自动构建。请注意，必须确保 package 阶段已先行执行，否则此构建生成的任何产物都无法被包含到组件中。如 docker:start 章节所述，这是 Maven 的一个限制。 * run : 当关联镜像发生变更时自动重启容器。此功能在外部拉取新版本镜像时特别有用，尤其是与 build 模式结合使用时，可在镜像自动重建后重启容器。该模式仅在配合 docker:start 使用时才能可靠工作。

示例
$ mvn docker:start docker:watch -Ddocker.watchMode=run
两者：同时启用构建和运行。此为默认设置。

无：完全忽略镜像的监视。

Copy：将变更的文件复制到运行中的容器。这是更新容器的快速方法，但目标容器也必须支持热部署才能有效。大多数应用服务器（如 Tomcat）均支持此功能。

模式也可以设置为 both 或 none，分别选择这两种变体或都不选择。默认值为 both。

Docker:watch 将持续运行，直到通过 CTRL-C 中断，此时它将停止所有容器。根据配置参数 keepContainer 和 removeVolumes 的设置，已停止的容器及其关联的存储卷也将被移除。

当被监视的镜像被移除时，系统会定期打印出错误信息。所以别这么干哦；-)

动态分配的端口保持稳定，这意味着即使容器停止后创建并启动新容器，这些端口也不会改变。新容器将尝试分配与之前容器相同的端口。

如果容器通过网络或卷相互链接，而您更新了其他容器所依赖的某个容器，目前依赖容器不会随之重启。例如，当 “服务” 容器访问 “数据库” 容器时，若 “数据库” 容器被更新，则 “服务” 容器将因未同步重启而出现故障。

该插件的未来版本将负责（以正确的顺序）重启这些容器，但目前仍需手动操作。

此 Maven 目标可通过以下顶级参数进行配置：

表 23. 监视配置
元素
描述
属性
容器名称模式

所有容器创建时的默认命名模式。详情请参阅 容器名称 。

docker.containerNamePattern

保留容器

至于 docker:stop，若此参数设为 true（且 keepRunning 未启用），则所有容器在停止后将被移除。默认值为 true。

docker.keepContainer

保持运行

若设为 true，所有容器在 docker:watch 停止后仍将保持运行状态。默认情况下，此选项设为 false。

docker.keepRunning

移除卷

若设为 true，将同时移除与容器关联的所有卷。若 keepContainer 或 keepRunning 任一为 true，则此选项将被忽略。

docker.removeVolumes

监视间隔

以毫秒为单位的检查变更间隔时间，必须大于 100 毫秒，默认值为 5 秒。

docker.watchInterval

观看模式

监视模式指定了需要监视的内容

构建：监视程序集的变化，并在有变动时重新构建镜像。

运行：监控容器镜像是否发生变化，并在变化时重启容器

副本：变更文件被复制到容器中。该容器可以是正在运行的，也可能已经退出（当作为数据容器链接到平台容器时使用）。要求 Docker 版本不低于 1.8。

两者合一：构建与运行相结合

None：既不监视构建也不监视镜像。如果您使用预构建的镜像且这些镜像不会更改，因此无需任何监视，此选项非常有用。none 最好在单个镜像级别上使用，具体指定方法如下所示。

docker.watchMode

WatchPostExec

在 watchMode 为 copy 时，文件被复制进容器后执行的一条命令。注意，该容器必须处于运行状态。

观看进球回放

一个在重建或重启后应调用的 Maven 目标。此目标必须遵循格式 ::，且相关插件需在 pom.xml 中配置完成。例如，后置目标 io.fabric8:fabric8:delete-pods 将触发 Kubernetes 中 POD 的删除操作，进而促使集群内启动新的 POD。此处指定的值为默认后置目标，可通过 配置中的 进行覆盖。

镜像特定的监视配置需置于额外的镜像级别 部分（即 …）。以下是可识别的参数：

表 24. 单张图片的监视配置
元素
描述
模式

每张图片均可单独配置监控模式，此设置优先于全局监控模式。此配置中指定的模式将覆盖全局设置的模式。

间隔

可在图像级别以毫秒为单位指定监视间隔。若设置此项，将覆盖全局监视间隔。

进球后

在重建或重启后执行的 Maven 插件目标。此处值必须遵循格式 <插件组 ID>:<插件构件 ID>:<目标>（例如：io.fabric8:fabric8:delete-pods）。

执行后操作

在复制模式下，文件被复制到运行中的容器后执行的命令。

以下是调整监视模式的一个示例：

示例


10000

both



service
….

5000




db
….

none


….


根据此配置

示例
mvn package docker:build docker:start docker:watch
您可以构建服务镜像、启动所有容器并进入监视循环。同样，您需要包含打包阶段，以便组装过程能够找到由该项目构建的产物。这是 Maven 的一个限制。数据库镜像在监视过程中不会被重新构建，因为假定其在监视期间不会发生变化。

5.6. docker: 移除
此目标可用于清理镜像。默认情况下，所有带有构建配置的镜像都将被移除。您可以通过将属性 removeMode（属性：docker.removeMode）设置为以下任一值来调整此行为：

表 25. removeMode 取值
值
描述
build

所有带有 构建配置 的镜像

run

所有没有 构建配置 的镜像

all

所有已配置的镜像

data

所有数据镜像，即没有 运行配置 的镜像。

此前，也可以通过设置‘removeAll‘属性来调整此行为，该属性指示删除此构建管理的所有镜像。否则，在 0.24.0 版本之前仅会删除数据镜像。‘removeAll‘已被弃用并将很快移除，请改用‘removeMode‘。

与其他目标一样，配置图像可用于调整待删除的映像。属于这些映像的所有容器以及分配给该映像的所有标签都将被一并移除。

考虑三个镜像’db’、’tomcat’和’data’，其中只有’data’镜像具有构建配置：

Mvn docker:remove 将删除 ’data’

Mvn -Ddocker.removeMode=all docker:remove 将删除全部三个镜像

Mvn -Ddocker.filter=data,tomcat docker:remove 将删除 ’data’

Mvn -Ddocker.filter=data,tomcat -Ddocker.removeMode=all docker:remove 将删除 ’data’ 和 ’tomcat’

表 26. 移除选项
元素
描述
属性
跳过标签

如果设置为 true，此插件将不会移除任何标签

docker.skip.tag

移除名称模式

如果提供了 名称模式 列表，任何匹配这些模式的图像都将被移除， 无论是否存在标记为待移除的 图像配置 。

docker.removeNamePattern

5.7. docker: 日志
为了实现这一目标，可以打印出由本插件配置的镜像启动的容器日志。默认情况下仅输出最新启动的容器日志，但可通过属性配置进行更改。日志输出的格式受所配置镜像的运行设置影响。以下系统属性可调整此目标的行为：

表 27. 日志记录选项
属性
描述
Docker.logAll

若设为 true，则打印由此插件配置的镜像创建的所有容器的日志。每条日志行前会附加容器 ID 前缀。这些镜像可能包含许多已停止的容器。直接通过命令行使用 docker logs 命令可能是更佳选择。

Docker.follow

若指定此选项，将等待后续日志输出直至按下 CTRL-C 终止，其行为类似于 docker logs -f（或 tail -f）命令的效果。

Docker.filter

用于限制应获取日志的镜像集合的过滤器。可以是镜像或别名名称的逗号分隔列表。

Docker.log 日期

日期格式设置。查看 “ 日志记录 ” 以获取可用格式。

示例
$ mvn docker:logs -Ddocker.follow -Ddocker.logDate=DEFAULT
5.8. docker:copy
此目标从容器中复制文件和目录。 调用时，将遍历项目中配置的所有镜像，这些镜像在 复制 元素中配置于 镜像配置 内。

除了 全局配置 外，此目标还支持以下配置选项：

表 28. 复制选项
元素
描述
属性
创建容器

是否创建临时容器或从现有容器中复制。

若为真，则在复制前创建一个临时容器（但不启动），并在复制完成后移除该容器，即使复制失败。容器镜像将根据 imagePullPolicy 从注册表中拉取。

若为假，则从现有容器中复制：

如果目标与 docker:start 目标一同调用，则仅从该目标启动的容器执行复制操作。

否则，将从匹配配置镜像的容器中执行复制，并检查镜像配置的 copyNamePattern 属性：

如果定义了 copyNamePattern 模式，则使用该模式来匹配容器。

否则，将使用镜像名称来匹配容器，即检查由同名镜像创建的容器。

临时容器的创建与移除，或现有容器的检查，均按照 镜像 配置的顺序进行。

默认为 false。

docker.createContainers

拉取镜像仓库

在创建临时容器时用于拉取镜像的注册表，以及 imagePullPolicy 允许或要求拉取相应镜像。 如果 createContainers 为 false 则忽略此设置。

docker.pull.registry

容器命名模式

创建容器时的 命名模式 。

如果 createContainers 为 false，则忽略此项。

默认为默认容器命名模式（% n-% i）。

docker.containerNamePattern

复制

是否从所有匹配的容器复制，还是仅从最新的容器复制。

如果 createContainers 为 true，则忽略此项。

默认为 false。

docker.copyAll

目标会遵循复制镜像配置元素，并包含以下子元素：

表 29. 复制配置（ 镜像配置 ）
元素
描述
条目

从容器中复制的项目列表。每个项目都用 & lt;entry> 和 & lt;/entry> 标签包裹。 请参考 复制条目格式 了解单个列表项的格式。 复制按列表项的顺序进行。

可选，即可以省略或包含空列表项。

复制元素条目列表中的每一项由以下子元素构成：

表 30. 拷贝条目格式
元素
描述
容器路径

容器文件或容器目录的路径，需要被复制。如果路径不是绝对路径，则视为相对于容器工作目录的路径。

主机目录

指向主机目录的路径，用于存放需要复制的文件或目录。”主机” 在此指执行复制目标的机器，即构建相应 Maven 项目的所在计算机。

若路径非绝对路径，则视为相对于 Maven 项目基目录的相对路径。当复制容器目录时，会在由 hostDirectory 定义的路径下创建同名目录，即复制的是整个容器目录而非仅其内容。

Optional. If omitted then project base directory is used.

Example of copy configuration

docker-maven-plugin










/etc/hosts

${project.build.directory}




/dev

target







5.9. docker:source
The docker:source target can be used to attach a docker build archive containing the Dockerfile and all added files to the Maven project with a certain classifier. It reuses the configuration from docker:build.

By default, only the first image configuration is used for creating the source archive. You can export all image configurations by setting the sourceMode configuration to all:

Export all image configs

docker-maven-plugin


all



For exporting all image configurations, docker:source uses the image’s alias as part of the classifier, so it is mandatory that the alias is set for this goal to work when all images should be exported this way. The classifier is calculated as docker- so when the alias is set to service, then the classifier is docker-service.

If you only export the first image configuration (which is the default), then the classifier is just docker (without alias).

docker:source can be attached to a Maven execution phase, which is generate-sources by default.

For example, this configuration will attach the docker build archive to the artifacts to store in the repository:

Example

docker-maven-plugin



sources

source




如果未绑定到执行阶段，docker:source 要求工件必须已创建，因此最好与 package 一起调用。

5.10. docker: 保存
Docker:save 目标将构建配置中定义的镜像保存到本地文件，类似于 docker save 命令。如果未设置 saveFile 选项，则自动计算文件名。

若使用了 saveAlias 参数，文件将保存为 target/-<项目版本>.tar.gz 格式。

否则，归档文件将保存为 target/<去除注册表及用户部分的镜像名称>-<镜像标签>.tar.gz

请注意，导出的镜像包含所有镜像层，可能体积较大（同时，导出镜像也需要一定时间）。

控制图像压缩
文件扩展名用于选择输出文件的压缩方法。

扩展名
压缩
类型
.tar 或无法识别

无压缩

.tar

.tar.gz，.tgz

GZIP 压缩

.tar.gz

.tar.bz、.tar.bz2、.tar.bzip2

BZIP2 压缩

.tar.bz

将保存的图片作为构件附加
若设置了 saveClassifier，保存的归档文件将使用提供的分类器附加到项目中，并根据文件名确定类型。占位符 % a 将被替换为图像别名。

请注意，若覆盖默认设置以使用 docker 或 docker-% a，当同时附加带有 docker:source 的源归档文件时，可能会导致冲突。

表 31. 保存选项
元素
描述
属性
保存名称

要保存的镜像配置名称。不得与别名（alias）、别名列表（aliases）或名称列表（names）同时使用。

docker.save.name

保存名称

要保存的镜像配置名称列表。不得与别名（alias、aliases）或名称（name）同时使用。

docker.save.names

保存别名

要保存的图像配置的别名。不得与名称、名称列表或别名列表同时使用。

docker.save.alias

保存别名

要保存的图像配置的别名列表。不得与名称、多个名称或别名同时使用。

docker.save.alias

保存文件

保存的文件名。

Docker.save.file 或 docker.file 或 file

保存分类器

如果设置，将保存的归档文件附加到项目中，并使用提供的分类器。占位符 % a 将被替换为镜像别名。

docker.save.classifier

保存

一个布尔标志，表示是否跳过目标的执行。

docker.skip.save

5.11. docker: 标签
‘docker:tag‘命令用于给镜像打标签，使其成为仓库的一部分。你可以用它来为已构建的镜像添加标签。以下是其使用示例：

~/work/repos/docker-maven-plugin/samples/zero-config : $ mvn docker:tag -Ddocker.image.tag=0.9.0
[INFO] Scanning for projects…
[INFO]
[INFO] ———–< io.fabric8.dmp.samples:demp-sample-zero-config >———–
[INFO] Building demp-sample-zero-config
[INFO] ——————————–[ jar ]———————————
[INFO]
[INFO] — docker-maven-plugin:dmpversion:tag (default-cli) @ demp-sample-zero-config —
[INFO] DOCKER> Tagging image samples/demp-sample-zero-config:0.9.0 successful!
[INFO] ————————————————————————
[INFO] BUILD SUCCESS
[INFO] ————————————————————————
[INFO] Total time: 1.155 s
[INFO] Finished at: 2020-06-27T14:05:33+05:30
[INFO] ————————————————————————
~/work/repos/docker-maven-plugin/samples/zero-config : $ docker images | grep 0.9.0
samples/demp-sample-zero-config 0.9.0 ac5c5991505d About an hour ago 479MB
表 32. 支持的选项
元素
描述
属性
标签名称

新标签的名称。

docker.image.tag

仓库

要打标签的仓库。例如，someuser/someimage。

docker.image.repo

5.12. docker: 卷创建
此目标创建一个或多个独立的 Docker 卷 ，这些卷可在 docker:start 配置中被引用，以便在运行时链接到卷。 因此，每个卷都具有唯一且可引用的名称。此外，还可以指定卷驱动程序和驱动程序选项。

卷配置示例




temp-volume
local

tmpfs
tmpfs
size=100m,uid=1000


true



…


配置
创建卷时可用的选项如下：

表 33. 卷配置
元素
描述
名称

卷的名称

驱动程序

使用的卷驱动程序。默认情况下，系统会使用本地驱动程序，该程序创建于本地文件系统上。请参考您的 Docker 安装说明以了解可用的其他驱动程序。

选项

以自定义 & lt;key> 值 & lt;/key> 形式传递的驱动程序特定选项，这些选项会映射为驱动程序的键值对参数，同样可通过 Docker CLI 提供。每个卷驱动程序支持不同的选项。本地驱动程序支持的选项是广为人知的 Linux 挂载选项 。

标签

标签以 & lt;key>value 形式给出，类似于 环境与标签 中描述的镜像标签。这些标签用于标记卷本身。

5.13. docker:volume-remove
此目标与 docker:volume-create 相对应，用于移除一个卷。 Docker 卷是在 Docker 镜像之外配置的，但可以被它们引用。 其配置与 docker:volume-create 相同。

示例：

temp-volume .... ... 配置 配置相当简单，仅需提供待删除卷的名称即可。

表 34. 卷配置
元素
描述
名称

卷名称

6. 外部配置
   针对特殊配置需求，存在从插件配置外部获取运行时及构建配置的可能性。这一功能通过‘‘配置区段实现，该区段至少需包含一个‘‘子元素。‘‘元素用于选定特定的 “处理器”，该处理器负责生成完整的镜像配置。处理器可自行决定是否采用在此‘‘区段外额外提供的‘‘与‘‘配置，亦或完全忽略任何附加配置选项。

处理程序还可以决定将此单一图像配置扩展为一系列图像配置。由此类外部配置生成的图像配置会被添加到常规的 配置中，而无需包含 部分。

可用的处理器如下所述。

6.1. 属性
对于简单的需求，镜像配置可以通过 Maven 属性完全定义，这些属性位于该插件配置之外。这种基于属性的配置可以通过选择‘‘为 properties 来启用。作为额外配置，可以为属性定义一个前缀，默认情况下此前缀为 docker。

对于单镜像配置，也可以通过外部设置的属性来激活基于属性的配置。

默认情况下，基于属性的配置仅使用属性，忽略任何 & lt;build> 和 & lt;run> 部分。要结合这两个来源的值，请使用 属性模式配置 。

属性是从 Maven 项目（定义在 中或来自 settings.xml 的全局 Maven 配置）读取的，并且自 0.25.0 版本起，还会从传递给 Maven 的任何 - D 标志中读取（优先级高于项目属性）。

示例


properties
docker
only


Given this example configuration a single image configuration is built up from the following properties, which correspond to the corresponding values in the and sections. A build configuration is only created when a docker.from or a docker.fromExt is set.

Table 35. External properties
docker.alias

Alias name

docker.args.BUILDVAR

Set the value of a build variable. The syntax is the same as for specifying environment variables (see below).

docker.assembly.baseDir

Directory name for the exported artifacts as described in an assembly (which is /maven by default).

docker.assembly.descriptor

Path to the assembly descriptor when building an image

docker.assembly.descriptorRef

Name of a predefined assembly to use.

docker.assembly.exportBaseDir

If true export base directory

docker.assembly.ignorePermissions

If set to true existing file permissions are ignored when creating the assembly archive. Deprecated, use a permission mode of ignore instead.

docker.assembly.permissions

can be ignore to use the permission as found on files regardless on any assembly configuration, keep to respect the assembly provided permissions, exec for setting the executable bit on all files (required for Windows when using an assembly mode dir) or auto to let the plugin select exec on Windows and keep on others. keep is the default value.

docker.assembly.dockerFileDir

specifies a directory containing an external Dockerfile that will be used to create the image. This is deprecated please use docker.dockerFileDir or docker.dockerFile instead.

docker.noCache

Don’t use Docker’s build cache. This can be overwritten by setting a system property docker.noCache when running Maven.

docker.bind.idx

Sets a list of paths to bind/expose in the container. See List Properties.

docker.build.network

Set the networking mode for the RUN instructions during build

docker.buildArg.VARIABLE

Set a ARG to be available during build of image. Note: this is handled separately from external configuration, and is always available. See Build Args for more details.

docker.buildx.builderName

Name of buildx builder

docker.buildx.cache

Location of image cache

docker.buildx.configFile

Configuration file for buildx builder

docker.buildx.platform

Platform for multi-architecture image

docker.buildx.cacheFrom

Cache source for buildx builder

Docker.buildx.cacheTo

Buildx 构建器的缓存目标

Docker.capAdd.idx

要添加到容器中的内核能力列表。参见 列表属性 。

Docker.capDrop.idx 要移除的容器内核能力列表。参见 列表属性 。

要从容器中移除的内核能力列表。请参阅 列表属性 。

Docker.sysctls.KEY

设置容器内命名空间的内核参数（sysctl）。

Docker.cleanup

每次构建后清理悬空（未标记）镜像，包括由此类镜像创建的任何已停止容器。同时，清理因镜像重新标记、自动拉取基础镜像或自动拉取缓存来源镜像而产生的悬空镜像。默认值为 try，即尝试移除旧镜像，但若操作无法完成（例如因镜像仍被运行中的容器使用）不会导致构建失败。其他可选值为 remove（若希望构建因此失败）或 none（完全跳过清理步骤）。

Docker.cmd

要执行的命令。此命令既在运行容器时使用，也作为创建镜像时的默认命令。

Docker.copy.entries.idx.containerPath

ContainerPath 是 复制配置条目 的子元素。idx 可以是整数或字符串，允许为空字符串。

Idx 定义了复制顺序。首先复制 idx 为整数的条目，按解析后的 idx 值升序排列；其次复制 idx 非整数的条目，按 idx 的字母顺序升序排列。

Docker.copy.entries.idx.hostDirectory

HostDirectory 是 复制配置条目 的子元素。其 idx 值应与 docker.copy.entries.idx.containerPath 外部属性中的 idx 保持一致。

Docker.copyNamePattern

设置 copyNamePattern 镜像配置项。

Docker.cpuset

指定容器可使用多少可用 CPU 资源

Docker.cpuset

将容器限制在特定的 CPU 或核心上。可以以逗号分隔的列表或连字符分隔的范围形式提供。

Docker.cpushares 设置容器可用的主机 CPU 周期比例

设置容器可用的主机 CPU 周期比例

Docker.cacheFrom.idx

定义用作缓存源的镜像名称列表。请参阅 列表属性 。

Docker.domainname

容器域名

Docker.dns.idx

要使用的 DNS 服务器列表。请参阅 列表属性 。

Docker.dnsSearch.idx

DNS 搜索域列表。请参阅 列表属性 。

Docker.dockerArchive

指定一个可通过‘docker load‘加载的存档。此选项可作为‘docker.dockerFile‘或‘docker.dockerFileDir‘的替代方案使用。

Docker.dockerFile

指定要使用的 Dockerfile。此属性必须直接指向 Dockerfile 文件本身。

Docker.dockerFileDir

指定一个包含外部 Dockerfile 的目录，该文件将用于创建镜像。此 Dockerfile 必须命名为 Dockerfile。

Docker.entrypoint

容器入口点

Docker.exposedPropertyKey

用于公开容器属性（如内部 IP 地址）的属性部分，如 docker:start 中所述。

Docker.env. 变量

设置一个用于构建和运行的环境变量。例如，<docker.env. JAVA_OPTS>-Xmx512m</docker.env. JAVA_OPTS> 设置了环境变量 JAVA_OPTS。可以提供多个此类条目。该环境既用于构建镜像，也用于运行容器。其值不能为空，但可包含在创建 Dockerfile 前会被解析的 Maven 属性名称。

Docker.env 构建。变量

设置一个仅在构建过程中使用的环境变量。例如，<docker.envBuild.JAVA_OPTS>-Xmx512m</docker.envBuild.JAVA_OPTS> 设置了环境变量 JAVA_OPTS。可以提供多个此类条目。此环境仅用于构建镜像。该值不能为空，但可以包含在创建 Dockerfile 之前解析的 Maven 属性名称。

Docker.envRun. 变量

设置一个仅在运行时使用的环境变量。例如，<docker.envRun.JAVA_OPTS>-Xmx512m</docker.envRun.JAVA_OPTS> 设置了环境变量 JAVA_OPTS。可以提供多个此类条目。此环境仅用于运行容器。值不能为空，但可以包含在创建 Dockerfile 之前解析的 Maven 属性名称。

Docker.envPropertyFile

指定一个属性文件的路径，该文件的属性将作为运行时的环境变量使用。这些环境变量优先于其他任何指定的环境变量。

docker.extraHosts.idx

需要添加到 /etc/hosts 文件的主机名与 IP 对应列表 请参阅列表属性。

Docker.filter

启用并设置属性替换的分隔符。默认情况下，格式为${…}的属性会被替换为 Maven 属性。通过将此属性设为 false 可关闭属性替换功能。若使用单字符（如 @）作为分隔符，则采用该字符界定替换范围（例如 @...@）。更多详情请参阅过滤机制。

Docker.from

构建镜像的基础镜像。创建镜像时必须设置（或使用 fromExt）。

Docker.fromExt. 变量

构建镜像的基础镜像（扩展格式），同时也会触发镜像的构建。

Docker.healthcheck.cmd

用于健康检查的命令

Docker.healthcheck.interval 用于健康检查的运行间隔（以秒或指定时间单位计）

运行健康检查的间隔时间（以秒或指定时间单位计）

Docker.healthcheck.mode

如果设置为 none，则禁用基础镜像中的健康检查

Docker.healthcheck.retries

健康检查失败前允许的重试次数

Docker.healthcheck.startPeriod

需要时间启动的容器初始化时长。在此期间内的探针失败不计入最大重试次数。然而，若启动阶段内健康检查成功，则容器视为已启动，此后所有连续失败都将计入最大重试次数。（以秒为单位或指定时间单位）

Docker.healthcheck.timeout

健康检查命令超时后即视为失败（以秒或指定时间单位计）

Docker.hostname

容器主机名

Docker.imagePropertyConfiguration

特殊属性，用于在不修改 XML 文件的情况下激活属性配置（参见 外部激活属性配置 ）。

Docker.imagepullpolicy.build

构建镜像时使用的特定拉取策略。有关可能的取值，请参阅 imagePullPolicy。

Docker.imagepullpolicy.run

用于下载运行镜像的特定拉取策略。有关可能的值，请参阅 imagePullPolicy。

Docker.labels.LABEL

设置一个类似于环境变量的标签。

Docker.loadNamePattern

在指定的 docker.dockerArchive 存档中搜索指定镜像名称，并根据匹配到的名称创建一个标签，指向构建镜像名称 docker.name。

Docker.log.enabled

启用日志记录（默认值：true）

Docker.log.prefix

输出前缀

Docker.log. 颜色

用于前缀的 ANSI 颜色

Docker.log.date

用于打印时间戳的日期格式

Docker.log.driver.name

替代日志驱动程序的名称

Docker.log.driver.opts.VARIABLE

日志驱动选项（指定方式类似于 docker.env.VARIABLE）

Docker.links.idx

定义了启动容器时链接到其他容器的列表。例如 & lt;docker.links.1>db</docker.links.1> 指定了一个别名为’db’的镜像链接。 详见 列表属性 。

Docker.maintainer

定义构建镜像时使用的维护者邮箱

Docker.memory

内存限制（以字节为单位）。

Docker.memorySwap

总内存限制（内存 + 交换区）以字节为单位。将 docker.memorySwap 设置为与 docker.memory 相同的值以禁用交换区。设为 - 1 则允许无限制的交换区使用。

Docker.name

镜像名称

Docker. 命名策略

容器命名（可选无或别名）

Docker.network.mode

使用的网络模式，可选值为 none、host、bridged、container 或 custom。

Docker.network.name

当模式为自定义时使用的自定义网络名称，或当模式为容器时用于创建容器的镜像别名。

Docker.network.alias.idx

一个或多个自定义网络的别名。仅在网络模式为自定义时使用。 参见 列表属性 。

构建镜像时不使用缓存

构建镜像时不使用缓存

docker.squash

将新构建的层压缩为单一层（需 API 1.25 + 版本支持，且需在 Docker 守护进程配置中启用）

Docker.optimise

若设置为 true，则会将所有 runCmds 压缩为单个 RUN 指令，从而仅创建一个镜像层。

Docker.portPropertyFile

指定容器启动时使用的端口映射路径。

Docker.ports.idx

设置端口映射。例如，<docker.ports.1>jolokia.ports:8080<docker.ports.1> 将容器端口 8080 动态映射到主机端口，并将该主机端口分配给 Maven 属性 ${jolokia.port}。有关可能的映射选项，请参阅 端口映射 。在创建镜像时，仅使用最右侧的端口进行暴露。若要提供多个端口映射，应递增索引计数。 关于列表属性的更多信息，请参见 列表属性 。

Docker.registry

用于推送镜像的注册表。

Docker.restartpolicy.name

容器重启策略

Docker.restartPolicy.retry

若使用 on-failure 策略时的最大重启重试次数

Docker.run.idx

创建镜像时要运行的命令列表。 参见 列表属性 。

Docker.securityOpts.idx

用于指定容器内核安全选项的 opt 元素列表。例如 docker.securityOpt.1=seccomp=unconfined。 参见 列表属性 。

Docker.shmsize

‘/dev/shm‘ 的大小（以字节为单位）。

Docker.tags.idx

应用于构建镜像的标签列表。 参见 列表属性 。

Docker.tmpfs.idx

一个或多个用于 tmpfs 的挂载点。在冒号后添加挂载选项。 参见 列表属性 。

Docker.ulimits.idx

容器的 Ulimits 设置。Ulimit 通过软限制和硬限制来指定，格式为 & lt; 类型 & gt;=< 软限制 & gt;[:< 硬限制 & gt;]，例如 docker.ulimits.1=memlock=-1:-1。 详情参阅 属性列表 。

Docker.user

在 Dockerfile 末尾切换到的用户。不要与 docker.username 混淆，后者用于与 Docker 注册表交互时的身份验证。

Docker.volumes.idx

定义在构建镜像时要暴露的卷列表。参见 列表属性 。

Docker.volumesFrom.idx

定义了一个容器应挂载的镜像别名列表。例如，<docker.volumesFrom.1>data</docker.volumesFrom.1> 将挂载由数据镜像导出的所有卷。 参阅 列表属性 。

Docker.wait.http.url

容器启动期间等待的 URL

Docker.wait.http.method 用于容器启动期间进行 ping 检查的 HTTP 方法

用于 ping 检查的 HTTP 方法

Docker.wait.http.status

执行 HTTP ping 检查时等待的状态码

Docker.wait.time

容器启动时等待的时间（单位：毫秒）

Docker.wait.log

等待日志输出出现。

Docker.wait.exec.postStart

容器启动后执行的命令。

容器停止前执行的命令

在命令停止前执行的指令。

Docker.wait.exec.breakOnError

如果设置为 “true”，则当 postStart 或 preStop 命令失败时停止构建

Docker.wait.shutdown

等待停止容器与移除容器之间的时间（以毫秒计）。

Docker.wait.tcp.mode

等待 TCP 连接时，可以是映射模式或直接模式

Docker.wait.tcp.host

用于 TCP 等待检查的主机名

Docker.wait.tcp.port.idx

用于 TCP 检查的端口列表。参见 列表属性 。

Docker.wait.kill

停止容器时，发送 SIGTERM 信号后等待发送 SIGKILL 信号的毫秒时间。

Docker.workdir

构建镜像时容器的工作目录

Docker.workingDir

运行容器时命令执行的当前工作目录

若多个属性配置处理器采用不同的前缀，则可同时使用。如前所述，环境与端口配置既用于运行容器，也用于构建镜像。如需独立配置，应明确区分运行与构建配置区块。

列表属性
列表属性指的是 XML 配置项中接受一系列值的元素，如‘‘或‘‘。若要通过属性指定这些值，必须为每个要添加到列表中的值声明一个属性，并在属性名后添加‘idx‘后缀以确定其在最终列表中的位置。例如：

<docker.ports.1>80<docker.ports.1>
<docker.ports.2>8080<docker.ports.2>

<docker.tags.jenkins>${BUILD_TIMESTAMP}</docker.tags.jenkins>
<docker.tags.current>latest</docker.tags.current>
Idx 后缀定义了复制的顺序。首先复制 idx 为整数的条目，按解析后的 idx 值升序排列；其次复制 idx 非整数的条目，按 idx 的字母顺序升序排列。

结合属性与 XML 配置
默认情况下，属性处理器仅会考虑属性而忽略 XML/POM 文件中的其他镜像配置。自 0.25.0 版本起，可通过添加 配置来改变这一行为，该配置可选用以下任一值：

表 36. 属性模式
only

仅关注属性，忽略此镜像的任何 或 部分。此为默认行为，也是 0.25.0 版本之前的处理方式。

override

若已设置属性则使用属性值，否则回退至该镜像的 或 部分查找的值。

fallback

使用该镜像的 或 部分中找到的值，否则回退到属性值。

skip

有效禁用属性，等同于完全不指定 部分。

外部激活属性配置
此外，还可以通过将属性‘docker.imagePropertyConfiguration‘设置为有效的属性模式来激活属性配置，而无需添加‘‘部分。此时，插件将使用所有默认带有‘docker.‘前缀的属性。这一功能在大部分配置已通过 XML/POM 文件指定，但需要在不修改 POM 文件的情况下覆盖某些配置值时尤为实用（可将此配置添加至父 POM 或全局的 settings.xml 文件中）。

如果在父 POM 中设置但不想在特定项目中生效，可以通过在本地将该属性值覆盖为 “skip” 来禁用该特定项目的属性配置。然而，根据 Maven 的设计，如果在 settings.xml 中设置该属性，则该值始终优先于 pom.xml 中定义的任何属性。

对于包含多张镜像的配置，默认情况下使用此属性将产生错误。所有镜像将共用相同的 docker 属性前缀，导致生成多个相同的配置。可以通过为所有镜像（或至少除一个之外的所有镜像）添加带有明确 的 配置元素来覆盖此行为。通常，您会希望为每个镜像使用不同的前缀，但若显式设置，则允许所有镜像使用相同前缀（甚至包括 docker）。这在您仅希望共享少量属性时非常有用。此功能仅在属性模式为 override 或 fallback，且镜像特定配置定义于 POM 配置中时才有意义。

例如，请参阅 此处

合并 POM 与属性值
对于某些字段，可能需要合并来自 POM 和属性的值。例如，在特定的运行环境中，我们可能希望注入一个 http_proxy 环境变量，但又不希望将此添加到 POM 文件中。

此问题通过采用一种名为 Combine 的策略来解决，该策略可选择替换（replace）或合并（merge）。合并操作仅适用于 Map 或 List 类型的配置。对于字符串、整数等标量值，则不支持此操作。针对 Map 类型，系统会将两个数据源合并，并优先采用优先级较高的数据源内容；而对于 List 类型，则会进行串联操作，优先级较高的数据源中的值将排列在前。

合并策略是针对每个配置键 / 属性指定的，大多数情况下当前默认策略为替换。以下键的默认策略为合并：

docker.args

docker.envBuild

docker.envRun

docker.labels

docker.ports

docker.tags

对于所有配置键（映射 / 列表类型），可通过设置一个附加属性（后缀为.combine）来单独覆盖此行为。例如，若不想合并端口，则设置 docker.ports.combine=replace；若要启用 DNS 合并，则设置 docker.dns._combine=merge。

例如，仅属性

<docker.name>jolokia/demo</docker.name>
<docker.alias>service</docker.alias>
<docker.from>consol/tomcat:7.0</docker.from>
<docker.assembly.descriptor>src/main/docker-assembly.xml</docker.assembly.descriptor>
<docker.env.CATALINA_OPTS>-Xmx32m</docker.env.CATALINA_OPTS>
<docker.label.version>${project.version}</docker.label.version>
<docker.ports.jolokia.port>8080</docker.ports.jolokia.port>
<docker.wait.url>http://localhost:${jolokia.port}/jolokia</docker.wait.url>

io.fabric8 docker-maven-plugin properties docker 例如，结合属性与 XML/POM 配置 src/main/docker-assembly.xml -Xmx32m ${project.version} 8080 http://localhost:${jolokia.port}/jolokia io.fabric8 docker-maven-plugin properties docker override

        <name>jolokia/demo</name>
        <alias>service</alias>

        <build>
          <from>consol/tomcat:7.0</from>
          <labels>
            <software>tomcat</software>
          </labels>
        </build>
      </image>
    </images>
  </configuration>
</plugin>

这将构建出与之前示例相同的镜像。如果改用命令‘mvn docker:build -Pdocker.from=console/tomcat:8.0 -Ddocker.tags.0=tc8-test‘进行构建，则会基于该镜像构建，并同时为该镜像添加此标签。

如果添加了 - Ddocker.labels.status=beta 参数，镜像将被赋予两个标签：status=beta 和 software=tomcat。若添加 - Ddocker.labels._combine=replace 参数，则镜像仅会获得一个标签：status=beta。

例如，外部激活属性配置，单一镜像
全局～/.m2/settings.xml 文件：

http-proxy http://proxy.example.com:8080 http://proxy.example.com:8080 override io.fabric8 docker-maven-plugin jolokia/demo service consol/tomcat:7.0 当插件在具有给定 settings.xml 配置的机器上执行时，该插件将识别 docker.imagePropertyConfiguration 配置并启用属性合并功能。构建过程中，它将注入 http_proxy 构建参数（ARG）；而在运行时，则会注入 http_proxy 环境变量（ENV）。其余配置均从 XML 文件中获取，除非 Maven 项目中定义了其他以 docker.* 开头的属性。

示例，外部激活属性配置，两个镜像
沿用之前示例中的全局～/.m2/settings.xml 文件，但在定义了两个镜像且无额外配置的情况下，会导致错误提示：无法在包含多个镜像的项目中使用 docker.imagePropertyConfiguration 属性。

通过在两个镜像中添加具有相同前缀的显式外部配置指令，此错误将被禁用。

io.fabric8 docker-maven-plugin properties docker override

        <name>jolokia/demo</name>
        <alias>service</alias>
        <build>
          <from>consol/tomcat:7.0</from>
        </build>
      </image>

      <image>
        <external>
          <type>properties</type>
          <prefix>docker</prefix>
          <mode>override</mode>
        </external>

        <name>jolokia/demo2</name>
        <alias>service2</alias>
        <build>
          <from>consol/tomcat:7.0</from>
        </build>
      </image>
    </images>
  </configuration>
</plugin>

现在的行为将与之前的示例相同。请注意，必须明确声明 override，否则将仅使用默认模式。

6.2. Docker Compose
该插件还支持通过 docker-compose 文件进行配置，尤其适用于运行在 docker-compose.yml 中指定的容器。Docker Compose 处理功能也可作为外部配置提供程序使用。

示例

webapp
fabric8/compose-demo:latest

compose
src/main/docker
docker-compose.yml

….

…
…

镜像的别名用作与 Docker Compose 文件中服务关联的键映射
需使用 配置处理器以支持 Docker Compose 功能
外部配置提供者的类型必须设置为 compose
用于处理程序的额外配置，指定 compose 文件的查找位置
可额外提供 ‘‘、‘‘ 和 ‘‘ 配置，这些配置将作为 Docker Compose 服务 webapp（按别名指定）的默认配置。
可提供以下选项：

表 37. Docker Compose 配置
元素
描述
默认
基础目录

用于查找 compose 文件的基础目录，同时也是检查 compose 文件时使用的工作目录。所有相对卷绑定都将相对于此目录进行解析。

${basedir}/src/main/docker

Compose 文件

要使用的 compose 文件名称

docker-compose.yml

忽略构建

忽略 compose 文件中的 build: 部分，仅使用插件的构建配置。

false

Docker Compose 文件可以包含如 Docker Compose 文档 所述的变量。这些变量会被替换为 Maven 项目属性。请注意，当带有变量的 docker-compose.yml 文件需要与 docker-compose CLI 命令一起使用时，这些变量同时也必须是有效的环境变量（即不能包含点号 .）。

除了‘docker-compose.yml‘文件外，您还可以为 、 和 配置元素添加所有已知选项，这些选项将作为默认值使用，并会被‘docker-compose.yml‘文件中定义的配置覆盖。XML 配置与‘docker-compose.yml‘文件中的信息通过 & lt;alias> 名称进行关联合并。例如，如果 XML 镜像配置的别名是‘webapp‘，那么它将作为 Docker Compose 服务名为‘webapp‘的默认配置。而 compose 文件中定义的所有其他服务则保持不变。

6.2.1. 限制
以下 Docker Compose 文件关键字目前暂不支持：

Cgroup_parent、devices、env_file、expose、pid、security_opt、stop_signal、cpu_quota、ipc、mac_address、read_only 目前尚未支持（但未来版本可能会实现）。

扩展以包含其他 Docker Compose 文件的功能尚未实现。

目前仅支持对服务的评估，尚不支持对卷（volumes）和网络（networks）的操作。

在 Docker Compose 文件中使用 depends_on 的长语法 时，请注意该插件无法支持所有可能的用法组合。根本原因在于此插件采用基于 等待条件 暂停执行的机制（这些条件附加于依赖容器），而 Docker Compose 则是在启动依赖容器时进行检查。需注意，只要任一等待条件满足，容器的执行便会继续。

7. 注册表处理
   Docker 使用注册表来存储镜像。注册表通常作为名称的一部分被指定。也就是说，如果名称的第一部分（第一个斜杠 / 之前的所有内容）包含点（.）或冒号（:），则该部分会被解析为远程注册表的地址（可选包含端口）。在推送（push）和拉取（pull）操作期间，将使用此注册表（如果未指定注册表，则默认为 docker.io）。本插件遵循相同的语义，因此如果镜像名称中指定了注册表部分，则会联系该注册表。身份验证将在下一 节 中说明。

然而，在某些情况下，您可能希望更灵活地指定远程仓库。这或许是因为您不想在 pom.xml 中硬编码仓库地址，而是希望通过环境变量或系统属性从外部提供。

该插件支持多种指定注册表的方式：

如果镜像名称包含注册表部分，则该注册表将被无条件使用，且无法从外部覆盖。

如果镜像名称中未包含注册表，则默认情况下，推送和拉取操作会使用默认的 Docker 注册表 docker.io。但这一默认设置可通过多种方式覆盖：

如果 配置中包含 子元素，则使用该注册表。

否则，将评估全局配置元素 ，该元素也可通过系统属性 - Ddocker.registry 提供。

最后，系统会查找环境变量 DOCKER_REGISTRY 以确定使用的注册表。

该注册表用于拉取（例如在执行 docker:build 时自动拉取基础镜像）以及通过 docker:push 推送镜像。然而，当这两个目标在命令行中联合使用时，例如执行‘mvn -Ddocker.registry=myregistry:5000 package docker:build docker:push‘命令，系统会为两项操作采用同一注册表。若需更精细的控制，可分别指定用于拉取和推送操作的独立注册表。

在插件的配置中，分别使用参数 和 。

通过系统属性‘docker.pull.registry‘和‘docker.push.registry‘分别指定。

示例

docker.jolokia.org:443



jolokia/jolokia-java

docker.ro14nd.de
….


postgresql

….



docker.example.com:5000/another/server



在使用如上所述的外部提供注册表时，存在一些特殊行为：

在拉取镜像时，被拉取的镜像还会被打上一个不包含注册表地址的仓库名称标签。这样设计的目的是，当配置中不再明确指定注册表时，仍可通过此名称引用该镜像。

推送本地镜像时，会临时添加一个包含注册表地址的标签，并在推送完成后移除。这一操作是必要的，因为 Docker 只能推送带有注册表命名的镜像。

8. 认证
   在拉取（通过 docker:start 的 autoPull 模式）或推送镜像时，可能需要对 Docker 注册表进行身份验证。

在搜索凭证时，会依次查找以下六种不同的位置：

从外部提供系统属性 docker.username 和 docker.password。

从外部提供系统属性 registry.username 和 registry.password。

在插件配置中使用 部分，包含 和 元素。

在～/.config/kube 中使用 OpenShift 配置

在～/.m2/settings.xml 中使用 配置

使用 docker login 登录到注册表（凭据存储在凭据助手或～/.docker/config.json 中）

直接在 pom.xml 中使用用户名和密码并不推荐，因为这会广泛可见。不过，这是最简单且透明的方式。使用 则更为直接明了：

consol/tomcat-7.0 ... jolokia s!cr!t 在使用诸如 Jenkins 等 CI 服务器时，系统属性提供的凭证是一个不错的折中方案。您只需从外部提供这些凭证即可：

示例
mvn -Ddocker.username=jolokia -Ddocker.password=s!cr!t docker:push
最符合 Maven 风格的做法是在 Maven 设置文件～/.m2/settings.xml 中添加一个服务器配置：

示例


docker.io
jolokia
s!cr!t

….

服务器 ID 必须指定推送 / 拉取镜像的注册表，默认情况下是中央索引 docker.io（或备选方案 index.docker.io/registry.hub.docker.com）。此处应添加您的 docker.io 账户以管理个人仓库。若同一注册表下存在多个账户，第二个用户可作为 ID 的一部分进行指定。例如上述场景中，若您拥有第二个账户’fabric8io’，则使用 docker.io/fabric8io 作为该条目。即：在 ID 名称后通过斜杠附加用户名。仅当未选择带用户名的服务器条目时，系统才会采用默认的无用户名配置。

最安全的方式是依赖 Docker 的凭证存储或凭证助手，并从外部凭证存储（如操作系统的原生钥匙串）中读取机密信息。请按照 Docker 登录文档 中的说明操作。

作为最后的备用方案，该插件会查询 $DOCKER_CONFIG/config.json（若 DOCKER_CONFIG 已设置）或～/.docker/config.json（若未设置），并直接读取存储在此文件中的凭据。这种不安全行为发生在以下情况：使用旧版 docker（1.13.0 之前）通过命令行执行 docker login 命令连接注册表时，或 docker 未配置使用 凭证存储 时。

8.1. 拉取式与推送式认证
上述凭证查找方式适用于推送和拉取操作。为了进一步细化，可以仅为拉取或推送操作提供凭证：

在 部分中，可以添加一个 和 / 或 子节。以下示例中，凭证提供程序仅用于镜像推送操作：

示例


consol/tomcat-7.0
…


jolokia
s!cr!t




当凭证通过命令行作为系统属性提供时，属性 ‘docker.pull.username‘ / ‘docker.pull.password‘ 和 ‘docker.push.username‘ / ‘docker.push.password‘ 将分别用于拉取和推送操作（若已提供）。无论哪种情况，均会采用前一节所述的标准查找算法作为备用方案。

8.2. OpenShift 认证
在使用 OpenShift 默认注册表时，认证所需的凭据是 OpenShift 用户名和访问令牌。因此，从外部与 OpenShift 注册表交互的典型流程如下：

oc login
…
mvn -Ddocker.registry=docker-registry.domain.com:80/default/myimage
-Ddocker.username=$(oc whoami)
-Ddocker.password=$(oc whoami -t)
（请注意，镜像的用户名部分（此处为 “default”）必须与当前连接账户有访问权限的同名 OpenShift 项目相对应。）

这可以通过使用系统属性‘docker.useOpenShiftAuth‘来简化，此时插件会自动执行查找。与上述示例等效的做法是：

oc login
…
mvn -Ddocker.registry=docker-registry.domain.com:80/default/myimage
-Ddocker.useOpenShiftAuth
或者，也可以在 部分添加配置选项 。

对于专用的拉取和推送配置，系统属性‘docker.pull.useOpenShiftAuth‘和‘docker.push.useOpenShiftAuth‘同样可用，此外在‘‘配置中的‘‘或‘‘部分内，也提供了配置选项‘‘。

如果启用了 useOpenShiftAuth，系统将在环境变量 $KUBECONFIG 中查找 OpenShift 配置，若未设置该环境变量，则转而查找～/.kube/config 文件。

8.3. 密码加密
无论选择哪种模式，您都可以按照 Maven 文档 中所述对密码进行加密。假设您已在～/.m2/security-settings.xml 文件中设置了主密码，即可轻松创建加密密码：

示例
$ mvn –encrypt-password
Password:
{QJ6wvuEfacMHklqsmrtrn1/ClOLqLm8hB7yUL23KOKo=}
随后，该密码可用于 authConfig、docker.password 及 / 或 配置设置中。然而，将加密后的密码放入 pom.xml 的 authConfig 内并无太大意义，因为此密码是使用个人主密码加密的。

8.4. 扩展认证
某些 Docker 注册表需要额外的步骤进行身份验证。Amazon ECR 要求使用 IAM 访问密钥来获取临时的 Docker 登录凭证。 对于任何形式为 & lt;awsAccountId>.dkr.ecr..amazonaws.com 的注册表，除非 skipExtendedAuth 配置（docker.skip.extendedAuth 属性）设为 true，否则 docker:push 和 docker:pull 目标会自动执行这一凭证交换过程。

请注意，对于 URI 为 123456789012.dkr.ecr.eu-west-1.amazonaws.com/example/image 的 ECR 仓库，d-m-p 的 docker.registry 应设置为 123456789012.dkr.ecr.eu-west-1.amazonaws.com，而 example/image 则是该镜像的 <名称>。

您可以使用任何具有必要权限的 IAM 访问密钥，但需注意上述提及的位置中不包括～/.docker/config.json。将 IAM 访问密钥 ID 作为用户名，秘密访问密钥作为密码。若您使用的是 AWS 安全令牌服务（AWS STS）提供的临时安全凭证，则还需同时提供安全令牌。为此，您可以通过指定 docker.auth 系统属性，或在 authConfig 中与用户名和密码并列提供 元素来实现。

D-m-p 在没有显式配置的情况下，会尝试从一些已知的位置读取 AWS 凭据：

它将获取环境变量 如 AWS CLI 文档所述

它将获取 EC2 实例的 IAM 角色 的临时凭证

它将获取 Fargate 任务（或使用 EC2 且 ECS_AWSVPC_BLOCK_IMDS 设为 “true” 的 ECS）的 IAM 角色 的临时凭证

如果这些认证信息中的任何一项可被获取，就会被使用。

为了获得更完整、稳健且可靠的认证体验，您可以将 AWS SDK for Java 添加为依赖项。

io.fabric8 docker-maven-plugin com.amazonaws aws-java-sdk-core 1.11.707 这一额外依赖使得可以使用 AWS 默认凭证提供链所支持的所有 选项 。

如果在类路径中发现了 AWS SDK，它将优先于上述自定义的 AWS 凭证查找机制。

9. 隐式属性
   Docker Maven 插件中存在一些不太直观的隐式配置。这些仅为确保 docker-maven-plugin 流程正确而采取的变通方案，旨在克服 Maven 及其他方面的限制。以下列举了部分此类配置：

如果‘env‘参数的唯一值是一个由 docker-maven-plugin 内部隐式设置的属性，则必须在该属性前加上单个‘+‘号，如‘+${docker.container.test.ip}‘。由于 Maven 的一些限制，未定义的单独属性在初始插值阶段会被简单地替换为空字符串，之后该插件无法再进行替换，因此这一操作是必要的。

在提供端口映射时，若采用‘host.ip:host.port:80‘格式，需在属性前添加单个‘+‘作为前缀。此形式下，容器的主机 IP 将被存入名为‘host.ip‘的 Maven 属性中。若 Docker 反馈该值为‘0.0.0.0‘，则系统会自动替换为‘docker.host.address‘的值。若需通过此形式让容器绑定到特定主机名 / IP 地址，可声明同名 Maven 属性（本例中为‘host.ip‘）并指定目标值。‘host:port‘的运作机制与上述描述完全一致。

10. 延伸阅读
    示例：

示例 位于 samples / 目录下，包含可供您作为自己项目蓝图的示例配置。

一场 对决 ，用于比较 Docker Maven 插件

另一个 示例项目 ，包含微服务和数据库。

更新日志 记录了这个插件的发布历史。

贡献指南 说明了如何为该项目做出贡献。我们非常欢迎提交拉取请求！