AWS Cdk Knowledge Patch

AWS CDK Knowledge Patch

Use this skill when writing, reviewing, upgrading, or debugging AWS CDK applications and construct libraries. Consult the topic references before assuming a generated L1 shape, default runtime, validation behavior, feature-flag effect, or recently added L2 capability.

How to use this patch

1. Identify the affected construct, service, and language binding.
2. Check the breaking changes and deprecations below first.
3. Open the matching topic reference for complete compatibility details.
4. Prefer the project manifest, lockfile, synthesized template, and tests when they conflict with generic guidance.
5. For generated L1 properties, compare the installed library's type declarations with the current CloudFormation contract before editing code.

Reference index

Breaking changes and migration traps

Treat validation failures as typed errors

Many construct families and the CLI now throw ValidationError rather than untyped errors. CDK errors and annotations can also carry error codes. Catch or classify by type and code; do not parse message text.

Built-in template validation uses a comprehensive default rule set. Disable it for one invocation only when necessary:

CDK_VALIDATION=false cdk synth

Validation reports are always written to the cloud assembly, include construct annotations, and use the newer self-contained schema. Report consumers must handle suppressed violations. The failSynthOnValidationErrors context key can suppress validation console output and the failing exit code.

Recheck generated L1 contracts after upgrades

Generated bindings have accumulated required-property additions, removed attributes and types, immutable fields, and replacement-only updates. Do not rely on an older L1 signature. Inspect Generated L1 and CloudFormation contracts whenever a compilation error, unexpected replacement, or missing attribute appears after upgrading.

Every generated L1 supplies from<Resource>Arn, from<Resource><Prop>, and isCfn<ResourceName> helpers. Prefer these supported factories and guards over hand-built casts.

Some exposed values now use narrow reference interfaces such as IComputeEnvironmentRef, IBackupVaultRef, IEventBusRef, and ILogGroupRef. Type-test or cast only when richer L2 members are actually required.

Update Lambda and custom-resource runtimes deliberately

Framework functions, custom resources, and Runtime.NODEJS_LATEST now resolve to Node.js 24 in every region. Node.js 24 rejects callback-style asynchronous handlers; convert them to async, pin Runtime.NODEJS_22_X, or set useLatestRuntimeVersion: false on NodejsFunction.

Python 3.8 is deprecated. Current catalogs also include Ruby 4.0, Node.js 24.x, Java 25, Python 3.14, and Java 8/11/17 variants on Amazon Linux 2023. Verify runtime availability and bundling behavior in the target region.

Do not assume old ECS defaults

AWS::ECS::Service.AvailabilityZoneRebalancing defaults to DISABLED. Set it explicitly when the intended behavior is enabled rebalancing.

ManagedInstancesCapacityProvider creates its instance profile, requires at least one security group, and accepts capacityOptionType for Spot. The deprecated canContainersAccessInstanceRole property should not be used.

Native ECS blue/green deployment support exists at L1 and L2, and built-in linear and canary configurations are available. Prefer those constructs over reconstructing the deployment contract manually.

Supply EKS dependencies and choose defaults explicitly

The older experimental Cluster and FargateCluster APIs require a kubectlLayer matching the Kubernetes version. EKS v2 constructs are stable, support native OIDC providers, removal policies, service-account overwrite control, deletion protection, provisioned control planes, and newer access-entry types.

Feature-flagged defaults can select Amazon Linux 2023 for EKS nodes. Isolated kubectl subnets produce a warning. Keep cluster, AMI, kubectl layer, and load-balancer-controller versions compatible.

Preserve explicit S3 deployment behavior

Source.jsonData() no longer escapes JSON automatically. Request the earlier behavior when needed:

Source.jsonData("config.json", data, { escape: true })

List-contained tokens are resolved, and Source.data() accepts an empty string. Asset bundling honors its configured platform, Docker builds accept network and context controls, and TarballImageAsset supports newer Docker tarball output.

Account for reversals, not just introductions

CloudWatch Logs metric-filter metrics do not retain the filter dimension map; the short-lived retention behavior was reverted. Batch useOptimalInstanceClasses remains supported after its earlier deprecation was reversed. EKS isolated-subnet validation is a warning rather than the earlier error.

High-value core and CLI capabilities

Bootstrap, plugins, and imports

• Use cdk bootstrap --untrust to retract bootstrap trust.
• Build CLI plugins against the public contract; imports from internal CLI libraries are unsupported.
• Credential plugins may return null expiration values and initially empty credentials.
• Use simplified resource import to bring existing resources under stack management with less setup.
• Treat CDK_TOOLKIT_VERSION as a supported cloud-assembly environment variable.

Synthesis and construct composition

• Use RemovalPolicies.of(scope) to apply removal policies from a scope-oriented entry point.
• Use additional context cache keys when otherwise identical lookups need distinct cached results.
• Use IEnvironmentAware to retrieve a construct's environment.
• Prefer weak cross-stack references when reference strength is unspecified; they support cross-environment use and list-valued attributes.
• Use Fn::GetStackOutput for cross-region stack outputs.
• Use Box for deferred values when accurate source traces matter.
• Use property injectors across L2 constructors and PropertyMergeStrategy for object or array merge behavior.

Mixins and validation plugins

Mixins are the stable extension mechanism exposed by @aws-cdk/cfn-property-mixins, with Aspect conversion helpers and S3/ECS service mixins in aws-cdk-lib. ECR and S3 provide auto-delete mixins.

Add app validation plugins through Validations; use addWarning, addError, and acknowledge. Policy-validation APIs use policyValidation, and validation plugins receive scope context and may write files into the cloud assembly.

High-value service capabilities

Workflows and event delivery

• Step Functions supports JSONata, workflow variables, JSONata ItemSelector and maxConcurrency, dynamic queue ARNs and result buckets, Parallel parameters, and custom Distributed Map writer configuration.
• State machines synthesize permissions for running and redriving Distributed Map, including maps nested in a StateGraph.
• EventBridge supports explicit rule roles, event-bus logging, archive encryption, HTTP API integrations, and targets for HTTP APIs, SNS, SQS, and Data Firehose.
• Data Firehose is stable and supports dynamic partitioning, record-format conversion, HTTP and Datadog destinations, processors, time zones, and EC2 flow-log destinations.
• Lambda Kafka event sources support timestamps, schema registries, failure destinations, and observability configuration.

Networking and edge

• CloudFront supports gRPC, VPC origins, origin-group selection criteria, versioned reads, IP-address controls, response-completion timeouts, and the Managed-HostHeaderOnly origin request policy.
• API Gateway supports dual-stack REST, HTTP, WebSocket, and domain configurations; TLS 1.3 domain policies; response streaming; WebSocket usage plans and API keys; and explicit Lambda-authorizer roles.
• Elastic Load Balancing supports minimum capacity reservations, NLB subnet mappings, mTLS CA-name advertisement, target-group health attributes, multi-value Lambda headers, and ALB JWT verification.
• Route 53 supports SVCB, HTTPS, failover records, accelerated recovery, and restricted delegation grants. Supplying TTL with an alias target produces a warning.
• Gateway VPC endpoints accept ipAddressType and dnsRecordIpType; ECS clusters can attach existing Cloud Map namespaces.

Data services

• DynamoDB TableV2 supports MRSC and cross-account global-table replication. Resource policies cover streams, and grants include index ARNs added after the original grant.
• RDS supports deferred modifications, Database Insights, engine lifecycle settings, snapshot restores, standalone parameter groups, proxy authentication schemes, and service-native Secrets Manager credentials.
• Aurora supports instance Availability Zones, Serverless v2 auto-pause, Limitless PostgreSQL, and current engine catalogs.
• S3 supports replication filters and custom roles, attribute-based access control, blocked encryption types, bucket-name prefixes and namespaces, and S3 Tables L2 constructs with KMS encryption.
• OpenSearch supports node options, S3 Vectors, gp3 throughput up to 2000 MiB/s, and local-storage node families that do not require EBS.

Observability and operations

• CloudWatch Logs supports field indexes, transformers, multiple stats commands, transformed-log metric filters, Infrequent Access in ADC regions, and deletion protection.
• Dashboard widgets support search expressions, query languages, pie-chart labels, cross-account visibility, metric IDs, and visibility controls.
• CloudWatch supports anomaly-detection alarms, PromQL alarms, composite AT_LEAST expressions, and mute rules.
• Synthetics supports safe updates, retries, tags, canary groups, browser selection, root-level scripts for newer Puppeteer runtimes, and current Node.js, Python, and Playwright runtimes.
• AppConfig supports environment and configuration-profile deletion protection, deployment-tick extensions, and KMS-encrypted hosted configurations.

Review checklist

• Confirm the installed aws-cdk-lib and construct package versions before applying compatibility advice.
• Inspect generated types for required, removed, and immutable L1 fields.
• Synthesize and diff changes that touch defaults, update policies, replacement-only properties, IAM, or encryption.
• Check feature flags explicitly; several behaviors are flag-controlled or changed defaults.
• Verify runtime, region, architecture, and image availability for deployment targets.
• Treat tokens as unresolved during validation unless the referenced guidance says token values are accepted.
• Prefer typed errors, error codes, and validation reports over message parsing.
• Open the full topic reference when an item involves more than one service.