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.5.tar.gz (104.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.5-py3-none-any.whl (102.6 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: cdk_preflight-0.0.5.tar.gz
  • Upload date:
  • Size: 104.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.5.tar.gz
Algorithm Hash digest
SHA256 f3f77a4a8de0cdb41ff401824bff099aa793fdc78409cf74052a1a21c48a267d
MD5 bb87e48d24f7ff806d5335f806b4b10b
BLAKE2b-256 74efe223a18a9a021d603762c8dae410bc0b9241dc967f6405f6eb25cfa614d9

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cdk_preflight-0.0.5-py3-none-any.whl
  • Upload date:
  • Size: 102.6 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.5-py3-none-any.whl
Algorithm Hash digest
SHA256 1e90609c616ee2b21a80567425fe42117a1f28f6e8164e435e00e841710e4e40
MD5 e2b43628ff6961cf3c9b8f983352e12d
BLAKE2b-256 aea2b11a7fe55831e16c3acc71804f1c64124b07780d3445b3fffc878355b60d

See more details on using hashes here.

Provenance

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

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

This release

0.0.5 This release

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