1. localstack/platform@2.2.0

localstack/platform@2.2.0

Partner
Sections
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.
Created: May 13, 2021Version Published: June 11, 2024Releases: 9
Org Usage:
< 25

Orb Quick Start Guide

Use CircleCI version 2.1 at the top of your .circleci/config.yml file.

1 version: 2.1

Add the orbs stanza below your version, invoking the orb:

1 2 orbs: platform: localstack/platform@2.2.0

Use platform elements in your existing workflows and jobs.

Opt-in to use of uncertified orbs on your organization’s Security settings page.

Usage 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 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.

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 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).

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 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

Commands

cloud_pods

Save or Load LocalStack Cloud Pods.

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
pod_action
Action to perform (save or load)
No
save
enum
pod_name
Name of the Cloud Pod'
No
cloud-pod
string

ephemeral

Start or Stop LocalStack Ephemeral Instance.

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
auto_load_pod
The pod to load on startup of LocalStack, the env var AUTO_LOAD_POD
No
''
string
ephemeral_action
Action to perform (start or stop)
No
start
enum
localstack_api_key
LocalStack API key used to create the preview environment
No
''
string
preview_cmd
Command(s) used to create a preview of the PR (can use $AWS_ENDPOINT_URL)
No
''
string

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).

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
install-awslocal
Whether to install the `awslocal` command line interface into the build environment (requires python3 and pip3)
No
true
boolean

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).

Show command Source

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).

Show command Source

tools

Install LocalStack tools.

Show command Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
install_awslocal
Whether to install the `awslocal` command line interface into the build environment (requires python3 and pip3)
No
true
boolean

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.

Show command Source

Executors

default

LocalStack executor on Ubuntu VM using Docker

Show executor Source
PARAMETER
DESCRIPTION
REQUIRED
DEFAULT
TYPE
image
Virtual machine image to use
No
ubuntu-2204:2023.02.1
string

Orb Source

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 # This code is licensed from CircleCI to the user under the MIT license. # See here for details: https://circleci.com/developer/orbs/licensing version: 2.1 description: | 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. display: home_url: https://localstack.cloud source_url: https://github.com/localstack/ci-plugin-circleci commands: cloud_pods: description: | Save or Load LocalStack Cloud Pods. parameters: pod_action: default: save description: Action to perform (save or load) enum: - save - load type: enum pod_name: default: cloud-pod description: Name of the Cloud Pod' type: string steps: - run: command: |- #!/bin/bash if [ "$ACTION" = "save" ]; then echo "Saving Cloud Pod $NAME" localstack pod save "$NAME" elif [ "$ACTION" = "load" ]; then echo "Loading Cloud Pod $NAME" localstack pod load "$NAME" else echo "Invalid action: $ACTION" exit 1 fi environment: ACTION: << parameters.pod_action >> NAME: << parameters.pod_name >> name: Process Cloud Pod ephemeral: description: | Start or Stop LocalStack Ephemeral Instance. parameters: auto_load_pod: default: "" description: The pod to load on startup of LocalStack, the env var AUTO_LOAD_POD type: string ephemeral_action: default: start description: Action to perform (start or stop) enum: - start - stop type: enum localstack_api_key: default: "" description: LocalStack API key used to create the preview environment type: string preview_cmd: default: "" description: Command(s) used to create a preview of the PR (can use $AWS_ENDPOINT_URL) type: string steps: - run: command: | #!/bin/bash # TODO: make preview name configurable! previewName=preview-$CIRCLE_PR_NUMBER if [ "$ACTION" = "start" ]; then response=$(curl -X POST -d "{\"auto_load_pod\": \"${AUTO_LOAD_POD:-${PARAM_AUTO_LOAD_POD}}\"}" \ -H "ls-api-key: ${LOCALSTACK_API_KEY:-${PARAM_LOCALSTACK_API_KEY}}" \ -H "authorization: token ${LOCALSTACK_API_KEY:-${LOCALSTACK_API_KEY}}" \ -H "content-type: application/json" \ "https://api.localstack.cloud/v1/previews/$previewName") endpointUrl=$(echo "$response" | jq -r .endpoint_url) if [ "$endpointUrl" = "null" ] || [ "$endpointUrl" = "" ]; then echo "Unable to create preview environment. API response: $response" exit 1 fi echo "Created preview environment with endpoint URL: $endpointUrl" echo "export LS_PREVIEW_URL=$endpointUrl >> $BASH_ENV" echo "export AWS_ENDPOINT_URL=$endpointUrl >> $BASH_ENV" eval "$PREVIEW_CMD" elif [ "$ACTION" = "stop" ]; then response=$(curl -X DELETE \ -H "ls-api-key: ${LOCALSTACK_API_KEY:-${LOCALSTACK_API_KEY}}" \ -H "authorization: token ${LOCALSTACK_API_KEY:-${LOCALSTACK_API_KEY}}" \ -H "content-type: application/json" \ "https://api.localstack.cloud/v1/previews/$previewName") if [[ "$response" != "{}" ]]; then # In case the deletion fails, e.g. if the instance cannot be found, we raise a proper error on the platform echo "Unable to delete preview environment. API response: $response" exit 1 fi else echo "Invalid action: $ACTION" exit 1 fi environment: ACTION: << parameters.ephemeral_action >> PARAM_AUTO_LOAD_POD: << parameters.auto_load_pod >> PARAM_LOCALSTACK_API_KEY: << parameters.localstack_api_key >> PREVIEW_CMD: << parameters.preview_cmd >> name: Process Ephemeral Instance start: description: | 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). parameters: install-awslocal: default: true description: Whether to install the `awslocal` command line interface into the build environment (requires python3 and pip3) type: boolean steps: - run: command: pip3 install --upgrade pip && pip3 install -q localstack name: Install Localstack - tools: install_awslocal: << parameters.install-awslocal >> - run: command: localstack start -d name: Start LocalStack container startup: description: | 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). steps: - start - wait stop: description: | 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). steps: - run: command: | localstack stop name: Stop LocalStack container tools: description: | Install LocalStack tools. parameters: install_awslocal: default: true description: Whether to install the `awslocal` command line interface into the build environment (requires python3 and pip3) type: boolean steps: - when: condition: <<parameters.install_awslocal>> steps: - run: pip3 install -q awscli-local[ver1] wait: description: | 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. steps: - run: command: | localstack wait -t 45 name: Wait for LocalStack to be ready executors: default: description: | LocalStack executor on Ubuntu VM using Docker machine: image: <<parameters.image>> parameters: image: default: ubuntu-2204:2023.02.1 description: Virtual machine image to use type: string examples: aws-cli-commands: description: | 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. usage: 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: description: | 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. usage: 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: description: | 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. usage: 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: description: | 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). usage: 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
Developer Updates
Get tips to optimize your builds
Or join our research panel and give feedback
By submitting this form, you are agreeing to ourTerms of UseandPrivacy Policy.