diff --git a/src/content/docs/azure/getting-started/auth-token.mdx b/src/content/docs/azure/getting-started/auth-token.mdx new file mode 100644 index 00000000..c1dfa81a --- /dev/null +++ b/src/content/docs/azure/getting-started/auth-token.mdx @@ -0,0 +1,229 @@ +--- +title: Auth Token +description: Configure your Auth Token to access and activate LocalStack for Azure. +template: doc +sidebar: + order: 1 +--- + +import { Code, Tabs, TabItem } from '@astrojs/starlight/components'; + +## Introduction + +An Auth Token is required to activate the LocalStack for Azure emulator. +It identifies and authenticates users outside the LocalStack Web Application, granting access to your workspace and to advanced features such as the Azure emulator image. + +Auth Tokens are issued at the workspace level in [app.localstack.cloud](https://app.localstack.cloud) and are shared across every LocalStack product you use — the same token activates LocalStack for AWS, Azure, and Snowflake. +There is no Azure-specific token. + +Auth Tokens come in two types: a **Developer Auth Token** and a **CI Auth Token**: + +- The **Developer Auth Token** is linked to a specific user within a specific workspace. + Every user has their own Auth Token. + It cannot be deleted but can be rotated for security reasons if needed. +- The **CI Auth Token** is not associated with any specific user and is designed for use in CI environments and other non-developer contexts. + These tokens are stored in the workspace and can be managed by members with appropriate permissions. + +Both the **Developer Auth Token** and **CI Auth Token** can be managed on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens). + +:::danger + +- It's crucial to keep your Auth Token confidential. + Do not include it in source code management systems, such as Git repositories. +- Be aware that if an Auth Token is committed to a public repository, it is at risk of exposure and could remain in the repository's history, even if attempts are made to rewrite it. +- In case your Auth Token is accidentally published, immediately rotate it on the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens). + ::: + +## Managing your License + +To use the LocalStack for Azure emulator, a license with access to Azure is required. +You can get a license by registering on the [LocalStack Web Application](https://app.localstack.cloud/sign-up) and starting a trial, or by contacting the LocalStack team about an Azure-enabled plan. + +After initiating your trial or acquiring a license, assign it to a user by following these steps: + +- Visit the [Users & Licenses page](https://app.localstack.cloud/workspace/members). +- Select a user in the **Workspace Members** section for license assignment. +- Define the user's role via the **Member Role** dropdown. + Single users automatically receive the **Admin** role. +- Toggle **Advanced Permissions** to set specific permissions. + Single users automatically receive full permissions. +- Click **Save** to complete the assignment. + Single users assign licenses to themselves. + +If you have joined a workspace, you need to be assigned a license by the workspace administrator. +When switching workspaces or licenses, make sure you are assigned to the correct license. + +:::note +If you do not assign a license, the Azure emulator will not start even if you have a valid Auth Token. +::: + +To view your own assigned license, visit the [My License page](https://app.localstack.cloud/workspace/my-license). +For more details on inviting users, assigning licenses, or managing roles, see [Users and Licenses](/aws/capabilities/web-app/managing-users-licenses/). + +## Configuring your Auth Token + +The Azure emulator reads the Auth Token from the `LOCALSTACK_AUTH_TOKEN` environment variable. +You can configure the Auth Token in several ways, depending on your setup. +The following sections describe the various methods of providing your Auth Token to the Azure container. + +:::danger + +- It's crucial to keep your Auth Token confidential. + Do not include it in source code management systems, such as Git repositories. +- Be aware that if an Auth Token is committed to a public repository, it is at risk of exposure and could remain in the repository's history, even if attempts are made to rewrite it. +- 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 + +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`: + + + + \nIMAGE_NAME=localstack/localstack-azure-alpha localstack start`} + lang="shell" + /> + + + \n$env:IMAGE_NAME="localstack/localstack-azure-alpha"; localstack start`} + lang="powershell" + /> + + + +:::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. + +### Docker + +To start the Azure emulator via Docker, provide the Auth Token using the `-e` flag: + +```bash {5} +docker run \ + --rm -it \ + -p 4566:4566 \ + -v /var/run/docker.sock:/var/run/docker.sock \ + -e LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:- } \ + localstack/localstack-azure-alpha +``` + +For more information about starting the Azure emulator with Docker, take a look at our [Azure installation guide](/azure/getting-started/#docker-cli). + +### Docker Compose + +To start the Azure emulator using `docker compose`, include the `LOCALSTACK_AUTH_TOKEN` environment variable in your `docker-compose.yml` file: + +```yaml +environment: + - LOCALSTACK_AUTH_TOKEN=${LOCALSTACK_AUTH_TOKEN:?} +``` + +You can manually set the Auth Token, or use the `export` command to establish the Auth Token in your current shell session. +This ensures the Auth Token is transmitted to the Azure container, enabling license activation. + +### CI Environments + +CI environments require a CI Auth Token. +Developer Auth Tokens cannot be used in CI. +CI Auth Tokens are available on the [Auth Tokens page](https://app.localstack.cloud/workspace/auth-tokens) and are configured similarly to Developer Auth Tokens. + +To set the CI Auth Token, add the Auth Token value in the `LOCALSTACK_AUTH_TOKEN` environment variable of your CI provider, and reference it when starting the Azure emulator in your CI workflow. +The same patterns used for [LocalStack in CI](/aws/integrations/continuous-integration/) apply to Azure — swap the image for `localstack/localstack-azure-alpha`. + +## Rotating the Auth Token + +Your personal Auth Token provides full access to your workspace and LocalStack license. +Treat it as confidential and avoid sharing or storing it in source control management systems (SCMs) like Git. + +If you believe your Auth Token has been compromised or becomes known to someone else, reset it without delay. +When you reset a token, the old one is immediately deactivated and can no longer access your license or workspace. +Previous tokens cannot be restored. + +To rotate your Auth Token, go to the [Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and select the **Reset Auth Token** option. + +## Verifying activation + +The simplest way to verify that the Azure emulator activated successfully is to query the health endpoint: + + + + + ```bash + curl http://localhost:4566/_localstack/info | jq + ``` + + + + + ```bash + Invoke-WebRequest -Uri http://localhost:4566/_localstack/info | ConvertFrom-Json + ``` + + + + +A successful activation returns `"is_license_activated": true`. +You can also check the container logs for a message indicating successful license activation: + +```bash +[...] Successfully activated license +``` + +Otherwise, check the [Troubleshooting](#troubleshooting) section below. + +## Troubleshooting + +The Azure emulator requires a successful license activation to start. +If activation fails, the container exits and prints an error message similar to: + +```bash +=============================================== +License activation failed! + +Reason: The credentials defined in your environment are invalid. Please make sure to set the LOCALSTACK_AUTH_TOKEN variable to a valid auth token. You can find your Auth Token in the LocalStack web app https://app.localstack.cloud. + +Due to this error, LocalStack has quit. The Azure emulator can only be used with a valid license. +``` + +The most common causes are listed below. + +### Missing credentials + +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 +``` + +### Invalid license + +The issue may occur if there is no valid license linked to your account (for example, because it has expired), or if the license has not been assigned to your user. +You can check your license status in the LocalStack Web Application on the [My License page](https://app.localstack.cloud/workspace/my-license). +If your license does not grant access to the Azure emulator, [contact us](https://localstack.cloud/contact/) to upgrade. + +### License server unreachable + +LocalStack initiates offline activation when the license server is unreachable, requiring re-activation every 24 hours. +Log output may indicate issues with your machine resolving the LocalStack API domain, which can be verified using a tool like `dig`: + +```bash +dig api.localstack.cloud +``` + +If the result shows a status other than `status: NOERROR`, your machine is unable to resolve this domain. +Certain corporate DNS servers may filter requests to specific domains. +Kindly reach out to your network administrator to safelist the `localstack.cloud` domain. + +If you continue to have problems with license activation, or if the steps above do not help, do not hesitate to [contact us](https://localstack.cloud/contact/). diff --git a/src/content/docs/azure/getting-started/index.mdx b/src/content/docs/azure/getting-started/index.mdx index 5d2b0e60..4aaac7b4 100644 --- a/src/content/docs/azure/getting-started/index.mdx +++ b/src/content/docs/azure/getting-started/index.mdx @@ -11,7 +11,7 @@ sidebar: 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](/aws/getting-started/auth-token/) to obtain your Auth Token and specify it in the `LOCALSTACK_AUTH_TOKEN` environment variable. +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. The Azure Docker image is available on the [LocalStack Docker Hub](https://hub.docker.com/r/localstack/localstack-azure-alpha). To pull the Azure Docker image, execute the following command: diff --git a/src/content/docs/azure/getting-started/quickstart.md b/src/content/docs/azure/getting-started/quickstart.md index cb57559e..7d1b681c 100644 --- a/src/content/docs/azure/getting-started/quickstart.md +++ b/src/content/docs/azure/getting-started/quickstart.md @@ -3,7 +3,7 @@ title: Quickstart description: Get started with LocalStack for Azure in a few simple steps. template: doc sidebar: - order: 1 + order: 2 --- ## Introduction @@ -16,6 +16,7 @@ In this guide, you will run some basic Azure CLI commands to manage resource gro - [`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/) ## Instructions diff --git a/src/content/docs/snowflake/getting-started/index.mdx b/src/content/docs/snowflake/getting-started/index.mdx index d82ad076..265a831b 100644 --- a/src/content/docs/snowflake/getting-started/index.mdx +++ b/src/content/docs/snowflake/getting-started/index.mdx @@ -103,7 +103,7 @@ Need more options? See our [alternative installation instructions](https://docs. ## Starting the Snowflake Emulator -Once the CLI is installed and your auth token is set, start the Snowflake Emulator with: +Once the CLI is installed and your [Auth Token](/snowflake/getting-started/auth-token/) is set, start the Snowflake Emulator with: ```bash localstack start --stack snowflake diff --git a/src/content/docs/snowflake/getting-started/quickstart.md b/src/content/docs/snowflake/getting-started/quickstart.md index fe7db22d..4b2f76dc 100644 --- a/src/content/docs/snowflake/getting-started/quickstart.md +++ b/src/content/docs/snowflake/getting-started/quickstart.md @@ -14,6 +14,7 @@ This guide explains how to set up the Snowflake emulator and use Snowflake CLI t - [LocalStack for Snowflake](/snowflake/getting-started/) - [`localstack` CLI](/aws/getting-started/installation/#localstack-cli) +- A [LocalStack Auth Token](/snowflake/getting-started/auth-token/) - [Snowflake CLI](/snowflake/integrations/snow-cli/) LocalStack for Snowflake works with popular Snowflake integrations to run your SQL queries. This guide uses the [Snowflake CLI](/snowflake/integrations/snow-cli/), but you can also use [SnowSQL](/snowflake/integrations/snow-sql/), [DBeaver](/snowflake/integrations/dbeaver/) or the [LocalStack Web Application](/snowflake/tooling/user-interface/) for this purpose. diff --git a/src/content/docs/snowflake/tutorials/aws-lambda-localstack-snowpark.md b/src/content/docs/snowflake/tutorials/aws-lambda-localstack-snowpark.md index 8c83970a..9659281d 100644 --- a/src/content/docs/snowflake/tutorials/aws-lambda-localstack-snowpark.md +++ b/src/content/docs/snowflake/tutorials/aws-lambda-localstack-snowpark.md @@ -19,7 +19,7 @@ The code in this tutorial is available on [GitHub](https://github.com/localstack ## Prerequisites -- [`localstack` CLI](/snowflake/getting-started/) with a [`LOCALSTACK_AUTH_TOKEN`](/aws/getting-started/auth-token/) +- [`localstack` CLI](/snowflake/getting-started/) with a [`LOCALSTACK_AUTH_TOKEN`](/snowflake/getting-started/auth-token/) - [LocalStack for Snowflake](/snowflake/getting-started/) - [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) & [`awslocal` wrapper](/aws/integrations/aws-native-tools/aws-cli/#localstack-aws-cli-awslocal) - Python 3.10 installed locally diff --git a/src/content/docs/snowflake/tutorials/credit-scoring-with-localstack-snowpark.md b/src/content/docs/snowflake/tutorials/credit-scoring-with-localstack-snowpark.md index a53a4843..0957f3c8 100644 --- a/src/content/docs/snowflake/tutorials/credit-scoring-with-localstack-snowpark.md +++ b/src/content/docs/snowflake/tutorials/credit-scoring-with-localstack-snowpark.md @@ -14,7 +14,7 @@ The Jupyter Notebook and the dataset used in this tutorial are available on [Git ## Prerequisites -- [`localstack` CLI](/snowflake/getting-started/) with a [`LOCALSTACK_AUTH_TOKEN`](/aws/getting-started/auth-token/) +- [`localstack` CLI](/snowflake/getting-started/) with a [`LOCALSTACK_AUTH_TOKEN`](/snowflake/getting-started/auth-token/) - [LocalStack for Snowflake](/snowflake/getting-started/) - [Snowpark](/snowflake/integrations/snowpark) with other Python libraries - [Jupyter Notebook](https://jupyter.org/install#jupyter-notebook) diff --git a/src/content/docs/snowflake/tutorials/s3-tables-iceberg-integration.md b/src/content/docs/snowflake/tutorials/s3-tables-iceberg-integration.md index 72b5c12c..f05fa6a9 100644 --- a/src/content/docs/snowflake/tutorials/s3-tables-iceberg-integration.md +++ b/src/content/docs/snowflake/tutorials/s3-tables-iceberg-integration.md @@ -18,7 +18,7 @@ With LocalStack's Snowflake emulator, you can create catalog integrations that c ## Prerequisites -- [`localstack` CLI](/snowflake/getting-started/) with a [`LOCALSTACK_AUTH_TOKEN`](/aws/getting-started/auth-token/) +- [`localstack` CLI](/snowflake/getting-started/) with a [`LOCALSTACK_AUTH_TOKEN`](/snowflake/getting-started/auth-token/) - [LocalStack for Snowflake](/snowflake/getting-started/) - [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) & [`awslocal` wrapper](/aws/integrations/aws-native-tools/aws-cli/#localstack-aws-cli-awslocal) - Python 3.10+ with `pyiceberg` and `pyarrow` installed