diff --git a/README.md b/README.md index f66ea04bcc6..b1cc516e9fb 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,11 @@ Lima is expected to be used on macOS hosts, but can be used on Linux hosts as we ✅ Intel on Intel -✅ ARM on Intel +✅ [ARM on Intel](./docs/multi-arch.md) ✅ ARM on ARM -✅ Intel on ARM +✅ [Intel on ARM](./docs/multi-arch.md) ✅ Various guest Linux distributions: [Alpine](./examples/alpine.yaml), [Arch Linux](./examples/archlinux.yaml), [CentOS](./examples/centos.yaml), [Debian](./examples/debian.yaml), [Fedora](./examples/fedora.yaml), [openSUSE](./examples/opensuse.yaml), [Ubuntu](./examples/ubuntu.yaml) (default), ... @@ -58,6 +58,8 @@ $ LIMA_INSTANCE=arm lima uname -a Linux lima-arm 5.11.0-16-generic #17-Ubuntu SMP Wed Apr 14 20:10:16 UTC 2021 aarch64 aarch64 aarch64 GNU/Linux ``` +See [`./docs/multi-arch.md`](./docs/multi-arch.md) for Intel-on-ARM and ARM-on-Intel . + ### Sharing files across macOS and Linux ```console $ echo "files under /Users on macOS filesystem are readable from Linux" > some-file @@ -318,7 +320,7 @@ Note: **Only** on macOS versions **before** 10.15.7 you might need to add this e #### "QEMU is slow" - Make sure that HVF is enabled with `com.apple.security.hypervisor` entitlement. See ["QEMU crashes with `HV_ERROR`"](#qemu-crashes-with-hv_error). -- Emulating non-native machines (ARM-on-Intel, Intel-on-ARM) is slow by design. +- Emulating non-native machines (ARM-on-Intel, Intel-on-ARM) is slow by design. See [`docs/multi-arch.md`](./docs/multi-arch.md) for a workaround. #### error "killed -9" - make sure qemu is codesigned, See ["QEMU crashes with `HV_ERROR`"](#qemu-crashes-with-hv_error). diff --git a/docs/multi-arch.md b/docs/multi-arch.md new file mode 100644 index 00000000000..a351c0ef9aa --- /dev/null +++ b/docs/multi-arch.md @@ -0,0 +1,61 @@ +# Intel-on-ARM and ARM-on-Intel + +Lima supports two modes for running Intel-on-ARM and ARM-on-Intel: +- [Slow mode](#slow-mode) +- [Fast mode](#fast-mode) + +## [Slow mode: Intel VM on ARM Host / ARM VM on Intel Host](#slow-mode) + +Lima can run a VM with a foreign architecture, just by specifying `arch` in the YAML. + +```yaml +arch: "x86_64" +# arch: "aarch64" + +images: + - location: "https://cloud-images.ubuntu.com/impish/current/impish-server-cloudimg-amd64.img" + arch: "x86_64" + - location: "https://cloud-images.ubuntu.com/impish/current/impish-server-cloudimg-arm64.img" + arch: "aarch64" + +# Disable mounts and containerd, otherwise booting up may timeout if the host is slow +mounts: [] +containerd: + system: false + user: false +``` + +Running a VM with a foreign architecture is extremely slow. +Consider using [Fast mode](#fast-mode) whenever possible. + +## [Fast mode: Intel containers on ARM VM on ARM Host / ARM containers on Intel VM on Intel Host](#fast-mode) + +This mode is significantly faster but often sacrifies compatibility. + +Fast mode requires Lima v0.7.3 (nerdctl v0.13.0) or later. + +If your VM was created with Lima prior to v0.7.3, you have to recreate the VM with Lima >= 0.7.3, +or upgrade `/usr/local/bin/nerdctl` binary in the VM to [>= 0.13.0](https://github.com/containerd/nerdctl/releases) manually. + +Set up: +```bash +lima sudo systemctl start containerd +lima sudo nerdctl run --privileged --rm tonistiigi/binfmt --install all +``` + +Run containers: +```console +$ lima nerdctl run --platform=amd64 --rm alpine uname -m +x86_64 + +$ lima nerdctl run --platform=arm64 --rm alpine uname -m +aarch64 +``` + +Build and push container images: +```console +$ lima nerdctl build --platform=amd64,arm64 -t example.com/foo:latest . +$ lima nerdctl push --all-platforms example.com/foo:latest +``` + +See also https://github.com/containerd/nerdctl/blob/master/docs/multi-platform.md