Compose 构建规范

目录

构建是Compose规范的一个可选部分。它告诉Compose如何从源代码（重新）构建应用程序，并允许您以便携的方式在Compose文件中定义构建过程。build可以指定为定义上下文路径的单个字符串，也可以指定为详细的构建定义。

在前一种情况下，整个路径被用作Docker上下文来执行Docker构建，寻找目录根部的标准Dockerfile。路径可以是绝对路径或相对路径。如果是相对路径，则从包含Compose文件的目录解析。如果是绝对路径，路径会阻止Compose文件的可移植性，因此Compose会显示警告。

在后一种情况下，可以指定构建参数，包括一个替代的 Dockerfile 位置。路径可以是绝对路径或相对路径。如果是相对路径，它是从包含你的 Compose 文件的目录解析的。如果是绝对路径，路径会导致 Compose 文件不可移植，因此 Compose 会显示一个警告。

使用 build 和 image

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

如果服务定义中缺少pull_policy，Compose 会尝试先拉取镜像，如果在注册表或平台缓存中找不到镜像，则从源代码构建。

发布构建的镜像

使用build支持的Compose提供了一个选项，可以将构建的镜像推送到注册表。在这样做时，它不会尝试推送没有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: 使用Compose文件父文件夹中的webapp子目录作为Docker构建上下文构建Docker镜像。如果此文件夹中缺少Dockerfile，则会抛出错误。
  • example/database: 使用Compose文件父文件夹中的backend子目录构建Docker镜像。backend.Dockerfile文件用于定义构建步骤，该文件相对于上下文路径进行搜索，这意味着..解析为Compose文件的父文件夹，因此backend.Dockerfile是一个同级文件。
  • 使用custom目录构建Docker镜像，用户的HOME作为Docker上下文。Compose会显示关于用于构建镜像的非可移植路径的警告。

在推送时，example/webapp 和 example/database Docker 镜像会被推送到默认的注册表。由于没有设置 image 属性，custom 服务镜像被跳过，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 可以是一个对象，其字段定义如下：

additional_contexts

Introduced in Docker Compose version 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，就像context所做的那样。其他上下文类型必须加上前缀以避免与type://前缀产生歧义。

如果镜像构建器不支持额外的上下文，Compose 会警告你，并可能列出未使用的上下文。

在Buildx中如何使用此功能的示例可以在这里找到。

args

args 定义了构建参数，即 Dockerfile 中的 ARG 值。

使用以下 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

context

context 定义了包含 Dockerfile 的目录路径，或者是一个 git 仓库的 URL。

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

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

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

cache_from

cache_from 定义了镜像构建器用于缓存解析的源列表。

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

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

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

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

cache_to

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

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

缓存目标使用与cache_from相同的type=TYPE[,KEY=VALUE]语法定义。

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

dockerfile

dockerfile 设置一个替代的 Dockerfile。相对路径是从构建上下文中解析的。 Compose 会警告你使用绝对路径定义 Dockerfile，因为它阻止了 Compose 文件的 可移植性。

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

build:
  context: .
  dockerfile: webapp.Dockerfile

dockerfile_inline

Introduced in Docker Compose version 2.17.0

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

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

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

entitlements

Introduced in Docker Compose version 2.27.1

entitlements 定义了在构建过程中允许的额外特权。

entitlements:
  - network.host
  - security.insecure

extra_hosts

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

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

标签

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"

network

设置网络容器在构建期间为RUN指令连接的网络。

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

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

build:
  context: .
  network: none

no_cache

no_cache 禁用镜像构建器缓存，并强制从源代码完全重建所有镜像层。这仅适用于在 Dockerfile 中声明的层，引用的镜像可以在标签在注册表上更新时从本地镜像存储中检索（参见 pull）。

平台

platforms 定义了一个目标 platforms 的列表。

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

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

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

在以下情况下，Composes 报告错误：

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

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

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

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

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

privileged

Introduced in Docker Compose version 2.15.0

privileged 配置服务镜像以提升权限构建。支持和实际影响因平台而异。

build:
  context: .
  privileged: true

pull

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

secrets

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

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

简短语法

简写语法变体仅指定密钥名称。这将授予容器对密钥的访问权限，并将其作为只读挂载到容器内的/run/secrets/。源名称和目标挂载点都设置为密钥名称。

以下示例使用简写语法授予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: 在服务的任务容器中拥有 /run/secrets/ 目录下文件的数字 UID 或 GID。默认值为运行容器的 USER。
  • mode: 文件在服务任务容器中挂载到/run/secrets/的权限，以八进制表示。 默认值为全局可读权限（模式0444）。 如果设置了可写位，则必须忽略。可执行位可以设置。

以下示例将容器内的server-certificate密钥文件名称设置为server.crt，将模式设置为0440（组可读），并将用户和组设置为103。server-certificate密钥的值由平台通过查找提供，密钥的生命周期不由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中定义机密并不意味着授予任何服务构建访问权限。此类授权必须在服务规范中明确指定，如secrets服务元素。

ssh

ssh 定义了镜像构建器在构建镜像时应使用的SSH认证（例如，克隆私有仓库）。

ssh 属性的语法可以是以下之一：

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

或

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

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

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

然后，镜像构建器可以依赖此功能在构建过程中挂载SSH密钥。

为了说明， SSH挂载 可以用来挂载由ID设置的SSH密钥并访问受保护的资源：

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

shm_size

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

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

标签

tags 定义了一个必须与构建镜像关联的标签映射列表。这个列表是除了 image 之外的 服务部分中定义的属性

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

目标

target 定义了在多阶段 Dockerfile 中定义的构建阶段。

build:
  context: .
  target: prod

ulimits

Introduced in Docker Compose version 2.23.1

ulimits 覆盖容器的默认 ulimits。它可以指定为单个限制的整数，或者作为软/硬限制的映射。

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