aws-serverless-deployment

Original source / Raw SKILL.md

---
name: aws-serverless-deployment
description: "AWS SAM and AWS CDK deployment for serverless applications. Triggers on phrases like: use SAM, SAM template, SAM init, SAM deploy, CDK serverless, CDK Lambda construct, NodejsFunction, PythonFunction, SAM and CDK together, serverless CI/CD pipeline. For general app deployment with service selection, use deploy-on-aws plugin instead."
argument-hint: "[what are you deploying?]"
---

# 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](../aws-lambda/).

## 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](references/sam-project-setup.md)
- **CDK project setup**, **constructs**, **CDK testing**, or **CDK pipelines** -> see [references/cdk-project-setup.md](references/cdk-project-setup.md)
- **CDK Lambda constructs**, **NodejsFunction**, **PythonFunction**, or **CDK Function** -> see [references/cdk-lambda-constructs.md](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](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](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](https://docs.aws.amazon.com/serverless-application-model/)
- [AWS CDK Documentation](https://docs.aws.amazon.com/cdk/)
- [AWS Serverless MCP Server](https://github.com/awslabs/mcp/tree/main/src/aws-serverless-mcp-server)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/sam-project-setup.md

```markdown
# SAM Project Setup Guide

## Template Selection

Choose the right template based on your use case:

| Template                     | Best For                                  |
| ---------------------------- | ----------------------------------------- |
| `hello-world`                | Basic Lambda function with API Gateway    |
| `quick-start-web`            | Web application with frontend and backend |
| `quick-start-cloudformation` | Infrastructure-focused templates          |
| `quick-start-scratch`        | Minimal template for custom builds        |

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

```text
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:

```yaml
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:

```yaml
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](#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.

```yaml
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:**

| Type                            | Traffic shift pattern                            |
| ------------------------------- | ------------------------------------------------ |
| `AllAtOnce`                     | Immediate full cutover (no safety, dev/test use) |
| `Canary10Percent5Minutes`       | 10% for 5 min, then 100%                         |
| `Canary10Percent30Minutes`      | 10% for 30 min, then 100%                        |
| `Linear10PercentEvery1Minute`   | +10% every minute                                |
| `Linear10PercentEvery10Minutes` | +10% every 10 min                                |

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:**

```yaml
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

| Criterion                | Zip Package         | Container Image                                 |
| ------------------------ | ------------------- | ----------------------------------------------- |
| Max size                 | 250 MB uncompressed | 10 GB                                           |
| Custom OS dependencies   | Limited (layers)    | Full control via Dockerfile                     |
| Existing Docker workflow | N/A                 | Reuse Dockerfiles and CI pipelines              |
| Cold start               | Faster baseline     | Slower baseline, mitigated by SOCI              |
| Local testing            | `sam local invoke`  | `sam local invoke` (Docker required either way) |

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):**

```dockerfile
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:**

```dockerfile
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

```yaml
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:

```toml
[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

| Level                 | What it tests                 | Speed                  | AWS dependency |
| --------------------- | ----------------------------- | ---------------------- | -------------- |
| **Unit**              | Handler logic, business rules | Fast (ms)              | None (mocked)  |
| **Local integration** | Function + event shape        | Medium (seconds)       | Docker only    |
| **Cloud integration** | Function + real AWS services  | Slow (seconds-minutes) | Full           |
| **End-to-end**        | Complete request path         | Slowest                | Full           |

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):**

```python
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):**

```typescript
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

```bash
# 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:

```bash
# 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.

```bash
# 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

```

### references/cdk-project-setup.md

```markdown
# 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.

|                          | SAM                                     | CDK                                                       |
| ------------------------ | --------------------------------------- | --------------------------------------------------------- |
| **Language**             | YAML/JSON (declarative)                 | TypeScript, Python, Java, Go, C# (imperative)             |
| **Learning curve**       | Lower — close to CloudFormation         | Higher — requires familiarity with a programming language |
| **Abstraction level**    | Handles wiring for Serverless resources | Rich L2/L3 constructs handle wiring automatically         |
| **Code sharing**         | Template fragments only                 | Full reuse via construct libraries (npm, PyPI)            |
| **Loops and conditions** | Limited                                 | Native language constructs (`for`, `if`, maps)            |
| **Testing**              | Manual template review                  | Unit tests with `aws-cdk-lib/assertions`                  |
| **Best for**             | Lambda-centric apps, teams new to IaC   | Large teams building reusable infrastructure patterns     |

**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:

```text
get_iac_guidance(iac_tool: "cdk")
```

---

## Getting Started

### Install and Bootstrap

```bash
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

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

### Project Structure

```text
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:

| Level             | Description                                                   | Example                           |
| ----------------- | ------------------------------------------------------------- | --------------------------------- |
| __L1 (Cfn_)_*     | Direct CloudFormation resource, 1:1 mapping                   | `CfnFunction`, `CfnTable`         |
| **L2**            | Opinionated wrapper with sensible defaults and helper methods | `Function`, `Table`, `Queue`      |
| **L3 (Patterns)** | Complete patterns that wire multiple resources together       | `LambdaRestApi`, `SqsEventSource` |

**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](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.

```typescript
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:

```typescript
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](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.

```typescript
// 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,
});
```

```typescript
// 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.

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

```typescript
// 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:

```typescript
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

```bash
# 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.

```typescript
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](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

```

### references/cdk-lambda-constructs.md

```markdown
# 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.

```typescript
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.

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

```typescript
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()`:

```typescript
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,
});
```

```

### references/cdk-serverless-patterns.md

```markdown
# 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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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') },
    }),
  ],
}));
```

```

### references/sam-cdk-coexistence.md

```markdown
# 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:

```bash
# 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

| Scenario                                                                  | Recommendation                                    |
| ------------------------------------------------------------------------- | ------------------------------------------------- |
| New Lambda-centric project, small team                                    | SAM — simpler templates, straightforward workflow |
| New project with complex infrastructure (VPCs, multiple services)         | CDK — richer abstractions, `grant*` methods       |
| Existing SAM project, works fine                                          | Keep SAM — migration cost isn't justified         |
| Existing SAM project, hitting limits (no loops, hard to share constructs) | Migrate incrementally to CDK                      |
| Reusable infrastructure patterns shared across teams                      | CDK construct libraries                           |
| Need local testing with CDK-defined infrastructure                        | CDK for templates, SAM CLI for `sam local invoke` |

```