> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# localstack/platform

Note: This orb has now been deprecated and will no longer be actively supported. Easily run integration tests with LocalStack, the local cloud testing platform.
This Orb provides a collection of useful, common, and parameterized tasks and commands to facilitate testing of your cloud application using LocalStack.


## Commands

### cloud_pods

Save or Load LocalStack Cloud Pods.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `pod_action` | enum | save | Action to perform (save or load) |
| `pod_name` | string | cloud-pod | Name of the Cloud Pod' |

### ephemeral

Start or Stop LocalStack Ephemeral Instance.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `auto_load_pod` | string |  | The pod to load on startup of LocalStack, the env var AUTO_LOAD_POD |
| `ephemeral_action` | enum | start | Action to perform (start or stop) |
| `localstack_api_key` | string |  | LocalStack API key used to create the preview environment |
| `preview_cmd` | string |  | Command(s) used to create a preview of the PR (can use $AWS_ENDPOINT_URL) |

### start

Install and start LocalStack in a background Docker container.

Use this command to install and start LocalStack in a background Docker container.
To retrieve the logs from this container, you can use the following command in any subsequent build command:

    localstack logs

Note: This command needs to be started with a VM executor (Docker-based executors are not yet supported).


| Parameter | Type | Default | Description |
|---|---|---|---|
| `install-awslocal` | boolean | true | Whether to install the `awslocal` command line interface into the build environment (requires python3 and pip3) |

### startup

This command installs and starts up LocalStack in Docker.

After this command finishes, the LocalStack instance is fully initialized and ready to use.

Note: This command needs to be started with a VM executor (Docker-based executors are not yet supported).


### stop

Stop the currently running LocalStack instance.

This command stops the LocalStack container running in the current build job (using the container name, "localstack-main" by default).


### tools

Install LocalStack tools.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `install_awslocal` | boolean | true | Whether to install the `awslocal` command line interface into the build environment (requires python3 and pip3) |

### wait

Wait for LocalStack to be up and running.

This command polls the LocalStack container status until initialization is done and it is ready to use.


## Executors

### default

LocalStack executor on Ubuntu VM using Docker


| Parameter | Type | Default | Description |
|---|---|---|---|
| `image` | string | ubuntu-2204:2023.02.1 | Virtual machine image to use |

## Examples

### aws-cli-commands

This example runs a simple LocalStack build that manages S3 buckets and objects locally.

The sample below uses the `awslocal` CLI command, a drop-in replacement of the `aws` CLI, for use with local APIs on `localhost`.
The sample contains 2 steps: first, it starts up LocalStack via the `localstack/startup` command; second, it runs the commands to interact with the local S3 API provided by LocalStack.


```yaml
version: '2.1'
orbs:
  localstack: localstack/platform@2.2
jobs:
  localstack-test:
    executor: localstack/default
    steps:
      - localstack/startup
      - run:
          command: |
            awslocal s3 mb s3://test
            awslocal s3 ls
workflows:
  localstack-test:
    jobs:
      - localstack-test
```

### cloud-pods

This example illustrates Cloud Pods usage with LocalStack to store the deployed infrastructure's state.

The sample first uses the `localstack/startup` command to start up LocalStack in the background,
then performs some infrastructure provisioning with awscli
and then finally uses the `localstack/cloud-pods` command to store the state in a Cloud Pod.


```yaml
version: '2.1'
orbs:
  localstack: localstack/platform@2.2
jobs:
  localstack-test:
    executor: localstack/default
    steps:
      - localstack/startup
      - run:
          command: |
            awslocal s3 mb s3://test
            awslocal sqs create-queue --queue-name=test-queue
      - localstack/cloud_pods:
          pod_name: circleci_test_pod
workflows:
  localstack-test:
    jobs:
      - localstack-test
```

### ephemeral-instance

This example illustrates LocalStack's Ephemeral Instance usage.

The sample first uses the `localstack/ephemeral` command to start up an ephemeral LocalStack instance,
which in this case loads a previous state from a Cloud Pod,
and then finally checks the expected resources already deployed in the state.


```yaml
version: '2.1'
orbs:
  localstack: localstack/platform@2.2
jobs:
  localstack-test:
    executor: localstack/default
    steps:
      - localstack/ephemeral:
          auto_load_pod: circleci_test_pod
      - run:
          command: |
            echo "Running checks on my preloaded state..."
            awslocal sqs get-queue-url --queue-name=test-queue
            awslocal s3 ls s3://test
workflows:
  localstack-test:
    jobs:
      - localstack-test
```

### startup-async

This example illustrates asynchronous LocalStack startup, to optimize the build time by running your test initialization tasks in parallel.

The sample first uses the `localstack/start` command to start up LocalStack in the background,
then performs custom application initialization commands (illustrated via the first `echo` command),
and then finally uses the `localstack/wait` command before proceeding with the actual application build logic (second `echo` command).


```yaml
version: '2.1'
orbs:
  localstack: localstack/platform@2.2
jobs:
  localstack-test:
    executor: localstack/default
    steps:
      - localstack/start
      - run:
          command: echo "Running my custom application initialization logic ..."
      - localstack/wait
      - run:
          command: echo "Now LocalStack has fully started up, and is ready to use!"
workflows:
  localstack-test:
    jobs:
      - localstack-test
```