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

目次

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

定義

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

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

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

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

イメージの一貫性

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

構築イメージの公開

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

YAML ファイル内でサービスに対する image 属性が明示的に宣言されていない場合、Compose 実装はサービスの image 属性を生成する仕組みを提供しても 構いません(MAY) 。このような挙動をする場合、 image 属性を持たないサービス イメージの送信を 試みてはいけません(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 実装はユーザに警告します。

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

build 定義

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

services:
  webapp:
    build: ./dir

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

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

context（必須）

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

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

build:
  context: ./dir

dockerfile

dockerfile は別の Dockerfile を指定できるようにします。相対パスは構築コンテキストを基準とする 必要があります(MUST) 。Compose ファイルがポータブルにならないのを防ぐため、 Dockerfile の定義で絶対パスが使われる場合、 Compose 実装はユーザに警告を出す 必要があります(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）の指定時に、値を省略できます。その場合、ユーザの操作によって構築時に値の指定が 必要です(MUST) 。そうしなければ、 Docker イメージの構築時に引数が設定されません。

args:
  - GIT_COMMIT

ssh

ssh は、イメージ構築中にイメージビルダが 使うべき(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 は、イメージビルダがキャッシュの解決に 使うべき(SHOULD) ソースのリストを定義します。

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

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

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

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

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

cache_to

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

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

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

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

extra_hosts

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

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

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

 162.242.195.82  somehost
50.31.209.229   otherhost

isolation

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

labels

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

他のソフトウェアが使うラベルとの重複を避けるため、逆引き DNS 記法を 使うべきです(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 内で定義されている 構築ステージ(build stage) を定義します。

build:
  context: .
  target: prod

実装

• Docker Compose

• buildX bake

参考

Compose file build reference

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