Compose ファイルのバージョンとアップグレード¶

Compose ファイルはとは、Docker アプリケーションのサービス(service) 、ネットワーク(network) 、ボリューム(volume) を定義する YAML ファイルです。

これらのリファレンスは、各バージョンに対応する Compose ファイル形式を説明します。

リファレンス・ファイル	対象バージョンの変更点
Compose 仕様（最新かつ推奨）	バージョン情報
バージョン 3	バージョン 3 更新情報
バージョン 2	バージョン 2 更新情報
バージョン 1 （非推奨）	バージョン 1 更新情報

以下のトピックで説明するのは、バージョン間の違い、Docker Engine 互換性、アップグレードの仕方です。

互換表 ¶

Compose ファイル形式には、1 、 2 、 2.x 、 3.x のように複数のバージョンがあります。

この表は、各 Compose ファイル形式を、どの Docker リリースでサポートしているかを表します。

Compose ファイル形式	Docker Engine リリース
Compose 仕様	19.03.0+
3.8	19.03.0+
3.7	18.06.0+
3.6	18.02.0+
3.5	17.12.0+
3.4	17.09.0+
3.3	17.06.0+
3.2	17.04.0+
3.1	1.13.1+
3.0	1.13.0+
2.4	17.12.0+
2.3	17.06.0+
2.2	1.13.0+
2.1	1.12.0+
2.0	1.10.0+

先ほどの表中にある Compose ファイル形式のバージョンに加え、Compose 自身も Compose リリースのページにリリース情報の一覧があります。しかし、ファイル形式のバージョンは、各リリースごとに増えていません。たとえば、Compose ファイル形式 3.0 が始めて導入されたのは、 Compose リリース 1.10.0 からであり、以降はリリースに従って順々とバージョンが割り当てられています。

最新の Compose ファイル形式は `Compose 仕様`_ で定義されており、 Docker Compose 1.27.0 以上 から実装されています。

注釈

Docker と Compose の互換性について、詳細を探していますか？

可能な限り、最新版に更新し続けるのを推奨します。しかしながら、Docker の古いバージョンを使っている場合や、Compose リリースに互換性があるかどうか判断する場合は、 Compose リリースノートを参照ください。リリースノートごとに、サポートしている Docker Engine のバージョン加え、互換性のある Compose ファイル形式のバージョンの詳細があります。（ issue #3404 の議論もご覧ください。）

バージョンについての詳細やアップグレードの仕方については、 <compose-file-versioning> と <compose-file-upgrading> をご覧ください。

バージョン仕様 ¶

Compose ファイル形式には、過去3つのバージョンがあります。

バージョン 1。これを指定するには、 YAML のルート（先頭）で version キーを省略します。
バージョン 2.x。これを指定するには、 YAML のルートで version: '2' や version: '2.1' のように入力します。
バージョン 3.x は、Compose と Docker Engine の swarm モード間で、互換性を持つように設計されました。これを指定するには、 YAML のルートで version: '3' や version: '3.1' のように入力します。

最新かつ推奨される Compose ファイル形式は、 `Compose 仕様`_ で定義されたものです。この形式はバージョン 2.x と 3.x を統合したもので、 Compose 1.27.0 以上 で実装されています。

v2 と v3 の宣言 ¶

メモ： Compose ファイルのバージョン指定時は、メジャー番号とマイナー番号の両方を指定してください。マイナーバージョンの指定が無ければ、最新のマイナーバージョンではなく、デフォルトの 0 が使われます。

互換表から、どの Compose ファイル形式が Docker Engine のリリースに対応しているか分かります。

プロジェクトを最新版に移行するには、アップグレード方法をご覧ください。

注釈

メモ：複数の Compose ファイルや :ref:`サービス拡張 <extending-services> を使う場合は、各ファイルのバージョンを同じにする必要があります。たとえば、1つのプロジェクト内でバージョン 1 と 2 は混在できません。

どのバージョンを使うかにより、複数の点が異なります。

構造と利用可能な設定キー
実行に必要な Docker Engine の最低バージョン
ネットワーク機能に関する Compose の挙動

これらの違いを、以下で説明します。

バージョン１（非推奨）¶

Compose ファイルでバージョンを宣言しなければ「バージョン１」とみなされます。バージョン１では、ドキュメントの冒頭から全てのサービスを定義します。

バージョン１は Compose 1.6.x まで サポートされました。今後の Compose バージョンでは非推奨(deprecated) です。

バージョン1のファイルでは volumes 、 networks 、 build 引数を使えません。

バージョン1を使うと、Compose はネットワーク機能を全く活用できません。これは、全てのコンテナがデフォルトの bridge ネットワークに置かれ、他すべてのコンテナと相互に IP アドレスで到達可能だからです。コンテナ間で接続先を見つけるには、 links を使う必要があります。

例：

web:
  build: .
  ports:
   - "8000:5000"
  volumes:
   - .:/code
  links:
   - redis
redis:
  image: redis

バージョン 2 ¶

バージョン 2 の Compose ファイルでは、ドキュメントの冒頭でバージョン番号を明示する必要があります。 services キーの下でサービスをすべて定義する必要があります。

バージョン２のファイルは Compose 1.6.0 以上 でサポートされており、実行には Docker Engine 1.10.0 以上 が必要です。

名前付きボリュームの宣言は volumes キーの下で行えます。また、名前付きネットワークの宣言は networks キーの下で行えます。

デフォルトでは、すべてのコンテナがアプリケーション全体のデフォルトネットワークに接続(join) します。そして（コンテナの）ホスト名は、各サービス名と同じ名前で発見可能になります。つまり、 links は全くもって不要です。詳細は Compose のを参照ください。

注釈

Compose ファイルのバージョンを指定する場合は、メジャー番号とマイナー番号の両方を指定する必要があります。マイナーバージョンの指定がなければ、最新のマイナーバージョンではなく、デフォルトの 0 が使われます。その結果、新しいバージョンで追加された機能はサポートされません。たとえば

version: "2"

は、以下の指定と同等です。

version: "2.0"

簡単な例：

version: "2.4"
services:
  web:
    build: .
    ports:
     - "8000:5000"
    volumes:
     - .:/code
  redis:
    image: redis

ボリュームとネットワークを定義するよう拡張した例：

version: "2.4"
services:
  web:
    build: .
    ports:
     - "8000:5000"
    volumes:
     - .:/code
    networks:
      - front-tier
      - back-tier
  redis:
    image: redis
    volumes:
      - redis-data:/var/lib/redis
    networks:
      - back-tier
volumes:
  redis-data:
    driver: local
networks:
  front-tier:
    driver: bridge
  back-tier:
    driver: bridge

以下のような、ネットワーク機能をサポートするオプションが追加されました。

aliases

depends_on オプションは、links に置き換わるもので、サービスと起動順番との間での依存関係を示します。

version: "2.4"
services:
  web:
    build: .
    depends_on:
      - db
      - redis
  redis:
    image: redis
  db:
    image: postgres

ipv4_address 、 ipv6_address

バージョン 2 では、変数の置き換えも追加されました。

バージョン 2.1 ¶

バージョン 2 の更新版で、 Docker Engine バージョン 1.12.0 以上 のみで利用可能なパラメータが導入されました。バージョン 2.1 形式のファイルは、 Compose 1.9.0 以上 でサポートされています。

以下のパラメータが追加導入されました。

link_local_ips
構築時の設定と、サービス定義での分離（isolation）
volumes 、 networks 、 build 用の lables
volumes 用の name
userns_mode
healthcheck
sysctls
pids_limit
oom_kill_disable
cpu_period

バージョン 2.2 ¶

バージョン 2.1 の更新版で、 Docker Engine バージョン 1.13.0 以上 のみで利用可能なパラメータが導入されました。バージョン 2.2 形式のファイルは、 Compose 1.13.0 以上 でサポートされています。また、このバージョンでは、サービスの定義内でデフォルトのスケール数(default scale numbers) を指定可能になりました。

以下のパラメータが追加導入されました。

init
scale
cpu_rt_runtime と cpu_rt_period
build 設定用の network

バージョン 2.3 ¶

バージョン 2.2 の更新版で、 Docker Engine バージョン 17.06.0 以上 のみで利用可能なパラメータが導入されました。バージョン 2.3 形式のファイルは、 Compose 1.16.0 以上 でサポートされています。

以下のパラメータが追加導入されました。

build 設定用の target 、 extra_hosts 、 shm_size
healthchecks 用の start_period
volumes 用の「長い書式（Long syntax）」
サービス定義用の runtime
device_cgroup_rules

バージョン 2.4 ¶

バージョン 2.3 の更新版で、 Docker Engine バージョン 17.12.0 以上 のみで利用可能なパラメータが導入されました。バージョン 2.4 形式のファイルは、 Compose 1.21.0 以上 でサポートされています。

以下のパラメータが追加導入されました。

サービス定義用の platform
サービスのルート、ネットワーク、ボリューム定義での、拡張フィールド(extension field) をサポート

バージョン 3 ¶

Compose と Docker Engine の swarm モード間で、互換性を持つように設計されました。バージョン 3 では複数のオプションが削除され、さらに複数のオプションが追加されました。

削除： volume_driver 、 volumes_from 、 cpu_shares 、 cpu_quota 、 cpuset 、 mem_limit 、 memswap_limit 、 extends 、 group_add 。これらを移行するにはアップグレード方法のガイドをご覧ください（ extends に関する詳しい情報は、サービスのをご覧ください）。
追加： deploy

注釈

Compose ファイルのバージョンを指定する場合は、メジャー番号とマイナー番号の両方を指定する必要があります。マイナーバージョンの指定がなければ、最新のマイナーバージョンではなく、デフォルトの 0 が使われます。その結果、新しいバージョンで追加された機能はサポートされません。たとえば

version: "3"

は、以下の指定と同等です。

version: "3.0"

バージョン 3.1 ¶

バージョン 3 の更新版で、 Docker Engine バージョン 17.04.0 以上 のみで利用可能なパラメータが導入されました。

以下のパラメータが追加導入されました。

secret

バージョン 3.2 ¶

バージョン 3 の更新版で、 Docker Engine バージョン 17.04.0 以上 のみで利用可能なパラメータが導入されました。

以下のパラメータが追加導入されました。

構築時の設定で、 cache_from
ports と volume マウントの長い構文(long syntax)
ネットワーク・ドライバのオプション * attachable
endpoint_mode のデプロイ
デプロイ時の配置設定(deploy placement) preference

バージョン 3.3 ¶

バージョン 3 の更新版で、 Docker Engine バージョン 17.06.0 以上 のみで利用可能なパラメータが導入されました。

以下のパラメータが追加導入されました。

バージョン 3.4 ¶

バージョン 3 の更新版で、 Docker Engine バージョン 17.09.0 以上 のみで利用可能なパラメータが導入されました。

以下のパラメータが追加導入されました。

構築用設定(build configurations) の target と network
healthcheck 用の start_period
設定更新時の順番（ order ）
volumes の name

バージョン 3.5 ¶

バージョン 3 の更新版で、 Docker Engine バージョン 17.12.0 以上 のみで利用可能なパラメータが導入されました。

以下のパラメータが追加導入されました。

サービス定義での分離（isolation）
networks、secrets、configs での name
構築用設定での shm_size

バージョン 3.6 ¶

バージョン 3 の更新版で、 Docker Engine バージョン 18.02.0 以上 のみで利用可能なパラメータが導入されました。

以下のパラメータが追加導入されました。

tmpfs タイプをマウントする tmpfs サイズ

バージョン 3.7 ¶

バージョン 3 の更新版で、 Docker Engine バージョン 18.06.0 以上 のみで利用可能なパラメータが導入されました。

以下のパラメータが追加導入されました。

サービス定義での init
デプロイ設定での rollback_config
サービスのルート、ネットワーク、ボリューム、シークレット、設定定義での拡張フィールドをサポート

バージョン 3.8 ¶

バージョン 3 の更新版で、 Docker Engine バージョン 19.03.0 以上 のみで利用可能なパラメータが導入されました。

以下のパラメータが追加導入されました。

placement 設定での max_replicas_per_node
config と secret 向けの template_driver オプション。このオプションをサポートしているのは、 docker stack deploy を使って swarm サービスをデプロイした時のみ。
secret 向けの driver オプションと driver_opts オプション。このオプションをサポートしているのは、 docker stack deploy を使って swarm サービスをデプロイした時のみ。

アップグレード方法 ¶

バージョン 2.x から 3.x ¶

バージョン 2.x と 3.x 間では、 Compose ファイルの構造は同じですが、いくつかのオプションが削除されています。

volume_driver : サービス上でボリュームドライバ(volume driver) を設定するのではなく、トップレベルの volumes オプションを使ってボリュームを定義し、ドライバもそこで指定します。
::
version: "3.9" services: db: image: postgres volumes: - data:/var/lib/postgresql/data volumes: data: driver: mydriver
volumes_from : サービス間でボリューム(volume) を共有するには、トップレベルの volumes オプションを使ってボリュームを定義します。それから、サービスごとにサービスレベルの volumes オプションを使い、対象のボリュームを参照します。
cpu_shares 、 cpu_quota 、 cpuset 、 mem_limit 、 memswap_limit : これらは deploy 以下の resources キーに置き換えられました。この deploy 設定が有効なのは、 docker stack deploy を使った時のみであり、 docker-compose では無視されます。
extends : このオプションは version: "3.x" 向けの Compose ファイルでは削除されました。（詳しい情報は、サービスのをご覧ください。）
group_add : このオプションは version: "3.x" 向けの Compose ファイルでは削除されました。
pids_limit : このオプションは version: "3.x" 向けの Compose ファイルでは削除されました。
networks での link_local_ips : このオプションは version: "3.x" 向けの Compose ファイルでは削除されました。

バージョン 1 から 2.x ¶

ほとんどの場合、バージョン１から２への移行はとても簡単な手順です。

最上位のレベルに services: キーを追加する。
ファイルの１行め冒頭に version: '2' を追加する。

特定の設定機能を使っている場合は、より複雑です。

dockerfile ： build キー配下に移動します。

build:
  context: .
  dockerfile: Dockerfile-alternate

log_driver 、 log_opt ：これらは logging キー以下です。

logging:
  driver: syslog
  options:
    syslog-address: "tcp://192.168.0.42:123"

links と環境変数： CONTAINERNAME_PORT のような、links によって作成される環境変数機能は、いずれ廃止予定です。新しい Docker ネットワーク・システム上では、これらは削除されています。ホスト名のリンクを使う場合は、適切なホスト名で接続できるように設定するか、あるいは自分自身で代替となる環境変数を指定します。

web:
  links:
    - db
  environment:
    - DB_PORT=tcp://db:5432

external_links ：バージョン２のプロジェクトを実行する時、 Compose は Docker ネットワーク機能を使います。つまり、これまでのリンク機能と挙動が変わります。典型的なのは、２つのコンテナが通信するためには、少なくとも１つのネットワークを共有する必要があります。これはリンク機能を使う場合でもです。

外部のコンテナがアプリケーションのデフォルト・ネットワークに接続する場合や、自分で作成したサービスが外部のコンテナと接続するには、外部ネットワーク機能を使います。

net ：これは network_mode に置き換えられました。

net: host    ->  network_mode: host
net: bridge  ->  network_mode: bridge
net: none    ->  network_mode: none

net: "コンテナ:[サービス名]" を使っていた場合は、 network_mode: "サービス:[サービス名]" に置き換える必要があります。

net: "container:web"  ->  network_mode: "service:web"

net: "コンテナ:[コンテナ名/ID]" の場合は変更不要です。

net: "container:cont-name"  ->  network_mode: "container:cont-name"
net: "container:abc12345"   ->  network_mode: "container:abc12345"

net: "container:abc12345" -> network_mode: "container:abc12345"

volumes を使う名前付きボリューム：Compose ファイル上で、トップレベルの volumes セクションとして明示する必要があります。 data という名称のボリュームにサービスがマウントする必要がある場合、トップレベルの volumes セクションで data ボリュームを宣言する必要があります。記述は以下のような形式です。

version: '2.4'
services:
  db:
    image: postgres
    volumes:
      - data:/var/lib/postgresql/data
volumes:
  data: {}

デフォルトでは、 Compose はプロジェクト名を冒頭に付けたボリュームを作成します。 data のように名前を指定するには、以下のように宣言します。

volumes:
  data:
    external: true

互換モード(compatibility mode)¶

開発者がバージョン 3 に簡単に以降するための手助けとなるのを意図し、 docker-compose 1.20.0 では新しい --compatibility （互換性）フラグが追加されミズ空いた。これを有効にすると、 docker-compose は deploy セクションの各サービス定義を読み込み、バージョン 2 のパラメータと同等に解釈しようとします。現時点では、以下の deploy キーが変換されます。

resources の制限(limits) とメモリ予約(memory reservations)
replicas
restart_policy の condition と max_attempts

その他のキーはすべて無視され、指定しても警告が表示されます。 config コマンドで --compatibility フラグを使うと、デプロイに使う設定をレビューできます。

注釈

本番環境では使わないでください

本番環境での --compatibility モードの使用に反対します。結果的に設定は、非 Swarm モードでの設定値(property) に近似しているだけであり、それにより、予期しない結果を生み出す可能性があるからです。

Compose ファイル形式リファレンス ¶

参考

Compose file versions and upgrading: https://docs.docker.com/compose/compose-file/compose-versioning/