Replace the deprecated localstack CLI with lstk in Samples CI and the sample guides

[paolosalvatori]

Motivation

Samples CI starts the emulator, waits for it and reads its logs with the localstack CLI, which is deprecated and no longer receives updates: every job prints WARNING: The 'localstack' CLI is deprecated. Use the 'lstk' CLI instead. The workflow already installs lstk, but only for lstk az start-interception. The sample READMEs and docs/LOCALSTACK.md start the emulator with the same CLI (IMAGE_NAME=localstack/localstack-azure localstack start -d, then localstack wait), while 45 of them list only lstk among their prerequisites, so a reader who follows them has no localstack command.

The last run on main (38376597563) shows three more problems, which this PR also fixes:

• False readiness timeouts. Five jobs logged Emulator was not ready within 400s and started a new emulator, although each emulator had been ready about ten seconds after it started. localstack wait waits for a log line reading exactly Ready., and the emulator prints that marker in two writes (print(constants.READY_MARKER_OUTPUT, flush=True) in localstack-pro's localstack-core/localstack/runtime/runtime.py) while the Azurite container of its managed storage account logs from another thread, so a line can land between them: Ready.2026-10-13T09:30:02.013 DEBUG --- [ Thread-4] .... All 27 timeouts in five full runs between 2026-09-18 and 2026-10-13 (23 jobs) were this. A longer timeout would only make each one longer. lstk polls /_localstack/health and never reads the marker.
• url-shortener/python/terraform fails with 409 PublicAccessNotPermitted when it creates its qrcodes container. The container is publicly readable (container_access_type = "blob"), but azurerm 5.x creates storage accounts with allow_nested_items_to_be_public = false unless told otherwise (provider source), and "If anonymous access is denied for the storage account, you can't configure anonymous access for a container" (Configure anonymous read access for containers and blobs). The emulator enforces this since localstack-pro#9198 (2026-10-07): the sample passed in the last full run before it and failed in the first one after. The Azure CLI and Bicep variants of the sample already allow public blob access on the account.
• The retry of a failed Terraform sample cannot succeed. The failed attempt leaves its Terraform state behind, and the retry runs on a fresh emulator, so terraform plan first refreshes resources that no longer exist. A storage table cannot find its account, and the url-shortener retry failed with 404 ResourceNotFound before deploying anything.

Fixes SMF-939

Changes

• lstk instead of the localstack CLI. The Start, Retry and Get LocalStack Logs steps of run-samples.yml run lstk start, lstk stop and lstk logs instead of python -m localstack_cli.cli.main and localstack logs, and the emulator container is now localstack-azure. run-samples.sh starts the emulator with lstk start, which returns at once in CI where the workflow has already started it, and no longer requires the localstack CLI. make logs runs lstk logs --verbose, and the localstack package leaves requirements-runtime.txt and pyproject.toml.
• Guides. The sample READMEs and docs/LOCALSTACK.md start the emulator with lstk start --type azure, which returns once the emulator is ready, instead of localstack start and localstack wait. Where a prerequisites list named LocalStack, it now names the lstk CLI. docs/LOCALSTACK.md stops the emulator with lstk stop and reads its logs with lstk logs. No file in the repository runs the old CLI any more.
• lstk version. lstk is installed before the emulator starts and moves from 0.19.0 to 1.4.0. The 0.19.0 pin avoided a 0.20.0 regression in which lstk picked the socket of a co-installed Podman instead of Docker's and reported the running emulator as absent; 0.20.1 fixed it (localstack/lstk#422). DOCKER_HOST now names the Docker daemon for every lstk call in the job.
• Emulator settings. The variables in DOCKER_FLAGS and the bare LS_LOG, DISABLE_EVENTS and DNS_ADDRESS become LOCALSTACK_-prefixed variables, which lstk forwards to the container and the image's entrypoint strips. ACTIVATE_PRO goes: nothing in the image reads it.
• Emulator logs. The container removes itself, logs included, when it exits, so the Start and Retry steps keep a copy of every emulator's logs, and Get LocalStack Logs prints it. A retried job now shows the emulator that failed as well as the one that ran the retry.
• Retry. run-samples.sh removes a Terraform sample's terraform.tfstate, its backup and tfplan before deploying it.
• url-shortener/python/terraform. The storage account sets allow_nested_items_to_be_public from a new storage_allow_nested_items_to_be_public variable that defaults to true.
• .claude/settings.json is removed: it held one developer's local Claude Code permissions, with absolute paths to a local checkout.

Tests

Each changed step of run-samples.yml replayed locally from the workflow file (the step's run: block with its env:, a fresh HOME, lstk 1.4.0, localstack/localstack-azure:latest of 2026-10-13):

• url-shortener/python/scripts: Start, Run and Retry pass, and the emulator reports ready within seconds.
• A well-formed auth token that the license server does not know: each attempt of the Start step stops with License activation failed! and the license server's reason (exit code 55), instead of Error: timeout.
• url-shortener/python/terraform: before the fixes, the first attempt reproduces the 409 PublicAccessNotPermitted; with only the sample fix, the retry over the leftover state reproduces the 404 ResourceNotFound; with both, the retry deploys from scratch (27 resources) and validate.sh passes. The committed workflow then passes Start, Run, Retry and Get LocalStack Logs, which prints the logs of both emulators.
• The new Setup block of samples/url-shortener/python/README.md, run in a terminal on a machine with no lstk configuration: lstk start --type azure returns once the emulator is running, az group create reaches the emulator after lstk az start-interception, and lstk stop stops it.
• actionlint, zizmor and gitleaks pass.

The CI of this PR runs all 91 jobs, and is the first time lstk starts the emulator on the arm64 runners.

Related

• Samples CI run 38376597563
• localstack-pro#9198
• localstack/lstk#422

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

Sample documentation still instructs users to run the removed localstack CLI.

1 open finding

• Update sample setup commands after removing localstack dependency · New

What changed in this PR

Migrates sample CI from the deprecated localstack CLI to lstk, improves retries and logging, and fixes public blob access.

Changes:

• Uses lstk for emulator lifecycle and diagnostics.
• Resets Terraform state before retries.
• Enables public QR-code blob access.

File	Description
.github/​workflows/​run-samples.yml	Migrates CI emulator management to lstk.
.claude/​settings.json	Removes developer-local settings.
Makefile	Uses lstk for logs.
requirements-runtime.txt	Removes the deprecated CLI dependency.
run-samples.sh	Starts with lstk and resets Terraform state.
samples/​url-shortener/​python/​terraform/​main.tf	Enables configurable public blob access.
samples/​url-shortener/​python/​terraform/​variables.tf	Defines the public-access setting.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.