Packer 之Docker Builder

The docker Packer builder builds Docker images using Docker. The builder starts a Docker container, runs provisioners within this container, then exports the container for reuse or commits the image.

docker Packer构建器使用Docker构建Docker镜像。 构建器启动Docker容器，在此容器中运行供应器，然后导出容器以供重用或提交映像。

Packer builds Docker containers without the use of Dockerfiles. By not using Dockerfiles, Packer is able to provision containers with portable scripts or configuration management systems that are not tied to Docker in any way. It also has a simple mental model: you provision containers much the same way you provision a normal virtualized or dedicated server. For more information, read the section on Dockerfiles.

Packer在不使用Dockerfiles的情况下构建Docker容器。 通过不使用Dockerfiles，Packer能够以任何方式使用与Docker无关的可移植脚本或配置管理系统来配置容器。 它还有一个简单的心理模型：您可以像配置普通的虚拟化或专用服务器一样配置容器。 有关更多信息，请阅读Dockerfiles部分。

The Docker builder must run on a machine that has Docker Engine installed. Therefore the builder only works on machines that support Docker and does not support running on a Docker remote host. You can learn about what platforms Docker supports and how to install onto them in the Docker documentation.

Docker构建器必须在安装了Docker Engine的计算机上运行。 因此，构建器仅适用于支持Docker且不支持在Docker远程主机上运行的计算机。 您可以在Docker文档中了解Docker支持的平台以及如何安装它们。

Please note: Packer does not yet have support for Windows containers.
请注意： Packer还不支持Windows容器

1. Basic Example: Export（基本示例：导出）
   Below is a fully functioning example. It doesn’t do anything useful, since no provisioners are defined, but it will effectively repackage an image.

下面是一个功能齐全的例子。 它没有做任何有用的事情，因为没有定义配置器，但它会有效地重新打包图像。

{
  "type": "docker",
  "image": "ubuntu",
  "export_path": "image.tar"
}

2. Basic Example: Commit（基本示例：提交）
   Below is another example, the same as above but instead of exporting the running container, this one commits the container to an image. The image can then be more easily tagged, pushed, etc.

下面是另一个例子，与上面相同，但不是导出正在运行的容器，而是将容器提交给图像。 然后可以更容易地标记，推送图像等。

{
  "type": "docker",
  "image": "ubuntu",
  "commit": true
}

3.Basic Example: Changes to Metadata（基本示例：元数据的更改）
Below is an example using the changes argument of the builder. This feature allows the source images metadata to be changed when committed back into the Docker environment. It is derived from the docker commit --change command line option to Docker.

Example uses of all of the options, assuming one is building an NGINX image from ubuntu as an simple example:

下面是使用构建器的changes参数的示例。 此功能允许在提交回Docker环境时更改源图像元数据。 它源自Docker的docker commit --change命令行选项。

示例使用所有选项，假设一个正在从ubuntu构建NGINX图像作为一个简单示例：

{
  "type": "docker",
  "image": "ubuntu",
  "commit": true,
  "changes": [
    "USER www-data",
    "WORKDIR /var/www",
    "ENV HOSTNAME www.example.com",
    "VOLUME /test1 /test2",
    "EXPOSE 80 443",
    "LABEL version=1.0",
    "ONBUILD RUN date",
    "CMD [\"nginx\", \"-g\", \"daemon off;\"]",
    "ENTRYPOINT /var/www/start.sh"
  ]
}

可以更改的允许元数据字段包括：

CMD
String, supports both array (escaped) and string form
EX: “CMD [“nginx”, “-g”, “daemon off;”]”
EX: “CMD nginx -g daemon off;”
ENTRYPOINT
String
EX: “ENTRYPOINT /var/www/start.sh”

ENV
String, note there is no equal sign:
EX: “ENV HOSTNAME www.example.com” not “ENV HOSTNAME=www.example.com”

EXPOSE
String, space separated ports
EX: “EXPOSE 80 443”

LABEL
String, space separated key=value pairs
EX: “LABEL version=1.0”

ONBUILD
String
EX: “ONBUILD RUN date”

MAINTAINER
String, deprecated in Docker version 1.13.0
EX: “MAINTAINER NAME”

USER
String
EX: “USER USERNAME”

VOLUME
String
EX: “VOLUME FROM TO”

WORKDIR
String
EX: “WORKDIR PATH”

4. Configuration Reference（配置参考）

Configuration options are organized below into two categories: required and optional. Within each category, the available options are alphabetized and described.

The Docker builder uses a special Docker communicator and will not use the standard communicators.

配置选项在下面分为两类：必需和可选。 在每个类别中，可用选项按字母顺序排列和描述。

Docker构建器使用特殊的Docker通信器，不会使用标准的通信器。

Required（必需）:
You must specify (only) one of commit, discard, or export_path.
您必须（仅）指定commit，discard或export_path之一。

commit (boolean) - If true, the container will be committed to an image rather than exported.

discard (boolean) - Throw away the container when the build is complete. This is useful for the artifice post-processor.

export_path (string) - The path where the final container will be exported as a tar file.

image (string) - The base image for the Docker container that will be started. This image will be pulled from the Docker registry if it doesn’t already exist.

commit（boolean） - 如果为true，则容器将提交给图像而不是导出。

discard（boolean） - 构建完成后丢弃容器。 这对于后处理器的技巧很有用。

export_path（string） - 将最终容器导出为tar文件的路径。

image（字符串） - 将要启动的Docker容器的基本映像。 如果该图像尚不存在，将从Docker注册表中提取该图像。

Optional（可选）:
author (string) - Set the author (e-mail) of a commit.

aws_access_key (string) - The AWS access key used to communicate with AWS. Learn how to set this.

aws_secret_key (string) - The AWS secret key used to communicate with AWS. Learn how to set this.

aws_token (string) - The AWS access token to use. This is different from the access key and secret key. If you’re not sure what this is, then you probably don’t need it. This will also be read from the AWS_SESSION_TOKEN environmental variable.

aws_profile (string) - The AWS shared credentials profile used to communicate with AWS. Learn how to set this.

changes (array of strings) - Dockerfile instructions to add to the commit. Example of instructions are CMD, ENTRYPOINT, ENV, and EXPOSE. Example: [ “USER ubuntu”, “WORKDIR /app”, “EXPOSE 8080” ]

ecr_login (boolean) - Defaults to false. If true, the builder will login in order to pull the image from Amazon EC2 Container Registry (ECR). The builder only logs in for the duration of the pull. If true login_server is required and login, login_username, and login_password will be ignored. For more information see the section on ECR.

exec_user (string) - Username or UID (format: [:]) to run remote commands with. You may need this if you get permission errors trying to run the shell or other provisioners.

login (boolean) - Defaults to false. If true, the builder will login in order to pull the image. The builder only logs in for the duration of the pull. It always logs out afterwards. For log into ECR see ecr_login.

login_username (string) - The username to use to authenticate to login.

login_password (string) - The password to use to authenticate to login.

login_server (string) - The server address to login to.

message (string) - Set a message for the commit.

privileged (boolean) - If true, run the docker container with the --privileged flag. This defaults to false if not set.

pull (boolean) - If true, the configured image will be pulled using docker pull prior to use. Otherwise, it is assumed the image already exists and can be used. This defaults to true if not set.

run_command (array of strings) - An array of arguments to pass to docker run in order to run the container. By default this is set to ["-d", “-i”, “-t”, “{{.Image}}”, “/bin/bash”]. As you can see, you have a couple template variables to customize, as well.

volumes (map of strings to strings) - A mapping of additional volumes to mount into this container. The key of the object is the host path, the value is the container path.

container_dir (string) - The directory inside container to mount temp directory from host server for work file provisioner. By default this is set to /packer-files.

fix_upload_owner (boolean) - If true, files uploaded to the container will be owned by the user the container is running as. If false, the owner will depend on the version of docker installed in the system. Defaults to true.

author（string） - 设置提交的作者（电子邮件）。

aws_access_key（字符串） - 用于与AWS通信的AWS访问密钥。了解如何设置此功能。

aws_secret_key（string） - 用于与AWS通信的AWS密钥。了解如何设置此功能。

aws_token（string） - 要使用的AWS访问令牌。这与访问密钥和密钥不同。如果您不确定这是什么，那么您可能不需要它。这也将从AWS_SESSION_TOKEN环境变量中读取。

aws_profile（字符串） - 用于与AWS通信的AWS共享凭证配置文件。了解如何设置此功能。

changes（字符串数组） - 要添加到提交的Dockerfile指令。指令示例是CMD，ENTRYPOINT，ENV和EXPOSE。示例：[“USER ubuntu”，“WORKDIR / app”，“EXPOSE 8080”]

ecr_login（boolean） - 默认为false。如果为true，则构建器将登录以从Amazon EC2 Container Registry（ECR）提取映像。构建器仅在拉动期间登录。如果需要true login_server，则将忽略login，login_username和login_password。有关更多信息，请参阅ECR部分。

exec_user（string） - 用户名或UID（格式： [：]）来运行远程命令。如果您在尝试运行shell或其他配置程序时遇到权限错误，则可能需要此操作。

login（boolean） - 默认为false。如果为true，则构建器将登录以提取图像。构建器仅在拉动期间登录。它总是在事后退出。要登录ECR，请参阅ecr_login。

login_username（string） - 用于进行身份验证以登录的用户名。

login_password（string） - 用于对登录进行身份验证的密码。

login_server（string） - 要登录的服务器地址。

message（字符串） - 为提交设置消息。

privileged（boolean） - 如果为true，则使用–privileged标志运行docker容器。如果未设置，则默认为false。

pull（boolean） - 如果为true，则在使用前使用docker pull拉出配置的图像。否则，假设图像已经存在并且可以使用。如果未设置，则默认为true。

run_command（strings of strings） - 要传递给docker运行以运行容器的参数数组。默认情况下，它设置为[“-d”，“ - i”，“ - t”，“{{。Image}}”，“/ bin / bash”]。如您所见，您还有一些模板变量可供自定义。

卷（字符串到字符串的映射） - 要装入此容器的其他卷的映射。对象的键是主机路径，值是容器路径。

container_dir（string） - 用于从工作文件配置器的主机服务器装载临时目录的容器内的目录。默认情况下，它设置为/ packer-files。

fix_upload_owner（boolean） - 如果为true，则上载到容器的文件将由容器运行的用户拥有。如果为false，则所有者将依赖于系统中安装的docker的版本。默认为true。

Using the Artifact: Export （使用工件：导出）
Once the tar artifact has been generated, you will likely want to import, tag, and push it to a container repository. Packer can do this for you automatically with the docker-import and docker-push post-processors.

Note: This section is covering how to use an artifact that has been exported. More specifically, if you set export_path in your configuration. If you set commit, see the next section.

The example below shows a full configuration that would import and push the created image. This is accomplished using a sequence definition (a collection of post-processors that are treated as as single pipeline, see Post-Processors for more information):

生成tar工件后，您可能希望导入，标记并将其推送到容器存储库。 Packer可以使用docker-import和docker-push后处理器自动为您完成此操作。

注意：本节介绍如何使用已导出的工件。 更具体地说，如果在配置中设置export_path。 如果设置了提交，请参阅下一节。

下面的示例显示了可导入和推送创建的图像的完整配置。 这是使用序列定义（被视为单个管道的后处理器集合，有关更多信息，请参阅后处理器）完成的：

{
  "post-processors": [
    [
      {
        "type": "docker-import",
        "repository": "hashicorp/packer",
        "tag": "0.7"
      },
      "docker-push"
    ]
  ]
}

In the above example, the result of each builder is passed through the defined sequence of post-processors starting first with the docker-import post-processor which will import the artifact as a docker image. The resulting docker image is then passed on to the docker-push post-processor which handles pushing the image to a container repository.

If you want to do this manually, however, perhaps from a script, you can import the image using the process below:

在上面的示例中，每个构建器的结果通过docker-import后处理器首先从定义的后处理器序列传递，后者将工件作为docker镜像导入。 然后将生成的泊坞窗图像传递给docker-push后处理器，后处理器处理将图像推送到容器存储库。

但是，如果您想手动执行此操作（可能是脚本），则可以使用以下过程导入图像：

$ docker import - registry.mydomain.com/mycontainer:latest < artifact.tar

You can then add additional tags and push the image as usual with docker tag and docker push, respectively.

然后，您可以添加其他标记，并像往常一样使用docker tag和docker push推送图像。

Using the Artifact: Committed （已提交的）

If you committed your container to an image, you probably want to tag, save, push, etc. Packer can do this automatically for you. An example is shown below which tags and pushes an image. This is accomplished using a sequence definition (a collection of post-processors that are treated as as single pipeline, see Post-Processors for more information)

如果您将容器提交给图像，则可能需要标记，保存，推送等.Packer可以自动为您执行此操作。 下面显示了一个标记和推送图像的示例。 这是使用序列定义（被视为单个管道的后处理器集合，有关更多信息，请参阅后处理器）完成的。

{
  "post-processors": [
    [
      {
        "type": "docker-tag",
        "repository": "hashicorp/packer",
        "tag": "0.7"
      },
      "docker-push"
    ]
  ]
}

In the above example, the result of each builder is passed through the defined sequence of post-processors starting first with the docker-tag post-processor which tags the committed image with the supplied repository and tag information. Once tagged, the resulting artifact is then passed on to the docker-push post-processor which handles pushing the image to a container repository.

Going a step further, if you wanted to tag and push an image to multiple container repositories, this could be accomplished by defining two, nearly-identical sequence definitions, as demonstrated by the example below:
在上面的示例中，每个构建器的结果通过定义的后处理器序列传递，首先使用docker-tag后处理器，后者使用提供的存储库和标记信息标记已提交的映像。 标记后，生成的工件将传递给docker-push后处理器，后处理器处理将图像推送到容器存储库。

更进一步，如果您想标记并将图像推送到多个容器存储库，可以通过定义两个几乎相同的序列定义来完成，如下例所示：

{
  "post-processors": [
    [
      {
        "type": "docker-tag",
        "repository": "hashicorp/packer1",
        "tag": "0.7"
      },
      "docker-push"
    ],
    [
      {
        "type": "docker-tag",
        "repository": "hashicorp/packer2",
        "tag": "0.7"
      },
      "docker-push"
    ]
  ]
}

Amazon EC2 Container Registry (亚马逊EC2容器注册表)
Packer can tag and push images for use in Amazon EC2 Container Registry. The post processors work as described above and example configuration properties are shown below:
Packer可以标记和推送图像，以便在Amazon EC2 Container Registry中使用。 后处理器的工作方式如上所述，示例配置属性如下所示：

{
  "post-processors": [
    [
      {
        "type": "docker-tag",
        "repository": "12345.dkr.ecr.us-east-1.amazonaws.com/packer",
        "tag": "0.7"
      },
      {
        "type": "docker-push",
        "ecr_login": true,
        "aws_access_key": "YOUR KEY HERE",
        "aws_secret_key": "YOUR SECRET KEY HERE",
        "login_server": "https://12345.dkr.ecr.us-east-1.amazonaws.com/"
      }
    ]
  ]
}

Dockerfiles
This builder allows you to build Docker images without Dockerfiles.

With this builder, you can repeatedly create Docker images without the use of a Dockerfile. You don’t need to know the syntax or semantics of Dockerfiles. Instead, you can just provide shell scripts, Chef recipes, Puppet manifests, etc. to provision your Docker container just like you would a regular virtualized or dedicated machine.

While Docker has many features, Packer views Docker simply as an container runner. To that end, Packer is able to repeatedly build these containers using portable provisioning scripts.

此构建器允许您在没有Dockerfiles的情况下构建Docker镜像。

使用此构建器，您可以重复创建Docker映像，而无需使用Dockerfile。 您不需要知道Dockerfiles的语法或语义。 相反，您可以提供shell脚本，Chef配方，Puppet清单等来配置Docker容器，就像使用常规虚拟化或专用计算机一样。

虽然Docker具有许多功能，但Packer只是将Docker视为容器运行器。 为此，Packer能够使用可移植配置脚本重复构建这些容器。

Overriding the host directory(覆盖主机目录)
By default, Packer creates a temporary folder under your home directory, and
uses that to stage files for uploading into the container. If you would like to change the path to this temporary folder, you can set the PACKER_TMP_DIR. This can be useful, for example, if you have your home directory permissions set up to disallow access from the docker daemon.

默认情况下，Packer会在您的主目录下创建一个临时文件夹
使用它来暂存文件以便上传到容器中。 如果要更改此临时文件夹的路径，可以设置PACKER_TMP_DIR。 例如，如果您将主目录权限设置为禁止从docker守护程序进行访问，则此操作非常有用。