Dockerfile の `COPY --exclude` オプションを使うために

※ 本記事は筆者による検証結果と個人的見解です。誤りや不足がありましたらぜひご指摘ください。

COPY --exclude は Dockerfile に最近追加された新しいオプションです。.dockerignore と比べると、ビルドの 異なるステージごとに 無視するファイルを切り替えられる点がメリットになります。

新しい機能であるため、利用時には コンテナツールのバージョン に注意が必要です。ここでは環境ごとに推奨されるコンテナツールをまとめました。

使用例：

# syntax=docker/dockerfile:1.7-labs
# Podman を使う場合、この行は不要

FROM python:3.11-slim AS builder
COPY --exclude=models . .

# 中略

FROM public.ecr.aws/sagemaker/sagemaker-distribution:2-gpu AS production
COPY models .

# 以降略

必須要件

Docker を使う場合
- Dockerfile の先頭に # syntax=docker/dockerfile:1.7-labs を記述する
- docker buildx でビルドする

Podman を使う場合
- 2024 年にリリースされた v5.3.0 以降 が必要

Docker と Podman、どちらを選ぶ？

OS / ディストリビューション	推奨ツール	理由
RHEL	Podman	デフォルトで Podman 5.4.0 がインストール済み。公式リポジトリに Docker がなく、Docker + Buildx Plugin の導入は手間。
Amazon Linux 2023	Docker	公式リポジトリの Docker に Buildx Plugin が同梱されており、`sudo dnf install docker` ですぐ使える。Podman を入れるには少し準備が必要。
Ubuntu	どちらも一手間かかる	公式リポジトリに Docker がなく、Podman も v4.9 と古い。どちらを使うにしても外部リポジトリや手動インストールが必要。
macOS	どちらでも可	Docker Desktop（または Rancher Desktop）には Buildx が含まれ、Podman も最新版を簡単に入手できる。

まとめ

まずは自分の環境に公式／デフォルトで用意されているツールを確認
Podman を使う場合は v5.3.0 以降 であることを必ずチェック
Docker を使う場合は Buildx が有効になっているか確認

「試したけど動かない！」という場合は、
docker buildx version / podman --version の結果をご確認ください。