AWS Serverless Deployment

SAM Project Setup Guide

Template Selection

Choose the right template based on your use case:

Use get_serverless_templates to browse additional templates from Serverless Land for specific patterns (e.g., API + DynamoDB, step functions, event processing).

Architecture Selection

Choose arm64 (Graviton) for better price-performance unless you have x86-specific dependencies.

Project Structure

my-serverless-app/
├── template.yaml          # SAM template
├── samconfig.toml         # Deployment configuration
├── src/                   # Function source code
│   ├── handlers/          # Lambda function handlers
│   ├── layers/            # Shared layers
│   └── utils/             # Utility functions
├── events/                # Test event files
└── tests/                 # Unit and integration tests

Testability tip: Extract pure business logic (calculations, validations, decisions) into plain functions that don't import the AWS SDK. This lets you unit test core logic without mocking — reserve mocks for the handler-level tests that exercise SDK calls.

Template Configuration

Global Settings

Set global defaults in template.yaml to apply to all functions:

Globals:
  Function:
    Timeout: 30
    MemorySize: 512
    Runtime: python3.12
    Tracing: Active
    Environment:
      Variables:
        LOG_LEVEL: INFO
        POWERTOOLS_SERVICE_NAME: my-service

Environment Parameters

Use CloudFormation parameters to make templates environment-aware:

Parameters:
  Environment:
    Type: String
    Default: dev
    AllowedValues: [dev, staging, prod]

Reference !Ref Environment in resource names and configuration to differentiate stacks.

Development Workflow

1. Initialize

Use sam_init with chosen runtime, template, and dependency manager.

2. Develop

Write handler code in src/handlers/. Create test events in events/.

3. Build

Use sam_build before every deployment. Use --use-container for consistent builds with Lambda-compatible dependencies.

4. Test Locally

Use sam_local_invoke with a test event to validate before deploying. For API-triggered functions, use sam local start-api to test with real HTTP requests (see Testing > Local Integration Testing below).

5. Deploy

Use sam_deploy with guided: true for the first deploy, which generates samconfig.toml. For subsequent deploys, sam_deploy reads from samconfig.toml.

6. Monitor

Use sam_logs to check function output. Use get_metrics to monitor health.

Deployment Strategies

Canary and Linear Deployments

For production APIs, use SAM's built-in DeploymentPreference to shift traffic gradually and automatically roll back on errors. This uses CodeDeploy and Lambda aliases under the hood.

Globals:
  Function:
    AutoPublishAlias: live

Resources:
  MyFunction:
    Type: AWS::Serverless::Function
    Properties:
      DeploymentPreference:
        Type: Canary10Percent5Minutes  # 10% for 5 min, then 100%
        Alarms:
          - !Ref MyFunctionErrorAlarm

Available deployment types:

Set DeploymentPreference.Alarms to a CloudWatch alarm on error rate. CodeDeploy automatically rolls back if the alarm fires during the shift window.

Lambda Layers

Layers let you share code and dependencies across functions without including them in each deployment package.

When to use layers:

• Shared business logic used by multiple functions

• Large dependencies (e.g., pandas, Pillow) you want to cache separately

• AWS Lambda Powertools (AWS provides a managed layer ARN per runtime/region)

Add a layer in SAM template:

MyLayer:
  Type: AWS::Serverless::LayerVersion
  Properties:
    LayerName: my-shared-utils
    ContentUri: layers/shared-utils/
    CompatibleRuntimes:
      - python3.12
    RetentionPolicy: Retain

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    Layers:
      - !Ref MyLayer

Limits: Maximum 5 layers per function. Total uncompressed size of function + layers must be under 250 MB.

Container Images

Lambda supports container images up to 10 GB as a first-class deployment model alongside zip packages.

When to Use Container Images

Use container images when your deployment package exceeds 250 MB (ML models, large native dependencies), you need OS-level packages not available in Lambda runtimes, or your team already has Docker build pipelines.

Dockerfile Examples

Python (multi-stage build):

FROM public.ecr.aws/lambda/python:3.12 AS builder
COPY requirements.txt .
RUN pip install --target /asset -r requirements.txt

FROM public.ecr.aws/lambda/python:3.12
COPY --from=builder /asset ${LAMBDA_TASK_ROOT}
COPY src/ ${LAMBDA_TASK_ROOT}/
CMD ["app.handler"]

Node.js:

FROM public.ecr.aws/lambda/nodejs:22
COPY package.json package-lock.json ${LAMBDA_TASK_ROOT}/
RUN npm ci --omit=dev
COPY src/ ${LAMBDA_TASK_ROOT}/
CMD ["app.handler"]

SAM Template Configuration

MyFunction:
  Type: AWS::Serverless::Function
  Properties:
    PackageType: Image
    Architectures: [arm64]
    MemorySize: 512
    Timeout: 30
  Metadata:
    Dockerfile: Dockerfile
    DockerContext: ./src
    DockerTag: latest

SAM builds the image locally during sam build and pushes it to ECR during sam deploy. No manual docker push needed.

Seekable OCI (SOCI) Lazy Loading

Container images have longer cold starts than zip because Lambda must download the full image before starting. SOCI creates an index that enables lazy loading — Lambda pulls only the layers needed at startup and fetches the rest in the background. SOCI is most beneficial for images larger than 250 MB. For smaller images, the overhead of maintaining the index may not be worthwhile.

Best Practices

• [ ] Use multi-stage builds to minimize final image size — install build dependencies in a builder stage, copy only artifacts to the final stage

• [ ] Use AWS base images (public.ecr.aws/lambda/*) — they include the Lambda runtime interface client

• [ ] Choose arm64 architecture for the same 20% cost savings as zip deployments

• [ ] Pin base image tags to specific versions in production (e.g., python:3.12.2024.11.22 not python:3.12)

• [ ] Create SOCI indexes for images larger than 250 MB to reduce cold starts

Configuration Management

samconfig.toml

Use environment-specific sections:

[default.deploy.parameters]
stack_name = "my-serverless-app"
region = "us-east-1"
capabilities = "CAPABILITY_IAM"

[dev.deploy.parameters]
stack_name = "my-app-dev"
parameter_overrides = "Environment=dev LogLevel=DEBUG"

[prod.deploy.parameters]
stack_name = "my-app-prod"
parameter_overrides = "Environment=prod LogLevel=WARN"

Deploy to a specific environment with sam_deploy using config_env: prod.

Security

• Follow least-privilege IAM: scope each function's role to only the actions and resources it needs

• Use AWSLambdaBasicExecutionRole managed policy for CloudWatch logging

• Add VPC configuration only when the function needs access to VPC resources (RDS, ElastiCache)

• Store secrets in Secrets Manager or SSM Parameter Store

Testing

Serverless Testing Pyramid

Invest most effort in unit tests. Use local integration to catch event shape mismatches. Reserve cloud tests for verifying IAM, networking, and service integration behavior.

Unit Testing

Mock all AWS SDK calls. Use the Arrange-Act-Assert pattern.

Python (pytest):

from unittest.mock import MagicMock, patch

def test_get_order_returns_item():
    # Arrange
    mock_table = MagicMock()
    mock_table.get_item.return_value = {"Item": {"orderId": "ord-1", "status": "active"}}

    with patch("src.handlers.orders.table", mock_table):
        from src.handlers.orders import app
        event = {"httpMethod": "GET", "pathParameters": {"orderId": "ord-1"}}
        # Act
        result = app.resolve(event, {})
        # Assert
        assert result["statusCode"] == 200

TypeScript (jest + aws-sdk-client-mock):

import { handler } from '../src/handlers/orders';
import { mockClient } from 'aws-sdk-client-mock';
import { DynamoDBDocumentClient, GetCommand } from '@aws-sdk/lib-dynamodb';

const ddbMock = mockClient(DynamoDBDocumentClient);

afterEach(() => ddbMock.reset());

it('should return order when it exists', async () => {
  // Arrange
  ddbMock.on(GetCommand).resolves({ Item: { orderId: 'ord-1', status: 'active' } });
  const event = { httpMethod: 'GET', pathParameters: { orderId: 'ord-1' } } as any;
  // Act
  const result = await handler(event, {} as any);
  // Assert
  expect(result.statusCode).toBe(200);
});

Local Integration Testing

# Generate a test event template
sam local generate-event s3 put --bucket my-bucket --key uploads/test.jpg > events/s3_put.json

# Invoke locally with the generated event
sam local invoke MyFunction --event events/s3_put.json

# Enable Powertools dev mode for verbose local output
sam local invoke MyFunction --event events/test.json \
  --env-vars <(echo '{"MyFunction": {"POWERTOOLS_DEV": "true"}}')

sam local generate-event supports all Lambda event sources (s3, sqs, sns, kinesis, dynamodb, apigateway, etc.). Use it instead of hand-crafting event JSON.

The sam local start-api subcommand runs your AWS Lambda functions locally to test through a local HTTP server host. This lets you test your APIs with real HTTP requests using curl, Postman, or your browser:

# Start local API server (default port 3000)
sam local start-api

# Test with curl
curl http://localhost:3000/hello

# Use custom port
sam local start-api --port 8080

Cloud Integration Testing

Local testing cannot fully replicate IAM policies, VPC networking, or service integrations. Use cloud-based testing for these.

# Test a deployed function directly
sam remote invoke MyFunction --stack-name my-app-dev --event-file events/test.json

# Deploy an ephemeral stack for PR testing
sam deploy --config-env ci \
  --parameter-overrides "Environment=pr-${PR_NUMBER}" \
  --stack-name "my-app-pr-${PR_NUMBER}"

# Tear down after tests pass
aws cloudformation delete-stack --stack-name "my-app-pr-${PR_NUMBER}"

Ephemeral stacks (one per PR) provide full isolation between test runs without polluting shared environments.

Testing Checklist

• [ ] Mock all AWS SDK calls in unit tests — never call real AWS services

• [ ] Keep test events in events/ for repeatability

• [ ] Use sam local generate-event rather than hand-crafting event JSON

• [ ] Set POWERTOOLS_DEV=true locally for verbose structured log output

• [ ] Run unit tests in CI on every commit; cloud integration tests on PR merge

• [ ] Use ephemeral stacks for integration testing to avoid environment conflicts