apple / apple/container

[Request]: Support building for exotic architectures (ppc64le, s390x, riscv64) via QEMU emulation in the build VM

Open
#1,496 0 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

### Feature or enhancement request details

`container build --platform linux/` works for `linux/arm64` (native) and `linux/amd64` (via Rosetta — as reflected in `build.rosetta` system property). However, building images that require `RUN` instructions for other architectures fails with `Exec format error`:

```console
% container build --platform linux/ppc64le -t myimage:ppc64le .
#4 [linux/ppc64le 1/2] RUN echo "arch: $(uname -m)" > /arch.txt
#4 ERROR: failed to unmount ...: operation not permitted: failed to mount ...: mount source: "/var/lib/buildkit/runc-native/snapshots/...", fstype: bind, flags: 20480, err: operation not permitted
Error: failed to solve: Build failed with exit code 1
```

Dockerfiles that contain only `FROM` + `COPY` + `CMD` (no `RUN`) do work, because those just repackage existing layers from the multi-arch base image. The failure occurs when any `RUN` instruction must execute a foreign-arch binary.

**Verified failing architectures**: `linux/ppc64le`, `linux/s390x`, `linux/riscv64` (see also #809, which covers `riscv64` for `container run`).

### macOS container tooling landscape

This gap affects the broader macOS container ecosystem, not just `container`. For context:

| Tool | `linux/arm64` | `linux/amd64` | `linux/ppc64le` / `linux/s390x` |
|------|:---:|:---:|:---:|
| `container build` (this project) | ✅ native | ✅ Rosetta | ❌ Exec format error |
| `podman build` via Podman machine | ✅ native | ✅ QEMU | ✅ QEMU (Fedora CoreOS VM has `qemu-user-static`) |
| Docker Desktop | ✅ native | ✅ Rosetta | ✅ QEMU |

Podman machine on macOS runs a Fedora CoreOS QEMU VM which ships `qemu-user-static` binfmt handlers — this is why `podman build --platform linux/ppc64le` with `RUN` steps works on macOS today, at the cost of a persistent shared QEMU VM. `container` and Docker Desktop (via Rosetta for amd64) both take a lighter-weight approach that doesn't currently extend to exotic architectures.

### Why this matters

IBM Power (ppc64le) and IBM Z (s390x) are major enterprise Linux targets. Many open-source projects — including OpenShift, Kubernetes operators, and Red Hat middleware — require multi-arch images that include these platforms. Developers on Apple Silicon currently have no path to build images with `RUN` steps for these architectures using `container` without a remote Linux builder.

### Proposed solution

Add QEMU user-mode static emulation support inside the BuildKit builder VM. This is how Docker Desktop and standard Linux CI (via `tonistiigi/binfmt`) handles cross-arch `RUN` steps:

1. Register `qemu-*-static` binfmt handlers inside the build VM at builder startup
2. Make this opt-in via a new system property (e.g. `build.qemu Bool false Enable QEMU user-mode emulation for exotic-arch RUN steps`) similar to how `build.rosetta` toggles Rosetta for amd64

Precedent: `build.rosetta` already shows the pattern of toggling arch-specific emulation strategies.

### Current workarounds

- **Remote builder**: `docker buildx create --driver docker-container --platform linux/ppc64le ssh://user@linux-box` — requires a separate Linux machine with QEMU binfmt configured
- **Podman machine**: `podman build --platform linux/ppc64le` works today via the Fedora CoreOS QEMU VM — at the cost of a persistent shared VM
- **GitHub Actions**: `docker/setup-qemu-action` on Ubuntu runners — zero-infrastructure path for CI
- **IBM Cloud**: Real Power/Z VSIs for production builds

### Environment

- macOS 26.0, Apple Silicon (M-series)
- `container` CLI (current)

Related: #809 (riscv64 `Exec format error` on `run`, closed), #913 (multi-platform semantics umbrella)

> [!Note]
> Responses generated with Claude

Contributor guide

Open the contributing guide

Research direction

Start at the `container build --platform` entry point and trace the existing `build.rosetta` system property through BuildKit builder VM startup. Determine where opt-in QEMU user-mode handlers would be registered, then verify that `RUN` steps work for ppc64le, s390x, and riscv64 while existing native and Rosetta builds remain unchanged.

Written by the indexing model from the issue text.

Assessment

Tech stack
linux, swift
Domain
build-system, cli, infrastructure
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.