Docker Compose v3→v4 移行ガイドと主な変更点

Docker Compose v3からv4への移行の概要

Docker Compose v3からv4への移行は、アプリケーション環境の一貫性向上と新機能利用を目的としています。特にネットワークモデルやYAML構文の仕様変更により、開発・本番環境での挙動差異を抑制できるようになりました。この記事では、移行に際して確認すべき主要な変更点と実施手順を具体的に解説します。

移行の目的と背景

Docker Compose v4は、コンテナ通信やボリューム管理の柔軟性を高める仕様刷新が行われています。例えば、default_networkの廃止やサービス定義書のパラメータ差分など、v3からv4に移行することでエラー率の低減が期待できます。

対象となるユーザー層

本記事は、Docker Composeを用いたアプリケーション開発者やDevOpsエンジニア向けに執筆されています。特に、既存のYAMLファイルがv3形式の場合、移行作業を検討する必要があります。

v3とv4の主要な仕様変更点

Docker Compose v4では、ネットワークモデルやサービス定義書の構文に重要な変更が加えられています。具体的には以下の差分があります。

コンテナネットワークモデルの刷新

v4では、default_networkの廃止が大きな変更点です。これにより、各コンテナが明示的に指定されたネットワークに参加する必要が生じます。

blockquote: ネットワークを明示的に定義することで、コンテナ間通信の一貫性が確保されます。

サービス定義書のパラメータ差分

サービス定義書においても、いくつかのパラメータが変更または廃止されています。代表的な例として、buildフィールドで指定できるargsの仕様変更があります。

• v3: build: args: KEY=VALUE
• v4: build: context: ., dockerfile: Dockerfile, args: KEY=VALUE

このように、v4ではcontextとdockerfileを明示的に指定する必要があります。

YAMLファイルにおける構文変更事項

YAMLファイルの構文に沿った具体的な書き換え方を解説します。サービス定義書やネットワーク設定の差分が明確になるため、v3とv4の比較表を作成しました。

service定義書の記法更新

v3からv4への移行では、buildフィールドの書き換えが必須です。また、portsやvolumesの指定方法にも変更があります。

• v3例:
  yaml
services:
app:
build: .
ports:
- "80:80"

• v4例:
  yaml
services:
app:
build:
context: .
dockerfile: Dockerfile
ports:
- target: 80
published: 80
protocol: tcp

blockquote: v4では、portsやvolumesのフィールドに加え、プロトコル名などの明示的な指定が求められます。

ネットワーク・ボリューム設定の書き換え方

ネットワーク設定は、networksセクションで定義されたネットワーク名をサービス定義書内で参照する必要があります。

• v3例:
  yaml
services:
app:
networks:
- default

• v4例:
  yaml
services:
app:
networks:
my_network:
aliases:
- alias1

blockquote: v4では、defaultネットワークの使用はできず、明示的に定義されたネットワーク名を指定する必要があります。

ボリューム・コンフィギュレーションの互換性確認

ボリュームやコンフィギュレーションファイルの互換性が確保されているかをテストする手順を解説します。

永続化データの移行手順

v4では、volumesセクションの書き換えが必須です。特に、ボリュームマッピングの指定方法に変更があります。

• v3例:
  yaml
volumes:

  • type: volume
name: my_volume
driver: default


• v4例:
  yaml
volumes:

  • my_volume:
driver: default


blockquote: v4では、typeやdriverの指定が省略されることがあり、互換性チェックが必要です。

コンフィギュレーションファイルのバージョンチェック

v3とv4のコンフィギュレーションファイルは互換性があるものの、extendsやconfigsの仕様に変更があるため、確認が必須です。

• extends: v4では、指定するリファレンスの形式が変更されています。
• configs: v4では、コンフィギュレーションファイルを明示的に定義する必要があります。

移行後のサービス起動テストとトラブルシューティング

移行後は、サービス起動時のエラーに注意が必要です。代表的なエラーコードやその解決策を紹介します。

エラーコード一覧と解決策

v4への移行中に発生する代表的なエラー例と対処法です。

• network not found: ネットワーク定義が不完全な場合に発生します。ネットワークセクションを明示的に定義してください。
• invalid compose file: invalid at line X: YAMLファイルの構文ミスがある可能性があります。YAML Validatorでチェックしてください。

Docker Desktopでのデバッグツール活用法

Docker Desktop v4.20+では、Graphical User Interface (GUI)からサービスのステータスを確認できるようになりました。以下の手順でデバッグを行います。

1. Docker Desktopを開き、「Resources」タブを選択
2. 「Compose」セクションで移行後のYAMLファイルが表示されているか確認
3. エラーが発生しているサービスを右クリックし、「View logs」を選択

blockquote: GUIでのデバッグは、エラーの特定と解決に効果的です。

Docker Desktop v4.20+での注意点

Docker Desktop v4.20以降では、GUI設定やCLIコマンドに変更が加えられているため、移行時に注意が必要です。

GUI設定とCLIコマンドの変更

v4.20以降では、docker-compose upコマンドに加えて、Docker Desktop内での設定反映が優先される傾向があります。

• GUI設定: ネットワークやボリュームのマッピングは、Docker Desktop内から変更可能です。
• CLIコマンド: docker-compose configなど、ファイルの構文チェックを明示的に実行する必要があります。

互換性テスト時のバージョン管理

v4.20以降では、Docker EngineとComposeファイルのバージョンが一致しているかを必ず確認してください。バージョンが異なる場合、予期せぬ挙動が発生する可能性があります。

• 推奨手順: docker-compose --versionで現行バージョンを確認し、公式ドキュメントに記載された互換性リストと照合する。

blockquote: Docker Desktop v4.20以降のGUI操作手順は、公式ドキュメントとの整合性確認が必要です（最新バージョンでの変更リスクあり）。

まとめ

本記事では、Docker Compose v3からv4への移行に関する以下のポイントを解説しました:

• ネットワークモデルの刷新により、明示的な設定が求められるようになった
• YAMLファイルの構文変更に注意し、buildやnetworksの書き換えが必要
• ボリューム・コンフィギュレーションにおける互換性確認手順を実施する
• 移行後のテストでは、エラーコードの一覧とその解決策を把握しておくこと
• Docker Desktop v4.20以降では、GUI設定やCLIコマンドの変更に注意が必要

最新版Docker Composeファイルを作成する際は、公式ドキュメントのバージョンガイドを参照しつつ本記事の手順をご活用ください。