add docs/multi-arch.md

Signed-off-by: Akihiro Suda <[email protected]>

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).

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