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

Common Deployment Pitfalls

• Cross-account / public Lambda layers need lambda:GetLayerVersion for the deploying identity. Referencing a foreign-account layer ARN (e.g. the AWS-published Powertools layer) fails at deploy time with AccessDeniedException ... lambda:GetLayerVersion if the CI/sandbox role lacks that permission. Fallback for locked-down environments: vendor the dependencies into the package (bundle at build time) and drop the layer reference — the artifact becomes self-contained. Don't vendor boto3/botocore (already in the runtime). Resolve any bundled non-code assets (schemas, config) via a runtime-known path (env var / __file__), not a build-time relative path.
• When you vendor deps, the package build must run before terraform apply / cdk deploy. Terraform's archive_file and CDK asset bundling zip a directory as-is — if a separate build step stages deps + source into that directory, run it first, and re-run on code changes so the artifact hash updates and the function is actually redeployed.
• Run a live smoke test after deploy — not just unit tests. Unit tests with fakes/mocks (moto, stubbed model clients) cannot catch provider-side request-validation errors, IAM-at-invoke failures, or environment/timing issues. Budget a minimal post-deploy invocation (one real request through the deployed path) in the Definition of Done. Example only visible live: a model/inference API rejecting a parameter combination the fake accepted (see next).
• Bedrock Converse inferenceConfig — newer models reject temperature and topP together. Some newer Anthropic Claude models (Sonnet 4.5+) return ValidationException: 'temperature' and 'top_p' cannot both be specified for this model. Please use only one. Send only ONE of temperature/topP. A mocked model client won't surface this — the live smoke test will.

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