diff --git a/src/content/docs/aws/customization/advanced/arm64-support.md b/src/content/docs/aws/customization/advanced/arm64-support.md index f07b7f76..089f9610 100644 --- a/src/content/docs/aws/customization/advanced/arm64-support.md +++ b/src/content/docs/aws/customization/advanced/arm64-support.md @@ -12,7 +12,7 @@ This manifest contains links to a Linux AMD64 as well as a Linux ARM64 image. ## Pulling the LocalStack image -With the multi-arch Docker manifest, your Docker client (and therefore the [LocalStack CLI](/aws/getting-started/installation/#localstack-cli)) now automatically selects the image according to your platform: +With the multi-arch Docker manifest, your Docker client (and therefore [`lstk`](/aws/developer-tools/running-localstack/lstk)) now automatically selects the image according to your platform: ```bash docker pull localstack/localstack diff --git a/src/content/docs/aws/customization/advanced/cross-account-access.md b/src/content/docs/aws/customization/advanced/cross-account-access.md index 32bd17af..906c9186 100644 --- a/src/content/docs/aws/customization/advanced/cross-account-access.md +++ b/src/content/docs/aws/customization/advanced/cross-account-access.md @@ -13,14 +13,17 @@ This document provides information to help design such setups. :::note Cross-account support in LocalStack is being actively developed. -Please report any issues on our [GitHub Discussions board](https://github.com/orgs/localstack/discussions/categories/bugs). +Please report any issues to [LocalStack Support](/aws/help-support/get-help). ::: Cross-account/cross-region access happens when a client attempts to access a resource in another account or region than what it is configured with: +The examples below select the account with the `--account` flag of `lstk aws`. +You can also set the account ID through the `AWS_ACCESS_KEY_ID` environment variable, for example `AWS_ACCESS_KEY_ID=111111111111 lstk aws ...`. + ```bash # Create a queue in one account and region -AWS_ACCESS_KEY_ID=111111111111 awslocal sqs create-queue \ +lstk aws --account 111111111111 sqs create-queue \ --queue-name my-queue \ --region ap-south-1 ``` @@ -33,14 +36,14 @@ AWS_ACCESS_KEY_ID=111111111111 awslocal sqs create-queue \ ```bash # Set some attributes -AWS_ACCESS_KEY_ID=111111111111 awslocal sqs set-queue-attributes \ +lstk aws --account 111111111111 sqs set-queue-attributes \ --attributes VisibilityTimeout=60 \ --queue-url http://sqs.ap-south-1.localhost.localstack.cloud:443/111111111111/my-queue \ --region ap-south-1 # Retrieve the queue attribute from another account and region # The required information for LocalStack to locate the queue is available in the queue URL -AWS_ACCESS_KEY_ID=222222222222 awslocal sqs get-queue-attributes \ +lstk aws --account 222222222222 sqs get-queue-attributes \ --attribute-names VisibilityTimeout \ --region eu-central-1 \ --queue-url http://sqs.ap-south-1.localhost.localstack.cloud:443/111111111111/my-queue diff --git a/src/content/docs/aws/customization/advanced/filesystem.mdx b/src/content/docs/aws/customization/advanced/filesystem.mdx index cd00e083..14a71fd6 100644 --- a/src/content/docs/aws/customization/advanced/filesystem.mdx +++ b/src/content/docs/aws/customization/advanced/filesystem.mdx @@ -100,12 +100,17 @@ In this case, the effective layout would be something like: - zipfile.4986fb95 -### Using the CLI +### Using lstk -When using the CLI to start LocalStack, the volume directory can be configured via the `LOCALSTACK_VOLUME_DIR`. -It should point to a directory on the host which is then automatically mounted into `/var/lib/localstack`. -The defaults are: +When using [`lstk`](/aws/developer-tools/running-localstack/lstk) to start LocalStack, the volume directory is configured with the `volume` field on a container block. +It should point to a directory on the host which is then automatically mounted into `/var/lib/localstack`: -- Mac: `~/Library/Caches/localstack/volume` -- Linux: `~/.cache/localstack/volume` -- Windows: `%LOCALAPPDATA%\cache\localstack\volume` +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +volume = "./volume" +``` + +If `volume` is not set, `lstk` defaults to `/lstk/volume/`. +Run [`lstk volume path`](/aws/developer-tools/running-localstack/lstk#volume) to print the resolved directory. diff --git a/src/content/docs/aws/customization/advanced/initialization-hooks.mdx b/src/content/docs/aws/customization/advanced/initialization-hooks.mdx index 2eb72067..547dc4e8 100644 --- a/src/content/docs/aws/customization/advanced/initialization-hooks.mdx +++ b/src/content/docs/aws/customization/advanced/initialization-hooks.mdx @@ -123,15 +123,16 @@ If you have more complex states, [Cloud Pods](/aws/developer-tools/snapshots/clo To execute aws cli commands when LocalStack becomes ready, simply create a script `init-aws.sh` and mount it into `/etc/localstack/init/ready.d/`. Make sure the script is executable: run `chmod +x init-aws.sh` on the file first. -You can use anything available inside the container, including `awslocal`: +You can use anything available inside the container, and can install new software: ```bash #!/bin/bash -export AWS_ACCESS_KEY_ID=000000000000 AWS_SECRET_ACCESS_KEY=000000000000 +npm install -g @localstack/lstk +lstk setup aws -awslocal s3 mb s3://my-bucket -awslocal sqs create-queue --queue-name my-queue +lstk aws s3 mb s3://my-bucket +lstk aws sqs create-queue --queue-name my-queue ``` Start Localstack: @@ -153,11 +154,22 @@ services: - "/var/run/docker.sock:/var/run/docker.sock" ``` - -```bash -# DOCKER_FLAGS are additional parameters to the `docker run` command of localstack start + +Declare the bind mount and the `DEBUG` profile in your config file, then start LocalStack: + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["debug"] +volumes = ["/path/to/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh"] + +[env.debug] +DEBUG = "1" +``` -DOCKER_FLAGS='-v /path/to/init-aws.sh:/etc/localstack/init/ready.d/init-aws.sh' localstack start +```bash +lstk start ``` @@ -172,8 +184,8 @@ and for more details on running init hooks in development mode, you can check ou Start LocalStack with **`EXTENSION_AUTO_INSTALL="localstack-extension-terraform-init"`**. Mount a **`main.tf`** file into **`/etc/localstack/init/ready.d`** -When LocalStack starts up, it will install the extension, which in turn installs Terraform and [`tflocal`](https://github.com/localstack/terraform-local) into the container. -If one of the init stage directories contain a `main.tf` file, the extension will run `tflocal init` and `tflocal apply` on that directory. +When LocalStack starts up, it will install the extension, which in turn installs Terraform into the container. +If one of the init stage directories contain a `main.tf` file, the extension will run `terraform init` and `terraform apply` on that directory. ```terraform # main.tf @@ -210,11 +222,20 @@ services: - "/var/run/docker.sock:/var/run/docker.sock" ``` - + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["terraform-init"] +volumes = ["./main.tf:/etc/localstack/init/ready.d/main.tf"] + +[env.terraform-init] +EXTENSION_AUTO_INSTALL = "localstack-extension-terraform-init" +``` + ```bash -localstack start \ - -e EXTENSION_AUTO_INSTALL="localstack-extension-terraform-init" \ - -v ./main.tf:/etc/localstack/init/ready.d/main.tf +lstk start ``` @@ -222,7 +243,7 @@ localstack start \ You can wait for LocalStack to complete the startup process, and then print the created S3 bucket: ```bash -localstack wait && awslocal s3 ls +lstk aws s3 ls ``` The logs should show something like: diff --git a/src/content/docs/aws/customization/advanced/multi-account-setups.md b/src/content/docs/aws/customization/advanced/multi-account-setups.md index edecce81..b3146569 100644 --- a/src/content/docs/aws/customization/advanced/multi-account-setups.md +++ b/src/content/docs/aws/customization/advanced/multi-account-setups.md @@ -8,7 +8,7 @@ sidebar: :::note Please note that multi-accounts may not work for use-cases that have cross-account and cross-service access. -Please open a [GitHub Discussion](https://github.com/orgs/localstack/discussions/new/choose) to request and upvote for support for specific use-cases. +Please contact [LocalStack Support](/aws/help-support/get-help) to request support for specific use-cases. ::: LocalStack ships with multi-account support which allows namespacing based on AWS account ID. @@ -20,14 +20,13 @@ The Access Key ID field can be configured in the AWS CLI in multiple ways: pleas ## Examples -In following examples, we configure the AWS CLI account ID via environment variable. +In the following examples, we select the account ID with the `--account` flag of `lstk aws`. ```bash -AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 create-key-pair --key-name green-hospital +lstk aws --account 000000000001 ec2 create-key-pair --key-name green-hospital +lstk aws --account 000000000002 ec2 create-key-pair --key-name red-medicine -AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 create-key-pair --key-name red-medicine - -AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 describe-key-pairs +lstk aws --account 000000000001 ec2 describe-key-pairs { "KeyPairs": [ { @@ -37,7 +36,7 @@ AWS_ACCESS_KEY_ID=000000000001 awslocal ec2 describe-key-pairs ] } -AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 describe-key-pairs +lstk aws --account 000000000002 ec2 describe-key-pairs { "KeyPairs": [ { @@ -48,11 +47,17 @@ AWS_ACCESS_KEY_ID=000000000002 awslocal ec2 describe-key-pairs } ``` +Alternatively, you can set the account ID through the `AWS_ACCESS_KEY_ID` environment variable: + +```bash +AWS_ACCESS_KEY_ID=000000000001 lstk aws ec2 describe-key-pairs +``` + If no explicit Account ID is set, LocalStack falls back to default. In this example, no resources are returned. ```bash -awslocal ec2 describe-key-pairs +lstk aws ec2 describe-key-pairs { "KeyPairs": [] } diff --git a/src/content/docs/aws/customization/advanced/usage-tracking.md b/src/content/docs/aws/customization/advanced/usage-tracking.md index 45e5364d..449b4a57 100644 --- a/src/content/docs/aws/customization/advanced/usage-tracking.md +++ b/src/content/docs/aws/customization/advanced/usage-tracking.md @@ -96,7 +96,7 @@ Here is an example of a CLI invocation event: "client_time": "2022-08-30 14:46:54.116457" }, "payload": { - "cmd": "localstack config validate", + "cmd": "lstk start", "params": [ "file" ] diff --git a/src/content/docs/aws/customization/configuration-options.md b/src/content/docs/aws/customization/configuration-options.md index 7b25af40..b6f6235c 100644 --- a/src/content/docs/aws/customization/configuration-options.md +++ b/src/content/docs/aws/customization/configuration-options.md @@ -6,17 +6,33 @@ template: doc LocalStack exposes various configuration options to control its behaviour. -These options can be passed to LocalStack as environment variables like so: +With `lstk`, these options can be passed as `LOCALSTACK_`-prefixed environment variables when starting the container: ```bash -DEBUG=1 localstack start +LOCALSTACK_DEBUG=1 lstk start ``` +Alternatively, set them as named environment profiles in your config file and reference them from the container block: + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["debug"] + +[env.debug] +DEBUG = "1" +``` + +```bash +lstk start +``` + +See [Passing environment variables to the container](/aws/developer-tools/running-localstack/lstk#passing-environment-variables-to-the-container) for details. + To facilitate interoperability, configuration variables can be prefixed with `LOCALSTACK_` in docker. For instance, setting `LOCALSTACK_PERSISTENCE=1` is equivalent to `PERSISTENCE=1`. -You can also use [Profiles](#profiles). - Configurations marked as **Deprecated** will be removed in the next major version. You can find previously removed configuration variables under [Legacy](#legacy). @@ -44,13 +60,8 @@ Options that affect the core LocalStack system. ## CLI -These options are applicable when using the CLI to start LocalStack. - -| Variable | Example Values | Description | -| - | - | - | -| `LOCALSTACK_VOLUME_DIR` | `~/.cache/localstack/volume` (on Linux) | The location on the host of the LocalStack volume directory mount. See [Filesystem Layout](/aws/customization/advanced/filesystem#using-the-cli) | -| `CONFIG_PROFILE` | | The configuration profile to load. See [Profiles](#profiles) | -| `CONFIG_DIR` | `~/.localstack` | The path where LocalStack can find configuration profiles and other CLI-specific configuration | +`lstk` is configured through its config file rather than through environment variables. +See [Configuration](/aws/developer-tools/running-localstack/lstk#configuration) on the `lstk` page for the config file search order, the field reference, and how to define named environment profiles. ## Docker @@ -58,6 +69,7 @@ Options to configure how LocalStack interacts with Docker. | Variable | Example Values | Description | | - | - | - | +| `LOCALSTACK_VOLUME_DIR` | `~/.cache/localstack/volume` (on Linux) | The location on the host of the LocalStack volume directory mount. See [Filesystem Layout](/aws/customization/advanced/filesystem) | | `DOCKER_FLAGS` | | Allows to pass custom flags (e.g., volume mounts) to "docker run" when running LocalStack in Docker. | | `DOCKER_SOCK` | `/var/run/docker.sock` | Path to local Docker UNIX domain socket | | `DOCKER_BRIDGE_IP` | `172.17.0.1` | IP of the docker bridge used to enable access between containers | @@ -540,51 +552,3 @@ These configurations have already been removed and **won't have any effect** on | `TMPDIR`| 2.0.0 | `/tmp` (default) | Temporary folder on the host running the CLI and inside the LocalStack container .| | `USE_LIGHT_IMAGE` | 2.0.0 | `1` (default) | Whether to use the light-weight Docker image. Overwritten by `IMAGE_NAME`.| | `PORT_WEB_UI` | 0.12.8 | `8080` (default) | Port for the legacy Web UI. Replaced by our [Web Application](https://app.localstack.cloud) | - -## Profiles - -LocalStack supports configuration profiles which are stored in the `~/.localstack` config directory. -If the directory does not exist, create it manually. -A configuration profile is a set of environment variables stored in an `.env` file in the LocalStack config directory. - -Here is an example of what configuration profiles might look like: - -```bash -tree ~/.localstack -/home/username/.localstack -├── default.env -├── dev.env -└── pro.env -``` - -Here is an example of what a specific environment profile looks like - -```bash -cat ~/.localstack/pro-debug.env -LOCALSTACK_AUTH_TOKEN=XXXXX -DEBUG=1 -DEVELOP=1 -``` - -You can load a profile by either setting the `env` variable `CONFIG_PROFILE=` or the `--profile=` CLI flag when using the CLI. -Let's take an example to load the `dev.env` profile file if it exists: - -```bash -python -m localstack.cli.main --profile=dev start -``` - -If no profile is specified, the `default.env` profile will be loaded. -While explicitly specified, the environment variables will always overwrite the profile. - -To display the config environment variables, you can use the following command: - -```bash -python -m localstack.cli.main --profile=dev config show -``` - -:::note -The `CONFIG_PROFILE` is a CLI feature and cannot be used with a Docker/Docker Compose setup. -You can look at [alternative means of setting environment variables](https://docs.docker.com/compose/environment-variables/set-environment-variables/) for your Docker Compose setups. - -For Docker setups, we recommend passing the environment variables directly to the `docker run` command. -::: diff --git a/src/content/docs/aws/customization/integrations/app-frameworks/aspire.md b/src/content/docs/aws/customization/integrations/app-frameworks/aspire.md index d9dbf289..e003f0f4 100644 --- a/src/content/docs/aws/customization/integrations/app-frameworks/aspire.md +++ b/src/content/docs/aws/customization/integrations/app-frameworks/aspire.md @@ -12,7 +12,7 @@ sidebar: With Aspire, developers can orchestrate cloud-native applications locally using the same AWS resources they deploy in production. By combining Aspire with LocalStack, teams can emulate their full cloud environment—including Lambda, SQS, S3, and DynamoDB—with minimal configuration and no AWS costs. -LocalStack integrates with Aspire through the [`LocalStack.Aspire.Hosting`](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) package, enabling seamless local development and testing of AWS-powered applications within the Aspire orchestration framework. This package extends the official [AWS integrations for .NET Aspire](https://github.com/aws/customization/integrations-on-dotnet-aspire-for-aws) to provide LocalStack-specific functionality. +LocalStack integrates with Aspire through the [`LocalStack.Aspire.Hosting`](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) package, enabling seamless local development and testing of AWS-powered applications within the Aspire orchestration framework. This package extends the official [AWS integrations for .NET Aspire](https://github.com/aws/integrations-on-dotnet-aspire-for-aws) to provide LocalStack-specific functionality. ## Getting started @@ -168,7 +168,7 @@ An event registration system showcasing distributed tracing and observability pa - [Aspire Documentation](https://aspire.dev/) - [LocalStack.Aspire.Hosting on GitHub](https://github.com/localstack-dotnet/dotnet-aspire-for-localstack) - [LocalStack.Client on GitHub](https://github.com/localstack-dotnet/localstack-dotnet-client) -- [AWS Aspire Integration](https://github.com/aws/customization/integrations-on-dotnet-aspire-for-aws) +- [AWS Aspire Integration](https://github.com/aws/integrations-on-dotnet-aspire-for-aws) - [AWS SDK for .NET Documentation](https://docs.aws.amazon.com/sdk-for-net/) - [LocalStack Serverless .NET Demo](https://github.com/localstack-dotnet/localstack-serverless-dotnet-demo) - [OpenTelemetry with Aspire and LocalStack Demo](https://github.com/Blind-Striker/dotnet-otel-aspire-localstack-demo) diff --git a/src/content/docs/aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster.md b/src/content/docs/aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster.md index 041fa817..e82b1bce 100644 --- a/src/content/docs/aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster.md +++ b/src/content/docs/aws/customization/integrations/app-frameworks/selfmanaged-kafka-cluster.md @@ -22,7 +22,7 @@ docker-compose up -d 2. Create the Lambda function: ```bash showshowLineNumbers -awslocal lambda create-function \ +lstk aws lambda create-function \ --function-name fun1 \ --handler lambda.handler \ --runtime python3.8 \ @@ -54,7 +54,7 @@ awslocal lambda create-function \ 3. Create an example secret: ```bash showshowLineNumbers -awslocal secretsmanager create-secret --name localstack +lstk aws secretsmanager create-secret --name localstack { "ARN": "arn:aws:secretsmanager:us-east-1:000000000000:secret:localstack-TDIuI", "Name": "localstack", @@ -72,7 +72,7 @@ Created topic t1. 5. Create the event source mapping to your local kafka cluster: ```bash showshowLineNumbers -awslocal lambda create-event-source-mapping \ +lstk aws lambda create-event-source-mapping \ --topics t1 \ --source-access-configuration Type=SASL_SCRAM_512_AUTH,URI=arn:aws:secretsmanager:us-east-1:000000000000:secret:localstack-TDIuI \ --function-name arn:aws:lambda:us-east-1:000000000000:function:fun1 \ diff --git a/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx b/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx index 8a9aa5c6..42c50521 100644 --- a/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx +++ b/src/content/docs/aws/customization/integrations/extensions/developing-extensions.mdx @@ -150,6 +150,11 @@ reference points to the plugin class. ## Using the extensions developer CLI +:::note +The new CLI experience, `lstk`, does not support LocalStack Extensions. There is no `lstk extensions` command suite. +Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) for the commands in this section. +::: + The extensions CLI has a set of developer commands that allow you to create new extensions, and toggle local dev mode for extensions. Extensions that are toggled for developer mode will be mounted into the localstack container so you don't need to re-install them every time you change something. diff --git a/src/content/docs/aws/customization/integrations/extensions/index.md b/src/content/docs/aws/customization/integrations/extensions/index.md index 102905a2..19d93b21 100644 --- a/src/content/docs/aws/customization/integrations/extensions/index.md +++ b/src/content/docs/aws/customization/integrations/extensions/index.md @@ -31,4 +31,7 @@ Our [MailHog tutorial](/aws/customization/integrations/extensions/mailhog) teach :::note The feature and the API are currently in preview stage and may be subject to change. Please report any issues or feature requests on [LocalStack Extension's GitHub repository](https://github.com/localstack/localstack-extensions). + +The new CLI experience, `lstk`, does not support LocalStack Extensions. There is no `lstk extensions` command suite. +Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) to install, manage, and develop extensions. ::: diff --git a/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx b/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx index 1e0bb5df..ea613995 100644 --- a/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx +++ b/src/content/docs/aws/customization/integrations/extensions/managing-extensions.mdx @@ -33,6 +33,11 @@ However, you may lose LocalStack state if you do not use persistence. ## Using the extensions CLI +:::note +The new CLI experience, `lstk`, does not support LocalStack Extensions. There is no `lstk extensions` command suite. +Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) for the commands in this section. +::: + If you use LocalStack with the CLI, you can also use our `localstack extensions` CLI command suite. To get a list of all available commands in LocalStack Extensions, run: diff --git a/src/content/docs/aws/customization/integrations/testing/lambdatest-hyperexecute.md b/src/content/docs/aws/customization/integrations/testing/lambdatest-hyperexecute.md index fde2c8c8..04831388 100644 --- a/src/content/docs/aws/customization/integrations/testing/lambdatest-hyperexecute.md +++ b/src/content/docs/aws/customization/integrations/testing/lambdatest-hyperexecute.md @@ -36,22 +36,24 @@ parallelism: 2 concurrency: 2 scenarioCommandStatusOnly: true runtime: - language: python - version: 3.10 + - language: python + version: '3.10' + - language: node + version: '18' pre: - - pip install localstack awscli awscli-local - - localstack start -d - - localstack wait -t 60 - - awslocal s3 mb s3://test-bucket - - awslocal sqs create-queue --queue-name test-queue - - awslocal sns create-topic --name test-topic + - npm install -g @localstack/lstk + - pip install awscli + - LOCALSTACK_AUTH_TOKEN=${{ .secrets.LOCALSTACK_AUTH_TOKEN }} lstk start --non-interactive --timeout 60s + - lstk aws s3 mb s3://test-bucket + - lstk aws sqs create-queue --queue-name test-queue + - lstk aws sns create-topic --name test-topic ``` The above minimal configuration file starts LocalStack and creates an S3 bucket, SQS queue, and SNS topic. :::note -To use the LocalStack for AWS image, configure a LocalStack Auth Token by appending `LOCALSTACK_AUTH_TOKEN=${{ .secrets.LOCALSTACK_AUTH_TOKEN }}` to the `localstack start` command. -Subsequently, you need to add your LocalStack Auth Token to your HyperExecute Portal as a secret. +`lstk` requires a LocalStack Auth Token, and CI environments need a [CI Auth Token](/aws/getting-started/auth-token/) rather than a personal Developer Token. +Add it to your HyperExecute Portal as a secret named `LOCALSTACK_AUTH_TOKEN` so `${{ .secrets.LOCALSTACK_AUTH_TOKEN }}` resolves at runtime. ::: ### Enabling test execution on HyperExecute diff --git a/src/content/docs/aws/customization/kubernetes/openshift.md b/src/content/docs/aws/customization/kubernetes/openshift.md index be460aea..767245b1 100644 --- a/src/content/docs/aws/customization/kubernetes/openshift.md +++ b/src/content/docs/aws/customization/kubernetes/openshift.md @@ -23,7 +23,7 @@ If you have any questions or uncertainties regarding the licensing implications, ## Getting started -This guide is designed for users new to LocalStack and assumes basic knowledge of the AWS CLI and our [`awslocal`](https://github.com/localstack/awscli-local) wrapper script. +This guide is designed for users new to LocalStack and assumes basic knowledge of the AWS CLI and our [`lstk aws` AWS CLI proxy](/aws/developer-tools/running-localstack/lstk#aws). As a general prerequisite, you should have access to the [OpenShift Web Console](https://docs.openshift.com/container-platform/4.14/web_console/web-console-overview.html). We will demonstrate how you can create local AWS resources using LocalStack using the AWS CLI. @@ -69,25 +69,32 @@ Click on the **localstack-dev-spaces** pod to view the details. You will be able to see the exposed route for the LocalStack container. Copy the route URL and use it to interact with the LocalStack container. -To create an S3 bucket and an SQS queue, run the following commands: +Since LocalStack is running on the cluster rather than on your machine, point `lstk` at the exposed route instead of its default local endpoint. +Set `LSTK_ENDPOINT_URL` once for the whole session: ```bash -export AWS_ENDPOINT_URL='' -awslocal s3 mb s3://my-bucket -awslocal sqs create-queue --queue-name my-queue +export LSTK_ENDPOINT_URL='' +lstk aws s3 mb s3://my-bucket +lstk aws sqs create-queue --queue-name my-queue +``` + +Alternatively, pass the global `--endpoint-url` flag per command: + +```bash +lstk --endpoint-url '' aws s3 mb s3://my-bucket +lstk --endpoint-url '' aws sqs create-queue --queue-name my-queue ``` In the above commands, replace `` with the route URL of the LocalStack container. -The `AWS_ENDPOINT_URL` environment variable is used to specify the endpoint URL of the LocalStack container. :::note -By default, the endpoint URL for `awslocal` is `http://localhost:4566`. -Since we are running LocalStack on OpenShift, we need to specify the route URL of the LocalStack container. -You can swap `awslocal` with the AWS CLI, by specifying the additional `--endpoint-url` parameter. +By default, `lstk aws` targets the emulator on your local machine. +Since we are running LocalStack on OpenShift, we need to specify the route URL of the LocalStack container, using either `LSTK_ENDPOINT_URL` or `--endpoint-url`. +The flag takes precedence over the environment variable. ::: -You can further use integrations, such as [CDK](https://docs.localstack.cloud/user-guide/integrations/aws-cdk/), [SAM CLI](https://docs.localstack.cloud/user-guide/integrations/aws-sam/), and [Terraform](https://docs.localstack.cloud/user-guide/integrations/terraform/), to interact with the Ephemeral Instance. -In these integrations, you can change the `AWS_ENDPOINT_URL` environment variable to the endpoint URL of the Ephemeral Instance. +You can further use the other `lstk` tool proxies, such as [`lstk cdk`](/aws/developer-tools/running-localstack/lstk#cdk), [`lstk sam`](/aws/developer-tools/running-localstack/lstk#sam), and [`lstk terraform`](/aws/developer-tools/running-localstack/lstk#terraform), to interact with the deployment. +As with `lstk aws`, set `LSTK_ENDPOINT_URL` or pass `--endpoint-url` to point these at the route URL instead of a local emulator. ### Deleting the LocalStack deployment diff --git a/src/content/docs/aws/customization/logging.md b/src/content/docs/aws/customization/logging.md index 1684408c..4b5fa784 100644 --- a/src/content/docs/aws/customization/logging.md +++ b/src/content/docs/aws/customization/logging.md @@ -4,7 +4,7 @@ description: Control LocalStack log output, verbosity, and error reporting. template: doc --- -LocalStack supports logging output and error reporting through the `localstack` CLI or a Docker/Docker Compose based setup. +LocalStack supports logging output and error reporting through the `lstk` CLI or a Docker/Docker Compose based setup. LocalStack's logging setup allows you to: - Discover errors in your code during development & testing. @@ -52,11 +52,22 @@ Requests to HTTP endpoints are logged in a similar way. ## Log inspection -You can inspect the logs of the LocalStack container using the `localstack` CLI or your Docker/Docker Compose setup. -With the `localstack` CLI, you can run the following command to inspect the logs of the LocalStack container: +You can inspect the logs of the LocalStack container using [`lstk`](/aws/developer-tools/running-localstack/lstk) or your Docker/Docker Compose setup. +With `lstk`, you can run the following command to inspect the logs of the LocalStack container: ```bash -localstack logs +lstk logs +``` + +By default this prints the currently available logs, with noisy internal lines filtered out. +Add `--follow` to stream logs in real time, and `--verbose` to show every line unfiltered: + +```bash +# Stream filtered logs in real-time +lstk logs --follow + +# Stream all logs without filtering +lstk logs --follow --verbose ``` With Docker/Docker-Compose, you can run `docker ps` to get the container ID of the LocalStack container and then run `docker logs ` to inspect the logs. diff --git a/src/content/docs/aws/customization/networking/accessing-endpoint-url.mdx b/src/content/docs/aws/customization/networking/accessing-endpoint-url.mdx index 36ace0ab..7f9c3275 100644 --- a/src/content/docs/aws/customization/networking/accessing-endpoint-url.mdx +++ b/src/content/docs/aws/customization/networking/accessing-endpoint-url.mdx @@ -16,7 +16,7 @@ This documentation provides step-by-step guidance on how to access LocalStack se Suppose you have LocalStack installed on your machine and want to access it using the AWS CLI. To connect, you must expose port 4566 from your LocalStack instance and connect to `localhost` or a domain name that points to `localhost`. -While the LocalStack CLI does this automatically, when running the Docker container directly or with docker compose, you must configure it manually. +While [`lstk`](/aws/developer-tools/running-localstack/lstk) does this automatically, when running the Docker container directly or with docker compose, you must configure it manually. Check out the [getting started documentation](/aws/getting-started/installation) for more information. :::tip @@ -93,7 +93,6 @@ All subdomains of `localhost.localstack.cloud` will also resolve to the LocalSta To configure your application container: -* add a user-managed docker network; * either determine your LocalStack container IP, or configure your LocalStack container to have a fixed known IP address; * set the DNS server of your application container to the IP address of the LocalStack container. @@ -101,16 +100,15 @@ To configure your application container: ```bash # start localstack -localstack start -d --network ls -localstack wait +lstk start # get the ip address of the LocalStack container -docker inspect localstack-main | \ +docker inspect localstack-aws | \ jq -r '.[0].NetworkSettings.Networks | to_entries | .[].value.IPAddress' # prints 172.27.0.2 # run your application container -docker run --rm -it --dns 172.27.0.2 --network ls +docker run --rm -it --dns 172.27.0.2 ``` @@ -234,9 +232,19 @@ Please update your LocalStack container and see the [instructions](#from-your-co LocalStack must listen to the address of the host, or `0.0.0.0`. - + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +env = ["listen-all"] + +[env.listen-all] +GATEWAY_LISTEN = "0.0.0.0" +``` + ```bash -GATEWAY_LISTEN="0.0.0.0" localstack start +lstk start ``` diff --git a/src/content/docs/aws/customization/networking/dns-server.md b/src/content/docs/aws/customization/networking/dns-server.md index 4c77bf77..00597aa2 100644 --- a/src/content/docs/aws/customization/networking/dns-server.md +++ b/src/content/docs/aws/customization/networking/dns-server.md @@ -130,8 +130,15 @@ Remember to save the default configuration and restore it after testing. 1. Expose the LocalStack DNS server: - a) Since version 3.5, the LocalStack CLI does not publish port `53` anymore by default. - Use the CLI flag `--host-dns` to expose the port on the host. + a) `lstk` does not publish port `53` on the host by default. + Add `expose_ports = [53]` to the container block in your `config.toml` to expose it: + + ```toml + # .lstk/config.toml + [[containers]] + type = "aws" + expose_ports = [53] + ``` b) For Docker Compose, add the following port mappings to your `docker-compose.yml`: @@ -189,6 +196,11 @@ Start LocalStack for AWS with `DNS_ADDRESS=127.0.0.1` as environment variable. This makes LocalStack bind port 53 on 127.0.0.1, whereas systemd-resolved binds its stub resolver to 127.0.0.53:53, which prevents a conflict. Once LocalStack is started, you can test the DNS server using `dig @127.0.0.1 s3.amazonaws.com` versus `dig @127.0.0.53 s3.amazonaws.com`, the former should return an A record `127.0.0.1`, the latter the real AWS DNS result. +:::caution +The `dns` command is only available in the [deprecated LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli#dns-systemd-resolved). +`lstk` has no equivalent command, so these steps require the legacy `localstack` CLI. +::: + Run: ```bash diff --git a/src/content/docs/aws/customization/networking/external-port-range.mdx b/src/content/docs/aws/customization/networking/external-port-range.mdx index 1fc870e9..bc7b8677 100644 --- a/src/content/docs/aws/customization/networking/external-port-range.mdx +++ b/src/content/docs/aws/customization/networking/external-port-range.mdx @@ -6,8 +6,6 @@ sidebar: order: 3 --- -import { Tabs, TabItem } from '@astrojs/starlight/components'; - ## Introduction LocalStack provides local cloud services, such as [OpenSearch](/aws/services/opensearch) or [Elasticsearch](/aws/services/es), which might utilize external software bound to specific ports. @@ -41,17 +39,8 @@ By adjusting these environment variables, you can customize the port range accor If you wish to run multiple instances of LocalStack simultaneously, it is essential to ensure that the edge port (default: `4566`) and external service ports are mapped to non-overlapping ranges. -Here's how you can achieve this using when either using the CLI or docker-compose to start your LocalStack instances: +Here's how you can achieve this using docker-compose to start your LocalStack instances: - - -```bash -GATEWAY_LISTEN=0.0.0.0:4566 EXTERNAL_SERVICE_PORTS_START=4510 EXTERNAL_SERVICE_PORTS_END=4559 MAIN_CONTAINER_NAME=localstack-main-1 localstack start -GATEWAY_LISTEN=0.0.0.0:4666 EXTERNAL_SERVICE_PORTS_START=4610 EXTERNAL_SERVICE_PORTS_END=4659 MAIN_CONTAINER_NAME=localstack-main-2 localstack start -GATEWAY_LISTEN=0.0.0.0:4766 EXTERNAL_SERVICE_PORTS_START=4710 EXTERNAL_SERVICE_PORTS_END=4759 MAIN_CONTAINER_NAME=localstack-main-3 localstack start -``` - - ```yaml showshowLineNumbers services: localstack-main-1: @@ -99,9 +88,7 @@ services: - "${LOCALSTACK_VOLUME_DIR:-./volume}:/var/lib/localstack" - "/var/run/docker.sock:/var/run/docker.sock" ``` - - By customizing the `GATEWAY_LISTEN` and `EXTERNAL_SERVICE_PORTS_START`/`EXTERNAL_SERVICE_PORTS_END` values for each instance, you can ensure that they operate on distinct port ranges, preventing any conflicts and enabling smooth execution of multiple LocalStack instances. -Please make sure to set `MAIN_CONTAINER_NAME` for following usages of the LocalStack CLI to specify which instance of LocalStack you want to address with the specific CLI command. +Each instance is given a distinct `MAIN_CONTAINER_NAME` so that it can be addressed individually. diff --git a/src/content/docs/aws/customization/other-installations/devcontainers.mdx b/src/content/docs/aws/customization/other-installations/devcontainers.mdx index 2aba6f90..53ea4617 100644 --- a/src/content/docs/aws/customization/other-installations/devcontainers.mdx +++ b/src/content/docs/aws/customization/other-installations/devcontainers.mdx @@ -19,6 +19,11 @@ You can use the following two approaches to set up LocalStack with DevContainers ## LocalStack Templates +:::note +The LocalStack DevContainer templates and Feature install the legacy `localstack` CLI, not the new CLI experience, `lstk`. +The commands and configuration keys on this page therefore refer to the [legacy LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/), which is what is available inside the DevContainer. +::: + LocalStack provides two different approaches for [Templates](https://github.com/localstack/devcontainer-template) which can be used via [supporting tools](https://containers.dev/supporting). | **Type** | **Advantages** | **Disadvantages** | diff --git a/src/content/docs/aws/customization/other-installations/enterprise-image.md b/src/content/docs/aws/customization/other-installations/enterprise-image.md index 436f4515..15900e62 100644 --- a/src/content/docs/aws/customization/other-installations/enterprise-image.md +++ b/src/content/docs/aws/customization/other-installations/enterprise-image.md @@ -27,11 +27,20 @@ This offline functionality is enabled by: - After the image is pushed to the customer-specific ECR repository, the customer can pull and push it to their internal Docker registry. - Developers within the customer’s network can then pull the image from this registry. -- To use the image from the command line interface (CLI), set the `IMAGE_NAME` configuration to the name of the Enterprise image, typically using the command: +- To use the image from the command line interface (CLI), set the `image` field on the container block to the name of the Enterprise image: + ```toml + # .lstk/config.toml + [[containers]] + type = "aws" + image = "localstack-enterprise" + ``` + ```bash - IMAGE_NAME=localstack-enterprise localstack start + lstk start ``` + See [Custom container image](/aws/developer-tools/running-localstack/lstk#custom-container-image) for details, including how `lstk` falls back to a locally present image when a pull fails. + ## "Online" vs "Offline" image This section compares the standard [LocalStack for AWS Docker image](/aws/customization/other-installations/docker-images) ("online") with the customer-specific Enterprise image ("offline"). diff --git a/src/content/docs/aws/customization/other-installations/podman.md b/src/content/docs/aws/customization/other-installations/podman.md index e30bcf96..85744221 100644 --- a/src/content/docs/aws/customization/other-installations/podman.md +++ b/src/content/docs/aws/customization/other-installations/podman.md @@ -10,6 +10,11 @@ By default, the LocalStack CLI starts the LocalStack runtime inside a Docker con Docker may not be available on your system, and a popular alternative is [Podman](https://podman.io/get-started) which you can use to run LocalStack. Podman support is still experimental, and the following docs give you an overview of the current state. +:::note +The new CLI experience, `lstk`, does not yet fully support Podman. +The commands and environment variables on this page refer to the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/), which you should continue to use for Podman setups. +::: + From the Podman docs: > Podman is a daemonless, open source, Linux native tool designed to make it easy to find, run, build, share and deploy applications using Open Containers Initiative (OCI) Containers and Container Images. diff --git a/src/content/docs/aws/customization/other-installations/rancher-desktop.mdx b/src/content/docs/aws/customization/other-installations/rancher-desktop.mdx index 3f0f8b3a..631a55a0 100644 --- a/src/content/docs/aws/customization/other-installations/rancher-desktop.mdx +++ b/src/content/docs/aws/customization/other-installations/rancher-desktop.mdx @@ -16,6 +16,11 @@ It utilizes `containerd` and `dockerd`, enabling users to easily switch between By default, the LocalStack CLI launches the LocalStack runtime inside a Docker container. However, if Docker is not available on your system, you can use Rancher Desktop as a popular alternative to run LocalStack. +:::note +The new CLI experience, `lstk`, does not yet fully support Rancher Desktop. +The commands and environment variables on this page refer to the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/), which you should continue to use for Rancher Desktop setups. +::: + ## Getting started To run LocalStack using Rancher Desktop, simply aliasing Docker commands to Rancher Desktop's `dockerd` service may not be sufficient for these reasons: diff --git a/src/content/docs/aws/services/opensearch.mdx b/src/content/docs/aws/services/opensearch.mdx index d4452bb0..881a3942 100644 --- a/src/content/docs/aws/services/opensearch.mdx +++ b/src/content/docs/aws/services/opensearch.mdx @@ -243,10 +243,19 @@ When using OpenSearch Dashboards with LocalStack, you need to make sure to: - Ensure that the OpenSearch Dashboards Docker container uses the LocalStack DNS. You can find more information on how to connect your Docker container to Localstack in our [Network Troubleshooting guide](/aws/customization/networking/). -First, you need to make sure to start LocalStack in a specific Docker network: +First, you need to create a dedicated Docker network and start LocalStack within it (note: custom networks are not supported by the `lstk` CLI) ```bash -localstack start --network ls +docker network create ls + +docker run \ + -d --rm \ + --name localstack-main \ + --network ls \ + -p 127.0.0.1:4566:4566 \ + -p 127.0.0.1:4510-4559:4510-4559 \ + -v /var/run/docker.sock:/var/run/docker.sock \ + localstack/localstack ``` Now you can provision a new OpenSearch domain. diff --git a/src/content/docs/aws/services/route53.mdx b/src/content/docs/aws/services/route53.mdx index 9e7d48fd..64bbde4d 100644 --- a/src/content/docs/aws/services/route53.mdx +++ b/src/content/docs/aws/services/route53.mdx @@ -20,9 +20,18 @@ LocalStack supports routing traffic to various AWS resources including [S3 stati LocalStack also integrates with its DNS server to respond to DNS queries with these domains. :::note -LocalStack CLI does not publish port `53` anymore by default. -Use the CLI flag `--host-dns` to expose the port on the host. -This would be required if you want to reach out to Route53 domain names from your host machine, using the LocalStack DNS server. +`lstk` does not publish port `53` on the host by default. +Add `expose_ports = [53]` to the container block in your `config.toml` to expose it: + +```toml +# .lstk/config.toml +[[containers]] +type = "aws" +expose_ports = [53] +``` + +This is required if you want to reach out to Route53 domain names from your host machine, using the LocalStack DNS server. +See [System DNS configuration](/aws/customization/networking/dns-server#system-dns-configuration) for details. ::: ## Getting started