Docker-maven-plugin 文档翻译

原文地址：https://github.com/spotify/docker-maven-plugin

 

 

A Maven plugin for building and pushing Docker images.

用于构建和推送Docker镜像的Maven插件。

 

We recommend that new projects use dockerfile-maven. This project will no longer have new features or accept PRs for new features. We will continue to accept bug fixes, however.

 

我们建议新项目使用dockerfile-maven。这个项目将不再有新特性，或者接受PRs作为新特性。但是，我们将继续接受bug修复。

 

The future of docker-maven-plugin

This plugin was the initial Maven plugin used at Spotify for building Docker images out of Java services. It was initially created in 2014 when we first began experimenting with Docker. This plugin is capable of generating a Dockerfile for you based on configuration in the pom.xml file for things like the FROM image, resources to add with ADD/COPY, etc.

 

这个插件是Spotify最初使用的Maven插件，用于从Java服务构建Docker映像。它最初创建于2014年，当时我们第一次开始使用Docker。这个插件能够根据pom中的配置为您生成Dockerfile。xml文件的内容，如从图像，资源添加与添加/复制，等等。

 

Over time at Spotify we have realized that the simplest way to build a Docker image from a Java project is to have the developer write the Dockerfile. The behavior of this plugin around generating Dockerfiles, copying your project directory to a "staging" directory to use as the Docker build context, etc., ultimately led to a lot of unnecessary confusion with our users that stemmed from introducing extra abstractions and a need for configuration on top of what Docker is providing.

 

随着时间的推移，我们在Spotify认识到，从Java项目构建Docker映像最简单的方法是让开发人员编写Dockerfile。这个插件生成Dockerfiles周围的行为,你的项目目录复制到“暂存”目录作为Docker 建立上下文,等等,最终导致很多不必要的混乱与我们的用户,源于引入额外的抽象和需要配置的Docker提供什么。

 

This led to the creation of a second Maven plugin for building docker images, dockerfile-maven, which we think offers a simpler mental model of working with Docker from Maven, for all of the reasons outlined in dockerfile-maven's README.

 

这导致创建了第二个用于构建docker映像的Maven插件dockerfile-maven，我们认为它提供了一个更简单的使用来自Maven的docker的心智模型，原因见dockerfile-maven的README。

 

Purpose

You can use this plugin to create a Docker image with artifacts built from your Maven project. For example, the build process for a Java service can output a Docker image that runs the service.

您可以使用这个插件创建一个Docker镜像，其中包含从Maven项目构建的工件。例如，Java服务的构建过程可以输出运行该服务的Docker镜像。

 

Setup

You can specify the base image, entry point, cmd, maintainer and files you want to add to your image directly in the pom, without needing a separate Dockerfile. If you need VOLUME command(or any other not supported dockerfile command), then you will need to create a Dockerfile and use the dockerDirectory element.

您可以在pom中指定要直接添加到映像中的基本映像、入口点、cmd、维护者和文件，而不需要单独的Dockerfile。如果需要VOLUME命令(或不支持的dockerfile命令)，则需要创建一个dockerfile并使用dockerDirectory元素。

By default the plugin will try to connect to docker on localhost:2375. Set the DOCKER_HOST environment variable to connect elsewhere.

默认情况下，插件将尝试连接到本地主机:2375上的docker。设置DOCKER_HOST环境变量以连接到其他地方。

DOCKER_HOST=tcp://<host>:2375

Other docker-standard environment variables are honored too such as TLS and certificates.

其他docker标准环境变量(如TLS和证书)也获得了荣誉。

 

Specify build info in the POM

This example creates a new image named example, copies the project's jar file into the image, and sets an entrypoint which runs the jar. Change VERSION GOES HERE to the latest tagged version.

这个示例创建一个名为example的新映像，将项目的jar文件复制到映像中，并设置一个运行jar的入口点。更改版本将转到这里的最新标记版本。

<build>

<plugins>

...

<plugin>

<groupId>com.spotify</groupId>

<artifactId>docker-maven-plugin</artifactId>

<version>VERSION GOES HERE</version>

<configuration>

<imageName>example</imageName>

<baseImage>java</baseImage>

<entryPoint>["java", "-jar", "/${project.build.finalName}.jar"]</entryPoint>

<!-- copy the service's jar file from target into the root directory of the image -->

<resources>

<resource>

<targetPath>/</targetPath>

<directory>${project.build.directory}</directory>

<include>${project.build.finalName}.jar</include>

</resource>

</resources>

</configuration>

</plugin>

...

</plugins>

</build>

 

Usage

You can build an image with the above configurations by running this command.

通过运行此命令，您可以使用上述配置构建镜像。

mvn clean package docker:build

 

To push the image you just built to the registry, specify the pushImage flag.

要将刚刚构建的映像推送到注册表，请指定pushImage标志。

mvn clean package docker:build -DpushImage

 

To push only specific tags of the image to the registry, specify the pushImageTag flag.

若要将特定标记的镜像推送到注册表，请指定pushImageTag标志。

mvn clean package docker:build -DpushImageTag

 

In order for this to succeed, at least one imageTag must be present in the config, multiple tags can be used.

为了成功，配置中必须至少有一个imageTag，可以使用多个标记。

<build>

<plugins>

...

<plugin>

<configuration>

...

<imageTags>

<imageTag>${project.version}</imageTag>

<imageTag>latest</imageTag>

</imageTags>

</configuration>

</plugin>

...

</plugins>

</build>

Optionally, you can force docker to overwrite your image tags on each new build:

<build>

<plugins>

...

<plugin>

<configuration>

...

<!-- optionally overwrite tags every time image is built with docker:build -->

<forceTags>true</forceTags>

<imageTags>

...

</imageTags>

</configuration>

</plugin>

...

</plugins>

</build>

Tags-to-be-pushed can also be specified directly on the command line with

还可以在命令行中直接指定要推送的标记

mvn ... docker:build -DpushImageTag -DdockerImageTags=latest,another-tag

 

Bind Docker commands to Maven phases

You can also bind the build, tag & push goals to the Maven phases, so the container will be built, tagged and pushed when you run just mvn deploy. If you have a multi-module project where a sub-module builds an image, you will need to do this binding so the image gets built when maven is run from the parent project.

您还可以将构建、标记和推送目标绑定到Maven 声明周期，以便在只运行mvn部署时构建、标记和推送容器。如果您有一个多模块项目，其中一个子模块构建一个映像，那么您将需要执行此绑定，以便在从父项目运行maven时构建映像。

<build>

<plugins>

...

<plugin>

<configuration>

...

<imageTags>

<imageTag>${project.version}</imageTag>

<imageTag>latest</imageTag>

</imageTags>

</configuration>

</plugin>

...

</plugins>

</build>

Optionally, you can force docker to overwrite your image tags on each new build:

<build>

<plugins>

...

<plugin>

<configuration>

...

<!-- optionally overwrite tags every time image is built with docker:build -->

<forceTags>true</forceTags>

<imageTags>

...

</imageTags>

</configuration>

</plugin>

...

</plugins>

</build>

You can skip Docker goals bound to Maven phases with:

您可以使用以下命令跳过绑定到Maven阶段的Docker目标:

-DskipDockerBuild to skip image build

-DskipDockerTag to skip image tag

-DskipDockerPush to skip image push

-DskipDocker to skip any Docker goals

 

To remove the image named foobar run the following command:

要删除名为foobar的映像，请运行以下命令:

mvn docker:removeImage -DimageName=foobar

 

For a complete list of configuration options run:

要获取配置选项的完整列表，请运行

mvn com.spotify:docker-maven-plugin: <version>:help -Ddetail=true

Using with Private Registries

与私有注册中心一起使用

 

To push an image to a private registry, Docker requires that the image tag being pushed is prefixed with the hostname and port of the registry. For example to push my-image to registry.example.com, the image needs to be tagged as registry.example.com/my-image.

要将镜像推送到私有注册中心，Docker要求所推送的镜像标记以注册中心的主机名和端口为前缀。例如，要将my-image推送到registry.example.com，需要将镜像标记为registry.example.com/my-image。

The simplest way to do this with docker-maven-plugin is to put the registry name in the <imageName> field, for example

使用docker-maven-plugin最简单的方法是将注册表名称放在<imageName>字段中

<plugin>

<groupId>com.spotify</groupId>

<artifactId>docker-maven-plugin</artifactId>

<configuration>

<imageName>registry.example.com/my-image</imageName>

...

Then when pushing the image with either docker:build -DpushImage or docker:push, the docker daemon will push to registry.example.com.

然后，当使用docker:build -DpushImage或docker:push推送映像时，docker守护进程将推送到registry.example.com。

Alternatively, if you wish to use a short name in docker:build you can use docker:tag -DpushImage to tag the just-built image with the full registry hostname and push it. It's important to use the pushImage flag as using docker:push independently will attempt to push the original image.

或者，如果希望在docker:build中使用短名称，可以使用docker:tag -DpushImage用完整注册表主机名标记刚刚构建的映像并推送它。与使用docker一样，使用pushImage标志非常重要:独立的push将尝试推送原始镜像。

For example:

<plugin>

<groupId>com.spotify</groupId>

<artifactId>docker-maven-plugin</artifactId>

<configuration>

<imageName>my-image</imageName>

...

</configuration>

<executions>

<execution>

<id>build-image</id>

<phase>package</phase>

<goals>

<goal>build</goal>

</goals>

</execution>

<execution>

<id>tag-image</id>

<phase>package</phase>

<goals>

<goal>tag</goal>

</goals>

<configuration>

<image>my-image</image>

<newName>registry.example.com/my-image</newName>

</configuration>

</execution>

</executions>

</plugin>

Authentication

Since version 1.0.0, the docker-maven-plugin will automatically use any authentication present in the docker-cli configuration file at ~/.dockercfg or ~/.docker/config.json, without the need to configure anything (in earlier versions of the plugin this behavior had to be enabled with <useConfigFile>true</useConfigFile>, but now it is always active).

从版本1.0.0,docker-maven-plugin将自动使用docker-cli配置文件中~/处的任何身份验证。dockercfg或~ / .docker /config.json，不需要配置任何东西(在早期版本的插件中，这个行为必须通过<useConfigFile>true</useConfigFile>来启用，但现在它总是激活的)。

Additionally the plugin will enable support for Google Container Registry if it is able to successfully load Google's "Application Default Credentials". The plugin will also load Google credentials from the file pointed to by the environment variable DOCKER_GOOGLE_CREDENTIALS if it is defined. Since GCR authentication requires retrieving short-lived access codes for the given credentials, support for this registry is baked into the underlying docker-client rather than having to first populate the docker config file before running the plugin.

此外，如果能够成功加载谷歌的“应用程序默认凭据”，插件将支持谷歌容器注册表。如果定义了环境变量DOCKER_GOOGLE_CREDENTIALS，插件还将从该文件中加载谷歌凭证。由于GCR身份验证需要检索给定凭据的短期访问代码，因此对该注册中心的支持将被放入底层docker-client中，而不必在运行插件之前首先填充docker配置文件。

Lastly, authentication credentials can be explicitly configured in your pom.xml and in your Maven installation's settings.xmlfile as part of the <servers></servers> block.

 

最后，可以在pom中显式配置身份验证凭据。xml和Maven安装的设置中。xmlfile作为<servers></servers>块的一部分。

<servers>

<server>

<id>docker-hub</id>

<username>foo</username>

<password>secret-password</password>

<configuration>

<email>foo@foo.bar</email>

</configuration>

</server>

</servers>

Now use the server id in your project pom.xml.

<plugin>

<plugin>

<groupId>com.spotify</groupId>

<artifactId>docker-maven-plugin</artifactId>

<version>VERSION GOES HERE</version>

<configuration>

[...]

<serverId>docker-hub</serverId>

<registryUrl>https://index.docker.io/v1/</registryUrl>

</configuration>

</plugin>

</plugins>

The plugin gives priority to any credentials in the docker-cli config file before explicitly configured credentials.

Using encrypted passwords for authentication

Credentials can be encrypted using Maven's built in encryption function. Only passwords enclosed in curly braces will be considered as encrypted.

<servers>

<server>

<id>docker-hub</id>

<username>foo</username>

<password>{gc4QPLrlgPwHZjAhPw8JPuGzaPitzuyjeBojwCz88j4=}</password>

</server>

</servers>