From 63ca2aace1f4c4de343a43eaeeb255c065a47036 Mon Sep 17 00:00:00 2001 From: Bart Date: Fri, 30 Oct 2026 10:13:08 +0100 Subject: [PATCH] feat(docker): bundle the Azure CLI so the Azure tool works in the image 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: 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 --- .github/workflows/docker.yml | 2 +- Dockerfile | 8 ++- README.md | 4 +- docs/AZURE.md | 2 +- docs/DOCKER.md | 25 +++++++--- src/cli/index.ts | 2 + src/cli/loopback-forward.test.ts | 86 ++++++++++++++++++++++++++++++++ src/cli/loopback-forward.ts | 55 ++++++++++++++++++++ tests/docker/validate-image.mjs | 53 ++++++++++++++++++++ 9 files changed, 226 insertions(+), 11 deletions(-) create mode 100644 src/cli/loopback-forward.test.ts create mode 100644 src/cli/loopback-forward.ts diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index ba07b96..d50536b 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -46,7 +46,7 @@ jobs: - name: Smoke test MCP startup env: - HARNESS_SKIP: prompt,docs,status,start,aws,logs,state,cloudpods,appinspector,chaos,iam,replicator,ephemeral,deploy,deploy-cdk,extensions,restart,stop,snowflake + HARNESS_SKIP: prompt,docs,status,start,aws,logs,state,cloudpods,appinspector,chaos,iam,replicator,ephemeral,deploy,deploy-cdk,extensions,restart,stop,snowflake,azure run: | node tests/docker/validate-image.mjs -- \ docker run -i --rm \ diff --git a/Dockerfile b/Dockerfile index 8210e86..2e42c86 100644 --- a/Dockerfile +++ b/Dockerfile @@ -23,8 +23,13 @@ RUN set -eux; \ chmod a+r /usr/share/keyrings/hashicorp-archive-keyring.gpg; \ echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com bookworm main" \ > /etc/apt/sources.list.d/hashicorp.list; \ + curl -fsSL https://packages.microsoft.com/keys/microsoft.asc \ + | gpg --dearmor -o /usr/share/keyrings/microsoft.gpg; \ + chmod a+r /usr/share/keyrings/microsoft.gpg; \ + echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/microsoft.gpg] https://packages.microsoft.com/repos/azure-cli/ bookworm main" \ + > /etc/apt/sources.list.d/azure-cli.list; \ apt-get update; \ - apt-get install -y --no-install-recommends terraform; \ + apt-get install -y --no-install-recommends terraform azure-cli; \ apt-get clean; \ rm -rf /var/lib/apt/lists/* @@ -57,6 +62,7 @@ RUN set -eux; \ terraform version; \ sam --version; \ cdk --version; \ + az version; \ snow --version; \ node dist/cli.js version; \ node -e "require('dockerode'); console.log('dockerode ok')" diff --git a/README.md b/README.md index 4ab0b40..dd77683 100644 --- a/README.md +++ b/README.md @@ -170,7 +170,7 @@ If you installed from source, change `command` and `args` to point to your local ### Run with Docker -The `localstack/localstack-mcp-server` Docker image bundles `lstk` with Terraform, CDK, and SAM, and the Snowflake CLI. The only required host dependency is Docker. The container uses the mounted Docker socket to run LocalStack as a sibling container on the host; state lives in a named Docker volume (`localstack-mcp`) unless `LOCALSTACK_VOLUME_DIR` points at a host directory. +The `localstack/localstack-mcp-server` Docker image bundles `lstk` with Terraform, CDK, and SAM, the Azure CLI, and the Snowflake CLI. The only required host dependency is Docker. The container uses the mounted Docker socket to run LocalStack as a sibling container on the host; state lives in a named Docker volume (`localstack-mcp`) unless `LOCALSTACK_VOLUME_DIR` points at a host directory. If you use the deployer tool with local Terraform, CDK, or SAM projects, bind-mount those project paths into the MCP container and pass the in-container path to the tool. The simplest convention is to mount projects at the same absolute path they use on the host. @@ -210,7 +210,7 @@ See **[docs/DOCKER.md](./docs/DOCKER.md)** for the run command, MCP client confi | Variable Name | Description | Default Value | | -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- | | `LOCALSTACK_AUTH_TOKEN` (**required**) | The LocalStack Auth Token to use for the MCP server | None | -| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1), so it needs a local gateway. | `localhost` | +| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1); in Docker the server forwards that port to this host. | `localhost` | | `LOCALSTACK_PORT` | Port of the LocalStack gateway the tools call. | `4566` | | `MAIN_CONTAINER_NAME` | The explicit LocalStack container name to use for Docker-based tools. When unset, the server auto-detects standard LocalStack containers such as `localstack-main` and `localstack-aws`, then LocalStack Docker images. | Auto-detect | | `LOCALSTACK_IMAGE_NAME` / `IMAGE_NAME` | Docker image the `start` action launches for the AWS stack. `LOCALSTACK_IMAGE_NAME` wins when both are set (beware: bare `IMAGE_NAME` is a common CI variable). | `localstack/localstack-pro:latest` | diff --git a/docs/AZURE.md b/docs/AZURE.md index 37d0944..22e960f 100644 --- a/docs/AZURE.md +++ b/docs/AZURE.md @@ -8,4 +8,4 @@ - Relative file paths in commands resolve against `LOCALSTACK_AZ_WORKDIR`, by default the directory the MCP client starts the server in. - `rest` calls the emulator: give it a relative URL. An absolute URL must name a local host; a `management.azure.com` URL is turned into a relative one. - Only `rest` URLs are checked: an endpoint given in a command, such as `--blob-endpoint` or a connection string, is used as it is. -- The Docker image does not include the Azure CLI yet: run the server with npx or from source to use the Azure tool. +- The Docker image includes the Azure CLI. Mount the files your commands use and set `LOCALSTACK_AZ_WORKDIR` to the mount (see [DOCKER.md](./DOCKER.md#azure-cli)). The image has no Azure CLI extensions or `bicep`, and its Azure CLI profile lasts only as long as the container. diff --git a/docs/DOCKER.md b/docs/DOCKER.md index ec8c63f..caee6d6 100644 --- a/docs/DOCKER.md +++ b/docs/DOCKER.md @@ -1,7 +1,7 @@ # Running the LocalStack MCP Server in Docker The published image bundles everything the server shells out to — `lstk` with -Terraform, AWS CDK, and AWS SAM, and the Snowflake `snow` +Terraform, AWS CDK, and AWS SAM, the Azure CLI, and the Snowflake `snow` CLI — so the **only dependency on your machine is Docker itself**. LocalStack lifecycle, logs, and `awslocal` run through the Docker Engine API and LocalStack's REST APIs. @@ -29,7 +29,9 @@ Because LocalStack is a sibling container, one thing must be configured at run t - **Reachability** — set `LOCALSTACK_HOSTNAME=host.docker.internal` so the server and the IaC CLIs target the sibling's published port instead of the container's - own `localhost`. + own `localhost`. The server also forwards the container's `127.0.0.1:4566` + (`LOCALSTACK_PORT`) to that host, because `*.localhost.localstack.cloud` names, + such as the Azure emulator's per-account storage hosts, resolve to `127.0.0.1`. LocalStack state lives in a **named Docker volume** (`localstack-mcp`) by default, so no host directory needs to be mounted or path-mirrored. To keep state in a host @@ -113,6 +115,21 @@ receives the LocalStack endpoint automatically when publishing to path-style S3, so no extra S3 host alias is needed. Existing configs that still pass `--add-host s3.host.docker.internal:host-gateway` keep working. +## Azure CLI + +The `localstack-azure-client` tool runs the bundled Azure CLI. As with IaC +projects, mount the files your commands use (templates, uploads) and point +`LOCALSTACK_AZ_WORKDIR` at the mount so relative paths resolve there: + +``` +-v "/Users/you/projects/my-app:/Users/you/projects/my-app" +-e LOCALSTACK_AZ_WORKDIR=/Users/you/projects/my-app +``` + +The tool's Azure CLI profile lives inside the container, so it is set up again +each time the container starts. The image has no Azure CLI extensions and no +`bicep`. + ## Known limitations - **Extra host aliases.** Include the aliases shown in the quick-start command. @@ -122,10 +139,6 @@ that still pass `--add-host s3.host.docker.internal:host-gateway` keep working. on the host even if your editor restarts the MCP container — reconnecting finds your stack still up. State persists in the `localstack-mcp` named volume (or `LOCALSTACK_VOLUME_DIR` if you set one). -- **No Azure CLI.** The image lists all 15 tools, but it does not include the Azure - CLI, so `localstack-azure-client` answers that `az` is not available. To use the - Azure tool, run the server with npx or from source. `localstack-management` can - still start and stop the Azure emulator (`service: azure`) from the image. ## Troubleshooting diff --git a/src/cli/index.ts b/src/cli/index.ts index f789b8d..8fd3fb0 100644 --- a/src/cli/index.ts +++ b/src/cli/index.ts @@ -7,6 +7,7 @@ import * as fs from "fs"; import * as path from "path"; import { exitWhenClientDisconnects } from "./lifecycle"; +import { forwardLoopbackGateway } from "./loopback-forward"; function getVersion(): string { try { @@ -58,6 +59,7 @@ async function main(): Promise { ); } exitWhenClientDisconnects(); + forwardLoopbackGateway(); require("./stdio.js"); } } diff --git a/src/cli/loopback-forward.test.ts b/src/cli/loopback-forward.test.ts new file mode 100644 index 0000000..4b5ba18 --- /dev/null +++ b/src/cli/loopback-forward.test.ts @@ -0,0 +1,86 @@ +import * as net from "net"; + +import { loopbackForwardTarget, startLoopbackForwarder } from "./loopback-forward"; + +describe("loopbackForwardTarget", () => { + it("forwards to the host gateway inside a container", () => { + expect(loopbackForwardTarget({ LOCALSTACK_HOSTNAME: "host.docker.internal" }, true)).toEqual({ + host: "host.docker.internal", + port: 4566, + }); + }); + + it("uses LOCALSTACK_PORT", () => { + expect( + loopbackForwardTarget( + { LOCALSTACK_HOSTNAME: "host.docker.internal", LOCALSTACK_PORT: "4567" }, + true + ) + ).toEqual({ host: "host.docker.internal", port: 4567 }); + }); + + it("does nothing outside a container", () => { + expect(loopbackForwardTarget({ LOCALSTACK_HOSTNAME: "host.docker.internal" }, false)).toBe( + undefined + ); + }); + + it.each([undefined, "localhost", "127.0.0.1"])( + "does nothing when LocalStack is local (%s)", + (host) => { + expect(loopbackForwardTarget({ LOCALSTACK_HOSTNAME: host }, true)).toBe(undefined); + } + ); + + it("does nothing for an invalid port", () => { + expect( + loopbackForwardTarget( + { LOCALSTACK_HOSTNAME: "host.docker.internal", LOCALSTACK_PORT: "nope" }, + true + ) + ).toBe(undefined); + }); +}); + +describe("startLoopbackForwarder", () => { + const listening = (server: net.Server) => + new Promise((resolve) => + server.listening + ? resolve((server.address() as net.AddressInfo).port) + : server.once("listening", () => resolve((server.address() as net.AddressInfo).port)) + ); + + it("pipes loopback connections to the target and back", async () => { + const upstream = net.createServer((socket) => socket.pipe(socket)); + upstream.listen(0, "127.0.0.1"); + const upstreamPort = await listening(upstream); + + const forwarder = startLoopbackForwarder({ host: "127.0.0.1", port: upstreamPort }, 0); + const forwarderPort = await listening(forwarder); + + const reply = await new Promise((resolve, reject) => { + const client = net.connect(forwarderPort, "127.0.0.1", () => client.write("ping")); + client.once("data", (data) => { + resolve(data.toString()); + client.destroy(); + }); + client.once("error", reject); + }); + + expect(reply).toBe("ping"); + forwarder.close(); + upstream.close(); + }); + + it("gives up quietly when the port is taken", async () => { + const taken = net.createServer(); + taken.listen(0, "127.0.0.1"); + const port = await listening(taken); + + const forwarder = startLoopbackForwarder({ host: "127.0.0.1", port: 1 }, port); + await new Promise((resolve) => forwarder.once("close", () => resolve())); + + expect(forwarder.listening).toBe(false); + taken.close(); + }); +}); diff --git a/src/cli/loopback-forward.ts b/src/cli/loopback-forward.ts new file mode 100644 index 0000000..3737e8c --- /dev/null +++ b/src/cli/loopback-forward.ts @@ -0,0 +1,55 @@ +/** + * In the Docker image LocalStack runs in a sibling container, but its + * *.localhost.localstack.cloud names resolve to 127.0.0.1 — this container. + * Names that `--add-host` cannot cover, such as the per-account Azure storage + * hosts (.blob.core.azure.localhost.localstack.cloud), would reach + * nothing. Forwarding the container's loopback gateway port to + * LOCALSTACK_HOSTNAME sends every such name to LocalStack; TLS passes through + * untouched, so certificates still match the requested host. + */ +import * as fs from "fs"; +import * as net from "net"; + +export interface ForwardTarget { + host: string; + port: number; +} + +/** Where to forward, or undefined outside a container or when LocalStack is already local. */ +export function loopbackForwardTarget( + env: NodeJS.ProcessEnv = process.env, + inContainer: boolean = fs.existsSync("/.dockerenv") +): ForwardTarget | undefined { + const host = env.LOCALSTACK_HOSTNAME?.trim(); + if (!inContainer || !host || host === "localhost" || host === "127.0.0.1") return undefined; + const port = Number(env.LOCALSTACK_PORT?.trim() || 4566); + if (!Number.isInteger(port) || port < 1 || port > 65535) return undefined; + return { host, port }; +} + +export function startLoopbackForwarder( + target: ForwardTarget, + listenPort: number = target.port +): net.Server { + const server = net.createServer((client) => { + const upstream = net.connect(target.port, target.host); + const close = () => { + client.destroy(); + upstream.destroy(); + }; + client.on("error", close).on("close", close); + upstream.on("error", close).on("close", close); + client.pipe(upstream).pipe(client); + }); + // Best effort: a taken port (e.g. `--network host`) only means no forwarding. + server.on("error", () => server.close()); + server.listen(listenPort, "127.0.0.1"); + // The client's stdio decides when the process exits, not this listener. + server.unref(); + return server; +} + +export function forwardLoopbackGateway(): void { + const target = loopbackForwardTarget(); + if (target) startLoopbackForwarder(target); +} diff --git a/tests/docker/validate-image.mjs b/tests/docker/validate-image.mjs index 2795be9..98bcf6c 100644 --- a/tests/docker/validate-image.mjs +++ b/tests/docker/validate-image.mjs @@ -26,6 +26,7 @@ * Env knobs: * HARNESS_DEPLOY_DIR In-container path to the terraform sample (default /work/data/sample-terraform) * HARNESS_CDK_DIR In-container path to the CDK sample (default /work/data/sample-cdk) + * HARNESS_AZURE_FILE In-container path to the file the Azure scenario uploads (default /work/data/sample-azure/hello.txt) * HARNESS_TOKEN_REAL "1" if LOCALSTACK_AUTH_TOKEN is a real/valid token (affects Pro-tool expectations) * HARNESS_SKIP Comma-separated scenario keys to skip (e.g. "deploy,extensions") * HARNESS_NO_CLEANUP "1" to leave LocalStack running afterwards @@ -47,6 +48,7 @@ const serverArgs = argv.slice(sep + 2); const DEPLOY_DIR = process.env.HARNESS_DEPLOY_DIR || "/work/data/sample-terraform"; const CDK_DIR = process.env.HARNESS_CDK_DIR || "/work/data/sample-cdk"; const SQL_FILE = process.env.HARNESS_SQL_FILE || "/work/data/sample-sql/snowflake_test.sql"; +const AZURE_FILE = process.env.HARNESS_AZURE_FILE || "/work/data/sample-azure/hello.txt"; const TOKEN_REAL = process.env.HARNESS_TOKEN_REAL === "1"; const SKIP = new Set( (process.env.HARNESS_SKIP || "") @@ -980,6 +982,57 @@ async function main() { } } } + + // 11. Azure stack — the bundled az CLI. The blob upload goes to a per-account + // *.localhost.localstack.cloud host, so it also validates the loopback forwarder. + if (!SKIP.has("azure")) { + const id = RUN_ID.replace(/[^a-z0-9]/g, "").slice(-12); + const group = `mcp-harness-${id}`; + const account = `mcpharness${id}`; + const storage = `--account-name ${account} --auth-mode key`; + const az = (command) => callTool("localstack-azure-client", { command }, 300000); + try { + const start = await callTool( + "localstack-management", + { action: "start", service: "azure" }, + 300000 + ); + const answers = [`start: ${start.text}`]; + let ok = !start.isError; + let blobs = ""; + for (const command of [ + `group create --name ${group} --location westeurope`, + `storage account create --name ${account} --resource-group ${group} --location westeurope --sku Standard_LRS`, + `storage container create --name data ${storage}`, + `storage blob upload --container-name data --name hello.txt --file ${AZURE_FILE} ${storage}`, + `storage blob list --container-name data ${storage} --query "[].name"`, + ]) { + if (!ok) break; + const r = await az(command); + answers.push(`${command.split(" --")[0]}: ${r.text}`); + ok = !r.isError; + blobs = r.text; + } + ok = ok && /hello\.txt/.test(blobs); + recordToolResult( + "azure", + "localstack-azure-client group/storage account/blob upload", + { text: answers.join("\n"), isError: !ok }, + () => ok + ); + } catch (e) { + record("azure", "azure-client", false, String(e.message)); + } finally { + if (!NO_CLEANUP) { + try { + await az(`group delete --name ${group} --yes`); + } catch {} + try { + await callTool("localstack-management", { action: "stop" }, 60000); + } catch {} + } + } + } } main()