[Bug]: Cannot use external APFS volume as container filesystem due to permission/ownership errors

[robbiemu]

I have done the following

• I have searched the existing issues
• If possible, I've reproduced the issue using the 'main' branch of this project

Steps to reproduce

1. Format an external drive as APFS and mount it at /Volumes/MacStorage.
2. Create a directory on the external volume: sudo mkdir -p /Volumes/MacStorage/services/gitlab.
3. Attempt to run a container with a bind mount from the external volume:

   sudo container run -d \
     --name gitlab-test \
     -v /Volumes/MacStorage/services/gitlab:/var/opt/gitlab \
     -p 8080:80 \
     gitlab/gitlab-ce:latest

4. Observe the container logs:

   sudo container logs gitlab-test

   You will see permission denied errors when the container attempts to write to /var/opt/gitlab.

Expected Behavior:
The container should start successfully and be able to read/write to the bind-mounted directory on the external APFS volume, just as it would with a native volume or a bind mount on the internal drive.

Actual Behavior:
The container fails to initialize. Logs show errors like:

• Permission denied @ dir_s_mkdir - /var/opt/gitlab/...
• Unable to create directory: /var/opt/gitlab/...
• Files created in the bind mount are owned by root:root inside the container, even though the host directory is owned by the admin user.

Diagnostic Output:

# Host: Directory ownership is correct
ls -ld /Volumes/MacStorage/services/gitlab
# drwxr-xr-x  2 rdev  admin  64 Jun 25 10:00 /Volumes/MacStorage/services/gitlab

# Container: Shows ownership as root
sudo container exec gitlab-test ls -ld /var/opt/gitlab
# drwxr-xr-x  2 root root 64 Jun 25 14:00 /var/opt/gitlab

# Container: Cannot write to directory
sudo container exec gitlab-test touch /var/opt/gitlab/testfile
# touch: cannot touch '/var/opt/gitlab/testfile': Permission denied

Problem description

When attempting to run a container with its root filesystem or bind-mounted volumes located on an external APFS volume, the container fails to start or access files due to persistent permission and ownership errors. The issue occurs even when the external volume is formatted as APFS and has correct ownership at the macOS level. The container process inside the VM cannot properly read/write to the mounted path, often defaulting to root ownership (UID 0) which conflicts with the container's user namespace.

Additional Context:

• The issue persists regardless of the --user flag or chown commands inside the container.
• The same container configuration works when the bind mount is on the internal drive (/Users/Shared/...).
• The external volume is not using Time Machine or other special filesystem features.
• This blocks the ability to use external storage for container data, which is a common need for development and production environments.

Potential Root Cause:
The virtiofs mount between the macOS host and the Linux VM may not correctly propagate ownership/permissions from APFS volumes, or the container runtime may not properly map UIDs/GIDs when the source is on an external drive. This differs from native volumes which are managed by the container runtime and stored in a location it controls.

See also:
I found several related issues, but none that clearly and exactly match the problem:

Issue	Title	Relevance
#890	Add ability to use external storage (USB drives, SSDs) for container	Requests general external storage support, but doesn't report a specific failure or permission error.
#621	"container system start" hangs when app root is placed on an external drive	Reports a hang (not a permission error) when the application root is on an external drive, which is different from my scenario where the container's filesystem volume is on an external drive.
#15	Postgres container fails to initialize when bind-mounting data	Reports permission errors (UID/GID mismatch) with bind mounts, which is similar to my permission issues, but it's specific to Postgres and doesn't mention external drives.
#565	Cannot use a relative path as the source path of a bind mount	About path parsing, not external drive permissions.

---

note: GLM helped me to document the issue, and urged me to file it here when I asked for advice ("This issue is important because it affects the fundamental ability to use external storage with containers—a critical feature for many use cases. Filing it will help the Apple team understand and prioritize the problem."). chatGPT was used to systematize the demonstration locally.

Environment

- macOS: 26.5.1 BuildVersion: 25F80
- Apple Containers CLI: 1.0.0 (build: release, commit: ee848e3)
- Container Image: GitLab CE (gitlab/gitlab-ce)
- Storage: External APFS volume on /dev/disk6s1 mounted at /Volumes/MacStorage

Code of Conduct

• I agree to follow this project's Code of Conduct

[danielsyauqi]

The root:root ownership inside the container is expected here — it's coming from the external volume having "Ignore ownership on this volume" enabled (the default for non-boot APFS drives), not from a virtiofs/UID-mapping bug.

Note that the directory was created with sudo mkdir, so its real on-disk owner is root. With ignore-ownership on, the host ls masks that and displays it as your user (rdev:admin) — but virtiofs reads the real metadata and propagates uid 0 into the VM, which is what GitLab then can't write to. The internal-drive path (/Users/Shared) works because ownership is enabled there, so the real owner is preserved end-to-end.

To confirm and fix:

# Confirm ownership is disabled on the volume (likely "Owners: Disabled")
diskutil info /Volumes/MacStorage | grep -i owners

# Enable ownership so host metadata reflects reality
sudo diskutil enableOwnership /Volumes/MacStorage

# Set the real on-disk owner (don't rely on the masked display)
sudo chown -R "$(id -u):$(id -g)" /Volumes/MacStorage/services/gitlab

Also worth avoiding sudo mkdir (it creates root-owned dirs) and reconsidering whether sudo container is needed at all.

In short: virtiofs is faithfully surfacing the ownership that the host UI was hiding — there's no UID-mapping defect. This is macOS volume-ownership behavior rather than a container bug, though it might be worth a docs note or a warning when a bind-mount source lives on an ignore-ownership volume.

[robbiemu]

The root:root ownership inside the container is expected here — it's coming from the external volume having "Ignore ownership on this volume" enabled (the default for non-boot APFS drives), not from a virtiofs/UID-mapping bug.

Thank you. I had checked Sharing and permissions but apparently it doesn't always render there: since it also shows specific users (and we had configured these) I assumed this was disabled. Checking this way I see I had misdiagnosed it:

diskutil info /Volumes/MacStorage | grep -i owners
   Owners:                    Disabled

I believe this could be the issue (I will come back once more to verify after I'm done , possible reshaping my set up to use a real user instead of root), at least the basis for the solution is not just hypothesis.

[robbiemu]

Yes, thanks for the detailed explanation! That uncovered a real misconfiguration and the mechanics of how virtiofs surfaces that masked metadata make more sense to me now. But it does not resolve the issue.

To give a little context on why this is running in the root/system scope: GitLab is managed as a boot-time LaunchDaemon (/Library/LaunchDaemons/org.srvmini2.gitlab.plist). It needs to start before GUI login and survive user sessions. I previously tested running Apple Container under a dedicated gitlab macOS user, but that only worked while the user had an active Aqua/GUI session. After logout, the gui/507 bootstrap domain disappeared and the UserName=gitlab LaunchDaemon could not bootstrap or talk to container-apiserver, failing with an XPC connection error. So using sudo launchctl bsexec / /usr/local/bin/container ... is the service-management model for this unattended deployment, not an attempt to work around the MacStorage ownership issue.

Your ownership tip was spot on. I enabled ownership on the external volume and confirmed it:

sudo diskutil enableOwnership /Volumes/MacStorage
diskutil info /Volumes/MacStorage | grep -i owners
# Owners: Enabled

I set up an isolated path (/Volumes/MacStorage/services/gitlab-canary/data) and explicitly chowned it to my host user/group (502:20). At this point, the external APFS volume has ownership enabled, and the bind-mount source is a real directory owned by the expected user.

However, the container still fails before it even starts—so I never actually get to run the touch, chmod, or UID tests inside the VM. It fails during bootstrap with this error:

container run --rm \
  -v /Volumes/MacStorage/services/gitlab-canary/data:/var/opt/gitlab \
  docker.io/library/debian:bookworm-slim \
  sh -lc '...'

Error: failed to bootstrap container
VZErrorDomain Code=2 "A directory sharing device configuration is invalid."
NSPOSIXErrorDomain Code=1 "Operation not permitted"

This also happens if the user not only owns the folder but even the drive (via sudo chmod -a "remove allow list,search,readattr,readextattr,readsecurity" /Volumes/MacStorage, sudo chmod -a "remove allow list,search,readattr,readextattr,readsecurity" /Volumes/MacStorage/services).

So we have now ruled out:

• ignore-ownership masking
• target owned by root
• missing remove ACL on the drive root
• missing remove ACL on /Volumes/MacStorage/services
• file-vs-directory mistake
• in-container GitLab UID/GID permissions, because the container never starts

The failure is still at Apple Virtualization’s directory-sharing bootstrap layer.

So it looks like there were actually two layers here:

1. The masked ownership issue you identified (which was real, and is now fixed).
2. A second issue where Apple Virtualization still rejects the external APFS directory share during VM/container bootstrap.

For now, I’m keeping GitLab on native Apple Container volumes, since external APFS bind mounts still appear to be blocked at the Virtualization directory-sharing layer even with ownership enabled and the source directory correctly chowned.

Thanks again for pointing me in the right direction on the ownership piece!