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.
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
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
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
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
Save or Load LocalStack Cloud Pods.
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 |
Start or Stop LocalStack Ephemeral Instance.
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 |
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 | 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 |
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 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).
Install LocalStack tools.
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 for LocalStack to be up and running. This command polls the LocalStack container status until initialization is done and it is ready to use.
LocalStack executor on Ubuntu VM using Docker
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
image | Virtual machine image to use | No | ubuntu-2204:2023.02.1 | string |
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