Skip to content

feat(docker): bundle the Azure CLI so the Azure tool works in the image - #98

Open
bartsdev wants to merge 1 commit into
update-docker-imagefrom
feat/docker-azure-cli
Open

bartsdev wants to merge 1 commit into
update-docker-imagefrom
feat/docker-azure-cli

Conversation

@bartsdev

Copy link
Copy Markdown
Member

Stacked on #97. Retarget to main after #97 merges: the Docker workflow only runs on PRs into main.

Summary

The image ships the Azure CLI, so localstack-azure-client works from Docker instead of answering that az is missing.

Installing az isn't enough by itself. Inside the container, every *.localhost.localstack.cloud name resolves to 127.0.0.1, which is the container itself. The emulator gives each storage account its own host (<account>.blob.core.azure.localhost.localstack.cloud), and --add-host can't list arbitrary account names. So the server now forwards its loopback gateway port to LocalStack:

sequenceDiagram
    participant az as az (in MCP container)
    participant fwd as 127.0.0.1:4566 forwarder
    participant LS as LocalStack (host.docker.internal:4566)
    az->>fwd: TLS to acct.blob.core.azure.localhost.localstack.cloud
    fwd->>LS: raw TCP pipe (SNI and cert unchanged)
    LS-->>az: response
Loading
 src/cli/index.ts  (default: start server)
   exitWhenClientDisconnects()
+  forwardLoopbackGateway()   # only in a container (/.dockerenv) with a non-local LOCALSTACK_HOSTNAME
   require("./stdio.js")
 Dockerfile
+  apt: packages.microsoft.com/repos/azure-cli bookworm → azure-cli   (amd64 + arm64, 2.91.0)
+  az version   # build-time check
 tests/docker/validate-image.mjs
+  11. azure: start emulator → group create → storage account → container → blob upload → blob list
 docs
+  DOCKER.md "Azure CLI" section (mount files, LOCALSTACK_AZ_WORKDIR); drop the "No Azure CLI" limitation

Evidence

  • Before: the image has no az, so the Azure tool returns "az is not available" in Docker.
    After: 409/409 unit tests pass, including the new forwarder tests:
    loopbackForwardTarget
      ✓ forwards to the host gateway inside a container
      ✓ does nothing outside a container / when LocalStack is local / for an invalid port
    startLoopbackForwarder
      ✓ pipes loopback connections to the target and back
      ✓ gives up quietly when the port is taken
    
  • I ran the bundled forwarder with the container check faked: a request to 127.0.0.1 for a blob hostname reached a stub on another interface and returned its body ("ok").
  • Not run locally: the image build and the new azure harness scenario (no Docker daemon here). The Docker workflow's integration step runs the scenario once this PR targets main. It uses the same LOCALSTACK_AUTH_TOKEN as the Azure smoke workflow, which needs LocalStack for Azure. Without that license, the scenario reports a WARN instead of failing.

Merge Danger

Door: two-way

Blast Radius: Docker image

  • Image size: the Azure CLI adds about 600 MB installed.
  • Forwarder scope: it only runs inside a container with a non-local LOCALSTACK_HOSTNAME, and binds only 127.0.0.1:<LOCALSTACK_PORT>, where nothing listened before. npx and from-source runs are unaffected. A taken port (--network host) means no forwarding, and nothing crashes.
  • Integration test time: the Docker workflow now also starts the Azure emulator.

🤖 Generated with Claude Code

Install azure-cli from Microsoft's apt repo. Inside the container,
*.localhost.localstack.cloud names resolve to the container itself, and
--add-host cannot cover the emulator's per-account storage hosts, so the
server forwards 127.0.0.1:<LOCALSTACK_PORT> to LOCALSTACK_HOSTNAME when
it runs in a container with LocalStack elsewhere.

Document the Azure CLI in the image and add an Azure scenario to the
Docker validation harness (group, storage account, blob upload).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@bartsdev
bartsdev requested a review from a team November 13, 2026 10:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant