Skip to content

Commit fb5cdf7

Browse files
Tell Mac users which samples need Rosetta (#145)
Every code deployment is built with Microsoft's Oryx build image, which is published for amd64 only and is a .NET app, and .NET does not support QEMU. On a Mac with Apple silicon, Docker Desktop emulates amd64 with QEMU unless Rosetta is turned on, and the build can then crash, as reported in #143. - Add a note to the Prerequisites of the 22 sample READMEs whose deployment depends on amd64-only images: the code-deployed web apps (Oryx build and runtime images, and SQL Server for web-app-sql-database) and the Function Apps (Oryx build image). - Rewrite the architecture section of the top-level README: Docker Desktop uses Rosetta only when its setting is on, and QEMU otherwise; add the missing url-shortener and eventhubs-eventgrid rows; servicebus/java runs its Spring Boot app on the host and needs no amd64-only image. - run-samples.sh: correct the architecture comments the same way, and print a Rosetta note when it runs on a Mac with Apple silicon. Claude-Session: https://claude.ai/code/session_01NGfV8ZhpdZCZfbmfwWd3Sw Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
1 parent e194535 commit fb5cdf7

24 files changed

Lines changed: 171 additions & 25 deletions

File tree

‎README.md‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -83,21 +83,25 @@ container images Microsoft publishes for `amd64` alone, so there is no `arm64` i
8383

8484
| Sample | Native amd64 | Native arm64 | Backing image |
8585
| --- | :---: | :---: | --- |
86-
| `function-app-*` | ✅ | ✅ | built from a multi-arch `python` / `node` / `dotnet` base |
87-
| `api-management-function-app` | ✅ | ✅ | the API Management gateway runs inside the emulator; its Function App backend is built from the multi-arch `python` base |
86+
| `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 |
87+
| `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 |
88+
| `eventhubs-eventgrid` | ✅ | not in the arm64 CI | a Python Function App, like `function-app-*` |
8889
| `web-app-custom-image` | ✅ | ✅ | the image the sample builds itself |
8990
| `aci-blob-storage` | ✅ | ✅ | the image the sample builds itself |
9091
| `container-apps-blob-storage` | ✅ | ✅ | the image the sample builds itself |
91-
| `web-app-*` (code deployment) | ✅ | emulated | `mcr.microsoft.com/oryx/<platform>` |
92+
| `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 |
93+
| `web-app-*` (code deployment) | ✅ | emulated | the Oryx build image and `mcr.microsoft.com/oryx/<platform>` |
9294
| `eventhubs` | ✅ | emulated | deploys a dashboard web app (Oryx, as above) |
93-
| `servicebus/java` | ✅ | emulated | `mcr.microsoft.com/azure-app-service/java` |
94-
| `web-app-sql-database` | ✅ | emulated | `mcr.microsoft.com/mssql/server` |
95-
96-
**"emulated" does not mean broken.** The emulator never pins `--platform`, so on an `arm64` host
97-
Docker pulls the `amd64` image and runs it under whatever emulation the runtime provides. Docker
98-
Desktop on Apple Silicon does this via Rosetta, so these samples do work on a Mac — just more
99-
slowly. They fail only on an `arm64` host with no emulation registered, such as GitHub's
100-
`ubuntu-*-arm` runners, which is why CI schedules only the natively-supported samples on `arm64`.
95+
| `url-shortener` | ✅ | emulated | deploys a web app (Oryx, as above) and a Python Function App |
96+
| `web-app-sql-database` | ✅ | emulated | `mcr.microsoft.com/mssql/server`, and the Oryx images of its web app |
97+
98+
**"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`.
99+
100+
> [!NOTE]
101+
> **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.
102+
> 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)).
103+
> Microsoft [does not test or support SQL Server under emulation](https://learn.microsoft.com/azure/azure-sql/database/local-dev-experience-dev-containers) either.
104+
> The README of every sample that depends on these images says so in its Prerequisites.
101105
102106
`run-samples.sh` warns when it runs one of these on an `arm64` host; set `SKIP_AMD64_ONLY=1` to skip
103107
them instead. The authoritative list lives in `ARM64_SAMPLE_DIRS` in [run-samples.sh](./run-samples.sh);

‎run-samples.sh‎

Lines changed: 28 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -121,26 +121,35 @@ TOTAL=${#ALL_SAMPLES[@]}
121121

122122
# 1c. Architecture support
123123
# Samples listed here run *natively* on both amd64 and arm64 (Apple Silicon, arm64 CI
124-
# runners). For everything else, the container image the emulator starts is published by
125-
# Microsoft for amd64 alone — there is no arm64 manifest:
124+
# runners). For everything else, the emulator starts a container image Microsoft
125+
# publishes for amd64 alone, with no arm64 manifest:
126126
# - `az webapp create --runtime ...` (code deployment) runs the app on
127127
# mcr.microsoft.com/oryx/<platform>, which is amd64-only. That rules out every
128-
# web-app-* sample, plus eventhubs (it deploys a dashboard web app).
129-
# - Java App Service uses mcr.microsoft.com/azure-app-service/java — amd64-only.
130-
# - SQL Database is backed by mcr.microsoft.com/mssql/server — amd64-only.
131-
# The samples below avoid all of those: Function Apps get an image built from a
128+
# web-app-* sample, plus eventhubs (a dashboard web app) and url-shortener (a web app).
129+
# - SQL Database is backed by mcr.microsoft.com/mssql/server, amd64-only.
130+
# The samples below avoid all of those: Function Apps run on an image built from a
132131
# multi-arch base (arm64 support added in localstack-pro#8102), and the custom-image
133132
# Web App, ACI and Container Apps samples run an image the sample itself builds (the
134133
# Container Apps k3d runtime images, rancher/k3s and k3d-proxy, are multi-arch).
135134
# Their Cosmos DB, Service Bus, Storage and Front Door dependencies all publish
136-
# arm64 manifests.
135+
# arm64 manifests. Function Apps are still *built* with the amd64-only Oryx build image
136+
# (mcr.microsoft.com/oryx/build): where it cannot run, the emulator installs a Python
137+
# app's requirements.txt natively, and a .NET app starts from its published output.
138+
# eventhubs-eventgrid (a Python Function App) and servicebus/java (a Spring Boot app
139+
# run on the host with Maven, no App Service) need no amd64-only image either, but are
140+
# not listed yet, so CI does not run them on arm64.
137141
#
138-
# "amd64-only" means *not native* — not "cannot run". The emulator never pins
142+
# "amd64-only" means *not native*, not "cannot run". The emulator never pins
139143
# --platform, so on an arm64 host Docker pulls the amd64 manifest and runs it under
140-
# whatever emulation the runtime provides. Docker Desktop on Apple Silicon emulates it
141-
# via Rosetta, which is why these samples do work on a Mac, just more slowly. They fail
142-
# on an arm64 host with no emulation registered, such as GitHub's ubuntu-*-arm runners,
143-
# so CI schedules only the natively-supported samples below on arm64.
144+
# whatever emulation the runtime provides, and a sample works only as well as that
145+
# emulation runs it. Docker Desktop on Apple Silicon emulates amd64 with Rosetta when
146+
# "Use Rosetta for x86_64/amd64 emulation on Apple Silicon" is on (Apple Virtualization
147+
# framework only; Docker VMM has no Rosetta), and with QEMU otherwise. The Oryx build is
148+
# a .NET app, and .NET does not support QEMU (dotnet/core release-notes/8.0/
149+
# supported-os.md): under QEMU the build of a code deployment can crash
150+
# (localstack-azure-samples#143). Without any emulation registered, as on GitHub's
151+
# ubuntu-*-arm runners, an amd64-only image cannot start, so CI schedules only the
152+
# natively-supported samples below on arm64.
144153
#
145154
# LocalStack's own test suite draws the same line: after localstack-pro#8102, Web App
146155
# tests that only assert SCM/deployment records run on arm64, while the ones that
@@ -327,6 +336,11 @@ HOST_ARCH=$(host_arch)
327336
echo "Running samples shard $SHARD of $SPLITS (index $START, count $COUNT)"
328337
echo "Total samples (scripts + terraform + bicep): $TOTAL"
329338
echo "Host architecture: $HOST_ARCH"
339+
if [[ "$HOST_ARCH" == "arm64" && "$(uname -s)" == "Darwin" ]]; then
340+
echo "Note: on a Mac with Apple silicon, turn on Rosetta in Docker Desktop (Settings > General >"
341+
echo " 'Use Rosetta for x86_64/amd64 emulation on Apple Silicon'): every code deployment is"
342+
echo " built with Microsoft's amd64-only Oryx image, a .NET app that can crash under QEMU."
343+
fi
330344

331345
# 7. Run Samples — deploy each test, then run its validation if defined
332346
for (( i=START; i<START+COUNT; i++ )); do
@@ -337,8 +351,8 @@ for (( i=START; i<START+COUNT; i++ )); do
337351
echo "============================================================"
338352

339353
# Warn rather than skip: on an arm64 host these still run under amd64 emulation
340-
# (Rosetta on Docker Desktop), just slowly. Set SKIP_AMD64_ONLY=1 to skip them
341-
# instead — useful on an arm64 host with no emulation registered, where they would
354+
# (Rosetta or QEMU on Docker Desktop), just slowly. Set SKIP_AMD64_ONLY=1 to skip them
355+
# instead, useful on an arm64 host with no emulation registered, where they would
342356
# otherwise fail with an opaque error deep inside a deployment.
343357
if [[ "$HOST_ARCH" == "arm64" ]] && ! supports_arm64 "$path"; then
344358
if [[ "${SKIP_AMD64_ONLY:-0}" == "1" ]]; then

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -58,6 +58,11 @@ The life of a request: the client calls `GET /inventory/items` on the gateway wi
5858
- [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install) (for the Bicep deployment)
5959
- A LocalStack account with a valid `LOCALSTACK_AUTH_TOKEN` (see the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/))
6060

61+
> [!NOTE]
62+
> **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).
63+
> 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**.
64+
> 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).
65+
6166
## Setup
6267

6368
Start the LocalStack Azure emulator and route the Azure CLI to it:

‎samples/eventhubs-eventgrid/python/README.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -99,6 +99,11 @@ whatever happened to be in the last batch.
9999
> aborts and the trigger silently never fires. Starting the emulator with `DNS_ADDRESS=0`
100100
> sidesteps it.
101101
102+
> [!NOTE]
103+
> **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).
104+
> 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**.
105+
> 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).
106+
102107
## Usage
103108

104109
```bash

‎samples/eventhubs/python/README.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,12 @@ schema registry.
104104
- [Terraform](https://developer.hashicorp.com/terraform/downloads) or the Bicep CLI, for
105105
the alternative deployments
106106

107+
> [!NOTE]
108+
> **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).
109+
> 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**.
110+
> 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).
111+
> The sample does not run on an arm64 Linux host without amd64 emulation.
112+
107113
## Quick start
108114

109115
```bash

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,11 @@ The life of a request: the client calls `GET /catalog/1` on the endpoint → the
6969
- [jq](https://jqlang.org/) and `zip`
7070
- A LocalStack account with a valid `LOCALSTACK_AUTH_TOKEN` (see the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/))
7171

72+
> [!NOTE]
73+
> **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).
74+
> 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**.
75+
> 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).
76+
7277
## Setup
7378

7479
Start LocalStack for Azure and point the Azure CLI at it:

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

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,11 @@ The LocalStack emulator emulates the following services, which are necessary at
5050
- [Bicep extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep), if you plan to install the sample via Bicep.
5151
- [Terraform](https://developer.hashicorp.com/terraform/downloads), if you plan to install the sample via Terraform.
5252

53+
> [!NOTE]
54+
> **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).
55+
> 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**.
56+
> 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).
57+
5358
## Deployment
5459

5560
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‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,11 @@ The solution is composed of the following Azure resources:
5454
- [Bicep extension](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-bicep), if you plan to install the sample via Bicep.
5555
- [Terraform](https://developer.hashicorp.com/terraform/downloads), if you plan to install the sample via Terraform.
5656

57+
> [!NOTE]
58+
> **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).
59+
> 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**.
60+
> 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).
61+
5762
## Deployment
5863

5964
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‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,11 @@ The sample uses the following configurable settings in `local.settings.json`:
134134
- [jq](https://jqlang.org/) is a JSON processor for scripting.
135135
- [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.
136136

137+
> [!NOTE]
138+
> **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).
139+
> 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**.
140+
> 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).
141+
137142
## Deployment
138143

139144
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‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -85,6 +85,12 @@ The flow of a single link: `POST /shorten` → Table Storage + Key Vault + Servi
8585
- [Bicep](https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/install) (for the Bicep deployment)
8686
- A LocalStack account with a valid `LOCALSTACK_AUTH_TOKEN` (see the [Auth Token guide](https://docs.localstack.cloud/getting-started/auth-token/))
8787

88+
> [!NOTE]
89+
> **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).
90+
> 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**.
91+
> 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).
92+
> The sample does not run on an arm64 Linux host without amd64 emulation.
93+
8894
## Setup
8995

9096
Start the LocalStack Azure emulator and route the Azure CLI to it:

0 commit comments

Comments
 (0)