aws-cdk

intent

use this skill to build AWS infrastructure in TypeScript with reusable constructs, safe defaults, and a validation-first delivery loop. pick this when creating or refactoring a CDK app, stack, or custom construct; choosing between L1, L2, and L3 abstractions; building serverless, networking, or security-focused infrastructure; wiring multi-stack applications with environment awareness; or validating infrastructure changes before deployment.

inputs

AWS credentials and environment

• AWS_REGION: target region for deployment (e.g., us-east-1, eu-west-1)
• CDK_DEFAULT_ACCOUNT: AWS account ID (retrieved from credentials if not set)
• CDK_DEFAULT_REGION: fallback region if not specified in stack props
• AWS CLI configured with valid credentials

project setup

• Node.js 18+ and npm/yarn installed
• TypeScript 4.7+
• AWS CDK CLI installed globally (npm install -g aws-cdk) or as a dev dependency
• cdk.json file (auto-generated during init)

CDK bootstrap (one-time per account/region)

• run cdk bootstrap aws://<account>/<region> before first deploy to each environment
• bootstrap creates S3 bucket and IAM roles for asset uploads

context values and parameters

• hardcoded context in cdk.json or passed via cdk deploy -c key=value
• environment variables for secrets (never commit API keys or passwords)
• CloudFormation parameters for runtime-configurable values

external integrations (optional)

• Secrets Manager for credentials and certificates
• S3 buckets for asset storage (Lambda code, Docker images)
• ECR repositories if using container-based Lambda functions
• VPC/subnets if deploying compute resources into existing networks

procedure

step 1: initialize a new CDK app

• run npx cdk init app --language typescript to scaffold a new project
• output: my-cdk-app/ directory with bin/, lib/, test/, cdk.json, tsconfig.json, package.json
• note: use the same command to generate inside an existing repo; don't use npx cdk init in an already-initialized directory

step 2: define your stack(s) in lib/

• input: desired AWS resources (S3, Lambda, DynamoDB, etc.) and their configuration
• create a class extending Stack that describes resources using L2 or L3 constructs
• export critical values (ARNs, names, endpoints) as public properties for cross-stack wiring
• set removalPolicy: RemovalPolicy.RETAIN for stateful resources in production
• set removalPolicy: RemovalPolicy.DESTROY only for temporary/dev environments
• output: stack class ready to instantiate in bin/

step 3: instantiate stacks in bin/ entry point

• input: stack class(es), environment config (account, region, tags), termination protection flag
• create an App instance and instantiate one or more stacks with environment-specific properties
• pass env: { account: '<account>', region: '<region>' } to avoid implicit defaults
• call app.synth() at the end to generate CloudFormation
• output: initialized App with all stacks registered

step 4: write infrastructure assertions in test/

• input: stack instance and critical resource requirements (billing mode, encryption, IAM scope, output names)
• use Template.fromStack() to extract the synthesized CloudFormation
• assert resource counts, properties, and IAM permissions with template.hasResourceProperties(), template.resourceCountIs(), template.fromJSON() helpers
• cover stateful resources, security settings, and critical outputs
• output: test suite that validates stack structure before deployment

step 5: run cdk synth to generate CloudFormation

• input: stack definitions from lib/ and entry point from bin/
• command: npx cdk synth (outputs cdk.out/ directory with CloudFormation templates)
• checkpoint: ensure no import errors, invalid props, missing context, or unresolved references
• if synthesis fails, fix the construct config or add missing context values, then retry
• output: cdk.out/<stack-name>.json CloudFormation template ready for review

step 6: run cdk diff to preview changes

• input: synthesized template and current deployed stack (if it exists)
• command: npx cdk diff [stack-id] to compare proposed vs deployed infrastructure
• checkpoint: review IAM permission additions, resource replacements, export changes, and deletes on stateful resources
• if the diff includes unintended IAM broadening or data loss, adjust RemovalPolicy, resource names, or dependencies, then rerun cdk diff
• output: human-readable diff showing additions (green +), modifications (~), and deletions (red -)

step 7: run infrastructure tests

• input: test files in test/ directory
• command: npm test (typically runs Jest or Vitest configured in package.json)
• checkpoint: all assertions pass; critical resources and IAM scopes verified
• if a test fails, update the stack definition or test expectation, then retry
• output: test report confirming stack structure matches requirements

step 8: run cdk deploy to apply changes

• input: synthesized template and AWS credentials with CloudFormation, IAM, and service-specific permissions
• command: npx cdk deploy [stack-id] to deploy a single stack, or npx cdk deploy --all for all stacks
• checkpoint: CloudFormation stack reaches CREATE_COMPLETE or UPDATE_COMPLETE in the AWS console
• if deploy fails, inspect CloudFormation events tab for quota exceeded, permission errors, export conflicts, or bootstrap issues; fix and retry
• output: deployed AWS resources with stack outputs visible in CloudFormation console or CLI

step 9: verify runtime outcomes

• input: deployed stack outputs, endpoints, alarms, and application logic
• confirm Lambda functions respond, DynamoDB tables accept writes, S3 buckets are accessible, API endpoints return 200
• check CloudWatch alarms and logs for any errors or unexpected behavior
• output: validated infrastructure ready for traffic or handoff to ops/testing team

decision points

if using L1 (Cfn) vs L2 vs L3 constructs:*

• use L2 for standard resource provisioning (recommended default). L2 provides sensible defaults, type safety, and grant helper methods like .grantRead() and .grantWrite().
• drop to L1 (Cfn*) only if you need CloudFormation properties not exposed by the L2 API.
• use L3 patterns (like LambdaRestApi) for multi-resource architectures that recur across stacks.

if synthesis fails:

• missing import: ensure the library is imported at the top of the file (e.g., import * as s3 from 'aws-cdk-lib/aws-s3').
• invalid props: check the construct's TypeScript interface in IDE autocomplete or docs; remove unsupported keys.
• missing context: add context values to cdk.json under the context key, or pass via cdk synth -c key=value.
• unresolved reference: confirm all dependent stacks are instantiated before the referencing stack accesses their properties.

if cdk diff shows risky changes (IAM expansion, resource replacement, or deletes on stateful data):

• for IAM expansion: audit the construct's grant helpers to confirm they match the principle of least privilege. if correct, proceed; if overly broad, file an issue or use Cfn* to tighten scope.
• for resource replacement: check if you renamed the logical ID, changed immutable properties (like bucketName), or altered the construct instance ID. revert the change or accept replacement if safe.
• for deletes on stateful resources: ensure removalPolicy is set to RETAIN or SNAPSHOT in production. adjust and rerun cdk diff.

if cdk deploy fails:

• CloudFormation quota exceeded (e.g., max 500 resources per stack): split the app into multiple stacks and wire them with cross-stack references.
• permission denied: confirm the AWS credentials have cloudformation:*, iam:*, s3:*, and service-specific permissions (e.g., lambda:*, rds:*).
• export already exists: if a stack export (CfnOutput) name conflicts with a deployed stack, rename the export or destroy the conflicting stack first.
• bootstrap not found: run cdk bootstrap aws://<account>/<region> once per environment before first deploy.
• asset upload timeout: check S3 bucket and network connectivity; retry cdk deploy.

if cross-stack references are used:

• prefer passing constructs directly (as in step 6 of procedure) over CloudFormation exports for tightly coupled stacks in the same app.
• use exports only if stacks are deployed independently or managed by different teams.
• when removing a stack with exports, dependent stacks must be destroyed or updated first (CloudFormation enforces this order).

if no environment is specified in stack props:

• CDK defaults to CDK_DEFAULT_ACCOUNT and CDK_DEFAULT_REGION env vars. if not set, synthesis may fail or deploy to an unintended account.
• always pass explicit env: { account, region } to avoid surprises, especially for production stacks.

output contract

synthesis output (cdk synth)

• location: cdk.out/ directory (committed to .gitignore by default)
• file format: <stack-name>.json (CloudFormation template in JSON)
• schema: valid AWS CloudFormation template with Resources, Outputs, Parameters, Metadata
• artifact files: cdk.out/assets/ contains Docker image digests and Lambda layer asset hashes

deployment output (cdk deploy)

• location: AWS CloudFormation console, stack details page
• stack status: CREATE_COMPLETE (new stack) or UPDATE_COMPLETE (updated stack)
• stack outputs: values exported as CfnOutput objects visible in CloudFormation outputs tab and available via aws cloudformation describe-stacks
• resources created: all constructs mapped to AWS resource types with logical and physical IDs

test output (npm test)

• format: Jest/Vitest report with pass/fail counts
• assertions verified: resource types, properties, IAM permissions, output names, resource counts
• exit code: 0 (all pass), non-zero (any fail)

outcome signal

successful skill execution is confirmed by:

1. synthesis succeeds with no errors: cdk synth outputs cdk.out/<stack-name>.json without missing imports, invalid props, or missing context
2. diff preview is reviewed and approved: cdk diff shows intended additions, modifications, and no unintended IAM expansions or data loss on stateful resources
3. infrastructure tests pass: npm test confirms all assertions on critical resources, IAM scope, and outputs
4. deployment completes: cdk deploy reaches CREATE_COMPLETE or UPDATE_COMPLETE in CloudFormation console within expected time
5. runtime verification confirms functionality: deployed Lambda functions respond, database tables accept writes, S3 buckets are readable/writable, API endpoints return expected responses, and alarms have valid baselines
6. stack outputs are available: aws cloudformation describe-stacks --stack-name <name> returns Outputs with expected values (ARNs, endpoints, bucket names, etc.)
7. no post-deployment errors in CloudWatch: Lambda logs, RDS events, and API Gateway access logs show normal operation with no 5xx errors, connection timeouts, or permission denied messages