Tell Mac users which samples need Rosetta

README.md

@@ -83,21 +83,25 @@ container images Microsoft publishes for `amd64` alone, so there is no `arm64` i
 
 | Sample | Native amd64 | Native arm64 | Backing image |
 | --- | :---: | :---: | --- |
-| `function-app-*` | ✅ | ✅ | built from a multi-arch `python` / `node` / `dotnet` base |
-| `api-management-function-app` | ✅ | ✅ | the API Management gateway runs inside the emulator; its Function App backend is built from the multi-arch `python` base |
+| `function-app-*` | ✅ | ✅ | built from a multi-arch `python` / `node` / `dotnet` base; the build step runs on the `amd64`-only Oryx build image, and where it cannot run the emulator installs a Python app's dependencies natively |
+| `api-management-function-app` | ✅ | ✅ | the API Management gateway runs inside the emulator; its Function App backend is built from the multi-arch `python` base, with the same build step |
+| `eventhubs-eventgrid` | ✅ | not in the arm64 CI | a Python Function App, like `function-app-*` |
 | `web-app-custom-image` | ✅ | ✅ | the image the sample builds itself |
 | `aci-blob-storage` | ✅ | ✅ | the image the sample builds itself |
 | `container-apps-blob-storage` | ✅ | ✅ | the image the sample builds itself |
-| `web-app-*` (code deployment) | ✅ | emulated | `mcr.microsoft.com/oryx/<platform>` |
+| `servicebus/java` | ✅ | not in the arm64 CI | none: the Spring Boot app runs on your machine (`mvn spring-boot:run`) against the emulator's Service Bus |
+| `web-app-*` (code deployment) | ✅ | emulated | the Oryx build image and `mcr.microsoft.com/oryx/<platform>` |
 | `eventhubs` | ✅ | emulated | deploys a dashboard web app (Oryx, as above) |
-| `servicebus/java` | ✅ | emulated | `mcr.microsoft.com/azure-app-service/java` |
-| `web-app-sql-database` | ✅ | emulated | `mcr.microsoft.com/mssql/server` |
-
-**"emulated" does not mean broken.** The emulator never pins `--platform`, so on an `arm64` host
-Docker pulls the `amd64` image and runs it under whatever emulation the runtime provides. Docker
-Desktop on Apple Silicon does this via Rosetta, so these samples do work on a Mac — just more
-slowly. They fail only on an `arm64` host with no emulation registered, such as GitHub's
-`ubuntu-*-arm` runners, which is why CI schedules only the natively-supported samples on `arm64`.
+| `url-shortener` | ✅ | emulated | deploys a web app (Oryx, as above) and a Python Function App |
+| `web-app-sql-database` | ✅ | emulated | `mcr.microsoft.com/mssql/server`, and the Oryx images of its web app |
+
+**"emulated" means `amd64` emulation, and how well the samples run depends on the emulator.** The emulator never pins `--platform`, so on an `arm64` host Docker pulls the `amd64` image and runs it under whatever emulation the runtime provides. Where none is registered, such as GitHub's `ubuntu-*-arm` runners, the image cannot start at all, which is why CI schedules only the natively-supported samples on `arm64`.
+
+> [!NOTE]
+> **Macs with Apple silicon: turn on Rosetta.** Docker Desktop emulates `amd64` with Rosetta only when **Use Rosetta for x86_64/amd64 emulation on Apple Silicon** is on (Settings, **General**, with the **Apple Virtualization framework** as the Virtual Machine Manager; Docker VMM has no Rosetta), and with QEMU otherwise.
+> Every code deployment, Function Apps included, is built with Microsoft's Oryx build image, which is `amd64`-only ([microsoft/Oryx#2133](https://github.com/microsoft/Oryx/issues/2133) asks for `arm64`) and is a .NET app, and [.NET does not support QEMU](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md): under QEMU that build can crash ([#143](https://github.com/localstack/localstack-azure-samples/issues/143)).
+> Microsoft [does not test or support SQL Server under emulation](https://learn.microsoft.com/azure/azure-sql/database/local-dev-experience-dev-containers) either.
+> The README of every sample that depends on these images says so in its Prerequisites.
 
 `run-samples.sh` warns when it runs one of these on an `arm64` host; set `SKIP_AMD64_ONLY=1` to skip
 them instead. The authoritative list lives in `ARM64_SAMPLE_DIRS` in [run-samples.sh](./run-samples.sh);

run-samples.sh

@@ -121,26 +121,35 @@ TOTAL=${#ALL_SAMPLES[@]}
 
 # 1c. Architecture support
 # Samples listed here run *natively* on both amd64 and arm64 (Apple Silicon, arm64 CI
-# runners). For everything else, the container image the emulator starts is published by
-# Microsoft for amd64 alone — there is no arm64 manifest:
+# runners). For everything else, the emulator starts a container image Microsoft
+# publishes for amd64 alone, with no arm64 manifest:
 #   - `az webapp create --runtime ...` (code deployment) runs the app on
 #     mcr.microsoft.com/oryx/<platform>, which is amd64-only. That rules out every
-#     web-app-* sample, plus eventhubs (it deploys a dashboard web app).
-#   - Java App Service uses mcr.microsoft.com/azure-app-service/java — amd64-only.
-#   - SQL Database is backed by mcr.microsoft.com/mssql/server — amd64-only.
-# The samples below avoid all of those: Function Apps get an image built from a
+#     web-app-* sample, plus eventhubs (a dashboard web app) and url-shortener (a web app).
+#   - SQL Database is backed by mcr.microsoft.com/mssql/server, amd64-only.
+# The samples below avoid all of those: Function Apps run on an image built from a
 # multi-arch base (arm64 support added in localstack-pro#8102), and the custom-image
 # Web App, ACI and Container Apps samples run an image the sample itself builds (the
 # Container Apps k3d runtime images, rancher/k3s and k3d-proxy, are multi-arch).
 # Their Cosmos DB, Service Bus, Storage and Front Door dependencies all publish
-# arm64 manifests.
+# arm64 manifests. Function Apps are still *built* with the amd64-only Oryx build image
+# (mcr.microsoft.com/oryx/build): where it cannot run, the emulator installs a Python
+# app's requirements.txt natively, and a .NET app starts from its published output.
+# eventhubs-eventgrid (a Python Function App) and servicebus/java (a Spring Boot app
+# run on the host with Maven, no App Service) need no amd64-only image either, but are
+# not listed yet, so CI does not run them on arm64.
 #
-# "amd64-only" means *not native* — not "cannot run". The emulator never pins
+# "amd64-only" means *not native*, not "cannot run". The emulator never pins
 # --platform, so on an arm64 host Docker pulls the amd64 manifest and runs it under
-# whatever emulation the runtime provides. Docker Desktop on Apple Silicon emulates it
-# via Rosetta, which is why these samples do work on a Mac, just more slowly. They fail
-# on an arm64 host with no emulation registered, such as GitHub's ubuntu-*-arm runners,
-# so CI schedules only the natively-supported samples below on arm64.
+# whatever emulation the runtime provides, and a sample works only as well as that
+# emulation runs it. Docker Desktop on Apple Silicon emulates amd64 with Rosetta when
+# "Use Rosetta for x86_64/amd64 emulation on Apple Silicon" is on (Apple Virtualization
+# framework only; Docker VMM has no Rosetta), and with QEMU otherwise. The Oryx build is
+# a .NET app, and .NET does not support QEMU (dotnet/core release-notes/8.0/
+# supported-os.md): under QEMU the build of a code deployment can crash
+# (localstack-azure-samples#143). Without any emulation registered, as on GitHub's
+# ubuntu-*-arm runners, an amd64-only image cannot start, so CI schedules only the
+# natively-supported samples below on arm64.
 #
 # LocalStack's own test suite draws the same line: after localstack-pro#8102, Web App
 # tests that only assert SCM/deployment records run on arm64, while the ones that
@@ -327,6 +336,11 @@ HOST_ARCH=$(host_arch)
 echo "Running samples shard $SHARD of $SPLITS (index $START, count $COUNT)"
 echo "Total samples (scripts + terraform + bicep): $TOTAL"
 echo "Host architecture: $HOST_ARCH"
+if [[ "$HOST_ARCH" == "arm64" && "$(uname -s)" == "Darwin" ]]; then
+  echo "Note: on a Mac with Apple silicon, turn on Rosetta in Docker Desktop (Settings > General >"
+  echo "      'Use Rosetta for x86_64/amd64 emulation on Apple Silicon'): every code deployment is"
+  echo "      built with Microsoft's amd64-only Oryx image, a .NET app that can crash under QEMU."
+fi
 
 # 7. Run Samples — deploy each test, then run its validation if defined
 for (( i=START; i<START+COUNT; i++ )); do
@@ -337,8 +351,8 @@ for (( i=START; i<START+COUNT; i++ )); do
   echo "============================================================"
 
   # Warn rather than skip: on an arm64 host these still run under amd64 emulation
-  # (Rosetta on Docker Desktop), just slowly. Set SKIP_AMD64_ONLY=1 to skip them
-  # instead — useful on an arm64 host with no emulation registered, where they would
+  # (Rosetta or QEMU on Docker Desktop), just slowly. Set SKIP_AMD64_ONLY=1 to skip them
+  # instead, useful on an arm64 host with no emulation registered, where they would
   # otherwise fail with an opaque error deep inside a deployment.
   if [[ "$HOST_ARCH" == "arm64" ]] && ! supports_arm64 "$path"; then
     if [[ "${SKIP_AMD64_ONLY:-0}" == "1" ]]; then

samples/api-management-function-app/python/README.md

@@ -58,6 +58,11 @@ The life of a request: the client calls `GET /inventory/items` on the gateway wi
 - [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install) (for the Bicep deployment)
 - A LocalStack account with a valid `LOCALSTACK_AUTH_TOKEN` (see the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/))
 
+> [!NOTE]
+> **Macs with Apple silicon**: the function app runs natively on arm64, but the emulator builds each deployment with Microsoft's Oryx build image, which Microsoft publishes for amd64 only ([microsoft/Oryx#2133](https://github.com/microsoft/Oryx/issues/2133) asks for arm64).
+> Docker Desktop runs that build under amd64 emulation: in Docker Desktop's settings, under **General**, select the **Apple Virtualization framework** as the Virtual Machine Manager and turn on **Use Rosetta for x86_64/amd64 emulation on Apple Silicon**.
+> Under QEMU, which Docker Desktop uses otherwise (Rosetta off, or Docker VMM, which has no Rosetta), the build can crash, because Oryx is a .NET app and [.NET does not support QEMU](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md).
+
 ## Setup
 
 Start the LocalStack Azure emulator and route the Azure CLI to it:

samples/eventhubs-eventgrid/python/README.md

@@ -99,6 +99,11 @@ whatever happened to be in the last batch.
 > aborts and the trigger silently never fires. Starting the emulator with `DNS_ADDRESS=0`
 > sidesteps it.
 
+> [!NOTE]
+> **Macs with Apple silicon**: the function app runs natively on arm64, but the emulator builds each deployment with Microsoft's Oryx build image, which Microsoft publishes for amd64 only ([microsoft/Oryx#2133](https://github.com/microsoft/Oryx/issues/2133) asks for arm64).
+> Docker Desktop runs that build under amd64 emulation: in Docker Desktop's settings, under **General**, select the **Apple Virtualization framework** as the Virtual Machine Manager and turn on **Use Rosetta for x86_64/amd64 emulation on Apple Silicon**.
+> Under QEMU, which Docker Desktop uses otherwise (Rosetta off, or Docker VMM, which has no Rosetta), the build can crash, because Oryx is a .NET app and [.NET does not support QEMU](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md).
+
 ## Usage
 
 ```bash

samples/eventhubs/python/README.md

@@ -104,6 +104,12 @@ schema registry.
 - [Terraform](https://developer.hashicorp.com/terraform/downloads) or the Bicep CLI, for
   the alternative deployments
 
+> [!NOTE]
+> **Macs with Apple silicon**: this sample's dashboard is a web app deployed from code. The emulator builds it with Microsoft's Oryx build image and runs it on an Oryx runtime image, and Microsoft publishes both for amd64 only ([microsoft/Oryx#2133](https://github.com/microsoft/Oryx/issues/2133) asks for arm64).
+> On a Mac with Apple silicon they run only under Docker Desktop's amd64 emulation: in Docker Desktop's settings, under **General**, select the **Apple Virtualization framework** as the Virtual Machine Manager and turn on **Use Rosetta for x86_64/amd64 emulation on Apple Silicon**.
+> Under QEMU, which Docker Desktop uses otherwise (Rosetta off, or Docker VMM, which has no Rosetta), the sample is not expected to work: Oryx is a .NET app, and [.NET does not support QEMU](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md).
+> The sample does not run on an arm64 Linux host without amd64 emulation.
+
 ## Quick start
 
 ```bash

samples/function-app-front-door/python/README.md

@@ -69,6 +69,11 @@ The life of a request: the client calls `GET /catalog/1` on the endpoint → the
 - [jq](https://jqlang.org/) and `zip`
 - A LocalStack account with a valid `LOCALSTACK_AUTH_TOKEN` (see the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/))
 
+> [!NOTE]
+> **Macs with Apple silicon**: the function app runs natively on arm64, but the emulator builds each deployment with Microsoft's Oryx build image, which Microsoft publishes for amd64 only ([microsoft/Oryx#2133](https://github.com/microsoft/Oryx/issues/2133) asks for arm64).
+> Docker Desktop runs that build under amd64 emulation: in Docker Desktop's settings, under **General**, select the **Apple Virtualization framework** as the Virtual Machine Manager and turn on **Use Rosetta for x86_64/amd64 emulation on Apple Silicon**.
+> Under QEMU, which Docker Desktop uses otherwise (Rosetta off, or Docker VMM, which has no Rosetta), the build can crash, because Oryx is a .NET app and [.NET does not support QEMU](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md).
+
 ## Setup
 
 Start LocalStack for Azure and point the Azure CLI at it:

samples/function-app-managed-identity/python/README.md

@@ -50,6 +50,11 @@ The LocalStack emulator emulates the following services, which are necessary at
 - [Bicep extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep), if you plan to install the sample via Bicep.
 - [Terraform](https://developer.hashicorp.com/terraform/downloads), if you plan to install the sample via Terraform.
 
+> [!NOTE]
+> **Macs with Apple silicon**: the function app runs natively on arm64, but the emulator builds each deployment with Microsoft's Oryx build image, which Microsoft publishes for amd64 only ([microsoft/Oryx#2133](https://github.com/microsoft/Oryx/issues/2133) asks for arm64).
+> Docker Desktop runs that build under amd64 emulation: in Docker Desktop's settings, under **General**, select the **Apple Virtualization framework** as the Virtual Machine Manager and turn on **Use Rosetta for x86_64/amd64 emulation on Apple Silicon**.
+> Under QEMU, which Docker Desktop uses otherwise (Rosetta off, or Docker VMM, which has no Rosetta), the build can crash, because Oryx is a .NET app and [.NET does not support QEMU](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md).
+
 ## Deployment
 
 Set up the Azure emulator using the LocalStack for Azure Docker image. Before starting, ensure you have a valid `LOCALSTACK_AUTH_TOKEN` to access the Azure emulator. Refer to the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/) to obtain your Auth Token and set it in the `LOCALSTACK_AUTH_TOKEN` environment variable. The Azure Docker image is available on the [LocalStack Docker Hub](https://hub.docker.com/r/localstack/localstack-azure). To pull the image, execute:

samples/function-app-service-bus/dotnet/README.md

@@ -54,6 +54,11 @@ The solution is composed of the following Azure resources:
 - [Bicep extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep), if you plan to install the sample via Bicep.
 - [Terraform](https://developer.hashicorp.com/terraform/downloads), if you plan to install the sample via Terraform.
 
+> [!NOTE]
+> **Macs with Apple silicon**: the function app runs natively on arm64, but the emulator builds each deployment with Microsoft's Oryx build image, which Microsoft publishes for amd64 only ([microsoft/Oryx#2133](https://github.com/microsoft/Oryx/issues/2133) asks for arm64).
+> Docker Desktop runs that build under amd64 emulation: in Docker Desktop's settings, under **General**, select the **Apple Virtualization framework** as the Virtual Machine Manager and turn on **Use Rosetta for x86_64/amd64 emulation on Apple Silicon**.
+> Under QEMU, which Docker Desktop uses otherwise (Rosetta off, or Docker VMM, which has no Rosetta), the build can crash, because Oryx is a .NET app and [.NET does not support QEMU](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md).
+
 ## Deployment
 
 Set up the Azure emulator using the LocalStack for Azure Docker image. Before starting, ensure you have a valid `LOCALSTACK_AUTH_TOKEN` to access the Azure emulator. Refer to the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/) to obtain your Auth Token and set it in the `LOCALSTACK_AUTH_TOKEN` environment variable. The Azure Docker image is available on the [LocalStack Docker Hub](https://hub.docker.com/r/localstack/localstack-azure). To pull the image, execute:

samples/function-app-storage-http/dotnet/README.md

@@ -134,6 +134,11 @@ The sample uses the following configurable settings in `local.settings.json`:
 - [jq](https://jqlang.org/) is a JSON processor for scripting.
 - [Azure Storage Explorer](https://learn.microsoft.com/en-us/azure/storage/storage-explorer/vs-azure-tools-storage-manage-with-storage-explorer) for viewing storage contents.
 
+> [!NOTE]
+> **Macs with Apple silicon**: the function app runs natively on arm64, but the emulator builds each deployment with Microsoft's Oryx build image, which Microsoft publishes for amd64 only ([microsoft/Oryx#2133](https://github.com/microsoft/Oryx/issues/2133) asks for arm64).
+> Docker Desktop runs that build under amd64 emulation: in Docker Desktop's settings, under **General**, select the **Apple Virtualization framework** as the Virtual Machine Manager and turn on **Use Rosetta for x86_64/amd64 emulation on Apple Silicon**.
+> Under QEMU, which Docker Desktop uses otherwise (Rosetta off, or Docker VMM, which has no Rosetta), the build can crash, because Oryx is a .NET app and [.NET does not support QEMU](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md).
+
 ## Deployment
 
 1. You can set up the Azure emulator by utilizing LocalStack for Azure Docker image. Before starting, ensure you have a valid `LOCALSTACK_AUTH_TOKEN` to access the Azure emulator. Refer to the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/) to obtain your Auth Token and specify it in the `LOCALSTACK_AUTH_TOKEN` environment variable. The Azure Docker image is available on the [LocalStack Docker Hub](https://hub.docker.com/r/localstack/localstack-azure). To pull the Azure Docker image, execute the following command:

samples/url-shortener/python/README.md

@@ -85,6 +85,12 @@ The flow of a single link: `POST /shorten` → Table Storage + Key Vault + Servi
 - [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install) (for the Bicep deployment)
 - A LocalStack account with a valid `LOCALSTACK_AUTH_TOKEN` (see the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/))
 
+> [!NOTE]
+> **Macs with Apple silicon**: this sample's web app is deployed from code. The emulator builds it with Microsoft's Oryx build image and runs it on an Oryx runtime image, and Microsoft publishes both for amd64 only ([microsoft/Oryx#2133](https://github.com/microsoft/Oryx/issues/2133) asks for arm64).
+> On a Mac with Apple silicon they run only under Docker Desktop's amd64 emulation: in Docker Desktop's settings, under **General**, select the **Apple Virtualization framework** as the Virtual Machine Manager and turn on **Use Rosetta for x86_64/amd64 emulation on Apple Silicon**.
+> Under QEMU, which Docker Desktop uses otherwise (Rosetta off, or Docker VMM, which has no Rosetta), the sample is not expected to work: Oryx is a .NET app, and [.NET does not support QEMU](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md).
+> The sample does not run on an arm64 Linux host without amd64 emulation.
+
 ## Setup
 
 Start the LocalStack Azure emulator and route the Azure CLI to it: