Lambda Layers and Environment Variables

As your serverless applications grow, you need strategies for sharing code across functions and externalising configuration. Lambda Layers let you package shared libraries, custom runtimes, and common utilities separately from your function code. Environment variables provide a mechanism for injecting configuration without modifying code.

---

What Are Lambda Layers?

A Lambda Layer is a ZIP archive containing libraries, a custom runtime, or other dependencies. Layers are extracted to the /opt directory in the execution environment and are available to your function code at runtime.

Execution Environment
+------------------------------------------+
|  /opt/                                   |
|  ├── nodejs/node_modules/  (Layer 1)     |
|  ├── python/lib/           (Layer 2)     |
|  └── custom-bin/           (Layer 3)     |
|                                          |
|  /var/task/                              |
|  └── index.mjs             (Your code)  |
+------------------------------------------+

Why Use Layers?

Benefit	Description
Code sharing	Share common libraries across multiple functions without duplicating code
Smaller deployments	Function packages shrink because dependencies live in layers
Independent updates	Update a shared library once in the layer; all functions pick it up
Separation of concerns	Business logic stays in the function; infrastructure dependencies live in layers
Custom runtimes	Package a language runtime as a layer (e.g., Rust, PHP, COBOL)

---

Layer Structure by Runtime

Each runtime expects layer contents in a specific directory structure:

Runtime	Layer Path	How It Works
Node.js	nodejs/node_modules/	Added to NODE_PATH automatically
Python	python/lib/python3.x/site-packages/	Added to sys.path automatically
Java	java/lib/	Added to classpath
Ruby	ruby/gems/3.x.0/	Added to GEM_PATH
Custom	bin/	Added to PATH
All	Any path under /opt/	Access via /opt/your-path

Creating a Node.js Layer

# Create the layer directory structure
mkdir -p my-layer/nodejs

# Install shared dependencies into the layer
cd my-layer/nodejs
npm init -y
npm install lodash dayjs uuid

# Package the layer
cd ..
zip -r my-layer.zip nodejs/

# Publish the layer
aws lambda publish-layer-version \
  --layer-name shared-utilities \
  --zip-file fileb://my-layer.zip \
  --compatible-runtimes nodejs18.x nodejs20.x \
  --description "Shared utilities: lodash, dayjs, uuid"

Creating a Python Layer

mkdir -p my-layer/python

pip install requests boto3 -t my-layer/python/

cd my-layer
zip -r my-layer.zip python/

aws lambda publish-layer-version \
  --layer-name python-deps \
  --zip-file fileb://my-layer.zip \
  --compatible-runtimes python3.11 python3.12

---

Using Layers in Functions

AWS CLI

aws lambda update-function-configuration \
  --function-name my-function \
  --layers \
    arn:aws:lambda:eu-west-1:123456789012:layer:shared-utilities:3 \
    arn:aws:lambda:eu-west-1:123456789012:layer:monitoring:1

SAM Template

Resources:
  SharedLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: shared-utilities
      ContentUri: layers/shared/
      CompatibleRuntimes:
        - nodejs20.x
      RetentionPolicy: Retain

  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: index.handler
      Runtime: nodejs20.x
      Layers:
        - !Ref SharedLayer

In Your Function Code

// Modules from the layer are available as normal imports
import { v4 as uuidv4 } from 'uuid';    // From layer
import dayjs from 'dayjs';               // From layer

export const handler = async (event) => {
  const id = uuidv4();
  const timestamp = dayjs().toISOString();
  return { statusCode: 200, body: JSON.stringify({ id, timestamp }) };
};

---

Layer Limits and Constraints

Constraint	Limit
Maximum layers per function	5
Total unzipped size (function + all layers)	250 MB
Maximum layer archive (zipped)	50 MB (direct upload), 250 MB (via S3)
Layer versions	Immutable — each publish creates a new version
Cross-account sharing	Supported via layer permissions
Cross-region	Not supported — layers must be in the same region as the function

Layer Version Immutability

Each publish-layer-version call creates a new, immutable version:

shared-utilities:1  ->  lodash 4.17.20, dayjs 1.10.0
shared-utilities:2  ->  lodash 4.17.21, dayjs 1.11.0  (updated)
shared-utilities:3  ->  lodash 4.17.21, dayjs 1.11.0, uuid 9.0.0  (added uuid)

Functions reference a specific layer version. Updating a layer does not automatically update functions — you must explicitly update the function configuration to point to the new version.

---

AWS-Provided Layers

AWS provides several useful layers: