diff --git a/src/content/docs/azure/getting-started/auth-token.mdx b/src/content/docs/azure/getting-started/auth-token.mdx index dd949c51..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 @@ -84,34 +84,13 @@ 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` 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. - - - \nIMAGE_NAME=localstack/localstack-azure localstack start`} - lang="shell" - /> - - - \n$env:IMAGE_NAME="localstack/localstack-azure"; localstack start`} - lang="powershell" - /> - - +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. -:::note - -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. +For CI environments, see [CI Environments](#ci-environments) below. ### Docker @@ -211,11 +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 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`, 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 2d52b6e3..9866f861 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. +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. -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: +Use [`lstk`](#lstk) to install, authenticate, and start the Azure emulator with minimal setup. -``` -$ docker pull localstack/localstack-azure -``` +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 -You can start the Azure emulator using the following methods: +`lstk` is a lightweight CLI for LocalStack that manages the authentication and container lifecycle for the AWS, Azure, and Snowflake emulators. -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/) +**Requirement:** You must have a working [Docker installation](https://docs.docker.com/get-docker/) before proceeding. -### `localstack` CLI +### Install lstk -To start the Azure emulator using the `localstack` CLI, execute the following command: + + + ```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`. + + +### 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 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 + +```bash +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. +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..0e7a9cd6 100644 --- a/src/content/docs/azure/getting-started/quickstart.md +++ b/src/content/docs/azure/getting-started/quickstart.md @@ -13,28 +13,31 @@ 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/) -- [LocalStack for Azure](/azure/getting-started/) -- A [LocalStack Auth Token](/azure/getting-started/auth-token/) +- [`lstk`](/azure/getting-started/installation/#lstk) +- [Azure CLI (`az`)](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) +- 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: -### Setup the `azlocal` tool +``` +$ lstk start +``` + +For more installation details, see the [installation instructions](/azure/getting-started/). + +### Set up the `az` CLI integration -To instruct the regular `az` CLI tool to communicate with the Azure emulator, run the following command: +To make sure the `az` tool sends requests to the Azure Emulator REST API, run the following command: ``` -$ azlocal start-interception +$ lstk az start-interception ``` -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, you can now run the same `az` command as you would normally: ``` $ az group create --name myResourceGroup --location westeurope @@ -67,7 +70,7 @@ $ az group show --name myResourceGroup To list all the resource groups, run the following command: ``` -$ azlocal group list +$ az group list ``` ### Delete the resource group @@ -80,10 +83,26 @@ $ az group delete --name myResourceGroup --yes ### Teardown -When you're done using the Azure Emulator, you can run the following command: +When you're done, disable interception and stop the emulator: ``` -$ azlocal stop-interception +$ lstk az stop-interception +$ lstk stop ``` -All invocations of the `az` CLI tool will now talk to the real Azure Cloud again. +### 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 +```