From 10d121fdb1afb1b48b58d53cb6b8a39b7299e822 Mon Sep 17 00:00:00 2001 From: HarshCasper Date: Fri, 27 Mar 2026 11:30:48 +0530 Subject: [PATCH 1/3] Remove References to LocalStack Java Utils and LocalStack CircleCI Orb --- .../continuous-integration/circleci.md | 294 +++++++++++++----- src/content/docs/aws/tooling/testing-utils.md | 4 +- 2 files changed, 222 insertions(+), 76 deletions(-) diff --git a/src/content/docs/aws/integrations/continuous-integration/circleci.md b/src/content/docs/aws/integrations/continuous-integration/circleci.md index b4fdd683..7726fbe3 100644 --- a/src/content/docs/aws/integrations/continuous-integration/circleci.md +++ b/src/content/docs/aws/integrations/continuous-integration/circleci.md @@ -9,7 +9,7 @@ sidebar: ## Introduction [CircleCI](https://circleci.com) is a continuous integration and continuous delivery (CI/CD) platform which uses a configuration file (usually named `.circleci/config.yml`) to define the build, test, and deployment workflows. -LocalStack supports CircleCI out of the box and can be easily integrated into your pipeline to run your tests against a local cloud emulator. +This guide shows how to run LocalStack in CircleCI using the LocalStack Docker image and the LocalStack CLI. ## Snippets @@ -19,34 +19,56 @@ LocalStack supports CircleCI out of the box and can be easily integrated into yo ```yaml showshowLineNumbers version: '2.1' -orbs: - localstack: localstack/platform@2.2 jobs: localstack-test: - executor: localstack/default + machine: + image: ubuntu-2204:current steps: - - localstack/startup - ... + - checkout + - run: + name: Install LocalStack CLI and awslocal + command: python3 -m pip install localstack awscli-local[ver1] + - run: + name: Start LocalStack + command: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 + - run: + name: Test LocalStack + command: | + awslocal s3 mb s3://test-bucket + awslocal s3 ls workflows: localstack-test: jobs: - localstack-test - ``` #### Async ```yaml showshowLineNumbers version: '2.1' -orbs: - localstack: localstack/platform@2.2 jobs: localstack-test: - executor: localstack/default + machine: + image: ubuntu-2204:current steps: - - localstack/start - ... - - localstack/wait + - checkout + - run: + name: Install LocalStack CLI and awslocal + command: python3 -m pip install localstack awscli-local[ver1] + - run: + name: Start LocalStack in background + command: | + docker pull localstack/localstack:latest + localstack start -d + - run: + name: Execute setup and tests + command: | + localstack wait -t 60 + awslocal sqs create-queue --queue-name test-queue + awslocal sqs list-queues workflows: localstack-test: jobs: @@ -65,11 +87,14 @@ Read more about the [configuration options](/aws/capabilities/config/configurati ... jobs: localstack-test: - executor: localstack/default + machine: + image: ubuntu-2204:current environment: DEBUG: 1 + LS_LOG: trace steps: - - localstack/startup + ... + - run: localstack start -d ... ``` @@ -79,18 +104,20 @@ jobs: ... jobs: localstack-test: - executor: localstack/default + machine: + image: ubuntu-2204:current steps: - run: name: Configure LocalStack - command: echo 'export DEBUG=1' >> "$BASH_ENV" + command: | + echo 'export DEBUG=1' >> "$BASH_ENV" + echo 'export LS_LOG=trace' >> "$BASH_ENV" ... ``` ### Configuring a CI Auth Token -To enable LocalStack for AWS, you need to add your LocalStack CI Auth Token to the project's environment variables. -The LocalStack container will automatically pick it up and activate the licensed features. +To enable CI Auth Token support, you need to add your LocalStack CI Auth Token to the project's environment variables. Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. To add the CI Auth Token to your CircleCI project, follow these steps: @@ -101,7 +128,36 @@ To add the CI Auth Token to your CircleCI project, follow these steps: - Name your environment variable `LOCALSTACK_AUTH_TOKEN`. - Paste your CI Auth Token into the input field. -After the above steps, just start up LocalStack using our official orb as usual. +After adding the variable, CircleCI injects `LOCALSTACK_AUTH_TOKEN` into your job environment. +The following example maps it explicitly at the job level and starts LocalStack. + +```yaml showshowLineNumbers +version: '2.1' +jobs: + localstack-test: + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} + steps: + - checkout + - run: + name: Install LocalStack CLI and awslocal + command: python3 -m pip install localstack awscli-local[ver1] + - run: + name: Start LocalStack + command: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 + - run: + name: Verify LocalStack setup + command: localstack logs | rg "activated|auth token|ready" +workflows: + localstack-test: + jobs: + - localstack-test +``` ### Dump LocalStack logs @@ -109,7 +165,8 @@ After the above steps, just start up LocalStack using our official orb as usual. ... jobs: localstack-test: - executor: localstack/default + machine: + image: ubuntu-2204:current steps: ... - run: @@ -131,6 +188,7 @@ _Note: For best result we recommend to use a combination of the below techniques #### Cloud Pods Cloud Pods providing an easy solution to persist LocalStack's state, even between workflows or projects. +Add `LOCALSTACK_AUTH_TOKEN` to every job that starts LocalStack when using Cloud Pods. Find more information about [Cloud Pods](/aws/capabilities/state-management/cloud-pods). @@ -141,23 +199,29 @@ Update or create the Cloud Pod in it's own project (ie in a separate Infrastruct _Note: If there is a previously created Cloud Pod which doesn't need updating this step can be skipped._ ```yaml showshowLineNumbers -orbs: - localstack: localstack/platform@2.2 ... jobs: localstack-update-cloud-pod: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: + - run: python3 -m pip install localstack awscli-local[ver1] + - run: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 ... - # LocalStack already running - run: - name: Load state if exists - command: localstack pod load || true # Not allowed to fail yet + name: Load state if exists + command: localstack pod load || true ... # Deploy infrastructure changes ... - - localstack/cloud_pods: - pod_name: + - run: + name: Save Cloud Pod + command: localstack pod save workflows: @@ -169,18 +233,23 @@ workflows: In a separate project use the previously created base Cloud Pod as below: ```yaml showshowLineNumbers -orbs: - localstack: localstack/platform@2.2 ... jobs: localstack-use-cloud-pod: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: + - run: python3 -m pip install localstack awscli-local[ver1] + - run: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 ... - # LocalStack already running - - localstack/cloud_pods: - pod_name: - pod_action: load + - run: + name: Load Cloud Pod + command: localstack pod load ... # Run some tests @@ -197,8 +266,6 @@ To use a dynamically updated Cloud Pod in multiple workflows but in the same pro Before you are able to use any stored artifacts in your pipeline, you must provide either a valid [project API token](https://circleci.com/docs/managing-api-tokens/#creating-a-project-api-token) or a [personal API token](https://circleci.com/docs/managing-api-tokens/#creating-a-personal-api-token) to CircleCI. ```yaml showshowLineNumbers -orbs: - localstack: localstack/platform@2.2 ... parameters: run_workflow_build: @@ -217,19 +284,26 @@ parameters: jobs: localstack-update-state: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: + - run: python3 -m pip install localstack awscli-local[ver1] + - run: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 ... - # LocalStack already running - - localstack/cloud_pods: - pod_name: - pod_action: load + - run: + name: Load Cloud Pod + command: localstack pod load || true ... # Deploy infrastructure ... - - localstack/cloud_pods: - pod_name: - pod_action: save # Optional as this is the default + - run: + name: Save Cloud Pod + command: localstack pod save - run: name: Trigger other workflows # Replace placeholders with right values @@ -242,13 +316,20 @@ jobs: localstack-use-state: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: + - run: python3 -m pip install localstack awscli-local[ver1] + - run: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 ... - # LocalStack already running - run: - name: Load state if exists - command: localstack pod load || true + name: Load state if exists + command: localstack pod load || true ... @@ -276,19 +357,29 @@ Find out more about [Ephemeral Instances](/aws/capabilities/cloud-sandbox/epheme ##### Same job ```yaml showshowLineNumbers -orbs: - localstack: localstack/platform@2.2 ... jobs: do-work: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - - localstack/ephemeral: - auto_load_pod: # Pod to load (optional) - # Commands to run (optional) - preview-cmd: | - awslocal sqs create-queue --queue-name=test-queue - awslocal s3 mb s3://test-bucket + - run: + name: Create Ephemeral Instance + command: | + response=$(curl -X POST \ + -H "ls-api-key: $LOCALSTACK_AUTH_TOKEN" \ + -H "authorization: token $LOCALSTACK_AUTH_TOKEN" \ + -H "content-type: application/json" \ + -d '{"auto_load_pod":"false"}' \ + https://api.localstack.cloud/v1/previews/my-circleci-state) + endpoint_url=$(echo "$response" | jq -r '.endpointUrl') + if [ -z "$endpoint_url" ] || [ "$endpoint_url" = "null" ]; then + echo "Unable to create preview environment. API response: $response" + exit 1 + fi + echo "export AWS_ENDPOINT_URL=$endpoint_url" >> "$BASH_ENV" - run: name: Output the ephemeral instance address command: echo "$AWS_ENDPOINT_URL" @@ -306,22 +397,39 @@ workflows: ... jobs: setup-instance: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - - localstack/ephemeral: - ephemeral_action: start - # Script to run (optional) - preview-cmd: bin/deploy.sh + - run: + name: Create Ephemeral Instance + command: | + response=$(curl -X POST \ + -H "ls-api-key: $LOCALSTACK_AUTH_TOKEN" \ + -H "authorization: token $LOCALSTACK_AUTH_TOKEN" \ + -H "content-type: application/json" \ + -d '{"auto_load_pod":"false"}' \ + https://api.localstack.cloud/v1/previews/my-circleci-state) + endpoint_url=$(echo "$response" | jq -r '.endpointUrl') + if [ -z "$endpoint_url" ] || [ "$endpoint_url" = "null" ]; then + echo "Unable to create preview environment. API response: $response" + exit 1 + fi + echo "export AWS_ENDPOINT_URL=$endpoint_url" >> ls-env-vars - run: name: Persist AWS Endpoint URL - command: echo "export AWS_ENDPOINT_URL=$endpointUrl" >> ls-env-vars + command: cat ls-env-vars - persist_to_workspace: root: . paths: - ls-env-vars run-test: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - attach_workspace: at: . @@ -332,10 +440,16 @@ jobs: name: Output the ephemeral instance address command: echo "$AWS_ENDPOINT_URL" ... - # Run any logic against the Ephemeral Instance, - # then stop when not needed anymore - - localstack/ephemeral: - ephemeral_action: stop + # Run any logic against the Ephemeral Instance, + # then stop when not needed anymore + - run: + name: Stop Ephemeral Instance + command: | + # Replace with the id returned by the API in setup-instance. + curl -X DELETE \ + -H "ls-api-key: $LOCALSTACK_AUTH_TOKEN" \ + -H "authorization: token $LOCALSTACK_AUTH_TOKEN" \ + https://api.localstack.cloud/v1/previews/ ... workflows: @@ -354,8 +468,16 @@ This strategy persist LocalStack's state between jobs for the current workflow. ... jobs: localstack-save-state: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: + - run: python3 -m pip install localstack awscli-local[ver1] + - run: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 ... # LocalStack already running and deployed infrastructure - run: @@ -370,8 +492,16 @@ jobs: paths: ls-state.zip ... localstack-load-state: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: + - run: python3 -m pip install localstack awscli-local[ver1] + - run: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 ... # LocalStack already running - attach_workspace: @@ -399,8 +529,16 @@ This strategy will persist LocalStack's state for every workflow re-runs, but no ... jobs: localstack-update-state: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: + - run: python3 -m pip install localstack awscli-local[ver1] + - run: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 ... # LocalStack already running # Let's restore previous workflow run's LocalStack state @@ -421,8 +559,16 @@ jobs: paths: ls-state.zip ... localstack-do-work: - executor: localstack/default + machine: + image: ubuntu-2204:current + environment: + LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: + - run: python3 -m pip install localstack awscli-local[ver1] + - run: | + docker pull localstack/localstack:latest + localstack start -d + localstack wait -t 60 # LocalStack already running - restore_cache: # Use latest "ls-state" prefixed cache diff --git a/src/content/docs/aws/tooling/testing-utils.md b/src/content/docs/aws/tooling/testing-utils.md index fbd98bc6..a880ec99 100644 --- a/src/content/docs/aws/tooling/testing-utils.md +++ b/src/content/docs/aws/tooling/testing-utils.md @@ -9,11 +9,11 @@ nav: ## Introduction LocalStack provides a set of tools to simplify application testing on LocalStack. -These tools are available for Python and JVM (Java and Kotlin) and can be used to integrate with various unit testing frameworks and simplify the setup of AWS clients with LocalStack. +These tools are available for Python and can be used to integrate with various unit testing frameworks and simplify the setup of AWS clients with LocalStack. ## Python -This Python Testing Utils streamlines the integration of Localstack with your unit tests. +This [Python Testing Utils](https://github.com/localstack/localstack-python-utils) streamlines the integration of Localstack with your unit tests. ### Installation From 8217825ac484f18d4d8ca7b262b54e71800ced2f Mon Sep 17 00:00:00 2001 From: HarshCasper Date: Fri, 27 Mar 2026 12:59:06 +0530 Subject: [PATCH 2/3] update --- .../continuous-integration/circleci.md | 55 +++++++++---------- 1 file changed, 26 insertions(+), 29 deletions(-) diff --git a/src/content/docs/aws/integrations/continuous-integration/circleci.md b/src/content/docs/aws/integrations/continuous-integration/circleci.md index 7726fbe3..084ec1d8 100644 --- a/src/content/docs/aws/integrations/continuous-integration/circleci.md +++ b/src/content/docs/aws/integrations/continuous-integration/circleci.md @@ -19,6 +19,8 @@ This guide shows how to run LocalStack in CircleCI using the LocalStack Docker i ```yaml showshowLineNumbers version: '2.1' +orbs: + python: circleci/python@4.0.0 jobs: localstack-test: machine: @@ -27,10 +29,14 @@ jobs: - checkout - run: name: Install LocalStack CLI and awslocal - command: python3 -m pip install localstack awscli-local[ver1] + command: | + python3 -m pip install --user --upgrade pip + python3 -m pip install --user localstack awscli-local[ver1] + echo 'export PATH=$HOME/.local/bin:$PATH' >> "$BASH_ENV" - run: name: Start LocalStack command: | + source "$BASH_ENV" docker pull localstack/localstack:latest localstack start -d localstack wait -t 60 @@ -49,6 +55,8 @@ workflows: ```yaml showshowLineNumbers version: '2.1' +orbs: + python: circleci/python@4.0.0 jobs: localstack-test: machine: @@ -57,15 +65,20 @@ jobs: - checkout - run: name: Install LocalStack CLI and awslocal - command: python3 -m pip install localstack awscli-local[ver1] + command: | + python3 -m pip install --user --upgrade pip + python3 -m pip install --user localstack awscli-local[ver1] + echo 'export PATH=$HOME/.local/bin:$PATH' >> "$BASH_ENV" - run: name: Start LocalStack in background command: | + source "$BASH_ENV" docker pull localstack/localstack:latest localstack start -d - run: name: Execute setup and tests command: | + source "$BASH_ENV" localstack wait -t 60 awslocal sqs create-queue --queue-name test-queue awslocal sqs list-queues @@ -129,24 +142,27 @@ To add the CI Auth Token to your CircleCI project, follow these steps: - Paste your CI Auth Token into the input field. After adding the variable, CircleCI injects `LOCALSTACK_AUTH_TOKEN` into your job environment. -The following example maps it explicitly at the job level and starts LocalStack. ```yaml showshowLineNumbers version: '2.1' +orbs: + python: circleci/python@4.0.0 jobs: localstack-test: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - checkout - run: name: Install LocalStack CLI and awslocal - command: python3 -m pip install localstack awscli-local[ver1] + command: | + python3 -m pip install --user --upgrade pip + python3 -m pip install --user localstack awscli-local[ver1] + echo 'export PATH=$HOME/.local/bin:$PATH' >> "$BASH_ENV" - run: name: Start LocalStack command: | + source "$BASH_ENV" docker pull localstack/localstack:latest localstack start -d localstack wait -t 60 @@ -188,7 +204,6 @@ _Note: For best result we recommend to use a combination of the below techniques #### Cloud Pods Cloud Pods providing an easy solution to persist LocalStack's state, even between workflows or projects. -Add `LOCALSTACK_AUTH_TOKEN` to every job that starts LocalStack when using Cloud Pods. Find more information about [Cloud Pods](/aws/capabilities/state-management/cloud-pods). @@ -204,8 +219,7 @@ jobs: localstack-update-cloud-pod: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} + steps: - run: python3 -m pip install localstack awscli-local[ver1] - run: | @@ -238,8 +252,7 @@ jobs: localstack-use-cloud-pod: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} + steps: - run: python3 -m pip install localstack awscli-local[ver1] - run: | @@ -286,8 +299,7 @@ jobs: localstack-update-state: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} + steps: - run: python3 -m pip install localstack awscli-local[ver1] - run: | @@ -318,8 +330,7 @@ jobs: localstack-use-state: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} + steps: - run: python3 -m pip install localstack awscli-local[ver1] - run: | @@ -362,8 +373,6 @@ jobs: do-work: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - run: name: Create Ephemeral Instance @@ -399,8 +408,6 @@ jobs: setup-instance: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - run: name: Create Ephemeral Instance @@ -428,8 +435,6 @@ jobs: run-test: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - attach_workspace: at: . @@ -470,8 +475,6 @@ jobs: localstack-save-state: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - run: python3 -m pip install localstack awscli-local[ver1] - run: | @@ -494,8 +497,6 @@ jobs: localstack-load-state: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - run: python3 -m pip install localstack awscli-local[ver1] - run: | @@ -531,8 +532,6 @@ jobs: localstack-update-state: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - run: python3 -m pip install localstack awscli-local[ver1] - run: | @@ -561,8 +560,6 @@ jobs: localstack-do-work: machine: image: ubuntu-2204:current - environment: - LOCALSTACK_AUTH_TOKEN: ${LOCALSTACK_AUTH_TOKEN} steps: - run: python3 -m pip install localstack awscli-local[ver1] - run: | From 8be84183ea7274a35abfd2856a0c23b19fb2150b Mon Sep 17 00:00:00 2001 From: HarshCasper Date: Fri, 27 Mar 2026 13:03:58 +0530 Subject: [PATCH 3/3] change in language --- .../docs/aws/integrations/continuous-integration/circleci.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/content/docs/aws/integrations/continuous-integration/circleci.md b/src/content/docs/aws/integrations/continuous-integration/circleci.md index 084ec1d8..7326ac2d 100644 --- a/src/content/docs/aws/integrations/continuous-integration/circleci.md +++ b/src/content/docs/aws/integrations/continuous-integration/circleci.md @@ -130,7 +130,8 @@ jobs: ### Configuring a CI Auth Token -To enable CI Auth Token support, you need to add your LocalStack CI Auth Token to the project's environment variables. +To enable LocalStack for AWS, you need to add your LocalStack CI Auth Token to the project's environment variables. +The LocalStack container will automatically pick it up and activate the licensed features. Go to the [CI Auth Token page](https://app.localstack.cloud/workspace/auth-tokens) and copy your CI Auth Token. To add the CI Auth Token to your CircleCI project, follow these steps: