Managing Lambda Event Function dependencies with layers

A Lambda layer is a .zip file archive that contains supplementary code or data. Layers usually contain library dependencies, a custom runtime, or configuration files.

There are multiple reasons why you might consider using layers:

• To reduce the size of your deployment packages. Instead of including all of your Event Function dependencies along with your Event Function code in your deployment package, put them in a layer. This keeps deployment packages small and organized.

• To separate core function logic from dependencies. With layers, you can update your Event Function dependencies independent of your Event Function code, and vice versa. This promotes separation of concerns and helps you focus on your Event Function logic.

• To share dependencies across multiple functions. After you create a layer, you can apply it to any number of Event Functions in your account. Without layers, you need to include the same dependencies in each individual deployment package.

• To use the Lambda console code editor. The code editor is a useful tool for testing minor Event Function code updates quickly. However, you can't use the editor if your deployment package size is too large. Using layers reduces your package size and can unlock usage of the code editor.

• To lock an embedded SDK version.The embedded SDKs might change without notice as AWS releases new services and features. You can lock a version of the SDK by creating a Lambda layer with the specific version needed. The Event Function then always uses the version in the layer, even if the version embedded in the service changes.

If you're working with Lambda Event Functions in Go or Rust, we recommend against using layers. For Go and Rust Event Functions, you provide your Event Function code as an executable, which includes your compiled Event Function code along with all of its dependencies. Putting your dependencies in a layer forces your Event Function to manually load additional assemblies during the initialization phase, which can increase cold start times. For optimal performance for Go and Rust Event Functions, include your dependencies along with your deployment package.

The following diagram illustrates the high-level architectural differences between two Event Functions that share dependencies. One uses Lambda layers, and the other does not.

When you add a layer to an Event Function, Lambda extracts the layer contents into the /opt directory in your Event Function's execution environment. All natively supported Lambda runtimes include paths to specific directories within the /opt directory. This gives your Event Function access to your layer content. For more information about these specific paths and how to properly package your layers, see Packaging your layer content.

You can include up to five layers per Event Function. Also, you can use layers only with Lambda Event Functions deployed as a .zip file archive. For Event Functions defined as a container image, 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

• How to use layers

• Layers and layer versions

• Packaging your layer content

• Creating and deleting layers in Lambda

• Adding layers to Event Functions

• Using AWS CloudFormation with layers

• Using AWS SAM with layers

How to use layers

To create a layer, package your dependencies into a .zip file, similar to how you create a normal deployment package. More specifically, the general process of creating and using layers involves these three steps:

• First, package your layer content. This means creating a .zip file archive. For more information, see Packaging your layer content.

• Next, create the layer in Lambda. For more information, see Creating and deleting layers in Lambda.

• Add the layer to your Event Function(s). For more information, see Adding layers to Event Functions.

Layers and layer versions

A layer version is an immutable snapshot of a specific version of a layer. When you create a new layer, Lambda creates a new layer version with a version number of 1. Each time you publish an update to the layer, Lambda increments the version number and creates a new layer version.

Every layer version is identified by a unique Amazon Resource Name (ARN). When adding a layer to the Event Function, you must specify the exact layer version you want to use (for example, arn:aws:lambda:us-east-1:123456789012:layer:my-layer:1).