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:
aws-serverless: circleci/aws-serverless@1.0.2
Use aws-serverless
elements in your existing workflows and jobs.
Test application in a staging environment in Cloudformation before deploying to production.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
jobs:
test_my_api:
executor: aws-servlerless/default
steps:
- run: echo "Run your tests here"
orbs:
aws-serverless: circleci/aws-serverless@x.y.z
version: 2.1
workflows:
test_and_deploy:
jobs:
- aws-serverless/deploy:
name: deploy-staging
stack-name: staging-stack
template: ./path/to/template.yml
- test_my_api:
requires:
- deploy-staging
- aws-serverless/deploy:
name: deploy-production
requires:
- test_my_api
stack-name: production-stack
template: ./path/to/template.yml
Install the SAM CLI to interact with the CLI directly.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
jobs:
build_app:
executor: aws-serverless/default
steps:
- checkout
- aws-serverless/install
- run: sam build
orbs:
aws-serverless: circleci/aws-serverless@x.y.z
version: 2.1
workflows:
my-workflow:
jobs:
- build_app
Install the SAM CLI to interact with the CLI directly.
1
2
3
4
5
6
7
8
9
10
jobs:
build_and_package:
executor: aws-serverless/default
steps:
- checkout
- aws-serverless/install
- aws-serverless/local-start-api
orbs:
aws-serverless: circleci/aws-serverless@x.y.z
version: 2.1
Deploy serverless applications.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
aws-region | Sets the AWS Region of the service (for example, us-east-1). | No | AWS_DEFAULT_REGION | env_var_name |
base-dir | Resolves relative paths to the function's source code with respect to this folder. Use this if the AWS SAM template and your source code aren't in the same enclosing folder. By default, relative paths are resolved with respect to the template's location. | No | '' | string |
build-dir | The path to a folder where the built artifacts are stored. | No | '' | string |
capabilities | - | No | CAPABILITY_IAM | string |
debug | Turns on debug logging. | No | false | boolean |
pre-deploy | Run these steps prior to deploying the application, but after the checkout, install, build, and package steps. | No | [] | steps |
profile-name | Select a specific profile from your credential file to get AWS credentials. | No | default | string |
python_version | If set, this version of Python will be installed and set with pyenv globally. ex: "3.7.0" This is only for the local environment and will not have any effect if use-container is enabled.9 | No | '' | string |
s3-bucket | The name of the S3 bucket where this command uploads the artifacts that are referenced in your template. If this option is set, the SAM package command will be run automatically. | Yes | - | string |
stack-name | The name of the AWS CloudFormation stack you're deploying to. If you specify an existing stack, the command updates the stack. If you specify a new stack, the command creates it. | Yes | - | string |
template | The AWS SAM template file | Yes | - | string |
use-container | If your functions depend on packages that have natively compiled dependencies, use this flag to build your function inside an AWS Lambda-like Docker container. | No | true | boolean |
validate | Validate your template file. This will run unless manually set to false. | No | true | boolean |
Build your Lambda source code and generate deployment artifacts that target Lambda's execution environment. The sam build command iterates through the functions in your application, looks for a manifest file (such as requirements.txt) that contains the dependencies, and automatically creates deployment artifacts that you can deploy to Lambda using the sam package and sam deploy commands. You can also use sam build in combination with other commands like sam local invoke to test your application locally. Optionally package for s3 or run locally. Ensure CLI has been installed before utilizing.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
aws-region | Sets the AWS Region of the service (for example, us-east-1). | No | AWS_DEFAULT_REGION | env_var_name |
base-dir | Resolves relative paths to the function's source code with respect to this folder. Use this if the AWS SAM template and your source code aren't in the same enclosing folder. By default, relative paths are resolved with respect to the template's location. | No | '' | string |
build-dir | The path to a folder where the built artifacts are stored. | No | '' | string |
debug | Turns on debug logging. | No | false | boolean |
output-template-file | The path to the file where the command writes the packaged template. If you don't specify a path, the command writes the template to the standard output. | No | '' | string |
profile-name | Select a specific profile from your credential file to get AWS credentials. | No | default | string |
s3-bucket | The name of the S3 bucket where this command uploads the artifacts that are referenced in your template. If this option is set, the SAM package command will be run automatically. | No | '' | string |
template | The AWS SAM template file | Yes | - | string |
use-container | If your functions depend on packages that have natively compiled dependencies, use this flag to build your function inside an AWS Lambda-like Docker container. | No | true | boolean |
validate | Validate your template file. This will run unless manually set to false. | No | true | boolean |
Deploys an AWS SAM application. It is recommended to create a Workflow to build and deploy your SAM app to a development stack for testing before deploying to a production stack.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
aws-region | Env var of AWS region to operate in
(defaults to AWS_DEFAULT_REGION)
| No | AWS_DEFAULT_REGION | env_var_name |
capabilities | A list of capabilities that you must specify before AWS Cloudformation can create certain stacks. The only valid values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM. If you have IAM resources, you can specify either capability. If you have IAM resources with custom names, you must specify CAPABILITY_NAMED_IAM. | No | CAPABILITY_IAM | string |
debug | Turns on debug logging. | No | false | boolean |
profile-name | Select a specific profile from your credential file to get AWS credentials. | No | default | string |
stack-name | The name of the AWS CloudFormation stack you're deploying to. If you specify an existing stack, the command updates the stack. If you specify a new stack, the command creates it. | Yes | - | string |
template | The path where your AWS SAM template file is located. | No | '' | string |
Install and configure the AWS CLI and the SAM CLI in one command. Must have IAM credentials set via environment variables.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
aws-access-key-id | AWS access key id for IAM role. Set this to the name of
the environment variable you will use to hold this
value, i.e. AWS_ACCESS_KEY.
| No | AWS_ACCESS_KEY_ID | env_var_name |
aws-region | Env var of AWS region to operate in
(defaults to AWS_DEFAULT_REGION)
| No | AWS_DEFAULT_REGION | env_var_name |
aws-secret-access-key | AWS secret key for IAM role. Set this to the name of
the environment variable you will use to hold this
value, i.e. $AWS_SECRET_ACCESS_KEY.
| No | AWS_SECRET_ACCESS_KEY | env_var_name |
configure-default-region | Some AWS actions don't require a region; set this to false if you do not want to store a default region in ~/.aws/config
| No | true | boolean |
profile-name | Profile name to be configured. | No | default | string |
python_version | If set, this version of Python will be installed and set with pyenv globally. ex: "3.7.0" This is only for the local environment and will not have any effect if use-container is enabled. | No | '' | string |
Run your SAM app locally in the background and wait until the server is online. This is an alias to the SAM CLI.
PARAMETER | DESCRIPTION | REQUIRED | DEFAULT | TYPE |
---|---|---|---|---|
debug | Enable debug logging
| No | false | boolean |
dockerize_version | Dockerize is a utility that will continuously attempt to connect to an endpoint. Used to wait for the API to come online. | No | 0.6.1 | string |
endpoint | After invoking the local-api this endpoint will be tested against until it is online before allowing the job to continue. | Yes | - | string |
env-vars | The JSON file that contains values for the Lambda function's environment variables. | No | '' | string |
port | The local port number to listen on | No | 3000 | integer |
template | The path where your AWS SAM template file is located. | No | '' | string |
timeout | The number in minutes to wait for the API to come online. | No | 5 | integer |
Machine executor provided by CircleCI. Needed for privileged access to Docker for the SAM CLI.
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
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
# This code is licensed from CircleCI to the user under the MIT license.
# See here for details: https://circleci.com/developer/orbs/licensing
commands:
build:
description: |
Build your Lambda source code and generate deployment artifacts that target Lambda's execution environment. The sam build command iterates through the functions in your application, looks for a manifest file (such as requirements.txt) that contains the dependencies, and automatically creates deployment artifacts that you can deploy to Lambda using the sam package and sam deploy commands. You can also use sam build in combination with other commands like sam local invoke to test your application locally.
Optionally package for s3 or run locally.
Ensure CLI has been installed before utilizing.
parameters:
aws-region:
default: AWS_DEFAULT_REGION
description: Sets the AWS Region of the service (for example, us-east-1).
type: env_var_name
base-dir:
default: ""
description: Resolves relative paths to the function's source code with respect
to this folder. Use this if the AWS SAM template and your source code aren't
in the same enclosing folder. By default, relative paths are resolved with
respect to the template's location.
type: string
build-dir:
default: ""
description: The path to a folder where the built artifacts are stored.
type: string
debug:
default: false
description: Turns on debug logging.
type: boolean
output-template-file:
default: ""
description: The path to the file where the command writes the packaged template.
If you don't specify a path, the command writes the template to the standard
output.
type: string
profile-name:
default: default
description: Select a specific profile from your credential file to get AWS
credentials.
type: string
s3-bucket:
default: ""
description: The name of the S3 bucket where this command uploads the artifacts
that are referenced in your template. If this option is set, the SAM package
command will be run automatically.
type: string
template:
description: The AWS SAM template file
type: string
use-container:
default: true
description: If your functions depend on packages that have natively compiled
dependencies, use this flag to build your function inside an AWS Lambda-like
Docker container.
type: boolean
validate:
default: true
description: Validate your template file. This will run unless manually set
to false.
type: boolean
steps:
- when:
condition: << parameters.validate >>
steps:
- run:
command: |
sam validate -t << parameters.template >> \
--region $<< parameters.aws-region >> \
--profile << parameters.profile-name >> \
<<# parameters.debug >>--debug<</ parameters.debug >>
name: Validating SAM template
- run:
command: |
sam build -t << parameters.template >> \
<<# parameters.build-dir >>--build-dir << parameters.build-dir >> \
<</ parameters.build-dir >><<# parameters.base-dir >>--base-dir << parameters.base-dir >> \
<</ parameters.base-dir >>--profile << parameters.profile-name >> \
<<# parameters.use-container >>--use-container \
<</ parameters.use-container >>--region $<< parameters.aws-region >> \
<<# parameters.debug >>--debug<</ parameters.debug >>
name: Building SAM application
- when:
condition: << parameters.s3-bucket >>
steps:
- run:
command: |
sam package --template-file << parameters.template >> \
--s3-bucket << parameters.s3-bucket >> \
<<# parameters.output-template-file >>--output-template-file << parameters.output-template-file >> \
<</ parameters.output-template-file >>--profile << parameters.profile-name >> \
--region $<< parameters.aws-region >> \
<<# parameters.debug >>--debug<</ parameters.debug >>
name: Package SAM app for deployment
deploy:
description: |
Deploys an AWS SAM application. It is recommended to create a Workflow to build and deploy your SAM app to a development stack for testing before deploying to a production stack.
parameters:
aws-region:
default: AWS_DEFAULT_REGION
description: |
Env var of AWS region to operate in
(defaults to AWS_DEFAULT_REGION)
type: env_var_name
capabilities:
default: CAPABILITY_IAM
description: A list of capabilities that you must specify before AWS Cloudformation
can create certain stacks. The only valid values are CAPABILITY_IAM and
CAPABILITY_NAMED_IAM. If you have IAM resources, you can specify either
capability. If you have IAM resources with custom names, you must specify
CAPABILITY_NAMED_IAM.
type: string
debug:
default: false
description: Turns on debug logging.
type: boolean
profile-name:
default: default
description: Select a specific profile from your credential file to get AWS
credentials.
type: string
stack-name:
description: The name of the AWS CloudFormation stack you're deploying to.
If you specify an existing stack, the command updates the stack. If you
specify a new stack, the command creates it.
type: string
template:
default: ""
description: The path where your AWS SAM template file is located.
type: string
steps:
- run:
command: |
sam deploy \
--capabilities << parameters.capabilities >> \
--template-file << parameters.template >> \
--stack-name << parameters.stack-name >> \
<<# parameters.profile-name >>--profile << parameters.profile-name >><</ parameters.profile-name >> \
--region $<< parameters.aws-region >> \
<<# parameters.debug >>--debug<</ parameters.debug >>
install:
description: |
Install and configure the AWS CLI and the SAM CLI in one command. Must have IAM credentials set via environment variables.
parameters:
aws-access-key-id:
default: AWS_ACCESS_KEY_ID
description: |
AWS access key id for IAM role. Set this to the name of
the environment variable you will use to hold this
value, i.e. AWS_ACCESS_KEY.
type: env_var_name
aws-region:
default: AWS_DEFAULT_REGION
description: |
Env var of AWS region to operate in
(defaults to AWS_DEFAULT_REGION)
type: env_var_name
aws-secret-access-key:
default: AWS_SECRET_ACCESS_KEY
description: |
AWS secret key for IAM role. Set this to the name of
the environment variable you will use to hold this
value, i.e. $AWS_SECRET_ACCESS_KEY.
type: env_var_name
configure-default-region:
default: true
description: |
Some AWS actions don't require a region; set this to false if you do not want to store a default region in ~/.aws/config
type: boolean
profile-name:
default: default
description: Profile name to be configured.
type: string
python_version:
default: ""
description: 'If set, this version of Python will be installed and set with
pyenv globally. ex: "3.7.0" This is only for the local environment and will
not have any effect if use-container is enabled.'
type: string
steps:
- when:
condition: << parameters.python_version >>
steps:
- run:
command: |
git clone git://github.com/pyenv/pyenv-update.git $(pyenv root)/plugins/pyenv-update
pyenv update
pyenv install << parameters.python_version >>
name: Installing Python << parameters.python_version >>
- run:
command: |
pyenv versions
pyenv global << parameters.python_version >>
name: Switching to Python << parameters.python_version >>
- aws-cli/install
- aws-cli/configure:
aws-access-key-id: << parameters.aws-access-key-id >>
aws-region: << parameters.aws-region >>
aws-secret-access-key: << parameters.aws-secret-access-key >>
configure-default-region: << parameters.configure-default-region >>
profile-name: << parameters.profile-name >>
- run:
command: |
curl -fsSL "https://raw.githubusercontent.com/Linuxbrew/install/master/install.sh" | bash
/home/linuxbrew/.linuxbrew/bin/brew shellenv >> $BASH_ENV
name: Install Homebrew (for Linux)
- run:
command: |
brew tap aws/tap
brew install aws-sam-cli
sam --version
name: Install the AWS SAM CLI
local-start-api:
description: |
Run your SAM app locally in the background and wait until the server is online. This is an alias to the SAM CLI.
parameters:
debug:
default: false
description: |
Enable debug logging
type: boolean
dockerize_version:
default: 0.6.1
description: Dockerize is a utility that will continuously attempt to connect
to an endpoint. Used to wait for the API to come online.
type: string
endpoint:
description: After invoking the local-api this endpoint will be tested against
until it is online before allowing the job to continue.
type: string
env-vars:
default: ""
description: The JSON file that contains values for the Lambda function's
environment variables.
type: string
port:
default: 3000
description: The local port number to listen on
type: integer
template:
default: ""
description: The path where your AWS SAM template file is located.
type: string
timeout:
default: 5
description: The number in minutes to wait for the API to come online.
type: integer
steps:
- run:
command: wget https://github.com/jwilder/dockerize/releases/download/v<< parameters.dockerize_version
>>/dockerize-linux-amd64-v<< parameters.dockerize_version >>.tar.gz && sudo
tar -C /usr/local/bin -xzvf dockerize-linux-amd64-v<< parameters.dockerize_version
>>.tar.gz && rm dockerize-linux-amd64-v<< parameters.dockerize_version >>.tar.gz
name: install dockerize
- run:
background: true
command: |
sam local start-api \
<<# parameters.template >>-t << parameters.template >> \
<</ parameters.template >>-p << parameters.port >> \
<<# parameters.env-vars >>-n << parameters.env-vars >> \
<</ parameters.env-vars >>
<<# parameters.debug >>--debug<</ parameters.debug >>
name: SAM local start-api
- run:
command: dockerize -wait http://127.0.0.1:3000/<< parameters.endpoint >> -timeout
<< parameters.timeout >>m
name: Wait for API
description: |
"Build, Test, and Deploy your AWS serverless applications on CircleCI utilizing the AWS Serverless Application Model. Learn More: https://aws.amazon.com/serverless/sam/ Repo: https://github.com/CircleCI-Public/aws-serverless-orb"
examples:
build_test_deploy:
description: |
Test application in a staging environment in Cloudformation before deploying to production.
usage:
jobs:
test_my_api:
executor: aws-servlerless/default
steps:
- run: echo "Run your tests here"
orbs:
aws-serverless: circleci/aws-serverless@x.y.z
version: 2.1
workflows:
test_and_deploy:
jobs:
- aws-serverless/deploy:
name: deploy-staging
stack-name: staging-stack
template: ./path/to/template.yml
- test_my_api:
requires:
- deploy-staging
- aws-serverless/deploy:
name: deploy-production
requires:
- test_my_api
stack-name: production-stack
template: ./path/to/template.yml
install-cli:
description: |
Install the SAM CLI to interact with the CLI directly.
usage:
jobs:
build_app:
executor: aws-serverless/default
steps:
- checkout
- aws-serverless/install
- run: sam build
orbs:
aws-serverless: circleci/aws-serverless@x.y.z
version: 2.1
workflows:
my-workflow:
jobs:
- build_app
local_test:
description: |
Install the SAM CLI to interact with the CLI directly.
usage:
jobs:
build_and_package:
executor: aws-serverless/default
steps:
- checkout
- aws-serverless/install
- aws-serverless/local-start-api
orbs:
aws-serverless: circleci/aws-serverless@x.y.z
version: 2.1
executors:
default:
description: |
Machine executor provided by CircleCI. Needed for privileged access to Docker for the SAM CLI.
machine: true
jobs:
deploy:
description: |
Deploy serverless applications.
executor: default
parameters:
aws-region:
default: AWS_DEFAULT_REGION
description: Sets the AWS Region of the service (for example, us-east-1).
type: env_var_name
base-dir:
default: ""
description: Resolves relative paths to the function's source code with respect
to this folder. Use this if the AWS SAM template and your source code aren't
in the same enclosing folder. By default, relative paths are resolved with
respect to the template's location.
type: string
build-dir:
default: ""
description: The path to a folder where the built artifacts are stored.
type: string
capabilities:
default: CAPABILITY_IAM
type: string
debug:
default: false
description: Turns on debug logging.
type: boolean
pre-deploy:
default: []
description: Run these steps prior to deploying the application, but after
the checkout, install, build, and package steps.
type: steps
profile-name:
default: default
description: Select a specific profile from your credential file to get AWS
credentials.
type: string
python_version:
default: ""
description: 'If set, this version of Python will be installed and set with
pyenv globally. ex: "3.7.0" This is only for the local environment and will
not have any effect if use-container is enabled.9'
type: string
s3-bucket:
description: The name of the S3 bucket where this command uploads the artifacts
that are referenced in your template. If this option is set, the SAM package
command will be run automatically.
type: string
stack-name:
description: The name of the AWS CloudFormation stack you're deploying to.
If you specify an existing stack, the command updates the stack. If you
specify a new stack, the command creates it.
type: string
template:
description: The AWS SAM template file
type: string
use-container:
default: true
description: If your functions depend on packages that have natively compiled
dependencies, use this flag to build your function inside an AWS Lambda-like
Docker container.
type: boolean
validate:
default: true
description: Validate your template file. This will run unless manually set
to false.
type: boolean
steps:
- checkout
- install:
profile-name: << parameters.profile-name >>
python_version: << parameters.python_version >>
- build:
aws-region: << parameters.aws-region >>
base-dir: << parameters.base-dir >>
build-dir: << parameters.build-dir >>
debug: << parameters.debug >>
output-template-file: ~/packaged_template.yml
profile-name: << parameters.profile-name >>
s3-bucket: << parameters.s3-bucket >>
template: << parameters.template >>
use-container: << parameters.use-container >>
validate: << parameters.validate >>
- steps: << parameters.pre-deploy >>
- deploy:
aws-region: << parameters.aws-region >>
capabilities: << parameters.capabilities >>
debug: << parameters.debug >>
profile-name: << parameters.profile-name >>
stack-name: << parameters.stack-name >>
template: ~/packaged_template.yml
orbs:
aws-cli: circleci/aws-cli@0.1.13
version: 2.1