Skip to content
master
Go to file
Code

README.md

Collection of git hooks for Terraform to be used with pre-commit framework

Github tag Help Contribute to Open Source

How to install

1. Install dependencies

  • pre-commit
  • terraform-docs required for terraform_docs hooks. GNU awk is required if using terraform-docs older than 0.8.0 with Terraform 0.12.
  • TFLint required for terraform_tflint hook.
  • TFSec required for terraform_tfsec hook.
  • coreutils required for terraform_validate hook on macOS (due to use of realpath).
MacOS
brew tap liamg/tfsec
brew install pre-commit gawk terraform-docs tflint tfsec coreutils
Ubuntu
sudo apt install python3-pip gawk &&\
pip3 install pre-commit
curl -L "$(curl -s https://api.github.com/repos/segmentio/terraform-docs/releases/latest | grep -o -E "https://.+?-linux-amd64")" > terraform-docs && chmod +x terraform-docs && sudo mv terraform-docs /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/terraform-linters/tflint/releases/latest | grep -o -E "https://.+?_linux_amd64.zip")" > tflint.zip && unzip tflint.zip && rm tflint.zip && sudo mv tflint /usr/bin/
env GO111MODULE=on go get -u github.com/liamg/tfsec/cmd/tfsec

2. Install the pre-commit hook globally

DIR=~/.git-template
git config --global init.templateDir ${DIR}
pre-commit init-templatedir -t pre-commit ${DIR}

3. Add configs and hooks

Step into the repository you want to have the pre-commit hooks installed and run:

git init
cat <<EOF > .pre-commit-config.yaml
repos:
- repo: git://github.com/antonbabenko/pre-commit-terraform
  rev: <VERSION> # Get the latest from: https://github.com/antonbabenko/pre-commit-terraform/releases
  hooks:
    - id: terraform_fmt
    - id: terraform_docs
EOF

4. Run

After pre-commit hook has been installed you can run it manually on all files in the repository

pre-commit run -a

Available Hooks

There are several pre-commit hooks to keep Terraform configurations (both *.tf and *.tfvars) and Terragrunt configurations (*.hcl) in a good shape:

Hook name Description
terraform_fmt Rewrites all Terraform configuration files to a canonical format.
terraform_validate Validates all Terraform configuration files.
terraform_docs Inserts input and output documentation into README.md. Recommended.
terraform_docs_without_aggregate_type_defaults Inserts input and output documentation into README.md without aggregate type defaults.
terraform_docs_replace Runs terraform-docs and pipes the output directly to README.md
terraform_tflint Validates all Terraform configuration files with TFLint.
terragrunt_fmt Rewrites all Terragrunt configuration files (*.hcl) to a canonical format.
terraform_tfsec TFSec static analysis of terraform templates to spot potential security issues.

Check the source file to know arguments used for each hook.

Notes about terraform_docs hooks

  1. terraform_docs and terraform_docs_without_aggregate_type_defaults will insert/update documentation generated by terraform-docs framed by markers:
<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

if they are present in README.md.

  1. terraform_docs_replace replaces the entire README.md rather than doing string replacement between markers. Put your additional documentation at the top of your main.tf for it to be pulled in. The optional --dest argument lets you change the name of the file that gets created/modified.

    1. Example:
    hooks:
      - id: terraform_docs_replace
        args: ['--with-aggregate-type-defaults', '--sort-inputs-by-required', '--dest=TEST.md']
  2. It is possible to pass additional arguments to shell scripts when using terraform_docs and terraform_docs_without_aggregate_type_defaults. Send pull-request with the new hook if there is something missing.

Notes about terraform_tflint hooks

  1. terraform_tflint supports custom arguments so you can enable module inspection, deep check mode etc.

    1. Example:
    hooks:
      - id: terraform_tflint
        args: ['args=--deep']

    In order to pass multiple args, try the following:

     - id: terraform_tflint
       args:
          - 'args=--deep'
          - 'args=--enable-rule=terraform_documented_variables'

Notes about terraform_tfsec hooks

  1. terraform_tfsec will recurse all directories/modules.
  2. To ignore specific warnings, follow the convention from the documentation.
    1. Example:
    resource "aws_security_group_rule" "my-rule" {
        type = "ingress"
        cidr_blocks = ["0.0.0.0/0"] #tfsec:ignore:AWS006
    }

Notes for developers

  1. Python hooks are supported now too. All you have to do is:
    1. add a line to the console_scripts array in entry_points in setup.py
    2. Put your python script in the pre_commit_hooks folder

Enjoy the clean and documented code!

Authors

This repository is managed by Anton Babenko with help from these awesome contributors.

License

MIT licensed. See LICENSE for full details.

You can’t perform that action at this time.