docs(aws/developer-tools): migrate /aws/developer-tools section to use lstk (#815)

Author: peter-smith-phd

astro.config.mjs

@@ -482,10 +482,6 @@ export default defineConfig({
                       label: 'Overview',
                       slug: 'aws/developer-tools/running-localstack',
                     },
-                    {
-                      label: 'LocalStack CLI',
-                      slug: 'aws/developer-tools/running-localstack/localstack-cli',
-                    },
                     {
                       label: 'lstk CLI',
                       slug: 'aws/developer-tools/running-localstack/lstk',
@@ -498,6 +494,10 @@ export default defineConfig({
                       label: 'LocalStack Desktop',
                       slug: 'aws/developer-tools/running-localstack/localstack-desktop',
                     },
+                    {
+                      label: 'Deprecated LocalStack CLI',
+                      slug: 'aws/developer-tools/running-localstack/localstack-cli',
+                    },
                   ],
                 },
                 {

src/components/SectionCards.astro

@@ -7,9 +7,10 @@ interface Props {
   title?: string;
   customTitles?: Record<string, string>;
   useDirectFiles?: boolean;
+  excludeFiles?: string[];
 }
 
-const { basePath, title, customTitles = {}, useDirectFiles = false } = Astro.props;
+const { basePath, title, customTitles = {}, useDirectFiles = false, excludeFiles = [] } = Astro.props;
 
 // Get sections - either index files from subdirectories or direct files
 const allSections = await getCollection('docs', ({ id }) => {
@@ -49,14 +50,18 @@ const sortedSections = allSections.sort((a, b) => {
   return titleA.localeCompare(titleB);
 });
 
-const sectionData = sortedSections.map(section => {
+const sectionData = sortedSections.flatMap(section => {
   // Extract the key name from the section ID
   const relativePath = section.id.substring(basePath.length);
   const keyName = relativePath.split('/').filter(part => part !== '')[0];
-  
+
   // For direct files, we need to remove the file extension from the key
   const cleanKey = useDirectFiles ? keyName.replace(/\.(md|mdx)$/, '') : keyName;
-  
+
+  if (excludeFiles.includes(cleanKey)) {
+    return [];
+  }
+
   // Use custom title if provided, otherwise fall back to the section title
   const sectionTitle = customTitles[cleanKey] || section.data.title || section.data.linkTitle || 'Unknown Section';
   const description = section.data.description || `Learn more about ${sectionTitle}`;

src/content/docs/aws/developer-tools/aws-replicator/index.mdx

@@ -20,17 +20,14 @@ LocalStack AWS Replicator creates identical copies of AWS resources in a running
 This means that external resources can easily be replicated before deploying the main application, and removes the need to change existing stacks or create custom infrastructure, making LocalStack setup easier.
 
 :::note
-The AWS Replicator is in a preview state, supporting only [selected resources](#supported-resources).
+The AWS Replicator is in a preview state, supporting only [selected resources](#supported-resources). The new CLI experience, `lstk`, does not yet support the AWS Replicator. 
+Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) version 4.2.0 or newer.
 :::
 
 ## Getting started
 
 A valid `LOCALSTACK_AUTH_TOKEN` must be configured to start the LocalStack for AWS image.
 
-:::note
-The Replicator is in limited preview and is available from LocalStack CLI version 4.2.0.
-If you encounter issues, update your [LocalStack CLI](/aws/getting-started/installation/#update-localstack-cli).
-:::
 
 ### Retrieve credentials to access AWS
 

src/content/docs/aws/developer-tools/chaos-engineering/chaos-api.md

@@ -33,7 +33,7 @@ If you'd like to try it out, please [contact us](https://www.localstack.cloud/de
 
 The prerequisites for this guide are:
 
-- LocalStack for AWS and [LocalStack CLI](/aws/getting-started/installation/) 
+- LocalStack for AWS and [`lstk`](/aws/developer-tools/running-localstack/lstk/#installation)
 - [LocalStack Auth Token](/aws/getting-started/auth-token/)
 - [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/install/)
 - [Python](https://www.python.org/downloads/)
@@ -119,7 +119,7 @@ All calls to these services in these regions will return a 503 Service Unavailab
 To see this in action, try to create an S3 bucket in `us-east-1`:
 
 ```bash
-awslocal s3 mb s3://test-bucket --region us-east-1
+lstk aws s3 mb s3://test-bucket --region us-east-1
 ```
 
 ```bash
@@ -129,7 +129,7 @@ make_bucket failed: s3://test-bucket An error occurred (ServiceUnavailableExcept
 However, the same operation, when run in `eu-central-1` will work as expected.
 
 ```bash
-awslocal s3 mb s3://test-bucket --region eu-central-1
+lstk aws s3 mb s3://test-bucket --region eu-central-1
 ```
 
 ```bash

src/content/docs/aws/developer-tools/cloud-sandbox/app-preview.md

@@ -105,7 +105,7 @@ preview-cmd: |
     make deploy;
     make build-frontend;
     make deploy-frontend;
-    distributionId=$(awslocal cloudfront list-distributions | jq -r '.DistributionList.Items[0].Id');
+    distributionId=$(lstk aws cloudfront list-distributions | jq -r '.DistributionList.Items[0].Id');
     echo LS_PREVIEW_URL=$AWS_ENDPOINT_URL/cloudfront/$distributionId/ >> $GITHUB_ENV;
 ```
 

src/content/docs/aws/developer-tools/cloud-sandbox/ephemeral-instances.md

@@ -13,7 +13,8 @@ Ephemeral Instances allows you to run a LocalStack instance in the cloud.
 You can interact with these instances via the LocalStack Web Application, or by configuring your integrations and developer tools with the endpoint URL of the ephemeral instance.
 
 :::note
-Ephemeral Instances is offered as a **preview** feature and is under active development.
+Ephemeral Instances is offered as a **preview** feature. `lstk` does not yet support Ephemeral Instances.
+Continue using the legacy [LocalStack CLI](/aws/developer-tools/running-localstack/localstack-cli/) for this feature.
 :::
 
 ## Getting started

src/content/docs/aws/developer-tools/lambda-tools/hot-reloading.mdx

@@ -142,7 +142,7 @@ To create the Lambda function, you just need to take care of two things:
 So, using the AWS example, this would be:
 
 ```bash
-awslocal lambda create-function --function-name my-cool-local-function \
+lstk aws lambda create-function --function-name my-cool-local-function \
     --code S3Bucket="hot-reload",S3Key="/tmp/aws-doc-sdk-examples/python/example_code/lambda" \
     --handler lambda_handler_basic.lambda_handler \
     --runtime python3.8 \
@@ -153,23 +153,12 @@ You can also check out some of our [Deployment Configuration Examples](#deployme
 
 We can also quickly make sure that it works by invoking it with a simple payload:
 
-<Tabs>
-<TabItem label="AWS CLI v1">
 ```bash
-awslocal lambda invoke --function-name my-cool-local-function \
-    --payload '{"action": "increment", "number": 3}' \
-    output.txt
-```
-</TabItem>
-<TabItem label="AWS CLI v2">
-```bash
-awslocal lambda invoke --function-name my-cool-local-function \
+lstk aws lambda invoke --function-name my-cool-local-function \
     --cli-binary-format raw-in-base64-out \
     --payload '{"action": "increment", "number": 3}' \
     output.txt
 ```
-</TabItem>
-</Tabs>
 
 The invocation returns itself returns:
 
@@ -332,10 +321,10 @@ To create the Lambda function, you need to take care of two things:
 * Set the S3 key to the path of the directory your lambda function resides in.
   The handler is then referenced by the filename of your lambda code and the function in that code that needs to be invoked.
 
-Create the Lambda Function using the `awslocal` CLI:
+Create the Lambda Function using `lstk aws`:
 
 ```bash
-awslocal lambda create-function \
+lstk aws lambda create-function \
     --function-name hello-world \
     --runtime "nodejs16.x" \
     --role arn:aws:iam::123456789012:role/lambda-ex \
@@ -345,25 +334,13 @@ awslocal lambda create-function \
 
 You can quickly make sure that it works by invoking it with a simple payload:
 
-<Tabs>
-<TabItem label="AWS CLI v1">
 ```bash
-awslocal lambda invoke \
-    --function-name hello-world \
-    --payload '{"action": "test"}' \
-    output.txt
-```
-</TabItem>
-<TabItem label="AWS CLI v2">
-```bash
-awslocal lambda invoke \
+lstk aws lambda invoke \
     --function-name hello-world \
     --cli-binary-format raw-in-base64-out \
     --payload '{"action": "test"}' \
     output.txt
 ```
-</TabItem>
-</Tabs>
 
 The invocation returns itself returns:
 
@@ -422,10 +399,10 @@ This is enabled using the [`nodemon-webpack-plugin`](https://www.npmjs.com/packa
 
 ##### Creating the Lambda Function with Webpack
 
-You can now create the Lambda function using the `awslocal` CLI:
+You can now create the Lambda function using `lstk aws`:
 
 ```bash
-awslocal lambda create-function \
+lstk aws lambda create-function \
     --function-name localstack-example \
     --runtime nodejs18.x \
     --role arn:aws:iam::000000000000:role/lambda-ex \
@@ -436,7 +413,7 @@ awslocal lambda create-function \
 Additionally, you can create a Lambda Function URL with the following command:
 
 ```bash
-function_url=$(awslocal lambda create-function-url-config \
+function_url=$(lstk aws lambda create-function-url-config \
     --function-name localstack-example \
     --auth-type NONE | jq -r '.FunctionUrl')
 ```
@@ -629,8 +606,8 @@ LAMBDA_MOUNT_CWD=$(pwd)/build/hot serverless deploy --stage local
 <TabItem label="AWS Cloud Development Kit (CDK)">
 ```bash
 STAGE=local && LAMBDA_MOUNT_CWD=$(pwd)/build/hot &&
-  cdklocal bootstrap aws://000000000000/$(AWS_REGION) && \
-  cdklocal deploy
+  lstk cdk bootstrap aws://000000000000/$(AWS_REGION) && \
+  lstk cdk deploy
 ```
 </TabItem>
 <TabItem label="Terraform">
@@ -686,7 +663,7 @@ Please note that this environment variable name is arbitrary - you can use any y
 You can then deploy a hot-reloading function with the following command:
 
 ```bash
-awslocal lambda create-function \
+lstk aws lambda create-function \
   --function-name test-function \
   --code S3Bucket=hot-reload,S3Key='$HOST_LAMBDA_DIR/src' \
   --handler handler.handler \

src/content/docs/aws/developer-tools/lambda-tools/remote-debugging.mdx

@@ -42,7 +42,7 @@ This guide describes how to use the AWS Toolkit for VS Code to debug Lambda func
 
 ### Prerequisites
 
-* Upgrade to LocalStack v4.8 (or higher) for both your LocalStack CLI and your LocalStack Docker image.
+* Install the [`lstk` CLI](/aws/developer-tools/running-localstack/lstk)
 * [VS Code](https://code.visualstudio.com/) (>= v1.83.0)
 * [AWS Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=AmazonWebServices.aws-toolkit-vscode) (>= v3.74)
 * [LocalStack Toolkit for VS Code](https://marketplace.visualstudio.com/items?itemName=LocalStack.localstack) (>= v1.2.0)
@@ -196,10 +196,19 @@ necessary tools and flexibility to troubleshoot effectively.
 
 To enable Lambda Debug Mode, set the `LAMBDA_DEBUG_MODE` environment variable as shown below:
 
+```toml
+# .lstk/config.toml
+[[containers]]
+type = "aws"
+env  = ["lambda-debug"]
+
+[env.lambda-debug]
+LAMBDA_DEBUG_MODE = "1"
+LAMBDA_DOCKER_FLAGS = "-p 19891:19891"
+```
+
 ```bash
-LAMBDA_DEBUG_MODE=1 \
-LAMBDA_DOCKER_FLAGS='-p 19891:19891' \
-localstack start
+lstk start
 ```
 
 When enabled, Lambda Debug Mode automatically adjusts timeouts to accommodate debugging needs:
@@ -217,11 +226,21 @@ Manually setting `LAMBDA_DOCKER_FLAGS` is unnecessary when using this configurat
 Here is an example of mounting a `debug_config.yaml` in your LocalStack container to start your Debug Mode:
 
 <Tabs>
-<TabItem label="LocalStack CLI">
+<TabItem label="lstk">
+```toml
+# .lstk/config.toml
+[[containers]]
+type    = "aws"
+env     = ["lambda-debug-advanced"]
+volumes = ["/path/to/debug-config.yaml:/tmp/lambda_debug_mode_config.yaml"]
+
+[env.lambda-debug-advanced]
+LAMBDA_DEBUG_MODE = "1"
+LAMBDA_DEBUG_MODE_CONFIG_PATH = "/tmp/debug_config.yaml"
+```
+
 ```bash
-LOCALSTACK_LAMBDA_DEBUG_MODE=1 \
-LOCALSTACK_LAMBDA_DEBUG_MODE_CONFIG_PATH=/tmp/debug_config.yaml \
-localstack start --volume /path/to/debug-config.yaml:/tmp/lambda_debug_mode_config.yaml
+lstk start
 ```
 </TabItem>
 <TabItem label="Docker Compose">
@@ -338,8 +357,18 @@ to [iterate quickly over your function code](/aws/developer-tools/lambda-tools/h
 
 First, make sure that LocalStack is started with the following configuration (see the [Configuration docs](/aws/customization/configuration-options#lambda) for more information):
 
+```toml
+# .lstk/config.toml
+[[containers]]
+type = "aws"
+env  = ["lambda-debug"]
+
+[env.lambda-debug]
+LAMBDA_DOCKER_FLAGS = "-p 19891:19891"
+```
+
 ```bash
-LAMBDA_DOCKER_FLAGS='-p 19891:19891' localstack start
+lstk start
 ```
 
 #### Preparing your code
@@ -479,7 +508,7 @@ To create the Lambda function, you just need to take care of two things:
 Using the AWS CLI, this would be:
 
 ```bash
-awslocal lambda create-function --function-name my-cool-local-function \
+lstk aws lambda create-function --function-name my-cool-local-function \
     --code S3Bucket="hot-reload",S3Key="$(pwd)/" \
     --handler handler.handler \
     --runtime python3.13 \
@@ -489,23 +518,12 @@ awslocal lambda create-function --function-name my-cool-local-function \
 
 We can quickly verify that it works by invoking it with a simple payload:
 
-<Tabs>
-<TabItem label="AWS CLI v1">
 ```bash
-awslocal lambda invoke --function-name my-cool-local-function \
-    --payload '{"message": "Hello from LocalStack!"}' \
-    output.txt
-```
-</TabItem>
-<TabItem label="AWS CLI v2">
-```bash
-awslocal lambda invoke --function-name my-cool-local-function \
+lstk aws lambda invoke --function-name my-cool-local-function \
     --cli-binary-format raw-in-base64-out \
     --payload '{"message": "Hello from LocalStack!"}' \
     output.txt
 ```
-</TabItem>
-</Tabs>
 
 ### Debugging JVM Lambda functions
 
@@ -527,7 +545,7 @@ services:
 When creating your Lambda function, set the `_JAVA_OPTIONS` environment variable like so:
 
 ```bash
-awslocal lambda create-function --function-name debugfunc \
+lstk aws lambda create-function --function-name debugfunc \
     --zip-file fileb://java-handler.zip \
     --handler myindex.handler \
     --runtime java8.al2 \
@@ -688,7 +706,7 @@ exports.handler = async (event) => {
 Create the lambda function using:
 
 ```bash
-awslocal lambda create-function --function-name func1 \
+lstk aws lambda create-function --function-name func1 \
     --code S3Bucket="hot-reload",S3Key="$(pwd)/" \
     --handler myindex.handler \
     --runtime nodejs14.x \
@@ -700,23 +718,12 @@ Now to debug your lambda function, click on the `Debug` icon with
 `Attach to Remote Node.js` configuration selected, and then invoke your
 lambda function:
 
-<Tabs>
-<TabItem label="AWS CLI v1">
-```bash
-awslocal lambda invoke --function-name func1 \
-    --payload '{"hello":"world"}' \
-    output.txt
-```
-</TabItem>
-<TabItem label="AWS CLI v2">
 ```bash
-awslocal lambda invoke --function-name func1 \
+lstk aws lambda invoke --function-name func1 \
     --cli-binary-format raw-in-base64-out \
     --payload '{"hello":"world"}' \
     output.txt
 ```
-</TabItem>
-</Tabs>
 
 
 ## Examples