apple / apple/container

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

Open
#1,830 5 comments 0 reactions 0 assignees View on GitHub
Dominant language
Swift
Stars
49.9k
Forks
1.8k
Avg merge
1d 20h
Merged PRs (30d)
22

Description

### I have done the following

- [x] I have searched the existing issues
- [x] 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:
```bash
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:
```bash
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:**
```bash
# 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](https://github.com/apple/container/issues/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](https://github.com/apple/container/issues/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](https://github.com/apple/container/issues/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](https://github.com/apple/container/issues/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

```markdown
- 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

- [x] I agree to follow this project's Code of Conduct

Contributor guide

Open the contributing guide

Research direction

Reproduce the provided container run on the listed macOS and external APFS setup, then inspect its logs, container exec output, and host directory ownership. Trace the bind mount through the macOS-to-Linux VM path; done means the GitLab container initializes and can read and write the mounted directory without the reported permission or ownership errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
macos, swift
Domain
infrastructure, operating-systems
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.