Compose ファイル構築リファレンス

Compose 仕様とは、複数のコンテナアプリケーションを定義するための、プラットフォームに中立な手法です。Compose の実装で焦点をあてているのは、ローカルマシン上でアプリケーションを実行する開発の利用例であり、ソースからアプリケーションを構築（および再構築）も明確にサポートしています。 Compose :ruby:`構築仕様 <Build specification>` により、Compose ファイル内の構築手順をポータブルな方法として定義できます。

定義

Compose Specification （仕様）は、サービス上で build （構築）サブセクションをオプションでサポートするように拡張されました。このセクションで定義するのは、サービス コンテナ イメージの :ruby:`構築 <build>` 要件を定義します。Compose ファイルの services サブセットのみ、 build サブセクションや image 属性をもとに作成されるその他を定義できます。サービスに build サブセクションがある場合、Compose 実装はソースからイメージを構築できるため、 Compose ファイルで対応するサービスの image 属性を見落とす処理も「 :ruby:`有効 <valid>` 」です。

構築の指定は、単一文字列でコンテクストのパスを指定するか、詳細な構築を定義するかのどちらかです。

前者の場合、パス全体を Docker コンテクストとして使用しますので、このコンテクストのルートで正しい Dockerfile を探し、docker build を実行します。コンテクストのパスは、絶対パスか相対パスです。なお、相対パスは Compose ファイルの親フォルダを基準にする必要があります。 Compose ファイルを持ち運びできるようにするには、絶対パスは避けるべきであり、 Compose 実装はユーザに対して :ruby:`警告すべきです <SHOULD>` 。

後者の場合、代替する Dockerfile の場所指定を含む、構築に対する引数を指定できます。これは、絶対パスも相対パスも利用できます。Dockerfile が相対パスの場合は、コンテキストのパスを基準にする :ruby:`必要があります <MUST>` 。 Compose ファイルを持ち運びできるようにするには、絶対パスは避けるべきであり、Dockerfile の代替パスに絶対パスが使われる場合、 Compose 実装はユーザに対して :ruby:`警告すべきです <SHOULD>` 。

イメージの一貫性

サービス定義に image 属性と build セクションの両方がある場合、取得したイメージがソースから構築したイメージと厳密に同じかどうかを、 Compose 実装では保証できません。ユーザから何らかの指示が明示されない限り、 Compose 実装は第一にイメージの取得を試し、レジストリ内にイメージがみつからない場合は、イメージをソースから構築します。Compose 実装はユーザからの要求によって、この挙動をカスタマイズするオプションを提供しても :ruby:構いません <MAY>` 。

構築イメージの公開

構築をサポートする Compose 実装は、構築したイメージのレジストリ :ruby:`送信 <push>`をオプションで :ruby:`サポートすべきです <SHOULD>` 。 image 属性を持たないイメージの送信を防ぐため、 Compose 実装はユーザに :ruby:`警告すべきです <SHOULD>` 。

YAML ファイル内でサービスに対する image 属性が明示的に宣言されていない場合、Compose 実装はサービスの image 属性を生成する仕組みを提供しても :ruby:`構いません <MAY>` 。このような挙動をする場合、 image 属性を持たないサービス イメージの送信を :ruby:`試みてはいけません <MUST NOT>` 。実際の生の YAML ファイルがイメージ属性を明示していなくても、Compose 実装は有効な image 属性を持っていると見なします。

説明例

以下の静的なサンプル アプリケーション例を通し、 Compose 仕様の概念を説明します。このサンプルは実用的ではありません。

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

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

  custom:
    build: ~/custom

ソースからサービス イメージを構築する時、このような Compose ファイルによって3つの Docker イメージが作成されます。

  • awesome/webapp docker イメージは、 Compose ファイルがある親フォルダ内の webapp サブディレクトリを、 docker 構築コンテクストとして使用します。このフォルダ内に Dockerfile が無い場合は、エラーを起こします。

  • awesome/database docker イメージは、 Compose ファイルがある親フォルダ内の webapp サブディレクトリを、 docker 構築コンテクストとして使用します。構築手順を定義するにあたり、 backend.Dockerfile ファイルを使います。このファイルはコンテクストパスに関連して検索されますので、つまり、このサンプルでは .. が Compose ファイルの親フォルダとして基準となります（解決されます）ので、 backend.Dockerfile は兄弟のようなファイルと言えます。

  • custom ディレクトリで、ユーザの HOME （ホームディレクトリ）内を docker コンテクストとして使い、 Docker イメージを構築します。ポータブルではないパスが構築イメージで使われた場合、Compose 実装はユーザに警告します。

:ruby:`送信 <push>` すると、 awesome/webapp と awesome/database の両 Docker イメージが（デフォルトの）レジストリに :ruby:`送信 <push>` されます。 custom サービスイメージは image 属性を持たないためスキップされ、ユーザには、この属性が無いと警告します。

build 定義

build 要素は、 Docker イメージをソースから構築するために、 Compose 実装によって適用される設定情報のオプションを定義します。 build は、構築コンテクストへのパスを含む文字列か、詳細な構造のどちらかで指定します。

services:
  webapp:
    build: ./dir

この文字列の構文を使うと、 Compose ファイルの親フォルダからの相対パスとしてのみ、構築コンテキストを設定できます。このパスはディレクトリであり、かつ、 Dockerfile を含む必要があります。

あるいは、 build は以下のように定義されたフィールドを持つオブジェクトにもできます。

context（必須）

context は Dockerfile を含むディレクトリのパスか、 git リポジトリの url を定義します。

値が相対パスとして指定される場合、 Compose ファイルの場所からの相対パスと解釈する :ruby:`必要があります <MUST>` 。Compose ファイルがポータブルにならないのを防ぐため、構築コンテキストの定義で絶対パスが使われる場合、Compose 実装はユーザに対して警告が :ruby:`必要です <MUST>` 。

build:
  context: ./dir

dockerfile

dockerfile は別の Dockerfile を指定できるようにします。相対パスは構築コンテキストを基準とする :ruby:`必要があります <MUST>` 。Compose ファイルがポータブルにならないのを防ぐため、 Dockerfile の定義で絶対パスが使われる場合、 Compose 実装はユーザに警告を出す :ruby:`必要があります <MUST>` 。

build:
  context: .
  dockerfile: webapp.Dockerfile

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

build の引数（args）の指定時に、値を省略できます。その場合、ユーザの操作によって構築時に値の指定が :ruby:`必要です <MUST>` 。そうしなければ、 Docker イメージの構築時に引数が設定されません。

args:
  - GIT_COMMIT

ssh

ssh は、イメージ構築中にイメージビルダが :ruby:`使うべき <SHOULD>` SSH 認証を定義します（例：プライベート リポジトリのクローン時）。

ssh 属性の構文は、以下どちらかです。

  • default`` ：ビルダを ssh-agent に接続します。

  • ID=path ：ID と関連するパスをキーバリューで定義します。 PEM ファイルや、 ssh-agent ソケットのパスを指定できます。

シンプルな default 例：

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 鍵をマウントできます。具体例として、 BuildKit 拡張構文によって、 ID として設定された SSH 鍵をマウントすると、リソースへ安全なアクセスできます：

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

cache_from

cache_from は、イメージビルダがキャッシュの解決に :ruby:`使うべき <SHOULD>` ソースのリストを定義します。

キャッシュ場所の構文は、以下のグローバル形式 [NAME|type=TYPE[,KEY=VALUE]] に従う必要があります。シンプルな NAME は、実際には type=registry,ref=NAME と書く形式の省略形です。

Compose ビルダの実装は任意のタイプをサポートしても :ruby:`構いません <MAY>` 。Compose 仕様ではサポートしなければ :ruby:`ならない <MUST>` 正式な型を定義しています。

  • registry は、キー ref によって設定された OCI イメージから構築キャッシュを取得します。

build:
  context: .
  cache_from:
    - alpine:latest
    - type=local,src=path/to/cache
    - type=gha

サポートされていないキャッシュは無視が :ruby:`必要で <MUST>` 、ユーザによるイメージ構築を妨げてはいけません。

cache_to

cache_to は、以後の構築時に構築キャッシュとして共有するために使えるよう、エクスポートする場所のリストを定義します。

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

:ruby:`キャッシュ対象 <cache target>` は cache_from で定義された同じ type=TYPE[,KEY=VALUE] 構文を使って定義できます。

サポートされていないキャッシュ対象は無視が :ruby:`必要で <MUST>` 、ユーザによるイメージ構築を妨げてはいけません。

extra_hosts

extra_hosts は構築時に追加のホスト名を割り当てます。 extra_hosts と同じ構文です。

extra_hosts:
  - "somehost:162.242.195.82"
  - "otherhost:50.31.209.229"

Compose 実装は、コンテナのネットワーク設定内に、 IP アドレスとホスト名の一致するエントリを作成する :ruby:`必要があります <MUST>` 。つまり Linux の /etc/hosts に行を追加します。

 162.242.195.82  somehost
50.31.209.229   otherhost

isolation

isolation は構築時のコンテナ分離技術を指定します。 isolation のように、サポートしている値はプラットフォーム固有です。

labels

labels は構築成果のイメージにメタデータを追加します。 labels はアレイ形式かマップ形式のどちらかです。

他のソフトウェアが使うラベルとの重複を避けるため、逆引き DNS 記法を :ruby:`使うべきです <SHOULD>` 。

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"

shm_size

shm_size は、Docker イメージ構築時に割り当てる共有メモリの容量（ Linux 上の /dev/shm パーティション ）を設定します。設定はバイトを整数値で指定するか、 バイト値 の文字列で表現します。

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

target

target は、マルチステージ Dockerfile 内で定義されている :ruby:`構築ステージ <build stage>` を定義します。

build:
  context: .
  target: prod

実装

参考

Compose file build reference

https://docs.docker.com/compose/compose-file/build/