Docker で overlay2 が使用できない（overlayfs が無効になっている） – amnimo FAQ

Docker のストレージドライバが vfs になりパフォーマンスが低下する場合、使用中のファームウェア／カーネルで overlayfs が無効になっていることが原因として考えられます。本記事では、原因の確認方法と解決策を説明します。

🚨 重要：本記事の内容（Docker 利用やカーネルオプション変更）は製品の動作保証対象外です。実施はお客様の責任のもと、検証環境で十分に確認のうえ本番適用してください。

対象

対象機種の例：AGシリーズ、AXシリーズ
典型的な環境例：Linux Kernel 5.10 系（CIP ベース）

※実機の型番・ファームウェアは以下のコマンドで確認してください。

admin@amnimo:~$ uname -r
5.10.201-cip41-01316-g6c57332311e5
admin@amnimo:~$ amsh
amnimo$ show firmware
amnimo G series AG10 version 3.2.0 build 71970
 Kernel: 5.10.201-cip41-01316-g6c57332311e5 #1 SMP PREEMPT Tue Jul 15 01:41:22 UTC 2025
 Bootloader: U-Boot 2018.03-devel-18.12.3 (Jul 08 2025 - 04:41:43 +0000)
 BootArea: 0
 Partitions: 5

症状

Docker のストレージドライバが vfs になり、ビルドや I/O のパフォーマンスが出ない。
overlay2 を使いたいが、以下のようなエラーで overlayfs が使えないと判断される。

sudo modprobe overlay
# => modprobe: FATAL: Module overlay not found in directory /lib/modules/<kernel-version>

原因

使用中のファームウェア／カーネルで overlayfs が無効になっています（カーネルオプション CONFIG_OVERLAY_FS が未有効）。

解決方法（推奨）：対応ファームウェアへ更新する

overlayfs が有効な 3.x.x 系ファームウェアへ更新してください。更新後、overlay2 が利用可能になります。

1) アップデート実施

手順は製品のファームウェア更新ドキュメントに従ってください。
更新前に設定・データのバックアップを推奨します。

2) 更新後の確認

以下のコマンドで overlayfs と Docker ストレージドライバを確認します。

# overlayfs がカーネルに存在するか
grep overlay /proc/filesystems
# 例: nodev   overlay  と表示されれば有効化済み

# あるいはモジュールの有無（built-in の場合は表示されません）
lsmod | grep overlay

# Docker のストレージドライバ確認
docker info --format '{{.Driver}}'
# 例: overlay2

ℹ️ 補足：3.x.x 系では CONFIG_OVERLAY_FS=y を含む、コンテナ実行に必要な主要オプション（namespaces、cgroups 等）が有効化されています。

代替策（保証外）：2.x.x 系のまま使う場合

どうしても 2.x.x 系を維持したい場合は、カーネルオプションを変更して再ビルドが必要です（保証外）。

一般的な目安：

CONFIG_OVERLAY_FS=y（または m）
コンテナ関連：CONFIG_NAMESPACES、UTS_NS、IPC_NS、PID_NS、NET_NS、USER_NS
cgroups：CONFIG_CGROUPS と関連機能
主要 FS：EXT4、XFS など

🚨 重要：カーネルビルド方法は「エッジゲートウェイデベロッパーズマニュアル（Linux カーネルのビルド方法）」を参照してください。再ビルド・導入は高度な知識を要し、製品保証対象外です。

バージョン別の目安（例）

機種	2.x.x 系	3.x.x 系
AG10	`overlayfs` 無効（例：2.6.2）	`overlayfs` 有効（例：3.2.0）
AX11	`overlayfs` 無効（例：2.6.2）	`overlayfs` 有効（例：3.1.0）

ℹ️ 補足：上表は代表例です。実機では必ず show firmware および確認コマンドで状態を確認してください。

Docker 側の設定（必要に応じて）

通常は overlayfs が有効なカーネルでは Docker が自動で overlay2 を選択しますが、環境によっては明示指定が必要な場合があります。

# /etc/docker/daemon.json に storage-driver を明示
sudo mkdir -p /etc/docker
cat <<'EOF' | sudo tee /etc/docker/daemon.json
{
  "storage-driver": "overlay2"
}
EOF
# 反映
sudo systemctl daemon-reload
sudo systemctl restart docker

# 確認
docker info --format '{{.Driver}}'   # => overlay2

⚠ 注意：既に vfs で運用していた場合、ドライバ切り替えには /var/lib/docker の初期化（削除）が必要となるケースがあります。データ消失に注意し、十分なバックアップと切り替え計画を立てて実施してください。

よくある質問（FAQ）

Q1. 3.x.x 系で overlayfs が無効化される予定はありますか？

A. 3.x.x 系では変更予定はありません。ただし、将来の 4.x.x 系以降については保証できません。

Q2. overlay2 が選ばれず vfs のままです。

A. 次を確認してください。

grep overlay /proc/filesystems に overlay が出るか
Docker の起動順序・設定（/etc/docker/daemon.json）
既存の /var/lib/docker に vfs メタデータが残っていないか
カーネルが製品標準の 3.x.x 系に更新済みか

Q3. Docker の利用はサポート対象ですか？

A. 本機での Docker 利用・カーネル再構築は動作保証対象外です。お客様の責任にて評価のうえご利用ください。

対象

症状

原因