AWS Lambda

Developer Guide
 AWS Lambda Developer Guide

AWS Lambda: Developer Guide

Copyright © Amazon Web Services, Inc. and/or its affiliates. All rights reserved.

Amazon's trademarks and trade dress may not be used in connection with any product or service that is not
Amazon's, in any manner that is likely to cause confusion among customers, or in any manner that disparages or
discredits Amazon. All other trademarks not owned by Amazon are the property of their respective owners, who may
or may not be affiliated with, connected to, or sponsored by Amazon.
 AWS Lambda Developer Guide

Table of Contents
What is AWS Lambda? ........................................................................................................................ 1
When should I use Lambda? ........................................................................................................ 1
Lambda features ........................................................................................................................ 2
Getting started with Lambda ....................................................................................................... 2
Related services ......................................................................................................................... 3
Accessing Lambda ...................................................................................................................... 3
Pricing for Lambda ..................................................................................................................... 4
Setting up ......................................................................................................................................... 5
AWS Account ............................................................................................................................. 5
AWS CLI .................................................................................................................................... 5
AWS SAM .................................................................................................................................. 5
AWS SAM CLI ............................................................................................................................ 6
Tools for container images .......................................................................................................... 6
Code authoring tools .................................................................................................................. 6
Getting started .................................................................................................................................. 8
Create a function ....................................................................................................................... 9
Create a Lambda function with default function code ............................................................. 9
Create a function defined as a container image .................................................................... 11
Code editor ............................................................................................................................. 17
Working with files and folders ........................................................................................... 17
Working with code ........................................................................................................... 19
Working in fullscreen mode ............................................................................................... 22
Working with preferences .................................................................................................. 22
AWS CLI .................................................................................................................................. 23
Prerequisites .................................................................................................................... 23
Create the execution role .................................................................................................. 23
Create the function .......................................................................................................... 24
List the Lambda functions in your account .......................................................................... 27
Retrieve a Lambda function ............................................................................................... 27
Clean up ......................................................................................................................... 28
Concepts ................................................................................................................................. 29
Function .......................................................................................................................... 29
Trigger ............................................................................................................................ 29
Event .............................................................................................................................. 29
Execution environment ...................................................................................................... 30
Deployment package ........................................................................................................ 30
Runtime .......................................................................................................................... 30
Layer .............................................................................................................................. 30
Extension ........................................................................................................................ 31
Concurrency ..................................................................................................................... 31
Qualifier .......................................................................................................................... 31
Features .................................................................................................................................. 32
Programming model ......................................................................................................... 32
Scaling ............................................................................................................................ 34
Concurrency controls ........................................................................................................ 35
Asynchronous invocation ................................................................................................... 36
Event source mappings ..................................................................................................... 37
Destinations ..................................................................................................................... 38
Function blueprints ........................................................................................................... 39
Testing and deployment tools ............................................................................................ 40
Application templates ....................................................................................................... 40
Deployment packages ............................................................................................................... 41
Container images ............................................................................................................. 41
.zip file archives ............................................................................................................... 41

iii
 AWS Lambda Developer Guide

Layers ............................................................................................................................. 42
Using other AWS services .................................................................................................. 42
Quotas .................................................................................................................................... 44
Permissions ..................................................................................................................................... 46
Execution role .......................................................................................................................... 47
Creating an execution role in the IAM console ...................................................................... 48
Grant least privilege access to your Lambda execution role .................................................... 48
Managing roles with the IAM API ....................................................................................... 49
AWS managed policies for Lambda features ........................................................................ 50
Resource-based policies ............................................................................................................. 51
Granting function access to AWS services ............................................................................ 52
Granting function access to other accounts .......................................................................... 53
Granting layer access to other accounts .............................................................................. 54
Cleaning up resource-based policies .................................................................................... 55
User policies ............................................................................................................................ 56
Function development ...................................................................................................... 56
Layer development and use ............................................................................................... 59
Cross-account roles ........................................................................................................... 60
Condition keys for VPC settings ........................................................................................ 60
Resources and conditions .......................................................................................................... 61
Function resource names ................................................................................................... 62
Function actions ............................................................................................................... 64
Event source mapping actions ............................................................................................ 66
Layer actions ................................................................................................................... 66
Permissions boundaries ............................................................................................................. 67
Managing functions .......................................................................................................................... 69
Configure console ..................................................................................................................... 70
Functions defined as container images ........................................................................................ 72
Function version $LATEST ................................................................................................. 72
Container image deployment ............................................................................................. 72
Amazon ECR permissions ................................................................................................. 72
Override the container settings .......................................................................................... 73
Creating a function (console) ............................................................................................. 73
Updating the function code (console) ................................................................................. 74
Overriding the image parameters (console) .......................................................................... 74
Using the Lambda API ...................................................................................................... 75
AWS CloudFormation ........................................................................................................ 75
Environment variables ............................................................................................................... 77
Configuring environment variables ..................................................................................... 77
Configuring environment variables with the API ................................................................... 78
Example scenario for environment variables ........................................................................ 78
Retrieve environment variables .......................................................................................... 79
Defined runtime environment variables ............................................................................... 80
Securing environment variables .......................................................................................... 81
Sample code and templates .............................................................................................. 83
Concurrency ............................................................................................................................. 84
Configuring reserved concurrency ....................................................................................... 85
Configuring provisioned concurrency .................................................................................. 87
Configuring concurrency with the Lambda API ..................................................................... 90
Versions .................................................................................................................................. 95
Creating function versions ................................................................................................. 95
Managing versions with the Lambda API ............................................................................. 95
Using versions .................................................................................................................. 96
Granting permissions ........................................................................................................ 96
Aliases .................................................................................................................................... 97
Creating a function alias (Console) ..................................................................................... 97
Managing aliases with the Lambda API ............................................................................... 97

iv
 AWS Lambda Developer Guide

Using aliases .................................................................................................................... 98

Resource policies .............................................................................................................. 98
Alias routing configuration ................................................................................................ 98
Creating layers ....................................................................................................................... 101
Creating layer content ..................................................................................................... 101
Compiling the .zip file archive for your layer ...................................................................... 101
Including library dependencies in a layer ........................................................................... 102
Creating a layer .............................................................................................................. 103
Deleting a layer version ................................................................................................... 104
Configuring layer permissions .......................................................................................... 104
Using AWS CloudFormation with layers ............................................................................. 105
Using layers ........................................................................................................................... 106
Configuring a function to use layers ................................................................................. 106
Accessing the contents of a layer ...................................................................................... 107
Finding layer information ................................................................................................ 107
Updating a layer version that your function uses ................................................................ 108
Adding layer permissions ................................................................................................. 108
Using AWS SAM to add a layer to a function ...................................................................... 105
Sample applications ........................................................................................................ 109
Memory ................................................................................................................................. 110
Configuring function memory .......................................................................................... 110
Accepting function memory recommendations ................................................................... 110
Network ................................................................................................................................ 111
Execution role and user permissions ................................................................................. 111
Configuring VPC access (console) ...................................................................................... 112
Configuring VPC access (API) ............................................................................................ 112
Using IAM condition keys for VPC settings ......................................................................... 113
Internet and service access for VPC-connected functions ..................................................... 116
VPC tutorials .................................................................................................................. 116
Sample VPC configurations .............................................................................................. 116
Interface VPC endpoints .......................................................................................................... 118
Considerations for Lambda interface endpoints .................................................................. 118
Creating an interface endpoint for Lambda ........................................................................ 119
Creating an interface endpoint policy for Lambda .............................................................. 119
Database ............................................................................................................................... 121
Creating a database proxy (console) .................................................................................. 121
Using the function's permissions for authentication ............................................................ 122
Sample application ......................................................................................................... 122
File system ............................................................................................................................ 126
Connecting to a file system (console) ................................................................................ 126
Configuring a file system and access point ......................................................................... 126
Execution role and user permissions ................................................................................. 127
Configuring file system access with the Lambda API ........................................................... 128
AWS CloudFormation and AWS SAM ................................................................................. 128
Sample applications ........................................................................................................ 129
Code signing .......................................................................................................................... 130
Signature validation ........................................................................................................ 130
Configuration prerequisites .............................................................................................. 131
Creating code signing configurations ................................................................................. 131
Updating a code signing configuration .............................................................................. 131
Deleting a code signing configuration ............................................................................... 132
Enabling code signing for a function ................................................................................. 132
Configuring IAM policies .................................................................................................. 132
Configuring code signing with the Lambda API .................................................................. 133
Tags ...................................................................................................................................... 134
Adding tags to a function (console) .................................................................................. 134
Using tags to filter functions (console) .............................................................................. 134

v
 AWS Lambda Developer Guide

Using Tags with the AWS CLI ........................................................................................... 135

Tag Key and Value Requirements ...................................................................................... 136
Invoking functions .......................................................................................................................... 137
Synchronous invocation ........................................................................................................... 138
Asynchronous invocation ......................................................................................................... 140
Configuring error handling for asynchronous invocation ...................................................... 142
Configuring destinations for asynchronous invocation ......................................................... 142
Asynchronous invocation configuration API ........................................................................ 144
Dead-letter queues ......................................................................................................... 145
Event source mapping ............................................................................................................. 148
Function states ....................................................................................................................... 151
Function scaling ..................................................................................................................... 153
Error handling ........................................................................................................................ 158
Using extensions .................................................................................................................... 160
Execution environment .................................................................................................... 161
Impact on performance and resources ............................................................................... 161
Permissions .................................................................................................................... 161
Configuring extensions (.zip file archive) ............................................................................ 162
Using extensions in container images ................................................................................ 162
Next steps ..................................................................................................................... 162
Invoking functions defined as container images .......................................................................... 164
Function lifecycle ............................................................................................................ 164
Invoking the function ...................................................................................................... 164
Image security ................................................................................................................ 164
Mobile SDK for Android .......................................................................................................... 165
Tutorial ......................................................................................................................... 165
Sample code .................................................................................................................. 171
Lambda applications ....................................................................................................................... 174
Manage applications ............................................................................................................... 175
Monitoring applications ................................................................................................... 175
Custom monitoring dashboards ........................................................................................ 175
Tutorial – Create an application ................................................................................................ 178
Prerequisites .................................................................................................................. 179
Create an application ...................................................................................................... 179
Invoke the function ........................................................................................................ 180
Add an AWS resource ...................................................................................................... 181
Update the permissions boundary .................................................................................... 183
Update the function code ................................................................................................ 183
Next steps ..................................................................................................................... 184
Troubleshooting ............................................................................................................. 185
Clean up ........................................................................................................................ 186
Rolling deployments ............................................................................................................... 187
Example AWS SAM Lambda template ............................................................................... 187
Use cases ............................................................................................................................... 189
Example 1: Amazon S3 pushes events and invokes a Lambda function ................................... 189
Example 2: AWS Lambda pulls events from a Kinesis stream and invokes a Lambda function ..... 190
Best practices ......................................................................................................................... 192
Function code ................................................................................................................ 192
Function configuration .................................................................................................... 193
Metrics and alarms ......................................................................................................... 194
Working with streams ..................................................................................................... 194
Lambda runtimes ........................................................................................................................... 195
Runtime support policy ........................................................................................................... 198
Execution environment ............................................................................................................ 200
Runtime lifecycle ............................................................................................................ 200
Container images .................................................................................................................... 203
AWS base images for Lambda ......................................................................................... 203

vi
 AWS Lambda Developer Guide

Base images for custom runtimes ..................................................................................... 203

Runtime interface clients ................................................................................................. 203
Runtime interface emulator ............................................................................................. 204
Runtime API ........................................................................................................................... 205
Next invocation .............................................................................................................. 205
Invocation response ........................................................................................................ 206
Initialization error ........................................................................................................... 206
Invocation error .............................................................................................................. 207
Extensions API ....................................................................................................................... 209
Lambda execution environment lifecycle ........................................................................... 210
Extensions API reference ................................................................................................. 218
Logs API ................................................................................................................................ 223
Subscribing to receive logs .............................................................................................. 224
Memory usage ............................................................................................................... 224
Destination protocols ...................................................................................................... 224
Buffering configuration ................................................................................................... 224
Example subscription ...................................................................................................... 225
Sample code for Logs API ................................................................................................ 225
Logs API reference .......................................................................................................... 226
Log messages ................................................................................................................ 227
Runtime modifications ............................................................................................................ 231
Language-specific environment variables ........................................................................... 231
Wrapper scripts .............................................................................................................. 233
Custom runtimes .................................................................................................................... 236
Using a custom runtime .................................................................................................. 236
Building a custom runtime ............................................................................................... 236
Tutorial – Custom runtime ....................................................................................................... 239
Prerequisites .................................................................................................................. 239
Create a function ............................................................................................................ 239
Create a layer ................................................................................................................ 241
Update the function ....................................................................................................... 242
Update the runtime ........................................................................................................ 243
Share the layer ............................................................................................................... 243
Clean up ........................................................................................................................ 243
AVX2 vectorization ................................................................................................................. 245
Compiling from source .................................................................................................... 245
Enabling AVX2 for Intel MKL ............................................................................................ 245
AVX2 support in other languages ..................................................................................... 245
Container images ............................................................................................................................ 247
Creating images ..................................................................................................................... 248
Image types ................................................................................................................... 248
Container tools .............................................................................................................. 248
Lambda requirements for container images ....................................................................... 249
Container image settings ................................................................................................. 249
Create an image from an AWS base image for Lambda ........................................................ 249
Create an image from an alternative base image ................................................................ 251
Create an image using the AWS SAM toolkit ...................................................................... 253
Testing images ....................................................................................................................... 254
Guidelines for using the RIE ............................................................................................. 254
Environment variables ..................................................................................................... 254
Test an image with RIE included in the image .................................................................... 255
Build RIE into your base image ........................................................................................ 255
Test an image without adding RIE to the image ................................................................. 256
Working with other services ............................................................................................................. 257
Alexa ..................................................................................................................................... 260
API Gateway .......................................................................................................................... 261
Permissions .................................................................................................................... 263

vii
 AWS Lambda Developer Guide

Handling errors with an API Gateway API .......................................................................... 264

Choosing an API type ...................................................................................................... 265
Sample applications ........................................................................................................ 267
Tutorial ......................................................................................................................... 267
Sample code .................................................................................................................. 277
Microservice blueprint ..................................................................................................... 280
Sample template ............................................................................................................ 281
CloudTrail .............................................................................................................................. 283
CloudTrail logs ............................................................................................................... 285
Tutorial ......................................................................................................................... 288
Sample code .................................................................................................................. 292
CloudWatch Events ................................................................................................................. 295
Tutorial ......................................................................................................................... 296
Sample template ............................................................................................................ 299
Schedule expressions ...................................................................................................... 300
CloudWatch Logs .................................................................................................................... 302
CloudFormation ...................................................................................................................... 303
CloudFront (Lambda@Edge) ..................................................................................................... 305
CodeCommit .......................................................................................................................... 307
CodePipeline .......................................................................................................................... 308
Permissions .................................................................................................................... 309
Cognito ................................................................................................................................. 310
Config ................................................................................................................................... 311
Connect ................................................................................................................................. 312
DynamoDB ............................................................................................................................. 313
Execution role permissions ............................................................................................... 314
Configuring a stream as an event source ........................................................................... 315
Event source mapping APIs .............................................................................................. 316
Error handling ................................................................................................................ 318
Amazon CloudWatch metrics ............................................................................................ 319
Time windows ................................................................................................................ 319
Reporting batch item failures ........................................................................................... 322
Tutorial ......................................................................................................................... 324
Sample code .................................................................................................................. 329
Sample template ............................................................................................................ 332
EC2 ....................................................................................................................................... 334
Permissions .................................................................................................................... 334
Tutorial – Spot Instances ................................................................................................. 335
ElastiCache ............................................................................................................................ 345
Prerequisites .................................................................................................................. 345
Create the execution role ................................................................................................ 345
Create an ElastiCache cluster ........................................................................................... 346
Create a deployment package .......................................................................................... 346
Create the Lambda function ............................................................................................ 347
Test the Lambda function ................................................................................................ 347
Clean up your resources .................................................................................................. 277
Elastic Load Balancing ............................................................................................................. 349
EFS ....................................................................................................................................... 351
Connections ................................................................................................................... 351
Throughput .................................................................................................................... 352
IOPS ............................................................................................................................. 352
IoT ........................................................................................................................................ 353
IoT Events ............................................................................................................................. 354
Apache Kafka ......................................................................................................................... 356
Managing access and permissions ..................................................................................... 357
Kafka authentication ....................................................................................................... 358
Network configuration .................................................................................................... 359

viii
 AWS Lambda Developer Guide

Adding a Kafka cluster as an event source ......................................................................... 359

Using a Kafka cluster as an event source ........................................................................... 361
Auto scaling of the Kafka event source ............................................................................. 361
Event source API operations ............................................................................................. 361
Event source errors ......................................................................................................... 362
Event source configuration parameters .............................................................................. 362
Kinesis Firehose ...................................................................................................................... 364
Kinesis Streams ...................................................................................................................... 365
Configuring your data stream and function ........................................................................ 366
Execution role permissions ............................................................................................... 367
Configuring a stream as an event source ........................................................................... 367
Event source mapping API ............................................................................................... 368
Error handling ................................................................................................................ 370
Amazon CloudWatch metrics ............................................................................................ 371
Time windows ................................................................................................................ 372
Reporting batch item failures ........................................................................................... 374
Tutorial ......................................................................................................................... 376
Sample code .................................................................................................................. 380
Sample template ............................................................................................................ 383
Lex ....................................................................................................................................... 386
Roles and permissions ..................................................................................................... 387
MQ ....................................................................................................................................... 389
Lambda consumer group ................................................................................................. 390
Execution role permissions ............................................................................................... 392
Configuring a broker as an event source ............................................................................ 392
Event source mapping API ............................................................................................... 393
Event source mapping errors ............................................................................................ 395
MSK ...................................................................................................................................... 396
Managing access and permissions ..................................................................................... 396
Network configuration .................................................................................................... 359
Adding Amazon MSK as an event source ........................................................................... 398
Auto scaling of the Amazon MSK event source ................................................................... 399
Amazon MSK configuration parameters ............................................................................. 362
RDS ...................................................................................................................................... 401
Tutorial ......................................................................................................................... 401
Configuring the function ................................................................................................. 405
S3 ......................................................................................................................................... 407
Tutorial: Use an S3 trigger ............................................................................................... 408
Tutorial: Use an S3 trigger to create thumbnails ................................................................. 413
Sample SAM template ..................................................................................................... 426
S3 Batch ................................................................................................................................ 427
Invoking Lambda functions from Amazon S3 batch operations ............................................. 428
Secrets Manager ..................................................................................................................... 429
SES ....................................................................................................................................... 430
SNS ...................................................................................................................................... 432
Tutorial ......................................................................................................................... 433
Sample code .................................................................................................................. 437
SQS ...................................................................................................................................... 439
Scaling and processing .................................................................................................... 440
Configuring a queue to use with Lambda .......................................................................... 441
Execution role permissions ............................................................................................... 441
Configuring a queue as an event source ............................................................................ 441
Event source mapping APIs .............................................................................................. 316
Tutorial ......................................................................................................................... 443
Sample code .................................................................................................................. 447
Sample template ............................................................................................................ 449
X-Ray .................................................................................................................................... 451

ix
 AWS Lambda Developer Guide

Execution role permissions ............................................................................................... 453

The AWS X-Ray daemon .................................................................................................. 453
Enabling active tracing with the Lambda API ..................................................................... 453
Enabling active tracing with AWS CloudFormation .............................................................. 454
Orchestrating functions ................................................................................................................... 455
Application patterns ............................................................................................................... 455
State machine components .............................................................................................. 455
State machine application patterns ................................................................................... 455
Applying patterns to state machines ................................................................................. 456
Example branching application pattern ............................................................................. 456
Manage state machines ........................................................................................................... 458
Viewing state machine details .......................................................................................... 459
Editing a state machine ................................................................................................... 459
Running a state machine ................................................................................................. 459
Orchestration examples ........................................................................................................... 460
Configuring a Lambda function as a task ........................................................................... 460
Configuring a state machine as an event source ................................................................. 460
Handling function and service errors ................................................................................. 461
AWS CloudFormation and AWS SAM ................................................................................. 462
Samples ........................................................................................................................................ 464
Blank function ....................................................................................................................... 466
Architecture and handler code ......................................................................................... 467
Deployment automation with AWS CloudFormation and the AWS CLI .................................... 468
Instrumentation with the AWS X-Ray ................................................................................ 470
Dependency management with layers ............................................................................... 471
Error processor ....................................................................................................................... 473
Architecture and event structure ...................................................................................... 474
Instrumentation with AWS X-Ray ...................................................................................... 475
AWS CloudFormation template and additional resources ..................................................... 475
List manager .......................................................................................................................... 478
Architecture and event structure ...................................................................................... 479
Instrumentation with AWS X-Ray ...................................................................................... 480
AWS CloudFormation templates and additional resources .................................................... 483
Working with Node.js ...................................................................................................................... 484
Handler ................................................................................................................................. 487
Async handlers ............................................................................................................... 487
Non-async handlers ........................................................................................................ 488
Deploy .zip file archives ........................................................................................................... 489
Prerequisites .................................................................................................................. 489
Updating a function with no dependencies ........................................................................ 489
Updating a function with additional dependencies .............................................................. 490
Deploy container images ......................................................................................................... 492
AWS base images for Node.js ........................................................................................... 492
Using a Node.js base image ............................................................................................. 492
Node.js runtime interface clients ...................................................................................... 492
Context ................................................................................................................................. 494
Logging ................................................................................................................................. 496
Creating a function that returns logs ................................................................................ 496
Using the Lambda console ............................................................................................... 497
Using the CloudWatch console ......................................................................................... 497
Using the AWS Command Line Interface (AWS CLI) ............................................................. 497
Deleting logs ................................................................................................................. 500
Errors .................................................................................................................................... 501
Syntax ........................................................................................................................... 501
How it works ................................................................................................................. 501
Using the Lambda console ............................................................................................... 502
Using the AWS Command Line Interface (AWS CLI) ............................................................. 502

x
 AWS Lambda Developer Guide

Error handling in other AWS services ................................................................................ 503

What's next? .................................................................................................................. 504
Tracing .................................................................................................................................. 505
Enabling active tracing with the Lambda API ..................................................................... 507
Enabling active tracing with AWS CloudFormation .............................................................. 508
Storing runtime dependencies in a layer ............................................................................ 508
Working with Python ...................................................................................................................... 510
Handler ................................................................................................................................. 512
Naming ......................................................................................................................... 512
How it works ................................................................................................................. 512
Returning a value ........................................................................................................... 513
Examples ....................................................................................................................... 513
Deploy .zip file archives ........................................................................................................... 515
Prerequisites .................................................................................................................. 515
What is a runtime dependency? ....................................................................................... 516
Tutorial: Create function .................................................................................................. 516
Update function ............................................................................................................. 525
Deploy container images ......................................................................................................... 529
AWS base images for Python ........................................................................................... 529
Python runtime interface clients ...................................................................................... 530
Deploying Python with an AWS base image ....................................................................... 530
Create a Python image from an alternative base image ....................................................... 531
Context ................................................................................................................................. 532
Logging ................................................................................................................................. 534
Creating a function that returns logs ................................................................................ 534
Using the Lambda console ............................................................................................... 535
Using the CloudWatch console ......................................................................................... 535
Using the AWS Command Line Interface (AWS CLI) ............................................................. 535
Deleting logs ................................................................................................................. 537
Logging library ............................................................................................................... 537
Errors .................................................................................................................................... 539
How it works ................................................................................................................. 539
Using the Lambda console ............................................................................................... 540
Using the AWS Command Line Interface (AWS CLI) ............................................................. 540
Error handling in other AWS services ................................................................................ 541
Error examples ............................................................................................................... 541
Sample applications ........................................................................................................ 542
What's next? .................................................................................................................. 504
Tracing .................................................................................................................................. 543
Enabling active tracing with the Lambda API ..................................................................... 545
Enabling active tracing with AWS CloudFormation .............................................................. 545
Storing runtime dependencies in a layer ............................................................................ 546
Working with Ruby ......................................................................................................................... 547
Handler ................................................................................................................................. 550
Deploy .zip file archives ........................................................................................................... 551
Prerequisites .................................................................................................................. 551
Tools and libraries .......................................................................................................... 551
Updating a function with no dependencies ........................................................................ 552
Updating a function with additional dependencies .............................................................. 552
Deploy container images ......................................................................................................... 554
AWS base images for Ruby .............................................................................................. 554
Using a Ruby base image ................................................................................................ 554
Ruby runtime interface clients ......................................................................................... 554
Context ................................................................................................................................. 556
Logging ................................................................................................................................. 557
Creating a function that returns logs ................................................................................ 557
Using the Lambda console ............................................................................................... 558

xi
 AWS Lambda Developer Guide

Using the CloudWatch console ......................................................................................... 558

Using the AWS Command Line Interface (AWS CLI) ............................................................. 559
Deleting logs ................................................................................................................. 561
Errors .................................................................................................................................... 562
Syntax ........................................................................................................................... 562
How it works ................................................................................................................. 562
Using the Lambda console ............................................................................................... 563
Using the AWS Command Line Interface (AWS CLI) ............................................................. 563
Error handling in other AWS services ................................................................................ 564
Sample applications ........................................................................................................ 565
What's next? .................................................................................................................. 565
Tracing .................................................................................................................................. 566
Enabling active tracing with the Lambda API ..................................................................... 568
Enabling active tracing with AWS CloudFormation .............................................................. 568
Storing runtime dependencies in a layer ............................................................................ 569
Working with Java .......................................................................................................................... 570
Sample apps .......................................................................................................................... 572
Handler ................................................................................................................................. 574
Choosing input and output types ..................................................................................... 575
Handler interfaces .......................................................................................................... 576
Sample handler code ...................................................................................................... 577
Deploy .zip file archives ........................................................................................................... 578
Prerequisites .................................................................................................................. 578
Tools and libraries .......................................................................................................... 578
Deploy container images ......................................................................................................... 585
AWS base images for Java ............................................................................................... 585
Using a Java base image ................................................................................................. 585
Java runtime interface clients .......................................................................................... 585
Context ................................................................................................................................. 587
Context in sample applications ......................................................................................... 588
Logging ................................................................................................................................. 590
Creating a function that returns logs ................................................................................ 590
Using the Lambda console ............................................................................................... 591
Using the CloudWatch console ......................................................................................... 591
Using the AWS Command Line Interface (AWS CLI) ............................................................. 592
Deleting logs ................................................................................................................. 594
Advanced logging with Log4j 2 and SLF4J ......................................................................... 594
Sample logging code ...................................................................................................... 596
Errors .................................................................................................................................... 597
Syntax ........................................................................................................................... 597
How it works ................................................................................................................. 598
Creating a function that returns exceptions ....................................................................... 598
Using the Lambda console ............................................................................................... 599
Using the AWS Command Line Interface (AWS CLI) ............................................................. 600
Error handling in other AWS services ................................................................................ 600
Sample applications ........................................................................................................ 601
What's next? .................................................................................................................. 601
Tracing .................................................................................................................................. 602
Enabling active tracing with the Lambda API ..................................................................... 604
Enabling active tracing with AWS CloudFormation .............................................................. 604
Storing runtime dependencies in a layer ............................................................................ 605
Tracing in sample applications ......................................................................................... 605
Tutorial - Eclipse IDE ............................................................................................................... 607
Prerequisites .................................................................................................................. 607
Create and build a project ............................................................................................... 607
Working with Go ............................................................................................................................ 610
Handler ................................................................................................................................. 611

xii
 AWS Lambda Developer Guide

Lambda function handler using structured types ................................................................ 612

Using global state .......................................................................................................... 613
Context ................................................................................................................................. 615
Accessing invoke context information ................................................................................ 615
Deploy .zip file archives ........................................................................................................... 617
Prerequisites .................................................................................................................. 617
Tools and libraries .......................................................................................................... 617
Sample applications ........................................................................................................ 617
Creating a .zip file on macOS and Linux ............................................................................ 618
Creating a .zip file on Windows ........................................................................................ 618
Deploy container images ......................................................................................................... 620
AWS base images for Go ................................................................................................. 620
Go runtime interface clients ............................................................................................. 620
Using the Go:1.x base image ............................................................................................ 621
Deploying Go with the provided.al2 base image ............................................................. 621
Deploying Go with an alternative base image ..................................................................... 622
Logging ................................................................................................................................. 624
Creating a function that returns logs ................................................................................ 624
Using the Lambda console ............................................................................................... 625
Using the CloudWatch console ......................................................................................... 625
Using the AWS Command Line Interface (AWS CLI) ............................................................. 625
Deleting logs ................................................................................................................. 628
Errors .................................................................................................................................... 629
Creating a function that returns exceptions ....................................................................... 629
How it works ................................................................................................................. 629
Using the Lambda console ............................................................................................... 630
Using the AWS Command Line Interface (AWS CLI) ............................................................. 630
Error handling in other AWS services ................................................................................ 631
What's next? .................................................................................................................. 632
Tracing .................................................................................................................................. 633
Enabling active tracing with the Lambda API ..................................................................... 635
Enabling active tracing with AWS CloudFormation .............................................................. 635
Environment variables ............................................................................................................. 637
Working with C# ............................................................................................................................ 638
Handler ................................................................................................................................. 640
Handling streams ........................................................................................................... 640
Handling standard data types .......................................................................................... 641
Handler signatures .......................................................................................................... 642
Serializing Lambda functions ........................................................................................... 642
Lambda function handler restrictions ................................................................................ 643
Using async in C# functions with AWS Lambda .................................................................. 643
Deployment package .............................................................................................................. 645
.NET Core CLI ................................................................................................................. 645
AWS Toolkit for Visual Studio .......................................................................................... 648
Deploy container images ......................................................................................................... 651
AWS base images for .NET ............................................................................................... 651
Using a .NET base image ................................................................................................. 651
.NET runtime interface clients .......................................................................................... 651
Context ................................................................................................................................. 652
Logging ................................................................................................................................. 653
Creating a function that returns logs ................................................................................ 653
Using the Lambda console ............................................................................................... 654
Using the CloudWatch console ......................................................................................... 654
Using the AWS Command Line Interface (AWS CLI) ............................................................. 655
Deleting logs ................................................................................................................. 657
Errors .................................................................................................................................... 658
Syntax ........................................................................................................................... 658

xiii
 AWS Lambda Developer Guide

How it works ................................................................................................................. 660

Using the Lambda console ............................................................................................... 661
Using the AWS Command Line Interface (AWS CLI) ............................................................. 661
Error handling in other AWS services ................................................................................ 662
What's next? .................................................................................................................. 662
Tracing .................................................................................................................................. 663
Enabling active tracing with the Lambda API ..................................................................... 665
Enabling active tracing with AWS CloudFormation .............................................................. 665
Working with PowerShell ................................................................................................................. 667
Development Environment ...................................................................................................... 668
Deployment package .............................................................................................................. 669
Tools and libraries .......................................................................................................... 669
Sample applications ........................................................................................................ 669
Creating a Lambda function ............................................................................................. 669
Handler ................................................................................................................................. 672
Returning data ............................................................................................................... 672
Context ................................................................................................................................. 673
Logging ................................................................................................................................. 674
Creating a function that returns logs ................................................................................ 674
Using the Lambda console ............................................................................................... 675
Using the CloudWatch console ......................................................................................... 675
Using the AWS Command Line Interface (AWS CLI) ............................................................. 675
Deleting logs ................................................................................................................. 678
Errors .................................................................................................................................... 679
Syntax ........................................................................................................................... 679
How it works ................................................................................................................. 680
Using the Lambda console ............................................................................................... 680
Using the AWS Command Line Interface (AWS CLI) ............................................................. 681
Error handling in other AWS services ................................................................................ 681
What's next? .................................................................................................................. 682
Monitoring ..................................................................................................................................... 683
Monitoring console ................................................................................................................. 684
Pricing ........................................................................................................................... 684
Using the Lambda console ............................................................................................... 684
Types of monitoring graphs ............................................................................................. 684
Viewing graphs on the Lambda console ............................................................................ 684
Viewing queries in the CloudWatch Logs console ................................................................ 685
What's next? .................................................................................................................. 685
Function insights .................................................................................................................... 686
How it works ................................................................................................................. 686
Pricing ........................................................................................................................... 686
Supported runtimes ........................................................................................................ 686
Enabling Lambda Insights in the console ........................................................................... 686
Enabling Lambda Insights programmatically ...................................................................... 687
Using the Lambda Insights dashboard ............................................................................... 687
Detecting function anomalies ........................................................................................... 688
Troubleshooting a function .............................................................................................. 690
What's next? .................................................................................................................. 685
Function metrics ..................................................................................................................... 692
Viewing metrics in the CloudWatch console ....................................................................... 692
Types of metrics ............................................................................................................. 692
Function logs ......................................................................................................................... 695
Prerequisites .................................................................................................................. 695
Pricing ........................................................................................................................... 695
Using the Lambda console ............................................................................................... 695
Using the AWS CLI .......................................................................................................... 696
What's next? .................................................................................................................. 696

xiv
 AWS Lambda Developer Guide

Example workflows ................................................................................................................. 696

Prerequisites .................................................................................................................. 697
Pricing ........................................................................................................................... 697
Viewing a service map .................................................................................................... 698
Viewing trace details ....................................................................................................... 698
Using Trusted Advisor to view recommendations ................................................................ 699
What's next? .................................................................................................................. 699
Security ......................................................................................................................................... 700
Data protection ...................................................................................................................... 700
Encryption in transit ....................................................................................................... 701
Encryption at rest ........................................................................................................... 701
Identity and access management .............................................................................................. 702
Audience ....................................................................................................................... 702
Authenticating with identities .......................................................................................... 702
Managing access using policies ......................................................................................... 704
How AWS Lambda works with IAM ................................................................................... 706
Identity-based policy examples ........................................................................................ 706
Troubleshooting ............................................................................................................. 707
Compliance validation ............................................................................................................. 710
Resilience .............................................................................................................................. 710
Infrastructure security ............................................................................................................. 711
Configuration and vulnerability analysis .................................................................................... 711
Troubleshooting ............................................................................................................................. 713
Deployment ........................................................................................................................... 713
General: Permission is denied / Cannot load such file .......................................................... 713
General: Error occurs when calling the UpdateFunctionCode ................................................ 713
Amazon S3: Error Code PermanentRedirect. ....................................................................... 714
General: Cannot find, cannot load, unable to import, class not found, no such file or directory ... 714
General: Undefined method handler ................................................................................. 714
Lambda: InvalidParameterValueException or RequestEntityTooLargeException ........................ 715
Lambda: InvalidParameterValueException .......................................................................... 715
Invocation .............................................................................................................................. 715
IAM: lambda:InvokeFunction not authorized ....................................................................... 716
Lambda: Operation cannot be performed ResourceConflictException ..................................... 716
Lambda: Function is stuck in Pending ............................................................................... 716
Lambda: One function is using all concurrency ................................................................... 716
General: Cannot invoke function with other accounts or services ........................................... 717
General: Function invocation is looping ............................................................................. 717
Lambda: Alias routing with provisioned concurrency ........................................................... 717
Lambda: Cold starts with provisioned concurrency .............................................................. 717
Lambda: Latency variability with provisioned concurrency .................................................... 718
Lambda: Cold starts with new versions .............................................................................. 718
EFS: Function could not mount the EFS file system ............................................................. 718
EFS: Function could not connect to the EFS file system ....................................................... 718
EFS: Function could not mount the EFS file system due to timeout ....................................... 719
Lambda: Lambda detected an IO process that was taking too long ........................................ 719
Execution ............................................................................................................................... 719
Lambda: Execution takes too long .................................................................................... 719
Lambda: Logs or traces don't appear ................................................................................ 719
Lambda: The function returns before execution finishes ...................................................... 720
AWS SDK: Versions and updates ....................................................................................... 720
Python: Libraries load incorrectly ...................................................................................... 720
Networking ............................................................................................................................ 721
VPC: Function loses internet access or times out ................................................................. 721
VPC: Function needs access to AWS services without using the internet ................................. 721
VPC: Limit was reached for the function's VPC ................................................................... 721
Container images .................................................................................................................... 721

xv
 AWS Lambda Developer Guide

Container: Error occurs on runtime InvalidEntrypoint .......................................................... 721

Lambda: System provisioning additonal capacity ................................................................ 721
CloudFormation: ENTRYPOINT is being overridden with a null or empty value ........................ 722
Releases ........................................................................................................................................ 723
Earlier updates ....................................................................................................................... 732
API reference ................................................................................................................................. 737
Actions .................................................................................................................................. 737
AddLayerVersionPermission .............................................................................................. 739
AddPermission ............................................................................................................... 743
CreateAlias ..................................................................................................................... 747
CreateCodeSigningConfig ................................................................................................ 751
CreateEventSourceMapping .............................................................................................. 754
CreateFunction ............................................................................................................... 763
DeleteAlias ..................................................................................................................... 775
DeleteCodeSigningConfig ................................................................................................ 777
DeleteEventSourceMapping .............................................................................................. 779
DeleteFunction ............................................................................................................... 784
DeleteFunctionCodeSigningConfig .................................................................................... 786
DeleteFunctionConcurrency .............................................................................................. 788
DeleteFunctionEventInvokeConfig ..................................................................................... 790
DeleteLayerVersion ......................................................................................................... 792
DeleteProvisionedConcurrencyConfig ................................................................................ 794
GetAccountSettings ......................................................................................................... 796
GetAlias ......................................................................................................................... 798
GetCodeSigningConfig ..................................................................................................... 801
GetEventSourceMapping .................................................................................................. 803
GetFunction ................................................................................................................... 808
GetFunctionCodeSigningConfig ........................................................................................ 812
GetFunctionConcurrency .................................................................................................. 815
GetFunctionConfiguration ................................................................................................ 817
GetFunctionEventInvokeConfig ......................................................................................... 824
GetLayerVersion ............................................................................................................. 827
GetLayerVersionByArn ..................................................................................................... 830
GetLayerVersionPolicy ..................................................................................................... 833
GetPolicy ....................................................................................................................... 835
GetProvisionedConcurrencyConfig ..................................................................................... 837
Invoke ........................................................................................................................... 840
InvokeAsync ................................................................................................................... 846
ListAliases ...................................................................................................................... 848
ListCodeSigningConfigs ................................................................................................... 851
ListEventSourceMappings ................................................................................................ 853
ListFunctionEventInvokeConfigs ........................................................................................ 856
ListFunctions .................................................................................................................. 859
ListFunctionsByCodeSigningConfig .................................................................................... 863
ListLayers ...................................................................................................................... 865
ListLayerVersions ............................................................................................................ 867
ListProvisionedConcurrencyConfigs ................................................................................... 870
ListTags ......................................................................................................................... 873
ListVersionsByFunction .................................................................................................... 875
PublishLayerVersion ........................................................................................................ 879
PublishVersion ................................................................................................................ 883
PutFunctionCodeSigningConfig ......................................................................................... 891
PutFunctionConcurrency .................................................................................................. 894
PutFunctionEventInvokeConfig ......................................................................................... 897
PutProvisionedConcurrencyConfig ..................................................................................... 901
RemoveLayerVersionPermission ........................................................................................ 904
RemovePermission .......................................................................................................... 906

xvi
 AWS Lambda Developer Guide

TagResource ................................................................................................................... 908

UntagResource ............................................................................................................... 910
UpdateAlias ................................................................................................................... 912
UpdateCodeSigningConfig ............................................................................................... 916
UpdateEventSourceMapping ............................................................................................ 919
UpdateFunctionCode ....................................................................................................... 927
UpdateFunctionConfiguration ........................................................................................... 936
UpdateFunctionEventInvokeConfig .................................................................................... 947
Data Types ............................................................................................................................ 950
AccountLimit .................................................................................................................. 952
AccountUsage ................................................................................................................ 953
AliasConfiguration .......................................................................................................... 954
AliasRoutingConfiguration ............................................................................................... 956
AllowedPublishers ........................................................................................................... 957
CodeSigningConfig ......................................................................................................... 958
CodeSigningPolicies ........................................................................................................ 960
Concurrency ................................................................................................................... 961
DeadLetterConfig ........................................................................................................... 962
DestinationConfig ........................................................................................................... 963
Environment .................................................................................................................. 964
EnvironmentError ........................................................................................................... 965
EnvironmentResponse ..................................................................................................... 966
EventSourceMappingConfiguration ................................................................................... 967
FileSystemConfig ............................................................................................................ 971
FunctionCode ................................................................................................................. 972
FunctionCodeLocation ..................................................................................................... 974
FunctionConfiguration ..................................................................................................... 975
FunctionEventInvokeConfig .............................................................................................. 980
ImageConfig .................................................................................................................. 982
ImageConfigError ........................................................................................................... 983
ImageConfigResponse ..................................................................................................... 984
Layer ............................................................................................................................. 985
LayersListItem ................................................................................................................ 986
LayerVersionContentInput ................................................................................................ 987
LayerVersionContentOutput ............................................................................................. 988
LayerVersionsListItem ...................................................................................................... 989
OnFailure ....................................................................................................................... 991
OnSuccess ..................................................................................................................... 992
ProvisionedConcurrencyConfigListItem .............................................................................. 993
SelfManagedEventSource ................................................................................................. 995
SourceAccessConfiguration ............................................................................................... 996
TracingConfig ................................................................................................................. 997
TracingConfigResponse .................................................................................................... 998
VpcConfig ...................................................................................................................... 999
VpcConfigResponse ....................................................................................................... 1000
Certificate errors when using an SDK ...................................................................................... 1000
AWS glossary ............................................................................................................................... 1002

xvii
 AWS Lambda Developer Guide
When should I use Lambda?

What is AWS Lambda?

Lambda is a compute service that lets you run code without provisioning or managing servers. Lambda
runs your code on a high-availability compute infrastructure and performs all of the administration of
the compute resources, including server and operating system maintenance, capacity provisioning and
automatic scaling, code monitoring and logging. With Lambda, you can run code for virtually any type
of application or backend service. All you need to do is supply your code in one of the languages that
Lambda supports (p. 195).
Note
In the AWS Lambda Developer Guide, we assume that you have experience with coding,
compiling, and deploying programs using one of the supported languages.

You organize your code into Lambda functions (p. 29). Lambda runs your function only when needed
and scales automatically, from a few requests per day to thousands per second. You pay only for the
compute time that you consume—there is no charge when your code is not running.

You can invoke your Lambda functions using the Lambda API, or Lambda can run your functions in
response to events from other AWS services. For example, you can use Lambda to:

• Build data-processing triggers for AWS services such as Amazon Simple Storage Service (Amazon S3)
and Amazon DynamoDB.
• Process streaming data stored in Amazon Kinesis.
• Create your own backend that operates at AWS scale, performance, and security.

Lambda is a highly available service. For more information, see the AWS Lambda Service Level
Agreement.

Sections
• When should I use Lambda? (p. 1)
• Lambda features (p. 2)
• Getting started with Lambda (p. 2)
• Related services (p. 3)
• Accessing Lambda (p. 3)
• Pricing for Lambda (p. 4)

When should I use Lambda?

Lambda is an ideal compute service for many application scenarios, as long as you can run your
application code using the Lambda standard runtime environment (p. 200) and within the resources
that Lambda provides.

When using Lambda, you are responsible only for your code. Lambda manages the compute fleet that
offers a balance of memory, CPU, network, and other resources to run your code. Because Lambda
manages these resources, you cannot log in to compute instances or customize the operating system on
provided runtimes (p. 195). Lambda performs operational and administrative activities on your behalf,
including managing capacity, monitoring, and logging your Lambda functions.

If you need to manage your own compute resources, AWS has other compute services to meet your
needs. For example:

1
 AWS Lambda Developer Guide
Lambda features

• Amazon Elastic Compute Cloud (Amazon EC2) offers a wide range of EC2 instance types to choose
from. It lets you customize operating systems, network and security settings, and the entire software
stack. You are responsible for provisioning capacity, monitoring fleet health and performance, and
using Availability Zones for fault tolerance.
• AWS Elastic Beanstalk enables you to deploy and scale applications onto Amazon EC2. You retain
ownership and full control over the underlying EC2 instances.

Lambda features
The following key features help you develop Lambda applications that are scalable, secure, and easily
extensible:

Concurrency and scaling controls

Concurrency and scaling controls (p. 153) such as concurrency limits and provisioned concurrency
give you fine-grained control over the scaling and responsiveness of your production applications.
Functions defined as container images

Use your preferred container image (p. 247) tooling, workflows, and dependencies to build, test,
and deploy your Lambda functions.
Code signing

Code signing (p. 130) for Lambda provides trust and integrity controls that let you verify that only
unaltered code that approved developers have published is deployed in your Lambda functions.
Lambda extensions

You can use Lambda extensions (p. 209) to augment your Lambda functions. For example, use
extensions to more easily integrate Lambda with your favorite tools for monitoring, observability,
security, and governance.
Function blueprints

A function blueprint provides sample code that shows how to use Lambda with other AWS services
or third-party applications. Blueprints include sample code and function configuration presets for
Node.js and Python runtimes.
Database access

A database proxy (p. 121) manages a pool of database connections and relays queries from a
function. This enables a function to reach high concurrency levels without exhausting database
connections.
File systems access

You can configure a function to mount an Amazon Elastic File System (Amazon EFS) file
system (p. 126) to a local directory. With Amazon EFS, your function code can access and modify
shared resources safely and at high concurrency.

Getting started with Lambda

To work effectively with Lambda, you need coding experience and expertise in the following domains:

• Linux OS and commands, as well as concepts such as processes, threads, and file permissions.
• Cloud concepts and IP networking concepts (for public and private networks).
• Distributed computing concepts such as HTML as an IPC, queues, messaging, notifications, and
concurrency.

2
 AWS Lambda Developer Guide
Related services

• Familiarity with security services and concepts: AWS Identity and Access Management (IAM) and access
control principles, and AWS Key Management Service (AWS KMS) and public key infrastructure.
• Familiarity with key services that interact with Lambda: Amazon API Gateway, Amazon S3, Amazon
Simple Queue Service (Amazon SQS), and DynamoDB.
• Configuring EC2 instances with Linux.

If you are a first-time user of Lambda, we recommend that you start with the following topics to help
you learn the basics:

1. Read the Lambda product overview and explore the Lambda getting started page.
2. To create and test a Lambda function using the Lambda console, try the console-based getting
started exercise (p. 8). This exercise teaches you about the Lambda programming model and
other concepts.
3. If you are familiar with container image workflows, try the getting started exercise to create a
Lambda function defined as a container image (p. 11).

AWS also provides the following resources for learning about serverless applications and Lambda:

• The AWS Compute Blog includes useful articles about Lambda.

• AWS Serverless provides blogs, videos, and training related to AWS serverless development.
• The AWS Online Tech Talks YouTube channel includes videos about Lambda-related topics. For an
overview of serverless applications and Lambda, see the Introduction to AWS Lambda & Serverless
Applications video.

Related services
Lambda integrates with other AWS services (p. 257) to invoke functions based on events that you
specify. For example:

• Use API Gateway (p. 261) to provide a secure and scalable gateway for web APIs that route HTTP
requests to Lambda functions.
• For services that generate a queue or data stream (such as DynamoDB (p. 313) and Kinesis (p. 365)),
Lambda polls the queue or data stream from the service and invokes your function to process the
received data.
• Define Amazon S3 (p. 407) events that invoke a Lambda function to process Amazon S3 objects, for
example, when an object is created or deleted.
• Use a Lambda function to process Amazon SQS (p. 439) messages or Amazon Simple Notification
Service (Amazon SNS) (p. 432) notifications.
• Use AWS Step Functions (p. 455) to connect Lambda functions together into serverless workflows
called state machines.

Accessing Lambda
You can create, invoke, and manage your Lambda functions using any of the following interfaces:

• AWS Management Console – Provides a web interface for you to access your functions. For more
information, see Configuring functions in the console (p. 70).
• AWS Command Line Interface (AWS CLI) – Provides commands for a broad set of AWS services,
including Lambda, and is supported on Windows, macOS, and Linux. For more information, see Using
AWS Lambda with the AWS Command Line Interface (p. 23).

3
 AWS Lambda Developer Guide
Pricing for Lambda

• AWS SDKs – Provide language-specific APIs and manage many of the connection details, such as
signature calculation, request retry handling, and error handling. For more information, see AWS SDKs.
• AWS CloudFormation – Enables you to create templates that define your Lambda applications. For
more information, see AWS Lambda applications (p. 174). AWS CloudFormation also supports the
AWS Cloud Development Kit (CDK).
• AWS Serverless Application Model (AWS SAM) – Provides templates and a CLI to configure and
manage AWS serverless applications. For more information, see AWS SAM (p. 5).

Pricing for Lambda

There is no additional charge for creating Lambda functions. There are charges for running a function
and for data transfer between Lambda and other AWS services. Some optional Lambda features (such as
provisioned concurrency (p. 84)) also incur charges. For more information, see AWS Lambda Pricing.

4
 AWS Lambda Developer Guide
AWS Account

Setting up with Lambda

To use AWS Lambda, you need an AWS account. If you plan to configure and use Lambda functions from
the command line, set up the AWS CLI. You can set up other development and build tools as required for
the environment and language that you are planning to use.

Sections
• AWS Account (p. 5)
• AWS CLI (p. 5)
• AWS SAM (p. 5)
• AWS SAM CLI (p. 6)
• Tools for container images (p. 6)
• Code authoring tools (p. 6)

AWS Account
To use Lambda and other AWS services, you need an AWS account. If you do not have an account, visit
aws.amazon.com and choose Create an AWS Account. For instructions, see How do I create and activate
a new AWS account?

As a best practice, create an AWS Identity and Access Management (IAM) user with administrator
permissions, and then use that IAM user for all work that does not require root credentials. Create a
password for console access, and create access keys to use command line tools. For instructions, see
Creating your first IAM admin user and group in the IAM User Guide.

AWS CLI
If you plan to configure and use Lambda functions from the command line, install the AWS Command
Line Interface (AWS CLI). Tutorials in this guide use the AWS CLI, which has commands for all Lambda API
operations. Some functionality is not available in the Lambda console and can be accessed only with the
AWS CLI or the AWS SDKs.

To set up the AWS CLI, see the following topics in the AWS Command Line Interface User Guide.

• Installing, updating, and uninstalling the AWS CLI

• Configuring the AWS CLI

To verify that the AWS CLI is configured correctly, run the list-functions command to see a list of
your Lambda functions in the current AWS Region.

aws lambda list-functions

AWS SAM
The AWS Serverless Application Model (AWS SAM) is an extension for the AWS CloudFormation template
language that lets you define serverless applications at a higher level. AWS SAM abstracts away common

5
 AWS Lambda Developer Guide
AWS SAM CLI

tasks such as function role creation, making it easier to write templates. AWS SAM is supported directly
by AWS CloudFormation, and includes additional functionality through the AWS CLI and AWS SAM CLI.

For more information about AWS SAM templates, see the AWS SAM specification in the AWS Serverless
Application Model Developer Guide.

AWS SAM CLI

The AWS SAM CLI is a separate command line tool that you can use to manage and test AWS SAM
applications. In addition to commands for uploading artifacts and launching AWS CloudFormation stacks
that are also available in the AWS CLI, the AWS SAM CLI provides commands for validating templates
and running applications locally in a Docker container. You can use the AWS SAM CLI to build functions
deployed as .zip file archives or container images.

To set up the AWS SAM CLI, see Installing the AWS SAM CLI in the AWS Serverless Application Model
Developer Guide.

Tools for container images

To create and test functions deployed as container images, you can use native container tools such as the
Docker CLI.

To set up the Docker CLI, see Get Docker on the Docker Docs website. For an introduction to using Docker
with AWS, see Getting started with Amazon ECR using the AWS CLI in the Amazon Elastic Container
Registry User Guide.

Code authoring tools

You can author your Lambda function code in the languages that Lambda supports. For a list of
supported languages, see Lambda runtimes (p. 195). There are tools for authoring code, such as the
Lambda console, Eclipse integrated development environment (IDE), and Visual Studio IDE. But the
available tools and options depend on:

• The language that you use to write your Lambda function code.
• The libraries that you use in your code. The Lambda runtimes provide some of the libraries, and you
must upload any additional libraries that you use.

The following table lists the languages that Lambda supports, and the tools and options that you can
use with them.

Language Tools and options for authoring code

Node.js • Lambda console

• Visual Studio, with IDE plugin (see AWS Lambda Support in Visual
Studio on the AWS Developer Blog)
• Your own authoring environment

Java • Eclipse, with the AWS Toolkit for Eclipse

• IntelliJ, with the AWS Toolkit for JetBrains
• Your own authoring environment

6
 AWS Lambda Developer Guide
Code authoring tools

Language Tools and options for authoring code

C# • Visual Studio, with IDE plugin (see AWS Toolkit for Visual Studio)
• .NET Core (see Download .NET on the Microsoft website)
• Your own authoring environment

Python • Lambda console

• PyCharm, with the AWS Toolkit for JetBrains
• Your own authoring environment

Ruby • Lambda console

• Your own authoring environment

Go • Your own authoring environment

PowerShell • Your own authoring environment

• PowerShell Core 6.0 (see Installing various versions of PowerShell
on the Microsoft Docs website)
• .NET Core 3.1 SDK (see Download .NET on the Microsoft website)
• AWSLambdaPSCore module (see AWSLambdaPSCore on the
PowerShell Gallery website)

7
 AWS Lambda Developer Guide

Getting started with Lambda

To get started with Lambda, use the Lambda console to create a function. In a few minutes, you can
create a function, invoke it, and then view logs, metrics, and trace data.
Note
To use Lambda and other AWS services, you need an AWS account. If you don't have an account,
visit aws.amazon.com and choose Create an AWS Account. For instructions, see How do I create
and activate a new AWS account?
As a best practice, create an AWS Identity and Access Management (IAM) user with administrator
permissions, and then use that IAM user for all work that does not require root credentials.
Create a password for console access, and create access keys to use command line tools. For
instructions, see Creating your first IAM admin user and group in the IAM User Guide.

You can author functions in the Lambda console, or with an IDE toolkit, command line tools, or the AWS
SDKs. The Lambda console provides a code editor (p. 17) for non-compiled languages that lets you
modify and test code quickly. The AWS Command Line Interface (AWS CLI) (p. 23) gives you direct
access to the Lambda API for advanced configuration and automation use cases.

You deploy your function code to Lambda using a deployment package. Lambda supports two types of
deployment packages:

• A .zip file archive that contains your function code and its dependencies. For an example tutorial, see
Using AWS Lambda with the AWS Command Line Interface (p. 23).
• A container image that is compatible with the Open Container Initiative (OCI) specification. For an
example tutorial, see Create a function defined as a container image (p. 11).

Topics
• Create a Lambda function with the console (p. 9)
• Creating functions using the AWS Lambda console editor (p. 17)
• Using AWS Lambda with the AWS Command Line Interface (p. 23)
• Lambda concepts (p. 29)
• Lambda features (p. 32)
• Lambda deployment packages (p. 41)
• Lambda quotas (p. 44)

8
 AWS Lambda Developer Guide
Create a function

Create a Lambda function with the console

In the following getting started exercises, you create Lambda functions using the console.

In the first exercise, you create a function and use the default code that Lambda creates. The Lambda
console provides a code editor (p. 17) for non-compiled languages that lets you modify and test code
quickly.

In the next exercise, you create a function defined as a container image. First, create a container image
for your function code, and then use the Lambda console to create a function from the container image.

Topics
• Create a Lambda function with default function code (p. 9)
• Create a function defined as a container image (p. 11)

Create a Lambda function with default function code

In this getting started exercise, you create a Node.js Lambda function using the Lambda console. Lambda
automatically creates default code for the function. Next, you manually invoke the Lambda function
using sample event data. Lambda runs the function and returns results. You then verify the results,
including the logs that your Lambda function created and various Amazon CloudWatch metrics.

To create a Lambda function with the console

1. Open the Functions page on the Lambda console.

2. Choose Create function.
3. Under Basic information, do the following:

a. For Function name, enter my-function.

b. For Runtime, confirm that Node.js 14.x is selected. Note that Lambda provides runtimes
for .NET (PowerShell, C#), Go, Java, Node.js, Python, and Ruby.
4. Choose Create function.

Lambda creates a Node.js function and an execution role (p. 47) that grants the function permission
to upload logs. The Lambda function assumes the execution role when you invoke your function, and
uses the execution role to create credentials for the AWS SDK and to read data from event sources.

Use the function overview

The Function overview shows a visualization of your function, including any triggers, destinations, and
layer that you have configured for the function.

9
 AWS Lambda Developer Guide
Create a Lambda function with default function code

Invoke the Lambda function

Invoke your Lambda function using the sample event data provided in the console.

To invoke a function

1. After selecting your function, choose the Test tab.

2. In the Test event section, choose New event. In Template, leave the default hello-world option.
Enter a Name for this test and note the following sample event template:

{
"key1": "value1",
"key2": "value2",
"key3": "value3"
}

3. Choose Save changes, and then choose Test. Each user can create up to 10 test events per function.
Those test events are not available to other users.

Lambda runs your function on your behalf. The function handler receives and then processes the
sample event.
4. Upon successful completion, view the results in the console.

• The Execution result shows the execution status as succeeded. To view the function execution
results, expand Details. Note that the logs link opens the Log groups page in the CloudWatch
console.
• The Summary section shows the key information reported in the Log output section (the REPORT
line in the execution log).
• The Log output section shows the log that Lambda generates for each invocation. The function
writes these logs to CloudWatch. The Lambda console shows these logs for your convenience.
Choose Click here to add logs to the CloudWatch log group and open the Log groups page in the
CloudWatch console.
5. Run the function (choose Test) a few more times to gather some metrics that you can view in the
next step.
6. Choose the Monitor tab. This page shows graphs for the metrics that Lambda sends to CloudWatch.

For more information on these graphs, see Monitoring functions in the AWS Lambda
console (p. 684).

10
 AWS Lambda Developer Guide
Create a function defined as a container image

Clean up
If you are done working with the example function, delete it. You can also delete the log group that
stores the function's logs, and the execution role that the console created.

To delete a Lambda function

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Actions, Delete.
4. In the Delete function dialog box, choose Delete.

To delete the log group

1. Open the Log groups page of the CloudWatch console.

2. Select the function's log group (/aws/lambda/my-function).
3. Choose Actions, Delete log group(s).
4. In the Delete log group(s) dialog box, choose Delete.

To delete the execution role

1. Open the Roles page of the AWS Identity and Access Management (IAM) console.
2. Select the function's role (my-function-role-31exxmpl).
3. Choose Delete role.
4. In the Delete role dialog box, choose Yes, delete.

You can automate the creation and cleanup of functions, log groups, and roles with AWS
CloudFormation and the AWS Command Line Interface (AWS CLI). For fully functional sample
applications, see Lambda sample applications (p. 464).

Create a function defined as a container image

In this getting started exercise, you use the Docker CLI to create a container image and then use the
Lambda console to create a function from the container image.

Topics
• Prerequisites (p. 11)
• Create the container image (p. 12)
• Upload the image to the Amazon ECR repository (p. 13)
• Update the user permissions (p. 13)
• Create a Lambda function defined as a container image (p. 14)
• Invoke the Lambda function (p. 14)
• Clean up (p. 15)

Prerequisites
To complete the following steps, you need a command line terminal or shell to run commands.
Commands and the expected output are listed in separate blocks:

11
 AWS Lambda Developer Guide
Create a function defined as a container image

aws --version

You should see the following output:

aws-cli/2.0.57 Python/3.7.4 Darwin/19.6.0 exe/x86_64

For long commands, an escape character (\) is used to split a command over multiple lines.

On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

This exercise uses Docker CLI commands to create the container image. To install the Docker CLI, see Get
Docker on the Docker Docs website.

Create the container image

AWS provides a set of base images in the Amazon Elastic Container Registry (Amazon ECR). In
this getting started exercise, we use the Node.js base image to create a container image. For more
information about base images, see AWS base images for Lambda (p. 203).

In the following commands, replace 123456789012 with your AWS account ID.

To create an image using the AWS Node.js 12 base image

1. On your local machine, create a project directory for your new function.
2. Create a file named app.js in your project directory. Add the following code to app.js:

exports.handler = async (event) => {

// TODO implement
const response = {
statusCode: 200,
body: JSON.stringify('Hello from Lambda!'),
};
return response;
};

3. Use a text editor to create a new file named Dockerfile in your project directory. Add the
following content to Dockerfile:

FROM public.ecr.aws/lambda/nodejs:12

# Copy function code and package.json

COPY app.js package.json /var/task/

# Install NPM dependencies for function

RUN npm install

# Set the CMD to your handler

CMD [ "app.handler" ]

4. Create the package.json file. From your project directory, run the npm init command. Accept all
of the default values:

npm init

5. Build your Docker image. From your project directory, run the following command:

12
 AWS Lambda Developer Guide
Create a function defined as a container image

docker build -t hello-world .

6. (Optional) AWS base images include the Lambda runtime interface emulator, so you can test your
function locally.

a. Run your Docker image. From your project directory, run the docker run command:

docker run -p 9000:8080 hello-world:latest

b. Test your Lambda function. In a new terminal window, run a curl command to invoke your
function:

curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d

'{}'

Upload the image to the Amazon ECR repository

1. Authenticate the Docker CLI to your Amazon ECR registry.

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-
stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

2. Create a repository in Amazon ECR using the create-repository command.

aws ecr create-repository --repository-name hello-world --image-scanning-configuration

scanOnPush=true --image-tag-mutability MUTABLE

3. Tag your image to match your repository name using the docker tag command.

docker tag hello-world:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/hello-

world:latest

4. Deploy the image to Amazon ECR using the docker push command.

docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest

Update the user permissions

Make sure that the permissions for the IAM user or role that creates the function contain the AWS
managed policies GetRepositoryPolicy, SetRepositoryPolicy, and InitiateLayerUpload. For
information about access policies, see Access Management in the IAM User Guide

For example, use the IAM console to create a role with the following policy:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": ["ecr:SetRepositoryPolicy","ecr:GetRepositoryPolicy",
"ecr:InitiateLayerUpload],
"Resource": "arn:aws:ecr:<region>:<account>:repository/<repo name>/"
}

13
 AWS Lambda Developer Guide
Create a function defined as a container image

]
}

Create a Lambda function defined as a container image

Use the Lambda console to create a function defined as a container image.

To create the function with the console

1. Open the Functions page on the Lambda console.

2. Choose Create function.
3. Choose the Container image option.
4. Under Basic information, do the following:

a. For Function name, enter my-function.

b. For Container image URI, enter the URI of the Amazon ECR image that you created previously.
5. Choose Create function.

Lambda creates your function and an execution role (p. 47) that grants the function permission to
upload logs. Lambda assumes the execution role when you invoke your function, and uses the execution
role to create credentials for the AWS SDK and to read data from event sources.

Invoke the Lambda function

Invoke your Lambda function using the sample event data provided in the console.

To invoke a function

1. After selecting your function, choose the Test tab.

2. In the Test event section, choose New event. In Template, leave the default hello-world option.
Enter a Name for this test and note the following sample event template:

{
"key1": "value1",
"key2": "value2",
"key3": "value3"
}

3. Choose Save changes, and then choose Test. Each user can create up to 10 test events per function.
Those test events are not available to other users.

Lambda runs your function on your behalf. The function handler receives and then processes the
sample event.
4. Upon successful completion, view the results in the console.

• The Execution result shows the execution status as succeeded. To view the function execution
results, expand Details. Note that the logs link opens the Log groups page in the CloudWatch
console.
• The Summary section shows the key information reported in the Log output section (the REPORT
line in the execution log).
• The Log output section shows the log that Lambda generates for each invocation. The function
writes these logs to CloudWatch. The Lambda console shows these logs for your convenience.
Choose Click here to add logs to the CloudWatch log group and open the Log groups page in the
CloudWatch console.

14
 AWS Lambda Developer Guide
Create a function defined as a container image

5. Run the function (choose Test) a few more times to gather some metrics that you can view in the
next step.
6. Choose the Monitor tab. This page shows graphs for the metrics that Lambda sends to CloudWatch.

For more information on these graphs, see Monitoring functions in the AWS Lambda
console (p. 684).

Clean up
If you are finished with the container image, see Deleting an image in the Amazon Elastic Container
Registry User Guide

If you are done working with your function, delete it. You can also delete the log group that stores the
function's logs and the execution role that the console created.

To delete a Lambda function

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Actions, Delete.
4. In the Delete function dialog box, choose Delete.

To delete the log group

1. Open the Log groups page of the CloudWatch console.

2. Select the function's log group (/aws/lambda/my-function).
3. Choose Actions, Delete log group(s).
4. In the Delete log group(s) dialog box, choose Delete.

To delete the execution role

1. Open the Roles page of the IAM console.

2. Select the function's role (my-function-role-31exxmpl).
3. Choose Delete role.
4. In the Delete role dialog box, choose Yes, delete.

15
 AWS Lambda Developer Guide
Create a function defined as a container image

You can automate the creation and cleanup of functions, log groups, and roles with AWS
CloudFormation and the AWS CLI. For fully functional sample applications, see Lambda sample
applications (p. 464).

16
 AWS Lambda Developer Guide
Code editor

Creating functions using the AWS Lambda console

editor
The Lambda console provides a code editor for languages that do not require compiling, such as Node.js
or Python. The code editor in the AWS Lambda console enables you to write, test, and view the execution
results of your Lambda function code.

The code editor includes the menu bar, windows, and the editor pane.

For a list of what the commands do, see the Menu commands reference in the AWS Cloud9 User Guide.
Note that some of the commands listed in that reference are not available in the code editor.

Topics
• Working with files and folders (p. 17)
• Working with code (p. 19)
• Working in fullscreen mode (p. 22)
• Working with preferences (p. 22)

Working with files and folders

You can use the Environment window in the code editor to create, open, and manage files for your
function.

To show or hide the Environment window, choose the Environment button. If the Environment button
is not visible, choose Window, Environment on the menu bar.

17
 AWS Lambda Developer Guide
Working with files and folders

To open a single file and show its contents in the editor pane, double-click the file in the Environment
window.

To open multiple files and show their contents in the editor pane, choose the files in the Environment
window. Right-click the selection, and then choose Open.

To create a new file, do one of the following:

• In the Environment window, right-click the folder where you want the new file to go, and then choose
New File. Type the file's name and extension, and then press Enter.
• Choose File, New File on the menu bar. When you're ready to save the file, choose File, Save or File,
Save As on the menu bar. Then use the Save As dialog box that displays to name the file and choose
where to save it.
• In the tab buttons bar in the editor pane, choose the + button, and then choose New File. When you're
ready to save the file, choose File, Save or File, Save As on the menu bar. Then use the Save As dialog
box that displays to name the file and choose where to save it.

To create a new folder, right-click the folder in the Environment window where you want the new
folder to go, and then choose New Folder. Type the folder's name, and then press Enter.

To save a file, with the file open and its contents visible in the editor pane, choose File, Save on the
menu bar.

To rename a file or folder, right-click the file or folder in the Environment window. Type the
replacement name, and then press Enter.

To delete files or folders, choose the files or folders in the Environment window. Right-click the
selection, and then choose Delete. Then confirm the deletion by choosing Yes (for a single selection) or
Yes to All.

To cut, copy, paste, or duplicate files or folders, choose the files or folders in the Environment window.
Right-click the selection, and then choose Cut, Copy, Paste, or Duplicate, respectively.

18
 AWS Lambda Developer Guide
Working with code

To collapse folders, choose the gear icon in the Environment window, and then choose Collapse All
Folders.

To show or hide hidden files, choose the gear icon in the Environment window, and then choose Show
Hidden Files.

Working with code

Use the editor pane in the code editor to view and write code.

Working with tab buttons

Use the tab buttons bar to select, view, and create files.

To display an open file's contents, do one of the following:

• Choose the file's tab.

• Choose the drop-down menu button in the tab buttons bar, and then choose the file's name.

19
 AWS Lambda Developer Guide
Working with code

To close an open file, do one of the following:

• Choose the X icon in the file's tab.

• Choose the file's tab. Then choose the drop-down menu button in the tab buttons bar, and choose
Close Pane.

To close multiple open files, choose the drop-down menu in the tab buttons bar, and then choose Close
All Tabs in All Panes or Close All But Current Tab as needed.

To create a new file, choose the + button in the tab buttons bar, and then choose New File. When you're
ready to save the file, choose File, Save or File, Save As on the menu bar. Then use the Save As dialog
box that displays to name the file and choose where to save it.

Working with the status bar

Use the status bar to move quickly to a line in the active file and to change how code is displayed.

To move quickly to a line in the active file, choose the line selector, type the line number to go to, and
then press Enter.

20
 AWS Lambda Developer Guide
Working with code

To change the code color scheme in the active file, choose the code color scheme selector, and then
choose the new code color scheme.

To change in the active file whether soft tabs or spaces are used, the tab size, or whether to convert
to spaces or tabs, choose the spaces and tabs selector, and then choose the new settings.

To change for all files whether to show or hide invisible characters or the gutter, auto-pair brackets
or quotes, wrap lines, or the font size, choose the gear icon, and then choose the new settings.

21
 AWS Lambda Developer Guide
Working in fullscreen mode

Working in fullscreen mode

You can expand the code editor to get more room to work with your code.

To expand the code editor to the edges of the web browser window, choose the Toggle fullscreen
button in the menu bar.

To shrink the code editor to its original size, choose the Toggle fullscreen button again.

In fullscreen mode, additional options are displayed on the menu bar: Save and Test. Choosing Save
saves the function code. Choosing Test or Configure Events enables you to create or edit the function's
test events.

Working with preferences

You can change various code editor settings such as which coding hints and warnings are displayed, code
folding behaviors, code autocompletion behaviors, and much more.

To change code editor settings, choose the Preferences gear icon in the menu bar.

For a list of what the settings do, see the following references in the AWS Cloud9 User Guide.

• Project setting changes you can make

• User setting changes you can make

Note that some of the settings listed in those references are not available in the code editor.

22
 AWS Lambda Developer Guide
AWS CLI

Using AWS Lambda with the AWS Command Line

Interface
You can use the AWS Command Line Interface to manage functions and other AWS Lambda resources.
The AWS CLI uses the AWS SDK for Python (Boto) to interact with the Lambda API. You can use it to
learn about the API, and apply that knowledge in building applications that use Lambda with the AWS
SDK.

In this tutorial, you manage and invoke Lambda functions with the AWS CLI. For more information, see
What is the AWS CLI? in the AWS Command Line Interface User Guide.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in the section called “Create a function” (p. 9).

To complete the following steps, you need a command line terminal or shell to run commands.
Commands and the expected output are listed in separate blocks:

aws --version

You should see the following output:

aws-cli/2.0.57 Python/3.7.4 Darwin/19.6.0 exe/x86_64

For long commands, an escape character (\) is used to split a command over multiple lines.

On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

This tutorial uses the AWS Command Line Interface (AWS CLI) to call service API operations. To install the
AWS CLI, see Installing the AWS CLI in the AWS Command Line Interface User Guide.

Create the execution role

Create the execution role (p. 47) that gives your function permission to access AWS resources. To
create an execution role with the AWS CLI, use the create-role command.

aws iam create-role --role-name lambda-ex --assume-role-policy-document file://trust-

policy.json

You should see the following output:

{
"Role": {
"Path": "/",
"RoleName": "lambda-ex",
"RoleId": "AROAQFOXMPL6TZ6ITKWND",
"Arn": "arn:aws:iam::123456789012:role/lambda-ex",
"CreateDate": "2020-01-17T23:19:12Z",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{

23
 AWS Lambda Developer Guide
Create the function

"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
}

The trust-policy.json file is a JSON file in the current directory that defines the trust policy for
the role. This trust policy allows Lambda to use the role's permissions by giving the service principal
lambda.amazonaws.com permission to call the AWS Security Token Service AssumeRole action.

Example trust-policy.json

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

You can also specify the trust policy inline. Requirements for escaping quotes in the JSON string vary
depending on your shell.

aws iam create-role --role-name lambda-ex --assume-role-policy-document '{"Version":

"2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service":
"lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'

To add permissions to the role, use the attach-policy-to-role command. Start by adding the
AWSLambdaBasicExecutionRole managed policy.

aws iam attach-role-policy --role-name lambda-ex --policy-arn arn:aws:iam::aws:policy/

service-role/AWSLambdaBasicExecutionRole

The AWSLambdaBasicExecutionRole policy has the permissions that the function needs to write logs to
CloudWatch Logs.

Create the function

The following example logs the values of environment variables and the event object.

Example index.js

exports.handler = async function(event, context) {

console.log("ENVIRONMENT VARIABLES\n" + JSON.stringify(process.env, null, 2))
console.log("EVENT\n" + JSON.stringify(event, null, 2))
return context.logStreamName
}

24
 AWS Lambda Developer Guide
Create the function

To create the function

1. Copy the sample code into a file named index.js.

2. Create a deployment package.

zip function.zip index.js

3. Create a Lambda function with the create-function command. Replace the highlighted text in
the role ARN with your account ID.

aws lambda create-function --function-name my-function \

--zip-file fileb://function.zip --handler index.handler --runtime nodejs12.x \
--role arn:aws:iam::123456789012:role/lambda-ex

You should see the following output:

{
"FunctionName": "my-function",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"Runtime": "nodejs12.x",
"Role": "arn:aws:iam::123456789012:role/lambda-ex",
"Handler": "index.handler",
"CodeSha256": "FpFMvUhayLkOoVBpNuNiIVML/tuGv2iJQ7t0yWVTU8c=",
"Version": "$LATEST",
"TracingConfig": {
"Mode": "PassThrough"
},
"RevisionId": "88ebe1e1-bfdf-4dc3-84de-3017268fa1ff",
...
}

To get logs for an invocation from the command line, use the --log-type option. The response
includes a LogResult field that contains up to 4 KB of base64-encoded logs from the invocation.

aws lambda invoke --function-name my-function out --log-type Tail

You should see the following output:

{
"StatusCode": 200,
"LogResult":
"U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
"ExecutedVersion": "$LATEST"
}

You can use the base64 utility to decode the logs.

aws lambda invoke --function-name my-function out --log-type Tail \

--query 'LogResult' --output text | base64 -d

You should see the following output:

START RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Version: $LATEST

"AWS_SESSION_TOKEN": "AgoJb3JpZ2luX2VjELj...", "_X_AMZN_TRACE_ID": "Root=1-5d02e5ca-
f5792818b6fe8368e5b51d50;Parent=191db58857df8395;Sampled=0"",ask/lib:/opt/lib",
END RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8

25
 AWS Lambda Developer Guide
Create the function

REPORT RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Duration: 79.67 ms Billed

Duration: 80 ms Memory Size: 128 MB Max Memory Used: 73 MB

The base64 utility is available on Linux, macOS, and Ubuntu on Windows. For macOS, the command is
base64 -D.

To get full log events from the command line, you can include the log stream name in the output of your
function, as shown in the preceding example. The following example script invokes a function named
my-function and downloads the last five log events.

Example get-logs.sh Script

This example requires that my-function returns a log stream ID.

#!/bin/bash
aws lambda invoke --function-name my-function --cli-binary-format raw-in-base64-out --
payload '{"key": "value"}' out
sed -i'' -e 's/"//g' out
sleep 15
aws logs get-log-events --log-group-name /aws/lambda/my-function --log-stream-name $(cat
out) --limit 5

The script uses sed to remove quotes from the output file, and sleeps for 15 seconds to allow time for
the logs to be available. The output includes the response from Lambda and the output from the get-
log-events command.

./get-logs.sh

You should see the following output:

{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
{
"events": [
{
"timestamp": 1559763003171,
"message": "START RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf Version:
$LATEST\n",
"ingestionTime": 1559763003309
},
{
"timestamp": 1559763003173,
"message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf
\tINFO\tENVIRONMENT VARIABLES\r{\r \"AWS_LAMBDA_FUNCTION_VERSION\": \"$LATEST\",\r ...",
"ingestionTime": 1559763018353
},
{
"timestamp": 1559763003173,
"message": "2019-06-05T19:30:03.173Z\t4ce9340a-b765-490f-ad8a-02ab3415e2bf
\tINFO\tEVENT\r{\r \"key\": \"value\"\r}\n",
"ingestionTime": 1559763018353
},
{
"timestamp": 1559763003218,
"message": "END RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\n",
"ingestionTime": 1559763018353
},
{
"timestamp": 1559763003218,

26
 AWS Lambda Developer Guide
List the Lambda functions in your account

"message": "REPORT RequestId: 4ce9340a-b765-490f-ad8a-02ab3415e2bf\tDuration:

26.73 ms\tBilled Duration: 27 ms \tMemory Size: 128 MB\tMax Memory Used: 75 MB\t\n",
"ingestionTime": 1559763018353
}
],
"nextForwardToken": "f/34783877304859518393868359594929986069206639495374241795",
"nextBackwardToken": "b/34783877303811383369537420289090800615709599058929582080"
}

List the Lambda functions in your account

Run the following AWS CLI list-functions command to retrieve a list of functions that you have
created.

aws lambda list-functions --max-items 10

You should see the following output:

{
"Functions": [
{
"FunctionName": "cli",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"Runtime": "nodejs12.x",
"Role": "arn:aws:iam::123456789012:role/lambda-ex",
"Handler": "index.handler",
...
},
{
"FunctionName": "random-error",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:random-error",
"Runtime": "nodejs12.x",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Handler": "index.handler",
...
},
...
],
"NextToken": "eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxMH0="
}

In response, Lambda returns a list of up to 10 functions. If there are more functions you can retrieve,
NextToken provides a marker you can use in the next list-functions request. The following list-
functions AWS CLI command is an example that shows the --starting-token parameter.

aws lambda list-functions --max-items 10 --starting-

token eyJNYXJrZXIiOiBudWxsLCAiYm90b190cnVuY2F0ZV9hbW91bnQiOiAxMH0=

Retrieve a Lambda function

The Lambda CLI get-function command returns Lambda function metadata and a presigned URL that
you can use to download the function's deployment package.

aws lambda get-function --function-name my-function

You should see the following output:

27
 AWS Lambda Developer Guide
Clean up

{
"Configuration": {
"FunctionName": "my-function",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"Runtime": "nodejs12.x",
"Role": "arn:aws:iam::123456789012:role/lambda-ex",
"CodeSha256": "FpFMvUhayLkOoVBpNuNiIVML/tuGv2iJQ7t0yWVTU8c=",
"Version": "$LATEST",
"TracingConfig": {
"Mode": "PassThrough"
},
"RevisionId": "88ebe1e1-bfdf-4dc3-84de-3017268fa1ff",
...
},
"Code": {
"RepositoryType": "S3",
"Location": "https://awslambda-us-east-2-tasks.s3.us-east-2.amazonaws.com/
snapshots/123456789012/my-function-4203078a-b7c9-4f35-..."
}
}

For more information, see GetFunction (p. 808).

Clean up
Run the following delete-function command to delete the my-function function.

aws lambda delete-function --function-name my-function

Delete the IAM role you created in the IAM console. For information about deleting a role, see Deleting
roles or instance profiles in the IAM User Guide.

28
 AWS Lambda Developer Guide
Concepts

Lambda concepts
With Lambda, you run functions to process events. To send events to your function, you can invoke it
using the Lambda API, or you can configure an AWS service or resource to invoke it.

Concepts
• Function (p. 29)
• Trigger (p. 29)
• Event (p. 29)
• Execution environment (p. 30)
• Deployment package (p. 30)
• Runtime (p. 30)
• Layer (p. 30)
• Extension (p. 31)
• Concurrency (p. 31)
• Qualifier (p. 31)

Function
A function is a resource that you can invoke to run your code in Lambda. A function has code to process
the events (p. 29) that you pass into the function or that other AWS services send to the function.

For more information, see Managing AWS Lambda functions (p. 69).

Trigger
A trigger is a resource or configuration that invokes a Lambda function. This includes AWS services
that you can configure to invoke a function, applications that you develop, and event source
mappings (p. 148). An event source mapping is a resource in Lambda that reads items from a stream or
queue and invokes a function. For more information, see Invoking AWS Lambda functions (p. 137) and
Using AWS Lambda with other services (p. 257).

Event
An event is a JSON-formatted document that contains data for a Lambda function to process. The
runtime converts the event to an object and passes it to your function code. When you invoke a function,
you determine the structure and contents of the event.

Example custom event – weather data

{
"TemperatureK": 281,
"WindKmh": -3,
"HumidityPct": 0.55,
"PressureHPa": 1020
}

When an AWS service invokes your function, the service defines the shape of the event.

Example service event – Amazon SNS notification

29
 AWS Lambda Developer Guide
Execution environment

"Records": [
{
"Sns": {
"Timestamp": "2019-01-02T12:45:07.000Z",
"Signature": "tcc6faL2yUC6dgZdmrwh1Y4cGa/ebXEkAi6RibDsvpi+tE/1+82j...65r==",
"MessageId": "95df01b4-ee98-5cb9-9903-4c221d41eb5e",
"Message": "Hello from SNS!",
...

For more information about events from AWS services, see Using AWS Lambda with other
services (p. 257).

Execution environment
An execution environment provides a secure and isolated runtime environment for your Lambda function.
An execution environment manages the processes and resources that are required to run the function.
The execution environment provides lifecycle support for the function and for any extensions (p. 31)
associated with your function.

For more information, see AWS Lambda execution environment (p. 200).

Deployment package
You deploy your Lambda function code using a deployment package. Lambda supports two types of
deployment packages:

• A .zip file archive that contains your function code and its dependencies. Lambda provides the
operating system and runtime for your function.
• A container image that is compatible with the Open Container Initiative (OCI) specification. You add
your function code and dependencies to the image. You must also include the operating system and a
Lambda runtime.

For more information, see Lambda deployment packages (p. 41).

Runtime
The runtime provides a language-specific environment that runs in an execution environment. The
runtime relays invocation events, context information, and responses between Lambda and the function.
You can use runtimes that Lambda provides, or build your own. If you package your code as a .zip file
archive, you must configure your function to use a runtime that matches your programming language.
For a container image, you include the runtime when you build the image.

For more information, see Lambda runtimes (p. 195).

Layer
A Lambda layer is a .zip file archive that can contain additional code or other content. A layer can contain
libraries, a custom runtime (p. 236), data, or configuration files.

Layers provide a convenient way to package libraries and other dependencies that you can use with your
Lambda functions. Using layers reduces the size of uploaded deployment archives and makes it faster to
deploy your code. Layers also promote code sharing and separation of responsibilities so that you can
iterate faster on writing business logic.

You can include up to five layers per function. Layers count towards the standard Lambda deployment
size quotas (p. 44). When you include a layer in a function, the contents are extracted to the /opt
directory in the execution environment.

30
 AWS Lambda Developer Guide
Extension

By default, the layers that you create are private to your AWS account. You can choose to share a layer
with other accounts or to make the layer public. If your functions consume a layer that a different
account published, your functions can continue to use the layer version after it has been deleted, or after
your permission to access the layer is revoked. However, you cannot create a new function or update
functions using a deleted layer version.

Functions deployed as a container image do not use layers. Instead, you package your preferred runtime,
libraries, and other dependencies into the container image when you build the image.

For more information, see Creating and sharing Lambda layers (p. 101).

Extension
Lambda extensions enable you to augment your functions. For example, you can use extensions to
integrate your functions with your preferred monitoring, observability, security, and governance tools.
You can choose from a broad set of tools that AWS Lambda Partners provides, or you can create your
own Lambda extensions (p. 209).

An internal extension runs in the runtime process and shares the same lifecycle as the runtime. An
external extension runs as a separate process in the execution environment. The external extension is
initialized before the function is invoked, runs in parallel with the function's runtime, and continues to
run after the function invocation is complete.

For more information, see Using Lambda extensions (p. 160).

Concurrency
Concurrency is the number of requests that your function is serving at any given time. When your
function is invoked, Lambda provisions an instance of it to process the event. When the function code
finishes running, it can handle another request. If the function is invoked again while a request is still
being processed, another instance is provisioned, increasing the function's concurrency.

Concurrency is subject to quotas (p. 44) at the AWS Region level. You can configure individual
functions to limit their concurrency, or to enable them to reach a specific level of concurrency. For more
information, see Managing concurrency for a Lambda function (p. 84).

Qualifier
When you invoke or view a function, you can include a qualifier to specify a version or alias. A version
is an immutable snapshot of a function's code and configuration that has a numerical qualifier. For
example, my-function:1. An alias is a pointer to a version that you can update to map to a different
version, or split traffic between two versions. For example, my-function:BLUE. You can use versions
and aliases together to provide a stable interface for clients to invoke your function.

For more information, see Lambda function versions (p. 95).

31
 AWS Lambda Developer Guide
Features

Lambda features
Lambda provides a management console and API for managing and invoking functions. It provides
runtimes that support a standard set of features so that you can easily switch between languages and
frameworks, depending on your needs. In addition to functions, you can also create versions, aliases,
layers, and custom runtimes.

Features
• Programming model (p. 32)
• Scaling (p. 34)
• Concurrency controls (p. 35)
• Asynchronous invocation (p. 36)
• Event source mappings (p. 37)
• Destinations (p. 38)
• Function blueprints (p. 39)
• Testing and deployment tools (p. 40)
• Application templates (p. 40)

Programming model
Authoring specifics vary between runtimes, but all runtimes share a common programming model that
defines the interface between your code and the runtime code. You tell the runtime which method to
run by defining a handler in the function configuration, and the runtime runs that method. The runtime
passes in objects to the handler that contain the invocation event and the context, such as the function
name and request ID.

When the handler finishes processing the first event, the runtime sends it another. The function's class
stays in memory, so clients and variables that are declared outside of the handler method in initialization
code can be reused. To save processing time on subsequent events, create reusable resources like AWS
SDK clients during initialization. Once initialized, each instance of your function can process thousands of
requests.

When AWS X-Ray tracing (p. 451) is enabled, the runtime records separate subsegments for
initialization and execution.

32
 AWS Lambda Developer Guide
Programming model

Your function also has access to local storage in the /tmp directory. Instances of your function that are
serving requests remain active for a few hours before being recycled.

The runtime captures logging output from your function and sends it to Amazon CloudWatch Logs. In
addition to logging your function's output, the runtime also logs entries when function invocation starts
and ends. This includes a report log with the request ID, billed duration, initialization duration, and other
details. If your function throws an error, the runtime returns that error to the invoker.
Note
Logging is subject to CloudWatch Logs quotas. Log data can be lost due to throttling or, in some
cases, when an instance of your function is stopped.

For a hands-on introduction to the programming model in your preferred programming language, see
the following chapters.

• Building Lambda functions with Node.js (p. 484)

• Building Lambda functions with Python (p. 510)
• Building Lambda functions with Ruby (p. 547)
• Building Lambda functions with Java (p. 570)
• Building Lambda functions with Go (p. 610)
• Building Lambda functions with C# (p. 638)
• Building Lambda functions with PowerShell (p. 667)

Lambda scales your function by running additional instances of it as demand increases, and by stopping
instances as demand decreases. Unless noted otherwise, incoming requests might be processed out of
order or concurrently. Store your application's state in other services, and don't rely on instances of your
function being long lived. Use local storage and class-level objects to increase performance, but keep

33
 AWS Lambda Developer Guide
Scaling

to a minimum the size of your deployment package and the amount of data that you transfer onto the
execution environment.

Scaling
Lambda manages the infrastructure that runs your code, and scales automatically in response to
incoming requests. When your function is invoked more quickly than a single instance of your function
can process events, Lambda scales up by running additional instances. When traffic subsides, inactive
instances are frozen or stopped. You only pay for the time that your function is initializing or processing
events.

For more information, see AWS Lambda function scaling (p. 153).

34
 AWS Lambda Developer Guide
Concurrency controls

Concurrency controls
Use concurrency settings to ensure that your production applications are highly available and highly
responsive. To prevent a function from using too much concurrency, and to reserve a portion of your
account's available concurrency for a function, use reserved concurrency. Reserved concurrency splits the
pool of available concurrency into subsets. A function with reserved concurrency only uses concurrency
from its dedicated pool.

To enable functions to scale without fluctuations in latency, use provisioned concurrency. For functions
that take a long time to initialize, or that require extremely low latency for all invocations, provisioned
concurrency enables you to pre-initialize instances of your function and keep them running at all times.
Lambda integrates with Application Auto Scaling to support autoscaling for provisioned concurrency
based on utilization.

35
 AWS Lambda Developer Guide
Asynchronous invocation

For more information, see Managing concurrency for a Lambda function (p. 84).

Asynchronous invocation
When you invoke a function, you can choose to invoke it synchronously or asynchronously. With
synchronous invocation (p. 138), you wait for the function to process the event and return a response.
With asynchronous invocation, Lambda queues the event for processing and returns a response
immediately.

36
 AWS Lambda Developer Guide
Event source mappings

For asynchronous invocations, Lambda handles retries if the function returns an error or is throttled. To
customize this behavior, you can configure error handling settings on a function, version, or alias. You
can also configure Lambda to send events that failed processing to a dead-letter queue, or to send a
record of any invocation to a destination (p. 38).

For more information, see Asynchronous invocation (p. 140).

Event source mappings

To process items from a stream or queue, you can create an event source mapping. An event source
mapping is a resource in Lambda that reads items from an Amazon Simple Queue Service (Amazon
SQS) queue, an Amazon Kinesis stream, or an Amazon DynamoDB stream, and sends the items to your
function in batches. Each event that your function processes can contain hundreds or thousands of items.

37
 AWS Lambda Developer Guide
Destinations

Event source mappings maintain a local queue of unprocessed items and handle retries if the function
returns an error or is throttled. You can configure an event source mapping to customize batching
behavior and error handling, or to send a record of items that fail processing to a destination.

For more information, see AWS Lambda event source mappings (p. 148).

Destinations
A destination is an AWS resource that receives invocation records for a function. For asynchronous
invocation (p. 36), you can configure Lambda to send invocation records to a queue, topic, function,
or event bus. You can configure separate destinations for successful invocations and events that failed
processing. The invocation record contains details about the event, the function's response, and the
reason that the record was sent.

38
 AWS Lambda Developer Guide
Function blueprints

For event source mappings (p. 37) that read from streams, you can configure Lambda to send a record
of batches that failed processing to a queue or topic. A failure record for an event source mapping
contains metadata about the batch, and it points to the items in the stream.

For more information, see Configuring destinations for asynchronous invocation (p. 142) and the error
handling sections of Using AWS Lambda with Amazon DynamoDB (p. 313) and Using AWS Lambda
with Amazon Kinesis (p. 365).

Function blueprints
When you create a function in the Lambda console, you can choose to start from scratch, use a
blueprint, use a container image (p. 41), or deploy an application from the AWS Serverless Application
Repository. A blueprint provides sample code that shows how to use Lambda with an AWS service or a
popular third-party application. Blueprints include sample code and function configuration presets for
Node.js and Python runtimes.

Blueprints are provided for use under the Amazon Software License. They are available only in the
Lambda console.

39
 AWS Lambda Developer Guide
Testing and deployment tools

Testing and deployment tools

Lambda supports deploying code as is or as container images (p. 41). You can use a rich tools
ecosystem for authoring, building, and deploying your Lambda functions using AWS and popular
community tools like the Docker command line interface (CLI).

To set up the Docker CLI, see Get Docker on the Docker Docs website. For an introduction to using Docker
with AWS, see Getting started with Amazon ECR using the AWS CLI in the Amazon Elastic Container
Registry User Guide.

Application templates
You can use the Lambda console to create an application with a continuous delivery pipeline. Application
templates in the Lambda console include code for one or more functions, an application template that
defines functions and supporting AWS resources, and an infrastructure template that defines an AWS
CodePipeline pipeline. The pipeline has build and deploy stages that run every time you push changes to
the included Git repository.

Application templates are provided for use under the MIT No Attribution license. They are available only
in the Lambda console.

For more information, see Creating an application with continuous delivery in the Lambda
console (p. 178).

40
 AWS Lambda Developer Guide
Deployment packages

Lambda deployment packages

Your AWS Lambda function's code consists of scripts or compiled programs and their dependencies.
You use a deployment package to deploy your function code to Lambda. Lambda supports two types of
deployment packages: container images and .zip file archives.

Topics
• Container images (p. 41)
• .zip file archives (p. 41)
• Layers (p. 42)
• Using other AWS services to build a deployment package (p. 42)

Container images
A container image includes the base operating system, the runtime, Lambda extensions, your application
code and its dependencies. You can also add static data, such as machine learning models, into the
image.

Lambda provides a set of open-source base images that you can use to build your container image.
To create and test container images, you can use the AWS Serverless Application Model (AWS SAM)
command line interface (CLI) or native container tools such as the Docker CLI.

You upload your container images to Amazon Elastic Container Registry (Amazon ECR), a managed AWS
container image registry service. To deploy the image to your function, you specify the Amazon ECR
image URL using the Lambda console, the Lambda API, command line tools, or the AWS SDKs.

For more information about Lambda container images, see Using container images with
Lambda (p. 247).

.zip file archives

A .zip file archive includes your application code and its dependencies. When you author functions using
the Lambda console or a toolkit, Lambda automatically creates a .zip file archive of your code.

When you create functions with the Lambda API, command line tools, or the AWS SDKs, you must create
a deployment package. You also must create a deployment package if your function uses a compiled
language, or to add dependencies to your function. To deploy your function's code, you upload the
deployment package from Amazon Simple Storage Service (Amazon S3) or your local machine.

You can upload a .zip file as your deployment package using the Lambda console, AWS Command Line
Interface (AWS CLI), or to an Amazon Simple Storage Service (Amazon S3) bucket.

Using the Lambda console

The following steps demonstrate how to upload a .zip file as your deployment package using the
Lambda console.

To upload a .zip file on the Lambda console

1. Open the Functions page on the Lambda console.

2. Select a function.
3. In the Code Source pane, choose Upload from and then .zip file.
4. Choose Upload to select your local .zip file.

41
 AWS Lambda Developer Guide
Layers

5. Choose Save.

Using the AWS CLI

You can upload a .zip file as your deployment package using the AWS Command Line Interface (AWS
CLI). For language-specific instructions, see the following topics.

• Deploy Node.js Lambda functions with .zip file archives (p. 489)
• Deploy Python Lambda functions with .zip file archives (p. 515)
• Deploy Ruby Lambda functions with .zip file archives (p. 551)
• Deploy Java Lambda functions with .zip or JAR file archives (p. 578)
• Deploy Go Lambda functions with .zip file archives (p. 617)
• Deploy C# Lambda functions with .zip file archives (p. 645)
• Deploy PowerShell Lambda functions with .zip file archives (p. 669)

Using Amazon S3
You can upload a .zip file as your deployment package using Amazon Simple Storage Service (Amazon
S3). For more information, see the section called “Using other AWS services”.

Layers
If you deploy your function code using a .zip file archive, you can use Lambda layers as a distribution
mechanism for libraries, custom runtimes, and other function dependencies. Layers enable you to
manage your in-development function code independently from the unchanging code and resources that
it uses. You can configure your function to use layers that you create, layers that AWS provides, or layers
from other AWS customers.

You do not use layers with container images. Instead, you package your preferred runtime, libraries, and
other dependencies into the container image when you build the image.

For more information about layers, see Creating and sharing Lambda layers (p. 101).

Using other AWS services to build a deployment

package
The following section describes other AWS services you can use to package dependencies for your
Lambda function.

Deployment packages with C or C++ libraries

If your deployment package contains native libraries, you can build the deployment package with AWS
Serverless Application Model (AWS SAM). You can use the AWS SAM CLI sam build command with the
--use-container to create your deployment package. This option builds a deployment package inside
a Docker image that is compatible with the Lambda execution environment.

For more information, see sam build in the AWS Serverless Application Model Developer Guide.

Deployment packages over 50 MB

If your deployment package is larger than 50 MB, we recommend uploading your function code and
dependencies to an Amazon S3 bucket.

42
 AWS Lambda Developer Guide
Using other AWS services

You can create a deployment package and upload the .zip file to your Amazon S3 bucket in the AWS
Region where you want to create a Lambda function. When you create your Lambda function, specify the
S3 bucket name and object key name on the Lambda console, or using the AWS CLI.

To create a bucket using the Amazon S3 console, see How do I create an S3 Bucket? in the Amazon
Simple Storage Service Console User Guide.

43
 AWS Lambda Developer Guide
Quotas

Lambda quotas
Lambda sets quotas for the amount of compute and storage resources that you can use to run and store
functions. The following quotas apply per AWS Region and can be increased. For more information, see
Requesting a quota increase in the Service Quotas User Guide.

Resource Default quota Can be

increased up
to

Concurrent executions 1,000 Tens of

thousands

Storage for uploaded functions (.zip file archives) 75 GB Terabytes

and layers. Each function version and layer version
consumes storage.

Storage for functions defined as container images. See Amazon ECR service quotas.
These images are stored in Amazon ECR.

Elastic network interfaces per virtual private cloud 250 Hundreds

(VPC) (p. 111)
Note
This quota is shared with other services,
such as Amazon Elastic File System
(Amazon EFS). See Amazon VPC quotas.

For details on concurrency and how Lambda scales your function concurrency in response to traffic, see
AWS Lambda function scaling (p. 153).

The following quotas apply to function configuration, deployments, and execution. They cannot be
changed.

Resource Quota

Function memory allocation (p. 70) 128 MB to 10,240 MB, in 1-MB

increments.

Function timeout (p. 70) 900 seconds (15 minutes)

Function environment variables (p. 77) 4 KB

Function resource-based policy (p. 51) 20 KB

Function layers (p. 101) five layers

Function burst concurrency (p. 153) 500 - 3000 (varies per Region)

Invocation payload (p. 137) (request and response) 6 MB (synchronous)

256 KB (asynchronous)

Deployment package (.zip file archive) (p. 41) size 50 MB (zipped, for direct upload)

250 MB (unzipped, including layers)

3 MB (console editor)

44
 AWS Lambda Developer Guide
Quotas

Resource Quota

Container image (p. 247) code package size 10 GB

Test events (console editor) 10

/tmp directory storage 512 MB

File descriptors 1,024

Execution processes/threads 1,024

The following quotas are associated with Lambda API requests.

Resource Quota

Invocation requests per Region (requests per second) 10 x concurrent executions quota
(synchronous (p. 138), all sources)

10 x concurrent executions quota

(asynchronous (p. 140), non-AWS
sources)

Invocation requests per Region (requests per second) for Unlimited requests accepted. Execution
asynchronous AWS service sources (p. 257) rate is based on concurrency available
to the function. See Asynchronous
invocation (p. 140).

Invocation requests per function version or alias (requests 10 x allocated provisioned

per second) concurrency (p. 84)
Note
This quota applies only to
functions that use provisioned
concurrency.

GetFunction (p. 808) API requests 100 requests per second

GetPolicy (p. 835) API requests 15 requests per second

Remainder of the control plane API requests (excludes 15 requests per second
invocation, GetFunction, and GetPolicy requests)

Quotas for other services, such as AWS Identity and Access Management (IAM), Amazon CloudFront
(Lambda@Edge), and Amazon Virtual Private Cloud (Amazon VPC), can impact your Lambda functions.
For more information, see AWS service quotas in the Amazon Web Services General Reference, and Using
AWS Lambda with other services (p. 257).

45
 AWS Lambda Developer Guide

AWS Lambda permissions

You can use AWS Identity and Access Management (IAM) to manage access to the Lambda API and
resources like functions and layers. For users and applications in your account that use Lambda, you
manage permissions in a permissions policy that you can apply to IAM users, groups, or roles. To grant
permissions to other accounts or AWS services that use your Lambda resources, you use a policy that
applies to the resource itself.

A Lambda function also has a policy, called an execution role (p. 47), that grants it permission to
access AWS services and resources. At a minimum, your function needs access to Amazon CloudWatch
Logs for log streaming. If you use AWS X-Ray to trace your function (p. 451), or your function accesses
services with the AWS SDK, you grant it permission to call them in the execution role. Lambda also
uses the execution role to get permission to read from event sources when you use an event source
mapping (p. 148) to trigger your function.
Note
If your function needs network access to a resource like a relational database that isn't
accessible through AWS APIs or the internet, configure it to connect to your VPC (p. 111).

Use resource-based policies (p. 51) to give other accounts and AWS services permission to use your
Lambda resources. Lambda resources include functions, versions, aliases, and layer versions. Each of
these resources has a permissions policy that applies when the resource is accessed, in addition to any
policies that apply to the user. When an AWS service like Amazon S3 calls your Lambda function, the
resource-based policy gives it access.

To manage permissions for users and applications in your accounts, use the managed policies that
Lambda provides (p. 56), or write your own. The Lambda console uses multiple services to get
information about your function's configuration and triggers. You can use the managed policies as-is, or
as a starting point for more restrictive policies.

You can restrict user permissions by the resource an action affects and, in some cases, by additional
conditions. For example, you can specify a pattern for the Amazon Resource Name (ARN) of a function
that requires a user to include their user name in the name of functions that they create. Additionally,
you can add a condition that requires that the user configure functions to use a specific layer to, for
example, pull in logging software. For the resources and conditions that are supported by each action,
see Resources and Conditions (p. 61).

For more information about IAM, see What is IAM? in the IAM User Guide.

For more information about applying security principles to Lambda applications, see Security in the
Lambda operator guide.

Topics
• AWS Lambda execution role (p. 47)
• Using resource-based policies for AWS Lambda (p. 51)
• Identity-based IAM policies for Lambda (p. 56)
• Resources and conditions for Lambda actions (p. 61)
• Using permissions boundaries for AWS Lambda applications (p. 67)

46
 AWS Lambda Developer Guide
Execution role

AWS Lambda execution role

A Lambda function's execution role is an AWS Identity and Access Management (IAM) role that grants
the function permission to access AWS services and resources. You provide this role when you create a
function, and Lambda assumes the role when your function is invoked. You can create an execution role
for development that has permission to send logs to Amazon CloudWatch and to upload trace data to
AWS X-Ray.

To view a function's execution role

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose Permissions.
4. Under Resource summary, view the services and resources that the function can access. The
following example shows the CloudWatch Logs permissions that Lambda adds to an execution role
when you create it in the Lambda console.

5. Choose a service from the dropdown list to see permissions related to that service.

47
 AWS Lambda Developer Guide
Creating an execution role in the IAM console

You can add or remove permissions from a function's execution role at any time, or configure your
function to use a different role. Add permissions for any services that your function calls with the AWS
SDK, and for services that Lambda uses to enable optional features.

When you add permissions to your function, make an update to its code or configuration as well. This
forces running instances of your function, which have out-of-date credentials, to stop and be replaced.

Topics
• Creating an execution role in the IAM console (p. 48)
• Grant least privilege access to your Lambda execution role (p. 48)
• Managing roles with the IAM API (p. 49)
• AWS managed policies for Lambda features (p. 50)

Creating an execution role in the IAM console

By default, Lambda creates an execution role with minimal permissions when you create a function in the
Lambda console (p. 9). You can also create an execution role in the IAM console.

To create an execution role in the IAM console

1. Open the Roles page in the IAM console.

2. Choose Create role.
3. Under Common use cases, choose Lambda.
4. Choose Next: Permissions.
5. Under Attach permissions policies, choose the AWS managed policies
AWSLambdaBasicExecutionRole and AWSXRayDaemonWriteAccess.
6. Choose Next: Tags.
7. Choose Next: Review.
8. For Role name, enter lambda-role.
9. Choose Create role.

For detailed instructions, see Creating a role for an AWS service (console) in the IAM User Guide.

Grant least privilege access to your Lambda execution

role
When you first create an IAM role for your Lambda function during the development phase, you might
sometimes grant permissions beyond what is required. Before publishing your function in the production
environment, best practice is to adjust the policy to include only the required permissions. For more
information, see granting least privilege.

Use IAM Access Analyzer to help identify the required permissions for the IAM execution role policy. IAM
Access Analyzer reviews your AWS CloudTrail logs over the date range that you specify and generates
a policy template with only the permissions that the function used during that time. You can use the
template to create a managed policy with fine-grained permissions, and then attach it to the IAM role.
That way, you grant only the permissions that the role needs to interact with AWS resources for your
specific use case.

To learn more, see Generate policies based on access activity in the IAM User Guide.

48
 AWS Lambda Developer Guide
Managing roles with the IAM API

Managing roles with the IAM API

To create an execution role with the AWS Command Line Interface (AWS CLI), use the create-role
command.

aws iam create-role --role-name lambda-ex --assume-role-policy-document file://trust-

policy.json

You should see the following output:

{
"Role": {
"Path": "/",
"RoleName": "lambda-ex",
"RoleId": "AROAQFOXMPL6TZ6ITKWND",
"Arn": "arn:aws:iam::123456789012:role/lambda-ex",
"CreateDate": "2020-01-17T23:19:12Z",
"AssumeRolePolicyDocument": {
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}
}
}

The trust-policy.json file is a JSON file in the current directory that defines the trust policy for
the role. This trust policy allows Lambda to use the role's permissions by giving the service principal
lambda.amazonaws.com permission to call the AWS Security Token Service AssumeRole action.

Example trust-policy.json

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": "sts:AssumeRole"
}
]
}

You can also specify the trust policy inline. Requirements for escaping quotes in the JSON string vary
depending on your shell.

aws iam create-role --role-name lambda-ex --assume-role-policy-document '{"Version":

"2012-10-17","Statement": [{ "Effect": "Allow", "Principal": {"Service":
"lambda.amazonaws.com"}, "Action": "sts:AssumeRole"}]}'

To add permissions to the role, use the attach-policy-to-role command. Start by adding the
AWSLambdaBasicExecutionRole managed policy.

49
 AWS Lambda Developer Guide
AWS managed policies for Lambda features

aws iam attach-role-policy --role-name lambda-ex --policy-arn arn:aws:iam::aws:policy/

service-role/AWSLambdaBasicExecutionRole

AWS managed policies for Lambda features

The following AWS managed policies provide permissions that are required to use Lambda features:

• AWSLambdaBasicExecutionRole – Permission to upload logs to CloudWatch.

• AWSLambdaDynamoDBExecutionRole – Permission to read records from an Amazon DynamoDB
stream.
• AWSLambdaKinesisExecutionRole – Permission to read events from an Amazon Kinesis data stream
or consumer.
• AWSLambdaMQExecutionRole – Permission to read records from an Amazon MQ broker.
• AWSLambdaMSKExecutionRole – Permission to read records from an Amazon Managed Streaming for
Apache Kafka (Amazon MSK) cluster.
• AWSLambdaSQSQueueExecutionRole – Permission to read a message from an Amazon Simple Queue
Service (Amazon SQS) queue.
• AWSLambdaVPCAccessExecutionRole – Permission to manage elastic network interfaces to connect
your function to a virtual private cloud (VPC).
• AWSXRayDaemonWriteAccess – Permission to upload trace data to X-Ray.
• CloudWatchLambdaInsightsExecutionRolePolicy – Permission to write runtime metrics to
CloudWatch Lambda Insights.

For some features, the Lambda console attempts to add missing permissions to your execution role in a
customer managed policy. These policies can become numerous. To avoid creating extra policies, add the
relevant AWS managed policies to your execution role before enabling features.

When you use an event source mapping (p. 148) to invoke your function, Lambda uses the execution
role to read event data. For example, an event source mapping for Kinesis reads events from a data
stream and sends them to your function in batches. You can use event source mappings with the
following services:

Services that Lambda reads events from

• Amazon DynamoDB (p. 313)

• Amazon Kinesis (p. 365)
• Amazon MQ (p. 389)
• Amazon Managed Streaming for Apache Kafka (p. 396)
• self-managed Apache Kafka (p. 356)
• Amazon Simple Queue Service (p. 439)

In addition to the AWS managed policies, the Lambda console provides templates for creating a custom
policy with permissions for additional use cases. When you create a function in the Lambda console,
you can choose to create a new execution role with permissions from one or more templates. These
templates are also applied automatically when you create a function from a blueprint, or when you
configure options that require access to other services. Example templates are available in this guide's
GitHub repository.

50
 AWS Lambda Developer Guide
Resource-based policies

Using resource-based policies for AWS Lambda

AWS Lambda supports resource-based permissions policies for Lambda functions and layers. Resource-
based policies let you grant usage permission to other AWS accounts on a per-resource basis. You also
use a resource-based policy to allow an AWS service to invoke your function on your behalf.

For Lambda functions, you can grant an account permission (p. 53) to invoke or manage a function.
You can add multiple statements to grant access to several accounts, or let any account invoke your
function. You can also use the policy to grant invoke permission to an AWS service (p. 52) that invokes
a function in response to activity in your account.

To view a function's resource-based policy

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose Permissions.
4. Scroll down to Resource-based policy and then choose View policy document. The resource-based
policy shows the permissions that are applied when another account or AWS service attempts to
access the function. The following example shows a statement that allows Amazon S3 to invoke a
function named my-function for a bucket named my-bucket in account 123456789012.

Example Resource-based policy

{
"Version": "2012-10-17",
"Id": "default",
"Statement": [
{
"Sid": "lambda-allow-s3-my-function",
"Effect": "Allow",
"Principal": {
"Service": "s3.amazonaws.com"
},
"Action": "lambda:InvokeFunction",
"Resource": "arn:aws:lambda:us-east-2:123456789012:function:my-function”,
"Condition": {
"StringEquals": {
"AWS:SourceAccount": "123456789012"
},
"ArnLike": {
"AWS:SourceArn": "arn:aws:s3:::my-bucket"
}
}
}
]
}

For Lambda layers, you can only use a resource-based policy on a specific layer version, instead of the
entire layer. In addition to policies that grant permission to a single account or multiple accounts, for
layers, you can also grant permission to all accounts in an organization.
Note
You can only update resource-based policies for Lambda resources within the scope of the
AddPermission (p. 743) and AddLayerVersionPermission (p. 739) API actions. Currently, you
can't author policies for your Lambda resources in JSON, or use conditions that don't map to
parameters for those actions.

51
 AWS Lambda Developer Guide
Granting function access to AWS services

Resource-based policies apply to a single function, version, alias, or layer version. They grant permission
to one or more services and accounts. For trusted accounts that you want to have access to multiple
resources, or to use API actions that resource-based policies don't support, you can use cross-account
roles (p. 56).

Topics
• Granting function access to AWS services (p. 52)
• Granting function access to other accounts (p. 53)
• Granting layer access to other accounts (p. 54)
• Cleaning up resource-based policies (p. 55)

Granting function access to AWS services

When you use an AWS service to invoke your function (p. 257), you grant permission in a statement on
a resource-based policy. You can apply the statement to the entire function to be invoked or managed, or
limit the statement to a single version or alias.
Note
When you add a trigger to your function with the Lambda console, the console updates the
function's resource-based policy to allow the service to invoke it. To grant permissions to other
accounts or services that aren't available in the Lambda console, you can use the AWS CLI.

Add a statement with the add-permission command. The simplest resource-based policy statement
allows a service to invoke a function. The following command grants Amazon SNS permission to invoke a
function named my-function.

aws lambda add-permission --function-name my-function --action lambda:InvokeFunction --

statement-id sns \
--principal sns.amazonaws.com --output text

You should see the following output:

{"Sid":"sns","Effect":"Allow","Principal":
{"Service":"sns.amazonaws.com"},"Action":"lambda:InvokeFunction","Resource":"arn:aws:lambda:us-
east-2:123456789012:function:my-function"}

This lets Amazon SNS call the lambda:Invoke API for the function, but it doesn't restrict the Amazon
SNS topic that triggers the invocation. To ensure that your function is only invoked by a specific resource,
specify the Amazon Resource Name (ARN) of the resource with the source-arn option. The following
command only allows Amazon SNS to invoke the function for subscriptions to a topic named my-topic.

aws lambda add-permission --function-name my-function --action lambda:InvokeFunction --

statement-id sns-my-topic \
--principal sns.amazonaws.com --source-arn arn:aws:sns:us-east-2:123456789012:my-topic

Some services can invoke functions in other accounts. If you specify a source ARN that has your account
ID in it, that isn't an issue. For Amazon S3, however, the source is a bucket whose ARN doesn't have
an account ID in it. It's possible that you could delete the bucket and another account could create a
bucket with the same name. Use the source-account option with your account ID to ensure that only
resources in your account can invoke the function.

aws lambda add-permission --function-name my-function --action lambda:InvokeFunction --

statement-id s3-account \
--principal s3.amazonaws.com --source-arn arn:aws:s3:::my-bucket-123456 --source-
account 123456789012

52
 AWS Lambda Developer Guide
Granting function access to other accounts

Granting function access to other accounts

To grant permissions to another AWS account, specify the account ID as the principal. The following
example grants account 210987654321 permission to invoke my-function with the prod alias.

aws lambda add-permission --function-name my-function:prod --statement-id xaccount --action

lambda:InvokeFunction \
--principal 210987654321 --output text

You should see the following output:

{"Sid":"xaccount","Effect":"Allow","Principal":
{"AWS":"arn:aws:iam::210987654321:root"},"Action":"lambda:InvokeFunction","Resource":"arn:aws:lambda:us
east-2:123456789012:function:my-function"}

The resource-based policy grants permission for the other account to access the function, but doesn't
allow users in that account to exceed their permissions. Users in the other account must have the
corresponding user permissions (p. 56) to use the Lambda API.

To limit access to a user or role in another account, specify the full ARN of the identity as the principal.
For example, arn:aws:iam::123456789012:user/developer.

The alias (p. 97) limits which version the other account can invoke. It requires the other account to
include the alias in the function ARN.

aws lambda invoke --function-name arn:aws:lambda:us-west-2:123456789012:function:my-

function:prod out

You should see the following output:

{
"StatusCode": 200,
"ExecutedVersion": "1"
}

The function owner can then update the alias to point to a new version without the caller needing to
change the way they invoke your function. This ensures that the other account doesn't need to change its
code to use the new version, and it only has permission to invoke the version of the function associated
with the alias.

You can grant cross-account access for most API actions that operate on an existing function (p. 64).
For example, you could grant access to lambda:ListAliases to let an account get a list of aliases, or
lambda:GetFunction to let them download your function code. Add each permission separately, or
use lambda:* to grant access to all actions for the specified function.

Cross-account APIs

Currently, Lambda doesn’t currently support cross-account actions for all of its APIs via resource-based
policies. The following APIs are supported:

• Invoke (p. 840)

• GetFunction (p. 808)
• GetFunctionConfiguration (p. 817)
• UpdateFunctionCode (p. 927)
• DeleteFunction (p. 784)

53
 AWS Lambda Developer Guide
Granting layer access to other accounts

• PublishVersion (p. 883)

• ListVersionsByFunction (p. 875)
• CreateAlias (p. 747)
• GetAlias (p. 798)
• ListAliases (p. 848)
• UpdateAlias (p. 912)
• DeleteAlias (p. 775)
• GetPolicy (p. 835)
• PutFunctionConcurrency (p. 894)
• DeleteFunctionConcurrency (p. 788)
• ListTags (p. 873)
• TagResource (p. 908)
• UntagResource (p. 910)

To grant other accounts permission for multiple functions, or for actions that don't operate on a
function, we recommend that you use IAM roles (p. 56).

Granting layer access to other accounts

To grant layer-usage permission to another account, add a statement to the layer version's permissions
policy using the add-layer-version-permission command. In each statement, you can grant permission
to a single account, all accounts, or an organization.

aws lambda add-layer-version-permission --layer-name xray-sdk-nodejs --statement-id

xaccount \
--action lambda:GetLayerVersion --principal 210987654321 --version-number 1 --output text

You should see output similar to the following:

e210ffdc-e901-43b0-824b-5fcd0dd26d16 {"Sid":"xaccount","Effect":"Allow","Principal":
{"AWS":"arn:aws:iam::210987654321:root"},"Action":"lambda:GetLayerVersion","Resource":"arn:aws:lambda:u
east-2:123456789012:layer:xray-sdk-nodejs:1"}

Permissions apply only to a single layer version. Repeat the process each time that you create a new layer
version.

To grant permission to all accounts in an organization, use the organization-id option. The following
example grants all accounts in an organization permission to use version 3 of a layer.

aws lambda add-layer-version-permission --layer-name my-layer \

--statement-id engineering-org --version-number 3 --principal '*' \
--action lambda:GetLayerVersion --organization-id o-t194hfs8cz --output text

You should see the following output:

b0cd9796-d4eb-4564-939f-de7fe0b42236 {"Sid":"engineering-
org","Effect":"Allow","Principal":"*","Action":"lambda:GetLayerVersion","Resource":"arn:aws:lambda:us-
east-2:123456789012:layer:my-layer:3","Condition":{"StringEquals":{"aws:PrincipalOrgID":"o-
t194hfs8cz"}}}"

To grant permission to all AWS accounts, use * for the principal, and omit the organization ID. For
multiple accounts or organizations, you need to add multiple statements.

54
 AWS Lambda Developer Guide
Cleaning up resource-based policies

Cleaning up resource-based policies

To view a function's resource-based policy, use the get-policy command.

aws lambda get-policy --function-name my-function --output text

You should see the following output:

{"Version":"2012-10-17","Id":"default","Statement":
[{"Sid":"sns","Effect":"Allow","Principal":
{"Service":"s3.amazonaws.com"},"Action":"lambda:InvokeFunction","Resource":"arn:aws:lambda:us-
east-2:123456789012:function:my-function","Condition":{"ArnLike":
{"AWS:SourceArn":"arn:aws:sns:us-east-2:123456789012:lambda*"}}}]} 7c681fc9-b791-4e91-
acdf-eb847fdaa0f0

For versions and aliases, append the version number or alias to the function name.

aws lambda get-policy --function-name my-function:PROD

To remove permissions from your function, use remove-permission.

aws lambda remove-permission --function-name example --statement-id sns

Use the get-layer-version-policy command to view the permissions on a layer.

aws lambda get-layer-version-policy --layer-name my-layer --version-number 3 --output text

You should see the following output:

b0cd9796-d4eb-4564-939f-de7fe0b42236 {"Sid":"engineering-
org","Effect":"Allow","Principal":"*","Action":"lambda:GetLayerVersion","Resource":"arn:aws:lambda:us-
west-2:123456789012:layer:my-layer:3","Condition":{"StringEquals":{"aws:PrincipalOrgID":"o-
t194hfs8cz"}}}"

Use remove-layer-version-permission to remove statements from the policy.

aws lambda remove-layer-version-permission --layer-name my-layer --version-number 3 --

statement-id engineering-org

55
 AWS Lambda Developer Guide
User policies

Identity-based IAM policies for Lambda

You can use identity-based policies in AWS Identity and Access Management (IAM) to grant users in your
account access to Lambda. Identity-based policies can apply to users directly, or to groups and roles that
are associated with a user. You can also grant users in another account permission to assume a role in
your account and access your Lambda resources.

Lambda provides AWS managed policies that grant access to Lambda API actions and, in some cases,
access to other AWS services used to develop and manage Lambda resources. Lambda updates these
managed policies as needed to ensure that your users have access to new features when they're released.
Note
The AWS managed policies AWSLambdaFullAccess and AWSLambdaReadOnlyAccess will be
deprecated on March 1, 2021. After this date, you cannot attach these policies to new IAM users.
For more information, see the related troubleshooting topic (p. 709).

• AWSLambda_FullAccess – Grants full access to Lambda actions and other AWS services used to
develop and maintain Lambda resources. This policy was created by scoping down the previous policy
AWSLambdaFullAccess.
• AWSLambda_ReadOnlyAccess – Grants read-only access to Lambda resources. This policy was created
by scoping down the previous policy AWSLambdaReadOnlyAccess.
• AWSLambdaRole – Grants permissions to invoke Lambda functions.

AWS managed policies grant permission to API actions without restricting the Lambda functions or layers
that a user can modify. For finer-grained control, you can create your own policies that limit the scope of
a user's permissions.

Sections
• Function development (p. 56)
• Layer development and use (p. 59)
• Cross-account roles (p. 60)
• Condition keys for VPC settings (p. 60)

Function development
The following shows an example of a permissions policy with limited scope. It allows a user to create and
manage Lambda functions named with a designated prefix (intern-), and configured with a designated
execution role.

Example Function development policy

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ReadOnlyPermissions",
"Effect": "Allow",
"Action": [
"lambda:GetAccountSettings",
"lambda:ListFunctions",
"lambda:ListTags",
"lambda:GetEventSourceMapping",
"lambda:ListEventSourceMappings",
"iam:ListRoles"
],

56
 AWS Lambda Developer Guide
Function development

"Resource": "*"
},
{
"Sid": "DevelopFunctions",
"Effect": "Allow",
"NotAction": [
"lambda:AddPermission",
"lambda:PutFunctionConcurrency"
],
"Resource": "arn:aws:lambda:*:*:function:intern-*"
},
{
"Sid": "DevelopEventSourceMappings",
"Effect": "Allow",
"Action": [
"lambda:DeleteEventSourceMapping",
"lambda:UpdateEventSourceMapping",
"lambda:CreateEventSourceMapping"
],
"Resource": "*",
"Condition": {
"StringLike": {
"lambda:FunctionArn": "arn:aws:lambda:*:*:function:intern-*"
}
}
},
{
"Sid": "PassExecutionRole",
"Effect": "Allow",
"Action": [
"iam:ListRolePolicies",
"iam:ListAttachedRolePolicies",
"iam:GetRole",
"iam:GetRolePolicy",
"iam:PassRole",
"iam:SimulatePrincipalPolicy"
],
"Resource": "arn:aws:iam::*:role/intern-lambda-execution-role"
},
{
"Sid": "ViewLogs",
"Effect": "Allow",
"Action": [
"logs:*"
],
"Resource": "arn:aws:logs:*:*:log-group:/aws/lambda/intern-*"
}
]
}

The permissions in the policy are organized into statements based on the resources and
conditions (p. 61) that they support.

• ReadOnlyPermissions – The Lambda console uses these permissions when you browse and view
functions. They don't support resource patterns or conditions.

"Action": [
"lambda:GetAccountSettings",
"lambda:ListFunctions",
"lambda:ListTags",
"lambda:GetEventSourceMapping",
"lambda:ListEventSourceMappings",
"iam:ListRoles"

57
 AWS Lambda Developer Guide
Function development

],
"Resource": "*"

• DevelopFunctions – Use any Lambda action that operates on functions prefixed with intern-,
except AddPermission and PutFunctionConcurrency. AddPermission modifies the resource-
based policy (p. 51) on the function and can have security implications. PutFunctionConcurrency
reserves scaling capacity for a function and can take capacity away from other functions.

"NotAction": [
"lambda:AddPermission",
"lambda:PutFunctionConcurrency"
],
"Resource": "arn:aws:lambda:*:*:function:intern-*"

• DevelopEventSourceMappings – Manage event source mappings on functions that are prefixed

with intern-. These actions operate on event source mappings, but you can restrict them by function
with a condition.

"Action": [
"lambda:DeleteEventSourceMapping",
"lambda:UpdateEventSourceMapping",
"lambda:CreateEventSourceMapping"
],
"Resource": "*",
"Condition": {
"StringLike": {
"lambda:FunctionArn": "arn:aws:lambda:*:*:function:intern-*"
}
}

• PassExecutionRole – View and pass only a role named intern-lambda-execution-role, which

must be created and managed by a user with IAM permissions. PassRole is used when you assign an
execution role to a function.

"Action": [
"iam:ListRolePolicies",
"iam:ListAttachedRolePolicies",
"iam:GetRole",
"iam:GetRolePolicy",
"iam:PassRole",
"iam:SimulatePrincipalPolicy"
],
"Resource": "arn:aws:iam::*:role/intern-lambda-execution-role"

• ViewLogs – Use CloudWatch Logs to view logs for functions that are prefixed with intern-.

"Action": [
"logs:*"
],
"Resource": "arn:aws:logs:*:*:log-group:/aws/lambda/intern-*"

This policy allows a user to get started with Lambda, without putting other users' resources at risk. It
doesn't allow a user to configure a function to be triggered by or call other AWS services, which requires
broader IAM permissions. It also doesn't include permission to services that don't support limited-scope
policies, like CloudWatch and X-Ray. Use the read-only policies for these services to give the user access
to metrics and trace data.

58
 AWS Lambda Developer Guide
Layer development and use

When you configure triggers for your function, you need access to use the AWS service that invokes
your function. For example, to configure an Amazon S3 trigger, you need permission to use the
Amazon S3 actions that manage bucket notifications. Many of these permissions are included in the
AWSLambdaFullAccess managed policy. Example policies are available in this guide's GitHub repository.

Layer development and use

The following policy grants a user permission to create layers and use them with functions. The resource
patterns allow the user to work in any AWS Region and with any layer version, as long as the name of the
layer starts with test-.

Example layer development policy

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "PublishLayers",
"Effect": "Allow",
"Action": [
"lambda:PublishLayerVersion"
],
"Resource": "arn:aws:lambda:*:*:layer:test-*"
},
{
"Sid": "ManageLayerVersions",
"Effect": "Allow",
"Action": [
"lambda:GetLayerVersion",
"lambda:DeleteLayerVersion"
],
"Resource": "arn:aws:lambda:*:*:layer:test-*:*"
}
]
}

You can also enforce layer use during function creation and configuration with the lambda:Layer
condition. For example, you can prevent users from using layers published by other accounts. The
following policy adds a condition to the CreateFunction and UpdateFunctionConfiguration
actions to require that any layers specified come from account 123456789012.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ConfigureFunctions",
"Effect": "Allow",
"Action": [
"lambda:CreateFunction",
"lambda:UpdateFunctionConfiguration"
],
"Resource": "*",
"Condition": {
"ForAllValues:StringLike": {
"lambda:Layer": [
"arn:aws:lambda:*:123456789012:layer:*:*"
]
}
}
}
]

59
 AWS Lambda Developer Guide
Cross-account roles

To ensure that the condition applies, verify that no other statements grant the user permission to these
actions.

Cross-account roles
You can apply any of the preceding policies and statements to a role, which you can then share with
another account to give it access to your Lambda resources. Unlike an IAM user, a role doesn't have
credentials for authentication. Instead, it has a trust policy that specifies who can assume the role and
use its permissions.

You can use cross-account roles to give accounts that you trust access to Lambda actions and
resources. If you just want to grant permission to invoke a function or use a layer, use resource-based
policies (p. 51) instead.

For more information, see IAM roles in the IAM User Guide.

Condition keys for VPC settings

You can use condition keys for VPC settings to provide additional permission controls for your Lambda
functions. For example, you can enforce that all Lambda functions in your organization are connected to
a VPC. You can also specify the subnets and security groups that the functions are allowed to use, or are
denied from using.

For more information, see the section called “Using IAM condition keys for VPC settings” (p. 113).

60
 AWS Lambda Developer Guide
Resources and conditions

Resources and conditions for Lambda actions

You can restrict the scope of a user's permissions by specifying resources and conditions in an IAM policy.
Each API action supports a combination of resource and condition types that varies depending on the
behavior of the action.

Every IAM policy statement grants permission to an action that's performed on a resource. When the
action doesn't act on a named resource, or when you grant permission to perform the action on all
resources, the value of the resource in the policy is a wildcard (*). For many API actions, you can restrict
the resources that a user can modify by specifying the Amazon Resource Name (ARN) of a resource, or an
ARN pattern that matches multiple resources.

To restrict permissions by resource, specify the resource by ARN.

Lambda resource ARN format

• Function – arn:aws:lambda:us-west-2:123456789012:function:my-function
• Function version – arn:aws:lambda:us-west-2:123456789012:function:my-function:1
• Function alias – arn:aws:lambda:us-west-2:123456789012:function:my-function:TEST
• Event source mapping – arn:aws:lambda:us-west-2:123456789012:event-source-
mapping:fa123456-14a1-4fd2-9fec-83de64ad683de6d47
• Layer – arn:aws:lambda:us-west-2:123456789012:layer:my-layer
• Layer version – arn:aws:lambda:us-west-2:123456789012:layer:my-layer:1

For example, the following policy allows a user in account 123456789012 to invoke a function named
my-function in the US West (Oregon) Region.

Example invoke function policy

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Invoke",
"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": "arn:aws:lambda:us-west-2:123456789012:function:my-function"
}
]
}

This is a special case where the action identifier (lambda:InvokeFunction) differs from the API
operation (Invoke (p. 840)). For other actions, the action identifier is the operation name prefixed by
lambda:.

Conditions are an optional policy element that applies additional logic to determine if an action is
allowed. In addition to common conditions supported by all actions, Lambda defines condition types
that you can use to restrict the values of additional parameters on some actions.

For example, the lambda:Principal condition lets you restrict the service or account that a user can
grant invocation access to on a function's resource-based policy. The following policy lets a user grant
permission to SNS topics to invoke a function named test.

61
 AWS Lambda Developer Guide
Function resource names

Example manage function policy permissions

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "ManageFunctionPolicy",
"Effect": "Allow",
"Action": [
"lambda:AddPermission",
"lambda:RemovePermission"
],
"Resource": "arn:aws:lambda:us-west-2:123456789012:function:test:*",
"Condition": {
"StringEquals": {
"lambda:Principal": "sns.amazonaws.com"
}
}
}
]
}

The condition requires that the principal is Amazon SNS and not another service or account. The resource
pattern requires that the function name is test and includes a version number or alias. For example,
test:v1.

For more information on resources and conditions for Lambda and other AWS services, see Actions,
resources, and condition keys in the IAM User Guide.

Sections
• Function resource names (p. 62)
• Function actions (p. 64)
• Event source mapping actions (p. 66)
• Layer actions (p. 66)

Function resource names

You reference a Lambda function in a policy statement using an Amazon Resource Names (ARN). The
format of a function ARN depends on whether you are referencing the whole function, a function
version (p. 95), or an alias (p. 97).

When making Lambda API calls, users can specify a version or alias by passing a version ARN or alias ARN
in the FunctionName parameter, or by setting a value in the Qualifier parameter. Lambda makes
authorization decisions by comparing the resource element in the IAM policy with the FunctionName
passed in the API calls.

You must use the correct function ARN types in your policies to achieve the results that you expect,
especially in policies that deny access. We recommend that you follow the best practices for using Deny
statements with functions.

Best practices for using Deny statements with functions

The following table summarizes the resources to use in Deny effects. In the Resource column,
MyFunction is the name of the function, :1 refers to version 1 of the function, and MyAlias is the
name of a function alias.

62
 AWS Lambda Developer Guide
Function resource names

Resource best practices

Policy objective Resource

Deny access to all MyFunction*

versions of a function

Deny access to a MyFunction:MyAlias

specific alias and MyFunction

Deny access to a MyFunction:1 and

specific version of a MyFunction
function

The following sections provide example policy statements for each of the policy objectives.
Note
You can use only identity-based policies to deny specific function resources. Currently, Lambda
does not support the Deny effect in resource-based policies.

For the action list in a policy statement, you can add any of the actions defined by Lambda that act on a
function resource.

Deny access to all function versions

The following identity-based policy statement denies access to the
lambda:GetFunctionConfiguration action for all versions of the my-function function. The
wildcard character at the end of the function ARN ensures that this policy applies to all version and alias
ARNs.

Example Example identity-based policy

{
"Version": "2020-07-20",
"Statement": [
{
"Effect": "Deny",
"Action": [
"lambda:GetFunctionConfiguration"
],
"Resource": "arn:aws:lambda:us-west-2:123456789012:function:my-function*"
}
]
}

Deny access to a specific function alias

To deny access to a specific alias, you must specify both the alias ARN and the unqualified function ARN
in the policy. This prevents users from accessing the specific alias by passing the unqualified ARN as the
FunctionName and the alias as the Qualifier.
Note
If you create this type of policy, API calls need to refer to the unpublished version of the
function by specifying a qualified ARN with the $LATEST suffix in the FunctionName
parameter.

The following identity-based policy statement denies access to the lambda:InvokeFunction action in
the my-alias alias of the my-function function.

63
 AWS Lambda Developer Guide
Function actions

Example Example identity-based policy

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenySpecificAlias",
"Effect": "Deny",
"Action": "lambda:InvokeFunction",
"Resource": [
"arn:aws:lambda:us-west-2:123456789012:function:my-function:my-alias",
"arn:aws:lambda:us-west-2:123456789012:function:my-function"
]
}
]
}

Deny access to a specific function version

To deny access to a specific version, you must specify both the qualified ARN and the unqualified ARN in
the policy. This prevents users from accessing the specific version by passing the unqualified ARN as the
FunctionName and the version as the Qualifier.
Note
If you create this type of policy, API calls need to refer to the unpublished version of the
function by specifying a qualified ARN with the $LATEST suffix in the FunctionName
parameter.

The following identity-based policy statement denies access to the invoke action in version 1 of the my-
function function.

Example Example identity-based policy

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenySpecificFunctionVersion",
"Effect": "Deny",
"Action": [
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:us-west-2:123456789012:function:my-function:1",
"arn:aws:lambda:us-west-2:123456789012:function:my-function"
]
}
]
}

Function actions
Actions that operate on a function can be restricted to a specific function by function, version, or alias
ARN, as described in the following table. Actions that don't support resource restrictions can only be
granted for all resources (*).

64
 AWS Lambda Developer Guide
Function actions

Functions

Action Resource Condition

AddPermission (p. 743) Function lambda:Principal

RemovePermission (p. 906) Function version

Function alias

Invoke (p. 840) Function None

Permission: Function version

lambda:InvokeFunction
Function alias

CreateFunction (p. 763) Function lambda:CodeSigningConfigArn

UpdateFunctionConfiguration (p. 936) lambda:Layer

lambda:VpcIds

lambda:SubnetIds

lambda:SecurityGroupIds

CreateAlias (p. 747) Function None

DeleteAlias (p. 775)

DeleteFunction (p. 784)

DeleteFunctionConcurrency (p. 788)

GetAlias (p. 798)

GetFunction (p. 808)

GetFunctionConfiguration (p. 817)

GetPolicy (p. 835)

ListAliases (p. 848)

ListVersionsByFunction (p. 875)

PublishVersion (p. 883)

PutFunctionConcurrency (p. 894)

UpdateAlias (p. 912)

UpdateFunctionCode (p. 927)

GetAccountSettings (p. 796) * None

ListFunctions (p. 859)

ListTags (p. 873)

TagResource (p. 908)

65
 AWS Lambda Developer Guide
Event source mapping actions

Action Resource Condition

UntagResource (p. 910)

Event source mapping actions

For event source mappings, delete and update permissions can be restricted to a specific event source.
The lambda:FunctionArn condition lets you restrict which functions a user can configure an event
source to invoke.

For these actions, the resource is the event source mapping, so Lambda provides a condition that lets you
restrict permission based on the function that the event source mapping invokes.

Event source mappings

Action Resource Condition

DeleteEventSourceMapping (p. 779) Event source mapping lambda:FunctionArn

UpdateEventSourceMapping (p. 919)

CreateEventSourceMapping (p. 754) * lambda:FunctionArn

GetEventSourceMapping (p. 803) * None

ListEventSourceMappings (p. 853)

Layer actions
Layer actions let you restrict the layers that a user can manage or use with a function. Actions related
to layer use and permissions act on a version of a layer, while PublishLayerVersion acts on a layer
name. You can use either with wildcards to restrict the layers that a user can work with by name.
Note
Note: the GetLayerVersion (p. 827) action also covers GetLayerVersionByArn (p. 830).
Lambda does not support GetLayerVersionByArn as an IAM action.

Layers

Action Resource Condition

AddLayerVersionPermission (p. 739) Layer version None

RemoveLayerVersionPermission (p. 904)

GetLayerVersion (p. 827)

GetLayerVersionPolicy (p. 833)

DeleteLayerVersion (p. 792)

ListLayerVersions (p. 867) Layer None

PublishLayerVersion (p. 879)

ListLayers (p. 865) * None

66
 AWS Lambda Developer Guide
Permissions boundaries

Using permissions boundaries for AWS Lambda

applications
When you create an application (p. 178) in the AWS Lambda console, Lambda applies a permissions
boundary to the application's IAM roles. The permissions boundary limits the scope of the execution
role (p. 47) that the application's template creates for each of its functions, and any roles that you add
to the template. The permissions boundary prevents users with write access to the application's Git
repository from escalating the application's permissions beyond the scope of its own resources.

The application templates in the Lambda console include a global property that applies a permissions
boundary to all functions that they create.

Globals:
Function:
PermissionsBoundary: !Sub 'arn:${AWS::Partition}:iam::${AWS::AccountId}:policy/
${AppId}-${AWS::Region}-PermissionsBoundary'

The boundary limits the permissions of the functions' roles. You can add permissions to a function's
execution role in the template, but that permission is only effective if it's also allowed by the permissions
boundary. The role that AWS CloudFormation assumes to deploy the application enforces the use of the
permissions boundary. That role only has permission to create and pass roles that have the application's
permissions boundary attached.

By default, an application's permissions boundary enables functions to perform actions on the resources
in the application. For example, if the application includes an Amazon DynamoDB table, the boundary
allows access to any API action that can be restricted to operate on specific tables with resource-level
permissions. You can only use actions that don't support resource-level permissions if they're specifically
permitted in the boundary. These include Amazon CloudWatch Logs and AWS X-Ray API actions for
logging and tracing.

Example permissions boundary

{
"Version": "2012-10-17",
"Statement": [
{
"Action": [
"*"
],
"Resource": [
"arn:aws:lambda:us-east-2:123456789012:function:my-app-getAllItemsFunction-
*",
"arn:aws:lambda:us-east-2:123456789012:function:my-app-getByIdFunction-*",
"arn:aws:lambda:us-east-2:123456789012:function:my-app-putItemFunction-*",
"arn:aws:dynamodb:us-east-1:123456789012:table/my-app-SampleTable-*"
],
"Effect": "Allow",
"Sid": "StackResources"
},
{
"Action": [
"logs:CreateLogGroup",
"logs:CreateLogStream",
"logs:DescribeLogGroups",
"logs:PutLogEvents",
"xray:Put*"
],
"Resource": "*",

67
 AWS Lambda Developer Guide
Permissions boundaries

"Effect": "Allow",
"Sid": "StaticPermissions"
},
...
]
}

To access other resources or API actions, you or an administrator must expand the permissions boundary
to include those resources. You might also need to update the execution role or deployment role of an
application to allow the use of additional actions.

• Permissions boundary – Extend the application's permissions boundary when you add resources to
your application, or the execution role needs access to more actions. In IAM, add resources to the
boundary to allow the use of API actions that support resource-level permissions on that resource's
type. For actions that don't support resource-level permissions, add them in a statement that isn't
scoped to any resource.
• Execution role – Extend a function's execution role when it needs to use additional actions. In the
application template, add policies to the execution role. The intersection of permissions in the
boundary and execution role is granted to the function.
• Deployment role – Extend the application's deployment role when it needs additional permissions
to create or configure resources. In IAM, add policies to the application's deployment role. The
deployment role needs the same user permissions that you need to deploy or update an application in
AWS CloudFormation.

For a tutorial that walks through adding resources to an application and extending its permissions, see
??? (p. 178).

For more information, see Permissions boundaries for IAM entities in the IAM User Guide.

68
 AWS Lambda Developer Guide

Managing AWS Lambda functions

You can use the AWS Lambda API or console to create functions and configure function settings. Basic
function settings (p. 70) include the description and the execution role that you specify when you
create a function in the Lambda console. You can configure more settings after you create a function, or
use the API to modify configuration settings such as the handler name, memory allocation, and security
groups during creation.

To keep secrets out of your function code, store them in the function's configuration and read them from
the execution environment during initialization. Environment variables (p. 77) are always encrypted
at rest, and can be encrypted client-side as well. Use environment variables to make your function code
portable by removing connection strings, passwords, and endpoints for external resources.

Versions and aliases (p. 95) are secondary resources that you can create to manage function
deployment and invocation. Publish versions (p. 95) of your function to store its code and
configuration as a separate resource that cannot be changed, and create an alias (p. 97) that points
to a specific version. Then you can configure your clients to invoke a function alias, and update the alias
when you want to point the client to a new version, instead of updating the client.

As you add libraries and other dependencies to your function, creating and uploading a deployment
package can slow down development. Use layers (p. 101) to manage your function's dependencies
independently and keep your deployment package small. You can also use layers to share your own
libraries with other customers and use publicly available layers with your functions.

To use your Lambda function with AWS resources in an Amazon VPC, configure it with security groups
and subnets to create a VPC connection (p. 111). Connecting your function to a VPC lets you access
resources in a private subnet such as relational databases and caches. You can also create a database
proxy (p. 121) for MySQL and Aurora DB instances. A database proxy enables a function to reach high
concurrency levels without exhausting database connections.

To use code signing (p. 130) with your Lambda function, configure it with a code-signing configuration.
When a user attempts to deploy a code package, Lambda checks that the code package has a valid
signature from a trusted publisher. The code-signing configuration includes a set of signing profiles,
which define the trusted publishers for this function.

69
 AWS Lambda Developer Guide
Configure console

Configuring functions in the console

You can use the Lambda console to configure function settings, add triggers and destinations, and
update and test your code.

To manage a function, open the Lambda console Functions page and choose a function.

The function overview shows a visualization of your function and its upstream and downstream
resources.

You can use it to configure triggers, layers, and destinations.

• Triggers – Triggers are services and resources that you have configured to invoke your function.
Choose Add trigger to create a Lambda event source mapping (p. 148) or to configure a trigger in
another service that the Lambda console integrates with. For details about these services and others,
see Using AWS Lambda with other services (p. 257).
• Layers – Choose the Layers node to add layers (p. 101) to your application. A layer is a .zip file
archive that contains libraries, a custom runtime, or other dependencies.
• Destinations – Add a destination to your function to send details about invocation results to another
service. You can send invocation records when your function is invoked asynchronously (p. 140), or by
an event source mapping (p. 148) that reads from a stream.

By default you are working with the Latest function version. You can modify the following settings in
this version:

Function settings

• Code – The code and dependencies of your function. For scripting languages, you can edit your
function code in the embedded editor (p. 17). To add libraries, or for languages that the editor doesn't
support, or to create a function deployed as a container image, upload a deployment package (p. 41).
If your deployment package is larger than 50 MB, choose Upload a file from Amazon S3.
• Runtime – The Lambda runtime (p. 195) that runs your function.
• Handler – The method that the runtime runs when your function is invoked, such as index.handler.
The first value is the name of the file or module. The second value is the name of the method.
• Environment variables – Key-value pairs that Lambda sets in the execution environment. To extend
your function's configuration outside of code, use environment variables (p. 77).
• Tags – Key-value pairs that Lambda attaches to your function resource. Use tags (p. 134) to organize
Lambda functions into groups for cost reporting and filtering in the Lambda console.

Tags apply to the entire function, including all versions and aliases.
• Execution role – The AWS Identity and Access Management (IAM) role (p. 47) that Lambda assumes
when it runs your function.

70
 AWS Lambda Developer Guide
Configure console

• Description – A description of the function.

• Memory– The amount of memory available to the function at runtime. To set the memory for your
function, enter a value between 128 MB and 10,240 MB in 1-MB increments.
• Timeout – The amount of time that Lambda allows a function to run before stopping it. The default is
three seconds. The maximum allowed value is 900 seconds.
• Virtual private cloud (VPC) – If your function needs network access to resources that are not available
over the internet, configure it to connect to a virtual private cloud (VPC) (p. 111).
• Database proxies – Create a database proxy (p. 121) for functions that use an Amazon RDS DB
instance or cluster.
• Active tracing – Sample incoming requests and trace sampled requests with AWS X-Ray (p. 451).
• Concurrency – Reserve concurrency for a function (p. 84) to set the maximum number of
simultaneous executions for a function. Provision concurrency to ensure that a function can scale
without fluctuations in latency.

Reserved concurrency applies to the entire function, including all versions and aliases.
• Asynchronous invocation – Configure error handling behavior (p. 140) to reduce the number of
retries that Lambda attempts, or the amount of time that unprocessed events stay queued before
Lambda discards them. Configure a dead-letter queue (p. 145) to retain discarded events.

You can configure error handling settings on a function, version, or alias.

Except as noted in the preceding list, you can only change function settings on the unpublished version
of a function. When you publish a version, code and most settings are locked to ensure a consistent
experience for users of that version. Use aliases (p. 97) to propagate configuration changes in a
controlled manner.

To configure functions with the Lambda API, use the following actions:

• UpdateFunctionCode (p. 927) – Update the function's code.

• UpdateFunctionConfiguration (p. 936) – Update version-specific settings.
• TagResource (p. 908) – Tag a function.
• AddPermission (p. 743) – Modify the resource-based policy (p. 51) of a function, version, or alias.
• PutFunctionConcurrency (p. 894) – Configure a function's reserved concurrency.
• PublishVersion (p. 883) – Create an immutable version with the current code and configuration.
• CreateAlias (p. 747) – Create aliases for function versions.
• PutFunctionEventInvokeConfig – Configure error handling for asynchronous invocation.

For example, to update a function's memory setting with the AWS CLI, use the update-function-
configuration command.

aws lambda update-function-configuration --function-name my-function --memory-size 256

For function configuration best practices, see Function configuration (p. 193).

71
 AWS Lambda Developer Guide
Functions defined as container images

Configuring functions defined as container images

You can use the Lambda console and the Lambda API to create a function defined as a container image,
update and test the image code, and configure other function settings.
Note
You cannot convert an existing .zip file archive function to use a container image. You must
create a new function.

When you select an image using an image tag, Lambda translates the tag to the underlying image digest.
To retrieve the digest for your image, use the GetFunctionConfiguration (p. 817) API operation. To
update the function to a newer image version, you must use the Lambda console to update the function
code (p. 74), or use the UpdateFunctionCode (p. 927) API operation. Configuration operations such
as UpdateFunctionConfiguration (p. 936) do not update the function's container image.
Note
In Amazon ECR, if you reassign the image tag to another image, Lambda does not update the
image version.

Topics
• Function version $LATEST (p. 72)
• Container image deployment (p. 72)
• Amazon ECR permissions (p. 72)
• Override the container settings (p. 73)
• Creating a function (console) (p. 73)
• Updating the function code (console) (p. 74)
• Overriding the image parameters (console) (p. 74)
• Using the Lambda API (p. 75)
• AWS CloudFormation (p. 75)

Function version $LATEST

When you publish a function version, the code and most of the configuration settings are locked
to maintain a consistent experience for users of that version. You can change the code and many
configuration settings only on the unpublished version of the function. By default, the console displays
configuration information for the unpublished version of the function. To view the versions of a function,
choose Qualifiers. The unpublished version is named $LATEST.

Note that Amazon Elastic Container Registry (Amazon ECR) also uses a latest tag to denote the latest
version of the container image. Be careful not to confuse this tag with the $LATEST function version.

For more information about managing versions, see Lambda function versions (p. 95).

Container image deployment

When you deploy code as a container image to a Lambda function, the image undergoes an optimization
process for running on Lambda. This process can take a few seconds, during which the function is in
pending state. When the optimization process completes, the function enters the active state.

Amazon ECR permissions

For your function to access the container image in Amazon ECR, you can add ecr:BatchGetImage and
ecr:GetDownloadUrlForLayer permissions to your Amazon ECR repository. The following example
shows the minumum policy:

72
 AWS Lambda Developer Guide
Override the container settings

{
"Sid": "LambdaECRImageRetrievalPolicy",
"Effect": "Allow",
"Principal": {
"Service": "lambda.amazonaws.com"
},
"Action": [
"ecr:BatchGetImage",
"ecr:GetDownloadUrlForLayer"
]
}

For more information about Amazon ECR repository permissions, see Repository policies in the Amazon
Elastic Container Registry User Guide.

If the Amazon ECR repository does not include these permissions, Lambda adds ecr:BatchGetImage
and ecr:GetDownloadUrlForLayer to the container image repository permissions. Lambda can
add these permissions only if the Principal calling Lambda has ecr:getRepositoryPolicy and
ecr:setRepositoryPolicy permissions.

To view or edit your Amazon ECR repository permissions, follow the directions in Setting a repository
policy statement in the Amazon Elastic Container Registry User Guide.

Override the container settings

You can use the Lambda console or the Lambda API to override the following container image settings:

• ENTRYPOINT – Specifies the absolute path of the entry point to the application.
• CMD – Specifies parameters that you want to pass in with ENTRYPOINT.
• WORKDIR – Specifies the absolute path of the working directory.
• ENV – Specifies an environment variable for the Lambda function.

Any values that you provide in the Lambda console or the Lambda API override the values in the
Dockerfile (p. 249).

Creating a function (console)

To create a function defined as a container image, you must first create the image (p. 248) and then
store the image in the Amazon ECR repository.

To create the function

1. Open the Functions page on the Lambda console.

2. Choose Create function.
3. Choose the Container image option.
4. Under Basic information, do the following:

a. For Function name, enter the function name.

b. For Container image URI, enter the Amazon ECR image URI.
• Or, to browse an Amazon ECR repository for the image, choose Browse images. Select the
Amazon ECR repository from the dropdown list, and then select the image.
c. (Optional) To override configuration settings that are included in the Dockerfile, expand
Container image overrides. You can override any of the following settings:

73
 AWS Lambda Developer Guide
Updating the function code (console)

• For Entrypoint, enter the full path of the runtime executable. The following example shows
an entrypoint for a Node.js function:

"/usr/bin/npx", "aws-lambda-ric"

• For Command, enter additional parameters to pass in to the image with Entrypoint. The
following example shows a command for a Node.js function:

"app.handler"

• For Working directory, enter the full path of the working directory for the function. The
following example shows the working directory for an AWS base image for Lambda:

"/var/task"

Note
For the override settings, make sure that you enclose each string in quotation marks ("
").
5. (Optional) Under Permissions, expand Change default execution role. Then, choose to create a new
Execution role, or to use an existing role.
6. Choose Create function.

Updating the function code (console)

After you deploy a container image to a function, the image is read-only. To update the function code,
you must first deploy a new image version. Create a new image version (p. 248), and then store the
image in the Amazon ECR repository.

To configure the function to use an updated container image

1. Open the Functions page on the Lambda console.

2. Choose the function to update.
3. Under Image, choose Deploy new image.
4. Choose Browse images.
5. In the Select container image dialog box, select the Amazon ECR repository from the dropdown list,
and then select the new image version.
6. Choose Save.

Overriding the image parameters (console)

You can use the Lambda console to override the configuration values in the container image.

To override the configuration values in the container image

1. Open the Functions page on the Lambda console.

2. Choose the function to update.
3. Under Image configuration, choose Edit.
4. Enter new values for any of the override settings, and then choose Save.
5. (Optional) To add or override environment variables, under Environment variables, choose Edit.

74
 AWS Lambda Developer Guide
Using the Lambda API

For more information, see the section called “Environment variables” (p. 77).

Using the Lambda API

To manage functions defined as container images, use the following API operations:

• CreateFunction (p. 763)

• UpdateFunctionCode (p. 927)
• UpdateFunctionConfiguration (p. 936)

To create a function defined as container image, use the create-function command. Set the
package-type to Image and specify your container image URI using the code parameter. Note that
you must create the function from the same account as the container registry in Amazon EFS.

aws lambda create-function --region sa-east-1 --function-name my-function \

--package-type Image \
--code ImageUri=<ECR Image URI> \
--role arn:aws:iam::123456789012:role/lambda-ex

To update the function code, use the update-function-code command. Specify the container image
location using the image-uri parameter.
Note
You cannot change the package-type of a function.

aws lambda update-function-code --region sa-east-1 --function-name my-function \

--image-uri <ECR Image URI> \

To update the function parameters, use the update-function-configuration operation. Specify

EntryPoint and Command as arrays of strings, and WorkingDirectory as a string.

aws lambda update-function-configuration --function-name my-function \

--image-config '{"EntryPoint": ["/usr/bin/npx", "aws-lambda-ric"], \
"Command": ["app.handler"] , \
"WorkingDirectory": "/var/task"}'

AWS CloudFormation
You can use AWS CloudFormation to create Lambda functions defined as container images. In your AWS
CloudFormation template, the AWS::Lambda::Function resource specifies the Lambda function. For
descriptions of the properties in the AWS::Lambda::Function resource, see AWS::Lambda::Function in
the AWS CloudFormation User Guide.

In the AWS::Lambda::Function resource, set the following properties to create a function defined as a
container image:

• AWS::Lambda::Function
• PackageType – Set to Image.
• Code – Enter your container image URI in the ImageUri field.
• ImageConfig – (Optional) Override the container image configuration properties.

The ImageConfig property in AWS::Lambda::Function contains the following fields:

75
 AWS Lambda Developer Guide
AWS CloudFormation

• Command – Specifies parameters that you want to pass in with EntryPoint.

• EntryPoint – Specifies the entry point to the application.
• WorkingDirectory – Specifies the working directory.

Note
If you declare an ImageConfig property in your AWS CloudFormation template, you must
provide values for all three of the ImageConfig properties.

For more information, see ImageConfig in the AWS CloudFormation User Guide.

76
 AWS Lambda Developer Guide
Environment variables

Using AWS Lambda environment variables

You can use environment variables to adjust your function's behavior without updating code. An
environment variable is a pair of strings that are stored in a function's version-specific configuration. The
Lambda runtime makes environment variables available to your code and sets additional environment
variables that contain information about the function and invocation request.
Note
To increase database security, we recommend that you use AWS Secrets Manager instead of
environment variables to store database credentials. For more information, see Configuring
database access for a Lambda function.

Environment variables are not evaluated prior to the function invocation. Any value you define is
considered a literal string and not expanded. Perform the variable evaluation in your function code.

Sections
• Configuring environment variables (p. 77)
• Configuring environment variables with the API (p. 78)
• Example scenario for environment variables (p. 78)
• Retrieve environment variables (p. 79)
• Defined runtime environment variables (p. 80)
• Securing environment variables (p. 81)
• Sample code and templates (p. 83)

Configuring environment variables

You define environment variables on the unpublished version of your function. When you publish
a version, the environment variables are locked for that version along with other version-specific
configuration (p. 70).

You create an environment variable on your function by defining a key and a value. Your function uses
the name of the key to retrieve the value of environment variable.

To set environment variables in the Lambda console

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration, then choose Environment variables.
4. Under Environment variables, choose Edit.
5. Choose Add environment variable.
6. Enter a key and value.

Requirements

• Keys start with a letter and are at least two characters.

• Keys only contain letters, numbers, and the underscore character (_).
• Keys aren't reserved by Lambda (p. 80).
• The total size of all environment variables doesn't exceed 4 KB.
7. Choose Save.

77
 AWS Lambda Developer Guide
Configuring environment variables with the API

Configuring environment variables with the API

To manage environment variables with the AWS CLI or AWS SDK, use the following API operations.

• UpdateFunctionConfiguration (p. 936)

• GetFunctionConfiguration (p. 817)
• CreateFunction (p. 763)

The following example sets two environment variables on a function named my-function.

aws lambda update-function-configuration --function-name my-function \

--environment "Variables={BUCKET=my-bucket,KEY=file.txt}"

When you apply environment variables with the update-function-configuration command, the
entire contents of the Variables structure is replaced. To retain existing environment variables when
you add a new one, include all existing values in your request.

To get the current configuration, use the get-function-configuration command.

aws lambda get-function-configuration --function-name my-function

You should see the following output:

{
"FunctionName": "my-function",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"Runtime": "nodejs12.x",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Environment": {
"Variables": {
"BUCKET": "my-bucket",
"KEY": "file.txt"
}
},
"RevisionId": "0894d3c1-2a3d-4d48-bf7f-abade99f3c15",
...
}

To ensure that the values don't change between when you read the configuration and when you update
it, you can pass the revision ID from the output of get-function-configuration as a parameter to
update-function-configuration.

To configure a function's encryption key, set the KMSKeyARN option.

aws lambda update-function-configuration --function-name my-function \

--kms-key-arn arn:aws:kms:us-east-2:123456789012:key/055efbb4-xmpl-4336-
ba9c-538c7d31f599

Example scenario for environment variables

You can use environment variables to customize function behavior in your test environment and
production environment. For example, you can create two functions with the same code but different
configurations. One function connects to a test database, and the other connects to a production
database. In this situation, you use environment variables to tell the function the hostname and other
connection details for the database.

78
 AWS Lambda Developer Guide
Retrieve environment variables

The following example shows how to define the database host and database name as environment
variables.

If you want your test environment to generate more debug information than the production
environment, you could set an environment variable to configure your test environment to use more
verbose logging or more detailed tracing.

Retrieve environment variables

To retrieve environment variables in your function code, use the standard method for your programming
language.

Node.js

let region = process.env.AWS_REGION

Python

import os
region = os.environ['AWS_REGION']

Note
In some cases, you may need to use the following format:

region = os.environ.get('AWS_REGION')

Ruby

region = ENV["AWS_REGION"]

Java

String region = System.getenv("AWS_REGION");

Go

var region = os.Getenv("AWS_REGION")

C#

string region = Environment.GetEnvironmentVariable("AWS_REGION");

79
 AWS Lambda Developer Guide
Defined runtime environment variables

PowerShell

$region = $env:AWS_REGION

Lambda stores environment variables securely by encrypting them at rest. You can configure Lambda to
use a different encryption key (p. 81), encrypt environment variable values on the client side, or set
environment variables in an AWS CloudFormation template with AWS Secrets Manager.

Defined runtime environment variables

Lambda runtimes (p. 195) set several environment variables during initialization. Most of the
environment variables provide information about the function or runtime. The keys for these
environment variables are reserved and cannot be set in your function configuration.

Reserved environment variables

• _HANDLER – The handler location configured on the function.

• _X_AMZN_TRACE_ID – The X-Ray tracing header (p. 451).
• AWS_REGION – The AWS Region where the Lambda function is executed.
• AWS_EXECUTION_ENV – The runtime identifier (p. 195), prefixed by AWS_Lambda_—for example,
AWS_Lambda_java8.
• AWS_LAMBDA_FUNCTION_NAME – The name of the function.
• AWS_LAMBDA_FUNCTION_MEMORY_SIZE – The amount of memory available to the function in MB.
• AWS_LAMBDA_FUNCTION_VERSION – The version of the function being executed.

AWS_LAMBDA_INITIALIZATION_TYPE – The initialization type of the function, which is either

on-demand or provisioned-concurrency. For information, see Configuring provisioned
concurrency (p. 87).
• AWS_LAMBDA_LOG_GROUP_NAME, AWS_LAMBDA_LOG_STREAM_NAME – The name of the Amazon
CloudWatch Logs group and stream for the function.
• AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN – The access keys obtained
from the function's execution role (p. 47).
• AWS_LAMBDA_RUNTIME_API – (Custom runtime (p. 236)) The host and port of the runtime
API (p. 205).
• LAMBDA_TASK_ROOT – The path to your Lambda function code.
• LAMBDA_RUNTIME_DIR – The path to runtime libraries.
• TZ – The environment's time zone (UTC). The execution environment uses NTP to synchronize the
system clock.

The following additional environment variables aren't reserved and can be extended in your function
configuration.

Unreserved environment variables

• LANG – The locale of the runtime (en_US.UTF-8).

• PATH – The execution path (/usr/local/bin:/usr/bin/:/bin:/opt/bin).
• LD_LIBRARY_PATH – The system library path (/lib64:/usr/lib64:$LAMBDA_RUNTIME_DIR:
$LAMBDA_RUNTIME_DIR/lib:$LAMBDA_TASK_ROOT:$LAMBDA_TASK_ROOT/lib:/opt/lib).
• NODE_PATH – (Node.js (p. 484)) The Node.js library path (/opt/nodejs/node12/
node_modules/:/opt/nodejs/node_modules:$LAMBDA_RUNTIME_DIR/node_modules).
• PYTHONPATH – (Python 2.7, 3.6, 3.8 (p. 510)) The Python library path ($LAMBDA_RUNTIME_DIR).

80
 AWS Lambda Developer Guide
Securing environment variables

• GEM_PATH – (Ruby (p. 547)) The Ruby library path ($LAMBDA_TASK_ROOT/vendor/bundle/

ruby/2.5.0:/opt/ruby/gems/2.5.0).
• AWS_XRAY_CONTEXT_MISSING – For X-Ray tracing, Lambda sets this to LOG_ERROR to avoid throwing
runtime errors from the X-Ray SDK.
• AWS_XRAY_DAEMON_ADDRESS – For X-Ray tracing, the IP address and port of the X-Ray daemon.
• AWS_LAMBDA_DOTNET_PREJIT – For the .NET 3.1 runtime, set this variable to enable or disable .NET
3.1 specific runtime optimizations. Values include always, never, and provisioned-concurrency.
For information, see Configuring provisioned concurrency (p. 87).

The sample values shown reflect the latest runtimes. The presence of specific variables or their values
can vary on earlier runtimes.

Securing environment variables

Lambda encrypts environment variables with a key that it creates in your account (an AWS managed
customer master key (CMK)). Use of this key is free. You can also choose to provide your own key for
Lambda to use instead of the default key.

When you provide the key, only users in your account with access to the key can view or manage
environment variables on the function. Your organization might also have internal or external
requirements to manage keys that are used for encryption and to control when they're rotated.

To use a customer managed CMK

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration, then choose Environment variables.
4. Under Environment variables, choose Edit.
5. Expand Encryption configuration.
6. Choose Use a customer master key.
7. Choose your customer managed CMK.
8. Choose Save.

Customer managed CMKs incur standard AWS KMS charges.

No AWS KMS permissions are required for your user or the function's execution role to use the default
encryption key. To use a customer managed CMK, you need permission to use the key. Lambda uses your
permissions to create a grant on the key. This allows Lambda to use it for encryption.

• kms:ListAliases – To view keys in the Lambda console.

• kms:CreateGrant, kms:Encrypt – To configure a customer managed CMK on a function.
• kms:Decrypt – To view and manage environment variables that are encrypted with a customer
managed CMK.

You can get these permissions from your user account or from a key's resource-based permissions policy.
ListAliases is provided by the managed policies for Lambda (p. 56). Key policies grant the remaining
permissions to users in the Key users group.

Users without Decrypt permissions can still manage functions, but they can't view environment
variables or manage them in the Lambda console. To prevent a user from viewing environment variables,
add a statement to the user's permissions that denies access to the default key, a customer managed key,
or all keys.

81
 AWS Lambda Developer Guide
Securing environment variables

Example IAM policy – Deny access by key ARN

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Deny",
"Action": [
"kms:Decrypt"
],
"Resource": "arn:aws:kms:us-east-2:123456789012:key/3be10e2d-xmpl-4be4-
bc9d-0405a71945cc"
}
]
}

For details on managing key permissions, see Using key policies in AWS KMS.

You can also encrypt environment variable values on the client side before sending them to Lambda, and
decrypt them in your function code. This obscures secret values in the Lambda console and API output,
even for users who have permission to use the key. In your code, you retrieve the encrypted value from
the environment and decrypt it by using the AWS KMS API.

To encrypt environment variables on the client side

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration, then choose Environment variables.
4. Under Environment variables, choose Edit.
5. Expand Encryption configuration.
6. Choose Enable helpers for encryption in transit.
7. Choose Encrypt next to a variable to encrypt its value.
8. Choose Save.

Note
When you use the console encryption helpers, your function needs permission to call the
kms:Decrypt API operation in its execution role (p. 47).

To view sample code for your function's language, choose Code next to an environment variable. The
sample code shows how to retrieve an environment variable in a function and decrypt its value.

Another option is to store passwords in AWS Secrets Manager secrets. You can reference the secret in
your AWS CloudFormation templates to set passwords on databases. You can also set the value of an
environment variable on the Lambda function. For an example, see the next section.

82
 AWS Lambda Developer Guide
Sample code and templates

Sample code and templates

Sample applications in this guide's GitHub repository demonstrate the use of environment variables in
function code and AWS CloudFormation templates.

Sample applications

• Blank function (p. 466) – Create a function and an Amazon SNS topic in the same template. Pass
the name of the topic to the function in an environment variable. Read environment variables in code
(multiple languages).
• RDS MySQL – Create a VPC and an Amazon RDS DB instance in one template, with a password stored
in Secrets Manager. In the application template, import database details from the VPC stack, read the
password from Secrets Manager, and pass all connection configuration to the function in environment
variables.

83
 AWS Lambda Developer Guide
Concurrency

Managing concurrency for a Lambda function

Concurrency is the number of requests that your function is serving at any given time. When your
function is invoked, Lambda allocates an instance of it to process the event. When the function code
finishes running, it can handle another request. If the function is invoked again while a request is still
being processed, another instance is allocated, which increases the function's concurrency. Concurrency is
subject to a Regional quota (p. 44) that is shared by all functions in a Region.

There are two types of concurrency controls available:

• Reserved concurrency – Reserved concurrency guarantees the maximum number of concurrent

instances for the function. When a function has reserved concurrency, no other function can use that
concurrency. There is no charge for configuring reserved concurrency for a function.
• Provisioned concurrency – Provisioned concurrency initializes a requested number of execution
environments so that they are prepared to respond immediately to your function's invocations. Note
that configuring provisioned concurrency incurs charges to your AWS account.

This topic details how to manage and configure reserved and provisioned concurrency. To learn about
how concurrency interacts with scaling, see Lambda function scaling.

To ensure that a function can always reach a certain level of concurrency, configure the function with
reserved concurrency (p. 85). When a function has reserved concurrency, no other function can use
that concurrency. Reserved concurrency also limits the maximum concurrency for the function, and
applies to the function as a whole, including versions and aliases.

When Lambda allocates an instance of your function, the runtime (p. 195) loads your function's code
and runs initialization code that you define outside of the handler. If your code and dependencies are
large, or you create SDK clients during initialization, this process can take some time. As your function
scales up (p. 153), this causes the portion of requests that are served by new instances to have higher
latency than the rest.

To enable your function to scale without fluctuations in latency, use provisioned concurrency (p. 87).
By allocating provisioned concurrency before an increase in invocations, you can ensure that all requests
are served by initialized instances with very low latency. You can configure provisioned concurrency on a
version of a function, or on an alias.

Lambda also integrates with Application Auto Scaling. You can configure Application Auto Scaling
to manage provisioned concurrency on a schedule or based on utilization. Use scheduled scaling to
increase provisioned concurrency in anticipation of peak traffic. To increase provisioned concurrency
automatically as needed, use the Application Auto Scaling API (p. 90) to register a target and create a
scaling policy.

Provisioned concurrency counts towards a function's reserved concurrency and Regional quotas. If
the amount of provisioned concurrency on a function's versions and aliases adds up to the function's
reserved concurrency, all invocations run on provisioned concurrency. This configuration also has the
effect of throttling the unpublished version of the function ($LATEST), which prevents it from executing.
Note
You can't allocate more provisioned concurrency than reserved concurrency for a function.

Sections
• Configuring reserved concurrency (p. 85)
• Configuring provisioned concurrency (p. 87)
• Configuring concurrency with the Lambda API (p. 90)

84
 AWS Lambda Developer Guide
Configuring reserved concurrency

Configuring reserved concurrency

To manage reserved concurrency settings for a function, use the Lambda console.

To reserve concurrency for a function

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose Concurrency.
4. Under Concurrency, choose Edit.
5. Choose Reserve concurrency. Enter the amount of concurrency to reserve for the function.
6. Choose Save.

You can reserve up to the Unreserved account concurrency value that is shown, minus 100 for functions
that don't have reserved concurrency. To throttle a function, set the reserved concurrency to zero. This
stops any events from being processed until you remove the limit.

The following example shows two functions with pools of reserved concurrency, and the unreserved
concurrency pool used by other functions. Throttling errors occur when all of the concurrency in a pool is
in use.

85
 AWS Lambda Developer Guide
Configuring reserved concurrency

Legend

• Function concurrency
• Reserved concurrency
• Unreserved concurrency
• Throttling

Reserving concurrency has the following effects.

• Other functions can't prevent your function from scaling – All of your account's functions in the
same Region without reserved concurrency share the pool of unreserved concurrency. Without
reserved concurrency, other functions can use up all of the available concurrency. This prevents your
function from scaling up when needed.
• Your function can't scale out of control – Reserved concurrency also limits your function from
using concurrency from the unreserved pool, which caps its maximum concurrency. You can reserve

86
 AWS Lambda Developer Guide
Configuring provisioned concurrency

concurrency to prevent your function from using all the available concurrency in the Region, or from
overloading downstream resources.

Setting per-function concurrency can impact the concurrency pool that is available to other functions.
To avoid issues, limit the number of users who can use the PutFunctionConcurrency and
DeleteFunctionConcurrency API operations.

Configuring provisioned concurrency

To manage provisioned concurrency settings for a version or alias, use the Lambda console.

To provision concurrency for an alias

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose Concurrency.
4. Under Provisioned concurrency configurations, choose Add configuration.
5. Choose an alias or version.
6. Enter the amount of provisioned concurrency to allocate.
7. Choose Save.

You can manage provisioned concurrency for all aliases and versions from the function configuration
page. The list of provisioned concurrency configurations shows the allocation progress of each
configuration. Provisioned concurrency settings are also available on the configuration page for each
version and alias.

In the following example, the my-function-DEV and my-function-PROD functions are configured
with both reserved and provisioned concurrency. For my-function-DEV, the full pool of reserved
concurrency is also provisioned concurrency. In this case, all invocations either run on provisioned
concurrency or are throttled. For my-function-PROD, a portion of the reserved concurrency pool
is standard concurrency. When all provisioned concurrency is in use, the function scales on standard
concurrency to serve any additional requests.

87
 AWS Lambda Developer Guide
Configuring provisioned concurrency

Legend

• Function concurrency
• Reserved concurrency
• Provisioned concurrency
• Unreserved concurrency
• Throttling

Provisioned concurrency does not come online immediately after you configure it. Lambda starts
allocating provisioned concurrency after a minute or two of preparation. Similar to how functions scale
under load (p. 153), up to 3000 instances of the function can be initialized at once, depending on the
Region. After the initial burst, instances are allocated at a steady rate of 500 per minute until the request
is fulfilled. When you request provisioned concurrency for multiple functions or versions of a function in
the same Region, scaling quotas apply across all requests.

88
 AWS Lambda Developer Guide
Configuring provisioned concurrency

Legend

• Function instances
• Open requests
• Provisioned concurrency
• Standard concurrency

To optimize latency, you can customize the initialization behavior for functions that use provisioned
concurrency . You can run initialization code for provisioned concurrency instances without impacting
latency, because the initialization code runs at allocation time. However, the initialization code for an
on-demand instance directly impacts the latency of the first invocation. For an on-demand instance, you
may choose to defer initialization for a specific capability until the function needs that capability.

To determine the type of initialization, check the value of AWS_LAMBDA_INITIALIZATION_TYPE.

Lambda sets this environment variable to provisioned-concurrency or on-demand. The value

89
 AWS Lambda Developer Guide
Configuring concurrency with the Lambda API

of AWS_LAMBDA_INITIALIZATION_TYPE is immutable and does not change over the lifetime of the
execution environment.

If you use the .NET 3.1 runtime, you can configure the AWS_LAMBDA_DOTNET_PREJIT environment
variable to improve the latency for functions that use provisioned concurrency. The .NET runtime
lazily compiles and initializes each library that your code calls for the first time. As a result, the
first invocation of a Lambda function can take longer than subsequent invocations. When you set
AWS_LAMBDA_DOTNET_PREJIT to ProvisionedConcurrency, Lambda performs ahead-of-time JIT
compilation for common system dependencies. Lambda performs this initialization optimization for
provisioned concurrency instances only, which results in faster performance for the first invocation. If
you set the environment variable to Always, Lambda performs ahead-of-time JIT compilation for every
initialization. If you set the environment variable to Never, ahead-of-time JIT compilation is disabled.
The default value for AWS_LAMBDA_DOTNET_PREJIT is ProvisionedConcurrency.

For provisioned concurrency instances, your function's initialization code (p. 32) runs during allocation
and every few hours, as running instances of your function are recycled. You can see the initialization
time in logs and traces (p. 451) after an instance processes a request. However, initialization is billed
even if the instance never processes a request. Provisioned concurrency runs continually and is billed
separately from initialization and invocation costs. For details, see AWS Lambda pricing.

Each version of a function can only have one provisioned concurrency configuration. This can be directly
on the version itself, or on an alias that points to the version. Two aliases can't allocate provisioned
concurrency for the same version. Also, you can't allocate provisioned concurrency on an alias that points
to the unpublished version ($LATEST).

When you change the version that an alias points to, provisioned concurrency is deallocated from the old
version and then allocated to the new version. You can add a routing configuration to an alias that has
provisioned concurrency. However, you can't manage provisioned concurrency settings on the alias while
the routing configuration is in place.

Lambda emits the following metrics for provisioned concurrency:

Provisioned concurrency metrics

• ProvisionedConcurrentExecutions
• ProvisionedConcurrencyInvocations
• ProvisionedConcurrencySpilloverInvocations
• ProvisionedConcurrencyUtilization

For details, see Working with AWS Lambda function metrics (p. 692).

Configuring concurrency with the Lambda API

To manage concurrency settings and autoscaling with the AWS CLI or AWS SDK, use the following API
operations.

• PutFunctionConcurrency (p. 894)

• GetFunctionConcurrency
• DeleteFunctionConcurrency (p. 788)
• PutProvisionedConcurrencyConfig
• GetProvisionedConcurrencyConfig
• ListProvisionedConcurrencyConfigs
• DeleteProvisionedConcurrencyConfig

90
 AWS Lambda Developer Guide
Configuring concurrency with the Lambda API

• GetAccountSettings (p. 796)

• (Application Auto Scaling) RegisterScalableTarget
• (Application Auto Scaling) PutScalingPolicy

To configure reserved concurrency with the AWS CLI, use the put-function-concurrency command.
The following command reserves a concurrency of 100 for a function named my-function:

aws lambda put-function-concurrency --function-name my-function --reserved-concurrent-

executions 100

You should see the following output:

{
"ReservedConcurrentExecutions": 100
}

To allocate provisioned concurrency for a function, use put-provisioned-concurrency-config.

The following command allocates a concurrency of 100 for the BLUE alias of a function named my-
function:

aws lambda put-provisioned-concurrency-config --function-name my-function \

--qualifier BLUE --provisioned-concurrent-executions 100

You should see the following output:

{
"Requested ProvisionedConcurrentExecutions": 100,
"Allocated ProvisionedConcurrentExecutions": 0,
"Status": "IN_PROGRESS",
"LastModified": "2019-11-21T19:32:12+0000"
}

To configure Application Auto Scaling to manage provisioned concurrency, use the Application Auto
Scaling to configure target tracking scaling. First, register a function's alias as a scaling target. The
following example registers the BLUE alias of a function named my-function:

aws application-autoscaling register-scalable-target --service-namespace lambda \

--resource-id function:my-function:BLUE --min-capacity 1 --max-capacity 100 \
--scalable-dimension lambda:function:ProvisionedConcurrency

Next, apply a scaling policy to the target. The following example configures Application Auto Scaling to
adjust the provisioned concurrency configuration for an alias to keep utilization near 70 percent:

aws application-autoscaling put-scaling-policy --service-namespace lambda \

--scalable-dimension lambda:function:ProvisionedConcurrency --resource-id function:my-
function:BLUE \
--policy-name my-policy --policy-type TargetTrackingScaling \
--target-tracking-scaling-policy-configuration '{ "TargetValue":
0.7, "PredefinedMetricSpecification": { "PredefinedMetricType":
"LambdaProvisionedConcurrencyUtilization" }}'

You should see the following output:

91
 AWS Lambda Developer Guide
Configuring concurrency with the Lambda API

"PolicyARN": "arn:aws:autoscaling:us-east-2:123456789012:scalingPolicy:12266dbb-1524-
xmpl-a64e-9a0a34b996fa:resource/lambda/function:my-function:BLUE:policyName/my-policy",
"Alarms": [
{
"AlarmName": "TargetTracking-function:my-function:BLUE-AlarmHigh-aed0e274-
xmpl-40fe-8cba-2e78f000c0a7",
"AlarmARN": "arn:aws:cloudwatch:us-east-2:123456789012:alarm:TargetTracking-
function:my-function:BLUE-AlarmHigh-aed0e274-xmpl-40fe-8cba-2e78f000c0a7"
},
{
"AlarmName": "TargetTracking-function:my-function:BLUE-AlarmLow-7e1a928e-
xmpl-4d2b-8c01-782321bc6f66",
"AlarmARN": "arn:aws:cloudwatch:us-east-2:123456789012:alarm:TargetTracking-
function:my-function:BLUE-AlarmLow-7e1a928e-xmpl-4d2b-8c01-782321bc6f66"
}
]
}

Application Auto Scaling creates two alarms in CloudWatch. The first alarm triggers when the utilization
of provisioned concurrency consistently exceeds 70 percent. When this happens, Application Auto
Scaling allocates more provisioned concurrency to reduce utilization. The second alarm triggers when
utilization is consistently less than 63 percent (90 percent of the 70 percent target). When this happens,
Application Auto Scaling reduces the alias's provisioned concurrency.

In the following example, a function scales between a minimum and maximum amount of provisioned
concurrency based on utilization. When the number of open requests increases, Application Auto
Scaling increases provisioned concurrency in large steps until it reaches the configured maximum. The
function continues to scale on standard concurrency until utilization starts to drop. When utilization is
consistently low, Application Auto Scaling decreases provisioned concurrency in smaller periodic steps.

92
 AWS Lambda Developer Guide
Configuring concurrency with the Lambda API

Legend

• Function instances
• Open requests
• Provisioned concurrency
• Standard concurrency

To view your account's concurrency quotas in a Region, use get-account-settings.

aws lambda get-account-settings

You should see the following output:

93
 AWS Lambda Developer Guide
Configuring concurrency with the Lambda API

{
"AccountLimit": {
"TotalCodeSize": 80530636800,
"CodeSizeUnzipped": 262144000,
"CodeSizeZipped": 52428800,
"ConcurrentExecutions": 1000,
"UnreservedConcurrentExecutions": 900
},
"AccountUsage": {
"TotalCodeSize": 174913095,
"FunctionCount": 52
}
}

94
 AWS Lambda Developer Guide
Versions

Lambda function versions

You can use versions to manage the deployment of your functions. For example, you can publish a new
version of a function for beta testing without affecting users of the stable production version. Lambda
creates a new version of your function each time that you publish the function. The new version is a copy
of the unpublished version of the function.

A function version includes the following information:

• The function code and all associated dependencies.

• The Lambda runtime that invokes the function.
• All of the function settings, including the environment variables.
• A unique Amazon Resource Name (ARN) to identify the specific version of the function.

Sections
• Creating function versions (p. 95)
• Managing versions with the Lambda API (p. 95)
• Using versions (p. 96)
• Granting permissions (p. 96)

Creating function versions

You can change the function code and settings only on the unpublished version of a function. When
you publish a version, the code and most of the settings are locked to maintain a consistent experience
for users of that version. For more information about configuring function settings, see Configuring
functions in the console (p. 70).

You can create a function version using the Lambda console.

To create a new function version

1. Open the Functions page on the Lambda console.

2. Choose a function and then choose Versions.
3. On the versions configuration page, choose Publish new version.
4. (Optional) Enter a version description.
5. Choose Publish.

Managing versions with the Lambda API

To publish a version of a function, use the PublishVersion (p. 883) API operation.

The following example publishes a new version of a function. The response returns configuration
information about the new version, including the version number and the function ARN with the version
suffix.

aws lambda publish-version --function-name my-function

You should see the following output:

95
 AWS Lambda Developer Guide
Using versions

"FunctionName": "my-function",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:1",
"Version": "1",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Handler": "function.handler",
"Runtime": "nodejs12.x",
...
}

Using versions
You can reference your Lambda function using either a qualified ARN or an unqualified ARN.

• Qualified ARN – The function ARN with a version suffix. The following example refers to version 42 of
the helloworld function.

arn:aws:lambda:aws-region:acct-id:function:helloworld:42

• Unqualified ARN – The function ARN without a version suffix.

arn:aws:lambda:aws-region:acct-id:function:helloworld

You can use a qualified or an unqualified ARN in all relevant API operations. However, you can't use an
unqualified ARN to create an alias.

If you decide not to publish function versions, you can invoke the function using either the qualified
or unqualified ARN in your event source mapping (p. 148). When you invoke a function using an
unqualified ARN, Lambda implicitly invokes $LATEST.

Lambda publishes a new function version only if the code has never been published or if the code has
changed from the last published version. If there is no change, the function version remains at the last
published version.

The qualified ARN for each Lambda function version is unique. After you publish a version, you can't
change the ARN or the function code.

Granting permissions
You can use a resource-based policy (p. 51) or an identity-based policy (p. 56) to grant access to your
function. The scope of the permission depends on whether you apply the policy to a function or to one
version of a function. For more information about function resource names in policies, see Resources and
conditions for Lambda actions (p. 61).

You can simplify the management of event sources and AWS Identity and Access Management (IAM)
policies by using function aliases. For more information, see Lambda function aliases (p. 97).

96
 AWS Lambda Developer Guide
Aliases

Lambda function aliases

You can create one or more aliases for your Lambda function. A Lambda alias is like a pointer to a
specific function version. Users can access the function version using the alias Amazon Resource Name
(ARN).

Sections
• Creating a function alias (Console) (p. 97)
• Managing aliases with the Lambda API (p. 97)
• Using aliases (p. 98)
• Resource policies (p. 98)
• Alias routing configuration (p. 98)

Creating a function alias (Console)

You can create a function alias using the Lambda console.

To create an alias

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Aliases and then choose Create alias.
4. On the Create alias page, do the following:

a. Enter a Name for the alias.

b. (Optional) Enter a Description for the alias.
c. For Version, choose a function version that you want the alias to point to.
d. (Optional) To configure routing on the alias, expand Weighted alias. For more information, see
Alias routing configuration (p. 98).
e. Choose Save.

Managing aliases with the Lambda API

To create an alias using the AWS Command Line Interface (AWS CLI), use the create-alias command.

aws lambda create-alias --function-name my-function --name alias-name --function-

version version-number --description " "

To change an alias to point a new version of the function, use the update-alias command.

aws lambda update-alias --function-name my-function --name alias-name --function-

version version-number

To delete an alias, use the delete-alias command.

aws lambda delete-alias --function-name my-function --name alias-name

The AWS CLI commands in the preceding steps correspond to the following Lambda API operations:

• CreateAlias (p. 747)

97
 AWS Lambda Developer Guide
Using aliases

• UpdateAlias (p. 912)

• DeleteAlias (p. 775)

Using aliases
Each alias has a unique ARN. An alias can point only to a function version, not to another alias. You can
update an alias to point to a new version of the function.

Event sources such as Amazon Simple Storage Service (Amazon S3) invoke your Lambda function. These
event sources maintain a mapping that identifies the function to invoke when events occur. If you specify
a Lambda function alias in the mapping configuration, you don't need to update the mapping when the
function version changes. For more information, see AWS Lambda event source mappings (p. 148).

In a resource policy, you can grant permissions for event sources to use your Lambda function. If you
specify an alias ARN in the policy, you don't need to update the policy when the function version
changes.

Resource policies
You can use a resource-based policy (p. 51) to give a service, resource, or account access to your function.
The scope of that permission depends on whether you apply it to an alias, a version, or the entire
function. For example, if you use an alias name (such as helloworld:PROD), the permission allows you
to invoke the helloworld function using the alias ARN (helloworld:PROD).

If you attempt to invoke the function without an alias or a specific version, then you get a permission
error. This permission error still occurs even if you attempt to directly invoke the function version
associated with the alias.

For example, the following AWS CLI command grants Amazon S3 permissions to invoke the PROD alias
of the helloworld function when Amazon S3 is acting on behalf of examplebucket.

aws lambda add-permission --function-name helloworld \

--qualifier PROD --statement-id 1 --principal s3.amazonaws.com --action
lambda:InvokeFunction \
--source-arn arn:aws:s3:::examplebucket --source-account 123456789012

For more information about using resource names in policies, see Resources and conditions for Lambda
actions (p. 61).

Alias routing configuration

Use routing configuration on an alias to send a portion of traffic to a second function version. For
example, you can reduce the risk of deploying a new version by configuring the alias to send most of the
traffic to the existing version, and only a small percentage of traffic to the new version.

Note that Lambda uses a simple probabilistic model to distribute the traffic between the two function
versions. At low traffic levels, you might see a high variance between the configured and actual
percentage of traffic on each version. If your function uses provisioned concurrency, you can avoid
spillover invocations (p. 692) by configuring a higher number of provisioned concurrency instances
during the time that alias routing is active.

You can point an alias to a maximum of two Lambda function versions. The versions must meet the
following criteria:

• Both versions must have the same execution role (p. 47).

98
 AWS Lambda Developer Guide
Alias routing configuration

• Both versions must have the same dead-letter queue configuration, or no dead-letter queue
configuration.
• Both versions must be published. The alias cannot point to $LATEST.

To configure routing on an alias

Note
Verify that the function has at least two published versions. To create additional versions, follow
the instructions in Lambda function versions (p. 95).

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Aliases and then choose Create alias.
4. On the Create alias page, do the following:

a. Enter a Name for the alias.

b. (Optional) Enter a Description for the alias.
c. For Version, choose the first function version that you want the alias to point to.
d. Expand Weighted alias.
e. For Additional version, choose the second function version that you want the alias to point to.
f. For Weight (%), enter a weight value for the function. Weight is the percentage of traffic that is
assigned to that version when the alias is invoked. The first version receives the residual weight.
For example, if you specify 10 percent to Additional version, the first version is assigned 90
percent automatically.
g. Choose Save.

Configuring alias routing using CLI

Use the create-alias and update-alias AWS CLI commands to configure the traffic weights
between two function versions. When you create or update the alias, you specify the traffic weight in the
routing-config parameter.

The following example creates a Lambda function alias named routing-alias that points to version 1
of the function. Version 2 of the function receives 3 percent of the traffic. The remaining 97 percent of
traffic is routed to version 1.

aws lambda create-alias --name routing-alias --function-name my-function --function-version

1 \
--routing-config AdditionalVersionWeights={"2"=0.03}

Use the update-alias command to increase the percentage of incoming traffic to version 2. In the
following example, you increase the traffic to 5 percent.

aws lambda update-alias --name routing-alias --function-name my-function \

--routing-config AdditionalVersionWeights={"2"=0.05}

To route all traffic to version 2, use the update-alias command to change the function-version
property to point the alias to version 2. The command also resets the routing configuration.

aws lambda update-alias --name routing-alias --function-name my-function \

--function-version 2 --routing-config AdditionalVersionWeights={}

The AWS CLI commands in the preceding steps correspond to the following Lambda API operations:

99
 AWS Lambda Developer Guide
Alias routing configuration

• CreateAlias (p. 747)

• UpdateAlias (p. 912)

Determining which version has been invoked

When you configure traffic weights between two function versions, there are two ways to determine the
Lambda function version that has been invoked:

• CloudWatch Logs – Lambda automatically emits a START log entry that contains the invoked version
ID to Amazon CloudWatch Logs for every function invocation. The following is an example:

19:44:37 START RequestId: request id Version: $version

For alias invocations, Lambda uses the Executed Version dimension to filter the metric data by the
invoked version. For more information, see Working with AWS Lambda function metrics (p. 692).
• Response payload (synchronous invocations) – Responses to synchronous function invocations
include an x-amz-executed-version header to indicate which function version has been invoked.

100
 AWS Lambda Developer Guide
Creating layers

Creating and sharing Lambda layers

A Lambda layer is a .zip file archive that can contain additional code or data. A layer can contain libraries,
a custom runtime (p. 236), data, or configuration files. Layers promote code sharing and separation of
responsibilities so that you can iterate faster on writing business logic.

You can use layers only with Lambda functions deployed as a .zip file archive (p. 41). For functions
defined as a container image (p. 247), you package your preferred runtime and all code dependencies
when you create the container image. For more information, see Working with Lambda layers and
extensions in container images on the AWS Compute Blog.

You can create layers using the Lambda console, the Lambda API, AWS CloudFormation, or the AWS
Serverless Application Model (AWS SAM). For more information about creating layers with AWS SAM, see
Working with layers in the AWS Serverless Application Model Developer Guide.

Sections
• Creating layer content (p. 101)
• Compiling the .zip file archive for your layer (p. 101)
• Including library dependencies in a layer (p. 102)
• Creating a layer (p. 103)
• Deleting a layer version (p. 104)
• Configuring layer permissions (p. 104)
• Using AWS CloudFormation with layers (p. 105)

Creating layer content

When you create a layer, you must bundle all its content into a .zip file archive. You upload the .zip file
archive to your layer from Amazon Simple Storage Service (Amazon S3) or your local machine. Lambda
extracts the layer contents into the /opt directory when setting up the execution environment for the
function.

Using the AWS CLI

You can create and upload a .zip file for your layer using the Lambda console or the AWS Command Line
Interface (AWS CLI). For language-specific instructions, see the following topics.

• Deploy Node.js Lambda functions with .zip file archives (p. 489)
• Deploy Python Lambda functions with .zip file archives (p. 515)
• Deploy Ruby Lambda functions with .zip file archives (p. 551)
• Deploy Java Lambda functions with .zip or JAR file archives (p. 578)
• Deploy Go Lambda functions with .zip file archives (p. 617)
• Deploy C# Lambda functions with .zip file archives (p. 645)
• Deploy PowerShell Lambda functions with .zip file archives (p. 669)

Compiling the .zip file archive for your layer

You build your layer code into a .zip file archive using the same procedure as you would for a function.
If your layer includes any native code libraries, you must compile and build these libraries using a Linux
development machine so that the binaries are compatible with Amazon Linux (p. 195).

101
 AWS Lambda Developer Guide
Including library dependencies in a layer

One way to ensure that you package libraries correctly for Lambda is to use AWS Cloud9. For more
information, see Using Lambda layers to simplify your development process on the AWS Compute Blog.

Including library dependencies in a layer

For each Lambda runtime (p. 195), the PATH variable includes specific folders in the /opt directory. If
you define the same folder structure in your layer .zip file archive, your function code can access the layer
content without the need to specify the path.

The following table lists the folder paths that each runtime supports.

Layer paths for each Lambda runtime

Runtime Path

Node.js nodejs/node_modules

nodejs/node14/node_modules (NODE_PATH)

Python python

python/lib/python3.8/site-packages(site
directories)

Java java/lib (CLASSPATH)

Ruby ruby/gems/2.5.0 (GEM_PATH)

ruby/lib (RUBYLIB)

All runtimes bin (PATH)

lib (LD_LIBRARY_PATH)

The following examples show how you can structure the folders in your layer .zip archive.

Node.js

Example file structure for the AWS X-Ray SDK for Node.js

xray-sdk.zip
# nodejs/node_modules/aws-xray-sdk

Python

Example file structure for the Pillow library

pillow.zip
# python/PIL
# python/Pillow-5.3.0.dist-info

Ruby

Example file structure for the JSON gem

json.zip

102
 AWS Lambda Developer Guide
Creating a layer

# ruby/gems/2.5.0/
| build_info
| cache
| doc
| extensions
| gems
| # json-2.1.0
# specifications
# json-2.1.0.gemspec

Java

Example file structure for the Jackson JAR file

jackson.zip
# java/lib/jackson-core-2.2.3.jar

All

Example file structure for the jq library

jq.zip
# bin/jq

For more information about path settings in the Lambda execution environment, see Defined runtime
environment variables (p. 80).

Creating a layer
You can create new layers using the Lambda console or the Lambda API.

Layers can have one or more version. When you create a layer, Lambda sets the layer version to version
1. You can configure permissions on an existing layer version, but to update the code or make other
configuration changes, you must create a new version of the layer.

To create a layer (console)

1. Open the Layers page of the Lambda console.

2. Choose Create layer.
3. Under Layer configuration, for Name, enter a name for your layer.
4. (Optional) For Description, enter a description for your layer.
5. To upload your layer code, do one of the following:
• To upload a .zip file from your computer, choose Upload a .zip file. Then, choose Upload to
select your local .zip file.
• To upload a file from Amazon S3, choose Upload a file from Amazon S3. Then, for Amazon S3
link URL, enter a link to the file.
6. (Optional) For Compatible runtimes, choose up to 15 runtimes.
7. (Optional) For License, enter any necessary license information.
8. Choose Create.

To create a layer (API)

103
 AWS Lambda Developer Guide
Deleting a layer version

To create a layer, use the publish-layer-version command with a name, description, .zip file archive, and
list of runtimes (p. 195) that are compatible with the layer. The list of runtimes is optional.

aws lambda publish-layer-version --layer-name my-layer --description "My layer" \

--license-info "MIT" --content S3Bucket=lambda-layers-us-
east-2-123456789012,S3Key=layer.zip \
--compatible-runtimes python3.6 python3.7 python3.8

You should see output similar to the following:

{
"Content": {
"Location": "https://awslambda-us-east-2-layers.s3.us-east-2.amazonaws.com/
snapshots/123456789012/my-layer-4aaa2fbb-ff77-4b0a-ad92-5b78a716a96a?
versionId=27iWyA73cCAYqyH...",
"CodeSha256": "tv9jJO+rPbXUUXuRKi7CwHzKtLDkDRJLB3cC3Z/ouXo=",
"CodeSize": 169
},
"LayerArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer",
"LayerVersionArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer:1",
"Description": "My layer",
"CreatedDate": "2018-11-14T23:03:52.894+0000",
"Version": 1,
"LicenseInfo": "MIT",
"CompatibleRuntimes": [
"python3.6",
"python3.7",
"python3.8"
]
}

Note
Each time that you call publish-layer-version, you create a new version of the layer.

Deleting a layer version

To delete a layer version, use the delete-layer-version command.

aws lambda delete-layer-version --layer-name my-layer --version-number 1

When you delete a layer version, you can no longer configure a Lambda function to use it. However, any
function that already uses the version continues to have access to it. Version numbers are never reused
for a layer name.

Configuring layer permissions

By default, a layer that you create is private to your AWS account. However, you can optionally share the
layer with other accounts or make it public.

To grant layer-usage permission to another account, add a statement to the layer version's permissions
policy using the add-layer-version-permission command. In each statement, you can grant permission
to a single account, all accounts, or an organization.

aws lambda add-layer-version-permission --layer-name xray-sdk-nodejs --statement-id

xaccount \
--action lambda:GetLayerVersion --principal 210987654321 --version-number 1 --output text

104
 AWS Lambda Developer Guide
Using AWS CloudFormation with layers

You should see output similar to the following:

e210ffdc-e901-43b0-824b-5fcd0dd26d16 {"Sid":"xaccount","Effect":"Allow","Principal":
{"AWS":"arn:aws:iam::210987654321:root"},"Action":"lambda:GetLayerVersion","Resource":"arn:aws:lambda:u
east-2:123456789012:layer:xray-sdk-nodejs:1"}

Permissions apply only to a single layer version. Repeat the process each time that you create a new layer
version.

For more examples, see Granting layer access to other accounts (p. 54).

Using AWS CloudFormation with layers

You can use AWS CloudFormation to create a layer and associate the layer with your Lambda function.
The following example template creates a layer named blank-nodejs-lib and attaches the layer to the
Lambda function using the Layers property.

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Description: A Lambda application that calls the Lambda API.
Resources:
function:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: nodejs12.x
CodeUri: function/.
Description: Call the Lambda API
Timeout: 10
# Function's execution role
Policies:
- AWSLambdaBasicExecutionRole
- AWSLambda_ReadOnlyAccess
- AWSXrayWriteOnlyAccess
Tracing: Active
Layers:
- !Ref libs
libs:
Type: AWS::Serverless::LayerVersion
Properties:
LayerName: blank-nodejs-lib
Description: Dependencies for the blank sample app.
ContentUri: lib/.
CompatibleRuntimes:
- nodejs12.x

105
 AWS Lambda Developer Guide
Using layers

Using layers with your Lambda function

A Lambda layer is a .zip file archive that can contain additional code or other content. A layer can contain
libraries, a custom runtime, data, or configuration files. Use layers to reduce deployment package size
and to promote code sharing and separation of responsibilities so that you can iterate faster on writing
business logic.

You can use layers only with Lambda functions deployed as a .zip file archive (p. 41). For a function
defined as a container image (p. 247), you can package your preferred runtime and all code
dependencies when you create the container image. For more information, see Working with Lambda
layers and extensions in container images on the AWS Compute Blog.

Sections
• Configuring a function to use layers (p. 106)
• Accessing the contents of a layer (p. 107)
• Finding layer information (p. 107)
• Updating a layer version that your function uses (p. 108)
• Adding layer permissions (p. 108)
• Using AWS SAM to add a layer to a function (p. 105)
• Sample applications (p. 109)

Configuring a function to use layers

A Lambda function can use up to five layers at a time. The total unzipped size of the function and all
layers cannot exceed the unzipped deployment package size quota of 250 MB. For more information, see
Lambda quotas (p. 44).

If your functions consume a layer that a different AWS account publishes, your functions can continue
to use the layer version after it has been deleted, or after your permission to access the layer is revoked.
However, you cannot create a new function that uses a deleted layer version.

To add layers to your function, use the update-function-configuration command. The following
example adds two layers: one from the same AWS account as the function, and one from a different
account.

aws lambda update-function-configuration --function-name my-function \

--layers arn:aws:lambda:us-east-2:123456789012:layer:my-layer:3
\
arn:aws:lambda:us-east-2:210987654321:layer:their-layer:2

You should see output similar to the following:

{
"FunctionName": "test-layers",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"Runtime": "nodejs12.x",
"Role": "arn:aws:iam::123456789012:role/service-role/lambda-role",
"Layers": [
{
"Arn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer:3",
"CodeSize": 169
},
{
"Arn": "arn:aws:lambda:us-east-2:210987654321:layer:their-layer:2",

106
 AWS Lambda Developer Guide
Accessing the contents of a layer

"CodeSize": 169
}
],
"RevisionId": "81cc64f5-5772-449a-b63e-12330476bcc4",
...
}

To specify the layer versions to use, you must provide the full Amazon Resource Name (ARN) of each
layer version. When you add layers to a function that already has layers, you overwrite the previous list of
layers. Be sure to include all layers every time that you update the layer configuration. Or, to remove all
layers, specify an empty list.

aws lambda update-function-configuration --function-name my-function --layers []

The creator of a layer can delete a version of the layer. If you're using that layer version in a function,
your function continues to run as though the layer version still exists. However, when you update the
layer configuration, you must remove the reference to the deleted version.

Accessing the contents of a layer

When you include a layer in a Lambda function, Lambda extracts the layer's contents into the /opt
directory in the function execution environment. Lambda extracts layers in the order that you specified
them, merging any folders with the same name. If the same file appears in multiple layers, the function
uses the version in the last extracted layer.

Each Lambda runtime (p. 195) adds specific /opt directory folders to the PATH variable. Your function
code can access the layer content without the need to specify the path. For more information about path
settings in the Lambda execution environment, see Defined runtime environment variables (p. 80).

Finding layer information

To find layers in your AWS account that are compatible with your Lambda function's runtime, use the
list-layers command.

aws lambda list-layers --compatible-runtime python3.8

You should see output similar to the following:

{
"Layers": [
{
"LayerName": "my-layer",
"LayerArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-layer",
"LatestMatchingVersion": {
"LayerVersionArn": "arn:aws:lambda:us-east-2:123456789012:layer:my-
layer:2",
"Version": 2,
"Description": "My layer",
"CreatedDate": "2018-11-15T00:37:46.592+0000",
"CompatibleRuntimes": [
"python3.6",
"python3.7",
"python3.8",
]
}
}
]

107
 AWS Lambda Developer Guide
Updating a layer version that your function uses

To list all layers in your account, you can omit the --compatible-runtime option. The details in the
response reflect the latest version of the layer.

You can also get the latest version of a layer using the list-layer-versions command.

aws lambda list-layer-versions --layer-name my-layer --query

'LayerVersions[0].LayerVersionArn

Updating a layer version that your function uses

Layers are versioned, and the content of each layer version is immutable. The layer owner can release a
new layer version to provide updated content.

To add an updated layer version to your function, use the update-function-configuration command.
Use the --layers option with this command to list all of the layer versions that you want to add. If the
function already has layers, the new list overwrites the previous list.

To update only one of the layer versions, you must include the ARNs of the existing layer versions with
the --layers option.

The following procedure assumes that you have packaged the updated layer code into a local file named
layer.zip.

Add an updated layer version to your function

1. (Optional) If the new layer version is not published yet, publish the new version.

aws lambda publish-layer-version --layer-name my-layer --description "My layer" --

license-info "MIT" \
--zip-file "fileb://layer.zip" --compatible-runtimes python3.6 python3.7

2. (Optional) If the function has more than one layer, get the current layer versions associated with the
function.

aws lambda get-function-config --function-name my-function --query 'Layers[*].Arn' --

output yaml

3. Add the new layer version to the function. In the following example command, the function also has
a layer version named other-layer:5:

aws lambda update-function-configuration --function-name my-function \

--layers arn:aws:lambda:us-east-2:123456789012:layer:my-layer:2 \
arn:aws:lambda:us-east-2:123456789012:layer:other-layer:5

Adding layer permissions

To use a Lambda function with a layer, you need permission to call the GetLayerVersion (p. 827) API
operation on the layer version. For functions in your AWS account, you can add this permission from your
user policy (p. 56).

108
 AWS Lambda Developer Guide
Using AWS SAM to add a layer to a function

To use a layer in another account, the owner of that account must grant your account permission in a
resource-based policy (p. 51).

For examples, see Granting layer access to other accounts (p. 54).

Using AWS SAM to add a layer to a function

To automate the creation and mapping of layers in your application, use the AWS Serverless Application
Model (AWS SAM). The AWS::Serverless::LayerVersion resource type creates a layer version that
you can reference from your Lambda function configuration.

Example blank-nodejs/template.yml – Serverless resources

AWSTemplateFormatVersion: '2010-09-09'
Transform: 'AWS::Serverless-2016-10-31'
Description: An AWS Lambda application that calls the Lambda API.
Resources:
function:
Type: AWS::Serverless::Function
Properties:
Handler: index.handler
Runtime: nodejs12.x
CodeUri: function/.
Description: Call the AWS Lambda API
Timeout: 10
# Function's execution role
Policies:
- AWSLambdaBasicExecutionRole
- AWSLambda_ReadOnlyAccess
- AWSXrayWriteOnlyAccess
Tracing: Active
Layers:
- !Ref libs
libs:
Type: AWS::Serverless::LayerVersion
Properties:
LayerName: blank-nodejs-lib
Description: Dependencies for the blank sample app.
ContentUri: lib/.
CompatibleRuntimes:
- nodejs12.x

When you update your dependencies and deploy, AWS SAM creates a new version of the layer and
updates the mapping.

Sample applications
The GitHub repository for this guide provides blank sample applications that demonstrate the use of
layers for dependency management.

• Node.js – blank-nodejs
• Python – blank-python
• Ruby – blank-ruby
• Java – blank-java

For more information about the blank sample app, see Blank function sample application for AWS
Lambda (p. 466). For other samples, see Samples (p. 464).

109
 AWS Lambda Developer Guide
Memory

Configuring Lambda function memory

Lambda allocates CPU power in proportion to the amount of memory configured. Memory is the amount
of memory available to your Lambda function at runtime. You can increase or decrease the memory and
CPU power allocated to your function using the Memory (MB) setting. To configure the memory for your
function, set a value between 128 MB and 10,240 MB in 1-MB increments. At 1,769 MB, a function has
the equivalent of one vCPU (one vCPU-second of credits per second).

This page describes how to update the memory allotted to your function in the Lambda console.

Sections
• Configuring function memory (console) (p. 110)
• Accepting function memory recommendations (console) (p. 110)

Configuring function memory (console)

You can configure the memory of your function in the Lambda console.

To update the memory of a function

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose General configuration
4. Under General configuration, choose Edit.
5. For Memory (MB), set a value from 128 MB to 10,240 MB.
6. Choose Save.

Accepting function memory recommendations

(console)
If you have administrator permissions in AWS Identity and Access Management (IAM), you can opt in
to receive Lambda function memory setting recommendations from AWS Compute Optimizer. For
instructions on opting in to memory recommendations for your account or organization, see Opting in
your account in the AWS Compute Optimizer User Guide.

When you've opted in and your Lambda function meets Compute Optimizer requirements, you can view
and accept function memory recommendations from Compute Optimizer in the Lambda console.

To accept a function memory recommendation

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose General configuration
4. Under General configuration, choose Edit.
5. Under Memory (MB), in the memory alert, choose Update.
6. Choose Save.

110
 AWS Lambda Developer Guide
Network

Configuring a Lambda function to access resources

in a VPC
You can configure a Lambda function to connect to private subnets in a virtual private cloud (VPC) in
your AWS account. Use Amazon Virtual Private Cloud (Amazon VPC) to create a private network for
resources such as databases, cache instances, or internal services. Connect your function to the VPC to
access private resources while the function is running.

When you connect a function to a VPC, Lambda creates an elastic network interface for each subnet in
your function's VPC configuration. This process can take several minutes.

While Lambda creates a network interface, you can't perform additional operations that target the
function, such as creating versions (p. 95) or updating the function's code. For new functions, you can't
invoke the function until its state changes from Pending to Active. For existing functions, you can still
invoke an earlier version while the update is in progress. For more information about function states, see
Monitoring the state of a function with the Lambda API (p. 151).

Multiple functions can share a network interface, if the functions share the same subnet and security
group. Connecting additional functions to a subnet that has an existing Lambda-managed network
interface is much quicker than having Lambda create additional network interfaces. However, if you have
many functions or functions with high network usage, Lambda might still create additional network
interfaces.

If your functions aren't active for a long period of time, Lambda reclaims its network interfaces, and the
functions become Idle. To reactivate an idle function, invoke it. This invocation fails, and the function
enters a Pending state again until a network interface is available.

Lambda functions can't connect directly to a VPC with dedicated instance tenancy. To connect to
resources in a dedicated VPC, peer it to a second VPC with default tenancy.

Sections
• Execution role and user permissions (p. 111)
• Configuring VPC access (console) (p. 112)
• Configuring VPC access (API) (p. 112)
• Using IAM condition keys for VPC settings (p. 113)
• Internet and service access for VPC-connected functions (p. 116)
• VPC tutorials (p. 116)
• Sample VPC configurations (p. 116)

Execution role and user permissions

Lambda uses your function's permissions to create and manage network interfaces. To connect to a VPC,
your function's execution role (p. 47) must have the following permissions:

Execution role permissions

• ec2:CreateNetworkInterface
• ec2:DescribeNetworkInterfaces
• ec2:DeleteNetworkInterface

These permissions are included in the AWS managed policy AWSLambdaVPCAccessExecutionRole.

111
 AWS Lambda Developer Guide
Configuring VPC access (console)

When you configure VPC connectivity, Lambda uses your permissions to verify network resources. To
configure a function to connect to a VPC, your AWS Identity and Access Management (IAM) user needs
the following permissions:

User permissions

• ec2:DescribeSecurityGroups
• ec2:DescribeSubnets
• ec2:DescribeVpcs

Configuring VPC access (console)

If your IAM permissions (p. 113) allow you only to create Lambda functions that connect to your VPC,
you must configure the VPC when you create the function. If your IAM permissions allow you to create
functions that aren't connected to your VPC, you can add the VPC configuration after you create the
function.

To configure a VPC when you create a function

1. Open the Functions page on the Lambda console.

2. Choose Create function.
3. Under Basic information, for Function name, enter a name for your function.
4. Expand Advanced settings.
5. Under Network, choose a VPC for your function to access.
6. Choose subnets and security groups. When you choose a security group, the console displays the
inbound and outbound rules for that security group.
Note
To access private resources, connect your function to private subnets. If your function needs
internet access, use network address translation (NAT) (p. 116). Connecting a function to a
public subnet doesn't give it internet access or a public IP address.
7. Choose Create function.

To configure a VPC for an existing function

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose VPC.
4. Under VPC, choose Edit.
5. Choose a VPC, subnets, and security groups.
Note
To access private resources, connect your function to private subnets. If your function needs
internet access, use network address translation (NAT) (p. 116). Connecting a function to a
public subnet doesn't give it internet access or a public IP address.
6. Choose Save.

Configuring VPC access (API)

To connect a Lambda function to a VPC, you can use the following API operations:

• CreateFunction (p. 763)

112
 AWS Lambda Developer Guide
Using IAM condition keys for VPC settings

• UpdateFunctionConfiguration (p. 936)

To create a function and connect it to a VPC using the AWS Command Line Interface (AWS CLI), you can
use the create-function command with the vpc-config option. The following example creates a
function with a connection to a VPC with two subnets and one security group.

aws lambda create-function --function-name my-function \

--runtime nodejs12.x --handler index.js --zip-file fileb://function.zip \
--role arn:aws:iam::123456789012:role/lambda-role \
--vpc-config
SubnetIds=subnet-071f712345678e7c8,subnet-07fd123456788a036,SecurityGroupIds=sg-085912345678492fb

To connect an existing function to a VPC, use the update-function-configuration command with

the vpc-config option.

aws lambda update-function-configuration --function-name my-function \

--vpc-config
SubnetIds=subnet-071f712345678e7c8,subnet-07fd123456788a036,SecurityGroupIds=sg-085912345678492fb

To disconnect your function from a VPC, update the function configuration with an empty list of subnets
and security groups.

aws lambda update-function-configuration --function-name my-function \

--vpc-config SubnetIds=[],SecurityGroupIds=[]

Using IAM condition keys for VPC settings

You can use Lambda-specific condition keys for VPC settings to provide additional permission controls
for your Lambda functions. For example, you can require that all functions in your organization are
connected to a VPC. You can also specify the subnets and security groups that the function's users can
and can't use.

Lambda supports the following condition keys in IAM policies:

• lambda:VpcIds – Allow or deny one or more VPCs.

• lambda:SubnetIds – Allow or deny one or more subnets.
• lambda:SecurityGroupIds – Allow or deny one or more security groups.

The Lambda API operations CreateFunction (p. 763) and UpdateFunctionConfiguration (p. 936)
support these condition keys. For more information about using condition keys in IAM policies, see IAM
JSON Policy Elements: Condition in the IAM User Guide.
Tip
If your function already includes a VPC configuration from a previous API request, you can send
an UpdateFunctionConfiguration request without the VPC configuration.

Example policies with condition keys for VPC settings

The following examples demonstrate how to use condition keys for VPC settings. After you create a
policy statement with the desired restrictions, append the policy statement for the target IAM user or
role.

Ensure that users deploy only VPC-connected functions

To ensure that all users deploy only VPC-connected functions, you can deny function create and update
operations that don't include a valid VPC ID.

113
 AWS Lambda Developer Guide
Using IAM condition keys for VPC settings

Note that VPC ID is not an input parameter to the CreateFunction or

UpdateFunctionConfiguration request. Lambda retrieves the VPC ID value based on the subnet and
security group parameters.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EnforceVPCFunction",
"Action": [
"lambda:CreateFunction",
"lambda:UpdateFunctionConfiguration"
],
"Effect": "Deny",
"Resource": "*",
"Condition": {
"Null": {
"lambda:VpcIds": "true"
}
}
}
]
}

Deny users access to specific VPCs, subnets, or security groups

To deny users access to specific VPCs, use StringEquals to check the value of the lambda:VpcIds
condition. The following example denies users access to vpc-1 and vpc-2.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EnforceOutOfVPC",
"Action": [
"lambda:CreateFunction",
"lambda:UpdateFunctionConfiguration"
],
"Effect": "Deny",
"Resource": "*",
"Condition": {
"StringEquals": {
"lambda:VpcIds": ["vpc-1", "vpc-2"]
}
}
}

To deny users access to specific subnets, use StringEquals to check the value of the
lambda:SubnetIds condition. The following example denies users access to subnet-1 and subnet-2.

{
"Sid": "EnforceOutOfSubnet",
"Action": [
"lambda:CreateFunction",
"lambda:UpdateFunctionConfiguration"
],
"Effect": "Deny",
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {

114
 AWS Lambda Developer Guide
Using IAM condition keys for VPC settings

"lambda:SubnetIds": ["subnet-1", "subnet-2"]

}
}
}

To deny users access to specific security groups, use StringEquals to check the value of the
lambda:SecurityGroupIds condition. The following example denies users access to sg-1 and sg-2.

{
"Sid": "EnforceOutOfSecurityGroups",
"Action": [
"lambda:CreateFunction",
"lambda:UpdateFunctionConfiguration"
],
"Effect": "Deny",
"Resource": "*",
"Condition": {
"ForAnyValue:StringEquals": {
"lambda:SecurityGroupIds": ["sg-1", "sg-2"]
}
}
}
]
}

Allow users to create and update functions with specific VPC settings
To allow users to access specific VPCs, use StringEquals to check the value of the lambda:VpcIds
condition. The following example allows users to access vpc-1 and vpc-2.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EnforceStayInSpecificVpc",
"Action": [
"lambda:CreateFunction",
"lambda:UpdateFunctionConfiguration"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"StringEquals": {
"lambda:VpcIds": ["vpc-1", "vpc-2"]
}
}
}

To allow users to access specific subnets, use StringEquals to check the value of the
lambda:SubnetIds condition. The following example allows users to access subnet-1 and subnet-2.

{
"Sid": "EnforceStayInSpecificSubnets",
"Action": [
"lambda:CreateFunction",
"lambda:UpdateFunctionConfiguration"
],
"Effect": "Allow",

115
 AWS Lambda Developer Guide
Internet and service access for VPC-connected functions

"Resource": "*",
"Condition": {
"ForAllValues:StringEquals": {
"lambda:SubnetIds": ["subnet-1", "subnet-2"]
}
}
}

To allow users to access specific security groups, use StringEquals to check the value of the
lambda:SecurityGroupIds condition. The following example allows users to access sg-1 and sg-2.

{
"Sid": "EnforceStayInSpecificSecurityGroup",
"Action": [
"lambda:CreateFunction",
"lambda:UpdateFunctionConfiguration"
],
"Effect": "Allow",
"Resource": "*",
"Condition": {
"ForAllValues:StringEquals": {
"lambda:SecurityGroupIds": ["sg-1", "sg-2"]
}
}
}
]
}

Internet and service access for VPC-connected

functions
By default, Lambda runs your functions in a secure VPC with access to AWS services and the internet.
Lambda owns this VPC, which isn't connected to your account's default VPC. When you connect a
function to a VPC in your account, the function can't access the internet unless your VPC provides access.
Note
Several AWS services offer VPC endpoints. You can use VPC endpoints to connect to AWS
services from within a VPC without internet access.

Internet access from a private subnet requires network address translation (NAT). To give your function
access to the internet, route outbound traffic to a NAT gateway in a public subnet. The NAT gateway
has a public IP address and can connect to the internet through the VPC's internet gateway. For more
information, see How do I give internet access to my Lambda function in a VPC?

VPC tutorials
In the following tutorials, you connect a Lambda function to resources in your VPC.

• Tutorial: Configuring a Lambda function to access Amazon RDS in an Amazon VPC (p. 401)
• Tutorial: Configuring a Lambda function to access Amazon ElastiCache in an Amazon VPC (p. 345)

Sample VPC configurations

You can use the following sample AWS CloudFormation templates to create VPC configurations to use
with Lambda functions. There are two templates available in this guide's GitHub repository:

116
 AWS Lambda Developer Guide
Sample VPC configurations

• vpc-private.yaml – A VPC with two private subnets and VPC endpoints for Amazon Simple Storage
Service (Amazon S3) and Amazon DynamoDB. Use this template to create a VPC for functions that
don't need internet access. This configuration supports use of Amazon S3 and DynamoDB with the
AWS SDKs, and access to database resources in the same VPC over a local network connection.
• vpc-privatepublic.yaml – A VPC with two private subnets, VPC endpoints, a public subnet with a NAT
gateway, and an internet gateway. Internet-bound traffic from functions in the private subnets is
routed to the NAT gateway using a route table.

To create a VPC using a template, on the AWS CloudFormation console Stacks page, choose Create stack,
and then follow the instructions in the Create stack wizard.

117
 AWS Lambda Developer Guide
Interface VPC endpoints

Configuring interface VPC endpoints for Lambda

If you use Amazon Virtual Private Cloud (Amazon VPC) to host your AWS resources, you can establish a
connection between your VPC and Lambda. You can use this connection to invoke your Lambda function
without crossing the public internet.

To establish a private connection between your VPC and Lambda, create an interface VPC endpoint.
Interface endpoints are powered by AWS PrivateLink, which enables you to privately access Lambda APIs
without an internet gateway, NAT device, VPN connection, or AWS Direct Connect connection. Instances
in your VPC don't need public IP addresses to communicate with Lambda APIs. Traffic between your VPC
and Lambda does not leave the AWS network.

Each interface endpoint is represented by one or more elastic network interfaces in your subnets. A
network interface provides a private IP address that serves as an entry point for traffic to Lambda.

Sections
• Considerations for Lambda interface endpoints (p. 118)
• Creating an interface endpoint for Lambda (p. 119)
• Creating an interface endpoint policy for Lambda (p. 119)

Considerations for Lambda interface endpoints

Before you set up an interface endpoint for Lambda, be sure to review Interface endpoint properties and
limitations in the Amazon VPC User Guide.

You can call any of the Lambda API operations from your VPC. For example, you can invoke the Lambda
function by calling the Invoke API from within your VPC. For the full list of Lambda APIs, see Actions in
the Lambda API reference.

Keep-alive for persistent connections

Lambda purges idle connections over time, so you must use a keep-alive directive to maintain persistent
connections. Attempting to reuse an idle connection when invoking a function results in a connection
error. To maintain your persistent connection, use the keep-alive directive associated with your runtime.
For an example, see Reusing Connections with Keep-Alive in Node.js in the AWS SDK for JavaScript
Developer Guide.

Billing Considerations
There is no additional cost to access a Lambda function through an interface endpoint. For more Lambda
pricing information, see AWS Lambda Pricing.

Standard pricing for AWS PrivateLink applies to interface endpoints for Lambda. Your AWS account
is billed for every hour an interface endpoint is provisioned in each Availability Zone and for data
processed through the interface endpoint. For more interface endpoint pricing information, see AWS
PrivateLink pricing.

VPC Peering Considerations

You can connect other VPCs to the VPC with interface endpoints using VPC peering. VPC peering is
a networking connection between two VPCs. You can establish a VPC peering connection between
your own two VPCs, or with a VPC in another AWS account. The VPCs can also be in two different AWS
Regions.

118
 AWS Lambda Developer Guide
Creating an interface endpoint for Lambda

Traffic between peered VPCs stays on the AWS network and does not traverse the public internet.
Once VPCs are peered, resources like Amazon Elastic Compute Cloud (Amazon EC2) instances, Amazon
Relational Database Service (Amazon RDS) instances, or VPC-enabled Lambda functions in both VPCs can
access the Lambda API through interface endpoints created in the one of the VPCs.

Creating an interface endpoint for Lambda

You can create an interface endpoint for Lambda using either the Amazon VPC console or the AWS
Command Line Interface (AWS CLI). For more information, see Creating an interface endpoint in the
Amazon VPC User Guide.

To create an interface endpoint for Lambda (console)

1. Open the Endpoints page of the Amazon VPC console.

2. Choose Create Endpoint.
3. For Service category, verify that AWS services is selected.
4. For Service Name, choose com.amazonaws.region.lambda. Verify that the Type is Interface.
5. Choose a VPC and subnets.
6. To enable private DNS for the interface endpoint, select the Enable DNS Name check box.
7. For Security group, choose one or more security groups.
8. Choose Create endpoint.

To use the private DNS option, you must set the enableDnsHostnames and
enableDnsSupportattributes of your VPC. For more information, see Viewing and updating
DNS support for your VPC in the Amazon VPC User Guide. If you enable private DNS for the interface
endpoint, you can make API requests to Lambda using its default DNS name for the Region, for example,
lambda.us-east-1.amazonaws.com. For more service endpoints, see Service endpoints and quotas in
the AWS General Reference.

For more information, see Accessing a service through an interface endpoint in the Amazon VPC User
Guide.

For information about creating and configuring an endpoint using AWS CloudFormation, see the
AWS::EC2::VPCEndpoint resource in the AWS CloudFormation User Guide.

To create an interface endpoint for Lambda (AWS CLI)

Use the create-vpc-endpoint command and specify the VPC ID, VPC endpoint type (interface),
service name, subnets that will use the endpoint, and security groups to associate with the endpoint's
network interfaces. For example:

aws ec2 create-vpc-endpoint --vpc-id vpc-ec43eb89 --vpc-endpoint-type Interface --service-

name \
com.amazonaws.us-east-1.lambda --subnet-id subnet-abababab --security-group-id
sg-1a2b3c4d

Creating an interface endpoint policy for Lambda

To control who can use your interface endpoint and which Lambda functions the user can access, you can
attach an endpoint policy to your endpoint. The policy specifies the following information:

• The principal that can perform actions.

119
 AWS Lambda Developer Guide
Creating an interface endpoint policy for Lambda

• The actions that the principal can perform.

• The resources on which the principal can perform actions.

For more information, see Controlling access to services with VPC endpoints in the Amazon VPC User
Guide.

Example: Interface endpoint policy for Lambda actions

The following is an example of an endpoint policy for Lambda. When attached to an endpoint, this policy
allows user MyUser to invoke the function my-function.

{
"Statement":[
{
"Principal":
{
"AWS": "arn:aws:iam::123412341234:user/MyUser"
},
"Effect":"Allow",
"Action":[
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:us-east-2:123456789012:function:my-function”
]
}
]
}

120
 AWS Lambda Developer Guide
Database

Configuring database access for a Lambda

function
You can create an Amazon RDS Proxy database proxy for your function. A database proxy manages a
pool of database connections and relays queries from a function. This enables a function to reach high
concurrency (p. 31) levels without exhausting database connections.

Sections
• Creating a database proxy (console) (p. 121)
• Using the function's permissions for authentication (p. 122)
• Sample application (p. 122)

Creating a database proxy (console)

You can use the Lambda console to create an Amazon RDS Proxy database proxy.

To create a database proxy

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose Database proxies.
4. Choose Add database proxy.
5. Configure the following options.

• Proxy identifier – The name of the proxy.

• RDS DB instance – A supported MySQL or PostgreSQL DB instance or cluster.
• Secret – A Secrets Manager secret with the database user name and password.

Example secret

{
"username": "admin",
"password": "e2abcecxmpldc897"
}

• IAM role – An IAM role with permission to use the secret, and a trust policy that allows Amazon
RDS to assume the role.
• Authentication – The authentication and authorization method for connecting to the proxy from
your function code.
6. Choose Add.

Pricing
Amazon RDS charges a hourly price for proxies that is determined by the instance size of your
database. For details, see RDS Proxy pricing.

Proxy creation takes a few minutes. When the proxy is available, configure your function to connect to
the proxy endpoint instead of the database endpoint.

Standard Amazon RDS Proxy pricing applies. For more information, see Managing connections with the
Amazon RDS Proxy in the Amazon Aurora User Guide.

121
 AWS Lambda Developer Guide
Using the function's permissions for authentication

Using the function's permissions for authentication

By default, you can connect to a proxy with the same username and password that it uses to connect to
the database. The only difference in your function code is the endpoint that the database client connects
to. The drawback of this method is that you must expose the password to your function code, either by
configuring it in a secure environment variable or by retrieving it from Secrets Manager.

You can create a database proxy that uses the function's IAM credentials for authentication and
authorization instead of a password. To use the function's permissions to connect to the proxy, set
Authentication to Execution role.

The Lambda console adds the required permission (rds-db:connect) to the execution role. You can
then use the AWS SDK to generate a token that allows it to connect to the proxy. The following example
shows how to configure a database connection with the mysql2 library in Node.js.

Example dbadmin/index-iam.js – AWS SDK signer

const signer = new AWS.RDS.Signer({

region: region,
hostname: host,
port: sqlport,
username: username
})

exports.handler = async (event) => {

let connectionConfig = {
host : host,
user : username,
database : database,
ssl: 'Amazon RDS',
authPlugins: { mysql_clear_password: () => () => signer.getAuthToken() }
}
var connection = mysql.createConnection(connectionConfig)
var query = event.query
var result
connection.connect()
}

For more information, see IAM database authentication in the Amazon RDS User Guide.

Sample application
Sample applications that demonstrate the use of Lambda with an Amazon RDS database are available in
this guide's GitHub repository. There are two applications:

• RDS MySQL – The AWS CloudFormation template template-vpcrds.yml creates a MySQL 5.7
database in a private VPC. In the sample application, a Lambda function proxies queries to the
database. The function and database templates both use Secrets Manager to access database
credentials.

122
 AWS Lambda Developer Guide
Sample application

• List Manager – A processor function reads events from a Kinesis stream. It uses the data from the
events to update DynamoDB tables, and stores a copy of the event in a MySQL database.

123
AWS Lambda Developer Guide
Sample application

124
 AWS Lambda Developer Guide
Sample application

To use the sample applications, follow the instructions in the GitHub repository: RDS MySQL, List
Manager.

125
 AWS Lambda Developer Guide
File system

Configuring file system access for Lambda

functions
You can configure a function to mount an Amazon Elastic File System (Amazon EFS) file system to a local
directory. With Amazon EFS, your function code can access and modify shared resources safely and at
high concurrency.

Sections
• Connecting to a file system (console) (p. 126)
• Configuring a file system and access point (p. 126)
• Execution role and user permissions (p. 127)
• Configuring file system access with the Lambda API (p. 128)
• AWS CloudFormation and AWS SAM (p. 128)
• Sample applications (p. 129)

Connecting to a file system (console)

A function connects to a file system over the local network in a VPC. The subnets that your function
connects to can be the same subnets that contain mount points for your file system, or subnets in the
same Availability Zone that can route NFS traffic (port 2049) to the file system.
Note
If your function is not already connected to a VPC, see Configuring a Lambda function to access
resources in a VPC (p. 111).

To configure file system access

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose File systems.
4. Under File system, choose Add file system.
5. Configure the following properties:

• EFS file system – The access point for a file system in the same VPC.
• Local mount path – The location where the file system is mounted on the Lambda function,
starting with /mnt/.

Pricing
Amazon EFS charges for storage and throughput, with rates that vary by storage class. For
details, see Amazon EFS pricing.
Lambda charges for data transfer between VPCs. This only applies if your function's VPC is
peered to another VPC with a file system. The rates are the same as for Amazon EC2 data
transfer between VPCs in the same Region. For details, see Lambda pricing.

For more information about Lambda's integration with Amazon EFS, see Using Amazon EFS with
Lambda (p. 351).

Configuring a file system and access point

Create a file system in Amazon EFS with a mount target in every Availability Zone that your function
connects to. For performance and resilience, use at least two Availability Zones. For example, in a simple

126
 AWS Lambda Developer Guide
Execution role and user permissions

configuration you could have a VPC with two private subnets in separate Availability Zones. The function
connects to both subnets and a mount target is available in each. Ensure that NFS traffic (port 2049) is
allowed by the security groups used by the function and mount targets.
Note
When you create a file system, you choose a performance mode that can't be changed later.
General purpose mode has lower latency, and Max I/O mode supports a higher maximum
throughput and IOPS. For help choosing, see Amazon EFS performance in the Amazon Elastic
File System User Guide.

An access point connects each instance of the function to the right mount target for the Availability Zone
it connects to. For best performance, create an access point with a non-root path, and limit the number
of files that you create in each directory. User and owner IDs are required, but they don't need to have a
specific value. The following example creates a directory named my-function on the file system and
sets the owner ID to 1001 with standard directory permissions (755).

Example access point configuration

• Name – files
• User ID – 1001
• Group ID – 1001
• Path – /my-function
• Permissions – 755
• Owner user ID – 1001
• Group user ID – 1001

When a function uses the access point, it is given user ID 1001 and has full access to the directory.

For more information, see the following topics in the Amazon Elastic File System User Guide:

• Creating resources for Amazon EFS

• Working with users, groups, and permissions

Execution role and user permissions

Lambda uses your function's permissions to mount file systems. To connect to a file system, your
function's execution role must have the following permissions in addition to the permissions required to
connect to the file system's VPC (p. 111):

Execution role permissions

• elasticfilesystem:ClientMount
• elasticfilesystem:ClientWrite (not required for read-only connections)

These permissions are included in the AmazonElasticFileSystemClientReadWriteAccess managed policy.

When you configure a file system, Lambda uses your permissions to verify mount targets. To configure a
function to connect to a file system, your IAM user needs the following permissions:

User permissions

• elasticfilesystem:DescribeMountTargets

127
 AWS Lambda Developer Guide
Configuring file system access with the Lambda API

Configuring file system access with the Lambda API

Use the following API operations to connect your Lambda function to a file system:

• CreateFunction (p. 763)

• UpdateFunctionConfiguration (p. 936)

To connect a function to a file system, use the update-function-configuration command. The

following example connects a function named my-function to a file system with ARN of an access
point.

ARN=arn:aws:elasticfilesystem:us-east-2:123456789012:access-point/fsap-015cxmplb72b405fd
aws lambda update-function-configuration --function-name my-function \
--fs-config FileSystemArn=$ARN,LocalMountPath=/mnt/efs0

You can get the ARN of a file system's access point with the describe-access-points command.

aws efs describe-access-points

You should see the following output:

{
"AccessPoints": [
{
"ClientToken": "console-aa50c1fd-xmpl-48b5-91ce-57b27a3b1017",
"Name": "lambda-ap",
"Tags": [
{
"Key": "Name",
"Value": "lambda-ap"
}
],
"AccessPointId": "fsap-015cxmplb72b405fd",
"AccessPointArn": "arn:aws:elasticfilesystem:us-east-2:123456789012:access-
point/fsap-015cxmplb72b405fd",
"FileSystemId": "fs-aea3xmpl",
"RootDirectory": {
"Path": "/"
},
"OwnerId": "123456789012",
"LifeCycleState": "available"
}
]
}

AWS CloudFormation and AWS SAM

You can use AWS CloudFormation and the AWS Serverless Application Model (AWS SAM) to
automate the creation of Lambda applications. To enable a file system connection on an AWS SAM
AWS::Serverless::Function resource, use the FileSystemConfigs property.

Example template.yml – File system configuration

Resources:
VPC:
Type: AWS::EC2::VPC
Properties:

128
 AWS Lambda Developer Guide
Sample applications

CidrBlock: 10.0.0.0/16
Subnet1:
Type: AWS::EC2::Subnet
Properties:
VpcId:
Ref: VPC
CidrBlock: 10.0.1.0/24
AvailabilityZone: "eu-central-1a"
EfsSecurityGroup:
Type: AWS::EC2::SecurityGroup
Properties:
VpcId:
Ref: VPC
GroupDescription: "mnt target sg"
SecurityGroupEgress:
- IpProtocol: -1
CidrIp: "0.0.0.0/0"
FileSystem:
Type: AWS::EFS::FileSystem
Properties:
PerformanceMode: generalPurpose
MountTarget1:
Type: AWS::EFS::MountTarget
Properties:
FileSystemId:
Ref: FileSystem
SubnetId:
Ref: Subnet1
SecurityGroups:
- Ref: EfsSecurityGroup
MyFunctionWithEfs:
Type: AWS::Serverless::Function
Properties:
CodeUri: function/.
Description: Use a file system.
FileSystemConfigs:
-
Arn: !Sub
- "arn:aws:elasticfilesystem:eu-central-1:123456789101:access-point/
fsap-015cxmplb72b405fd"
LocalMountPath: "/mnt/efs0"
DependsOn: "MountTarget1"

You must add the DependsOn to ensure that the mount targets are fully created before the Lambda runs
for the first time.

For the AWS CloudFormation AWS::Lambda::Function type, the property name and fields are the
same. For more information, see Using AWS Lambda with AWS CloudFormation (p. 303).

Sample applications
The GitHub repository for this guide includes a sample application that demonstrates the use of Amazon
EFS with a Lambda function.

• efs-nodejs – A function that uses an Amazon EFS file system in a Amazon VPC. This sample includes a
VPC, file system, mount targets, and access point configured for use with Lambda.

129
 AWS Lambda Developer Guide
Code signing

Configuring code signing for AWS Lambda

Code signing for AWS Lambda helps to ensure that only trusted code runs in your Lambda functions.
When you enable code signing for a function, Lambda checks every code deployment and verifies that
the code package is signed by a trusted source.
Note
Functions defined as container images do not support code signing.

To verify code integrity, use AWS Signer to create digitally signed code packages for functions and
layers. When a user attempts to deploy a code package, Lambda performs validation checks on the code
package before accepting the deployment. Because code signing validation checks run at deployment
time, there is no performance impact on function execution.

You also use AWS Signer to create signing profiles. You use a signing profile to create the signed code
package. Use AWS Identity and Access Management (IAM) to control who can sign code packages and
create signing profiles. For more information, see Authentication and Access Control in the AWS Signer
Developer Guide.

To enable code signing for a function, you create a code signing configuration and attach it to the
function. A code signing configuration defines a list of allowed signing profiles and the policy action to
take if any of the validation checks fail.

Lambda layers follow the same signed code package format as function code packages. When you add a
layer to a function that has code signing enabled, Lambda checks that the layer is signed by an allowed
signing profile. When you enable code signing for a function, all layers that are added to the function
must also be signed by one of the allowed signing profiles.

Use IAM to control who can create code signing configurations. Typically, you allow only specific
administrative users to have this ability. Additionally, you can set up IAM policies to enforce that
developers only create functions that have code signing enabled.

You can configure code signing to log changes to AWS CloudTrail. Successful and blocked deployments
to functions are logged to CloudTrail with information about the signature and validation checks.

You can configure code signing for your functions using the Lambda console, the AWS Command Line
Interface (AWS CLI), AWS CloudFormation, and the AWS Serverless Application Model (AWS SAM).

There is no additional charge for using AWS Signer or code signing for AWS Lambda.

Sections
• Signature validation (p. 130)
• Configuration prerequisites (p. 131)
• Creating code signing configurations (p. 131)
• Updating a code signing configuration (p. 131)
• Deleting a code signing configuration (p. 132)
• Enabling code signing for a function (p. 132)
• Configuring IAM policies (p. 132)
• Configuring code signing with the Lambda API (p. 133)

Signature validation
Lambda performs the following validation checks when you deploy a signed code package to your
function:

130
 AWS Lambda Developer Guide
Configuration prerequisites

1. Integrity – Validates that the code package has not been modified since it was signed. Lambda
compares the hash of the package with the hash from the signature.
2. Expiry – Validates that the signature of the code package has not expired.
3. Mismatch – Validates that the code package is signed with one of the allowed signing profiles for the
Lambda function. A mismatch also occurs if a signature is not present.
4. Revocation – Validates that the signature of the code package has not been revoked.

The signature validation policy defined in the code signing configuration determines which of the
following actions Lambda takes if any of the validation checks fail:

• Warn – Lambda allows the deployment of the code package, but issues a warning. Lambda issues a
new Amazon CloudWatch metric and also stores the warning in the CloudTrail log.
• Enforce – Lambda issues a warning (the same as for the Warn action) and blocks the deployment of
the code package.

You can configure the policy for the expiry, mismatch, and revocation validation checks. Note that you
cannot configure a policy for the integrity check. If the integrity check fails, Lambda blocks deployment.

Configuration prerequisites
Before you can configure code signing for a Lambda function, use AWS Signer to do the following:

• Create one or more signing profiles.

• Use a signing profile to create a signed code package for your function.

For more information, see Creating Signing Profiles (Console) in the AWS Signer Developer Guide.

Creating code signing configurations

A code signing configuration defines a list of allowed signing profiles and the signature validation policy.

To create a code signing configuration (console)

1. Open the Code signing configurations page of the Lambda console.

2. Choose Create configuration.
3. For Description, enter a descriptive name for the configuration.
4. Under Signing profiles, add up to 20 signing profiles to the configuration.

a. For Signing profile version ARN, choose a profile version's Amazon Resource Name (ARN), or
enter the ARN.
b. To add an additional signing profile, choose Add signing profiles.
5. Under Signature validation policy, choose Warn or Enforce.
6. Choose Create configuration.

Updating a code signing configuration

When you update a code signing configuration, the changes impact the future deployments of functions
that have the code signing configuration attached.

131
 AWS Lambda Developer Guide
Deleting a code signing configuration

To update a code signing configuration (console)

1. Open the Code signing configurations page of the Lambda console.

2. Select a code signing configuration to update, and then choose Edit.
3. For Description, enter a descriptive name for the configuration.
4. Under Signing profiles, add up to 20 signing profiles to the configuration.

a. For Signing profile version ARN, choose a profile version's Amazon Resource Name (ARN), or
enter the ARN.
b. To add an additional signing profile, choose Add signing profiles.
5. Under Signature validation policy, choose Warn or Enforce.
6. Choose Save changes.

Deleting a code signing configuration

You can delete a code signing configuration only if no functions are using it.

To delete a code signing configuration (console)

1. Open the Code signing configurations page of the Lambda console.

2. Select a code signing configuration to delete, and then choose Delete.
3. To confirm, choose Delete again.

Enabling code signing for a function

To enable code signing for a function, you associate a code signing configuration with the function.

To associate a code signing configuration with a function (console)

1. Open the Functions page on the Lambda console.

2. Choose the function for which you want to enable code signing.
3. Under Code signing configuration, choose Edit.
4. In Edit code signing, choose a code signing configuration for this function.
5. Choose Save.

Configuring IAM policies

To grant permission for a user to access the code signing API operations (p. 133), attach one or more
policy statements to the user policy. For more information about user policies, see Identity-based IAM
policies for Lambda (p. 56).

The following example policy statement grants permission to create, update, and retrieve code signing
configurations.

{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"lambda:CreateCodeSigningConfig",

132
 AWS Lambda Developer Guide
Configuring code signing with the Lambda API

"lambda:UpdateCodeSigningConfig",
"lambda:GetCodeSigningConfig"
],
"Resource": "*"
}
]
}

Administrators can use the CodeSigningConfigArn condition key to specify the code signing
configurations that developers must use to create or update your functions.

The following example policy statement grants permission to create a function. The policy statement
includes a lambda:CodeSigningConfigArn condition to specify the allowed code signing
configuration. Lambda blocks any CreateFunction API request if its CodeSigningConfigArn
parameter is missing or does not match the value in the condition.

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "AllowReferencingCodeSigningConfig",
"Effect": "Allow",
"Action": [
"lambda:CreateFunction",
],
"Resource": "*",
"Condition": {
"StringEquals": {
"lambda:CodeSigningConfigArn":
“arn:aws:lambda:us-west-2:123456789012:code-signing-
config:csc-0d4518bd353a0a7c6”
}
}
}
]
}

Configuring code signing with the Lambda API

To manage code signing configurations with the AWS CLI or AWS SDK, use the following API operations:

• ListCodeSigningConfigs
• CreateCodeSigningConfig
• GetCodeSigningConfig
• UpdateCodeSigningConfig
• DeleteCodeSigningConfig

To manage the code signing configuration for a function, use the following API operations:

• CreateFunction (p. 763)

• GetFunctionCodeSigningConfig
• PutFunctionCodeSigningConfig
• DeleteFunctionCodeSigningConfig
• ListFunctionsByCodeSigningConfig

133
 AWS Lambda Developer Guide
Tags

Tagging Lambda Functions

You can tag Lambda functions to organize them by owner, project or department. Tags are freeform
key-value pairs that are supported across AWS services for use in filtering resources and adding detail to
billing reports.

Sections
• Adding tags to a function (console) (p. 134)
• Using tags to filter functions (console) (p. 134)
• Using Tags with the AWS CLI (p. 135)
• Tag Key and Value Requirements (p. 136)

Adding tags to a function (console)

To add tags to a function

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose Tags.
4. Under Tags, choose Manage tags.
5. Enter a key and value. To add additional tags, choose Add new tag.

6. Choose Save.

Using tags to filter functions (console)

You can filter functions based on the presence or value of a tag with the Lambda console or with the
AWS Resource Groups API. Tags apply at the function level, not to versions or aliases. Tags are not part of
the version-specific configuration that is snapshotted when you publish a version.

To filter functions with tags

1. Open the Functions page on the Lambda console.

2. Click within the search bar to see a list of function attributes and tag keys.

134
 AWS Lambda Developer Guide
Using Tags with the AWS CLI

3. Choose a tag key to see a list of values that are in-use in the current region.
4. Choose a value to see functions with that value, or choose (all values) to see all functions that have
a tag with that key.

The search bar also supports searching for tag keys. Type tag to see just a list of tag keys, or start typing
the name of a key to find it in the list.

With AWS Billing and Cost Management, you can use tags to customize billing reports and create
cost-allocation reports. For more information, see see Monthly Cost Allocation Report and Using Cost
Allocation Tags in the AWS Billing and Cost Management User Guide.

Using Tags with the AWS CLI

When you create a new Lambda function, you can include tags with the --tags option.

aws lambda create-function --function-name my-function

--handler index.js --runtime nodejs12.x \
--role arn:aws:iam::123456789012:role/lambda-role \
--tags Department=Marketing,CostCenter=1234ABCD

135
 AWS Lambda Developer Guide
Tag Key and Value Requirements

To add tags to an existing function, use the tag-resource command.

aws lambda tag-resource \

--resource arn:aws:lambda:us-east-2:123456789012:function:my-function \
--tags Department=Marketing,CostCenter=1234ABCD

To remove tags, use the untag-resource command.

aws lambda untag-resource --resource function arn \

--tag-keys Department

If you want to view the tags that are applied to a specific Lambda function, you can use either of the
following Lambda API commands:

• ListTags (p. 873) – You supply your Lambda function ARN (Amazon Resource Name) to view a list of
the tags associated with this function:

aws lambda list-tags --resource function arn

• GetFunction (p. 808) – You supply your Lambda function name to a view a list of the tags associated
with this function:

aws lambda get-function --function-name my-function

You can also use the AWS Tagging Service’s GetResources API to filter your resources by tags. The
GetResources API receives up to 10 filters, with each filter containing a tag key and up to 10 tag values.
You provide GetResources with a ‘ResourceType’ to filter by specific resource types. For more information
about the AWS Tagging Service, see Working with Resource Groups.

Tag Key and Value Requirements

The following requirements apply to tags:

• Maximum number of tags per resource—50

• Maximum key length—128 Unicode characters in UTF-8
• Maximum value length—256 Unicode characters in UTF-8
• Tag keys and values are case sensitive.
• Do not use the aws: prefix in your tag names or values because it is reserved for AWS use. You can't
edit or delete tag names or values with this prefix. Tags with this prefix do not count against your tags
per resource limit.
• If your tagging schema will be used across multiple services and resources, remember that other
services may have restrictions on allowed characters. Generally allowed characters are: letters, spaces,
and numbers representable in UTF-8, plus the following special characters: + - = . _ : / @.

136
 AWS Lambda Developer Guide

Invoking AWS Lambda functions

You can invoke Lambda functions directly with the Lambda console (p. 10), the Lambda API, the AWS
SDK, the AWS CLI, and AWS toolkits. You can also configure other AWS services to invoke your function,
or you can configure Lambda to read from a stream or queue and invoke your function.

When you invoke a function, you can choose to invoke it synchronously or asynchronously. With
synchronous invocation (p. 138), you wait for the function to process the event and return a response.
With asynchronous (p. 140) invocation, Lambda queues the event for processing and returns a response
immediately. For asynchronous invocation, Lambda handles retries and can send invocation records to a
destination (p. 142).

To use your function to process data automatically, add one or more triggers. A trigger is a Lambda
resource or a resource in another service that you configure to invoke your function in response to
lifecycle events, external requests, or on a schedule. Your function can have multiple triggers. Each
trigger acts as a client invoking your function independently. Each event that Lambda passes to your
function only has data from one client or trigger.

To process items from a stream or queue, you can create an event source mapping (p. 148). An event
source mapping is a resource in Lambda that reads items from an Amazon SQS queue, an Amazon
Kinesis stream, or an Amazon DynamoDB stream, and sends them to your function in batches. Each
event that your function processes can contain hundreds or thousands of items.

Other AWS services and resources invoke your function directly. For example, you can configure
CloudWatch Events to invoke your function on a timer, or you can configure Amazon S3 to invoke your
function when an object is created. Each service varies in the method it uses to invoke your function,
the structure of the event, and how you configure it. For more information, see Using AWS Lambda with
other services (p. 257).

Depending on who invokes your function and how it's invoked, scaling behavior and the types of errors
that occur can vary. When you invoke a function synchronously, you receive errors in the response and
can retry. When you invoke asynchronously, use an event source mapping, or configure another service
to invoke your function, the retry requirements and the way that your function scales to handle large
numbers of events can vary. For details, see AWS Lambda function scaling (p. 153) and Error handling
and automatic retries in AWS Lambda (p. 158).

Topics
• Synchronous invocation (p. 138)
• Asynchronous invocation (p. 140)
• AWS Lambda event source mappings (p. 148)
• Monitoring the state of a function with the Lambda API (p. 151)
• AWS Lambda function scaling (p. 153)
• Error handling and automatic retries in AWS Lambda (p. 158)
• Using Lambda extensions (p. 160)
• Invoking functions defined as container images (p. 164)
• Invoking Lambda functions with the AWS Mobile SDK for Android (p. 165)

137
 AWS Lambda Developer Guide
Synchronous invocation

Synchronous invocation
When you invoke a function synchronously, Lambda runs the function and waits for a response. When
the function completes, Lambda returns the response from the function's code with additional data, such
as the version of the function that was invoked. To invoke a function synchronously with the AWS CLI,
use the invoke command.

aws lambda invoke --function-name my-function --payload '{ "key": "value" }' response.json

You should see the following output:

{
"ExecutedVersion": "$LATEST",
"StatusCode": 200
}

The following diagram shows clients invoking a Lambda function synchronously. Lambda sends the
events directly to the function and sends the function's response back to the invoker.

The payload is a string that contains an event in JSON format. The name of the file where the AWS CLI
writes the response from the function is response.json. If the function returns an object or error, the
response is the object or error in JSON format. If the function exits without error, the response is null.

The output from the command, which is displayed in the terminal, includes information from headers
in the response from Lambda. This includes the version that processed the event (useful when you use
aliases (p. 97)), and the status code returned by Lambda. If Lambda was able to run the function, the
status code is 200, even if the function returned an error.
Note
For functions with a long timeout, your client might be disconnected during synchronous
invocation while it waits for a response. Configure your HTTP client, SDK, firewall, proxy, or
operating system to allow for long connections with timeout or keep-alive settings.

If Lambda isn't able to run the function, the error is displayed in the output.

aws lambda invoke --function-name my-function --payload value response.json

You should see the following output:

138
 AWS Lambda Developer Guide
Synchronous invocation

An error occurred (InvalidRequestContentException) when calling the Invoke operation: Could

not parse request body into json: Unrecognized token 'value': was expecting ('true',
'false' or 'null')
at [Source: (byte[])"value"; line: 1, column: 11]

The AWS CLI is an open-source tool that enables you to interact with AWS services using commands in
your command line shell. To complete the steps in this section, you must have the following:

• AWS CLI – Install version 2

• AWS CLI – Quick configuration with aws configure

You can use the AWS CLI to retrieve logs for an invocation using the --log-type command option.
The response contains a LogResult field that contains up to 4 KB of base64-encoded logs from the
invocation.

Example retrieve a log ID

The following example shows how to retrieve a log ID from the LogResult field for a function named
my-function.

aws lambda invoke --function-name my-function out --log-type Tail

You should see the following output:

{
"StatusCode": 200,
"LogResult":
"U1RBUlQgUmVxdWVzdElkOiA4N2QwNDRiOC1mMTU0LTExZTgtOGNkYS0yOTc0YzVlNGZiMjEgVmVyc2lvb...",
"ExecutedVersion": "$LATEST"
}

Example decode the logs

In the same command prompt, use the base64 utility to decode the logs. The following example shows
how to retrieve base64-encoded logs for my-function.

aws lambda invoke --function-name my-function out --log-type Tail \

--query 'LogResult' --output text | base64 -d

You should see the following output:

START RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Version: $LATEST

"AWS_SESSION_TOKEN": "AgoJb3JpZ2luX2VjELj...", "_X_AMZN_TRACE_ID": "Root=1-5d02e5ca-
f5792818b6fe8368e5b51d50;Parent=191db58857df8395;Sampled=0"",ask/lib:/opt/lib",
END RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8
REPORT RequestId: 57f231fb-1730-4395-85cb-4f71bd2b87b8 Duration: 79.67 ms Billed
Duration: 80 ms Memory Size: 128 MB Max Memory Used: 73 MB

The base64 utility is available on Linux, macOS, and Ubuntu on Windows. macOS users may need to use
base64 -D.

For more information about the Invoke API, including a full list of parameters, headers, and errors, see
Invoke (p. 840).

When you invoke a function directly, you can check the response for errors and retry. The AWS CLI
and AWS SDK also automatically retry on client timeouts, throttling, and service errors. For more
information, see Error handling and automatic retries in AWS Lambda (p. 158).

139
 AWS Lambda Developer Guide
Asynchronous invocation

Asynchronous invocation
Several AWS services, such as Amazon Simple Storage Service (Amazon S3) and Amazon Simple
Notification Service (Amazon SNS), invoke functions asynchronously to process events. When you invoke
a function asynchronously, you don't wait for a response from the function code. You hand off the event
to Lambda and Lambda handles the rest. You can configure how Lambda handles errors, and can send
invocation records to a downstream resource to chain together components of your application.

The following diagram shows clients invoking a Lambda function asynchronously. Lambda queues the
events before sending them to the function.

For asynchronous invocation, Lambda places the event in a queue and returns a success response
without additional information. A separate process reads events from the queue and sends them to your
function. To invoke a function asynchronously, set the invocation type parameter to Event.

aws lambda invoke \

--function-name my-function \
--invocation-type Event \
--cli-binary-format raw-in-base64-out \
--payload '{ "key": "value" }' response.json

The cli-binary-format option is required if you are using AWS CLI version 2. You can also configure this
option in your AWS CLI config file
.

You should see the following output:

{
"StatusCode": 202
}

The output file (response.json) doesn't contain any information, but is still created when you run
this command. If Lambda isn't able to add the event to the queue, the error message appears in the
command output.

140
 AWS Lambda Developer Guide
Asynchronous invocation

Lambda manages the function's asynchronous event queue and attempts to retry on errors. If the
function returns an error, Lambda attempts to run it two more times, with a one-minute wait between
the first two attempts, and two minutes between the second and third attempts. Function errors include
errors returned by the function's code and errors returned by the function's runtime, such as timeouts.

If the function doesn't have enough concurrency available to process all events, additional requests
are throttled. For throttling errors (429) and system errors (500-series), Lambda returns the event
to the queue and attempts to run the function again for up to 6 hours. The retry interval increases
exponentially from 1 second after the first attempt to a maximum of 5 minutes. However, it might be
longer if the queue is backed up. Lambda also reduces the rate at which it reads events from the queue.

The following example shows an event that was successfully added to the queue, but is still pending one
hour later due to throttling.

Even if your function doesn't return an error, it's possible for it to receive the same event from Lambda
multiple times because the queue itself is eventually consistent. If the function can't keep up with
incoming events, events might also be deleted from the queue without being sent to the function.
Ensure that your function code gracefully handles duplicate events, and that you have enough
concurrency available to handle all invocations.

When the queue is backed up, new events might age out before Lambda has a chance to send them
to your function. When an event expires or fails all processing attempts, Lambda discards it. You can
configure error handling (p. 142) for a function to reduce the number of retries that Lambda performs,
or to discard unprocessed events more quickly.

You can also configure Lambda to send an invocation record to another service. Lambda supports the
following destinations (p. 142) for asynchronous invocation.

• Amazon SQS – A standard SQS queue.

141
 AWS Lambda Developer Guide
Configuring error handling for asynchronous invocation

• Amazon SNS – An SNS topic.

• AWS Lambda – A Lambda function.
• Amazon EventBridge – An EventBridge event bus.

The invocation record contains details about the request and response in JSON format. You can configure
separate destinations for events that are processed successfully, and events that fail all processing
attempts. Alternatively, you can configure an SQS queue or SNS topic as a dead-letter queue (p. 145)
for discarded events. For dead-letter queues, Lambda only sends the content of the event, without
details about the response.

Sections
• Configuring error handling for asynchronous invocation (p. 142)
• Configuring destinations for asynchronous invocation (p. 142)
• Asynchronous invocation configuration API (p. 144)
• AWS Lambda function dead-letter queues (p. 145)

Configuring error handling for asynchronous

invocation
Use the Lambda console to configure error handling settings on a function, a version, or an alias.

To configure error handling

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose Asynchronous invocation.
4. Under Asynchronous invocation, choose Edit.
5. Configure the following settings.

• Maximum age of event – The maximum amount of time Lambda retains an event in the
asynchronous event queue, up to 6 hours.
• Retry attempts – The number of times Lambda retries when the function returns an error,
between 0 and 2.
6. Choose Save.

When an invocation event exceeds the maximum age or fails all retry attempts, Lambda discards it. To
retain a copy of discarded events, configure a failed-event destination.

Configuring destinations for asynchronous invocation

To send records of asynchronous invocations to another service, add a destination to your function.
You can configure separate destinations for events that fail processing and events that are successfully
processed. Like error handling settings, you can configure destinations on a function, a version, or an
alias.

The following example shows a function that is processing asynchronous invocations. When the function
returns a success response or exits without throwing an error, Lambda sends a record of the invocation
to an EventBridge event bus. When an event fails all processing attempts, Lambda sends an invocation
record to an Amazon SQS queue.

142
 AWS Lambda Developer Guide
Configuring destinations for asynchronous invocation

To send events to a destination, your function needs additional permissions. Add a policy with the
required permissions to your function's execution role (p. 47). Each destination service requires a
different permission, as follows:

• Amazon SQS – sqs:SendMessage

• Amazon SNS – sns:Publish
• Lambda – lambda:InvokeFunction
• EventBridge – events:PutEvents

Add destinations to your function in the Lambda console's function visualization.

To configure a destination for asynchronous invocation records

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Under Function overview, choose Add destination.

143
 AWS Lambda Developer Guide
Asynchronous invocation configuration API

4. For Source, choose Asynchronous invocation.

5. For Condition, choose from the following options:

• On failure – Send a record when the event fails all processing attempts or exceeds the maximum
age.
• On success – Send a record when the function successfully processes an asynchronous invocation.
6. For Destination type, choose the type of resource that receives the invocation record.
7. For Destination, choose a resource.
8. Choose Save.

When an invocation matches the condition, Lambda sends a JSON document with details about the
invocation to the destination. The following example shows an invocation record for an event that failed
three processing attempts due to a function error.

Example invocation record

{
"version": "1.0",
"timestamp": "2019-11-14T18:16:05.568Z",
"requestContext": {
"requestId": "e4b46cbf-b738-xmpl-8880-a18cdf61200e",
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function:
$LATEST",
"condition": "RetriesExhausted",
"approximateInvokeCount": 3
},
"requestPayload": {
"ORDER_IDS": [
"9e07af03-ce31-4ff3-xmpl-36dce652cb4f",
"637de236-e7b2-464e-xmpl-baf57f86bb53",
"a81ddca6-2c35-45c7-xmpl-c3a03a31ed15"
]
},
"responseContext": {
"statusCode": 200,
"executedVersion": "$LATEST",
"functionError": "Unhandled"
},
"responsePayload": {
"errorMessage": "RequestId: e4b46cbf-b738-xmpl-8880-a18cdf61200e Process exited
before completing request"
}
}

The invocation record contains details about the event, the response, and the reason that the record was
sent.

Asynchronous invocation configuration API

To manage asynchronous invocation settings with the AWS CLI or AWS SDK, use the following API
operations.

• PutFunctionEventInvokeConfig
• GetFunctionEventInvokeConfig
• UpdateFunctionEventInvokeConfig
• ListFunctionEventInvokeConfigs

144
 AWS Lambda Developer Guide
Dead-letter queues

• DeleteFunctionEventInvokeConfig

To configure asynchronous invocation with the AWS CLI, use the put-function-event-invoke-
config command. The following example configures a function with a maximum event age of 1 hour
and no retries.

aws lambda put-function-event-invoke-config --function-name error \

--maximum-event-age-in-seconds 3600 --maximum-retry-attempts 0

You should see the following output:

{
"LastModified": 1573686021.479,
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:error:$LATEST",
"MaximumRetryAttempts": 0,
"MaximumEventAgeInSeconds": 3600,
"DestinationConfig": {
"OnSuccess": {},
"OnFailure": {}
}
}

The put-function-event-invoke-config command overwrites any existing configuration on the

function, version, or alias. To configure an option without resetting others, use update-function-
event-invoke-config. The following example configures Lambda to send a record to an SQS queue
named destination when an event can't be processed.

aws lambda update-function-event-invoke-config --function-name error \

--destination-config '{"OnFailure":{"Destination": "arn:aws:sqs:us-
east-2:123456789012:destination"}}'

You should see the following output:

{
"LastModified": 1573687896.493,
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:error:$LATEST",
"MaximumRetryAttempts": 0,
"MaximumEventAgeInSeconds": 3600,
"DestinationConfig": {
"OnSuccess": {},
"OnFailure": {
"Destination": "arn:aws:sqs:us-east-2:123456789012:destination"
}
}
}

AWS Lambda function dead-letter queues

As an alternative to an on-failure destination (p. 142), you can configure your function with a dead-
letter queue to save discarded events for further processing. A dead-letter queue acts the same as an
on-failure destination in that it is used when an event fails all processing attempts or expires without
being processed. However, a dead-letter queue is part of a function's version-specific configuration, so
it is locked in when you publish a version. On-failure destinations also support additional targets and
include details about the function's response in the invocation record.

If you don't have a queue or topic, create one. Choose the target type that matches your use case.

145
 AWS Lambda Developer Guide
Dead-letter queues

• Amazon SQS queue – A queue holds failed events until they're retrieved. You can retrieve events
manually, or you can configure Lambda to read from the queue (p. 439) and invoke a function.

Create a queue in the Amazon SQS console.

• Amazon SNS topic – A topic relays failed events to one or more destinations. You can configure a topic
to send events to an email address, a Lambda function, or an HTTP endpoint.

Create a topic in the Amazon SNS console.

To send events to a queue or topic, your function needs additional permissions. Add a policy with the
required permissions to your function's execution role (p. 47).

• Amazon SQS – sqs:SendMessage

• Amazon SNS – sns:Publish

If the target queue or topic is encrypted with a customer managed key, the execution role must also be a
user in the key's resource-based policy.

After creating the target and updating your function's execution role, add the dead-letter queue to your
function. You can configure multiple functions to send events to the same target.

To configure a dead-letter queue

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose Configuration and then choose Asynchronous invocation.
4. Under Asynchronous invocation, choose Edit.
5. Set DLQ resource to Amazon SQS or Amazon SNS.
6. Choose the target queue or topic.
7. Choose Save.

To configure a dead-letter queue with the AWS CLI, use the update-function-configuration
command.

aws lambda update-function-configuration --function-name my-function \

--dead-letter-config TargetArn=arn:aws:sns:us-east-2:123456789012:my-topic

Lambda sends the event to the dead-letter queue as-is, with additional information in attributes. You
can use this information to identify the error that the function returned, or to correlate the event with
logs or an AWS X-Ray trace.

Dead-letter queue message attributes

• RequestID (String) – The ID of the invocation request. Request IDs appear in function logs. You can
also use the X-Ray SDK to record the request ID on an attribute in the trace. You can then search for
traces by request ID in the X-Ray console. For an example, see the error processor sample (p. 473).
• ErrorCode (Number) – The HTTP status code.
• ErrorMessage (String) – The first 1 KB of the error message.

146
 AWS Lambda Developer Guide
Dead-letter queues

If Lambda can't send a message to the dead-letter queue, it deletes the event and emits the
DeadLetterErrors (p. 692) metric. This can happen because of lack of permissions, or if the total size of
the message exceeds the limit for the target queue or topic. For example, if an Amazon SNS notification
with a body close to 256 KB triggers a function that results in an error, the additional event data added
by Amazon SNS, combined with the attributes added by Lambda, can cause the message to exceed the
maximum size allowed in the dead-letter queue.

If you're using Amazon SQS as an event source, configure a dead-letter queue on the Amazon SQS queue
itself and not on the Lambda function. For more information, see Using AWS Lambda with Amazon
SQS (p. 439).

147
 AWS Lambda Developer Guide
Event source mapping

AWS Lambda event source mappings

An event source mapping is an AWS Lambda resource that reads from an event source and invokes
a Lambda function. You can use event source mappings to process items from a stream or queue in
services that don't invoke Lambda functions directly. Lambda provides event source mappings for the
following services.

Services that Lambda reads events from

• Amazon DynamoDB (p. 313)

• Amazon Kinesis (p. 365)
• Amazon MQ (p. 389)
• Amazon Managed Streaming for Apache Kafka (p. 396)
• self-managed Apache Kafka (p. 356)
• Amazon Simple Queue Service (p. 439)

An event source mapping uses permissions in the function's execution role (p. 47) to read and manage
items in the event source. Permissions, event structure, settings, and polling behavior vary by event
source. For more information, see the linked topic for the service that you use as an event source.

To manage an event source with the AWS CLI or AWS SDK, you can use the following API operations:

• CreateEventSourceMapping (p. 754)

• ListEventSourceMappings (p. 853)
• GetEventSourceMapping (p. 803)
• UpdateEventSourceMapping (p. 919)
• DeleteEventSourceMapping (p. 779)

The following example uses the AWS CLI to map a function named my-function to a DynamoDB
stream that is specified by its Amazon Resource Name (ARN), with a batch size of 500.

aws lambda create-event-source-mapping --function-name my-function --batch-size 500 --

starting-position LATEST \
--event-source-arn arn:aws:dynamodb:us-east-2:123456789012:table/my-table/
stream/2019-06-10T19:26:16.525

You should see the following output:

{
"UUID": "14e0db71-5d35-4eb5-b481-8945cf9d10c2",
"BatchSize": 500,
"MaximumBatchingWindowInSeconds": 0,
"ParallelizationFactor": 1,
"EventSourceArn": "arn:aws:dynamodb:us-east-2:123456789012:table/my-table/
stream/2019-06-10T19:26:16.525",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"LastModified": 1560209851.963,
"LastProcessingResult": "No records processed",
"State": "Creating",
"StateTransitionReason": "User action",
"DestinationConfig": {},
"MaximumRecordAgeInSeconds": 604800,
"BisectBatchOnFunctionError": false,

148
 AWS Lambda Developer Guide
Event source mapping

"MaximumRetryAttempts": 10000
}

Event source mappings read items from a stream or queue in batches. They include multiple items in the
event that your function receives. You can configure the size of the batch that the event source mapping
sends to your function, up to a maximum that varies by service. The number of items in the event can be
smaller than the batch size if there aren't enough items available, or if the batch is too large to send in
one event and has to be split up.

The following example shows an event source mapping that reads from a Kinesis stream. If a batch of
events fails all processing attempts, the event source mapping sends details about the batch to an SQS
queue.

The event batch is the event that Lambda sends to the function. It is a batch of records or messages
compiled from the items that the event source mapping reads from a stream or queue. Batch size and
other settings only apply to the event batch.

149
 AWS Lambda Developer Guide
Event source mapping

For streams, an event source mapping creates an iterator for each shard in the stream and processes
items in each shard in order. You can configure the event source mapping to read only new items that
appear in the stream, or to start with older items. Processed items aren't removed from the stream and
can be processed by other functions or consumers.

By default, if your function returns an error, the entire batch is reprocessed until the function succeeds,
or the items in the batch expire. To ensure in-order processing, processing for the affected shard is
paused until the error is resolved. You can configure the event source mapping to discard old events,
restrict the number of retries, or process multiple batches in parallel. If you process multiple batches in
parallel, in-order processing is still guaranteed for each partition key, but multiple partition keys in the
same shard are processed simultaneously.

You can also configure the event source mapping to send an invocation record to another service when it
discards an event batch. Lambda supports the following destinations (p. 142) for event source mappings.

• Amazon SQS – An SQS queue.

• Amazon SNS – An SNS topic.

The invocation record contains details about the failed event batch in JSON format.

The following example shows an invocation record for a Kinesis stream.

Example invocation Record

{
"requestContext": {
"requestId": "c9b8fa9f-5a7f-xmpl-af9c-0c604cde93a5",
"functionArn": "arn:aws:lambda:us-east-2:123456789012:function:myfunction",
"condition": "RetryAttemptsExhausted",
"approximateInvokeCount": 1
},
"responseContext": {
"statusCode": 200,
"executedVersion": "$LATEST",
"functionError": "Unhandled"
},
"version": "1.0",
"timestamp": "2019-11-14T00:38:06.021Z",
"KinesisBatchInfo": {
"shardId": "shardId-000000000001",
"startSequenceNumber": "49601189658422359378836298521827638475320189012309704722",
"endSequenceNumber": "49601189658422359378836298522902373528957594348623495186",
"approximateArrivalOfFirstRecord": "2019-11-14T00:38:04.835Z",
"approximateArrivalOfLastRecord": "2019-11-14T00:38:05.580Z",
"batchSize": 500,
"streamArn": "arn:aws:kinesis:us-east-2:123456789012:stream/mystream"
}
}

Lambda also supports in-order processing for FIFO (first-in, first-out) queues (p. 439), scaling up to
the number of active message groups. For standard queues, items aren't necessarily processed in order.
Lambda scales up to process a standard queue as quickly as possible. When an error occurs, batches
are returned to the queue as individual items and might be processed in a different grouping than the
original batch. Occasionally, the event source mapping might receive the same item from the queue
twice, even if no function error occurred. Lambda deletes items from the queue after they're processed
successfully. You can configure the source queue to send items to a dead-letter queue if they can't be
processed.

For information about services that invoke Lambda functions directly, see Using AWS Lambda with other
services (p. 257).

150
 AWS Lambda Developer Guide
Function states

Monitoring the state of a function with the

Lambda API
When you create or update a function, Lambda provisions the compute and networking resources that
enable it to run. In most cases, this process is very fast, and your function is ready to be invoked or
modified right away.

If you configure your function to connect to a virtual private cloud (VPC), the process can take longer.
When you first connect a function to a VPC, Lambda provisions network interfaces, which takes about
a minute. To communicate the current state of your function, Lambda includes additional fields in the
function configuration (p. 975) document that is returned by several Lambda API actions.

When you create a function, the function is initially in the Pending state. When the function is ready to
be invoked, the state changes from Pending to Active. While the state is Pending, invocations and
other API actions that operate on the function return an error. If you build automation around creating
and updating functions, wait for the function to become active before performing additional actions that
operate on the function.

You can use the Lambda API to get information about a function's state. State information is included in
the FunctionConfiguration (p. 975) document returned by several API actions. To view the function's
state with the AWS CLI, use the get-function-configuration command.

aws lambda get-function-configuration --function-name my-function

You should see the following output:

{
"FunctionName": "my-function",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"Runtime": "nodejs12.x",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"TracingConfig": {
"Mode": "Active"
},
"State": "Pending",
"StateReason": "The function is being created.",
"StateReasonCode": "Creating",
...
}

The StateReason and StateReasonCode contain additional information about the state when it is not
Active. The following operations fail while function creation is pending:

• Invoke (p. 840)

• UpdateFunctionCode (p. 927)
• UpdateFunctionConfiguration (p. 936)
• PublishVersion (p. 883)

When you update a function's configuration, the update can trigger an asynchronous operation to
provision resources. While this is in progress, you can invoke the function, but other operations on
the function fail. Invocations that occur while the update is in progress run against the previous
configuration. The function's state is Active, but its LastUpdateStatus is InProgress.

Example Function configuration – Connecting to a VPC

151
 AWS Lambda Developer Guide
Function states

"FunctionName": "my-function",
"FunctionArn": "arn:aws:lambda:us-east-2:123456789012:function:my-function",
"Runtime": "nodejs12.x",
"VpcConfig": {
"SubnetIds": [
"subnet-071f712345678e7c8",
"subnet-07fd123456788a036",
"subnet-0804f77612345cacf"
],
"SecurityGroupIds": [
"sg-085912345678492fb"
],
"VpcId": "vpc-08e1234569e011e83"
},
"State": "Active",
"LastUpdateStatus": "InProgress",
...
}

The following operations fail while an asynchronous update is in progress:

• UpdateFunctionCode (p. 927)

• UpdateFunctionConfiguration (p. 936)
• PublishVersion (p. 883)

Other operations, including invocation, work while updates are in progress.

For example, when you connect your function to a virtual private cloud (VPC), Lambda provisions an
elastic network interface for each subnet. This process can leave your function in a pending state for a
minute or so. Lambda also reclaims network interfaces that are not in use, placing your function in an
Inactive state. When the function is inactive, an invocation causes it to enter the Pending state while
network access is restored. The invocation that triggers restoration, and further invocations while the
operation is pending, fail with ResourceNotReadyException.

If Lambda encounters an error when restoring a function's network interface, the function goes back to
the Inactive state. The next invocation can trigger another attempt. For some configuration errors,
Lambda waits at least 5 minutes before attempting to create another network interface. These errors
have the following LastUpdateStatusReasonCode values:

• InsufficientRolePermission – Role doesn't exist or is missing permissions.

• SubnetOutOfIPAddresses – All IP addresses in a subnet are in use.

For more information on how states work with VPC connectivity, see Configuring a Lambda function to
access resources in a VPC (p. 111).

152
 AWS Lambda Developer Guide
Function scaling

AWS Lambda function scaling

The first time you invoke your function, AWS Lambda creates an instance of the function and runs its
handler method to process the event. When the function returns a response, it stays active and waits
to process additional events. If you invoke the function again while the first event is being processed,
Lambda initializes another instance, and the function processes the two events concurrently. As more
events come in, Lambda routes them to available instances and creates new instances as needed. When
the number of requests decreases, Lambda stops unused instances to free up scaling capacity for other
functions.

Your functions' concurrency is the number of instances that serve requests at a given time. For an initial
burst of traffic, your functions' cumulative concurrency in a Region can reach an initial level of between
500 and 3000, which varies per Region. Note that the burst concurrency quota is not per-function; it
applies to all of your functions in the Region.

Burst concurrency quotas

• 3000 – US West (Oregon), US East (N. Virginia), Europe (Ireland)

• 1000 – Asia Pacific (Tokyo), Europe (Frankfurt), US East (Ohio)
• 500 – Other Regions

After the initial burst, your functions' concurrency can scale by an additional 500 instances each
minute. This continues until there are enough instances to serve all requests, or until a concurrency
limit is reached. When requests come in faster than your function can scale, or when your function is at
maximum concurrency, additional requests fail with a throttling error (429 status code).

The following example shows a function processing a spike in traffic. As invocations increase
exponentially, the function scales up. It initializes a new instance for any request that can't be routed to
an available instance. When the burst concurrency limit is reached, the function starts to scale linearly.
If this isn't enough concurrency to serve all requests, additional requests are throttled and should be
retried.

153
 AWS Lambda Developer Guide
Function scaling

Legend

• Function instances
• Open requests
• Throttling possible

The function continues to scale until the account's concurrency limit for the function's Region is reached.
The function catches up to demand, requests subside, and unused instances of the function are stopped
after being idle for some time. Unused instances are frozen while they're waiting for requests and don't
incur any charges.

154
 AWS Lambda Developer Guide
Function scaling

The regional concurrency limit starts at 1,000. You can increase the limit by submitting a request in the
Support Center console. To allocate capacity on a per-function basis, you can configure functions with
reserved concurrency (p. 84). Reserved concurrency creates a pool that can only be used by its function,
and also prevents its function from using unreserved concurrency.

When your function scales up, the first request served by each instance is impacted by the time it
takes to load and initialize your code. If your initialization code (p. 32) takes a long time, the impact on
average and percentile latency can be significant. To enable your function to scale without fluctuations
in latency, use provisioned concurrency (p. 84). The following example shows a function with provisioned
concurrency processing a spike in traffic.

Legend

• Function instances
• Open requests
• Provisioned concurrency
• Standard concurrency

155
 AWS Lambda Developer Guide
Function scaling

When you allocate provisioned concurrency, your function is ready to serve a burst of incoming requests
with very low latency. When all provisioned concurrency is in use, the function scales up normally to
handle any additional requests.

Application Auto Scaling takes this a step further by providing autoscaling for provisioned concurrency.
With Application Auto Scaling, you can create a target tracking scaling policy that adjusts provisioned
concurrency levels automatically, based on the utilization metric that Lambda emits. Use the Application
Auto Scaling API (p. 90) to register an alias as a scalable target and create a scaling policy.

In the following example, a function scales between a minimum and maximum amount of provisioned
concurrency based on utilization. When the number of open requests increases, Application Auto
Scaling increases provisioned concurrency in large steps until it reaches the configured maximum. The
function continues to scale on standard concurrency until utilization starts to drop. When utilization is
consistently low, Application Auto Scaling decreases provisioned concurrency in smaller periodic steps.

156
 AWS Lambda Developer Guide
Function scaling

Legend

• Function instances
• Open requests
• Provisioned concurrency
• Standard concurrency

When you invoke your function asynchronously, by using an event source mapping or another AWS
service, scaling behavior varies. For example, event source mappings that read from a stream are limited
by the number of shards in the stream. Scaling capacity that is unused by an event source is available for
use by other clients and event sources. For more information, see the following topics.

• Asynchronous invocation (p. 140)

• AWS Lambda event source mappings (p. 148)
• Error handling and automatic retries in AWS Lambda (p. 158)
• Using AWS Lambda with other services (p. 257)

You can monitor concurrency levels in your account by using the following metrics:

Concurrency metrics

• ConcurrentExecutions
• UnreservedConcurrentExecutions
• ProvisionedConcurrentExecutions
• ProvisionedConcurrencyInvocations
• ProvisionedConcurrencySpilloverInvocations
• ProvisionedConcurrencyUtilization

For more information, see Working with AWS Lambda function metrics (p. 692).

157
 AWS Lambda Developer Guide
Error handling

Error handling and automatic retries in AWS

Lambda
When you invoke a function, two types of error can occur. Invocation errors occur when the invocation
request is rejected before your function receives it. Function errors occur when your function's code or
runtime (p. 195) returns an error. Depending on the type of error, the type of invocation, and the client
or service that invokes the function, the retry behavior and the strategy for managing errors varies.

Issues with the request, caller, or account can cause invocation errors. Invocation errors include an error
type and status code in the response that indicate the cause of the error.

Common invocation errors

• Request – The request event is too large or isn't valid JSON, the function doesn't exist, or a parameter
value is the wrong type.
• Caller – The user or service doesn't have permission to invoke the function.
• Account – The maximum number of function instances are already running, or requests are being
made too quickly.

Clients such as the AWS CLI and the AWS SDK retry on client timeouts, throttling errors (429), and other
errors that aren't caused by a bad request. For a full list of invocation errors, see Invoke (p. 840).

Function errors occur when your function code or the runtime that it uses return an error.

Common function errors

• Function – Your function's code throws an exception or returns an error object.

• Runtime – The runtime terminated your function because it ran out of time, detected a syntax error, or
failed to marshal the response object into JSON. The function exited with an error code.

Unlike invocation errors, function errors don't cause Lambda to return a 400-series or 500-series status
code. If the function returns an error, Lambda indicates this by including a header named X-Amz-
Function-Error, and a JSON-formatted response with the error message and other details. For
examples of function errors in each language, see the following topics.

• AWS Lambda function errors in Node.js (p. 501)

• AWS Lambda function errors in Python (p. 539)
• AWS Lambda function errors in Ruby (p. 562)
• AWS Lambda function errors in Java (p. 597)
• AWS Lambda function errors in Go (p. 629)
• AWS Lambda function errors in C# (p. 658)
• AWS Lambda function errors in PowerShell (p. 679)

When you invoke a function directly, you determine the strategy for handling errors. You can retry, send
the event to a queue for debugging, or ignore the error. Your function's code might have run completely,
partially, or not at all. If you retry, ensure that your function's code can handle the same event multiple
times without causing duplicate transactions or other unwanted side effects.

When you invoke a function indirectly, you need to be aware of the retry behavior of the invoker and any
service that the request encounters along the way. This includes the following scenarios.

158
 AWS Lambda Developer Guide
Error handling

• Asynchronous invocation – Lambda retries function errors twice. If the function doesn't have enough
capacity to handle all incoming requests, events might wait in the queue for hours or days to be sent
to the function. You can configure a dead-letter queue on the function to capture events that weren't
successfully processed. For more information, see Asynchronous invocation (p. 140).
• Event source mappings – Event source mappings that read from streams retry the entire batch of
items. Repeated errors block processing of the affected shard until the error is resolved or the items
expire. To detect stalled shards, you can monitor the Iterator Age (p. 692) metric.

For event source mappings that read from a queue, you determine the length of time between retries
and destination for failed events by configuring the visibility timeout and redrive policy on the source
queue. For more information, see AWS Lambda event source mappings (p. 148) and the service-
specific topics under Using AWS Lambda with other services (p. 257).
• AWS services – AWS services can invoke your function synchronously (p. 138) or asynchronously.
For synchronous invocation, the service decides whether to retry. For example, Amazon S3 batch
operations retries the operation if the Lambda function returns a TemporaryFailure response code.
Services that proxy requests from an upstream user or client may have a retry strategy or may relay
the error response back to the requestor. For example, API Gateway always relays the error response
back to the requestor.

For asynchronous invocation, the behavior is the same as when you invoke the function synchronously.
For more information, see the service-specific topics under Using AWS Lambda with other
services (p. 257) and the invoking service's documentation.
• Other accounts and clients – When you grant access to other accounts, you can use resource-based
policies (p. 51) to restrict the services or resources they can configure to invoke your function. To
protect your function from being overloaded, consider putting an API layer in front of your function
with Amazon API Gateway (p. 261).

To help you deal with errors in Lambda applications, Lambda integrates with services like Amazon
CloudWatch and AWS X-Ray. You can use a combination of logs, metrics, alarms, and tracing to quickly
detect and identify issues in your function code, API, or other resources that support your application.
For more information, see Monitoring and troubleshooting Lambda applications (p. 683).

For a sample application that uses a CloudWatch Logs subscription, X-Ray tracing, and a Lambda
function to detect and process errors, see Error processor sample application for AWS Lambda (p. 473).

159
 AWS Lambda Developer Guide
Using extensions

Using Lambda extensions

You can use Lambda extensions to augment your Lambda functions. For example, use Lambda
extensions to integrate functions with your preferred monitoring, observability, security, and governance
tools. You can choose from a broad set of tools that AWS Lambda Partners provides, or you can create
your own Lambda extensions (p. 209).

Lambda supports external and internal extensions. An external extension runs as an independent process
in the execution environment and continues to run after the function invocation is fully processed.
Because extensions run as separate processes, you can write them in a different language than the
function.

An internal extension runs as part of the runtime process. Your function accesses internal extensions by
using wrapper scripts or in-process mechanisms such as JAVA_TOOL_OPTIONS. For more information,
see Modifying the runtime environment (p. 231).

You can add extensions to a function using the Lambda console, the AWS Command Line Interface (AWS
CLI), or infrastructure as code (IaC) services and tools such as AWS CloudFormation, AWS Serverless
Application Model (AWS SAM), and Terraform.

The following Lambda runtimes (p. 195) support extensions:

• .NET Core 3.1 (C#/PowerShell) (dotnetcore3.1)

• Custom runtime (provided)
• Custom runtime on Amazon Linux 2 (provided.al2)
• Java 11 (Corretto) (java11)
• Java 8 (Corretto) (java8.al2)
• Node.js 14.x (nodejs14.x)
• Node.js 12.x (nodejs12.x)
• Node.js 10.x (nodejs10.x)
• Python 3.8 (python3.8)
• Python 3.7 (python3.7)
• Ruby 2.7 (ruby2.7)
• Ruby 2.5 (ruby2.5)

Note that the Go 1.x runtime does not support extensions. To support extensions, you can create Go
functions on the provided.al2 runtime. For more information, see Migrating Lambda functions to
Amazon Linux 2.

You are charged for the execution time that the extension consumes (in 1 ms increments). For more
pricing information for extensions, see AWS Lambda Pricing. For pricing information for partner
extensions, see those partners' websites. There is no cost to install your own extensions.

Topics
• Execution environment (p. 161)
• Impact on performance and resources (p. 161)
• Permissions (p. 161)
• Configuring extensions (.zip file archive) (p. 162)
• Using extensions in container images (p. 162)
• Next steps (p. 162)

160
 AWS Lambda Developer Guide
Execution environment

Execution environment
Lambda invokes your function in an execution environment (p. 200), which provides a secure and
isolated runtime environment. The execution environment manages the resources required to run your
function and provides lifecycle support for the function's runtime and extensions.

The lifecycle of the execution environment includes the following phases:

• Init: In this phase, Lambda creates or unfreezes an execution environment with the configured
resources, downloads the code for the function and all layers, initializes any extensions, initializes the
runtime, and then runs the function’s initialization code (the code outside the main handler). The Init
phase happens either during the first invocation, or in advance of function invocations if you have
enabled provisioned concurrency (p. 87).

The Init phase is split into three sub-phases: Extension init, Runtime init, and Function
init. These sub-phases ensure that all extensions and the runtime complete their setup tasks before
the function code runs.
• Invoke: In this phase, Lambda invokes the function handler. After the function runs to completion,
Lambda prepares to handle another function invocation.
• Shutdown: This phase is triggered if the Lambda function does not receive any invocations for a period
of time. In the Shutdown phase, Lambda shuts down the runtime, alerts the extensions to let them
stop cleanly, and then removes the environment. Lambda sends a Shutdown event to each extension,
which tells the extension that the environment is about to be shut down.

During the Init phase, Lambda extracts layers containing extensions into the /opt directory in the
execution environment. Lambda looks for extensions in the /opt/extensions/ directory, interprets
each file as an executable bootstrap for launching the extension, and starts all extensions in parallel.

Impact on performance and resources

The size of your function's extensions counts towards the deployment package size limit. For a .zip
file archive, the total unzipped size of the function and all extensions cannot exceed the unzipped
deployment package size limit of 250 MB.

Extensions can impact the performance of your function because they share function resources such as
CPU, memory, and storage. For example, if an extension performs compute-intensive operations, you
may see your function's execution duration increase.

Each extension must complete its initialization before Lambda invokes the function. Therefore,
an extension that consumes significant initialization time can increase the latency of the function
invocation.

To measure the extra time that the extension takes after the function execution, you can use the
PostRuntimeExtensionsDuration function metric (p. 692). To measure the increase in memory
used, you can use the MaxMemoryUsed metric. To understand the impact of a specific extension, you can
run different versions of your functions side by side.

Permissions
Extensions have access to the same resources as functions. Because extensions are executed within the
same environment as the function, permissions are shared between the function and the extension.

For a .zip file archive, you can create an AWS CloudFormation template to simplify the task of attaching
the same extension configuration—including AWS Identity and Access Management (IAM) permissions—
to multiple functions.

161
 AWS Lambda Developer Guide
Configuring extensions (.zip file archive)

Configuring extensions (.zip file archive)

You can add an extension to your function as a Lambda layer (p. 101). Using layers enables you to share
extensions across your organization or to the entire community of Lambda developers. You can add one
or more extensions to a layer. You can register up to 10 extensions for a function.

You add the extension to your function using the same method as you would for any layer. For more
information, see Using layers with your Lambda function (p. 106).

Add an extension to your function (console)

1. Open the Functions page on the Lambda console.

2. Choose a function.
3. Choose the Code tab if it is not already selected.
4. Under Layers, choose Edit.
5. For Choose a layer, choose Specify an ARN.
6. For Specify an ARN, enter the Amazon Resource Name (ARN) of an extension layer.
7. Choose Add.

Using extensions in container images

You can add extensions to your container image (p. 247). The ENTRYPOINT container image setting
specifies the main process for the function. Configure the ENTRYPOINT setting in the Dockerfile, or as an
override in the function configuration.

You can run multiple processes within a container. Lambda manages the lifecycle of the main process
and any additional processes. Lambda uses the Extensions API (p. 209) to manage the extension
lifecycle.

Example: Adding an external extension

An external extension runs in a separate process from the Lambda function. Lambda starts a process for
each extension in the /opt/extensions/ directory. Lambda uses the Extensions API to manage the
extension lifecycle. After the function has run to completion, Lambda sends a Shutdown event to each
external extension.

Example of adding an external extension to a Python base image

FROM public.ecr.aws/lambda/python:3.8

# Copy and install the app

COPY /app /app
WORKDIR /app
RUN pip install -r requirements.txt

# Add an extension from the local directory into /opt

ADD my-extension.zip /opt
CMD python ./index.py

Next steps
To learn more about extensions, we recommend the following resources:

• For a basic working example, see Building Extensions for AWS Lambda on the AWS Compute Blog.

162
 AWS Lambda Developer Guide
Next steps

• For information about extensions that AWS Lambda Partners provides, see Introducing AWS Lambda
Extensions on the AWS Compute Blog.
• To view available example extensions and wrapper scripts, see AWS Lambda Extensions on the AWS
Samples GitHub repository.

163
 AWS Lambda Developer Guide
Invoking functions defined as container images

Invoking functions defined as container images

For a Lambda function defined as a container image, function behavior during invocation is very
similar to a function defined as a .zip file archive. The following sections highlight the similarities and
differences.

Topics
• Function lifecycle (p. 164)
• Invoking the function (p. 164)
• Image security (p. 164)

Function lifecycle
Lambda optimizes a new or updated container image in preparation for the function to receive
invocations. The optimization process can take a few seconds. The function remains in the Pending
state until the process completes. The function then transitions to the Active state. While the state is
Pending, you can invoke the function, but other operations on the function fail. Invocations that occur
while an image update is in progress run the code from the previous image.

If a function is not invoked for multiple weeks, Lambda reclaims its optimized version, and the function
transitions to the Inactive state. To reactivate the function, you must invoke it. Lambda rejects the first
invocation and the function enters the Pending state until Lambda re-optimizes the image. The function
then returns to the Active state.

Lambda periodically fetches the associated container image from the Amazon Elastic Container Registry
(Amazon ECR) repository. If the corresponding container image no longer exists on Amazon ECR, the
function enters the Failed state, and Lambda returns a failure for any function invocations.

You can use the Lambda API to get information about a function's state. For more information, see
Monitoring the state of a function with the Lambda API (p. 151).

Invoking the function

When you invoke the function, Lambda deploys the container image to an execution environment.
Lambda initializes any extensions (p. 162) and then runs the function’s initialization code (the code
outside the main handler). Note that function initialization duration is included in billed execution time.

Lambda then runs the function by calling the code entry point specified in the function configuration
(the ENTRYPOINT and CMD container image settings (p. 249)).

Image security
When Lambda first downloads the container image from its original source (Amazon ECR), the container
image is optimized, encrypted, and stored using authenticated convergent encryption methods. All
keys that are required to decrypt customer data are protected using customer managed AWS Key
Management Service (AWS KMS) customer master keys (CMKs). To track and audit Lambda's usage of
CMKs, you can view the AWS CloudTrail logs (p. 285).

164
 AWS Lambda Developer Guide
Mobile SDK for Android

Invoking Lambda functions with the AWS Mobile

SDK for Android
You can call a Lambda function from a mobile application. Put business logic in functions to separate
its development lifecycle from that of front-end clients, making mobile applications less complex to
develop and maintain. With the Mobile SDK for Android, you use Amazon Cognito to authenticate users
and authorize requests (p. 165).

When you invoke a function from a mobile application, you choose the event structure, invocation
type (p. 137), and permission model. You can use aliases (p. 97) to enable seamless updates to your
function code, but otherwise the function and application are tightly coupled. As you add more
functions, you can create an API layer to decouple your function code from your front-end clients and
improve performance.

To create a fully-featured web API for your mobile and web applications, use Amazon API Gateway.
With API Gateway, you can add custom authorizers, throttle requests, and cache results for all of your
functions. For more information, see Using AWS Lambda with Amazon API Gateway (p. 261).

Topics
• Tutorial: Using AWS Lambda with the Mobile SDK for Android (p. 165)
• Sample function code (p. 171)

Tutorial: Using AWS Lambda with the Mobile SDK for

Android
In this tutorial, you create a simple Android mobile application that uses Amazon Cognito to get
credentials and invokes a Lambda function.

The mobile application retrieves AWS credentials from an Amazon Cognito identity pool and uses them
to invoke a Lambda function with an event that contains request data. The function processes the
request and returns a response to the front-end.

165
 AWS Lambda Developer Guide
Tutorial

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting started with Lambda (p. 9) to create
your first Lambda function.

To complete the following steps, you need a command line terminal or shell to run commands.
Commands and the expected output are listed in separate blocks:

aws --version

You should see the following output:

aws-cli/2.0.57 Python/3.7.4 Darwin/19.6.0 exe/x86_64

For long commands, an escape character (\) is used to split a command over multiple lines.

On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

Create the execution role

Create the execution role (p. 47) that gives your function permission to access AWS resources.

To create an execution role

1. Open the roles page in the IAM console.

2. Choose Create role.
3. Create a role with the following properties.

• Trusted entity – AWS Lambda.

• Permissions – AWSLambdaBasicExecutionRole.
• Role name – lambda-android-role.

The AWSLambdaBasicExecutionRole policy has the permissions that the function needs to write logs to
CloudWatch Logs.

Create the function

The following example uses data to generate a string response.
Note
For sample code in other languages, see Sample function code (p. 171).

Example index.js

exports.handler = function(event, context, callback) {

console.log("Received event: ", event);
var data = {
"greetings": "Hello, " + event.firstName + " " + event.lastName + "."
};
callback(null, data);
}

166
 AWS Lambda Developer Guide
Tutorial

To create the function

1. Copy the sample code into a file named index.js.

2. Create a deployment package.

zip function.zip index.js

3. Create a Lambda function with the create-function command.

aws lambda create-function --function-name AndroidBackendLambdaFunction \

--zip-file fileb://function.zip --handler index.handler --runtime nodejs12.x \
--role arn:aws:iam::123456789012:role/lambda-android-role

Test the Lambda function

Invoke the function manually using the sample event data.

To test the Lambda function (AWS CLI)

1. Save the following sample event JSON in a file, input.txt.

{ "firstName": "first-name", "lastName": "last-name" }

2. Run the following invoke command:

aws lambda invoke --function-name AndroidBackendLambdaFunction \

--payload file://file-path/input.txt outputfile.txt

The cli-binary-format option is required if you are using AWS CLI version 2. You can also configure
this option in your AWS CLI config file
.

Create an Amazon Cognito identity pool

In this section, you create an Amazon Cognito identity pool. The identity pool has two IAM
roles. You update the IAM role for unauthenticated users and grant permissions to run the
AndroidBackendLambdaFunction Lambda function.

For more information about IAM roles, see IAM roles in the IAM User Guide. For more information about
Amazon Cognito services, see the Amazon Cognito product detail page.

To create an identity pool

1. Open the Amazon Cognito console.

2. Create a new identity pool called JavaFunctionAndroidEventHandlerPool. Before you follow
the procedure to create an identity pool, note the following:

• The identity pool you are creating must allow access to unauthenticated identities because our
example mobile application does not require a user log in. Therefore, make sure to select the
Enable access to unauthenticated identities option.
• Add the following statement to the permission policy associated with the unauthenticated
identities.

167
 AWS Lambda Developer Guide
Tutorial

"Effect": "Allow",
"Action": [
"lambda:InvokeFunction"
],
"Resource": [
"arn:aws:lambda:us-
east-1:123456789012:function:AndroidBackendLambdaFunction"
]
}

The resulting policy will be as follows:

{
"Version":"2012-10-17",
"Statement":[
{
"Effect":"Allow",
"Action":[
"mobileanalytics:PutEvents",
"cognito-sync:*"
],
"Resource":[
"*"
]
},
{
"Effect":"Allow",
"Action":[
"lambda:invokefunction"
],
"Resource":[
"arn:aws:lambda:us-east-1:account-
id:function:AndroidBackendLambdaFunction"
]
}
]
}

For instructions about how to create an identity pool, log in to the Amazon Cognito console and
follow the New Identity Pool wizard.
3. Note the identity pool ID. You specify this ID in your mobile application you create in the next
section. The app uses this ID when it sends request to Amazon Cognito to request for temporary
security credentials.

Create an Android application

Create a simple Android mobile application that generates events and invokes Lambda functions by
passing the event data as parameters.

The following instructions have been verified using Android studio.

1. Create a new Android project called AndroidEventGenerator using the following configuration:

• Select the Phone and Tablet platform.

• Choose Blank Activity.
2. In the build.gradle (Module:app) file, add the following in the dependencies section:

compile 'com.amazonaws:aws-android-sdk-core:2.2.+'

168
 AWS Lambda Developer Guide
Tutorial

compile 'com.amazonaws:aws-android-sdk-lambda:2.2.+'

3. Build the project so that the required dependencies are downloaded, as needed.
4. In the Android application manifest (AndroidManifest.xml), add the following permissions so
that your application can connect to the Internet. You can add them just before the </manifest>
end tag.

<uses-permission android:name="android.permission.INTERNET" />

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

5. In MainActivity, add the following imports:

import com.amazonaws.mobileconnectors.lambdainvoker.*;
import com.amazonaws.auth.CognitoCachingCredentialsProvider;
import com.amazonaws.regions.Regions;

6. In the package section, add the following two classes (RequestClass and ResponseClass). Note
that the POJO is same as the POJO you created in your Lambda function in the preceding section.

• RequestClass. The instances of this class act as the POJO (Plain Old Java Object) for event data
which consists of first and last name. If you are using Java example for your Lambda function
you created in the preceding section, this POJO is same as the POJO you created in your Lambda
function code.

package com.example....lambdaeventgenerator;
public class RequestClass {
String firstName;
String lastName;

public String getFirstName() {

return firstName;
}

public void setFirstName(String firstName) {

this.firstName = firstName;
}

public String getLastName() {

return lastName;
}

public void setLastName(String lastName) {

this.lastName = lastName;
}

public RequestClass(String firstName, String lastName) {

this.firstName = firstName;
this.lastName = lastName;
}

public RequestClass() {
}
}

• ResponseClass

package com.example....lambdaeventgenerator;
public class ResponseClass {
String greetings;

public String getGreetings() {

return greetings;

169
 AWS Lambda Developer Guide
Tutorial

public void setGreetings(String greetings) {

this.greetings = greetings;
}

public ResponseClass(String greetings) {

this.greetings = greetings;
}

public ResponseClass() {
}
}

7. In the same package, create interface called MyInterface for invoking the
AndroidBackendLambdaFunction Lambda function.

package com.example.....lambdaeventgenerator;
import com.amazonaws.mobileconnectors.lambdainvoker.LambdaFunction;
public interface MyInterface {

/**
* Invoke the Lambda function "AndroidBackendLambdaFunction".
* The function name is the method name.
*/
@LambdaFunction
ResponseClass AndroidBackendLambdaFunction(RequestClass request);

The @LambdaFunction annotation in the code maps the specific client method to the same-name
Lambda function.
8. To keep the application simple, we are going to add code to invoke the Lambda function in the
onCreate() event handler. In MainActivity, add the following code toward the end of the
onCreate() code.

// Create an instance of CognitoCachingCredentialsProvider

CognitoCachingCredentialsProvider cognitoProvider = new
CognitoCachingCredentialsProvider(
this.getApplicationContext(), "identity-pool-id", Regions.US_WEST_2);

// Create LambdaInvokerFactory, to be used to instantiate the Lambda proxy.

LambdaInvokerFactory factory = new LambdaInvokerFactory(this.getApplicationContext(),
Regions.US_WEST_2, cognitoProvider);

// Create the Lambda proxy object with a default Json data binder.
// You can provide your own data binder by implementing
// LambdaDataBinder.
final MyInterface myInterface = factory.build(MyInterface.class);

RequestClass request = new RequestClass("John", "Doe");

// The Lambda function invocation results in a network call.
// Make sure it is not called from the main thread.
new AsyncTask<RequestClass, Void, ResponseClass>() {
@Override
protected ResponseClass doInBackground(RequestClass... params) {
// invoke "echo" method. In case it fails, it will throw a
// LambdaFunctionException.
try {
return myInterface.AndroidBackendLambdaFunction(params[0]);
} catch (LambdaFunctionException lfe) {
Log.e("Tag", "Failed to invoke echo", lfe);
return null;

170
 AWS Lambda Developer Guide
Sample code

}
}

@Override
protected void onPostExecute(ResponseClass result) {
if (result == null) {
return;
}

// Do a toast
Toast.makeText(MainActivity.this, result.getGreetings(),
Toast.LENGTH_LONG).show();
}
}.execute(request);

9. Run the code and verify it as follows:

• The Toast.makeText() displays the response returned.

• Verify that CloudWatch Logs shows the log created by the Lambda function. It should show the
event data (first name and last name). You can also verify this in the AWS Lambda console.

Sample function code

Sample code is available for the following languages.

Topics
• Node.js (p. 171)
• Java (p. 171)

Node.js
The following example uses data to generate a string response.

Example index.js

exports.handler = function(event, context, callback) {

console.log("Received event: ", event);
var data = {
"greetings": "Hello, " + event.firstName + " " + event.lastName + "."
};
callback(null, data);
}

Zip up the sample code to create a deployment package. For instructions, see Deploy Node.js Lambda
functions with .zip file archives (p. 489).

Java
The following example uses data to generate a string response.

In the code, the handler (myHandler) uses the RequestClass and ResponseClass types for the
input and output. The code provides implementation for these types.

Example HelloPojo.java

package example;

171
 AWS Lambda Developer Guide
Sample code

import com.amazonaws.services.lambda.runtime.Context;

public class HelloPojo {

// Define two classes/POJOs for use with Lambda function.

public static class RequestClass {
String firstName;
String lastName;

public String getFirstName() {

return firstName;
}

public void setFirstName(String firstName) {

this.firstName = firstName;
}

public String getLastName() {

return lastName;
}

public void setLastName(String lastName) {

this.lastName = lastName;
}

public RequestClass(String firstName, String lastName) {

this.firstName = firstName;
this.lastName = lastName;
}

public RequestClass() {
}
}

public static class ResponseClass {

String greetings;

public String getGreetings() {

return greetings;
}

public void setGreetings(String greetings) {

this.greetings = greetings;
}

public ResponseClass(String greetings) {

this.greetings = greetings;
}

public ResponseClass() {
}

public static ResponseClass myHandler(RequestClass request, Context context){

String greetingString = String.format("Hello %s, %s.", request.firstName,
request.lastName);
context.getLogger().log(greetingString);
return new ResponseClass(greetingString);
}
}

Dependencies

• aws-lambda-java-core

172
 AWS Lambda Developer Guide
Sample code

Build the code with the Lambda library dependencies to create a deployment package. For instructions,
see Deploy Java Lambda functions with .zip or JAR file archives (p. 578).

173
 AWS Lambda Developer Guide

AWS Lambda applications

An AWS Lambda application is a combination of Lambda functions, event sources, and other resources
that work together to perform tasks. You can use AWS CloudFormation and other tools to collect your
application's components into a single package that can be deployed and managed as one resource.
Applications make your Lambda projects portable and enable you to integrate with additional developer
tools, such as AWS CodePipeline, AWS CodeBuild, and the AWS Serverless Application Model command
line interface (SAM CLI).

The AWS Serverless Application Repository provides a collection of Lambda applications that you
can deploy in your account with a few clicks. The repository includes both ready-to-use applications
and samples that you can use as a starting point for your own projects. You can also submit your own
projects for inclusion.

AWS CloudFormation enables you to create a template that defines your application's resources and lets
you manage the application as a stack. You can more safely add or modify resources in your application
stack. If any part of an update fails, AWS CloudFormation automatically rolls back to the previous
configuration. With AWS CloudFormation parameters, you can create multiple environments for your
application from the same template. AWS SAM (p. 5) extends AWS CloudFormation with a simplified
syntax focused on Lambda application development.

The AWS CLI (p. 5) and SAM CLI (p. 6) are command line tools for managing Lambda application stacks.
In addition to commands for managing application stacks with the AWS CloudFormation API, the AWS
CLI supports higher-level commands that simplify tasks like uploading deployment packages and
updating templates. The AWS SAM CLI provides additional functionality, including validating templates
and testing locally.

When creating an application, you can create its Git repository using either CodeCommit or an AWS
CodeStar connection to GitHub. CodeCommit enables you to use the IAM console to manage SSH keys
and HTTP credentials for your users. AWS CodeStar connections enables you to connect to your GitHub
account. For more information about connections, see What are connections? in the Developer Tools
console User Guide.

For more information about designing Lambda applications, see Application design in the Lambda
operator guide.

Topics
• Managing applications in the AWS Lambda console (p. 175)
• Creating an application with continuous delivery in the Lambda console (p. 178)
• Rolling deployments for Lambda functions (p. 187)
• Common Lambda application types and use cases (p. 189)
• Best practices for working with AWS Lambda functions (p. 192)

174
 AWS Lambda Developer Guide
Manage applications

Managing applications in the AWS Lambda console

The AWS Lambda console helps you monitor and manage your Lambda applications (p. 174). The
Applications menu lists AWS CloudFormation stacks with Lambda functions. The menu includes stacks
that you launch in AWS CloudFormation by using the AWS CloudFormation console, the AWS Serverless
Application Repository, the AWS CLI, or the AWS SAM CLI.

To view a Lambda application

1. Open the Lambda console Applications page.

2. Choose an application.

The overview shows the following information about your application.

• AWS CloudFormation template or SAM template – The template that defines your application.
• Resources – The AWS resources that are defined in your application's template. To manage your
application's Lambda functions, choose a function name from the list.

Monitoring applications
The Monitoring tab shows an Amazon CloudWatch dashboard with aggregate metrics for the resources
in your application.

To monitor a Lambda application

1. Open the Lambda console Applications page.

2. Choose Monitoring.

By default, the Lambda console shows a basic dashboard. You can customize this page by defining
custom dashboards in your application template. When your template includes one or more dashboards,
the page shows your dashboards instead of the default dashboard. You can switch between dashboards
with the drop-down menu on the top right of the page.

Custom monitoring dashboards

Customize your application monitoring page by adding one or more Amazon CloudWatch dashboards to
your application template with the AWS::CloudWatch::Dashboard resource type. The following example
creates a dashboard with a single widget that graphs the number of invocations of a function named
my-function.

175
 AWS Lambda Developer Guide
Custom monitoring dashboards

Example function dashboard template

Resources:
MyDashboard:
Type: AWS::CloudWatch::Dashboard
Properties:
DashboardName: my-dashboard
DashboardBody: |
{
"widgets": [
{
"type": "metric",
"width": 12,
"height": 6,
"properties": {
"metrics": [
[
"AWS/Lambda",
"Invocations",
"FunctionName",
"my-function",
{
"stat": "Sum",
"label": "MyFunction"
}
],
[
{
"expression": "SUM(METRICS())",
"label": "Total Invocations"
}
]
],
"region": "us-east-1",
"title": "Invocations",
"view": "timeSeries",
"stacked": false
}
}
]
}

You can get the definition for any of the widgets in the default monitoring dashboard from the
CloudWatch console.

To view a widget definition

1. Open the Lambda console Applications page.

2. Choose an application that has the standard dashboard.
3. Choose Monitoring.
4. On any widget, choose View in metrics from the drop-down menu.

176
 AWS Lambda Developer Guide
Custom monitoring dashboards

5. Choose Source.

For more information about authoring CloudWatch dashboards and widgets, see Dashboard body
structure and syntax in the Amazon CloudWatch API Reference.

177
 AWS Lambda Developer Guide
Tutorial – Create an application

Creating an application with continuous delivery in

the Lambda console
You can use the Lambda console to create an application with an integrated continuous delivery pipeline.
With continuous delivery, every change that you push to your source control repository triggers a
pipeline that builds and deploys your application automatically. The Lambda console provides starter
projects for common application types with Node.js sample code and templates that create supporting
resources.

In this tutorial, you create the following resources.

• Application – A Node.js Lambda function, build specification, and AWS Serverless Application Model
(AWS SAM) template.
• Pipeline – An AWS CodePipeline pipeline that connects the other resources to enable continuous
delivery.
• Repository – A Git repository in AWS CodeCommit. When you push a change, the pipeline copies the
source code into an Amazon S3 bucket and passes it to the build project.
• Trigger – An Amazon CloudWatch Events rule that watches the main branch of the repository and
triggers the pipeline.
• Build project – An AWS CodeBuild build that gets the source code from the pipeline and packages the
application. The source includes a build specification with commands that install dependencies and
prepare the application template for deployment.
• Deployment configuration – The pipeline's deployment stage defines a set of actions that take
the processed AWS SAM template from the build output, and deploy the new version with AWS
CloudFormation.
• Bucket – An Amazon Simple Storage Service (Amazon S3) bucket for deployment artifact storage.
• Roles – The pipeline's source, build, and deploy stages have IAM roles that allow them to manage AWS
resources. The application's function has an execution role (p. 47) that allows it to upload logs and can
be extended to access other services.

Your application and pipeline resources are defined in AWS CloudFormation templates that you can
customize and extend. Your application repository includes a template that you can modify to add
Amazon DynamoDB tables, an Amazon API Gateway API, and other application resources. The continuous
delivery pipeline is defined in a separate template outside of source control and has its own stack.

The pipeline maps a single branch in a repository to a single application stack. You can create additional
pipelines to add environments for other branches in the same repository. You can also add stages to your
pipeline for testing, staging, and manual approvals. For more information about AWS CodePipeline, see
What is AWS CodePipeline.

Sections
• Prerequisites (p. 179)
• Create an application (p. 179)
• Invoke the function (p. 180)
• Add an AWS resource (p. 181)
• Update the permissions boundary (p. 183)
• Update the function code (p. 183)
• Next steps (p. 184)
• Troubleshooting (p. 185)
• Clean up (p. 186)

178
 AWS Lambda Developer Guide
Prerequisites

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting started with Lambda (p. 9) to create
your first Lambda function.

To complete the following steps, you need a command line terminal or shell to run commands.
Commands and the expected output are listed in separate blocks:

aws --version

You should see the following output:

aws-cli/2.0.57 Python/3.7.4 Darwin/19.6.0 exe/x86_64

For long commands, an escape character (\) is used to split a command over multiple lines.

On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

This tutorial uses CodeCommit for source control. To set up your local machine to access and update
application code, see Setting up in the AWS CodeCommit User Guide.

Create an application
Create an application in the Lambda console. In Lambda, an application is an AWS CloudFormation
stack with a Lambda function and any number of supporting resources. In this tutorial, you create an
application that has a function and its execution role.

To create an application

1. Open the Lambda console Applications page.

2. Choose Create application.
3. Choose Author from scratch.
4. Configure application settings.

• Application name – my-app.

• Runtime – Node.js 10.x.
• Source control service – CodeCommit.
• Repository name – my-app-repo.
• Permissions – Create roles and permissions boundary.
5. Choose Create.

Lambda creates the pipeline and related resources and commits the sample application code to the Git
repository. As resources are created, they appear on the overview page.

179
 AWS Lambda Developer Guide
Invoke the function

The Infrastructure stack contains the repository, build project, and other resources that combine to form
a continuous delivery pipeline. When this stack finishes deploying, it in turn deploys the application stack
that contains the function and execution role. These are the application resources that appear under
Resources.

Invoke the function

When the deployment process completes, invoke the function from the Lambda console.

To invoke the application's function

1. Open the Lambda console Applications page.

2. Choose my-app.
3. Under Resources, choose helloFromLambdaFunction.
4. Choose Test.
5. Configure a test event.

• Event name – event

• Body – {}
6. Choose Create.
7. Choose Test.

The Lambda console runs your function and displays the result. Expand the Details section under the
result to see the output and execution details.

180
 AWS Lambda Developer Guide
Add an AWS resource

Add an AWS resource

In the previous step, Lambda console created a Git repository that contains function code, a template,
and a build specification. You can add resources to your application by modifying the template and
pushing changes to the repository. To get a copy of the application on your local machine, clone the
repository.

To clone the project repository

1. Open the Lambda console Applications page.

2. Choose my-app.
3. Choose Code.
4. Under Repository details, copy the HTTP or SSH repository URI, depending on the authentication
mode that you configured during setup (p. 179).
5. To clone the repository, use the git clone command.

git clone ssh://git-codecommit.us-east-2.amazonaws.com/v1/repos/my-app-repo

To add a DynamoDB table to the application, define an AWS::Serverless::SimpleTable resource in

the template.

To add a DynamoDB table

1. Open template.yml in a text editor.

2. Add a table resource, an environment variable that passes the table name to the function, and a
permissions policy that allows the function to manage it.

Example template.yml - resources

...
Resources:
ddbTable:
Type: AWS::Serverless::SimpleTable
Properties:

181
 AWS Lambda Developer Guide
Add an AWS resource

PrimaryKey:
Name: id
Type: String
ProvisionedThroughput:
ReadCapacityUnits: 1
WriteCapacityUnits: 1
helloFromLambdaFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./
Handler: src/handlers/hello-from-lambda.helloFromLambdaHandler
Runtime: nodejs10.x
MemorySize: 128
Timeout: 60
Description: A Lambda function that returns a static string.
Environment:
Variables:
DDB_TABLE: !Ref ddbTable
Policies:
- DynamoDBCrudPolicy:
TableName: !Ref ddbTable
- AWSLambdaBasicExecutionRole

3. Commit and push the change.

git commit -am "Add DynamoDB table"

git push

When you push a change, it triggers the application's pipeline. Use the Deployments tab of the
application screen to track the change as it flows through the pipeline. When the deployment is
complete, proceed to the next step.

182
 AWS Lambda Developer Guide
Update the permissions boundary

Update the permissions boundary

The sample application applies a permissions boundary to its function's execution role. The permissions
boundary limits the permissions that you can add to the function's role. Without the boundary, users
with write access to the project repository could modify the project template to give the function
permission to access resources and services outside of the scope of the sample application.

In order for the function to use the DynamoDB permission that you added to its execution role in the
previous step, you must extend the permissions boundary to allow the additional permissions. The
Lambda console detects resources that aren't in the permissions boundary and provides an updated
policy that you can use to update it.

To update the application's permissions boundary

1. Open the Lambda console Applications page.

2. Choose your application.
3. Under Resources, choose Edit permissions boundary.
4. Follow the instructions shown to update the boundary to allow access to the new table.

For more information about permissions boundaries, see Using permissions boundaries for AWS Lambda
applications (p. 67).

Update the function code

Next, update the function code to use the table. The following code uses the DynamoDB table to track
the number of invocations processed by each instance of the function. It uses the log stream ID as a
unique identifier for the function instance.

To update the function code

1. Add a new handler named index.js to the src/handlers folder with the following content.

Example src/handlers/index.js

const dynamodb = require('aws-sdk/clients/dynamodb');

const docClient = new dynamodb.DocumentClient();

exports.handler = async (event, context) => {

const message = 'Hello from Lambda!';
const tableName = process.env.DDB_TABLE;
const logStreamName = context.logStreamName;
var params = {
TableName : tableName,
Key: { id : logStreamName },
UpdateExpression: 'set invocations = if_not_exists(invocations, :start)
+ :inc',
ExpressionAttributeValues: {
':start': 0,
':inc': 1
},
ReturnValues: 'ALL_NEW'
};
await docClient.update(params).promise();

const response = {
body: JSON.stringify(message)
};
console.log(`body: ${response.body}`);
return response;

183
 AWS Lambda Developer Guide
Next steps

2. Open the application template and change the handler value to src/handlers/index.handler.

Example template.yml

...
helloFromLambdaFunction:
Type: AWS::Serverless::Function
Properties:
CodeUri: ./
Handler: src/handlers/index.handler
Runtime: nodejs10.x

3. Commit and push the change.

git add . && git commit -m "Use DynamoDB table"

git push

After the code change is deployed, invoke the function a few times to update the DynamoDB table.

To view the DynamoDB table

1. Open the Tables page of the DynamoDB console.

2. Choose the table that starts with my-app.
3. Choose Items.
4. Choose Start search.

Lambda creates additional instances of your function to handle multiple concurrent invocations. Each log
stream in the CloudWatch Logs log group corresponds to a function instance. A new function instance
is also created when you change your function's code or configuration. For more information on scaling,
see AWS Lambda function scaling (p. 153).

Next steps
The AWS CloudFormation template that defines your application resources uses the AWS Serverless
Application Model transform to simplify the syntax for resource definitions, and automate uploading

184
 AWS Lambda Developer Guide
Troubleshooting

the deployment package and other artifacts. AWS SAM also provides a command line interface (the AWS
SAM CLI), which has the same packaging and deployment functionality as the AWS CLI, with additional
features specific to Lambda applications. Use the AWS SAM CLI to test your application locally in a
Docker container that emulates the Lambda execution environment.

• Installing the AWS SAM CLI

• Testing and debugging serverless applications

AWS Cloud9 provides an online development environment that includes Node.js, the AWS SAM CLI, and
Docker. With AWS Cloud9, you can start developing quickly and access your development environment
from any computer. For instructions, see Getting started in the AWS Cloud9 User Guide.

For local development, AWS toolkits for integrated development environments (IDEs) let you test and
debug functions before pushing them to your repository.

• AWS Toolkit for JetBrains – Plugin for PyCharm (Python) and IntelliJ (Java) IDEs.
• AWS Toolkit for Eclipse – Plugin for Eclipse IDE (multiple languages).
• AWS Toolkit for Visual Studio Code – Plugin for Visual Studio Code IDE (multiple languages).
• AWS Toolkit for Visual Studio – Plugin for Visual Studio IDE (multiple languages).

Troubleshooting
As you develop your application, you will likely encounter the following types of errors.

• Build errors – Issues that occur during the build phase, including compilation, test, and packaging
errors.
• Deployment errors – Issues that occur when AWS CloudFormation isn't able to update the application
stack. These include permissions errors, account quotas, service issues, or template errors.
• Invocation errors – Errors that are returned by a function's code or runtime.

For build and deployment errors, you can identify the cause of an error in the Lambda console.

To troubleshoot application errors

1. Open the Lambda console Applications page.

2. Choose an application.
3. Choose Deployments.
4. To view the application's pipeline, choose Deployment pipeline.
5. Identify the action that encountered an error.
6. To view the error in context, choose Details.

For deployment errors that occur during the ExecuteChangeSet action, the pipeline links to a list of
stack events in the AWS CloudFormation console. Search for an event with the status UPDATE_FAILED.
Because AWS CloudFormation rolls back after an error, the relevant event is under several other events
in the list. If AWS CloudFormation could not create a change set, the error appears under Change sets
instead of under Events.

A common cause of deployment and invocation errors is a lack of permissions in one or more roles.
The pipeline has a role for deployments (CloudFormationRole) that's equivalent to the user
permissions (p. 56) that you would use to update an AWS CloudFormation stack directly. If you add
resources to your application or enable Lambda features that require user permissions, the deployment
role is used. You can find a link to the deployment role under Infrastructure in the application overview.

185
 AWS Lambda Developer Guide
Clean up

If your function accesses other AWS services or resources, or if you enable features that require the
function to have additional permissions, the function's execution role (p. 47) is used. All execution roles
that are created in your application template are also subject to the application's permissions boundary.
This boundary requires you to explicitly grant access to additional services and resources in IAM after
adding permissions to the execution role in the template.

For example, to connect a function to a virtual private cloud (p. 111) (VPC), you need user permissions to
describe VPC resources. The execution role needs permission to manage network interfaces. This requires
the following steps.

1. Add the required user permissions to the deployment role in IAM.

2. Add the execution role permissions to the permissions boundary in IAM.
3. Add the execution role permissions to the execution role in the application template.
4. Commit and push to deploy the updated execution role.

After you address permissions errors, choose Release change in the pipeline overview to rerun the build
and deployment.

Clean up
You can continue to modify and use the sample to develop your own application. If you are done using
the sample, delete the application to avoid paying for the pipeline, repository, and storage.

To delete the application

1. Open the AWS CloudFormation console.

2. Delete the application stack – my-app.
3. Open the Amazon S3 console.
4. Delete the artifact bucket – us-east-2-123456789012-my-app-pipe.
5. Return to the AWS CloudFormation console and delete the infrastructure stack – serverlessrepo-
my-app-toolchain.

Function logs are not associated with the application or infrastructure stack in AWS CloudFormation.
Delete the log group separately in the CloudWatch Logs console.

To delete the log group

1. Open the Log groups page of the Amazon CloudWatch console.

2. Choose the function's log group (/aws/lambda/my-app-
helloFromLambdaFunction-YV1VXMPLK7QK).
3. Choose Actions, and then choose Delete log group.
4. Choose Yes, Delete.

186
 AWS Lambda Developer Guide
Rolling deployments

Rolling deployments for Lambda functions

Use rolling deployments to control the risks associated with introducing new versions of your Lambda
function. In a rolling deployment, the system automatically deploys the new version of the function and
gradually sends an increasing amount of traffic to the new version. The amount of traffic and rate of
increase are parameters that you can configure.

You configure a rolling deployment by using AWS CodeDeploy and AWS SAM. CodeDeploy is a service
that automates application deployments to Amazon computing platforms such as Amazon EC2 and AWS
Lambda. For more information, see What is CodeDeploy?. By using CodeDeploy to deploy your Lambda
function, you can easily monitor the status of the deployment and initiate a rollback if you detect any
issues.

AWS SAM is an open-source framework for building serverless applications. You create an AWS
SAM template (in YAML format) to specify the configuration of the components required for the
rolling deployment. AWS SAM uses the template to create and configure the components. For more
information, see What is the AWS SAM?.

In a rolling deployment, AWS SAM performs these tasks:

• It configures your Lambda function and creates an alias.

The alias routing configuration is the underlying capability that implements the rolling deployment.
• It creates a CodeDeploy application and deployment group.

The deployment group manages the rolling deployment and the rollback (if needed).
• It detects when you create a new version of your Lambda function.
• It triggers CodeDeploy to start the deployment of the new version.

Example AWS SAM Lambda template

The following example shows an AWS SAM template for a simple rolling deployment.

AWSTemplateFormatVersion : '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: A sample SAM template for deploying Lambda functions.

Resources:
# Details about the myDateTimeFunction Lambda function
myDateTimeFunction:
Type: AWS::Serverless::Function
Properties:
Handler: myDateTimeFunction.handler
Runtime: nodejs12.x
# Creates an alias named "live" for the function, and automatically publishes when you
update the function.
AutoPublishAlias: live
DeploymentPreference:
# Specifies the deployment configuration
Type: Linear10PercentEvery2Minutes

This template defines a Lambda function named myDateTimeFunction with the following properties.

187
 AWS Lambda Developer Guide
Example AWS SAM Lambda template

AutoPublishAlias

The AutoPublishAlias property creates an alias named live. In addition, the AWS SAM
framework automatically detects when you save new code for the function. The framework then
publishes a new function version and updates the live alias to point to the new version.
DeploymentPreference

The DeploymentPreference property determines the rate at which the CodeDeploy application
shifts traffic from the original version of the Lambda function to the new version. The value
Linear10PercentEvery2Minutes shifts an additional ten percent of the traffic to the new
version every two minutes.

For a list of the predefined deployment configurations, see Deployment configurations.

For a detailed tutorial on how to use CodeDeploy with Lambda functions, see Deploy an updated
Lambda function with CodeDeploy.

188
 AWS Lambda Developer Guide
Use cases

Common Lambda application types and use cases

When building applications on AWS Lambda the core components are Lambda functions and triggers. A
trigger is the AWS service or application that invokes a function, and a Lambda function is the code and
runtime that process events. To illustrate, consider the following scenarios:

• File processing – Suppose you have a photo sharing application. People use your application to upload
photos, and the application stores these user photos in an Amazon S3 bucket. Then, your application
creates a thumbnail version of each user's photos and displays them on the user's profile page. In this
scenario, you may choose to create a Lambda function that creates a thumbnail automatically. Amazon
S3 is one of the supported AWS event sources that can publish object-created events and invoke your
Lambda function. Your Lambda function code can read the photo object from the S3 bucket, create a
thumbnail version, and then save it in another S3 bucket.
• Data and analytics – Suppose you are building an analytics application and storing raw data in a
DynamoDB table. When you write, update, or delete items in a table, DynamoDB streams can publish
item update events to a stream associated with the table. In this case, the event data provides the
item key, event name (such as insert, update, and delete), and other relevant details. You can write a
Lambda function to generate custom metrics by aggregating raw data.
• Websites – Suppose you are creating a website and you want to host the backend logic on Lambda.
You can invoke your Lambda function over HTTP using Amazon API Gateway as the HTTP endpoint.
Now, your web client can invoke the API, and then API Gateway can route the request to Lambda.
• Mobile applications – Suppose you have a custom mobile application that produces events. You can
create a Lambda function to process events published by your custom application. For example, in
this scenario you can configure a Lambda function to process the clicks within your custom mobile
application.

AWS Lambda supports many AWS services as event sources. For more information, see Using AWS
Lambda with other services (p. 257). When you configure these event sources to trigger a Lambda
function, the Lambda function is invoked automatically when events occur. You define event source
mapping, which is how you identify what events to track and which Lambda function to invoke.

The following are introductory examples of event sources and how the end-to-end experience works.

Example 1: Amazon S3 pushes events and invokes a

Lambda function
Amazon S3 can publish events of different types, such as PUT, POST, COPY, and DELETE object events on
a bucket. Using the bucket notification feature, you can configure an event source mapping that directs
Amazon S3 to invoke a Lambda function when a specific type of event occurs, as shown in the following
illustration.

189
 AWS Lambda Developer Guide
Example 2: AWS Lambda pulls events from a
Kinesis stream and invokes a Lambda function

The diagram illustrates the following sequence:

1. The user creates an object in a bucket.

2. Amazon S3 detects the object created event.
3. Amazon S3 invokes your Lambda function using the permissions provided by the execution
role (p. 47).
4. AWS Lambda runs the Lambda function, specifying the event as a parameter.

You configure Amazon S3 to invoke your function as a bucket notification action. To grant Amazon S3
permission to invoke the function, update the function's resource-based policy (p. 51).

Example 2: AWS Lambda pulls events from a Kinesis

stream and invokes a Lambda function
For poll-based event sources, AWS Lambda polls the source and then invokes the Lambda function when
records are detected on that source.

• CreateEventSourceMapping (p. 754)

• UpdateEventSourceMapping (p. 919)

The following diagram shows how a custom application writes records to a Kinesis stream.

190
 AWS Lambda Developer Guide
Example 2: AWS Lambda pulls events from a
Kinesis stream and invokes a Lambda function

The diagram illustrates the following sequence:

1. The custom application writes records to a Kinesis stream.

2. AWS Lambda continuously polls the stream, and invokes the Lambda function when the service
detects new records on the stream. AWS Lambda knows which stream to poll and which Lambda
function to invoke based on the event source mapping you create in Lambda.
3. The Lambda function is invoked with the incoming event.

When working with stream-based event sources, you create event source mappings in AWS Lambda.
Lambda reads items from the stream invokes the function synchronously. You don't need to grant
Lambda permission to invoke the function, but it does need permission to read from the stream.

191
 AWS Lambda Developer Guide
Best practices

Best practices for working with AWS Lambda

functions
The following are recommended best practices for using AWS Lambda:

Topics
• Function code (p. 192)
• Function configuration (p. 193)
• Metrics and alarms (p. 194)
• Working with streams (p. 194)

For more information about best practices for Lambda applications, see Application design in the
Lambda operator guide.

Function code
• Separate the Lambda handler from your core logic. This allows you to make a more unit-testable
function. In Node.js this may look like:

exports.myHandler = function(event, context, callback) {

var foo = event.foo;
var bar = event.bar;
var result = MyLambdaFunction (foo, bar);

callback(null, result);
}

function MyLambdaFunction (foo, bar) {

// MyLambdaFunction logic here
}

• Take advantage of execution environment reuse to improve the performance of your function.
Initialize SDK clients and database connections outside of the function handler, and cache static assets
locally in the /tmp directory. Subsequent invocations processed by the same instance of your function
can reuse these resources. This saves cost by reducing function run time.

To avoid potential data leaks across invocations, don’t use the execution environment to store user
data, events, or other information with security implications. If your function relies on a mutable state
that can’t be stored in memory within the handler, consider creating a separate function or separate
versions of a function for each user.
• Use a keep-alive directive to maintain persistent connections. Lambda purges idle connections over
time. Attempting to reuse an idle connection when invoking a function will result in a connection error.
To maintain your persistent connection, use the keep-alive directive associated with your runtime. For
an example, see Reusing Connections with Keep-Alive in Node.js.
• Use environment variables (p. 77) to pass operational parameters to your function. For example, if
you are writing to an Amazon S3 bucket, instead of hard-coding the bucket name you are writing to,
configure the bucket name as an environment variable.
• Control the dependencies in your function's deployment package. The AWS Lambda execution
environment contains a number of libraries such as the AWS SDK for the Node.js and Python runtimes
(a full list can be found here: Lambda runtimes (p. 195)). To enable the latest set of features and
security updates, Lambda will periodically update these libraries. These updates may introduce subtle
changes to the behavior of your Lambda function. To have full control of the dependencies your
function uses, package all of your dependencies with your deployment package.

192
 AWS Lambda Developer Guide
Function configuration

• Minimize your deployment package size to its runtime necessities. This will reduce the amount of
time that it takes for your deployment package to be downloaded and unpacked ahead of invocation.
For functions authored in Java or .NET Core, avoid uploading the entire AWS SDK library as part of
your deployment package. Instead, selectively depend on the modules which pick up components of
the SDK you need (e.g. DynamoDB, Amazon S3 SDK modules and Lambda core libraries).
• Reduce the time it takes Lambda to unpack deployment packages authored in Java by putting your
dependency .jar files in a separate /lib directory. This is faster than putting all your function’s code
in a single jar with a large number of .class files. See Deploy Java Lambda functions with .zip or JAR
file archives (p. 578) for instructions.
• Minimize the complexity of your dependencies. Prefer simpler frameworks that load quickly on
execution environment (p. 200) startup. For example, prefer simpler Java dependency injection (IoC)
frameworks like Dagger or Guice, over more complex ones like Spring Framework.
• Avoid using recursive code in your Lambda function, wherein the function automatically calls itself
until some arbitrary criteria is met. This could lead to unintended volume of function invocations and
escalated costs. If you do accidentally do so, set the function reserved concurrency to 0 immediately to
throttle all invocations to the function, while you update the code.

Function configuration
• Performance testing your Lambda function is a crucial part in ensuring you pick the optimum
memory size configuration. Any increase in memory size triggers an equivalent increase in CPU
available to your function. The memory usage for your function is determined per-invoke and can be
viewed in Amazon CloudWatch. On each invoke a REPORT: entry will be made, as shown below:

REPORT RequestId: 3604209a-e9a3-11e6-939a-754dd98c7be3 Duration: 12.34 ms Billed

Duration: 100 ms Memory Size: 128 MB Max Memory Used: 18 MB

By analyzing the Max Memory Used: field, you can determine if your function needs more memory
or if you over-provisioned your function's memory size.

To find the right memory configuration for your functions, we recommend using the open source
AWS Lambda Power Tuning project. For more information, see AWS Lambda Power Tuning on GitHub.

To optimize function performance, we also recommend deploying libraries that can leverage Advanced
Vector Extensions 2 (AVX2). This allows you to process demanding workloads, including machine
learning inferencing, media processing, high performance computing (HPC), scientific simulations, and
financial modeling. For more information, see Creating faster AWS Lambda functions with AVX2.
• Load test your Lambda function to determine an optimum timeout value. It is important to analyze
how long your function runs so that you can better determine any problems with a dependency
service that may increase the concurrency of the function beyond what you expect. This is especially
important when your Lambda function makes network calls to resources that may not handle
Lambda's scaling.
• Use most-restrictive permissions when setting IAM policies. Understand the resources and
operations your Lambda function needs, and limit the execution role to these permissions. For more
information, see AWS Lambda permissions (p. 46).
• Be familiar with Lambda quotas (p. 44). Payload size, file descriptors and /tmp space are often
overlooked when determining runtime resource limits.
• Delete Lambda functions that you are no longer using. By doing so, the unused functions won't
needlessly count against your deployment package size limit.
• If you are using Amazon Simple Queue Service as an event source, make sure the value of the
function's expected invocation time does not exceed the Visibility Timeout value on the queue. This
applies both to CreateFunction (p. 763) and UpdateFunctionConfiguration (p. 936).
• In the case of CreateFunction, AWS Lambda will fail the function creation process.

193
 AWS Lambda Developer Guide
Metrics and alarms

• In the case of UpdateFunctionConfiguration, it could result in duplicate invocations of the function.

Metrics and alarms

• Use Working with AWS Lambda function metrics (p. 692) and CloudWatch Alarms instead of
creating or updating a metric from within your Lambda function code. It's a much more efficient way
to track the health of your Lambda functions, allowing you to catch issues early in the development
process. For instance, you can configure an alarm based on the expected duration of your Lambda
function invocation in order to address any bottlenecks or latencies attributable to your function code.
• Leverage your logging library and AWS Lambda Metrics and Dimensions to catch app errors (e.g.
ERR, ERROR, WARNING, etc.)

Working with streams

• Test with different batch and record sizes so that the polling frequency of each event source is tuned
to how quickly your function is able to complete its task. BatchSize (p. 755) controls the maximum
number of records that can be sent to your function with each invoke. A larger batch size can often
more efficiently absorb the invoke overhead across a larger set of records, increasing your throughput.

By default, Lambda invokes your function as soon as records are available in the stream. If the batch
that Lambda reads from the stream only has one record in it, Lambda sends only one record to the
function. To avoid invoking the function with a small number of records, you can tell the event source
to buffer records for up to five minutes by configuring a batch window. Before invoking the function,
Lambda continues to read records from the stream until it has gathered a full batch, or until the batch
window expires.
• Increase Kinesis stream processing throughput by adding shards. A Kinesis stream is composed
of one or more shards. Lambda will poll each shard with at most one concurrent invocation. For
example, if your stream has 100 active shards, there will be at most 100 Lambda function invocations
running concurrently. Increasing the number of shards will directly increase the number of maximum
concurrent Lambda function invocations and can increase your Kinesis stream processing throughput.
If you are increasing the number of shards in a Kinesis stream, make sure you have picked a good
partition key (see Partition Keys) for your data, so that related records end up on the same shards and
your data is well distributed.
• Use Amazon CloudWatch on IteratorAge to determine if your Kinesis stream is being processed. For
example, configure a CloudWatch alarm with a maximum setting to 30000 (30 seconds).

194
 AWS Lambda Developer Guide

Lambda runtimes
Lambda supports multiple languages through the use of runtimes (p. 30). For a function defined as a
container image (p. 72), you choose a runtime and the Linux distribution when you create the container
image (p. 248). To change the runtime, you create a new container image.

When you use a .zip file archive for the deployment package, you choose a runtime when you create
the function. To change the runtime, you can update your function's configuration (p. 70). The runtime
is paired with one of the Amazon Linux distributions. The underlying execution environment provides
additional libraries and environment variables (p. 77) that you can access from your function code.

Amazon Linux

• Image – amzn-ami-hvm-2018.03.0.20181129-x86_64-gp2
• Linux kernel – 4.14.171-105.231.amzn1.x86_64

Amazon Linux 2

• Image – Custom
• Linux kernel – 4.14.165-102.205.amzn2.x86_64

When your function is invoked, Lambda attempts to re-use the execution environment from a previous
invocation if one is available. This saves time preparing the execution environment, and it allows you to
save resources such as database connections and temporary files in the execution environment (p. 200)
to avoid creating them every time your function runs.

A runtime can support a single version of a language, multiple versions of a language, or multiple
languages. Runtimes specific to a language or framework version are deprecated (p. 198) when the
version reaches end of life.

Node.js runtimes

Name Identifier SDK for JavaScript Operating system

Node.js 14 nodejs14.x 2.880.0 Amazon Linux 2

Node.js 12 nodejs12.x 2.880.0 Amazon Linux 2

Node.js 10 nodejs10.x 2.880.0 Amazon Linux 2

Note
For end of support information about Node.js 10, see the section called “Runtime support
policy” (p. 198).

Python runtimes

Name Identifier AWS SDK for Operating system

Python

Python 3.8 python3.8 boto3-1.17.42 Amazon Linux 2

botocore-1.20.42

Python 3.7 python3.7 boto3-1.17.42 Amazon Linux

botocore-1.20.42

195
 AWS Lambda Developer Guide

Name Identifier AWS SDK for Operating system

Python

Python 3.6 python3.6 boto3-1.17.42 Amazon Linux

botocore-1.20.42

Python 2.7 python2.7 boto3-1.17.42 Amazon Linux

botocore-1.20.42

Important
Python 2.7 reached end of life on January 1, 2020. End of support (phase 1) for the Python
2.7 runtime starts on July 15, 2021. For more information, see Announcing end of support for
Python 2.7 in AWS Lambda on the AWS Compute Blog.

Ruby runtimes

Name Identifier SDK for Ruby Operating system

Ruby 2.7 ruby2.7 3.0.1 Amazon Linux 2

Ruby 2.5 ruby2.5 3.0.1 Amazon Linux

Note
For end of support information about Ruby 2.5, see the section called “Runtime support
policy” (p. 198).

Java runtimes

Name Identifier JDK Operating system

Java 11 java11 amazon-corretto-11 Amazon Linux 2

Java 8 java8.al2 amazon-corretto-8 Amazon Linux 2

Java 8 java8 java-1.8.0-openjdk Amazon Linux

Go runtimes

Name Identifier Operating system

Go 1.x go1.x Amazon Linux

.NET runtimes

Name Identifier Operating system

.NET Core 3.1 dotnetcore3.1 Amazon Linux 2

.NET Core 2.1 dotnetcore2.1 Amazon Linux

Note
For end of support information about .NET Core 2.1, see the section called “Runtime support
policy” (p. 198).

196
 AWS Lambda Developer Guide

To use other languages in Lambda, you can implement a custom runtime (p. 236). The Lambda
execution environment provides a runtime interface (p. 205) for getting invocation events and sending
responses. You can deploy a custom runtime alongside your function code, or in a layer (p. 101).

Custom runtime

Name Identifier Operating system

Custom Runtime provided.al2 Amazon Linux 2

Custom Runtime provided Amazon Linux

Topics
• Runtime support policy (p. 198)
• AWS Lambda execution environment (p. 200)
• Runtime support for Lambda container images (p. 203)
• AWS Lambda runtime API (p. 205)
• Lambda Extensions API (p. 209)
• Lambda Logs API (p. 223)
• Modifying the runtime environment (p. 231)
• Custom AWS Lambda runtimes (p. 236)
• Tutorial – Publishing a custom runtime (p. 239)
• Using AVX2 vectorization in Lambda (p. 245)

197
 AWS Lambda Developer Guide
Runtime support policy

Runtime support policy

Lambda runtimes (p. 195) for .zip file archives are built around a combination of operating system,
programming language, and software libraries that are subject to maintenance and security updates.
When security updates are no longer available for a component of a runtime, Lambda deprecates the
runtime.

Deprecation (end of support) for a runtime occurs in two phases. In phase 1, Lambda no longer applies
security patches or other updates to the runtime. You can no longer create functions that use the
runtime, but you can continue to update existing functions. This includes updating the runtime version,
and rolling back to the previous runtime version. Note that functions that use a deprecated runtime are
no longer eligible for technical support.

In phase 2, which starts at least 30 days after the start of phase 1, you can no longer create or update
functions that use the runtime. To update a function, you need to migrate it to a supported runtime
version. After you migrate the function to a supported runtime version, you cannot rollback the function
to the previous runtime.

Lambda does not block invocations of functions that use deprecated runtime versions. Function
invocations continue indefinitely after the runtime version reaches end of support. However, AWS
strongly recommends that you migrate functions to a supported runtime version so that you continue to
receive security patches and remain eligible for technical support.
Important
Python 2.7 reached end of life on January 1, 2020. End of support (phase 1) for the Python
2.7 runtime starts on July 15, 2021. For more information, see Announcing end of support for
Python 2.7 in AWS Lambda on the AWS Compute Blog.

The following runtimes have reached or are scheduled for end of support:

Runtime end of support dates

Name Identifier Operating system End of support End of support

phase 1 start phase 2 start

.NET Core 2.1 dotnetcore2.1 Amazon Linux Aug 23, 2021 Sept 23, 2021

Python 2.7 python2.7 Amazon Linux July 15, 2021 Sept 30, 2021

Ruby 2.5 ruby2.5 Amazon Linux July 30, 2021 Aug 30, 2021

Node.js 10.x nodejs10.x Amazon Linux 2 July 30, 2021 Aug 30, 2021

Node.js 8.10 nodejs8.10 Amazon Linux March 6, 2020

Node.js 6.10 nodejs6.10 Amazon Linux August 12, 2019

Node.js 4.3 edge nodejs4.3-edge Amazon Linux April 30, 2019

Node.js 4.3 nodejs4.3 Amazon Linux March 6, 2020

Node.js 0.10 nodejs Amazon Linux October 31, 2016

.NET Core 2.0 dotnetcore2.0 Amazon Linux May 30, 2019

.NET Core 1.0 dotnetcore1.0 Amazon Linux July 30, 2019

In almost all cases, the end-of-life date of a language version or operating system is known well in
advance. Lambda notifies you by email if you have functions using a runtime that is scheduled for end of

198
 AWS Lambda Developer Guide
Runtime support policy

support in the next 60 days. In rare cases, advance notice of support ending might not be possible. For
example, security issues that require a backwards-incompatible update, or a runtime component that
doesn't provide a long-term support (LTS) schedule.

Language and framework support policies

• Node.js – github.com
• Python – devguide.python.org
• Ruby – www.ruby-lang.org
• Java – www.oracle.com and Corretto FAQs
• Go – golang.org
• .NET Core – dotnet.microsoft.com

199
 AWS Lambda Developer Guide
Execution environment

AWS Lambda execution environment

Lambda invokes your function in an execution environment, which provides a secure and isolated
runtime environment. The execution environment manages the resources required to run your function.
The execution environment also provides lifecycle support for the function's runtime and any external
extensions (p. 160) associated with your function.

The function's runtime communicates with Lambda using the Runtime API (p. 205). Extensions
communicate with Lambda using the Extensions API (p. 209). Extensions can also receive log messages
from the function by subscribing to logs using the Logs API (p. 223).

When you create your Lambda function, you specify configuration information, such as the amount
of memory available and the maximum execution time allowed for your function. Lambda uses this
information to set up the execution environment.

The function's runtime and each external extension are processes that run within the execution
environment. Permissions, resources, credentials, and environment variables are shared between the
function and the extensions.

Lambda execution environment lifecycle

The lifecycle of the execution environment includes the following phases:

• Init: In this phase, Lambda creates or unfreezes an execution environment with the configured
resources, downloads the code for the function and all layers, initializes any extensions, initializes the
runtime, and then runs the function’s initialization code (the code outside the main handler). The Init
phase happens either during the first invocation, or in advance of function invocations if you have
enabled provisioned concurrency (p. 87).

The Init phase is split into three sub-phases: Extension init, Runtime init, and Function
init. These sub-phases ensure that all extensions and the runtime complete their setup tasks before
the function code runs.
• Invoke: In this phase, Lambda invokes the function handler. After the function runs to completion,
Lambda prepares to handle another function invocation.
• Shutdown: This phase is triggered if the Lambda function does not receive any invocations for a period
of time. In the Shutdown phase, Lambda shuts down the runtime, alerts the extensions to let them
stop cleanly, and then removes the environment. Lambda sends a Shutdown event to each extension,
which tells the extension that the environment is about to be shut down.

200
 AWS Lambda Developer Guide
Runtime lifecycle

Each phase starts with an event that Lambda sends to the runtime and to all registered extensions. The
runtime and each extension indicate completion by sending a Next API request. Lambda freezes the
execution environment when the runtime and each extension have completed and there are no pending
events.

Topics
• Init phase (p. 201)
• Invoke phase (p. 201)
• Shutdown phase (p. 202)

Init phase
In the Init phase, Lambda performs three tasks:

• Start all extensions (Extension init)

• Bootstrap the runtime (Runtime init)
• Run the function's static code (Function init)

The Init phase ends when the runtime and all extensions signal that they are ready by sending a
Next API request. The Init phase is limited to 10 seconds. If all three tasks do not complete within 10
seconds, Lambda retries the Init phase at the time of the first function invocation.

Invoke phase
When a Lambda function is invoked in response to a Next API request, Lambda sends an Invoke event
to the runtime and to each extension.

The function's timeout setting limits the duration of the entire Invoke phase. For example, if you set the
function timeout as 360 seconds, the function and all extensions need to complete within 360 seconds.
Note that there is no independent post-invoke phase. The duration is the sum of all invocation time
(runtime + extensions) and is not calculated until the function and all extensions have finished executing.

The invoke phase ends after the runtime and all extensions signal that they are done by sending a Next
API request.

If the Lambda function crashes or times out during the Invoke phase, Lambda resets the execution
environment. The reset behaves like a Shutdown event. First, Lambda shuts down the runtime. Then
Lambda sends a Shutdown event to each registered external extension. The event includes the reason
for the shutdown. If another Invoke event results in this execution environment being reused, Lambda
initializes the runtime and extensions as part of the next invocation.

201
 AWS Lambda Developer Guide
Runtime lifecycle

Shutdown phase
When Lambda is about to shut down the runtime, it sends a Shutdown event to the runtime and to
each external extension. Extensions can use this time for final cleanup tasks. The Shutdown event is a
response to a Next API request.

Duration: The entire Shutdown phase is capped at 2 seconds. If the runtime or any extension does not
respond, Lambda terminates it via a signal (SIGKILL).

After the function and all extensions have completed, Lambda maintains the execution environment
for some time in anticipation of another function invocation. In effect, Lambda freezes the execution
environment. When the function is invoked again, Lambda thaws the environment for reuse. Reusing the
execution environment has the following implications:

• Objects declared outside of the function's handler method remain initialized, providing additional
optimization when the function is invoked again. For example, if your Lambda function establishes
a database connection, instead of reestablishing the connection, the original connection is used in
subsequent invocations. We recommend adding logic in your code to check if a connection exists
before creating a new one.
• Each execution environment provides 512 MB of disk space in the /tmp directory. The directory
content remains when the execution environment is frozen, providing a transient cache that can be
used for multiple invocations. You can add extra code to check if the cache has the data that you
stored. For more information on deployment size limits, see Lambda quotas (p. 44).
• Background processes or callbacks that were initiated by your Lambda function and did not complete
when the function ended resume if Lambda reuses the execution environment. Make sure that any
background processes or callbacks in your code are complete before the code exits.

When you write your function code, do not assume that Lambda automatically reuses the execution
environment for subsequent function invocations. Other factors may dictate a need for Lambda to
create a new execution environment, which can lead to unexpected results, such as database connection
failures.

202
 AWS Lambda Developer Guide
Container images

Runtime support for Lambda container images

AWS provides a set of open-source base images that you can use. You can also use a preferred
community or private base image. Lambda provides client software that you add to your preferred base
image to make it compatible with the Lambda service.

Topics
• AWS base images for Lambda (p. 203)
• Base images for custom runtimes (p. 203)
• Runtime interface clients (p. 203)
• Runtime interface emulator (p. 204)

AWS base images for Lambda

You can use one of the AWS base images for Lambda to build the container image for your function
code. The base images are preloaded with a language runtime and other components required to run a
container image on Lambda. You add your function code and dependencies to the base image and then
package it as a container image.

AWS will maintain and regularly update these images. In addition, AWS will release an AWS base images
when any new managed runtime becomes available.

Lambda provides base images for the following runtimes:

• Node.js (p. 492)

• Python (p. 529)
• Java (p. 585)
• .NET (p. 651)
• Go (p. 620)
• Ruby (p. 554)

Base images for custom runtimes

AWS provides base images that contain the required Lambda components and the Amazon Linux or
Amazon Linux2 operating system. You can add your preferred runtime, dependencies and code to these
images.

Tags Runtime Operating system

al2 provided.al2 Amazon Linux 2

alami provided Amazon Linux

DockerHub: amazon/aws-lambda-provided

ECR Public: public.ecr.aws/lambda/provided

Runtime interface clients

The runtime interface client in your container image manages the interaction between Lambda and your
function code. The Runtime API (p. 205), along with the Extensions API (p. 209), defines a simple

203
 AWS Lambda Developer Guide
Runtime interface emulator

HTTP interface for runtimes to receive invocation events from Lambda and respond with success or
failure indications.

Each of the AWS base images for Lambda include a runtime interface client. If you choose one of the
base images for custom runtimes or an alternative base image, you need to add the appropriate runtime
interface client.

For your convenience, Lambda provides an open source runtime interface client for each of the
supported Lambda runtimes:

• Node.js (p. 492)

• Python (p. 530)
• Java (p. 585)
• .NET (p. 651)
• Go (p. 620)
• Ruby (p. 554)

Runtime interface emulator

Lambda provides a runtime interface emulator (RIE) for you to test your function locally. The AWS base
images for Lambda and base images for custom runtimes include the RIE. For other base images, you can
download the Runtime interface emulator from the AWS GitHub repository.

204
 AWS Lambda Developer Guide
Runtime API

AWS Lambda runtime API

AWS Lambda provides an HTTP API for custom runtimes (p. 236) to receive invocation events from
Lambda and send response data back within the Lambda execution environment (p. 195).

The OpenAPI specification for the runtime API version 2018-06-01 is available in runtime-api.zip

To create an API request URL, runtimes get the API endpoint from the AWS_LAMBDA_RUNTIME_API
environment variable, add the API version, and add the desired resource path.

Example Request

curl "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/next"

API methods
• Next invocation (p. 205)
• Invocation response (p. 206)
• Initialization error (p. 206)
• Invocation error (p. 207)

Next invocation
Path – /runtime/invocation/next

Method – GET

The runtime sends this message to Lambda to request an invocation event. The response body contains
the payload from the invocation, which is a JSON document that contains event data from the function
trigger. The response headers contain additional data about the invocation.

Response headers

• Lambda-Runtime-Aws-Request-Id – The request ID, which identifies the request that triggered the
function invocation.

For example, 8476a536-e9f4-11e8-9739-2dfe598c3fcd.

• Lambda-Runtime-Deadline-Ms – The date that the function times out in Unix time milliseconds.

For example, 1542409706888.

• Lambda-Runtime-Invoked-Function-Arn – The ARN of the Lambda function, version, or alias
that's specified in the invocation.

For example, arn:aws:lambda:us-east-2:123456789012:function:custom-runtime.

• Lambda-Runtime-Trace-Id – The AWS X-Ray tracing header.

For example, Root=1-5bef4de7-

ad49b0e87f6ef6c87fc2e700;Parent=9a9197af755a6419;Sampled=1.
• Lambda-Runtime-Client-Context – For invocations from the AWS Mobile SDK, data about the
client application and device.
• Lambda-Runtime-Cognito-Identity – For invocations from the AWS Mobile SDK, data about the
Amazon Cognito identity provider.

205
 AWS Lambda Developer Guide
Invocation response

Do not set a timeout on the GET request as the response may be delayed. Between when Lambda
bootstraps the runtime and when the runtime has an event to return, the runtime process may be frozen
for several seconds.

The request ID tracks the invocation within Lambda. Use it to specify the invocation when you send the
response.

The tracing header contains the trace ID, parent ID, and sampling decision. If the request is
sampled, the request was sampled by Lambda or an upstream service. The runtime should set the
_X_AMZN_TRACE_ID with the value of the header. The X-Ray SDK reads this to get the IDs and
determine whether to trace the request.

Invocation response
Path – /runtime/invocation/AwsRequestId/response

Method – POST

After the function has run to completion, the runtime sends an invocation response to Lambda. For
synchronous invocations, Lambda sends the response to the client.

Example success request

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/
response" -d "SUCCESS"

Initialization error
If the function returns an error or the runtime encounters an error during initialization, the runtime uses
this method to report the error to Lambda.

Path – /runtime/init/error

Method – POST

Headers

Lambda-Runtime-Function-Error-Type – Error type that the extension encountered. Required: no.

This header consists of a string value. Lambda accepts any string, but we recommend a format of
<category.reason>. For example:

• Runtime.NoSuchHandler
• Extension.APIKeyNotFound
• Extension.ConfigInvalid
• Extension.UnknownReason

Body parameters

ErrorRequest – Information about the error. Required: no.

This field is a JSON object with the following structure:

{
errorMessage: string (text description of the error),

206
 AWS Lambda Developer Guide
Invocation error

errorType: string,
stackTrace: array of strings
}

Note that Lambda accepts any value for errorType.

The following example shows a Lambda function error message in which the function could not parse
the event data provided in the invocation.

Example Function error

{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}

Response body parameters

• StatusResponse – String. Status information, sent with 202 response codes.

• ErrorResponse – Additional error information, sent with the error response codes. ErrorResponse
contains an error type and an error message.

Response codes

• 202 – Accepted
• 403 – Forbidden
• 500 – Container error. Non-recoverable state. Extension should exit promptly.

Example initialization error request

ERROR="{\"errorMessage\" : \"Failed to load function.\", \"errorType\" :

\"InvalidFunctionException\"}"
curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/init/error" -d "$ERROR"
--header "Lambda-Runtime-Function-Error-Type: Unhandled"

Invocation error
If the function returns an error or the runtime encounters an error, the runtime uses this method to
report the error to Lambda.

Path – /runtime/invocation/AwsRequestId/error

Method – POST

Headers

Lambda-Runtime-Function-Error-Type – Error type that the extension encountered. Required: no.

This header consists of a string value. Lambda accepts any string, but we recommend a format of
<category.reason>. For example:

• Runtime.NoSuchHandler
• Extension.APIKeyNotFound
• Extension.ConfigInvalid

207
 AWS Lambda Developer Guide
Invocation error

• Extension.UnknownReason

Body parameters

ErrorRequest – Information about the error. Required: no.

This field is a JSON object with the following structure:

{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}

Note that Lambda accepts any value for errorType.

The following example shows a Lambda function error message in which the function could not parse
the event data provided in the invocation.

Example Function error

{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}

Response body parameters

• StatusResponse – String. Status information, sent with 202 response codes.

• ErrorResponse – Additional error information, sent with the error response codes. ErrorResponse
contains an error type and an error message.

Response codes

• 202 – Accepted
• 400 – Bad Request
• 403 – Forbidden
• 500 – Container error. Non-recoverable state. Extension should exit promptly.

Example error request

REQUEST_ID=156cb537-e2d4-11e8-9b34-d36013741fb9
ERROR="{\"errorMessage\" : \"Error parsing event data.\", \"errorType\" :
\"InvalidEventDataException\"}"
curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/
error" -d "$ERROR" --header "Lambda-Runtime-Function-Error-Type: Unhandled"

208
 AWS Lambda Developer Guide
Extensions API

Lambda Extensions API

Lambda function authors use extensions to integrate Lambda with their preferred tools for monitoring,
observability, security, and governance. Function authors can use extensions from AWS, AWS Partners,
and open-source projects. For more information on using extensions, see Introducing AWS Lambda
Extensions on the AWS Compute Blog.

As an extension author, you can use the Lambda Extensions API to integrate deeply into the Lambda
execution environment (p. 200). Your extension can register for function and execution environment
lifecycle events. In response to these events, you can start new processes, run logic, and control and
participate in all phases of the Lambda lifecycle: initialization, invocation, and shutdown. In addition, you
can use the Runtime Logs API (p. 223) to receive a stream of logs.

An extension runs as an independent process in the execution environment and can continue to run
after the function invocation is fully processed. Because extensions run as processes, you can write
them in a different language than the function. We recommend that you implement extensions using a
compiled language. In this case, the extension is a self-contained binary that is compatible with all of the
supported runtimes. If you use a non-compiled language, ensure that you include a compatible runtime
in the extension.

The following Lambda runtimes (p. 195) support extensions:

• .NET Core 3.1 (C#/PowerShell) (dotnetcore3.1)

• Custom runtime (provided)
• Custom runtime on Amazon Linux 2 (provided.al2)
• Java 11 (Corretto) (java11)
• Java 8 (Corretto) (java8.al2)
• Node.js 14.x (nodejs14.x)
• Node.js 12.x (nodejs12.x)
• Node.js 10.x (nodejs10.x)
• Python 3.8 (python3.8)
• Python 3.7 (python3.7)
• Ruby 2.7 (ruby2.7)
• Ruby 2.5 (ruby2.5)

Note that the Go 1.x runtime does not support extensions. To support extensions, you can create Go
functions on the provided.al2 runtime. For more information, see Migrating Lambda functions to
Amazon Linux 2.

Lambda also supports internal extensions. An internal extension runs as a separate thread in the runtime
process. The runtime starts and stops the internal extension. An alternative way to integrate with the
Lambda environment is to use language-specific environment variables and wrapper scripts (p. 231).
You can use these to configure the runtime environment and modify the startup behavior of the runtime
process.

You can add extensions to a function in two ways. For a function deployed as a .zip file archive (p. 41),
you deploy your extension as a layer (p. 101). For a function defined as a container image, you add the
extensions (p. 162) to your container image.
Note
For example extensions and wrapper scripts, see AWS Lambda Extensions on the AWS Samples
GitHub repository.

209
 AWS Lambda Developer Guide
Lambda execution environment lifecycle

Topics
• Lambda execution environment lifecycle (p. 210)
• Extensions API reference (p. 218)

Lambda execution environment lifecycle

The lifecycle of the execution environment includes the following phases:

• Init: In this phase, Lambda creates or unfreezes an execution environment with the configured
resources, downloads the code for the function and all layers, initializes any extensions, initializes the
runtime, and then runs the function’s initialization code (the code outside the main handler). The Init
phase happens either during the first invocation, or in advance of function invocations if you have
enabled provisioned concurrency (p. 87).

The Init phase is split into three sub-phases: Extension init, Runtime init, and Function
init. These sub-phases ensure that all extensions and the runtime complete their setup tasks before
the function code runs.
• Invoke: In this phase, Lambda invokes the function handler. After the function runs to completion,
Lambda prepares to handle another function invocation.
• Shutdown: This phase is triggered if the Lambda function does not receive any invocations for a period
of time. In the Shutdown phase, Lambda shuts down the runtime, alerts the extensions to let them
stop cleanly, and then removes the environment. Lambda sends a Shutdown event to each extension,
which tells the extension that the environment is about to be shut down.

Each phase starts with an event from Lambda to the runtime and to all registered extensions. The
runtime and each extension signal completion by sending a Next API request. Lambda freezes the
execution environment when each process has completed and there are no pending events.

210
 AWS Lambda Developer Guide
Lambda execution environment lifecycle

Topics
• Init phase (p. 212)
• Invoke phase (p. 201)
• Shutdown phase (p. 202)
• Permissions and configuration (p. 216)
• Failure handling (p. 217)
• Troubleshooting extensions (p. 218)

211
 AWS Lambda Developer Guide
Lambda execution environment lifecycle

Init phase
During the Extension init phase, each extension needs to register with Lambda to receive events.
Lambda uses the full file name of the extension to validate that the extension has completed the
bootstrap sequence. Therefore, each Register API call must include the Lambda-Extension-Name
header with the full file name of the extension.

You can register up to 10 extensions for a function. This limit is enforced through the Register API call.

After each extension registers, Lambda starts the Runtime init phase. The runtime process calls
functionInit to start the Function init phase.

The Init phase completes after the runtime and each registered extension indicate completion by
sending a Next API request.
Note
Extensions can complete their initialization at any point in the Init phase.

212
 AWS Lambda Developer Guide
Lambda execution environment lifecycle

Invoke phase
When a Lambda function is invoked in response to a Next API request, Lambda sends an Invoke event
to the runtime and to each extension that is registered for the Invoke event.

During the invocation, external extensions run in parallel with the function. They also continue running
after the function has completed. This enables you to capture diagnostic information or to send logs,
metrics, and traces to a location of your choice.

After receiving the function response from the runtime, Lambda returns the response to the client, even
if extensions are still running.

213
 AWS Lambda Developer Guide
Lambda execution environment lifecycle

The Invoke phase ends after the runtime and all extensions signal that they are done by sending a Next
API request.

Event payload: The event sent to the runtime (and the Lambda function) carries the entire request,
headers (such as RequestId), and payload. The event sent to each extension contains metadata that
describes the event content. This lifecycle event includes the type of the event, the time that the
function times out (deadlineMs), the requestId, the invoked function's Amazon Resource Name
(ARN), and tracing headers.

Extensions that want to access the function event body can use an in-runtime SDK that communicates
with the extension. Function developers use the in-runtime SDK to send the payload to the extension
when the function is invoked.

Here is an example payload:

{
"eventType": "INVOKE",
"deadlineMs": 676051,
"requestId": "3da1f2dc-3222-475e-9205-e2e6c6318895",
"invokedFunctionArn": "arn:aws:lambda:us-east-1:123456789012:function:ExtensionTest",

214
 AWS Lambda Developer Guide
Lambda execution environment lifecycle

"tracing": {
"type": "X-Amzn-Trace-Id",
"value":
"Root=1-5f35ae12-0c0fec141ab77a00bc047aa2;Parent=2be948a625588e32;Sampled=1"
}
}

Duration limit: The function's timeout setting (p. 70) limits the duration of the entire Invoke phase.
For example, if you set the function timeout as 360 seconds, the function and all extensions need to
complete within 360 seconds. Note that there is no independent post-invoke phase. The duration is
the sum of all invocation time (runtime + extensions) and is not calculated until the function and all
extensions have finished running.

Performance impact and extension overhead: Extensions can impact function performance. As an
extension author, you have control over the performance impact of your extension. For example, if
your extension performs compute-intensive operations, the function's duration increases because the
extension and the function code share the same CPU resources. In addition, if your extension performs
extensive operations after the function invocation completes, the function duration increases because
the Invoke phase continues until all extensions signal that they are completed.
Note
Lambda allocates CPU power in proportion to the function's memory setting. You might see
increased execution and initialization duration at lower memory settings because the function
and extension processes are competing for the same CPU resources. To reduce the execution and
initialization duration, try increasing the memory setting.

To help identify the performance impact introduced by extensions on the Invoke phase, Lambda
outputs the PostRuntimeExtensionsDuration metric. This metric measures the cumulative time
spent between the runtime Next API request and the last extension Next API request. To measure the
increase in memory used, use the MaxMemoryUsed metric. For more information about function metrics,
see Working with AWS Lambda function metrics (p. 692).

Function developers can run different versions of their functions side by side to understand the impact
of a specific extension. We recommend that extension authors publish expected resource consumption to
make it easier for function developers to choose a suitable extension.

Shutdown phase
When Lambda is about to shut down the runtime, it sends a Shutdown event to the runtime and then to
each registered external extension. Extensions can use this time for final cleanup tasks. The Shutdown
event is sent in response to a Next API request.

Duration limit: The maximum duration of the Shutdown phase depends on the configuration of
registered extensions:

• 300 ms – A function with no registered extensions

• 500 ms – A function with a registered internal extension
• 2,000 ms – A function with one or more registered external extensions

For a function with external extensions, Lambda reserves up to 300 ms (500 ms for a runtime with
an internal extension) for the runtime process to perform a graceful shutdown. Lambda allocates the
remainder of the 2,000 ms limit for external extensions to shut down.

If the runtime or an extension does not respond to the Shutdown event within the limit, Lambda ends
the process using a SIGKILL signal.

215
 AWS Lambda Developer Guide
Lambda execution environment lifecycle

Event payload: The Shutdown event contains the reason for the shutdown and the time remaining in
milliseconds.

The shutdownReason includes the following values:

• SPINDOWN – Normal shutdown

• TIMEOUT – Duration limit timed out
• FAILURE – Error condition, such as an out-of-memory event

{
"eventType": "SHUTDOWN",
"shutdownReason": "reason for shutdown",
"deadlineMs": "the time and date that the function times out in Unix time milliseconds"
}

Permissions and configuration

Extensions run in the same execution environment as the Lambda function. Extensions also share
resources with the function, such as CPU, memory, and /tmp disk storage. In addition, extensions use the
same AWS Identity and Access Management (IAM) role and security context as the function.

216
 AWS Lambda Developer Guide
Lambda execution environment lifecycle

File system and network access permissions: Extensions run in the same file system and network
name namespace as the function runtime. This means that extensions need to be compatible with the
associated operating system. If an extension requires any additional outbound network traffic rules, you
must apply these rules to the function configuration.
Note
Because the function code directory is read-only, extensions cannot modify the function code.

Environment variables: Extensions can access the function's environment variables (p. 77), except for the
following variables that are specific to the runtime process:

• AWS_EXECUTION_ENV
• AWS_LAMBDA_LOG_GROUP_NAME
• AWS_LAMBDA_LOG_STREAM_NAME
• AWS_XRAY_CONTEXT_MISSING
• AWS_XRAY_DAEMON_ADDRESS
• LAMBDA_RUNTIME_DIR
• LAMBDA_TASK_ROOT
• _AWS_XRAY_DAEMON_ADDRESS
• _AWS_XRAY_DAEMON_PORT
• _HANDLER

Failure handling
Initialization failures: If an extension fails, Lambda restarts the execution environment to enforce
consistent behavior and to encourage fail fast for extensions. Also, for some customers, the extensions
must meet mission-critical needs such as logging, security, governance, and telemetry collection.

Invoke failures (such as out of memory, function timeout): Because extensions share resources with the
runtime, memory exhaustion affects them. When the runtime fails, all extensions and the runtime itself
participate in the Shutdown phase. In addition, the runtime is restarted—either automatically as part of
the current invocation, or via a deferred re-initialization mechanism.

If there is a failure (such as a function timeout or runtime error) during Invoke, the Lambda service
performs a reset. The reset behaves like a Shutdown event. First, Lambda shuts down the runtime, then
it sends a Shutdown event to each registered external extension. The event includes the reason for the
shutdown. If this environment is used for a new invocation, the extension and runtime are re-initialized
as part of the next invocation.

Extension logs: Lambda sends the log output of extensions to CloudWatch Logs. Lambda also generates
an additional log event for each extension during Init. The log event records the name and registration
preference (event, config) on success, or the failure reason on failure.

217
 AWS Lambda Developer Guide
Extensions API reference

Troubleshooting extensions
• If a Register request fails, make sure that the Lambda-Extension-Name header in the Register
API call contains the full file name of the extension.
• If the Register request fails for an internal extension, make sure that the request does not register
for the Shutdown event.

Extensions API reference

The OpenAPI specification for the extensions API version 2020-01-01 is available here: extensions-api.zip

You can retrieve the value of the API endpoint from the AWS_LAMBDA_RUNTIME_API environment
variable. To send a Register request, use the prefix 2020-01-01/ before each API path. For example:

http://${AWS_LAMBDA_RUNTIME_API}/2020-01-01/extension/register

API methods
• Register (p. 218)
• Next (p. 219)
• Init error (p. 219)
• Exit error (p. 221)

Register
During Extension init, all extensions need to register with Lambda to receive events. Lambda uses
the full file name of the extension to validate that the extension has completed the bootstrap sequence.
Therefore, each Register API call must include the Lambda-Extension-Name header with the full file
name of the extension.

Internal extensions are started and stopped by the runtime process, so they are not permitted to register
for the Shutdown event.

Path – /extension/register

Method – POST

Headers

Lambda-Extension-Name – The full file name of the extension. Required: yes. Type: string.

Body parameters

events – Array of the events to register for. Required: no. Type: array of strings. Valid strings: INVOKE,
SHUTDOWN.

Response headers

• Lambda-Extension-Identifier – Generated unique agent identifier (UUID string) that is required

for all subsequent requests.

Response codes

• 200 – Response body contains the function name, function version, and handler name.

218
 AWS Lambda Developer Guide
Extensions API reference

• 400 – Bad Request

• 403 – Forbidden
• 500 – Container error. Non-recoverable state. Extension should exit promptly.

Example Example request body

{
'events': [ 'INVOKE', 'SHUTDOWN']
}

Example Example response body

{
"functionName": "helloWorld",
"functionVersion": "$LATEST",
"handler": "lambda_function.lambda_handler"
}

Next
Extensions send a Next API request to receive the next event, which can be an Invoke event or a
Shutdown event. The response body contains the payload, which is a JSON document that contains
event data.

The extension sends a Next API request to signal that it is ready to receive new events. This is a blocking
call.

Do not set a timeout on the GET call, as the extension can be suspended for a period of time until there
is an event to return.

Path – /extension/event/next

Method – GET

Parameters

Lambda-Extension-Identifier – Unique identifier for extension (UUID string). Required: yes. Type:
UUID string.

Response header

• Lambda-Extension-Identifier – Unique agent identifier (UUID string).

Response codes

• 200 – Response contains information about the next event (EventInvoke or EventShutdown).
• 403 – Forbidden
• 500 – Container error. Non-recoverable state. Extension should exit promptly.

Init error
The extension uses this method to report an initialization error to Lambda. Call it when the extension
fails to initialize after it has registered. After Lambda receives the error, no further API calls succeed. The
extension should exit after it receives the response from Lambda.

219
 AWS Lambda Developer Guide
Extensions API reference

Path – /extension/init/error

Method – POST

Headers

Lambda-Extension-Identifier – Unique identifier for extension. Required: yes. Type: UUID string.

Lambda-Extension-Function-Error-Type – Error type that the extension encountered. Required:

yes.

This header consists of a string value. Lambda accepts any string, but we recommend a format of
<category.reason>. For example:

• Runtime.NoSuchHandler
• Extension.APIKeyNotFound
• Extension.ConfigInvalid
• Extension.UnknownReason

Body parameters

ErrorRequest – Information about the error. Required: no.

This field is a JSON object with the following structure:

{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}

Note that Lambda accepts any value for errorType.

The following example shows a Lambda function error message in which the function could not parse
the event data provided in the invocation.

Example Function error

{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}

Response body

• Lambda-Extension-Identifier – Unique agent identifier (UUID string).

Response codes

• 202 – Accepted
• 400 – Bad Request
• 403 – Forbidden
• 500 – Container error. Non-recoverable state. Extension should exit promptly.

220
 AWS Lambda Developer Guide
Extensions API reference

Exit error
The extension uses this method to report an error to Lambda before exiting. Call it when you encounter
an unexpected failure. After Lambda receives the error, no further API calls succeed. The extension
should exit after it receives the response from Lambda.

Path – /extension/exit/error

Method – POST

Headers

Lambda-Extension-Identifier – Unique identifier for extension. Required: yes. Type: UUID string.

Lambda-Extension-Function-Error-Type – Error type that the extension encountered. Required:

yes.

This header consists of a string value. Lambda accepts any string, but we recommend a format of
<category.reason>. For example:

• Runtime.NoSuchHandler
• Extension.APIKeyNotFound
• Extension.ConfigInvalid
• Extension.UnknownReason

Body parameters

ErrorRequest – Information about the error. Required: no.

This field is a JSON object with the following structure:

{
errorMessage: string (text description of the error),
errorType: string,
stackTrace: array of strings
}

Note that Lambda accepts any value for errorType.

The following example shows a Lambda function error message in which the function could not parse
the event data provided in the invocation.

Example Function error

{
"errorMessage" : "Error parsing event data.",
"errorType" : "InvalidEventDataException",
"stackTrace": [ ]
}

Response body

• Lambda-Extension-Identifier – Unique agent identifier (UUID string).

Response codes

• 202 – Accepted

221
 AWS Lambda Developer Guide
Extensions API reference

• 400 – Bad Request

• 403 – Forbidden
• 500 – Container error. Non-recoverable state. Extension should exit promptly.

222
 AWS Lambda Developer Guide
Logs API

Lambda Logs API

Lambda automatically captures runtime logs and streams them to Amazon CloudWatch. This log stream
contains the logs that your function code and extensions generate, and also the logs that Lambda
generates as part of the function invocation.

Lambda extensions (p. 209) can use the Lambda Runtime Logs API to subscribe to log streams directly
from within the Lambda execution environment (p. 200). Lambda streams the logs to the extension, and
the extension can then process, filter, and send the logs to any preferred destination.

The Logs API allows extensions to subscribe to three different logs streams:

• Function logs that the Lambda function generates and writes to stdout or stderr.
• Extension logs that extension code generates.
• Lambda platform logs, which record events and errors related to invocations and extensions.

Note
Lambda sends all logs to CloudWatch, even when an extension subscribes to one or more of the
log streams.

Topics
• Subscribing to receive logs (p. 224)
• Memory usage (p. 224)
• Destination protocols (p. 224)
• Buffering configuration (p. 224)
• Example subscription (p. 225)
• Sample code for Logs API (p. 225)
• Logs API reference (p. 226)
• Log messages (p. 227)

223
 AWS Lambda Developer Guide
Subscribing to receive logs

Subscribing to receive logs

A Lambda extension can subscribe to receive logs by sending a subscription request to the Logs API.

To subscribe to receive logs, you need the extension identifier (Lambda-Extension-Identifier). First
register the extension (p. 218) to receive the extension identifier. Then subscribe to the Logs API during
initialization (p. 201). After the initialization phase completes, Lambda does not process subscription
requests.
Note
Logs API subscription is idempotent. Duplicate subscribe requests do not result in duplicate
subscriptions.

Memory usage
Memory usage increases linearly as the number of subscribers increases. Subscriptions consume memory
resources because each subscription opens a new memory buffer to store the logs. To help optimize
memory usage, you can adjust the buffering configuration (p. 224). Buffer memory usage counts
towards overall memory consumption in the execution environment.

Destination protocols
You can choose one of the following protocols to receive the logs:

1. HTTP (recommended) – Lambda delivers logs to a local HTTP endpoint (http://

sandbox.localdomain:${PORT}/${PATH}) as an array of records in JSON format. The $PATH
parameter is optional. Note that only HTTP is supported, not HTTPS. You can choose to receive logs
through PUT or POST.
2. TCP – Lambda delivers logs to a TCP port in Newline delimited JSON (NDJSON) format.

We recommend using HTTP rather than TCP. With TCP, the Lambda platform cannot acknowledge when
it delivers logs to the application layer. Therefore, you might lose logs if your extension crashes. HTTP
does not share this limitation.

We also recommend setting up the local HTTP listener or the TCP port before subscribing to receive logs.
During setup, note the following:

• Lambda sends logs only to destinations that are inside the execution environment.
• Lambda retries the attempt to send the logs (with backoff) if there is no listener, or if the POST or
PUT request results in an error. If the log subscriber crashes, it continues to receive logs after Lambda
restarts the execution environment.
• Lambda reserves port 9001. There are no other port number restrictions or recommendations.

Buffering configuration
Lambda can buffer logs and deliver them to the subscriber. You can configure this behavior in the
subscription request by specifying the following optional fields. Note that Lambda uses the default value
for any field that you do not specify.

• timeoutMs – The maximum time (in milliseconds) to buffer a batch. Default: 1,000. Minimum: 25.
Maximum: 30,000.
• maxBytes – The maximum size (in bytes) of the logs to buffer in memory. Default: 262,144. Minimum:
262,144. Maximum: 1,048,576.

224
 AWS Lambda Developer Guide
Example subscription

• maxItems – The maximum number of events to buffer in memory. Default: 10,000. Minimum: 1,000.
Maximum: 10,000.

During buffering configuration, note the following points:

• Lambda flushes the logs if any of the input streams are closed, for example, if the runtime crashes.
• Each subscriber can specify a different buffering configuration in their subscription request.
• Consider the buffer size that you need for reading the data. Expect to receive payloads as large as
2*maxBytes+metadata, where maxBytes is configured in the subscribe request. For example,
Lambda adds the following metadata bytes to each record:

{
"time": "2020-08-20T12:31:32.123Z",
"type": "function",
"record": "Hello World"
}

• If the subscriber cannot process incoming logs quickly enough, Lambda might drop logs to
keep memory utilization bounded. To indicate the number of dropped records, Lambda sends a
platform.logsDropped log.

Example subscription
The following example shows a request to subscribe to the platform and function logs.

PUT http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs/ HTTP/1.1

{ "schemaVersion": "2020-08-15",
"types": [
"platform",
"function"
],
"buffering": {
"maxItems": 1000,
"maxBytes": 10240,
"timeoutMs": 100
}
"destination": {
"protocol": "HTTP",
"URI": "http://sandbox.localdomain:8080/lambda_logs"
}
}

If the request succeeds, the subscriber receives an HTTP 200 success response.

HTTP/1.1 200 OK
"OK"

Sample code for Logs API

For sample code showing how to send logs to a custom destination, see Using AWS Lambda extensions
to send logs to custom destinations on the AWS Compute Blog.

For Python and Go code examples showing how to develop a basic Lambda extension and subscribe to
the Logs API, see AWS Lambda Extensions on the AWS Samples GitHub repository. For more information
about building a Lambda extension, see the section called “Extensions API” (p. 209).

225
 AWS Lambda Developer Guide
Logs API reference

Logs API reference

You can retrieve the Logs API endpoint from the AWS_LAMBDA_RUNTIME_API environment variable. To
send an API request, use the prefix 2020-08-15/ before the API path. For example:

http://${AWS_LAMBDA_RUNTIME_API}/2020-08-15/logs/

The OpenAPI specification for the Logs API version 2020-08-15 is available here: logs-api-request.zip

Subscribe
To subscribe to one or more of the log streams available in the Lambda execution environment,
extensions send a Subscribe API request.

Path – /logs

Method – PUT

Body parameters

destination – See the section called “Destination protocols” (p. 224). Required: yes. Type: strings.

buffering – See the section called “Buffering configuration” (p. 224). Required: no. Type: strings.

types – An array of the types of logs to receive. Required: yes. Type: array of strings. Valid values:
"platform", "function", "extension".

schemaVersion – Required: no. Default value: "2020-08-15". Set to "2021-03-18" for the extension to
receive platform.runtimeDone (p. 229) messages.

Response parameters

The OpenAPI specifications for the subscription responses version 2020-08-15 are available for the HTTP
and TCP protocols:

• HTTP: logs-api-http-response.zip
• TCP: logs-api-tcp-response.zip

Response codes

• 200 – Request completed successfully

• 202 – Request accepted. Response to a subscription request during local testing.
• 4XX – Bad Request
• 500 – Service error

If the request succeeds, the subscriber receives an HTTP 200 success response.

HTTP/1.1 200 OK
"OK"

If the request fails, the subscriber receives an error response. For example:

HTTP/1.1 400 OK

226
 AWS Lambda Developer Guide
Log messages

{
"errorType": "Logs.ValidationError",
"errorMessage": URI port is not provided; types should not be empty"
}

Log messages
The Logs API allows extensions to subscribe to three different logs streams:

• Function – Logs that the Lambda function generates and writes to stdout or stderr.
• Extension – Logs that extension code generates.
• Platform – Logs that the runtime platform generates, which record events and errors related to
invocations and extensions.

Topics
• Function logs (p. 227)
• Extension logs (p. 227)
• Platform logs (p. 227)

Function logs
The Lambda function and internal extensions generate function logs and write them to stdout or
stderr.

The following example shows the format of a function log message. { "time":
"2020-08-20T12:31:32.123Z", "type": "function", "record": "ERROR encountered. Stack trace:\n\my-
function (line 10)\n" }

Extension logs
Extensions can generate extension logs. The log format is the same as for a function log.

Platform logs
Lambda generates log messages for platform events such as platform.start, platform.end, and
platform.fault.

Optionally, you can subscribe to the 2021-03-18 version of the Logs API schema, which includes the
platform.runtimeDone log message.

Example platform log messages

The following example shows the platform start and platform end logs. These logs indicate the
invocation start time and invocation end time for the invocation that the requestId specifies.

{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.start",
"record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}
}
{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.end",
"record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56"}

227
 AWS Lambda Developer Guide
Log messages

The platform report log includes metrics about the invocation that the requestId specifies. The
initDurationMs field is included in the log only if the invocation included a cold start. If AWS X-Ray
tracing is active, the log includes X-Ray metadata. The following example shows a platform report log for
an invocation that included a cold start.

{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.report",
"record": {"requestId": "6f7f0961f83442118a7af6fe80b88d56",
"metrics": {"durationMs": 101.51,
"billedDurationMs": 300,
"memorySizeMB": 512,
"maxMemoryUsedMB": 33,
"initDurationMs": 116.67
}
}
}

The platform fault log captures runtime or execution environment errors. The following example shows a
platform fault log message.

{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.fault",
"record": "RequestId: d783b35e-a91d-4251-af17-035953428a2c Process exited before
completing request"
}

Lambda generates a platform extension log when an extension registers with the extensions API. The
following example shows a platform extension message.

{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.extension",
"record": {"name": "Foo.bar",
"state": "Ready",
"events": ["INVOKE", "SHUTDOWN"]
}
}

Lambda generates a platform logs subscription log when an extension subscribes to the logs API. The
following example shows a logs subscription message.

{
"time": "2020-08-20T12:31:32.123Z",
"type": "platform.logsSubscription",
"record": {"name": "Foo.bar",
"state": "Subscribed",
"types": ["function", "platform"],
}
}

Lambda generates a platform logs dropped log when an extension is not able to process the number of
logs that it is receiving. The following example shows a platform.logsDropped log message.

228
 AWS Lambda Developer Guide
Log messages

"time": "2020-08-20T12:31:32.123Z",
"type": "platform.logsDropped",
"record": {"reason": "Consumer seems to have fallen behind as it has not acknowledged
receipt of logs.",
"droppedRecords": 123,
"droppedBytes" 12345
}
}

Platform runtimeDone messages

If you set the schema version to "2021-03-18" in the subscribe request, Lambda sends a
platform.runtimeDone message after the function invocation completes either successfully or
with an error. The extension can use this message to stop all the telemetry collection for this function
invocation.

The OpenAPI specification for the Log event type in schema version 2021-03-18 is available here:
schema-2021-03-18.zip

Lambda generates the platform.runtimeDone log message when the runtime sends a Next or
Error runtime API request. The platform.runtimeDone log informs consumers of the Logs API that
the function invocation completes. Extensions can use this information to decide when to send all the
telemetry collected during that invocation.

Examples

Lambda sends the platform.runtimeDone message after the runtime sends the NEXT request when
the function invocation completes. The following examples show messages for each of the status values:
success, failure, and timeout.

Example Example success message

{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "success"
}
}

Example Example failure message

{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",
"status": "failure"
}
}

Example Example timeout message

{
"time": "2021-02-04T20:00:05.123Z",
"type": "platform.runtimeDone",
"record": {
"requestId":"6f7f0961f83442118a7af6fe80b88",

229
 AWS Lambda Developer Guide
Log messages

"status": "timeout"
}
}

230
 AWS Lambda Developer Guide
Runtime modifications

Modifying the runtime environment

You can use internal extensions (p. 160) to modify the runtime process. Internal extensions are not
separate processes—they run as part of the runtime process.

Lambda provides language-specific environment variables (p. 77) that you can set to add options and
tools to the runtime. Lambda also provides wrapper scripts (p. 233), which allow Lambda to delegate
the runtime startup to your script. You can create a wrapper script to customize the runtime startup
behavior.

Language-specific environment variables

Lambda supports configuration-only ways to enable code to be pre-loaded during function initialization
through the following language-specific environment variables:

• JAVA_TOOL_OPTIONS – On Java 11 and Java 8 (java8.al2), Lambda supports this environment

variable to set additional command-line variables in Lambda. This environment variable allows you to
specify the initialization of tools, specifically the launching of native or Java programming language
agents using the agentlib or javaagent options.
• NODE_OPTIONS – On Node.js 10x and above, Lambda supports this environment variable.
• DOTNET_STARTUP_HOOKS – On .NET Core 3.1 and above, this environment variable specifies a path to
an assembly (dll) that Lambda can use.

Using language-specific environment variables is the preferred way to set startup properties.

Example: Intercept Lambda invokes with javaagent

The Java virtual machine (JVM) tries to locate the class that was specified with the javaagent
parameter to the JVM, and invoke its premain method before the application's entry point.

The following example uses Byte Buddy, a library for creating and modifying Java classes during the
runtime of a Java application without the help of a compiler. Byte Buddy offers an additional API for
generating Java agents. In this example, the Agent class intercepts every call of the handleRequest
method made to the RequestStreamHandler class. This class is used internally in the runtime to wrap the
handler invocations.

import com.amazonaws.services.lambda.runtime.RequestStreamHandler;
import net.bytebuddy.agent.builder.AgentBuilder;
import net.bytebuddy.asm.Advice;
import net.bytebuddy.matcher.ElementMatchers;

import java.lang.instrument.Instrumentation;

public class Agent {

public static void premain(String agentArgs, Instrumentation inst) {

new AgentBuilder.Default()
.with(new AgentBuilder.InitializationStrategy.SelfInjection.Eager())
.type(ElementMatchers.isSubTypeOf(RequestStreamHandler.class))
.transform((builder, typeDescription, classLoader, module) -> builder
.method(ElementMatchers.nameContains("handleRequest"))
.intercept(Advice.to(TimerAdvice.class)))
.installOn(inst);
}
}

231
 AWS Lambda Developer Guide
Language-specific environment variables

The agent in the preceding example uses the TimerAdvice method. TimerAdvice measures how many
milliseconds are spent with the method call and logs the method time and details, such as name and
passed arguments.

import static net.bytebuddy.asm.Advice.AllArguments;

import static net.bytebuddy.asm.Advice.Enter;
import static net.bytebuddy.asm.Advice.OnMethodEnter;
import static net.bytebuddy.asm.Advice.OnMethodExit;
import static net.bytebuddy.asm.Advice.Origin;

public class TimerAdvice {

@OnMethodEnter
static long enter() {
return System.currentTimeMillis();
}

@OnMethodExit
static void exit(@Origin String method, @Enter long start, @AllArguments Object[] args)
{
StringBuilder sb = new StringBuilder();
for (Object arg : args) {
sb.append(arg);
sb.append(", ");
}
System.out.println(method + " method with args: " + sb.toString() + " took " +
(System.currentTimeMillis() - start) + " milliseconds ");
}
}

The TimerAdvice method above has the following dependencies.

*'com.amazonaws'*, *name*: *'aws-lambda-java-core'*, *version*: *'1.2.1'*

*'net.bytebuddy'*, *name*: *'byte-buddy-dep'*, *version*: *'1.10.14'*
*'net.bytebuddy'*, *name*: *'byte-buddy-agent'*, *version*: *'1.10.14'*

After you create a layer that contains the agent JAR, you can pass the JAR name to the runtime's JVM by
setting an environment variable.

JAVA_TOOL_OPTIONS=-javaagent:"/opt/ExampleAgent-0.0.jar"

After invoking the function with {key=lambdaInput}, you can find the following line in the logs:

public java.lang.Object lambdainternal.EventHandlerLoader

$PojoMethodRequestHandler.handleRequest
(java.lang.Object,com.amazonaws.services.lambda.runtime.Context) method with args:
{key=lambdaInput}, lambdainternal.api.LambdaContext@4d9d1b69, took 106 milliseconds

Example: Adding a shutdown hook to the JVM runtime process

When an extension is registered during a Shutdown event, the runtime process gets up to 500 ms
to handle graceful shutdown. You can hook into the runtime process, and when the JVM begins its
shutdown process, it starts all registered hooks. To register a shutdown hook, you must register as an

232
 AWS Lambda Developer Guide
Wrapper scripts

extension (p. 218). You do not need to explicitly register for the Shutdown event, as that is automatically
sent to the runtime.

import java.lang.instrument.Instrumentation;

public class Agent {

public static void premain(String agentArgs, Instrumentation inst) {

// Register the extension.
// ...

// Register the shutdown hook

addShutdownHook();
}

private static void addShutdownHook() {

// Shutdown hooks get up to 500 ms to handle graceful shutdown before the runtime is
terminated.
//
// You can use this time to egress any remaining telemetry, close open database
connections, etc.
Runtime.getRuntime().addShutdownHook(new Thread(() -> {
// Inside the shutdown hook's thread we can perform any remaining task which
needs to be done.
}));
}

Example: Retrieving the InvokedFunctionArn

@OnMethodEnter
static long enter() {
String invokedFunctionArn = null;
for (Object arg : args) {
if (arg instanceof Context) {
Context context = (Context) arg;
invokedFunctionArn = context.getInvokedFunctionArn();
}
}
}

Wrapper scripts
You can create a wrapper script to customize the runtime startup behavior of your Lambda function. A
wrapper script enables you to set configuration parameters that cannot be set through language-specific
environment variables.
Note
Invocations may fail if the wrapper script does not successfully start the runtime process.

The following Lambda runtimes (p. 195) support wrapper scripts:

• Node.js 14.x
• Node.js 12.x

233
 AWS Lambda Developer Guide
Wrapper scripts

• Node.js 10.x
• Python 3.8
• Ruby 2.7
• Java 11
• Java 8 (java8.al2)
• .NET Core 3.1

When you use a wrapper script for your function, Lambda starts the runtime using your script. Lambda
sends to your script the path to the interpreter and all of the original arguments for the standard
runtime startup. Your script can extend or transform the startup behavior of the program. For example,
the script can inject and alter arguments, set environment variables, or capture metrics, errors, and other
diagnostic information.

You specify the script by setting the value of the AWS_LAMBDA_EXEC_WRAPPER environment variable as
the file system path of an executable binary or script.

Example: Create and use a wrapper script with Python 3.8

In the following example, you create a wrapper script to start the Python interpreter with the -X
importtime option. When you run the function, Lambda generates a log entry to show the duration of
the import time for each import.

To create and use a wrapper script with Python 3.8

1. To create the wrapper script, paste the following code into a file named importtime_wrapper:

#!/bin/bash

# the path to the interpreter and all of the originally intended arguments
args=("$@")

# the extra options to pass to the interpreter

extra_args=("-X" "importtime")

# insert the extra options

args=("${args[@]:0:$#-1}" "${extra_args[@]}" "${args[@]: -1}")

# start the runtime with the extra options

exec "${args[@]}"

2. To give the script executable permissions, enter chmod +x importtime_wrapper from the
command line.
3. Deploy the script as a Lambda layer (p. 101).
4. Create a function using the Lambda console.

a. Open the Lambda console.

b. Choose Create function.
c. Under Basic information, for Function name, enter wrapper-test-function.
d. For Runtime, choose Python 3.8.
e. Choose Create function.
5. Add the layer to your function.

a. Choose your function, and then choose Code if it is not already selected.

234
 AWS Lambda Developer Guide
Wrapper scripts

b. Choose Add a layer.

c. Under Choose a layer, choose the Name and Version of the compatible layer that you created
earlier.
d. Choose Add.
6. Add the code and the environment variable to your function.

a. In the function code editor (p. 17), paste the following function code:

import json

def lambda_handler(event, context):

# TODO implement
return {
'statusCode': 200,
'body': json.dumps('Hello from Lambda!')
}

b. Choose Save.
c. Under Environment variables, choose Edit.
d. Choose Add environment variable.
e. For Key, enter AWS_LAMBDA_EXEC_WRAPPER.
f. For Value, enter /opt/importtime_wrapper.
g. Choose Save.
7. To run the function, choose Test.

Because your wrapper script started the Python interpreter with the -X importtime option, the
logs show the time required for each import. For example:

...
2020-06-30T18:48:46.780+01:00 import time: 213 | 213 | simplejson
2020-06-30T18:48:46.780+01:00 import time: 50 | 263 | simplejson.raw_json
...

235
 AWS Lambda Developer Guide
Custom runtimes

Custom AWS Lambda runtimes

You can implement an AWS Lambda runtime in any programming language. A runtime is a program that
runs a Lambda function's handler method when the function is invoked. You can include a runtime in
your function's deployment package in the form of an executable file named bootstrap.

A runtime is responsible for running the function's setup code, reading the handler name from an
environment variable, and reading invocation events from the Lambda runtime API. The runtime passes
the event data to the function handler, and posts the response from the handler back to Lambda.

Your custom runtime runs in the standard Lambda execution environment (p. 195). It can be a shell
script, a script in a language that's included in Amazon Linux, or a binary executable file that's compiled
in Amazon Linux.

To get started with custom runtimes, see Tutorial – Publishing a custom runtime (p. 239). You can also
explore a custom runtime implemented in C++ at awslabs/aws-lambda-cpp on GitHub.

Topics
• Using a custom runtime (p. 236)
• Building a custom runtime (p. 236)

Using a custom runtime

To use a custom runtime, set your function's runtime to provided. The runtime can be included in your
function's deployment package, or in a layer (p. 101).

Example function.zip

.
### bootstrap
### function.sh

If there's a file named bootstrap in your deployment package, Lambda runs that file. If not, Lambda
looks for a runtime in the function's layers. If the bootstrap file isn't found or isn't executable, your
function returns an error upon invocation.

Building a custom runtime

A custom runtime's entry point is an executable file named bootstrap. The bootstrap file can be the
runtime, or it can invoke another file that creates the runtime. The following example uses a bundled
version of Node.js to run a JavaScript runtime in a separate file named runtime.js.

Example bootstrap

#!/bin/sh
cd $LAMBDA_TASK_ROOT
./node-v11.1.0-linux-x64/bin/node runtime.js

Your runtime code is responsible for completing some initialization tasks. Then it processes
invocation events in a loop until it's terminated. The initialization tasks run once per instance of the
function (p. 200) to prepare the environment to handle invocations.

Initialization tasks

• Retrieve settings – Read environment variables to get details about the function and environment.

236
 AWS Lambda Developer Guide
Building a custom runtime

• _HANDLER – The location to the handler, from the function's configuration. The standard format is
file.method, where file is the name of the file without an extension, and method is the name of
a method or function that's defined in the file.
• LAMBDA_TASK_ROOT – The directory that contains the function code.
• AWS_LAMBDA_RUNTIME_API – The host and port of the runtime API.

See Defined runtime environment variables (p. 80) for a full list of available variables.
• Initialize the function – Load the handler file and run any global or static code that it contains.
Functions should create static resources like SDK clients and database connections once, and reuse
them for multiple invocations.
• Handle errors – If an error occurs, call the initialization error (p. 206) API and exit immediately.

Initialization counts towards billed execution time and timeout. When an execution triggers the
initialization of a new instance of your function, you can see the initialization time in the logs and AWS
X-Ray trace (p. 451).

Example log

REPORT RequestId: f8ac1208... Init Duration: 48.26 ms Duration: 237.17 ms Billed

Duration: 300 ms Memory Size: 128 MB Max Memory Used: 26 MB

While it runs, a runtime uses the Lambda runtime interface (p. 205) to manage incoming events and
report errors. After completing initialization tasks, the runtime processes incoming events in a loop. In
your runtime code, perform the following steps in order.

Processing tasks

• Get an event – Call the next invocation (p. 205) API to get the next event. The response body contains
the event data. Response headers contain the request ID and other information.
• Propagate the tracing header – Get the X-Ray tracing header from the Lambda-Runtime-Trace-Id
header in the API response. Set the _X_AMZN_TRACE_ID environment variable locally with the same
value. The X-Ray SDK uses this value to connect trace data between services.
• Create a context object – Create an object with context information from environment variables and
headers in the API response.
• Invoke the function handler – Pass the event and context object to the handler.
• Handle the response – Call the invocation response (p. 206) API to post the response from the
handler.

237
 AWS Lambda Developer Guide
Building a custom runtime

• Handle errors – If an error occurs, call the invocation error (p. 207) API.
• Cleanup – Release unused resources, send data to other services, or perform additional tasks before
getting the next event.

You can include the runtime in your function's deployment package, or distribute the runtime separately
in a function layer. For an example walkthrough, see Tutorial – Publishing a custom runtime (p. 239).

238
 AWS Lambda Developer Guide
Tutorial – Custom runtime

Tutorial – Publishing a custom runtime

In this tutorial, you create a Lambda function with a custom runtime. You start by including the runtime
in the function's deployment package. Then you migrate it to a layer that you manage independently
from the function. Finally, you share the runtime layer with the world by updating its resource-based
permissions policy.

Prerequisites
This tutorial assumes that you have some knowledge of basic Lambda operations and the Lambda
console. If you haven't already, follow the instructions in Getting started with Lambda (p. 9) to create
your first Lambda function.

To complete the following steps, you need a command line terminal or shell to run commands.
Commands and the expected output are listed in separate blocks:

aws --version

You should see the following output:

aws-cli/2.0.57 Python/3.7.4 Darwin/19.6.0 exe/x86_64

For long commands, an escape character (\) is used to split a command over multiple lines.

On Linux and macOS, use your preferred shell and package manager. On Windows 10, you can install the
Windows Subsystem for Linux to get a Windows-integrated version of Ubuntu and Bash.

You need an IAM role to create a Lambda function. The role needs permission to send logs to
CloudWatch Logs and access the AWS services that your function uses. If you don't have a role for
function development, create one now.

To create an execution role

1. Open the roles page in the IAM console.

2. Choose Create role.
3. Create a role with the following properties.

• Trusted entity – Lambda.

• Permissions – AWSLambdaBasicExecutionRole.
• Role name – lambda-role.

The AWSLambdaBasicExecutionRole policy has the permissions that the function needs to write
logs to CloudWatch Logs.

Create a function
Create a Lambda function with a custom runtime. This example includes two files, a runtime bootstrap
file, and a function handler. Both are implemented in Bash.

The runtime loads a function script from the deployment package. It uses two variables to locate the
script. LAMBDA_TASK_ROOT tells it where the package was extracted, and _HANDLER includes the name
of the script.

239
 AWS Lambda Developer Guide
Create a function

Example bootstrap

#!/bin/sh

set -euo pipefail

# Initialization - load function handler

source $LAMBDA_TASK_ROOT/"$(echo $_HANDLER | cut -d. -f1).sh"

# Processing
while true
do
HEADERS="$(mktemp)"
# Get an event. The HTTP request will block until one is received
EVENT_DATA=$(curl -sS -LD "$HEADERS" -X GET "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/
runtime/invocation/next")

# Extract request ID by scraping response headers received above

REQUEST_ID=$(grep -Fi Lambda-Runtime-Aws-Request-Id "$HEADERS" | tr -d '[:space:]' | cut
-d: -f2)

# Run the handler function from the script

RESPONSE=$($(echo "$_HANDLER" | cut -d. -f2) "$EVENT_DATA")

# Send the response

curl -X POST "http://${AWS_LAMBDA_RUNTIME_API}/2018-06-01/runtime/invocation/$REQUEST_ID/
response" -d "$RESPONSE"
done

After loading the script, the runtime processes events in a loop. It uses the runtime API to retrieve an
invocation event from Lambda, passes the event to the handler, and posts the response back to Lambda.
To get the request ID, the runtime saves the headers from the API response to a temporary file, and
reads the Lambda-Runtime-Aws-Request-Id header from the file.
Note
Runtimes have additional responsibilities, including error handling, and providing context
information to the handler. For details, see Building a custom runtime (p. 236).

The script defines a handler function that takes event data, logs it to stderr, and returns it.

Example function.sh

function handler () {
EVENT_DATA=$1
echo "$EVENT_DATA" 1>&2;
RESPONSE="Echoing request: '$EVENT_DATA'"

echo $RESPONSE
}

Save both files in a project directory named runtime-tutorial.

runtime-tutorial
# bootstrap
# function.sh

Make the files executable and add them to a .zip file archive.

runtime-tutorial$ chmod 755 function.sh bootstrap

runtime-tutorial$ zip function.zip function.sh bootstrap

240
 AWS Lambda Developer Guide
Create a layer

adding: function.sh (deflated 24%)

adding: bootstrap (deflated 39%)

Create a function named bash-runtime.

runtime-tutorial$ aws lambda create-function --function-name bash-runtime \

--zip-file fileb://function.zip --handler function.handler --runtime provided \
--role arn:aws:iam::123456789012:role/lambda-role
{
"FunctionName": "bash-runtime",
"FunctionArn": "arn:aws:lambda:us-west-2:123456789012:function:bash-runtime",
"Runtime": "provided",
"Role": "arn:aws:iam::123456789012:role/lambda-role",
"Handler": "function.handler",
"CodeSha256": "mv/xRv84LPCxdpcbKvmwuuFzwo7sLwUO1VxcUv3wKlM=",
"Version": "$LATEST",
"TracingConfig": {
"Mode": "PassThrough"
},
"RevisionId": "2e1d51b0-6144-4763-8e5c-7d5672a01713",
...
}

Invoke the function and verify the response.

runtime-tutorial$ aws lambda invoke --function-name bash-runtime --payload

'{"text":"Hello"}' response.txt --cli-binary-format raw-in-base64-out
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
runtime-tutorial$ cat response.txt
Echoing request: '{"text":"Hello"}'

Create a layer
To separate the runtime code from the function code, create a layer that only contains the runtime.
Layers let you develop your function's dependencies independently, and can reduce storage usage when
you use the same layer with multiple functions.

Create a layer archive that contains the bootstrap file.

runtime-tutorial$ zip runtime.zip bootstrap

adding: bootstrap (deflated 39%)

Create a layer with the publish-layer-version command.

runtime-tutorial$ aws lambda publish-layer-version --layer-name bash-runtime --zip-file

fileb://runtime.zip
{
"Content": {
"Location": "https://awslambda-us-west-2-layers.s3.us-west-2.amazonaws.com/
snapshots/123456789012/bash-runtime-018c209b...",
"CodeSha256": "bXVLhHi+D3H1QbDARUVPrDwlC7bssPxySQqt1QZqusE=",
"CodeSize": 584,
"UncompressedCodeSize": 0
},
"LayerArn": "arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime",
"LayerVersionArn": "arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:1",

241
 AWS Lambda Developer Guide
Update the function

"Description": "",
"CreatedDate": "2018-11-28T07:49:14.476+0000",
"Version": 1
}

This creates the first version of the layer.

Update the function

To use the runtime layer with the function, configure the function to use the layer, and remove the
runtime code from the function.

Update the function configuration to pull in the layer.

runtime-tutorial$ aws lambda update-function-configuration --function-name bash-runtime \

--layers arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:1
{
"FunctionName": "bash-runtime",
"Layers": [
{
"Arn": "arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:1",
"CodeSize": 584,
"UncompressedCodeSize": 679
}
]
...
}

This adds the runtime to the function in the /opt directory. Lambda uses this runtime, but only if you
remove it from the function's deployment package. Update the function code to only include the handler
script.

runtime-tutorial$ zip function-only.zip function.sh

adding: function.sh (deflated 24%)
runtime-tutorial$ aws lambda update-function-code --function-name bash-runtime --zip-file
fileb://function-only.zip
{
"FunctionName": "bash-runtime",
"CodeSize": 270,
"Layers": [
{
"Arn": "arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:7",
"CodeSize": 584,
"UncompressedCodeSize": 679
}
]
...
}

Invoke the function to verify that it works with the runtime layer.

runtime-tutorial$ aws lambda invoke --function-name bash-runtime --payload

'{"text":"Hello"}' response.txt
{
"StatusCode": 200,
"ExecutedVersion": "$LATEST"
}
runtime-tutorial$ cat response.txt
Echoing request: '{"text":"Hello"}'

242
 AWS Lambda Developer Guide
Update the runtime

Update the runtime

To log information about the execution environment, update the runtime script to output environment
variables.

Example bootstrap

#!/bin/sh

set -euo pipefail

echo "## Environment variables:"

env

# Initialization - load function handler

source $LAMBDA_TASK_ROOT/"$(echo $_HANDLER | cut -d. -f1).sh"
...

Create a second version of the layer with the new code.

runtime-tutorial$ zip runtime.zip bootstrap

updating: bootstrap (deflated 39%)
runtime-tutorial$ aws lambda publish-layer-version --layer-name bash-runtime --zip-file
fileb://runtime.zip

Configure the function to use the new version of the layer.

runtime-tutorial$ aws lambda update-function-configuration --function-name bash-runtime \

--layers arn:aws:lambda:us-west-2:123456789012:layer:bash-runtime:2

Share the layer

Add a permission statement to your runtime layer to share it with other accounts.

runtime-tutorial$ aws lambda add-layer-version-permission --layer-name bash-runtime --

version-number 2 \
--principal "*" --statement-id publish --action lambda:GetLayerVersion
{
"Statement": "{\"Sid\":\"publish\",\"Effect\":\"Allow\",\"Principal\":\"*\",\"Action\":
\"lambda:GetLayerVersion\",\"Resource\":\"arn:aws:lambda:us-west-2:123456789012:layer:bash-
runtime:2\"}",
"RevisionId": "9d5fe08e-2a1e-4981-b783-37ab551247ff"
}

You can add multiple statements that each grant permission to a single account, accounts in an
organization, or all accounts.

Clean up
Delete each version of the layer.

runtime-tutorial$ aws lambda delete-layer-version --layer-name bash-runtime --version-

number 1
runtime-tutorial$ aws lambda delete-layer-version --layer-name bash-runtime --version-
number 2

243
 AWS Lambda Developer Guide
Clean up

Because the function holds a reference to version 2 of the layer, it still exists in Lambda. The function
continues to work, but functions can no longer be configured to use the deleted version. If you then
modify the list of layers on the function, you must specify a new version or omit the deleted layer.

Delete the tutorial function with the delete-function command.

runtime-tutorial$ aws lambda delete-function --function-name bash-runtime

244
 AWS Lambda Developer Guide
AVX2 vectorization

Using AVX2 vectorization in Lambda

Advanced Vector Extensions 2 (AVX2) is a vectorization extension to the Intel x86 instruction set that can
perform single instruction multiple data (SIMD) instructions over vectors of 256 bits. For vectorizable
algorithms with highly parallelizable operation, using AVX2 can enhance CPU performance, resulting in
lower latencies and higher throughput. Use the AVX2 instruction set for compute-intensive workloads
such as machine learning inferencing, multimedia processing, scientific simulations, and financial
modeling applications.

To use AVX2 with your Lambda function, make sure that your function code is accessing AVX2-optimized
code. For some languages, you can install the AVX2-supported version of libraries and packages. For
other languages, you can recompile your code and dependencies with the appropriate compiler flags
set (if the compiler supports auto-vectorization). You can also compile your code with third-party
libraries that use AVX2 to optimize math operations. For example, Intel Math Kernel Library (Intel MKL),
OpenBLAS (Basic Linear Algebra Subprograms), and AMD BLAS-like Library Instantiation Software (BLIS).
Auto-vectorized languages, such as Java, automatically use AVX2 for computations.

You can create new Lambda workloads or move existing AVX2-enabled workloads to Lambda at no
additional cost.

For more information about AVX2, see Advanced Vector Extensions 2 in Wikipedia.

Compiling from source

If your Lambda function uses a C or C++ library to perform compute-intensive vectorizable operations,
you can set the appropriate compiler flags and recompile the function code. Then, the compiler
automatically vectorizes your code.

For the gcc or clang compiler, add -march=haswell to the command or set -mavx2 as a command
option.

~ gcc -march=haswell main.c

or
~ gcc -mavx2 main.c

~ clang -march=haswell main.c

or
~ clang -mavx2 main.c

To use a specific library, follow instructions in the library's documentation to compile and build the
library. For example, to build TensorFlow from source, you can follow the installation instructions on the
TensorFlow website. Make sure to use the -march=haswell compile option.

Enabling AVX2 for Intel MKL

Intel MKL is a library of optimized math operations that implicitly use AVX2 instructions when the
compute platform supports them. Frameworks such as PyTorch build with Intel MKL by default, so you
don't need to enable AVX2.

Some libraries, such as TensorFlow, provide options in their build process to specify Intel MKL
optimization. For example, with TensorFlow, use the --config=mkl option.

You can also build popular scientific Python libraries, such as SciPy and NumPy, with Intel MKL. For
instructions on building these libraries with Intel MKL, see Numpy/Scipy with Intel MKL and Intel
Compilers on the Intel website.

245
 AWS Lambda Developer Guide
AVX2 support in other languages

For more information about Intel MKL and similar libraries, see Math Kernel Library in Wikipedia, the
OpenBLAS website, and the AMD BLIS repository on GitHub.

AVX2 support in other languages

If you don't use C or C++ libraries and don't build with Intel MKL, you can still get some AVX2
performance improvement for your applications. Note that the actual improvement depends on the
compiler or interpreter's ability to utilize the AVX2 capabilities on your code.

Python

Python users generally use SciPy and NumPy libraries for compute-intensive workloads. You can
compile these libraries to enable AVX2, or you can use the Intel MKL-enabled versions of the
libraries.
Node

For compute-intensive workloads, use AVX2-enabled or Intel MKL-enabled versions of the libraries
that you need.
Java

Java's JIT compiler can auto-vectorize your code to run with AVX2 instructions. For information
about detecting vectorized code, see the Code vectorization in the JVM presentation on the
OpenJDK website.
Go

The standard Go compiler doesn't currently support auto-vectorization, but you can use gccgo, the
GCC compiler for Go. Set the -mavx2 option:

gcc -o avx2 -mavx2 -Wall main.c

Intrinsics

It's possible to use intrinsic functions in many languages to manually vectorize your code to use
AVX2. However, we don't recommend this approach. Manually writing vectorized code takes
significant effort. Also, debugging and maintaining such code is more difficult than using code that
depends on auto-vectorization.

246
 AWS Lambda Developer Guide

Using container images with Lambda

You can package your code and dependencies as a container image using tools such as the Docker
command line interface (CLI). You can then upload the image to your container registry hosted on
Amazon Elastic Container Registry (Amazon ECR).

AWS provides a set of open-source base images that you can use to build the container image for
your function code. You can also use alternative base images from other container registries. AWS
also provides an open-source runtime client that you add to your alternative base image to make it
compatible with the Lambda service.

Additionally, AWS provides a runtime interface emulator for you to test your functions locally using tools
such as the Docker CLI.

There is no additional charge for packaging and deploying functions as container images. When a
function deployed as a container image is invoked, you pay for invocation requests and execution
duration. You do incur charges related to storing your container images in Amazon ECR. For more
information, see Amazon ECR pricing.

Topics
• Creating Lambda container images (p. 248)
• Testing Lambda container images locally (p. 254)

247
 AWS Lambda Developer Guide
Creating images

Creating Lambda container images

You can package your Lambda function code and dependencies as a container image, using tools such
as the Docker CLI. You can then upload the image to your container registry hosted on Amazon Elastic
Container Registry (Amazon ECR). Note that you must create the Lambda function from the same
account as the container registry in Amazon ECR.

AWS provides a set of open-source base images (p. 203) that you can use to create your container
image. These base images include a runtime interface client (p. 203) to manage the interaction between
Lambda and your function code.

You can also use an alternative base image from another container registry. Lambda provides open-
source runtime interface clients that you add to an alternative base image to make it compatible with
Lambda.

For example applications, including a Node.js example and a Python example, see Container image
support for Lambda on the AWS Blog.

After you create a container image in the Amazon ECR container registry, you can create and run (p. 72)
the Lambda function.

Topics
• Image types (p. 248)
• Container tools (p. 248)
• Lambda requirements for container images (p. 249)
• Container image settings (p. 249)
• Create an image from an AWS base image for Lambda (p. 249)
• Create an image from an alternative base image (p. 251)
• Create an image using the AWS SAM toolkit (p. 253)

Image types
You can use an AWS provided base image or an alternative base image, such as Alpine or Debian. Lambda
supports any image that conforms to one of the following image manifest formats:

• Docker image manifest V2, schema 2 (used with Docker version 1.10 and newer)
• Open Container Initiative (OCI) Specifications (v1.0.0 and up)

Lambda supports images up to 10 GB in size.

Container tools
To create your container image, you can use any development tool that supports one of the following
container image manifest formats:

• Docker image manifest V2, schema 2 (used with Docker version 1.10 and newer)
• OCI Specifications (v1.0.0 and up)

For example, you can use the Docker CLI to build, test, and deploy your container images.

248
 AWS Lambda Developer Guide
Lambda requirements for container images

Lambda requirements for container images

To deploy a container image to Lambda, note the following requirements:

1. The container image must implement the Lambda Runtime API (p. 205). The AWS open-source
runtime interface clients (p. 203) implement the API. You can add a runtime interface client to your
preferred base image to make it compatible with Lambda.
2. The container image must be able to run on a read-only file system. Your function code can access a
writable /tmp directory with 512 MB of storage.
3. The default Lambda user must be able to read all the files required to run your function code. Lambda
follows security best practices by defining a default Linux user with least-privileged permissions.
Verify that your application code does not rely on files that other Linux users are restricted from
running.
4. Lambda supports only Linux-based container images.

Container image settings

Lambda supports the following container image settings in the Dockerfile:

• ENTRYPOINT – Specifies the absolute path to the entry point of the application.
• CMD – Specifies parameters that you want to pass in with ENTRYPOINT.
• WORKDIR – Specifies the absolute path to the working directory.
• ENV – Specifies an environment variable for the Lambda function.

Note
Lambda ignores the values of any unsupported container image settings in the Dockerfile.

For more information about how Docker uses the container image settings, see ENTRYPOINT in the
Dockerfile reference on the Docker Docs website. For more information about using ENTRYPOINT and
CMD, see Demystifying ENTRYPOINT and CMD in Docker on the AWS Open Source Blog.

You can specify the container image settings in the Dockerfile when you build your image. You can
also override these configurations using the Lambda console or Lambda API. This allows you to deploy
multiple functions that deploy the same container image but with different runtime configurations.
Warning
When you specify ENTRYPOINT or CMD in the Dockerfile or as an override, make sure that you
enter the absolute path. Also, do not use symlinks as the entry point to the container.

Create an image from an AWS base image for

Lambda
To build a container image for a new Lambda function, you can start with an AWS base image for
Lambda.
Note
AWS periodically provides updates to the AWS base images for Lambda. If your Dockerfile
includes the image name in the FROM property, your Docker client pulls the latest version of the
image from Docker Hub. To use the updated base image, you must rebuild your container image
and update the function code (p. 74).

Prerequisites

249
 AWS Lambda Developer Guide
Create an image from an AWS base image for Lambda

• The AWS Command Line Interface (AWS CLI)

The following instructions use the AWS CLI to call AWS service API operations. To install the AWS CLI,
see Installing, updating, and uninstalling the AWS CLI in the AWS Command Line Interface User Guide.
• Docker Desktop

The following instructions use Docker CLI commands to create the container image. To install the
Docker CLI, see Get Docker on the Docker Docs website.
• Your function code

To create an image from an AWS base image for Lambda

1. On your local machine, create a project directory for your new function.
2. Create a directory named app in in the project directory, and then add your function handler code to
the app directory.
3. Use a text editor to create a new Dockerfile.

The AWS base images provide the following environment variables:

• LAMBDA_TASK_ROOT=/var/task
• LAMBDA_RUNTIME_DIR=/var/runtime

The following shows an example Dockerfile for Node.js version 14. :

FROM public.ecr.aws/lambda/nodejs:14
# Alternatively, you can pull the base image from Docker Hub: amazon/aws-lambda-
nodejs:12

# Assumes your function is named "app.js", and there is a package.json file in the app
directory.
COPY app.js package.json /var/task/

# Install NPM dependencies for function

RUN npm install

# Set the CMD to your handler (could also be done as a parameter override outside of
the Dockerfile)
CMD [ "app.handler" ]

4. Build your Docker image with the docker build command. Enter a name for the image. The
following example names the image hello-world.

docker build -t hello-world .

5. Start the Docker image with the docker run command. For this example, enter hello-world as
the image name.

docker run -p 9000:8080 hello-world

6. (Optional) Test your application locally using the runtime interface emulator (p. 254). From a new
terminal window, post an event to the following endpoint using a curl command:

curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

This command invokes the function running in the container image and returns a response.
7. Authenticate the Docker CLI to your Amazon ECR registry.

250
 AWS Lambda Developer Guide
Create an image from an alternative base image

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-
stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

8. Create a repository in Amazon ECR using the create-repository command.

aws ecr create-repository --repository-name hello-world --image-scanning-configuration

scanOnPush=true --image-tag-mutability MUTABLE

9. Tag your image to match your repository name, and deploy the image to Amazon ECR using the
docker push command.

docker tag hello-world:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/hello-

world:latest
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest

Now that your container image resides in the Amazon ECR container registry, you can create and
run (p. 72) the Lambda function.

Create an image from an alternative base image

Prerequisites

• The AWS CLI

• Docker Desktop
• Your function code

To create an image using an alternative base image

1. Choose a base image. Lambda supports all Linux distributions, such as Alpine, Debian, and Ubuntu.
2. On your local machine, create a project directory for your new function.
3. Create a directory named app in the project directory, and then add your function handler code to
the app directory.
4. Use a text editor to create a new Dockerfile with the following configuration:

• Set the FROM property to the URI of the base image.

• Add instructions to install the runtime interface client.
• Set the ENTRYPOINT property to invoke the runtime interface client.
• Set the CMD argument to specify the Lambda function handler.

The following example shows a Dockerfile for Python:

# Define function directory

ARG FUNCTION_DIR="/function"

FROM python:buster as build-image

# Install aws-lambda-cpp build dependencies

RUN apt-get update && \
apt-get install -y \
g++ \
make \
cmake \
unzip \

251
 AWS Lambda Developer Guide
Create an image from an alternative base image

libcurl4-openssl-dev

# Include global arg in this stage of the build

ARG FUNCTION_DIR
# Create function directory
RUN mkdir -p ${FUNCTION_DIR}

# Copy function code

COPY app/* ${FUNCTION_DIR}

# Install the runtime interface client

RUN pip install \
--target ${FUNCTION_DIR} \
awslambdaric

# Multi-stage build: grab a fresh copy of the base image

FROM python:buster

# Include global arg in this stage of the build

ARG FUNCTION_DIR
# Set working directory to function root directory
WORKDIR ${FUNCTION_DIR}

# Copy in the build image dependencies

COPY --from=build-image ${FUNCTION_DIR} ${FUNCTION_DIR}

ENTRYPOINT [ "/usr/local/bin/python", "-m", "awslambdaric" ]

CMD [ "app.handler" ]

5. Build your Docker image with the docker build command. Enter a name for the image. The
following example names the image hello-world.

docker build -t hello-world .

6. (Optional) Test your application locally using the Runtime interface emulator (p. 254).
7. Authenticate the Docker CLI to your Amazon ECR registry.

aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-
stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com

8. Create a repository in Amazon ECR using the create-repository command.

aws ecr create-repository --repository-name hello-world --image-scanning-configuration

scanOnPush=true --image-tag-mutability MUTABLE

9. Tag your image to match your repository name, and deploy the image to Amazon ECR using the
docker push command.

docker tag hello-world:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/hello-

world:latest
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/hello-world:latest

Now that your container image resides in the Amazon ECR container registry, you can create and
run (p. 72) the Lambda function.

252
 AWS Lambda Developer Guide
Create an image using the AWS SAM toolkit

Create an image using the AWS SAM toolkit

You can use the AWS Serverless Application Model (AWS SAM) toolkit to create and deploy a function
defined as a container image. For a new project, you can use the AWS SAM CLI init command to set up
the scaffolding for your project in your preferred runtime.

In your AWS SAM template, you set the Runtime type to Image and provide the URI of the base image.

For more information, see Building applications in the AWS Serverless Application Model Developer Guide.

253
 AWS Lambda Developer Guide
Testing images

Testing Lambda container images locally

The AWS Lambda Runtime Interface Emulator (RIE) is a proxy for the Lambda Runtime API that allows
you to locally test your Lambda function packaged as a container image. The emulator is a lightweight
web server that converts HTTP requests into JSON events to pass to the Lambda function in the
container image.

The AWS base images for Lambda include the RIE component. If you use an alternate base image, you
can test your image without adding RIE to the image. You can also build the RIE component into your
base image. AWS provides an open-sourced RIE component on the AWS GitHub repository.

You can use the emulator to test whether your function code is compatible with the Lambda
environment. Also use the emulator to test that your Lambda function runs to completion successfully
and provides the expected output. If you build extensions and agents into your container image, you can
use the emulator to test that the extensions and agents work correctly with the Lambda Extensions API.

For examples of how to use the RIE, see Container image support for Lambda on the AWS Blog.

Topics
• Guidelines for using the RIE (p. 254)
• Environment variables (p. 254)
• Test an image with RIE included in the image (p. 255)
• Build RIE into your base image (p. 255)
• Test an image without adding RIE to the image (p. 256)

Guidelines for using the RIE

Note the following guidelines when using the Runtime Interface Emulator:

• The RIE does not emulate Lambda’s security and authentication configurations, or Lambda
orchestration.
• The emulator supports only Linux x86-64 architectures.
• The emulator does not support AWS X-Ray tracing or other Lambda integrations.

Environment variables
The runtime interface emulator supports a subset of environment variables (p. 77) for the Lambda
function in the local running image.

If your function uses security credentials, you can configure the credentials by setting the following
environment variables:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_SESSION_TOKEN
• AWS_REGION

To set the function timeout, configure AWS_LAMBDA_FUNCTION_TIMEOUT. Enter the maximum number
of seconds that you want to allow the function to run.

The emulator does not populate the following Lambda environment variables. However, you can set
them to match the values that you expect when the function runs in the Lambda service:

254
 AWS Lambda Developer Guide
Test an image with RIE included in the image

• AWS_LAMBDA_FUNCTION_VERSION
• AWS_LAMBDA_FUNCTION_NAME
• AWS_LAMBDA_FUNCTION_MEMORY_SIZE

Test an image with RIE included in the image

The AWS base images for Lambda include the runtime interface emulator. You can also follow these
steps if you built the RIE into your alternative base image.

To test your Lambda function with the emulator

1. Build your image locally using the docker build command.

docker build -t myfunction:latest .

2. Run your container image locally using the docker run command.

docker run -p 9000:8080 myfunction:latest

This command runs the image as a container and starts up an endpoint locally at
localhost:9000/2015-03-31/functions/function/invocations.
3. From a new terminal window, post an event to the following endpoint using a curl command:

curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

This command invokes the Lambda function running in the container image and returns a response.

Build RIE into your base image

You can build RIE into a base image. Download the RIE from GitHub to your local machine and update
your Dockerfile to install RIE.

To build the emulator into your image

1. Create a script and save it in your project directory. Set execution permissions for the script file.

The script checks for the presence of the AWS_LAMBDA_RUNTIME_API environment variable, which
indicates the presence of the runtime API. If the runtime API is present, the script runs the runtime
interface client (p. 203). Otherwise, the script runs the runtime interface emulator.

The following example shows a typical script for a Node.js function.

#!/bin/sh
if [ -z "${AWS_LAMBDA_RUNTIME_API}" ]; then
exec /usr/local/bin/aws-lambda-rie /usr/local/bin/npx aws-lambda-ric $@
else
exec /usr/local/bin/npx aws-lambda-ric $@
fi

The following example shows a typical script for a Python function.

#!/bin/sh
if [ -z "${AWS_LAMBDA_RUNTIME_API}" ]; then

255
 AWS Lambda Developer Guide
Test an image without adding RIE to the image

exec /usr/local/bin/aws-lambda-rie /usr/local/bin/python -m awslambdaric $@

else
exec /usr/local/bin/python -m awslambdaric $@
fi

2. Download the runtime interface emulator from GitHub into your project directory.
3. Copy the script, install the emulator package, and change ENTRYPOINT to run the new script by
adding the following lines to your Dockerfile:

COPY ./entry_script.sh /entry_script.sh

ADD aws-lambda-rie /usr/local/bin/aws-lambda-rie
ENTRYPOINT [ "/entry_script.sh" ]

4. Build your image locally using the docker build command.

docker build -t myfunction:latest .

Test an image without adding RIE to the image

You install the runtime interface emulator to your local machine. When you run the container image, you
set the entry point to be the emulator.

To test an image without adding RIE to the image

1. From your project directory, run the following command to download the RIE from GitHub and
install it on your local machine.

mkdir -p ~/.aws-lambda-rie && curl -Lo ~/.aws-lambda-rie/aws-lambda-rie \

https://github.com/aws/aws-lambda-runtime-interface-emulator/releases/latest/download/
aws-lambda-rie \
&& chmod +x ~/.aws-lambda-rie/aws-lambda-rie

2. Run your Lambda function using the docker run command.

docker run -d -v ~/.aws-lambda-rie:/aws-lambda -p 9000:8080 \

--entrypoint /aws-lambda/aws-lambda-rie hello-world:latest <image entrypoint> \
<(optional) image command>

This runs the image as a container and starts up an endpoint locally at

localhost:9000/2015-03-31/functions/function/invocations.
3. Post an event to the following endpoint using a curl command:

curl -XPOST "http://localhost:9000/2015-03-31/functions/function/invocations" -d '{}'

This command invokes the function running in the container image and returns a response.

256
 AWS Lambda Developer Guide

Using AWS Lambda with other

services
AWS Lambda integrates with other AWS services to invoke functions. You can configure triggers to
invoke a function in response to resource lifecycle events, respond to incoming HTTP requests, consume
events from a queue, or run on a schedule (p. 295).

Each service that integrates with Lambda sends data to your function in JSON as an event. The structure
of the event document is different for each event type, and contains data about the resource or request
that triggered the function. Lambda runtimes convert the event into an object and pass it to your
function.

The following example shows a test event from an Application Load Balancer (p. 349) that represents a
GET request to /lambda?query=1234ABCD.

Example event from an Application Load Balancer

{
"requestContext": {
"elb": {
"targetGroupArn": "arn:aws:elasticloadbalancing:us-
east-2:123456789012:targetgroup/lambda-279XGJDqGZ5rsrHC2Fjr/49e9d65c45c6791a"
}
},
"httpMethod": "GET",
"path": "/lambda",
"queryStringParameters": {
"query": "1234ABCD"
},
"headers": {
"accept": "text/html,application/xhtml+xml,applicati