cdk-preflight

Catch deploy-time CloudFormation failures at cdk synth time.

Some CloudFormation constraints are not expressed in resource provider schemas — they live only in documentation, in service API validation, or across multiple properties. Templates that violate them pass cdk synth, pass CloudFormation pre-deployment validation, and then fail minutes into a deployment, burning a rollback cycle.

cdk-preflight is a curated Rego rule pack for exactly those constraints, evaluated with the CloudFormation validation engine that ships inside aws-cdk-lib (>= 2.267.0). By default a violation fails cdk synth — a template that is known to fail at deploy time never leaves your machine.

Every bundled rule is backed by a fail/pass template pair, and the failure has been reproduced against real AWS (or is explicitly marked doc-only). Rules that the built-in validation engine already covers are deliberately not duplicated — a test suite enforces this.

Quick start

npm i -D cdk-preflight
npx cdk-preflight init   # inserts Preflight.apply(app) into your CDK app

or add one line yourself:

import { Preflight } from 'cdk-preflight';

const app = new App();
Preflight.apply(app);

On violation, cdk synth fails with one error per finding, including the construct trace:

ERROR idle_timeout.timeout_seconds is 5000 but must be between 1 and 4000 seconds (cdk-preflight)
   MyStack/Alb/Resource (Alb16C2F182) aws-cdk-lib.aws_elasticloadbalancingv2.CfnLoadBalancer

Synthesis finished with errors

Observe-only mode

To roll the rules out gradually, start with enforce: false: findings then surface as synth warnings through the CDK built-in validator, with construct traces and per-finding acknowledgement:

Preflight.apply(app, { enforce: false });

WARNING idle_timeout.timeout_seconds is 5000 but must be between 1 and 4000 seconds (CloudFormation Validate)
   MyStack/Alb (Alb) aws-cdk-lib.aws_elasticloadbalancingv2.CfnLoadBalancer
   Acknowledge with 'CloudFormation-Validate::pf-elbv2-lb-idle-timeout-range'
Option Default Effect
enforce true Violations of bundled rules fail synthesis; set to false to only warn
strict false With enforce: also fail on error-class findings (ERROR/FATAL, e.g. F3034) of the built-in validation engine itself, which the CDK currently downgrades to warnings
exclude [] Rule ids to disable
includeUpstreamPending true Include rules already proposed to the upstream engine but not yet merged

To opt out of a single rule, pass its id in exclude. In observe-only mode, individual findings can also be suppressed with the CDK acknowledge mechanism shown in the warning text.

Bundled rules

See docs/rules.md for the generated rule table. Highlights:

  • ELBv2: idle_timeout / deregistration_delay / slow_start attribute ranges (stringly-typed Key/Value attributes are invisible to schema validation)
  • IAM: managed (6,144 chars) and inline (role/group/user) policy document size limits
  • CloudFront: MinTTL <= DefaultTTL <= MaxTTL ordering, ACM certificates must live in us-east-1
  • Step Functions: Next/Default/Choices must reference defined states (a dangling StartAt is already caught by the engine's built-in E3601)
  • EC2: security group TCP/UDP port ranges and FromPort <= ToPort

For AI agents

To add cdk-preflight to a CDK app:

  1. npm i -D cdk-preflight
  2. npx cdk-preflight init (finds the entry point via cdk.json and inserts Preflight.apply(app); use --dry-run to preview)
  3. Run cdk synth. Violations fail the synth with a validation report; each finding carries a rule id, the actual value, and a suggested fix
  4. To fix a finding, prefer correcting the resource. To opt out instead: exclude: ['<rule-id>'] disables one rule, enforce: false switches to warn-only reporting

The machine-readable findings are written to cdk.out/validation-report.json when synthesizing with -c @aws-cdk/core:validationReportJson=true.

How it works

Preflight.apply() evaluates the rules with the cloudformation-validate Rust/WASM engine that ships inside aws-cdk-lib — no extra binaries, no network access at synth time. In the default enforce mode the engine is invoked through a dedicated CDK validation plugin so that violations fail synthesis; with enforce: false the rules are instead injected into the CDK built-in CloudFormationValidatePlugin and reported as warnings.

Constraints that can be expressed in schemas or generic engine rules are contributed upstream instead of living here; each rule's meta.yaml tracks its upstream status, and rules retire once the engine covers them.

Requirements

  • aws-cdk-lib >= 2.267.0 (the first release that bundles the built-in CloudFormation validator)

Contributing

Rule authoring, the verification gates (including real-deploy reproduction), and the test layout are documented in AGENTS.md — written for AI coding agents and humans alike.

License

Apache-2.0

Project links

Data verified by PyPI on Sep 3, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.0.48)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for badmintoncryer from gravatar.com badmintoncryer

Credits

Author: Kazuho CryerShinozuka<malaysia.cryer@gmail.com>

GitHub Statistics

Data verified by PyPI on Sep 3, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

OSI Approved (Apache-2.0)

Requires

Python >=3.10

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cdk_preflight-0.0.20.tar.gz (219.6 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

cdk_preflight-0.0.20-py3-none-any.whl (217.7 kB view details)

Uploaded Python 3

File details

Details for the file cdk_preflight-0.0.20.tar.gz.

File metadata

  • Download URL: cdk_preflight-0.0.20.tar.gz
  • Upload date:
  • Size: 219.6 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.14.7

File hashes

Hashes for cdk_preflight-0.0.20.tar.gz
Algorithm Hash digest
SHA256 8b95c8e801637c2de00343e30ec74f195c49e21426a97baef809a568a560e7b3
MD5 bd2be91363291df22cf94b1c4b30bcce
BLAKE2b-256 ca3e0095a334e8d05a12ce2845cf3f0cb8658b882d965067f978b2bea7b8958f

See more details on using hashes here.

Provenance

The following attestation bundles were made for cdk_preflight-0.0.20.tar.gz:

Publisher: release.yml on badmintoncryer/cdk-preflight

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file cdk_preflight-0.0.20-py3-none-any.whl.

File metadata

  • Download URL: cdk_preflight-0.0.20-py3-none-any.whl
  • Upload date:
  • Size: 217.7 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.14.7

File hashes

Hashes for cdk_preflight-0.0.20-py3-none-any.whl
Algorithm Hash digest
SHA256 26bc97b273dcde875fffc59c7c80af6672ac5c8ad3394fc395ca7a51226ed42f
MD5 ab6084c55fbe49469126403d8ec6ac94
BLAKE2b-256 29f82ddb379ee50bbd39fe4078cbfe9c9873462d37f2ecdbc64ffca26d0fa16c

See more details on using hashes here.

Provenance

The following attestation bundles were made for cdk_preflight-0.0.20-py3-none-any.whl:

Publisher: release.yml on badmintoncryer/cdk-preflight

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

0.0.48

2 files

0.0.47

2 files

0.0.46

2 files

0.0.45

2 files

0.0.44

2 files

0.0.43

2 files

0.0.42

2 files

0.0.41

2 files

0.0.40

2 files

0.0.39

2 files

0.0.38

2 files

0.0.37

2 files

0.0.36

2 files

0.0.35

2 files

0.0.34

2 files

0.0.33

2 files

0.0.32

2 files

0.0.31

2 files

0.0.30

2 files

0.0.29

2 files

0.0.28

2 files

0.0.27

2 files

0.0.26

2 files

0.0.25

2 files

0.0.24

2 files

0.0.23

2 files

0.0.22

2 files

0.0.21

2 files

This release

0.0.20 This release

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

0.0.16

2 files

0.0.15

2 files

0.0.14

2 files

0.0.13

2 files

0.0.12

2 files

0.0.11

2 files

0.0.10

2 files

0.0.9

2 files

0.0.8

2 files

0.0.7

2 files

0.0.6

2 files

0.0.5

2 files

0.0.4

2 files

0.0.3

2 files

0.0.2

2 files

0.0.1

2 files

0.0.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page