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.9.tar.gz (134.7 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.9-py3-none-any.whl (132.8 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: cdk_preflight-0.0.9.tar.gz
  • Upload date:
  • Size: 134.7 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.9.tar.gz
Algorithm Hash digest
SHA256 e9dd6ae62e2ea28ad0bdf74a82d0f151dbf8cca922b10650d32df06bae2e9efe
MD5 c737260f47f6b8134e93fab8cb31f9ee
BLAKE2b-256 111da1538e631053608e283c4337baf084275800a08a33ab286e04733464fbc7

See more details on using hashes here.

Provenance

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

File metadata

  • Download URL: cdk_preflight-0.0.9-py3-none-any.whl
  • Upload date:
  • Size: 132.8 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.9-py3-none-any.whl
Algorithm Hash digest
SHA256 483c611e637108aa285d9fc8cab63f413cf59792de0921b98b97ba06d2317b52
MD5 17b098dc32519a70e4f6ebda15340854
BLAKE2b-256 abbbfd550603a6b9323fabeebf13b772b3c052ca463f08d09430af3ee9ed5410

See more details on using hashes here.

Provenance

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

This release

0.0.9 This release

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