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 2, 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 2, 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.16.tar.gz (189.3 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.16-py3-none-any.whl (188.0 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: cdk_preflight-0.0.16.tar.gz
  • Upload date:
  • Size: 189.3 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.16.tar.gz
Algorithm Hash digest
SHA256 e62f94693bc29624e62b1bdf1d561023cf4cd2fbea4dbff024ce2b5790d7c28a
MD5 46ec4a0688ccc5bb8b78a7dd482c7630
BLAKE2b-256 fb5ab0ada0a47af759ac8ed30916914e7d809dee9f23a08d31b7f198d0e26772

See more details on using hashes here.

Provenance

The following attestation bundles were made for cdk_preflight-0.0.16.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.16-py3-none-any.whl.

File metadata

  • Download URL: cdk_preflight-0.0.16-py3-none-any.whl
  • Upload date:
  • Size: 188.0 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.16-py3-none-any.whl
Algorithm Hash digest
SHA256 1df6c91e5e12ca028c4ea4952f32e54bb5178347d0932b24676b7ec03d534553
MD5 88d65684994247f18ed1aa2682a873ec
BLAKE2b-256 22c3112346bd5ea332bdac6f334bab128beb24003b5be1394860805a7c0eb323

See more details on using hashes here.

Provenance

The following attestation bundles were made for cdk_preflight-0.0.16-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

0.0.20

2 files

0.0.19

2 files

0.0.18

2 files

0.0.17

2 files

This release

0.0.16 This release

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