From 48509401d36947e4b1fd308c698cda18234738f9 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Tue, 21 Jul 2026 00:59:32 +0200 Subject: [PATCH 1/2] DOC-360: Update Azure getting started guide to use lstk Replace the localstack CLI and azlocal wrapper across the Azure Getting Started docs with lstk, mirroring the AWS Getting Started guide. --- .../docs/azure/getting-started/auth-token.mdx | 26 +++---- .../docs/azure/getting-started/index.mdx | 73 ++++++++++++++----- .../docs/azure/getting-started/quickstart.md | 33 +++------ 3 files changed, 77 insertions(+), 55 deletions(-) diff --git a/src/content/docs/azure/getting-started/auth-token.mdx b/src/content/docs/azure/getting-started/auth-token.mdx index dd949c51..1940a75b 100644 --- a/src/content/docs/azure/getting-started/auth-token.mdx +++ b/src/content/docs/azure/getting-started/auth-token.mdx @@ -84,34 +84,32 @@ The following sections describe the various methods of providing your Auth Token - In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens). ::: -### LocalStack CLI +### lstk -You should set the `LOCALSTACK_AUTH_TOKEN` environment variable either before or during the startup of LocalStack using the `localstack` command-line interface (CLI). -When starting the Azure emulator, point the CLI at the Azure image via `IMAGE_NAME`: +`lstk` resolves your Auth Token in this order: a token stored by a previous `lstk login`, then the `LOCALSTACK_AUTH_TOKEN` environment variable, then a browser-based login prompt in interactive mode. + +Set the environment variable before starting the Azure emulator: \nIMAGE_NAME=localstack/localstack-azure localstack start`} + code={`export LOCALSTACK_AUTH_TOKEN=\nlstk start`} lang="shell" /> \n$env:IMAGE_NAME="localstack/localstack-azure"; localstack start`} + code={`$env:LOCALSTACK_AUTH_TOKEN=""\nlstk start`} lang="powershell" /> :::note +Alternatively, run `lstk login` to authenticate through a browser-based flow; the resulting token is stored in your system keyring and reused on subsequent starts. +::: -1. You can alternatively `export LOCALSTACK_AUTH_TOKEN=` in your shell session. - The CLI transmits the token to the Azure container, enabling license activation. -2. The `localstack auth set-token` command is only available for the `localstack` CLI and cannot be used with a Docker or Docker Compose setup. - ::: - -You have the option to run the Azure container in the background by appending the `-d` flag to the `localstack start` command. +Make sure your `config.toml` (or a project-local `.lstk/config.toml`) targets the Azure emulator, as described in [Configure lstk for Azure](/azure/getting-started/installation/#configure-lstk-for-azure). ### Docker @@ -211,11 +209,7 @@ The most common causes are listed below. You need to provide an Auth Token to start the Azure emulator. You can find your Auth Token on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application. -If you are using the `localstack` CLI, you can set the `LOCALSTACK_AUTH_TOKEN` environment variable to your Auth Token or use the following command to set it up: - -```bash -localstack auth set-token -``` +If you are using `lstk`, set the `LOCALSTACK_AUTH_TOKEN` environment variable to your Auth Token, or run `lstk login` to authenticate through a browser-based flow instead. ### Invalid license diff --git a/src/content/docs/azure/getting-started/index.mdx b/src/content/docs/azure/getting-started/index.mdx index 2d52b6e3..4e3bd41b 100644 --- a/src/content/docs/azure/getting-started/index.mdx +++ b/src/content/docs/azure/getting-started/index.mdx @@ -6,35 +6,74 @@ sidebar: order: 0 --- +import { Tabs, TabItem } from '@astrojs/starlight/components'; ## Introduction -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](/azure/getting-started/auth-token/) to obtain your Auth Token and specify it in the `LOCALSTACK_AUTH_TOKEN` environment variable. +You can set up the Azure emulator by utilizing LocalStack for Azure Docker image, [`localstack/localstack-azure`](https://hub.docker.com/r/localstack/localstack-azure). +Before starting, ensure you have a valid Auth Token to access the Azure emulator; see the [Auth Token guide](/azure/getting-started/auth-token/) to obtain one. -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: +We recommend installing with [`lstk`](#lstk) for the simplest setup — it handles authentication, image pulls, and the container lifecycle in a single workflow. +Alternatively, you can start the Azure emulator directly with the [`docker` CLI](#docker-cli) or [Docker Compose](#docker-compose). -``` -$ docker pull localstack/localstack-azure -``` +## lstk + +`lstk` is a lightweight CLI for LocalStack that manages the authentication and container lifecycle for the AWS, Azure, and Snowflake emulators. + +**Requirement:** You must have a working [Docker installation](https://docs.docker.com/get-docker/) before proceeding. + +### Install lstk + + + + ```bash + brew install localstack/tap/lstk + ``` + + + ```bash + npm install -g @localstack/lstk + ``` + + + Download the binary for your platform from the [GitHub Releases](https://github.com/localstack/lstk/releases) and add it to your `PATH`. + + + +### Configure lstk for Azure -You can start the Azure emulator using the following methods: +`lstk` starts the AWS emulator by default. To target the Azure emulator instead, create a project-local `.lstk/config.toml`: -1. [`localstack` CLI](/aws/getting-started/installation/#localstack-cli) -2. [`docker` CLI](https://docs.docker.com/get-docker/) -3. [Docker Compose](https://docs.docker.com/compose/install/) +```toml +# .lstk/config.toml +[[containers]] +type = "azure" +port = "4566" +``` -### `localstack` CLI +Alternatively, run `lstk` interactively with no existing config file and choose `z` for Azure when prompted; your choice is written to `config.toml` automatically. -To start the Azure emulator using the `localstack` CLI, execute the following command: +### Start lstk +```bash +lstk start ``` -$ export LOCALSTACK_AUTH_TOKEN= -$ IMAGE_NAME=localstack/localstack-azure localstack start + +The first execution initiates a browser-based login flow. Subsequent starts use credentials stored in your system keyring. + +### Update lstk + +```bash +lstk update ``` +For more details, see the [lstk documentation](/aws/developer-tools/running-localstack/lstk/). + +## Container and orchestration tools + +Use these methods when you need explicit container configuration or want to run LocalStack alongside other services. +For everyday local development, `lstk` is usually simpler. + ### `docker` CLI To start the Azure emulator using the `docker` CLI, execute the following command: @@ -74,7 +113,7 @@ Start the Azure emulator with the following command: $ docker-compose up ``` -### Updating +### Updating the Docker image To update the Azure Docker container, pull the latest image and restart the container. diff --git a/src/content/docs/azure/getting-started/quickstart.md b/src/content/docs/azure/getting-started/quickstart.md index 7d1b681c..8b758756 100644 --- a/src/content/docs/azure/getting-started/quickstart.md +++ b/src/content/docs/azure/getting-started/quickstart.md @@ -13,8 +13,8 @@ In this guide, you will run some basic Azure CLI commands to manage resource gro ## Prerequisites -- [`localstack` CLI](/aws/getting-started/installation/#localstack-cli) -- [`azlocal` CLI](https://pypi.org/project/azlocal/) +- [`lstk`](/azure/getting-started/installation/#lstk) +- [Azure CLI (`az`)](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) - [LocalStack for Azure](/azure/getting-started/) - A [LocalStack Auth Token](/azure/getting-started/auth-token/) @@ -22,22 +22,21 @@ In this guide, you will run some basic Azure CLI commands to manage resource gro Before you begin, make sure that the Emulator is running, see the [installation instructions](/azure/getting-started/). -### Setup the `azlocal` tool +### Set up the `az` CLI integration -To instruct the regular `az` CLI tool to communicate with the Azure emulator, run the following command: +`lstk az` proxies your host `az` CLI against the Azure emulator, using an isolated configuration directory so your global `~/.azure` setup is left untouched. +Run the following command once to prepare it: ``` -$ azlocal start-interception +$ lstk setup azure ``` -You may see some warnings about experimental commands, you can safely ignore these. - ### Create a resource group -To create a resource group, you can now the same `az` command as you would normally: +To create a resource group, prefix the same `az` command you would normally run with `lstk az`: ``` -$ az group create --name myResourceGroup --location westeurope +$ lstk az group create --name myResourceGroup --location westeurope ``` The following output would be displayed: @@ -61,13 +60,13 @@ The following output would be displayed: To check the resource group details, run the following command: ``` -$ az group show --name myResourceGroup +$ lstk az group show --name myResourceGroup ``` To list all the resource groups, run the following command: ``` -$ azlocal group list +$ lstk az group list ``` ### Delete the resource group @@ -75,15 +74,5 @@ $ azlocal group list To delete the resource group, run the following command: ``` -$ az group delete --name myResourceGroup --yes +$ lstk az group delete --name myResourceGroup --yes ``` - -### Teardown - -When you're done using the Azure Emulator, you can run the following command: - -``` -$ azlocal stop-interception -``` - -All invocations of the `az` CLI tool will now talk to the real Azure Cloud again. From f3bc634abc6aee5f5950e7978b3aafee29048822 Mon Sep 17 00:00:00 2001 From: Quetzalli Date: Thu, 23 Jul 2026 14:27:18 +0200 Subject: [PATCH 2/2] DOC-360: Address review feedback on lstk auth and interception flow - Simplify the auth-token lstk section: just run lstk/lstk start, since lstk resolves the token automatically; drop manual env var instructions in favor of lstk login for credential issues. - Reorder the installation intro to lead with the lstk recommendation (mirroring the AWS getting started guide), and move the manual per-project config.toml override below Update lstk, framed as an edge case for users whose global config already defaults elsewhere. Note that the first lstk run also prompts for an emulator choice. - Quickstart: recommend lstk az start-interception/stop-interception as the default flow (plain az commands in between), with lstk setup azure + prefixed lstk az commands as the alternative. Add explicit lstk start/stop steps. --- .../docs/azure/getting-started/auth-token.mdx | 29 ++--------- .../docs/azure/getting-started/index.mdx | 36 ++++++------- .../docs/azure/getting-started/quickstart.md | 50 +++++++++++++++---- 3 files changed, 63 insertions(+), 52 deletions(-) diff --git a/src/content/docs/azure/getting-started/auth-token.mdx b/src/content/docs/azure/getting-started/auth-token.mdx index 1940a75b..4b5b7ec8 100644 --- a/src/content/docs/azure/getting-started/auth-token.mdx +++ b/src/content/docs/azure/getting-started/auth-token.mdx @@ -6,7 +6,7 @@ sidebar: order: 1 --- -import { Code, Tabs, TabItem } from '@astrojs/starlight/components'; +import { Tabs, TabItem } from '@astrojs/starlight/components'; ## Introduction @@ -86,30 +86,11 @@ The following sections describe the various methods of providing your Auth Token ### lstk -`lstk` resolves your Auth Token in this order: a token stored by a previous `lstk login`, then the `LOCALSTACK_AUTH_TOKEN` environment variable, then a browser-based login prompt in interactive mode. +`lstk` handles authentication for you — just run `lstk` or `lstk start` and it takes care of the rest. See the [lstk documentation](/aws/developer-tools/running-localstack/lstk/) for details on how it resolves your Auth Token. -Set the environment variable before starting the Azure emulator: +On first run, `lstk` prompts you to pick an emulator and remembers your choice. If your `config.toml` already defaults to a different emulator, see [Already using lstk with a different default emulator?](/azure/getting-started/installation/#already-using-lstk-with-a-different-default-emulator) to target Azure instead. - - - \nlstk start`} - lang="shell" - /> - - - "\nlstk start`} - lang="powershell" - /> - - - -:::note -Alternatively, run `lstk login` to authenticate through a browser-based flow; the resulting token is stored in your system keyring and reused on subsequent starts. -::: - -Make sure your `config.toml` (or a project-local `.lstk/config.toml`) targets the Azure emulator, as described in [Configure lstk for Azure](/azure/getting-started/installation/#configure-lstk-for-azure). +For CI environments, see [CI Environments](#ci-environments) below. ### Docker @@ -209,7 +190,7 @@ The most common causes are listed below. You need to provide an Auth Token to start the Azure emulator. You can find your Auth Token on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) in the LocalStack Web Application. -If you are using `lstk`, set the `LOCALSTACK_AUTH_TOKEN` environment variable to your Auth Token, or run `lstk login` to authenticate through a browser-based flow instead. +If you are using `lstk`, run `lstk login` to authenticate through a browser-based flow. In CI, set the `LOCALSTACK_AUTH_TOKEN` environment variable instead; see [CI Environments](#ci-environments). ### Invalid license diff --git a/src/content/docs/azure/getting-started/index.mdx b/src/content/docs/azure/getting-started/index.mdx index 4e3bd41b..9866f861 100644 --- a/src/content/docs/azure/getting-started/index.mdx +++ b/src/content/docs/azure/getting-started/index.mdx @@ -10,11 +10,13 @@ import { Tabs, TabItem } from '@astrojs/starlight/components'; ## Introduction -You can set up the Azure emulator by utilizing LocalStack for Azure Docker image, [`localstack/localstack-azure`](https://hub.docker.com/r/localstack/localstack-azure). -Before starting, ensure you have a valid Auth Token to access the Azure emulator; see the [Auth Token guide](/azure/getting-started/auth-token/) to obtain one. +LocalStack provides multiple installation paths depending on your development environment and requirements. We recommend a CLI-based installation for the most consistent local startup experience. -We recommend installing with [`lstk`](#lstk) for the simplest setup — it handles authentication, image pulls, and the container lifecycle in a single workflow. -Alternatively, you can start the Azure emulator directly with the [`docker` CLI](#docker-cli) or [Docker Compose](#docker-compose). +Use [`lstk`](#lstk) to install, authenticate, and start the Azure emulator with minimal setup. + +LocalStack for Azure features require an [Auth Token](/azure/getting-started/auth-token/) to activate your running instance. `lstk` handles authentication through a browser-based login flow, while Docker and CI workflows can use `LOCALSTACK_AUTH_TOKEN`. + +Alternatively, you can set up the Azure emulator directly using the LocalStack for Azure Docker image, [`localstack/localstack-azure`](https://hub.docker.com/r/localstack/localstack-azure), with the [`docker` CLI](#docker-cli) or [Docker Compose](#docker-compose). ## lstk @@ -40,26 +42,13 @@ Alternatively, you can start the Azure emulator directly with the [`docker` CLI] -### Configure lstk for Azure - -`lstk` starts the AWS emulator by default. To target the Azure emulator instead, create a project-local `.lstk/config.toml`: - -```toml -# .lstk/config.toml -[[containers]] -type = "azure" -port = "4566" -``` - -Alternatively, run `lstk` interactively with no existing config file and choose `z` for Azure when prompted; your choice is written to `config.toml` automatically. - ### Start lstk ```bash lstk start ``` -The first execution initiates a browser-based login flow. Subsequent starts use credentials stored in your system keyring. +The first execution initiates a browser-based login flow and, in an interactive terminal, prompts you to pick which emulator to run — choose `z` for Azure. Your choice is written to `config.toml` and used as the default on subsequent runs. Subsequent starts use credentials stored in your system keyring. ### Update lstk @@ -69,6 +58,17 @@ lstk update For more details, see the [lstk documentation](/aws/developer-tools/running-localstack/lstk/). +### Already using lstk with a different default emulator? + +If your global `config.toml` already defaults to a different emulator (for example, AWS), target Azure for a specific project instead by creating a project-local `.lstk/config.toml`: + +```toml +# .lstk/config.toml +[[containers]] +type = "azure" +port = "4566" +``` + ## Container and orchestration tools Use these methods when you need explicit container configuration or want to run LocalStack alongside other services. diff --git a/src/content/docs/azure/getting-started/quickstart.md b/src/content/docs/azure/getting-started/quickstart.md index 8b758756..0e7a9cd6 100644 --- a/src/content/docs/azure/getting-started/quickstart.md +++ b/src/content/docs/azure/getting-started/quickstart.md @@ -15,28 +15,32 @@ In this guide, you will run some basic Azure CLI commands to manage resource gro - [`lstk`](/azure/getting-started/installation/#lstk) - [Azure CLI (`az`)](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) -- [LocalStack for Azure](/azure/getting-started/) -- A [LocalStack Auth Token](/azure/getting-started/auth-token/) +- A LocalStack account with a license that covers Azure usage — `lstk` handles authentication for you (see [Authentication](/azure/getting-started/auth-token/)) ## Instructions -Before you begin, make sure that the Emulator is running, see the [installation instructions](/azure/getting-started/). +Start the Azure emulator: + +``` +$ lstk start +``` + +For more installation details, see the [installation instructions](/azure/getting-started/). ### Set up the `az` CLI integration -`lstk az` proxies your host `az` CLI against the Azure emulator, using an isolated configuration directory so your global `~/.azure` setup is left untouched. -Run the following command once to prepare it: +To make sure the `az` tool sends requests to the Azure Emulator REST API, run the following command: ``` -$ lstk setup azure +$ lstk az start-interception ``` ### Create a resource group -To create a resource group, prefix the same `az` command you would normally run with `lstk az`: +To create a resource group, you can now run the same `az` command as you would normally: ``` -$ lstk az group create --name myResourceGroup --location westeurope +$ az group create --name myResourceGroup --location westeurope ``` The following output would be displayed: @@ -60,13 +64,13 @@ The following output would be displayed: To check the resource group details, run the following command: ``` -$ lstk az group show --name myResourceGroup +$ az group show --name myResourceGroup ``` To list all the resource groups, run the following command: ``` -$ lstk az group list +$ az group list ``` ### Delete the resource group @@ -74,5 +78,31 @@ $ lstk az group list To delete the resource group, run the following command: ``` +$ az group delete --name myResourceGroup --yes +``` + +### Teardown + +When you're done, disable interception and stop the emulator: + +``` +$ lstk az stop-interception +$ lstk stop +``` + +### Alternative: prefixed commands + +Instead of interception, you can prefix each `az` command with `lstk az` individually, without changing your global `~/.azure` configuration. Run this once to prepare the integration: + +``` +$ lstk setup azure +``` + +Then prefix every command: + +``` +$ lstk az group create --name myResourceGroup --location westeurope +$ lstk az group show --name myResourceGroup +$ lstk az group list $ lstk az group delete --name myResourceGroup --yes ```