Aws Serverless Deployment

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

## 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](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)