Docker ComposeのComposeファイルのバージョンについて

はじめに

Docker ComposeのComposeファイル(docker-compose.yml)の冒頭でversion: '3'のようにバージョン表記があるが、バージョン番号に何を書くのが正しいかを調べてみた。

結論

Composeファイル中のversionで指定するのは、Composeファイルのフォーマットのバージョンである。 公式ドキュメントとGitHubのreleaseの情報をまとめると、各バージョンの対応表は以下の通り。

Compose file format Docker Engine
3.7 (Compose 1.22.0+) 18.06.0+
3.6 (Compose 1.20.0+) 18.02.0+
3.5 (Compose 1.18.0+) 17.12.0+
3.4 (Compose 1.17.0+) 17.09.0+
3.3 (Compose 1.14.0+) 17.06.0+
3.2 (Compose 1.12.0+) 17.04.0+
3.1 (Compose 1.11.0+) 1.13.1+
3.0 (Compose 1.10.0+) 1.13.0+
2.4 (Compose 1.21.0+) 17.12.0+
2.3 (Compose 1.16.0+) 17.06.0+
2.2 (Compose 1.13.0+) 1.13.0+
2.1 (Compose 1.9.0+) 1.12.0+
2.0 (Compose 1.6.0+) 1.10.0+
1.0 1.9.1.+

フォーマットのバージョン2.xと3.xは並行してアップデートされているようだ。 それぞれのバージョンのフォーマットのドキュメントは、以下にある。

Compose file format ドキュメントのURL
3.x https://docs.docker.com/compose/compose-file/
2.x https://docs.docker.com/compose/compose-file/compose-file-v2/
1.0 https://docs.docker.com/compose/compose-file/compose-file-v1/

Composeファイルのバージョンの指定方法について

ドキュメントには以下のようにある。

Note: When specifying the Compose file version to use, make sure to specify both the major and minor numbers. If no minor version is given, 0 is used by default and not the latest minor version.

日本語に訳すと以下のようになる。

注: 利用時にComposeファイルのバージョンを指定する場合は、メジャーとマイナーの番号を確実に指定してください。もしマイナーバージョンの指定がない場合は、最新のマイナーバージョンではなく、0が利用されます。

なので、明確にversion: '3.7'のように書くべきで、version: '3'という指定方法は避けたほうが良い。 公式ドキュメント中のサンプルのdocker-compose.ymlには、後者の表記が用いられていることがあるので、サンプルを流用する場合は注意が必要。

参考