Compose 構建規範

目錄

Build 是 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：Docker 映象使用 Compose 檔案資料夾內的 webapp 子目錄作為 Docker 構建上下文進行構建。此資料夾中缺少 Dockerfile 會返回錯誤。
  • example/database：Docker 映象使用 Compose 檔案資料夾內的 backend 子目錄進行構建。backend.Dockerfile 檔案用於定義構建步驟，此檔案相對於上下文路徑進行搜尋，這意味著 .. 解析為 Compose 檔案資料夾，因此 backend.Dockerfile 是一個同級檔案。
  • Docker 映象使用使用者 $HOME 中的 custom 目錄作為 Docker 上下文進行構建。Compose 會顯示有關用於構建映象的不可移植路徑的警告。

推送時，example/webapp 和 example/database Docker 映象都會推送到預設登錄檔。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 可以是具有以下定義的欄位的物件

additional_contexts

要求： 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，就像 context 一樣。其他上下文型別必須加上字首以避免與 type:// 字首產生歧義。

如果映象構建器不支援額外的上下文，Compose 會發出警告，並可能列出未使用的上下文。

有關 Buildx 中如何使用此功能的說明性示例，請參閱此處。

additional_contexts 還可以引用由另一個服務構建的映象。這允許使用另一個服務映象作為基礎映象來構建服務映象，並在服務映象之間共享層。

services:
 base:
  build:
    context: .
    dockerfile_inline: |
      FROM alpine
      RUN ...
 my-service:
  build:
    context: .
    dockerfile_inline: |
      FROM base # image built for service base
      RUN ...
    additional_contexts:
      base: service:base

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

cache_from

cache_from 定義了映象構建器應用於快取解析的源列表。

快取位置語法遵循全域性格式 [NAME|type=TYPE[,KEY=VALUE]]。簡單的 NAME 實際上是 type=registry,ref=NAME 的快捷方式。

Compose 構建實現可能支援自定義型別，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] 語法進行定義。

不支援的快取會被忽略，不會阻止你構建映象。

context

context 定義了包含 Dockerfile 的目錄路徑，或 Git 儲存庫的 URL。

當提供的值是相對路徑時，它被解釋為相對於專案目錄。Compose 會警告你用於定義構建上下文的絕對路徑，因為這些路徑會阻止 Compose 檔案的可移植性。

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

如果未明確設定，context 預設為專案目錄 (.)。

dockerfile

dockerfile 設定備用 Dockerfile。相對路徑從構建上下文解析。Compose 會警告你用於定義 Dockerfile 的絕對路徑，因為它會阻止 Compose 檔案的可移植性。

設定後，不允許使用 dockerfile_inline 屬性，並且 Compose 會拒絕任何同時設定這兩個屬性的 Compose 檔案。

build:
  context: .
  dockerfile: webapp.Dockerfile

dockerfile_inline

要求： Docker Compose 2.17.0 及更高版本

dockerfile_inline 將 Dockerfile 內容定義為 Compose 檔案中的內聯字串。設定後，不允許使用 dockerfile 屬性，並且 Compose 會拒絕任何同時設定這兩個屬性的 Compose 檔案。

建議使用 YAML 多行字串語法來定義 Dockerfile 內容。

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

entitlements

要求： Docker Compose 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 將元資料新增到生成的映象。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"

網路

設定在構建期間 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 會包含服務的平臺，否則使用者將無法執行他們構建的映象。

在以下情況下，Compose 會報告錯誤

  • 當列表中包含多個平臺，但實現無法儲存多平臺映象時。

  • 當列表中包含不支援的平臺時。

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

  • 當列表非空且不包含服務的平臺時。

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

privileged

要求： Docker Compose 2.15.0 及更高版本

privileged 配置服務映象以提升許可權進行構建。支援和實際影響是平臺特定的。

build:
  context: .
  privileged: true

provenance

要求： Docker Compose 2.39.0 及更高版本

provenance 配置構建器將 來源證明 新增到已釋出的映象中。

該值可以是布林值以啟用/停用來源證明，也可以是 key=value 字串以設定來源配置。你可以透過設定 mode 引數來選擇要包含在來源證明中的詳細程度。

build:
  context: .
  provenance: true
build:
  context: .
  provenance: mode=max

pull

pull 要求映象構建器拉取引用的映象（FROM Dockerfile 指令），即使這些映象已在本地映象儲存中可用。

sbom

要求： Docker Compose 2.39.0 及更高版本

sbom 配置構建器將 來源證明 新增到已釋出的映象中。該值可以是布林值以啟用/停用 SBOM 證明，也可以是 key=value 字串以設定 SBOM 生成器配置。這允許你選擇備用的 SBOM 生成器映象（請參閱 https://github.com/moby/buildkit/blob/master/docs/attestations/sbom-protocol.md）。

build:
  context: .
  sbom: true
build:
  context: .
  sbom: generator=docker/scout-sbom-indexer:latest # Use an alternative SBOM generator

secrets

secrets 授予對按服務構建定義的 secrets 敏感資料的訪問許可權。支援兩種不同的語法變體：短語法和長語法。

如果秘密未在此 Compose 檔案的 secrets 部分中定義，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：Dockerfile 中宣告的秘密 ID。如果未指定，則預設為 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: cert # secret ID in Dockerfile
          uid: "103"
          gid: "103"
          mode: 0440
secrets:
  server-certificate:
    external: true
# Dockerfile
FROM nginx
RUN --mount=type=secret,id=cert,required=true,target=/root/cert ...

服務構建可以獲得對多個秘密的訪問許可權。秘密的長語法和短語法可以在同一個 Compose 檔案中使用。在頂級 secrets 中定義秘密不應意味著授予任何服務構建訪問該秘密的許可權。此類授予必須在服務規範中明確宣告為 secrets 服務元素。

ssh

ssh 定義了映象構建器在映象構建過程中應使用的 SSH 認證（例如，克隆私有儲存庫）。

ssh 屬性語法可以是以下之一

  • default：讓構建器連線到 SSH 代理。
  • ID=path：ID 及其關聯路徑的鍵/值定義。它可以是 PEM 檔案，也可以是 SSH 代理套接字的路徑。
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

tags 定義了必須與構建映象關聯的標籤對映列表。此列表是服務部分中定義的 image 屬性的補充。

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

target

target 定義了在多階段 Dockerfile 中定義的要構建的階段。

build:
  context: .
  target: prod

ulimits

要求： Docker Compose 2.23.1 及更高版本

ulimits 覆蓋容器的預設 ulimits。它指定為單個限制的整數或軟/硬限制的對映。

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