Aws Serverless Deployment

AWS Serverless Deployment

Deploy serverless applications to AWS using SAM or CDK. This skill covers project scaffolding, IaC templates, CDK constructs and patterns, deployment workflows, CI/CD pipelines, and SAM/CDK coexistence.

For Lambda runtime behavior, event sources, orchestration, observability, and optimization, see the aws-lambda skill.

When to Load Reference Files

Load the appropriate reference file based on what the user is working on:

• SAM project setup, templates, deployment workflow, local testing, or container images -> see references/sam-project-setup.md
• CDK project setup, constructs, CDK testing, or CDK pipelines -> see references/cdk-project-setup.md
• CDK Lambda constructs, NodejsFunction, PythonFunction, or CDK Function -> see references/cdk-lambda-constructs.md
• CDK serverless patterns, API Gateway CDK, Function URL CDK, EventBridge CDK, DynamoDB CDK, or SQS CDK -> see references/cdk-serverless-patterns.md
• SAM and CDK coexistence, migrating from SAM to CDK, or using sam build with CDK -> see references/sam-cdk-coexistence.md

Best Practices

SAM

• Do: Use sam_init with an appropriate template for your use case
• Do: Set global defaults for timeout, memory, runtime, and tracing in the Globals section
• Do: Use samconfig.toml environment-specific sections for multi-environment deployments
• Do: Use sam build --use-container when native dependencies are involved
• Don't: Copy-paste templates from the internet without understanding the resource configuration
• Don't: Hardcode resource ARNs or account IDs in templates — use !Ref, !GetAtt, and !Sub

CDK

• Do: Use TypeScript — type checking catches errors at synthesis time, before any AWS API calls
• Do: Prefer L2 constructs and grant* methods over L1 and raw IAM statements
• Do: Separate stateful and stateless resources into different stacks; enable termination protection on stateful stacks
• Do: Commit cdk.context.json to version control — it caches VPC/AZ lookups for deterministic synthesis
• Do: Write unit tests with aws-cdk-lib/assertions; assert logical IDs of stateful resources to detect accidental replacements
• Do: Use cdk diff in CI before every deployment to review changes
• Don't: Hardcode account IDs or region strings — use this.account and this.region
• Don't: Use cdk deploy directly in production without a pipeline
• Don't: Skip cdk bootstrap — deployments will fail without the CDK toolkit stack

Configuration

AWS CLI Setup

This skill requires that AWS credentials are configured on the host machine:

Verify access: Run aws sts get-caller-identity to confirm credentials are valid

SAM CLI Setup

Verify: Run sam --version

Container Runtime Setup

1. Install a Docker compatible container runtime: Required for sam_local_invoke and container-based builds 2. Verify: Use an appropriate command such as docker --version or finch --version

AWS Serverless MCP Server

Write access is enabled by default. The plugin ships with --allow-write in .mcp.json, so the MCP server can create projects, generate IaC, and deploy on behalf of the user.

Access to sensitive data (like Lambda and API Gateway logs) is not enabled by default. To grant it, add --allow-sensitive-data-access to .mcp.json.

SAM Template Validation Hook

This plugin includes a PostToolUse hook that runs sam validate automatically after any edit to template.yaml or template.yml. If validation fails, the error is returned as a system message so you can fix it immediately. The hook requires SAM CLI and jq to be installed; if either is missing, validation is skipped with a system message. Users can disable it via /hooks.

Verify: Run jq --version

IaC framework selection

Default: CDK

Override syntax:

• "use CloudFormation" → Generate YAML templates
• "use SAM" → Generate YAML templates

When not specified, ALWAYS use CDK

Language selection for CDK

Default: TypeScript

Override syntax:

• "use Python" → Generate Python code
• "use JavaScript" → Generate JavaScript code

When not specified, ALWAYS use TypeScript

Error Scenarios

Serverless MCP Server Unavailable

• Inform user: "AWS Serverless MCP not responding"
• Ask: "Proceed without MCP support?"
• DO NOT continue without user confirmation

Resources

• AWS SAM Documentation
• AWS CDK Documentation
• AWS Serverless MCP Server

CDK Lambda Function Constructs

CDK provides specialized constructs for defining Lambda functions. Always prefer the runtime-specific L2 constructs (NodejsFunction, PythonFunction) over the base Function when available — they handle bundling automatically.

Node.js — NodejsFunction

The NodejsFunction construct bundles TypeScript/JavaScript with esbuild automatically. No separate build step needed.

import * as cdk from 'aws-cdk-lib';
import { NodejsFunction } from 'aws-cdk-lib/aws-lambda-nodejs';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import { Duration } from 'aws-cdk-lib';

export class MyStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const orderHandler = new NodejsFunction(this, 'OrderHandler', {
      entry: 'lambda/order-handler.ts',   // path to TypeScript entry file
      handler: 'handler',                 // exported function name
      runtime: lambda.Runtime.NODEJS_24_X,
      architecture: lambda.Architecture.ARM_64,  // ~20% cheaper than x86_64
      memorySize: 512,
      timeout: Duration.seconds(30),
      tracing: lambda.Tracing.ACTIVE,
      environment: {
        TABLE_NAME: myTable.tableName,    // reference, not hardcoded string
      },
      bundling: {
        minify: true,
        sourceMap: true,
        externalModules: ['@aws-sdk/*'],  // exclude AWS SDK (provided by runtime)
      },
    });
  }
}

Entry auto-detection: If entry is omitted, CDK looks for {stack-filename}.{construct-id}.ts next to the stack file.

Handler resolution: "handler" (no dot) resolves to "index.handler".

Python — PythonFunction (Alpha)

PythonFunction is in a separate alpha package and requires Docker for bundling.

npm install @aws-cdk/aws-lambda-python-alpha

import { PythonFunction } from '@aws-cdk/aws-lambda-python-alpha';
import * as lambda from 'aws-cdk-lib/aws-lambda';

const orderHandler = new PythonFunction(this, 'OrderHandler', {
  entry: 'lambda/order-handler',   // directory containing index.py
  index: 'index.py',               // default
  handler: 'handler',              // default
  runtime: lambda.Runtime.PYTHON_3_14,
  architecture: lambda.Architecture.ARM_64,
  memorySize: 512,
  timeout: Duration.seconds(30),
  tracing: lambda.Tracing.ACTIVE,
  environment: {
    TABLE_NAME: myTable.tableName,
  },
});

The entry directory should contain a requirements.txt, Pipfile, or pyproject.toml. Docker must be running during cdk synth and cdk deploy.

Alpha warning: @aws-cdk/aws-lambda-python-alpha can introduce breaking changes without a major version bump. Pin the exact version and test after upgrades.

Other Runtimes — Base Function

For Java, Go, .NET, or custom runtimes, use the base Function construct with Code.fromAsset():

import * as lambda from 'aws-cdk-lib/aws-lambda';

const orderHandler = new lambda.Function(this, 'OrderHandler', {
  code: lambda.Code.fromAsset('build/distributions/order-handler.zip'),
  handler: 'com.example.OrderHandler::handleRequest',
  runtime: lambda.Runtime.JAVA_21,
  architecture: lambda.Architecture.ARM_64,
  memorySize: 1024,
  timeout: Duration.seconds(60),
  snapStart: lambda.SnapStartConf.ON_PUBLISHED_VERSIONS,  // Java 11+
  tracing: lambda.Tracing.ACTIVE,
});

CDK Project Setup Guide

SAM vs CDK: When to Use Each

Both SAM and CDK synthesize CloudFormation. Choosing between them is a matter of team preference and project context.

Choose SAM when your primary concern is Lambda functions and you want the SAM MCP tools.

Choose CDK when you have complex infrastructure, want to write reusable construct libraries, prefer a programming-language interface, or your team already uses CDK elsewhere.

Both tools support the get_iac_guidance MCP tool for additional context:

get_iac_guidance(iac_tool: "cdk")

---

Getting Started

Install and Bootstrap

npm install -g aws-cdk
cdk --version

# One-time account/region bootstrap (creates CDK toolkit stack)
cdk bootstrap aws://ACCOUNT-ID/REGION

Initialize a New Project

mkdir my-serverless-app && cd my-serverless-app
cdk init app --language typescript
npm install

Project Structure

my-serverless-app/
├── bin/
│   └── my-serverless-app.ts    # App entry point
├── lib/
│   └── my-serverless-app-stack.ts  # Stack definition
├── lambda/
│   └── handler.ts              # Lambda function code
├── test/
│   └── my-serverless-app.test.ts
├── cdk.context.json            # Committed to git — caches lookups
├── cdk.json                    # CDK config
└── tsconfig.json

---

Construct Levels

CDK has three levels of constructs:

Always prefer L2 constructs. Use L1 only when a feature is missing from the L2. Use L3 patterns as a starting point, but understand what they create.

---

Lambda Functions

For CDK Lambda function constructs — NodejsFunction (TypeScript/JavaScript with esbuild), PythonFunction (alpha, Docker-based), and base Function (Java, Go, .NET) — see cdk-lambda-constructs.md.

---

IAM with grant* Methods

CDK L2 constructs expose grant* methods that generate least-privilege policies automatically. Prefer these over writing raw PolicyStatement objects.

import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as sqs from 'aws-cdk-lib/aws-sqs';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as events from 'aws-cdk-lib/aws-events';

// DynamoDB
table.grantReadWriteData(myFunction);
table.grantReadData(readOnlyFunction);

// S3
bucket.grantRead(myFunction);
bucket.grantPut(myFunction);

// SQS
queue.grantSendMessages(myFunction);
queue.grantConsumeMessages(myFunction);

// EventBridge — put events
eventBus.grantPutEventsTo(myFunction);

// Lambda — invoke another function
otherFunction.grantInvoke(myFunction);

// Secrets Manager
secret.grantRead(myFunction);

For resources not covered by grant*, add a PolicyStatement directly:

import * as iam from 'aws-cdk-lib/aws-iam';

myFunction.addToRolePolicy(new iam.PolicyStatement({
  effect: iam.Effect.ALLOW,
  actions: ['bedrock:InvokeModel'],
  resources: [`arn:aws:bedrock:${this.region}::foundation-model/anthropic.claude-3-sonnet*`],
}));

---

Common Serverless Patterns

For CDK code examples of common serverless patterns — API Gateway HTTP API, Lambda Function URL, EventBridge custom bus, DynamoDB table, and SQS queue with Lambda — see cdk-serverless-patterns.md.

---

Separating Stateful and Stateless Stacks

Stateful resources (databases, queues, S3 buckets, event buses) should be in a separate stack with termination protection. This prevents accidental deletion during routine deployments.

// bin/my-app.ts
const app = new cdk.App();

// Stateful stack — deployed once, termination-protected
const stateful = new StatefulStack(app, 'StatefulStack', {
  env: { account: '123456789012', region: 'us-east-1' },
  terminationProtection: true,
});

// Stateless stack — deployed on every code change
const stateless = new StatelessStack(app, 'StatelessStack', {
  env: { account: '123456789012', region: 'us-east-1' },
  // Pass references from stateful stack
  ordersTable: stateful.ordersTable,
  orderEventBus: stateful.orderEventBus,
});

// lib/stateful-stack.ts
export class StatefulStack extends cdk.Stack {
  public readonly ordersTable: dynamodb.Table;
  public readonly orderEventBus: events.EventBus;

  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    this.ordersTable = new dynamodb.Table(this, 'OrdersTable', {
      // ...
      removalPolicy: cdk.RemovalPolicy.RETAIN,
    });

    this.orderEventBus = new events.EventBus(this, 'OrderEventBus', {
      eventBusName: 'order-events',
    });
  }
}

---

CDK Testing

CDK constructs can be unit tested without deploying. Use aws-cdk-lib/assertions with Jest.

npm install --save-dev jest @types/jest ts-jest

// test/order-stack.test.ts
import * as cdk from 'aws-cdk-lib';
import { Template, Match } from 'aws-cdk-lib/assertions';
import { OrderStack } from '../lib/order-stack';

describe('OrderStack', () => {
  let template: Template;

  beforeEach(() => {
    const app = new cdk.App();
    const stack = new OrderStack(app, 'TestOrderStack');
    template = Template.fromStack(stack);
  });

  it('creates Lambda function with ARM64 architecture', () => {
    template.hasResourceProperties('AWS::Lambda::Function', {
      Architectures: ['arm64'],
      Runtime: 'nodejs22.x',
    });
  });

  it('grants DynamoDB read-write to order handler', () => {
    template.hasResourceProperties('AWS::IAM::Policy', {
      PolicyDocument: {
        Statement: Match.arrayWith([
          Match.objectLike({
            Action: Match.arrayWith([
              'dynamodb:GetItem',
              'dynamodb:PutItem',
            ]),
          }),
        ]),
      },
    });
  });

  it('has exactly one DynamoDB table', () => {
    template.resourceCountIs('AWS::DynamoDB::Table', 1);
  });

  it('DynamoDB table has retention policy', () => {
    template.hasResource('AWS::DynamoDB::Table', {
      DeletionPolicy: 'Retain',
    });
  });
});

Assert logical IDs of stateful resources to catch accidental replacements early — renaming a CDK construct ID causes CloudFormation to delete and recreate the resource:

it('orders table logical ID is stable', () => {
  const resources = template.findResources('AWS::DynamoDB::Table');
  expect(Object.keys(resources)).toContain('OrdersTable1234ABCD');  // update if intentionally renamed
});

---

Deployment Workflow

# Synthesize CloudFormation template (runs assertions, no AWS calls)
cdk synth

# Preview changes before deploying
cdk diff

# Deploy all stacks
cdk deploy --all

# Deploy a specific stack
cdk deploy StatelessStack

# Deploy with approval prompt disabled (CI/CD)
cdk deploy --require-approval never

# Destroy a stack (respects RemovalPolicy — RETAIN resources are kept)
cdk destroy StatelessStack

---

CDK Pipelines (CI/CD)

CDK Pipelines is a self-mutating CI/CD pipeline construct built on CodePipeline.

import { CodePipeline, CodePipelineSource, ManualApprovalStep, ShellStep } from 'aws-cdk-lib/pipelines';

export class PipelineStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const pipeline = new CodePipeline(this, 'Pipeline', {
      pipelineName: 'MyServerlessPipeline',
      synth: new ShellStep('Synth', {
        input: CodePipelineSource.gitHub('my-org/my-repo', 'main'),
        commands: ['npm ci', 'npm run build', 'npx cdk synth'],
      }),
    });

    // Staging stage
    pipeline.addStage(new MyAppStage(this, 'Staging', {
      env: { account: '111111111111', region: 'us-east-1' },
    }));

    // Production stage with manual approval
    pipeline.addStage(new MyAppStage(this, 'Production', {
      env: { account: '222222222222', region: 'us-east-1' },
    }), {
      pre: [new ManualApprovalStep('PromoteToProduction')],
    });
  }
}

The pipeline updates itself: when you push changes to the pipeline stack, the next run applies them before deploying the application.

---

SAM and CDK Coexistence

For guidance on running SAM and CDK side by side — incremental migration, using sam build on CDK-synthesized templates, and when to use which — see sam-cdk-coexistence.md.

---

Best Practices

Do

• Use TypeScript — type checking catches errors at synthesis time, before any AWS API calls
• Prefer L2 constructs and grant* methods over L1 and raw IAM statements
• Never hardcode resource names — always reference generated names (table.tableName, queue.queueUrl)
• Separate stateful and stateless resources into different stacks; enable termination protection on stateful stacks
• Commit cdk.context.json to version control — it caches VPC/AZ lookups for deterministic synthesis
• Write unit tests with aws-cdk-lib/assertions; assert logical IDs of stateful resources to detect accidental replacements
• Set RemovalPolicy.RETAIN on all databases, S3 buckets, and event buses
• Use cdk diff in CI before every deployment to review changes
• Pass all configuration to constructs via props; never read environment variables inside construct constructors

Don't

• Hardcode account IDs or region strings — use this.account and this.region
• Use cdk deploy directly in production without a pipeline
• Skip cdk bootstrap — deployments will fail without the CDK toolkit stack
• Rely on CloudFormation Parameters and Conditions when you can express the same logic in TypeScript
• Mix RemovalPolicy.DESTROY into shared/stateful stacks
• Reference constructs across separate CDK apps using CloudFormation outputs if you can pass object references directly

CDK Serverless Patterns

Common CDK patterns for serverless applications. Each example uses L2 constructs with grant* methods for least-privilege IAM.

API Gateway HTTP API + Lambda

Creates an HTTP API with CORS configuration and Lambda integration for handling REST endpoints.

import * as apigwv2 from 'aws-cdk-lib/aws-apigatewayv2';
import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';

const api = new apigwv2.HttpApi(this, 'OrderApi', {
  corsPreflight: {
    allowOrigins: ['https://myapp.example.com'],
    allowMethods: [apigwv2.CorsHttpMethod.GET, apigwv2.CorsHttpMethod.POST],
    allowHeaders: ['Content-Type', 'Authorization'],
  },
});

api.addRoutes({
  path: '/orders',
  methods: [apigwv2.HttpMethod.POST],
  integration: new HttpLambdaIntegration('CreateOrder', createOrderFunction),
});

new cdk.CfnOutput(this, 'ApiUrl', { value: api.apiEndpoint });

Lambda Function URL

Exposes a Lambda function directly via HTTPS with optional IAM auth and streaming support.

const fnUrl = myFunction.addFunctionUrl({
  authType: lambda.FunctionUrlAuthType.NONE,   // or AWS_IAM
  invokeMode: lambda.InvokeMode.RESPONSE_STREAM,  // for streaming
  cors: {
    allowedOrigins: ['https://myapp.example.com'],
    allowedMethods: [lambda.HttpMethod.POST],
  },
});

new cdk.CfnOutput(this, 'FunctionUrl', { value: fnUrl.url });

EventBridge Custom Bus + Rule

Sets up a custom event bus with archiving, routing rules, and DLQ for event-driven architectures.

import * as events from 'aws-cdk-lib/aws-events';
import * as targets from 'aws-cdk-lib/aws-events-targets';
import * as sqs from 'aws-cdk-lib/aws-sqs';

const orderEventBus = new events.EventBus(this, 'OrderEventBus', {
  eventBusName: 'order-events',
});

// Archive all events for replay
new events.Archive(this, 'OrderEventArchive', {
  sourceEventBus: orderEventBus,
  archiveName: 'order-events-archive',
  retention: cdk.Duration.days(30),
  eventPattern: { source: ['com.mycompany.orders'] },
});

// DLQ for the rule target
const processDlq = new sqs.Queue(this, 'ProcessOrderDLQ', {
  retentionPeriod: cdk.Duration.days(14),
});

// Rule routing to Lambda
new events.Rule(this, 'OrderPlacedRule', {
  eventBus: orderEventBus,
  eventPattern: {
    source: ['com.mycompany.orders'],
    detailType: ['OrderPlaced'],
  },
  targets: [
    new targets.LambdaFunction(processOrderFunction, {
      retryAttempts: 3,
      maxEventAge: cdk.Duration.hours(1),
      deadLetterQueue: processDlq,
    }),
  ],
});

// Allow publisher to send events to the bus
orderEventBus.grantPutEventsTo(publisherFunction);

DynamoDB Table + Lambda

Provisions a DynamoDB table with GSI, point-in-time recovery, and least-privilege Lambda access.

import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';

const ordersTable = new dynamodb.Table(this, 'OrdersTable', {
  partitionKey: { name: 'orderId', type: dynamodb.AttributeType.STRING },
  sortKey: { name: 'createdAt', type: dynamodb.AttributeType.STRING },
  billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
  removalPolicy: cdk.RemovalPolicy.RETAIN,   // never delete in production
  pointInTimeRecoverySpecification: {
    pointInTimeRecoveryEnabled: true,
  },
});

ordersTable.addGlobalSecondaryIndex({
  indexName: 'ByUserId',
  partitionKey: { name: 'userId', type: dynamodb.AttributeType.STRING },
  sortKey: { name: 'createdAt', type: dynamodb.AttributeType.STRING },
});

// Least-privilege: read-write for the handler
ordersTable.grantReadWriteData(orderHandler);

// Pass table name via environment (never hardcode)
orderHandler.addEnvironment('TABLE_NAME', ordersTable.tableName);

SQS Queue + Lambda ESM

Configures an SQS queue with DLQ and Lambda event source mapping for asynchronous processing.

import * as sqs from 'aws-cdk-lib/aws-sqs';
import { SqsEventSource } from 'aws-cdk-lib/aws-lambda-event-sources';

const orderQueue = new sqs.Queue(this, 'OrderQueue', {
  visibilityTimeout: cdk.Duration.seconds(90),  // >= function timeout
});

const dlq = new sqs.Queue(this, 'OrderDLQ', {
  retentionPeriod: cdk.Duration.days(14),
});

orderQueue.addDeadLetterQueue({
  queue: dlq,
  maxReceiveCount: 3,
});

orderHandler.addEventSource(new SqsEventSource(orderQueue, {
  batchSize: 10,
  reportBatchItemFailures: true,  // partial batch success
  filters: [
    lambda.FilterCriteria.filter({
      body: { eventType: lambda.FilterRule.isEqual('ORDER_CREATED') },
    }),
  ],
}));

SAM and CDK Coexistence

Most teams don't switch from SAM to CDK all at once. Both tools produce CloudFormation templates, so they can coexist in the same project, the same account, and even the same CI/CD pipeline. SAM CLI works with any CloudFormation template, whether it uses the SAM transform or is synthesized by CDK.

Incremental Migration

The lowest-risk approach is to add CDK alongside SAM rather than replacing it:

1. Start with one new stack in CDK — a supporting resource (DynamoDB table, SQS queue, event bus) that your SAM functions reference via SSM parameters or CloudFormation exports 2. Keep existing SAM stacks untouched — they continue to deploy via sam build && sam deploy 3. Migrate function stacks gradually — move functions to CDK one stack at a time as you gain confidence

Cross-stack references between SAM and CDK stacks work the same way as any CloudFormation cross-stack reference: export a value from one stack, import it in the other via Fn::ImportValue (SAM) or cdk.Fn.importValue() (CDK). Alternatively, write values to SSM Parameter Store and read them from either side.

Using SAM CLI with CDK Templates

SAM CLI can build and locally test functions defined in any CloudFormation template, including one synthesized by CDK:

# Synthesize the CDK app to cdk.out/
cdk synth

# Use SAM CLI to build the synthesized template
sam build --template cdk.out/MyStack.template.json

# Test a function locally
sam local invoke MyFunction --template cdk.out/MyStack.template.json

This gives you CDK's construct model for infrastructure while using SAM CLI's sam local invoke for local testing.

When to Use Which

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