撰写构建规范

笔记：

构建是 Compose 规范的可选部分

专注于在本地计算机上运行应用程序的 Compose 实现还需要支持从源代码（重新）构建应用程序。 Compose 构建规范允许您以可移植的方式在 Compose 文件中定义构建过程。

build可以指定为定义上下文路径的单个字符串，也可以指定为详细的构建定义。

在前一种情况下，整个路径用作 Docker 上下文来执行 Docker 构建， Dockerfile在目录的根目录中查找规范。该路径可以是绝对路径或相对路径。如果是相对的，则从 Compose 文件的父文件夹中解析。如果是绝对路径，则该路径会阻止 Compose 文件可移植，因此 Compose 会显示警告。

在后一种情况下，可以指定构建参数，包括备用Dockerfile位置。该路径可以是绝对路径或相对路径。如果是相对的，则从 Compose 文件的父文件夹中解析。如果是绝对路径，则该路径会阻止 Compose 文件可移植，因此 Compose 会显示警告。

使用构建和镜像

当 Compose 遇到build服务的子部分和image属性时，它遵循属性定义的规则 pull_policy。

如果pull_policy服务定义中缺少该镜像，Compose 将首先尝试提取该镜像，然后在注册表或平台缓存中未找到该镜像时从源构建。

发布构建的图像

Compose with buildsupport 提供了将构建的映像推送到注册表的选项。这样做时，它不会尝试推送没有image属性的服务图像。 Compose 会警告您缺少image属性，该属性会阻止推送图像。

说明性示例

以下示例通过具体示例应用程序说明了 Compose 构建规范概念。该样本是非标准的。

services:
  frontend:
    image: example/webapp
    build: ./webapp

  backend:
    image: example/database
    build:
      context: backend
      dockerfile: ../backend.Dockerfile

  custom:
    build: ~/custom

当用于从源构建服务映像时，Compose 文件会创建三个 Docker 映像：

  • example/webapp：Docker 映像是使用webappCompose 文件的父文件夹中的子目录构建的，作为 Docker 构建上下文。此文件夹中缺少 aDockerfile会引发错误。
  • example/database：Docker 映像是使用backendCompose 文件父文件夹中的子目录构建的。backend.Dockerfilefile 用于定义构建步骤，相对于上下文路径搜索该文件，这意味着..解析到 Compose 文件的父文件夹，因此backend.Dockerfile也是同级文件。
  • Docker 镜像是使用custom以用户 HOME 为 Docker 上下文的目录构建的。 Compose 显示有关用于构建映像的不可移植路径的警告。

推送时， Dockerexample/webapp镜像example/database都会推送到默认注册表。custom由于未设置任何属性，因此会跳过服务映像，image并且 Compose 会显示有关此缺失属性的警告。

属性

本build小节定义了 Compose 用于从源构建 Docker 映像的配置选项。 build可以指定为包含构建上下文路径的字符串或详细结构：

使用字符串语法，只有构建上下文可以配置为：

  • Compose 文件的父文件夹的相对路径。该路径必须是一个目录并且必须包含Dockerfile

    services:
  webapp:
    build: ./dir

  • git 存储库 URL。 Git URL 在其片段部分接受上下文配置，以冒号 ( :) 分隔。第一部分表示 Git 签出的引用，可以是分支、标签或远程引用。第二部分表示存储库内用作构建上下文的子目录。

    services:
  webapp:
    build: https://github.com/mycompany/example.git#branch_or_tag:subdirectory

或者build可以是具有如下定义字段的对象：

语境

context定义包含 Dockerfile 的目录的路径，或 git 存储库的 URL。

当提供的值是相对路径时，它将被解释为相对于 Compose 文件的位置。 Compose 会警告您有关用于定义构建上下文的绝对路径，因为这些路径会阻止 Compose 文件的可移植性。

build:
  context: ./dir
services:
  webapp:
    build: https://github.com/mycompany/webapp.git

如果未明确设置，context则默认为项目目录 ( .)。

docker文件

dockerfile设置备用 Dockerfile。相对路径是从构建上下文解析的。 Compose 会警告您有关用于定义 Dockerfile 的绝对路径，因为它会阻止 Compose 文件的可移植性。

设置后，dockerfile_inline不允许使用属性，并且 Compose 会拒绝任何同时设置了这两种属性的 Compose 文件。

build:
  context: .
  dockerfile: webapp.Dockerfile

dockerfile_内联

Docker Compose 2.17.0版本中引入

dockerfile_inline将 Dockerfile 内容定义为 Compose 文件中的内联字符串。设置后，dockerfile 不允许使用该属性，并且 Compose 会拒绝任何同时设置了这两个属性的 Compose 文件。

建议使用 YAML 多行字符串语法来定义 Dockerfile 内容：

build:
  context: .
  dockerfile_inline: |
    FROM baseimage
    RUN some command

参数

args定义构建参数，即 DockerfileARG值。

使用以下 Dockerfile 作为示例：

ARG GIT_COMMIT
RUN echo "Based on commit: $GIT_COMMIT"

args可以在Compose文件下设置build键来定义GIT_COMMIT。args可以设置为映射或列表：

build:
  context: .
  args:
    GIT_COMMIT: cdc3b19
build:
  context: .
  args:
    - GIT_COMMIT=cdc3b19

指定构建参数时可以省略值，在这种情况下，构建时的值必须通过用户交互获取，否则在构建 Docker 映像时将不会设置构建参数。

args:
  - GIT_COMMIT

SSH

ssh定义镜像构建器在镜像构建期间应使用的 SSH 身份验证（例如，克隆私有存储库）。

ssh属性语法可以是：

  • default：让构建器连接到 ssh-agent。
  • ID=path：ID 和关联路径的键/值定义。它可以是 PEM文件，也可以是 ssh-agent 套接字的路径。
build:
  context: .
  ssh:
    - default   # mount the default ssh agent

或者

build:
  context: .
  ssh: ["default"]   # mount the default ssh agent

myproject使用带有本地 SSH 密钥路径的自定义 ID ：

build:
  context: .
  ssh:
    - myproject=~/.ssh/myproject.pem

然后，映像构建器可以依靠它在构建过程中挂载 SSH 密钥。例如， BuildKit 扩展语法可用于安装按 ID 设置的 SSH 密钥并访问受保护的资源：

RUN --mount=type=ssh,id=myproject git clone ...

缓存来源

cache_from定义图像生成器应用于缓存解析的源列表。

缓存位置语法遵循全局格式[NAME|type=TYPE[,KEY=VALUE]]。 SimpleNAME实际上是 的快捷表示法type=registry,ref=NAME。

Compose Build 实现可能支持自定义类型，Compose 规范定义了必须支持的规范类型：

  • registry从按键设置的 OCI 映像中检索构建缓存ref
build:
  context: .
  cache_from:
    - alpine:latest
    - type=local,src=path/to/cache
    - type=gha

不支持的缓存将被忽略，并且不会阻止您构建图像。

缓存到

cache_to定义用于与未来构建共享构建缓存的导出位置列表。

build:
  context: .
  cache_to:
   - user/app:cache
   - type=local,dest=path/to/cache

缓存目标是使用type=TYPE[,KEY=VALUE]与 cache_from.

不支持的缓存将被忽略，并且不会阻止您构建图像。

附加上下文

Docker Compose 2.17.0版本中引入

additional_contexts定义映像生成器在映像生成期间应使用的命名上下文列表。

additional_contexts可以是映射或列表：

build:
  context: .
  additional_contexts:
    - resources=/path/to/resources
    - app=docker-image://my-app:latest
    - source=https://github.com/myuser/project.git
build:
  context: .
  additional_contexts:
    resources: /path/to/resources
    app: docker-image://my-app:latest
    source: https://github.com/myuser/project.git

当用作列表时，语法遵循NAME=VALUE格式，其中VALUE是字符串。除此之外的验证是镜像构建者的责任（并且是特定于构建者的）。 Compose 至少支持目录的绝对路径和相对路径以及 Git 存储库 URL，就像 上下文一样。其他上下文风格必须添加前缀以避免前缀引起歧义type://。

如果映像生成器不支持其他上下文，Compose 会向您发出警告，并且可能会列出未使用的上下文。

可以在此处找到有关如何在 Buildx 中使用此功能的说明性示例 。

额外主机

extra_hosts在构建时添加主机名映射。使用与extra_hosts相同的语法 。

extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"

IPv6 地址可以用方括号括起来，例如：

extra_hosts:
  - "myhostv6=[::1]"

隔板=是优选的，但:也可以使用。在 Docker Compose 版本 2.24.1中引入。例如：

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

Compose 在容器的网络配置中创建与 IP 地址和主机名匹配的条目，这意味着对于 Linux/etc/hosts将获得额外的行：

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

隔离

isolation指定构建的容器隔离技术。与隔离一样 ，支持的值是特定于平台的。

特权

Docker Compose 2.15.0版本中引入

privileged配置服务映像以使用提升的权限进行构建。支持和实际影响因平台而异。

build:
  context: .
  privileged: true

标签

labels将元数据添加到结果图像中。labels可以设置为数组或映射。

建议您使用反向 DNS 表示法，以防止您的标签与其他软件发生冲突。

build:
  context: .
  labels:
    com.example.description: "Accounting webapp"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""
build:
  context: .
  labels:
    - "com.example.description=Accounting webapp"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"

无缓存

no_cache禁用图像生成器缓存并强制从所有图像层的源完全重建。这仅适用于 Dockerfile 中声明的层，只要在注册表上更新标签（请参阅 pull），就可以从本地映像存储中检索引用的映像。

拉

pull要求镜像生成器拉取引用的镜像（FROMDockerfile 指令），即使这些镜像已经在本地镜像存储中可用。

网络

设置网络容器连接以获取RUN构建期间的说明。

build:
  context: .
  network: host
build:
  context: .
  network: custom_network_1

用于none在构建期间禁用网络：

build:
  context: .
  network: none

shm_大小

shm_size/dev/shm设置为构建 Docker 映像分配的共享内存（Linux 上的分区）的大小。指定为表示字节数的整数值或表示 字节值的字符串。

build:
  context: .
  shm_size: '2gb'
build:
  context: .
  shm_size: 10000000

目标

target定义要构建的阶段，如多阶段中定义的那样Dockerfile。

build:
  context: .
  target: prod

秘密

secrets授予对每个服务构建基础上秘密定义的敏感数据的访问权限 。支持两种不同的语法变体：短语法和长语法。

secrets如果此 Compose 文件的部分中未定义密钥，Compose 会报告错误 。

简短语法

短语法变体仅指定秘密名称。这将授予容器对机密的访问权限，并将其以只读方式安装到/run/secrets/<secret_name> 容器内。源名称和目标安装点均设置为秘密名称。

以下示例使用短语法来授予服务构建frontend对server-certificate密钥的访问权限。的值server-certificate设置为文件的内容./server.cert。

services:
  frontend:
    build:
      context: .
      secrets:
        - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

长语法

长语法提供了如何在服务容器内创建机密的更细粒度。

  • source：平台上存在的机密名称。
  • target/run/secrets/：要挂载到服务任务容器中的文件的名称。source如果未指定则默认为。
  • uid和：拥有服务任务容器中gid的文件的数字 UID 或 GID 。/run/secrets/默认值是运行容器的用户。
  • mode： 要 在服务的任务容器中安装的文件的权限/run/secrets/，以八进制表示法。默认值是世界可读的权限（mode 0444）。如果设置了可写位，则必须忽略该位。可以设置可执行位。

以下示例将机密文件的名称设置server-certificate为server.crt 在容器内，将模式设置为0440（组可读）并将用户和组设置为103。 Secret的值server-certificate由平台通过查找提供，并且 Secret 生命周期不由 Compose 直接管理。

services:
  frontend:
    build:
      context: .
      secrets:
        - source: server-certificate
          target: server.cert
          uid: "103"
          gid: "103"
          mode: 0440
secrets:
  server-certificate:
    external: true

服务构建可以被授予对多个秘密的访问权限。秘密的长语法和短语法可以在同一个 Compose 文件中使用。在顶层定义机密secrets并不意味着授予任何服务构建对其的访问权限。此类授权必须在服务规范中明确作为 秘密服务元素。

标签

tags定义必须与构建映像关联的标签映射列表。此列表是对服务部分中定义的属性的补充image 

tags:
  - "myimage:mytag"
  - "registry/username/myrepos:my-other-tag"

极限值

Docker Compose 2.23.1版本中引入

ulimits覆盖容器的默认 ulimit。它被指定为单个限制的整数或软/硬限制的映射。

services:
  frontend:
    build:
      context: .
      ulimits:
        nproc: 65535
        nofile:
          soft: 20000
          hard: 40000

平台

platforms定义目标平台列表 。

build:
  context: "."
  platforms:
    - "linux/amd64"
    - "linux/arm64"

当省略该platforms属性时，Compose 会将服务的平台包含在默认构建目标平台的列表中。

定义该platforms属性后，Compose 会包含该服务的平台，否则用户将无法运行他们构建的映像。

Compose 在以下情况下报告错误：

  • 当列表包含多个平台但实现无法存储多平台图像时。

  • 当列表包含不受支持的平台时。

    build:
  context: "."
  platforms:
    - "linux/amd64"
    - "unsupported/unsupported"

  • 当列表非空且不包含服务平台时

    services:
  frontend:
    platform: "linux/amd64"
    build:
      context: "."
      platforms:
        - "linux/arm64"