Skip to content
CloudFormation Linter
Branch: master
Clone or download
Latest commit 2089187 May 25, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Add Spec file/versioning information to the Issue Template (#679) Feb 26, 2019
docs Nesting rules May 20, 2019
examples Changed year from 2018 to 2019 (#555) Jan 5, 2019
logo Update SVG logo to have correct font in label (#701) Mar 7, 2019
scripts Added ap-east-1 to pricing script Apr 29, 2019
src/cfnlint Support CDK generated templates May 24, 2019
test Convert datetime to string when dumping transformed templates May 24, 2019
.coveragerc Add coverage testing Dec 12, 2018
.gitignore Added rule E3022 for dup route table associations Oct 26, 2018
.pre-commit-hooks.yaml Migrate to aws-cloudformation Mar 3, 2019
.travis.yml Add pylint 3.7 support to the Inspection (#902) May 15, 2019
CHANGELOG.md Release v0.21.3 May 24, 2019
CODE_OF_CONDUCT.md Creating initial file from template Apr 10, 2018
CONTRIBUTING.md Migrate to aws-cloudformation Mar 3, 2019
LICENSE Switch from 'MIT' to 'MIT no attribution' Apr 17, 2018
MANIFEST.in Add LICENSE. Fixes #878 May 9, 2019
NOTICE Changed year from 2018 to 2019 (#555) Jan 5, 2019
README.md Release v0.21.3 May 24, 2019
codecov.yml Add code coverage rules to prevent small decreases in code coverage c… Mar 14, 2019
logo.png Added new cfn-lint logo to repo and README Feb 7, 2019
pylintrc update for new release of pylint Jul 16, 2018
setup.cfg Initial code commit for cfn-lint Apr 12, 2018
setup.py Uncap requests May 25, 2019
tox.ini Add pylint 3.7 support to the Inspection (#902) May 15, 2019

README.md

CloudFormation Linter

[cfn-lint logo]

Build Status PyPI version codecov

Validate CloudFormation yaml/json templates against the CloudFormation spec and additional checks. Includes checking valid values for resource properties and best practices.

Warning

This is an attempt to provide validation for CloudFormation templates properties and their values. For values things can get pretty complicated (mappings, joins, splits, conditions, and nesting those functions inside each other) so its a best effort to validate those values but the promise is to not fail if we can't understand or translate all the things that could be going on.

Serverless Application Model

The Serverless Application Model (SAM) is supported by the linter. The template is transformed using AWS SAM https://github.com/awslabs/serverless-application-model before the linter processes the template.

To get information about the SAM Transformation, run the linter with --info

Install

Python 2.7+ and 3.4+ are supported.

Pip Install

pip install cfn-lint. If pip is not available, run python setup.py clean --all then python setup.py install.

Homebrew (macOS)

brew install cfn-lint

Editor Plugins

There are IDE plugins available to get direct linter feedback from you favorite editor:

Basic Usage

  • cfn-lint template.yaml
  • cfn-lint -t template.yaml
Lint multiple files

Multiple files can be linted by either specifying multiple specific files:

  • cfn-lint template1.yaml template2.yaml
  • cfn-lint -t template1.yaml template2.yaml

Multiple files can also be specified using wildcards (globbing):

Lint all yaml files in path:

  • cfn-lint path/*.yaml

Lint all yaml files in path and all subdirectories (recursive):

  • cfn-lint path/to/templates/**/*.yaml

Note: Glob in Python 3.5 supports recursive searching **/*.yaml. If you are using an earlier version of Python you will have to handle this manually (folder1/*.yaml, folder2/*.yaml, etc).

Specifying the template as an input stream

The template to be linted can also be passed using standard input:

  • cat path/template.yaml | cfn-lint -
Specifying the template with other parameters
  • cfn-lint -r us-east-1 ap-south-1 -- template.yaml
  • cfn-lint -r us-east-1 ap-south-1 -t template.yaml

Configuration

Command Line

From a command prompt run cfn-lint <path to yaml template> to run standard linting of the template.

Config File

You can define a yaml file in your project or home folder called .cfnlintrc. In that file you can specify settings from the parameter section below.

Example:

templates:
- test/fixtures/templates/good/**/*.yaml
ignore_templates:
- codebuild.yaml
include_checks:
- I

Parameters

Optional parameters:

Command Line Metadata Options Description
-h, --help Get description of cfn-lint
-t, --template filename Alternative way to specify Template file path to the file that needs to be tested by cfn-lint
-f, --format format quiet, parseable, json Output format
-l, --list-rules List all the rules
-r, --regions regions [REGIONS [REGIONS ...]] Test the template against many regions. Supported regions
-b, --ignore-bad-template ignore_bad_template Ignores bad template errors
--ignore-templates IGNORE_TEMPLATES [IGNORE_TEMPLATES ...] Ignore templates from being scanned
-a, --append-rules append_rules [RULESDIR [RULESDIR ...]] Specify one or more rules directories using one or more --append-rules arguments.
-i, --ignore-checks ignore_checks [IGNORE_CHECKS [IGNORE_CHECKS ...]] Only check rules whose ID do not match or prefix these values. Examples:
- A value of W will disable all warnings
- W2 disables all Warnings for Parameter rules.
- W2001 will disable rule W2001
-e, --include-experimental include_experimental Whether rules that still in an experimental state should be included in the checks
-c, --include-checks INCLUDE_CHECKS [INCLUDE_CHECKS ...] Include rules whose id match these values
-x, --configure-rule CONFIGURE_RULES [CONFIGURE_RULES ...] Provide configuration for a rule. Format RuleId:key=value. Example: E3012:strict=false
-D, --debug Specify to enable debug logging. Debug logging outputs detailed information about rules processing, useful for debugging rules.
-I, --info Specify to enable logging. Outputs additional information about the template processing.
-u, --update-specs Update the CloudFormation Specs. You may need sudo to run this. You will need internet access when running this command
-o, --override-spec filename Spec-style file containing custom definitions. Can be used to override CloudFormation specifications. More info here
-v, --version Version of cfn-lint

Info Rules

To maintain backwards compatibility info rules are not included by default. To include these rules you will need to include -c I or --include-checks I

Metadata

Template Based Metadata

Inside the root level Metadata key you can configure cfn-lint using the supported parameters.

Metadata:
  cfn-lint:
    config:
      regions:
      - us-east-1
      - us-east-2
      ignore_checks:
      - E2530

Resource Based Metadata

Inside a resources Metadata key you can configure cfn-lint to ignore checks. This will filter out failures for the resource in which the Metadata belongs.

Resources:
  myInstance:
    Type: AWS::EC2::Instance
    Metadata:
      cfn-lint:
        config:
          ignore_checks:
          - E3030
    Properties:
      InstanceType: nt.x4superlarge
      ImageId: ami-abc1234

Precedence

cfn-lint applies the configuration from the CloudFormation Metadata first and then overrides those values with anything specified in the CLI.

Configure Rules

Certain rules will support configuration properties. You can configure these rules by using configure_rules parameter.

From the command line the format is E3012:strict=false From the cfnlintrc or Metadata section the format is

configure_rules:
  E3012:
    strict: False  

Getting Started Guides

There are getting started guides available in the documentation section to help with integrating cfn-lint or creating rules.

Rules

This linter checks the CloudFormation by processing a collection of Rules, where every rules handles a specific function check or validation of the template.

This collection of rules can be extended with custom rules using the --append-rules argument.

More information describing how rules are set up and an overview of all the Rules that are applied by this linter are documented here

Customize specifications

The linter follows the CloudFormation specifications by default. However, for your use case specific requirements might exist. For example, within your organisation it might be mandatory to use Tagging.

The linter provides the possibility to implement these customized specifications using the --override-spec argument.

More information about how this feature works is documented here

pre-commit

If you'd like cfn-lint to be run automatically when making changes to files in your Git repository, you can install pre-commit and add the following text to your repositories' .pre-commit-config.yaml:

repos:
-   repo: https://github.com/aws-cloudformation/cfn-python-lint
    rev: v0.21.3  # The version of cfn-lint to use
    hooks:
    -   id: cfn-python-lint
        files: path/to/cfn/dir/.*\.(json|yml|yaml)$
  • If you exclude the files: line above, every json/yml/yaml file will be checked.
  • You can see available cfn-lint versions on the releases page.

PyPi:

PyPI - Downloads PyPI - Downloads

You can’t perform that action at this time.