cfn-lint

Overview

cfn-lint is an open-source tool from AWS that validates CloudFormation templates against the CloudFormation resource specification. It catches errors before deployment and enforces best practices.

How the starter kit uses cfn-lint

Integration Point	Description
Local validation	Run `cfn-lint templates/*.yml` directly before committing
CI enforcement	Deploy workflow runs cfn-lint before Rain deployment; failing checks block the pipeline
VS Code integration	Pair with the CloudFormation Linter extension for real-time validation

Note: The validate-templates.sh script runs Checkov only. Run cfn-lint directly for template syntax validation.

Running cfn-lint

Directly

# Validate all templates
cfn-lint templates/*.yml

# Validate a single template
cfn-lint templates/oidc-provider.yml

# With specific configuration
cfn-lint --config .cfnlintrc templates/*.yml

Common issues detected

Missing required properties

Resources:
  Bucket:
    Type: AWS::S3::Bucket
    Properties:
      BucketEncryption:
        ServerSideEncryptionConfiguration:
          # Missing required Rules property

Error: E3002: Invalid property for resource

Invalid property values

Resources:
  Instance:
    Type: AWS::EC2::Instance
    Properties:
      InstanceType: t2.invalid  # Invalid instance type

Error: E3030: Value must be one of the allowed values

Incorrect intrinsic functions

Resources:
  BucketPolicy:
    Type: AWS::S3::BucketPolicy
    Properties:
      Bucket: !Ref Bucket
      PolicyDocument:
        Statement:
          - Effect: Allow
            Resource: !Ref Bucket  # Should use !GetAtt Bucket.Arn

Error: E1012: Ref is not valid for resource type

Configuration

The starter kit includes a .cfnlintrc file. See the linting configuration section for customization details.

Configuration file format

# .cfnlintrc
templates:
  - templates/*.yml
  - templates/*.yaml

ignore_templates:
  - templates/experimental/*.yml

regions:
  - us-east-1
  - eu-west-1

ignore_checks:
  - E3001  # Skip specific rule
  - W*     # Skip all warnings

configure_rules:
  E3012:
    strict: false

Configuration options

Option	Description
`templates`	Glob patterns for templates to validate
`ignore_templates`	Exclude specific templates
`regions`	Validate against specific regions
`ignore_checks`	Skip specific rules by ID
`include_checks`	Include additional check types
`configure_rules`	Fine-tune specific rules

Rule categories

Category	Description
E1xxx	Basic CloudFormation errors (syntax, schema)
E2xxx	Template structure errors (limits, formatting)
E3xxx	Resource specification errors (properties, values)
E4xxx	Function errors (Ref, GetAtt, Sub, etc.)
W1xxx	Basic warnings
W2xxx	Template structure warnings
W3xxx	Resource specification warnings
I1xxx	Informational messages

Suppressing rules

Inline metadata suppression

Suppress rules for specific resources:

Resources:
  LegacyBucket:
    Type: AWS::S3::Bucket
    Metadata:
      cfn-lint:
        config:
          ignore_checks:
            - E3001
            - W3045
    Properties:
      BucketName: legacy-bucket

Template-level suppression

Suppress rules for the entire template:

Metadata:
  cfn-lint:
    config:
      ignore_checks:
        - W3045

Output formats

Format	Command	Use Case
Default	`cfn-lint templates/*.yml`	Human-readable output
JSON	`cfn-lint --format json templates/*.yml`	Parsing in scripts
JUnit	`cfn-lint --format junit templates/*.yml > results.xml`	Test reporting
Parseable	`cfn-lint --format parseable templates/*.yml`	Tool integration

VS Code integration

Install the CloudFormation Linter extension for real-time validation:

Install CloudFormation Linter extension
Install cfn-lint: pip install cfn-lint
Open any CloudFormation template
See errors and warnings inline as you type

For more tips, read our guide on leveling up CloudFormation authoring in VS Code.

Best practices

Run locally first - Use ./scripts/validate-templates.sh before committing
Keep cfn-lint updated - Run pip install --upgrade cfn-lint regularly
Review all errors - Don't ignore errors; they usually indicate real problems
Use VS Code integration - Get real-time feedback while editing
Configure for your regions - Set the regions option to validate against target regions

Troubleshooting

Template not found

Check file paths in .cfnlintrc or command line arguments.

Python version issues

cfn-lint requires Python 3.8+:

python --version
pip install --upgrade cfn-lint

Outdated resource specs

If cfn-lint doesn't recognize new AWS resources:

pip install --upgrade cfn-lint

Next steps

Checkov reference - Security scanning
Scripts reference - Validation automation
Local Development - Daily workflow