Docker Compose v1→v2移行ガイド｜最新手順とトラブルシューティング

Docker Compose v2移行の概要と準備

Docker Compose v1からv2への移行は、DevOpsエンジニアやLinuxサーバー管理者にとって重要な課題です。Docker Compose v2は公式リポジトリから提供される最新バージョンで、v1と比べてDocker CLIに統合されたサブコマンドとして実行されるため、安定性やパフォーマンスの向上が期待できます。移行する際には、まず現在の環境を確認し、公式リポジトリ経由での導入を推奨します。以下の手順で準備を進めることで、問題なく移行が可能です。

公式リポジトリ導入の重要性

公式リポジトリを利用してパッケージを導入するメリットは、信頼性とセキュリティにあります。非公式なソースや手動ダウンロードでは、バージョン不整合や脆弱性リスクが生じる可能性があります。Docker Compose v2の導入においても公式リポジトリ経由の利用が最善策です。

移行前の環境確認フロー

移行前に環境を確認することでトラブルを防ぎます。以下のステップに従い、システムとの互換性や現在のバージョン状況を把握してください。

1. OSのバージョン確認: cat /etc/os-release または uname -a を実行し、Linuxディストリビューションとバージョンを確認します。
2. Docker Engineのバージョンチェック: docker --version でインストールされているDocker Engineのバージョンを把握します。v20以上が推奨されます。
3. 既存のComposeバージョン確認: docker compose version を実行し、現在のバージョンを取得します。

現在のDocker Composeバージョン確認手順

Docker Compose v2ではdocker-compose --versionコマンドが非推奨となりました。代わりに以下の方法でバージョン情報を得られます。

docker compose versionコマンドの代替案

v1とv2を混在させた環境では、docker compose version コマンドが有効です。このコマンドは、現在のComposeバージョンとサブコマンドの一覧を表示します。

Docker EngineとComposeバージョンの関係性

Docker EngineとComposeのバージョンは密接に関連しています。以下の表は推奨組み合わせです。

注意: Docker Engineが古すぎると、v2の新機能を活用できません。最新バージョンへのアップグレードも検討してください。

docker-compose-pluginのインストール方法

Docker Compose v2ではdocker-compose-plugin を公式リポジトリから導入する方法が推奨されています。以下に、Linuxディストリビューションごとの手順を紹介します。

APTベースOSでの手順

DebianやUbuntuなどのAPTベースOSを使用している場合、以下のコマンドでインストールできます。

1. 公式リポジトリの追加:
   $ curl -fsSL https://get.docker.com | sh

2. パッケージの更新とインストール:
   $ sudo apt update
$ sudo apt install docker-compose-plugin

DNF/YUMベースOSでの手順

FedoraやCentOSなどのDNF/YUMベースOSでは、以下のように手順を進める必要があります。

1. 公式リポジトリの追加:
   $ dnf config-manager --add-repo=https://download.docker.com/linux/fedora/docker.repo

2. パッケージの更新とインストール:
   $ sudo dnf update -y
$ sudo dnf install -y docker-compose-plugin

注意: 上記コマンドは、Docker公式リポジトリが正しく設定されている前提で動作します。リポジトリのURLが変更された場合は、最新情報を確認してください。

YAMLファイルの実践的な書き換えポイント

Docker Compose v2ではYAMLファイルの記述規則に変更があります。特に以下の点をチェックすることが重要です。

ダッシュの必要性について

v2では、サービス名の前につけるダッシュ（-）は必須ではありません。v1では必須でしたが、v2では省略可能です。例えば、以下のような記述はv2でも動作します。

注意: ダッシュはv1との互換性を保つために追加される場合もありますが、v2では不要です。ファイル全体を確認しましょう。

エイリアス有効化設定例

v2では、docker-compose up ではなく docker compose up の形式を使用します。この変更に対応するためには、YAMLファイルに以下のように alias: true を追加してください。

補足: alias: true の設定は、一部の環境では不要ですが、v2の互換性を保つために推奨されます。

移行後のコマンド変更点と互換性対策

Docker Compose v1からv2への移行後は、コマンド形式に大きな違いがあります。以下では、主な変更点とその対応策を解説します。

v1/v2共存時のコマンド違い

このように、v2ではdocker-composeではなくdocker composeというコマンドの形式が変更されています。移行後に誤ってv1のコマンドを使用すると、エラーになる可能性があります。

スクリプトの互換性テスト方法

既存のスクリプトやCI/CDパイプラインに影響を与えないようにするには、以下のような対応が必要です。

• バージョン指定付きコマンドの使用:
  docker-compose v1 up
  このコマンドは、v2環境でもv1の動作を再現可能です。ただし、長期的に使用することは推奨されません。

• スクリプトの更新:
  docker-compose の部分をすべて docker compose に置き換えてください。これは、手動での変更だけでなく、CI/CD用のシェルスクリプトやDockerfileの中でも行う必要があります。

移行チェックリストとトラブルシューティング

移行後の環境を確認するためには、5ステップのチェックリストを使用してください。また、よくあるエラーに対応する方法も紹介します。

必須確認項目5ステップ

以下のように順にチェックすることで、移行が正常に行われていることを確認できます。

1. コマンドの実行: docker compose version を実行し、v2のバージョンが出力されることを確認。
2. YAMLファイルの整合性: 所有するサービス定義にダッシュがついているかチェック。
3. サービス起動テスト: docker compose up -d で全サービスを起動して動作を検証。
4. ログ確認: 起動中にエラーがないか、docker compose logs や journalctl で確認。
5. 互換性テスト: v1のコマンド（docker-compose up）を使用して、v2環境が正常に動作することを検証。

よくあるエラーの解決策

移行時に発生する主なエラーやその対処方法は以下の通りです。

重要: docker-compose-plugin のインストール状態も再確認してください。パッケージ管理システム（apt/dnf）を使用して再度インストールすると、問題が解決する場合があります。