AWS Cdk Knowledge Patch

AWS CDK Knowledge Patch

Load this skill when changing, reviewing, debugging, or upgrading AWS CDK applications, construct libraries, CLI integrations, or synthesized CloudFormation templates.

Prefer the project's manifests, lockfiles, source, synthesized output, and tests when they disagree with this guidance. Apply feature-flagged behavior only when the relevant flag is enabled.

Reference index

First-pass compatibility audit

Before editing an established application:

1. Read the package-manager manifest and lockfile to identify the exact aws-cdk-lib, constructs, CLI, and alpha-module versions.
2. Inspect cdk.json, context files, environment variables, and feature flags; many defaults are intentionally flag-gated.
3. Search for generated L1 properties or attributes that became required, immutable, optional, renamed, or removed.
4. Check custom implementations of public interfaces for newly required reference getters or narrower return types.
5. Review Lambda, custom-resource, EKS, Batch, and CloudFront runtime defaults before accepting a synthesized diff.
6. Synthesize and inspect replacement-sensitive resources, IAM policies, runtime choices, validation reports, and asset commands.
7. Run the application's tests and any snapshot assertions against the actual synthesized assembly.

Breaking contracts and reversals

Treat validation failures as typed errors

Many construct libraries and the CLI now throw ValidationError rather than untyped errors. Catch typed errors and use error codes where available; do not classify failures by message text.

Audit generated L1 surfaces during upgrades

CloudFormation schema refreshes can remove attributes and nested types, make properties required or immutable, or change replacement behavior. Compile all languages and inspect the synthesized template rather than assuming a former generated member still exists.

Generated L1s also expose import factories, resource interfaces, construct-valued relationship parameters, and static isCfn<ResourceName> guards. Prefer these public contracts to hand-built casts.

Account for narrower reference interfaces

Several APIs now return I<Resource>Ref values instead of richer L2 interfaces. Type-test or cast only when code genuinely needs L2-only members.

IEncryptedResource is environment-aware but is not necessarily an IResource. Use an intersection type or Resource.isResource() when both contracts are required.

Use current reversal outcomes

• CloudWatch Logs metric-filter metrics do not retain the filter dimension map.
• Batch useOptimalInstanceClasses remains supported despite its earlier deprecation.
• Isolated kubectl subnets produce an EKS warning, not an error.
• Native ECS blue/green L2 support is present; do not infer absence from the short-lived revert.

Recheck replacement-sensitive L1 properties

Immutable properties on resources such as EC2 Fleets, CloudFront Functions, OpenSearch Serverless collections, SageMaker clusters, Lex policies, and AppStream image builders can force replacement. Treat synthesized replacement changes as deployment decisions, not formatting noise.

Runtime and platform defaults

Lambda and custom resources

Framework functions, custom resources, and Runtime.NODEJS_LATEST now select Node.js 24.x. Callback-style asynchronous handlers are unsupported there; convert them to async, pin Node.js 22.x, or disable latest-runtime selection for NodejsFunction.

The runtime catalogs also contain newer Ruby, Java, Python, and Node.js entries. Confirm regional availability and test native dependencies before changing a runtime.

EKS and container platforms

Experimental EKS clusters require an explicit kubectlLayer matching the Kubernetes version. Stable EKS v2 constructs, newer Kubernetes versions, Hybrid Nodes, managed node repair, native OIDC providers, access-entry types, and provisioned control planes are available.

Feature flags can switch EKS and Batch defaults to Amazon Linux 2023. Review AMI changes and bootstrap assumptions before rollout.

CloudFront Functions and Synthetics

CloudFront Functions can default to JavaScript 2.0 under its feature flag. Synthetics supports newer Node.js, Playwright, Puppeteer, Python Selenium, browser-selection, retry, group, and safe-update capabilities; choose an explicit runtime when reproducibility matters.

Validation and synthesis

Built-in template validation

CDK validates templates with a comprehensive default rule set. For a single invocation, set CDK_VALIDATION=false only when bypassing built-in validation is deliberate:

CDK_VALIDATION=false cdk synth

Do not treat this switch as a substitute for fixing application or policy-validation findings.

Validation plugins and reports

Use Validations to add plugins and emit warnings or errors. The stable policy-validation interfaces omit the older beta suffix.

Validation reports are always written to the cloud assembly, include construct annotations and suppressed violations, use the newer schema, and may include plugin-created files. Consumers must not assume every reported violation failed synthesis.

failSynthOnValidationErrors can suppress validation-error console output and the failing exit code. Keep CI behavior explicit when adopting it.

Diagnostics and source traces

Deferred Box values preserve source traces. L1 property mutations and external ConstructError traces can flow into cloud-assembly metadata, making post-construction changes easier to locate.

Weak references and cross-region outputs

Choose reference strength deliberately. Weak cross-stack references work within and across environments, including list-valued attributes, while Fn::GetStackOutput supports cross-region output references.

CLI, bootstrap, and plugin boundaries

Use cdk bootstrap --untrust to retract bootstrap trust.

CLI plugins must target the public plugin contract and must not import internal CLI libraries. Credential plugins may return a null expiration and may initially return empty credentials.

Simplified CloudFormation resource import reduces manual import setup. Keep logical-ID and ownership changes under review when bringing existing resources into a stack.

CDK_TOOLKIT_VERSION is a supported cloud-assembly environment contract. Pipelines can also pin the cdk-assets version.

Workflow quick reference

Step Functions

JSONata and workflow variables are supported across additional task and state properties, including Map selectors and concurrency, dynamic queue ARNs and result buckets, intrinsic API endpoints, and REST API paths.

Distributed Map supports custom writer configuration and synthesizes run and redrive permissions, including for maps nested only in a StateGraph.

CodePipeline and CodeBuild

Pipelines support command, invoke-pipeline, EC2 deployment, ECR publish, Inspector scan, trigger-filter, stage-condition, and manual-approval capabilities. Pipeline projects propagate fleet and certificate settings.

CodeBuild supports attribute-based fleets, custom fleet instances and VPCs, shared caches, remote Docker servers, newer Windows and macOS images, and configurable build compute types.

Assets and packaging

Asset bundling honors platform; Docker build options accept network and context controls; tarball assets handle newer Docker output and honor CDK_DOCKER; and current Bun lockfiles are recognized without forcing frozen-lockfile behavior.

Service quick reference

Containers

ECS includes enhanced Container Insights, fault injection, availability-zone rebalancing controls, Service Connect TLS and access logs, managed-storage encryption, managed-instances capacity providers, deployment strategies, and existing Cloud Map namespaces.

Check the current availability-zone rebalancing default for raw AWS::ECS::Service resources, and review security-group behavior when using ECS patterns.

Networking and APIs

API Gateway supports dual-stack APIs and domains, private-API policies, response streaming, WebSocket usage plans, stage variables, access logs, TLS 1.3, Lambda-authorizer roles, and additional integrations.

CloudFront supports gRPC, VPC origins, versioned reads, origin-group criteria, HTTP-origin controls, Lambda Function URL addressing, host-header-only origin policy, and stronger certificate diagnostics.

Elastic Load Balancing supports minimum capacity, NLB subnet mappings, mTLS CA-name advertisement, Lambda multi-value headers, health attributes, ALB JWT verification, and feature-flagged NLB security groups.

Storage and databases

RDS and Aurora include lookup, proxy endpoints, maintenance-window modification, backup retention, replication sources, lifecycle controls, Database Insights, Serverless v2 auto-pause, native Secrets Manager credentials, and expanded engine catalogs.

S3 includes replication filters and custom roles, public-access defaults, deployment token fixes, blocked encryption types, attribute-based access control, naming prefixes and namespaces, and auto-delete Mixins. S3 Tables includes table, namespace, and KMS-encryption support.

DynamoDB includes the point-in-time recovery specification, MRSC and cross-account global-table replication, compound GSI keys, stream resource policies, index-aware grant policies, and stricter grantee validation.

Events and observability

EventBridge, Scheduler, Kinesis, Data Firehose, SNS, SQS, and Lambda event sources expose additional destinations, processors, failure handling, dynamic partitioning, format conversion, HTTP delivery, stream consumers, and observability controls.

CloudWatch adds newer alarm, dashboard, metric, query, transformer, field-index, deletion-protection, PromQL, cross-account, and composite-rule capabilities. Verify AgentCore metric dimensions before reusing existing alarms or dashboards.

Identity and AI services

Cognito supports managed login, analytics, choice-based authentication, passkeys, refresh-token rotation, identity pools, and newer pre-token trigger events.

Bedrock and AgentCore include newer foundation-model identifiers, inference profiles, customization workflows, runtimes, tools, memory, gateways, interface endpoints, authorizers, IAM credential targets, and stream delivery resources.

Use the detailed references for exact property names, defaults, version catalogs, feature-flag conditions, and generated schema changes.