aws-cdk

AWS CDK

Overview

Domain expertise for CDK construct authoring, deployment workflows, compliance, drift, importing resources, safe refactoring, and troubleshooting CDK CLI / CloudFormation errors.

When NOT to use: Raw CloudFormation YAML/JSON. SAM. Terraform/Pulumi. CI/CD beyond CDK Pipelines. Use builtin knowledge or specialized skills for these.

Critical Warnings

Deadly embrace: Removing a cross-stack reference deadlocks deployment. Two-deploy fix required: (1) remove consumer import + add this.exportValue() on producer, deploy; (2) remove exportValue(), deploy again. See troubleshooting-deployment.

Construct ID changes cause replacement: Renaming/moving a construct changes its logical ID → CloudFormation replaces the resource (data loss for stateful resources). Always cdk diff before deploy. See refactor-and-prevent-replacement.

UPDATE_ROLLBACK_FAILED: Stack is stuck. Fix with cdk rollback $STACK or cdk rollback $STACK --orphan <LogicalId>. See troubleshooting-deployment.

Non-empty S3 buckets persist after destroy: You MUST set both removalPolicy: DESTROY and autoDeleteObjects: true. Versioned buckets are worse — delete markers persist even after apparent deletion.

Common Workflows

Task	Quick Command	Details
Bootstrap	cdk bootstrap aws://$ACCOUNT/$REGION	bootstrap-and-project-setup
New TS project	cdk init app --language typescript — use tsx, eslint-plugin-awscdk	bootstrap-and-project-setup
New Python project	cdk init app --language python — pin deps, use virtualenv	bootstrap-and-project-setup
Deploy	cdk synth --strict → cdk diff → cdk deploy	Always diff before deploy to prod
cdk-nag	Aspects.of(app).add(new AwsSolutionsChecks())	compliance-and-drift
Drift	cdk drift $STACK (use --fail in CI)	compliance-and-drift
Import resource	cdk import (interactive or --resource-mapping for CI), cdk deploy --import-existing-resources	import-and-migrate
Refactor safely	cdk refactor --unstable=refactor — no property changes in same deploy	refactor-and-prevent-replacement

Troubleshooting

Error	Cause → Fix
DeployFailed / DeploymentError	CDK error is not root cause. Check CFN events: aws cloudformation describe-stack-events --stack-name $STACK --query "StackEvents[?contains(ResourceStatus,'FAILED')]". Details
NoCredentials / ExpiredToken / AssumeRoleFailed	aws sts get-caller-identity + cdk doctor. Expired SSO, missing env, missing sts:AssumeRole. Details
Asset errors (CannotFindAsset, FailedToBundleAsset, AssetBuildFailed, AssetPublishFailed)	Path wrong, Docker not running, or bootstrap bucket perms. Use path.join(__dirname, ...). Details
AppRequired	Add "app": "npx tsx bin/my-app.ts" to cdk.json. Details
AnnotationErrors	Fix the underlying issue; suppress with NagSuppressions only as last resort. Details
ConcurrentReadLock / ConcurrentWriteLock	rm -rf cdk.out then re-run. Parallel CI: --output ./cdk.out.$BUILD_ID. Details
BootstrapVersionValidation	Re-bootstrap. Match --qualifier everywhere. Details
DependencyCycle	Extract shared resource into third stack or use SSM for late-binding. Details
UnresolvedAccount	Set explicit env: { account, region } on stack. Commit cdk.context.json. Details
NoStacksMatched	CDK uses logical ID (2nd constructor arg), not CFN name. cdk list to find IDs. Details
Cannot find module (synth time)	Run npx tsc --noEmit, check cdk.json app path matches tsconfig.json outDir, delete stale .js files. Python: activate venv. Details
V1 import paths / duplicate aws-cdk-lib	V1 @aws-cdk/* imports, wrong Construct import, duplicate lib copies in monorepos. Details
Lambda Cannot find module (runtime)	Wrong handler value, missing SDK v3 migration, Python deps not bundled. Details
API Gateway multi-stage conflicts	Set deploy: false on RestApi, create Deployment and Stage explicitly. Details

Construct Patterns

Prefer L2. Use L1 with Mixins/Facades when L2 lacks a property. Escape hatches: node.defaultChild → addPropertyOverride. See construct-patterns.

Additional Resources

• Search AWS documentation for "CDK Developer Guide", "CDK API Reference" and "CDK Pipelines" respectively

Security Considerations

• OIDC for CI/CD credentials (no static keys)
• --custom-permissions-boundary on bootstrap
• grant*() for inter-resource IAM
• cdk-nag + --strict in CI
• Stateful resources in own stack with terminationProtection: true
• Commit cdk.context.json