DOC-419/DOC-420: Document SIGILL crash on Apple Silicon and the supervisor's new fatal-signal diagnostics

src/content/docs/aws/customization/advanced/arm64-support.md

@@ -79,6 +79,11 @@ docker run --privileged --rm tonistiigi/binfmt --install amd64
 
 ## Troubleshooting
 
+### Container exits with SIGILL on Apple Silicon
+
+On newer Apple Silicon hardware (for example Apple M4), running under Colima or Podman with an older Linux guest kernel can cause the container to crash immediately after license activation with exit code `252` (SIGILL).
+See [Why does the LocalStack container exit immediately with SIGILL (exit code 252) on Apple Silicon?](/aws/getting-started/faq/#why-does-the-localstack-container-exit-immediately-with-sigill-exit-code-252-on-apple-silicon) for the workaround and permanent fix.
+
 ### Pulling images for other architectures
 
 :::note

src/content/docs/aws/getting-started/faq.mdx

@@ -631,6 +631,40 @@ lsof -i :443
 netstat -anv | grep 443
 ```
 
+### Why does the LocalStack container exit immediately with SIGILL (exit code 252) on Apple Silicon?
+
+On newer Apple Silicon hardware (for example Apple M4), the container can crash immediately after license activation with exit code `252` (SIGILL, illegal instruction, reported as `-4` by some supervisors).
+This is a known incompatibility between the `cryptography` library (version 47.0.0 and newer) and older Linux guest kernels running under Apple's Virtualization Framework: the library tries to use ARM CPU instructions the kernel does not fully support.
+It mainly affects Colima or Podman with an older guest kernel (for example `6.8.0-39`); a fully updated Docker Desktop is generally not affected.
+
+The supervisor decodes and logs a fatal signal like this unconditionally, without needing `DEBUG=1`:
+
+```text
+localstack process (PID 24) was terminated by signal 4 (SIGILL) (exit code 252). If there is no traceback above, the crash happened in native code, ...
+```
+
+It also enables Python's `faulthandler` in the `localstack` process by default (`PYTHONFAULTHANDLER=1`), so a native crash such as this one prints a Python and C stack trace before the process dies, for example pointing directly at the `cryptography` import.
+Set `PYTHONFAULTHANDLER=0` yourself if you need to opt out.
+Exit-code semantics are unchanged, the container still exits with the crashed process's status.
+
+**Workaround:** disable the faulty ARM capability detection by setting `OPENSSL_armcap=0` on the container:
+
+```yaml
+services:
+  localstack:
+    image: localstack/localstack-pro:latest
+    environment:
+      - OPENSSL_armcap=0
+```
+
+With `lstk`, set it as a `LOCALSTACK_`-prefixed host variable so `lstk start` forwards it into the container:
+
+```bash
+LOCALSTACK_OPENSSL_armcap=0 lstk start
+```
+
+**Permanent fix:** update your VM provider (for example Colima) or its underlying Linux guest kernel to a newer version (for example `7.0.0`, or a patched `6.8.0`).
+
 ### Why do I see a warning about non-prefixed `REQUESTS_CA_BUNDLE` being forwarded?
 
 The CLI prints `Non-prefixed environment variable REQUESTS_CA_BUNDLE is forwarded…` when it auto-forwards a host environment variable into the container.