Colima + sshfs 環境で AWS CDK の Python レイヤーバンドリングが失敗する2つの原因と virtiofs での解決策
はじめに
みなさん Colima を使われているでしょうか。
macOS で Docker を使う際、Docker Desktop の代替として Colima を使っている方も多いでしょう。
以前はRancher Desktopを使っていたのですが、若干重いなと思いこちらを参考に移行しました。
移行後に AWS CDK で Python Lambda レイヤーをバンドリングしようとしたところ、見慣れないエラーに遭遇しました。
原因は 2 つの独立した問題の重なりで、どちらも Colima のマウント方式（sshfs）に起因しており、virtiofs に移行することで両方まとめて解決できました。
環境
| 項目 | 値 |
|---|---|
| macOS | 15.7.4 (Apple Silicon / aarch64) |
| Colima | 0.10.3 |
| Docker | v27.4.0 (Colima 経由) |
| CDK | aws-cdk-lib 2.232.2 |
| @aws-cdk/aws-lambda-python-alpha | 2.222.0-alpha.0 |
事象
npm run test（CDK スナップショットテスト）を実行すると、以下の 2 種類のエラーが発生しました。
エラー 1: rsync Permission denied
rsync: [Receiver] mkdir "/asset-output/python" failed: Permission denied (13)
CDK は Python レイヤーをビルドする際、以下のようなコマンドでコンテナを起動します。
docker run --rm -u "502:20" \
-v "/Users/suzuki.jun/.../apps/layers/util:/asset-input:delegated" \
-v "/private/var/folders/.../asset-building:/asset-output:delegated" \
<cdk-image> \
bash -c "rsync ... /asset-input/ /asset-output/python && uv export ..."
-u 502:20（macOS の UID:GID）で起動したコンテナが /asset-output への書き込みに失敗している状態です。
エラー 2: Bundling did not produce any output
ValidationError: Failed to bundle asset ...: bundle output is located at
/private/var/folders/.../asset-building: ExecutionError: Bundling did not produce any output
rsync 自体は成功しているものの、CDK が出力ディレクトリを検証できないエラーです。
原因の調査
問題 1 の根本原因: sshfs の UID マッピング
Colima はデフォルトで mountType: sshfs を使用します。
このモードではホスト macOS 側の UID 502 が Colima の Linux VM 内で root（UID 0）にマッピングされます。
Docker に -u 502:20 を渡しても、マウントされたボリュームのオーナーはコンテナ内では別の UID となるため、書き込みが拒否されてしまいます。
問題 2 の根本原因: TMPDIR が Colima にマウントされていない
macOS の os.tmpdir() は /private/var/folders/... を返しますが、Colima はデフォルトでホームディレクトリ（$HOME）のみを VM にマウントします。
/private/var/folders は Colima の VM 外のため、CDK が Docker にマウントしようとしてもコンテナ内から見えず、出力の検証に失敗します。
試したが不十分だった対処
user: "root" を CDK コンストラクトに追加する
bundling: {
assetExcludes: [".venv", "__pycache__", ".pytest_cache", "*.pyc", ".DS_Store"],
environment: { UV_PYTHON: "python3.13" },
user: "root",
},
UID マッピング問題（エラー 1）は回避できますが、TMPDIR 問題（エラー 2）は残ります。
また、ローカル環境固有の問題をプロジェクトファイルへ持ち込む形になるため採用しませんでした。
package.json の test スクリプトに TMPDIR を設定する
"test": "mkdir -p $HOME/.cache/cdk-tmp && TMPDIR=$HOME/.cache/cdk-tmp jest"
TMPDIR 問題（エラー 2）は解決しますが、エラー 1 は残ります。
プロジェクト全体のテストコマンドを書き換えることになるため、こちらも採用しませんでした。
2 つの問題を個別に回避しようとするとプロジェクトファイルへの変更が必要になります。
ただ本来この問題はローカル環境側に起因しているため、環境側で解決したいところです。
解決方法: Colima を virtiofs に移行する
virtiofs（Apple VZ framework）を使うと UID/GID がホストと同一のまま伝播します。
また TMPDIR も追加マウントで解決できるため、2 つの問題をまとめて解消できます。
1. Colima を停止・削除する
mountType は VM 作成後に変更できないため、VM を削除して再作成します。
colima stop
colima delete --force
2. virtiofs + 必要なマウントで起動する
colima start \
--vm-type vz \
--mount-type virtiofs \
--mount /Users/suzuki.jun:w \
--mount /private/var/folders:w
--mount /private/var/folders:w を追加することで TMPDIR の問題も解消できます。
/Users/suzuki.jun の部分はご自身のユーザー名に合わせてください。
確認する
起動後、VM 内のマウント状況を確認してみましょう。
colima ssh -- mount | grep virtiofs
# lima-xxx on /Users/suzuki.jun type virtiofs (rw,relatime)
# lima-xxx on /private/var/folders type virtiofs (rw,relatime)
2 つのマウントが確認できたら、CDK のスナップショットテストを実行します。
npm run build && npm run test
プロジェクトファイルを変更せずにテストが通れば成功です。
注意点: --mount 指定で $HOME 自動マウントが上書きされる
--mount でカスタムマウントを指定すると、Colima のデフォルト $HOME 自動マウントが上書きされます。
/private/var/folders だけを指定すると $HOME がマウントされず、Docker の -v /Users/... ボリュームが空になってしまいます。
必ず /Users/<username>（$HOME）も明示的に追加してください。
なお colima.yaml を編集して colima stop && colima start しても、virtiofs のマウント変更は既存 VM に反映されません。
確実に反映するには colima delete で VM を再作成してください。
mountType: virtiofs
mounts:
- location: /Users/suzuki.jun
writable: true
- location: /private/var/folders
writable: true
CI（GitHub Actions）との差異
この問題はローカルの Colima 環境固有です。
GitHub Actions は Linux（Ubuntu-latest x64）上でネイティブ動作するため、UID マッピングや TMPDIR の問題は生じません。
プロジェクトファイルを変更する必要はありません。
まとめ
Colima を virtiofs に移行することで、CDK の Python レイヤーバンドリングをプロジェクトファイルの変更なしに動かせました。
2 つのエラーが独立した原因（sshfs の UID マッピングと TMPDIR のマウント外問題）から来ていたため最初は混乱しましたが、Colima の仕様を理解してスムーズに解決できました。
macOS で Colima を使って CDK の Python バンドリングがうまくいかない場合は、ぜひ virtiofs への移行を試してみてください。
以上、鈴木純がお送りしました。
