docker compose runの--rm忘れでorphan containers警告が溜まってた

この記事は、構成と文章の整理にAIを使っています。
あくまで読みやすくするための補助で、内容そのものをAIにすべて任せて書いているわけではありませんが、ところどころ相談しながら整えています。

docker compose up するたびに以下の警告が出るようになった。

WARN[0000] Found orphan containers ([example-service-run-5b309a2333a4 example-service-run-fb0ce3e50aaa example-service-run-72954821e119]) for this project.

コンテナ名を見ると example-service という同じサービス名の後ろに run-<hash> が付いた形で複数残っている。最初は「サービス名変えたっけ？」と思ったけど、心当たりがなかった。

原因

このワーニングの一般的な原因は、公式の警告文の通り3パターンある。

• Compose ファイルでサービス名を変更・削除した
• 別の Compose ファイルやプロジェクト名で起動し直した
• Compose ファイルを変更したのに古いコンテナを手動で止めていない

ただし今回のように -run-<hash> という命名規則が付いているコンテナの場合、これは上記とは別のパターンで、docker compose run コマンドで作られた一時コンテナが原因らしい。

docker compose run は本来「使い捨て」のコンテナを起動するコマンドで、--rm オプションを付けないと実行後もコンテナが残り続ける。そして次に docker compose up や docker compose run を実行するたびに、その残骸が「今のCompose定義には存在しないコンテナ」として orphan 扱いされて積み上がっていく。

この挙動は docker/compose の GitHub issue でも複数報告されている（#12314、#12214）。中には --remove-orphans を付けて docker compose run しても消えないという報告もあった。実機で --remove-orphans 付き run を検証したわけではないので、そこは未確認。

対応

原因によって対応が変わる。

サービス名変更・Composeファイル切り替えが原因の場合

docker compose up --remove-orphans

docker compose run の使い捨てコンテナが原因の場合

まず現状確認。

docker ps -a

example-service-run-<hash> のようなコンテナが並んでいたら、それが該当する。個別に消すなら以下。

docker rm -f example-service-run-5b309a2333a4 \
              example-service-run-fb0ce3e50aaa \
              example-service-run-72954821e119

根本対応としては、今後 docker compose run を使うときに --rm を忘れないこと。

docker compose run --rm example-service some-command

-run-<hash> という命名パターンが付いているorphanコンテナを見かけたら、サービス名変更よりも先に docker compose run --rm の付け忘れを疑ったほうが早い。