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. For a function defined as a container image, 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.
Topics
- Configuring a function to use layers
- Accessing the contents of a layer
- Finding layer information
- Updating a layer version that your function uses
- Adding layer permissions
- Using AWS SAM to add a layer to a function
- Sample applications
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.
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",
"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.
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 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.
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",
]
}
}
]
}
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
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
-
(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 -
(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 -
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
To use a Lambda function with a layer, you need permission to call the GetLayerVersion API operation on the layer version. For functions in your AWS account, you can add this permission from your user policy.
To use a layer in another account, the owner of that account must grant your account permission in a resource-based policy.
For examples, see Granting layer access to other accounts.
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](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-function.html)
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](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-resource-layerversion.html)
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.
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. For other samples, see Lambda sample applications.