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 の挙動

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

バージョン1(非推奨)

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

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

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

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

例:

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

バージョン 2

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

バージョン2のファイルは 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:
     - "5000:5000"
    volumes:
     - .:/code
  redis:
    image: redis

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

version: "2.4"
services:
  web:
    build: .
    ports:
     - "5000: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)
  • volumesnetworksbuild 用の 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) を指定可能になりました。

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

バージョン 2.3

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

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

  • build 設定 用の targetextra_hostsshm_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_drivervolumes_fromcpu_sharescpu_quotacpusetmem_limitmemswap_limitextendsgroup_add 。これらを移行するには アップグレード方法 のガイドをご覧ください( extends に関する詳しい情報は、 サービスの拡張 をご覧ください)。
  • 追加: deploy

注釈

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

version: "3"

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

version: "3.0"

バージョン 3.1

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

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

バージョン 3.2

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

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

バージョン 3.3

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

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

バージョン 3.4

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

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

  • 構築用設定(build configurations)targetnetwork
  • healthcheck 用の start_period
  • 設定更新時 の順番( order
  • volumesname

バージョン 3.5

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

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

バージョン 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
  • configsecret 向けの 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_sharescpu_quotacpusetmem_limitmemswap_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

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

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

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

  • dockerfilebuild キー配下に移動します。
build:
  context: .
  dockerfile: Dockerfile-alternate
  • log_driverlog_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 : バージョン2のプロジェクトを実行する時、 Compose は Docker ネットワーク機能を使います。つまり、これまでのリンク機能と挙動が変わります。典型的なのは、2つのコンテナが通信するためには、少なくとも1つのネットワークを共有する必要があります。これはリンク機能を使う場合でもです。

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

  • 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-composedeploy セクションの各サービス定義を読み込み、バージョン 2 のパラメータと同等に解釈しようとします。現時点では、以下の deploy キーが変換されます。

  • resources制限(limits)メモリ予約(memory reservations)
  • replicas
  • restart_policyconditionmax_attempts

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

注釈

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

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