Skip to content

DOC-360: Update Azure getting started guide to use lstk #802

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
quetzalliwrites wants to merge 1 commit into
base: main
Choose a base branch
from
+77 −55
Open

DOC-360: Update Azure getting started guide to use lstk #802

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 10 additions & 16 deletions src/content/docs/azure/getting-started/auth-token.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

@mmaureenliu mmaureenliu Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The recommended mode with lstk is to let the CLI handle entire setup, including authentication. No need to mention how lstk resolves the auth token as it's in the lstk doc already. All the user needs to know here is to let lstk do the job and simply run lstk or lstk start.

In theory the user doesn't even need to know about developer personal auth token with lstk.

Unless it's in CI, in which case refer to the CI section below.


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:

<Tabs>
<TabItem label="macOS/Linux">
<Code
code={`localstack auth set-token <YOUR_AUTH_TOKEN>\nIMAGE_NAME=localstack/localstack-azure localstack start`}
code={`export LOCALSTACK_AUTH_TOKEN=<YOUR_AUTH_TOKEN>\nlstk start`}
lang="shell"
/>
</TabItem>
<TabItem label="Windows">
<Code
code={`localstack auth set-token <YOUR_AUTH_TOKEN>\n$env:IMAGE_NAME="localstack/localstack-azure"; localstack start`}
code={`$env:LOCALSTACK_AUTH_TOKEN="<YOUR_AUTH_TOKEN>"\nlstk start`}
lang="powershell"
/>
</TabItem>
</Tabs>

:::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=<YOUR_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

Expand Down Expand Up @@ -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 <YOUR_AUTH_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.

@mmaureenliu mmaureenliu Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Again we don't recommend manually setting auth token env var with lstk. If there's issue with credential, just lstk login.


### Invalid license

Expand Down
73 changes: 56 additions & 17 deletions src/content/docs/azure/getting-started/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

@mmaureenliu mmaureenliu Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd swap this paragraph with the lstk paragraph below. Start by saying we recommend lstk (it's simplest and you don't need to worry about understanding the auth token or pulling the correct docker image). Then this paragraph as alternative.

Alternatively we can mirror the AWS getting started guide.

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

<Tabs>
<TabItem label="Homebrew">
```bash
brew install localstack/tap/lstk
```
</TabItem>
<TabItem label="npm">
```bash
npm install -g @localstack/lstk
```
</TabItem>
<TabItem label="Binary">
Download the binary for your platform from the [GitHub Releases](https://github.com/localstack/lstk/releases) and add it to your `PATH`.
</TabItem>
</Tabs>

### 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`:

@mmaureenliu mmaureenliu Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That's no longer true. If user starts lstk for the first time it will ask you to pick an emulator and record your choice in the global config as the default. So I'd move this section below "Update lstk" and frame it as "What to do if you already use lstk and your global config defaults to the AWS emulator"


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=<your_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.

@mmaureenliu mmaureenliu Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can mention here the first execution will also prompt user to choose an emulator which will be recorded in global config as the default.


### 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:
Expand Down Expand Up @@ -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.

Expand Down
33 changes: 11 additions & 22 deletions src/content/docs/azure/getting-started/quickstart.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,31 +13,30 @@ 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/)

@mmaureenliu mmaureenliu Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

More accurately this should be a valid license that covers azure usage. Auth token is invisible here - every registered localstack user has one and lstk handles the authentication the user doesn't even need to know about it.


## Instructions

Before you begin, make sure that the Emulator is running, see the [installation instructions](/azure/getting-started/).

@mmaureenliu mmaureenliu Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For completeness I'd prefer to still add the start command here, but also mention see installation doc for details:

lstk start

and at the end

lstk stop


### Setup the `azlocal` tool
### Set up the `az` CLI integration

@mmaureenliu mmaureenliu Jul 21, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We actually recommend using the lstk az start/stop-interception mode as default, i.e.

lstk az start-interception (no need to setup azure)
az ...
az ...
lstk az stop-interception

Then maybe mention this as an alternative

lstk setup azure (only need to do once per config scope)
lstk az ...
lstk az ...


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:
Expand All @@ -61,29 +60,19 @@ 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

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.
Loading