Want to contribute? Check open issues and contributing notes.
Automated provisioning of Terraform workflows and Infrastructure as Code.
Cloud cost estimates for Terraform.
If you are using pre-commit-terraform
already or want to support its development and many other open-source projects, please become a GitHub Sponsor!
--args
pre-commit
checkov
required for checkov
hook.terraform-docs
required for terraform_docs
hook.terragrunt
required for terragrunt_validate
hook.terrascan
required for terrascan
hook.TFLint
required for terraform_tflint
hook.TFSec
required for terraform_tfsec
hook.infracost
required for infracost_breakdown
hook.jq
required for infracost_breakdown
hook.tfupdate
required for tfupdate
hook.hcledit
required for terraform_wrapper_module_for_each
hook.Note: not needed if you use the Docker image
DIR=~/.git-template
git config --global init.templateDir ${DIR}
pre-commit init-templatedir -t pre-commit ${DIR}
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: https://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
Execute this command to run pre-commit
on all files in the repository (not only changed files):
pre-commit run -a
Or, using Docker (available tags):
NOTE: This command uses your user id and group id for the docker container to use to access the local files. If the files are owned by another user, update the USERID
environment variable. See File Permissions section for more information.
TAG=latest
docker run -e "USERID=$(id -u):$(id -g)" -v $(pwd):/lint -w /lint ghcr.io/antonbabenko/pre-commit-terraform:$TAG run -a
Execute this command to list the versions of the tools in Docker:
TAG=latest
docker run --rm --entrypoint cat ghcr.io/antonbabenko/pre-commit-terraform:$TAG /usr/bin/tools_versions_info
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 | Dependencies Install instructions here |
---|---|---|
checkov and terraform_checkov |
checkov static analysis of terraform templates to spot potential security issues. Hook notes | checkov Ubuntu deps: python3 , python3-pip |
infracost_breakdown |
Check how much your infra costs with infracost. Hook notes | infracost , jq , Infracost API key |
terraform_docs |
Inserts input and output documentation into README.md . Recommended. Hook notes |
terraform-docs |
terraform_docs_replace |
Runs terraform-docs and pipes the output directly to README.md. DEPRECATED, see #248. Hook notes |
python3 , terraform-docs |
terraform_docs_without_ aggregate_type_defaults |
Inserts input and output documentation into README.md without aggregate type defaults. Hook notes same as for terraform_docs |
terraform-docs |
terraform_fmt |
Reformat all Terraform configuration files to a canonical format. Hook notes | - |
terraform_providers_lock |
Updates provider signatures in dependency lock files. Hook notes | - |
terraform_tflint |
Validates all Terraform configuration files with TFLint. Available TFLint rules. Hook notes. | tflint |
terraform_tfsec |
TFSec static analysis of terraform templates to spot potential security issues. Hook notes | tfsec |
terraform_validate |
Validates all Terraform configuration files. Hook notes | - |
terragrunt_fmt |
Reformat all Terragrunt configuration files (*.hcl ) to a canonical format. |
terragrunt |
terragrunt_validate |
Validates all Terragrunt configuration files (*.hcl ) |
terragrunt |
terraform_wrapper_module_for_each |
Generates Terraform wrappers with for_each in module. Hook notes |
hcledit |
terrascan |
terrascan Detect compliance and security violations. Hook notes | terrascan |
tfupdate |
tfupdate Update version constraints of Terraform core, providers, and modules. Hook notes | tfupdate |
Check the source file to know arguments used for each hook.
--args
All, except deprecated hooks:
checkov
,terraform_docs_replace
You can use environment variables for the --args
section.
Note: You must use the ${ENV_VAR}
definition, $ENV_VAR
will not expand.
Config example:
- id: terraform_tflint
args:
- --args=--config=${CONFIG_NAME}.${CONFIG_EXT}
- --args=--module
If for config above set up export CONFIG_NAME=.tflint; export CONFIG_EXT=hcl
before pre-commit run
, args will be expanded to --config=.tflint.hcl --module
.
All, except deprecated hooks:
checkov
,terraform_docs_replace
You can specify environment variables that will be passed to the hook at runtime.
Config example:
- id: terraform_validate
args:
- --env-vars=AWS_DEFAULT_REGION="us-west-2"
- --env-vars=AWS_ACCESS_KEY_ID="anaccesskey"
- --env-vars=AWS_SECRET_ACCESS_KEY="asecretkey"
All, except deprecated hooks:
checkov
,terraform_docs_replace
To disable color output for all hooks, set PRE_COMMIT_COLOR=never
var. Eg:
PRE_COMMIT_COLOR=never pre-commit run
checkov
hook is deprecated, please useterraform_checkov
.
Note that terraform_checkov
runs recursively during -d .
usage. That means, for example, if you change .tf
file in repo root, all existing .tf
files in repo will be checked.
You can specify custom arguments. E.g.:
- id: terraform_checkov
args:
- --args=--quiet
- --args=--skip-check CKV2_AWS_8
Check all available arguments here.
For deprecated hook you need to specify each argument separately:
- id: checkov
args: [
"-d", ".",
"--skip-check", "CKV2_AWS_8",
]
When you have multiple directories and want to run terraform_checkov
in all of them and share a single config file - use the __GIT_WORKING_DIR__
placeholder. It will be replaced by terraform_checkov
hooks with Git working directory (repo root) at run time. For example:
- id: terraform_checkov
args:
- --args=--config-file __GIT_WORKING_DIR__/.checkov.yml
infracost_breakdown
executes infracost breakdown
command and compare the estimated costs with those specified in the hook-config. infracost breakdown
parses Terraform HCL code, and calls Infracost Cloud Pricing API (remote version or self-hosted version).
Unlike most other hooks, this hook triggers once if there are any changed files in the repository.
infracost_breakdown
supports all infracost breakdown
arguments (run infracost breakdown --help
to see them). The following example only shows costs:
- id: infracost_breakdown
args:
- --args=--path=./env/dev
verbose: true # Always show costs
Note that spaces are not allowed in --args
, so you need to split it, like this:
- id: infracost_breakdown
args:
- --args=--path=./env/dev
- --args=--terraform-var-file="terraform.tfvars"
- --args=--terraform-var-file="../terraform.tfvars"
(Optionally) Define cost constrains
the hook should evaluate successfully in order to pass:
- id: infracost_breakdown
args:
- --args=--path=./env/dev
- --hook-config='.totalHourlyCost|tonumber > 0.1'
- --hook-config='.totalHourlyCost|tonumber > 1'
- --hook-config='.projects[].diff.totalMonthlyCost|tonumber != 10000'
- --hook-config='.currency == "USD"'
- id: infracost_breakdown
) is allowed.verbose: true
to see cost even when the checks are passed.jq
to process the cost estimation report returned by infracost breakdown
command--hook-config
argument should be in a jq-compatible format (e.g. .totalHourlyCost
, .totalMonthlyCost
)
To study json output produced by infracost
, run the command infracost breakdown -p PATH_TO_TF_DIR --format json
, and explore it on jqplay.org.<
, <=
, ==
, !=
, >=
, >
..totalHourlyCost
(same as .projects[].breakdown.totalHourlyCost
) - show total hourly infra cost.totalMonthlyCost
(same as .projects[].breakdown.totalMonthlyCost
) - show total monthly infra cost.projects[].diff.totalHourlyCost
- show the difference in hourly cost for the existing infra and tf plan.projects[].diff.totalMonthlyCost
- show the difference in monthly cost for the existing infra and tf plan.diffTotalHourlyCost
(for Infracost version 0.9.12 or newer) or [.projects[].diff.totalMonthlyCost | select (.!=null) | tonumber] | add
(for Infracost older than 0.9.12)Docker usage. In docker build
or docker run
command:
-e INFRACOST_API_KEY=<your token>
. By default, it is saved in ~/.config/infracost/credentials.yml
-e INFRACOST_SKIP_UPDATE_CHECK=true
to skip the Infracost update check if you use this hook as part of your CI/CD pipeline.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
.
It is possible to pass additional arguments to shell scripts when using terraform_docs
and terraform_docs_without_aggregate_type_defaults
.
It is possible to automatically:
README.md
)- id: terraform_docs
args:
- --hook-config=--path-to-file=README.md # Valid UNIX path. I.e. ../TFDOC.md or docs/README.md etc.
- --hook-config=--add-to-existing-file=true # Boolean. true or false
- --hook-config=--create-file-if-not-exist=true # Boolean. true or false
You can provide any configuration available in terraform-docs
as an argument to terraform_doc
hook, for example:
- id: terraform_docs
args:
- --args=--config=.terraform-docs.yml
Note: Avoid use recursive.enabled: true
in config file, that can cause unexpected behavior.
If you need some exotic settings, it can be done too. I.e. this one generates HCL files:
- id: terraform_docs
args:
- tfvars hcl --output-file terraform.tfvars.model .
DEPRECATED. Will be merged in terraform_docs
. See #248 for details.
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 filename that gets created/modified.
Example:
- id: terraform_docs_replace
args:
- --sort-by-required
- --dest=TEST.md
terraform_fmt
supports custom arguments so you can pass supported flags. Eg:
- id: terraform_fmt
args:
- --args=-no-color
- --args=-diff
- --args=-write=false
The hook requires Terraform 0.14 or later.
The hook invokes two operations that can be really slow:
terraform init
(in case .terraform
directory is not initialised)terraform providers lock
Both operations require downloading data from remote Terraform registries, and not all of that downloaded data or meta-data is currently being cached by Terraform.
terraform_providers_lock
supports custom arguments:
- id: terraform_providers_lock
args:
- --args=-platform=windows_amd64
- --args=-platform=darwin_amd64
It may happen that Terraform working directory (.terraform
) already exists but not in the best condition (eg, not initialized modules, wrong version of Terraform, etc.). To solve this problem, you can find and delete all .terraform
directories in your repository:
echo "
function rm_terraform {
find . \( -iname ".terraform*" ! -iname ".terraform-docs*" \) -print0 | xargs -0 rm -r
}
" >>~/.bashrc
# Reload shell and use `rm_terraform` command in the repo root
terraform_providers_lock
hook will try to reinitialize directories before running the terraform providers lock
command.
terraform_providers_lock
support passing custom arguments to its terraform init
:
- id: terraform_providers_lock
args:
- --tf-init-args=-upgrade
terraform_tflint
supports custom arguments so you can enable module inspection, enable / disable rules, etc.
Example:
- id: terraform_tflint
args:
- --args=--module
- --args=--enable-rule=terraform_documented_variables
When you have multiple directories and want to run tflint
in all of them and share a single config file, it is impractical to hard-code the path to the .tflint.hcl
file. The solution is to use the __GIT_WORKING_DIR__
placeholder which will be replaced by terraform_tflint
hooks with Git working directory (repo root) at run time. For example:
- id: terraform_tflint
args:
- --args=--config=__GIT_WORKING_DIR__/.tflint.hcl
terraform_tfsec
will consume modified files that pre-commit
passes to it, so you can perform whitelisting of directories
or files to run against via files
pre-commit flag
Example:
- id: terraform_tfsec
files: ^prd-infra/
The above will tell pre-commit to pass down files from the prd-infra/
folder
only such that the underlying tfsec
tool can run against changed files in this
directory, ignoring any other folders at the root level
To ignore specific warnings, follow the convention from the documentation.
Example:
resource "aws_security_group_rule" "my-rule" {
type = "ingress"
cidr_blocks = ["0.0.0.0/0"] #tfsec:ignore:AWS006
}
terraform_tfsec
supports custom arguments, so you can pass supported --no-color
or --format
(output), -e
(exclude checks) flags:
- id: terraform_tfsec
args:
- >
--args=--format json
--no-color
-e aws-s3-enable-bucket-logging,aws-s3-specify-public-access-block
When you have multiple directories and want to run tfsec
in all of them and share a single config file - use the __GIT_WORKING_DIR__
placeholder. It will be replaced by terraform_tfsec
hooks with Git working directory (repo root) at run time. For example:
- id: terraform_tfsec
args:
- --args=--config-file=__GIT_WORKING_DIR__/.tfsec.json
Otherwise, will be used files that located in sub-folders:
- id: terraform_tfsec
args:
- --args=--config-file=.tfsec.json
terraform_validate
supports custom arguments so you can pass supported -no-color
or -json
flags:
- id: terraform_validate
args:
- --args=-json
- --args=-no-color
terraform_validate
also supports passing custom arguments to its terraform init
:
- id: terraform_validate
args:
- --tf-init-args=-lockfile=readonly
It may happen that Terraform working directory (.terraform
) already exists but not in the best condition (eg, not initialized modules, wrong version of Terraform, etc.). To solve this problem, you can find and delete all .terraform
directories in your repository:
echo "
function rm_terraform {
find . \( -iname ".terraform*" ! -iname ".terraform-docs*" \) -print0 | xargs -0 rm -r
}
" >>~/.bashrc
# Reload shell and use `rm_terraform` command in the repo root
terraform_validate
hook will try to reinitialize them before running the terraform validate
command.
Warning: If you use Terraform workspaces, DO NOT use this workaround (details). Wait to force-init
option implementation.
terraform_validate
in a repo with Terraform module, written using Terraform 0.15+ and which uses provider configuration_aliases
(Provider Aliases Within Modules), errors out.
When running the hook against Terraform code where you have provider configuration_aliases
defined in a required_providers
configuration block, terraform will throw an error like:
Error: Provider configuration not present To work with
its original provider configuration at provider["registry.terraform.io/hashicorp/aws"]. is required, but it has been removed. This occurs when a provider configuration is removed while objects created by that provider still exist in the state. Re-add the provider configuration to destroy , after which you can remove the provider configuration again.
This is a known issue with Terraform and how providers are initialized in Terraform 0.15 and later. To work around this you can add an exclude
parameter to the configuration of terraform_validate
hook like this:
- id: terraform_validate
exclude: '^[^/]+$'
This will exclude the root directory from being processed by this hook. Then add a subdirectory like "examples" or "tests" and put an example implementation in place that defines the providers with the proper aliases, and this will give you validation of your module through the example. If instead you are using this with multiple modules in one repository you'll want to set the path prefix in the regular expression, such as exclude: modules/offendingmodule/[^/]+$
.
Alternately, you can use terraform-config-inspect and use a variant of this script to generate a providers file at runtime:
terraform-config-inspect --json . | jq -r '
[.required_providers[].aliases]
| flatten
| del(.[] | select(. == null))
| reduce .[] as $entry (
{};
.provider[$entry.name] //= [] | .provider[$entry.name] += [{"alias": $entry.alias}]
)
' | tee aliased-providers.tf.json
Save it as .generate-providers.sh
in the root of your repository and add a pre-commit
hook to run it before all other hooks, like so:
- repos:
- repo: local
hooks:
- id: generate-terraform-providers
name: generate-terraform-providers
require_serial: true
entry: .generate-providers.sh
language: script
files: \.tf(vars)?$
pass_filenames: false
- repo: https://github.com/pre-commit/pre-commit-hooks
[...]
Note: The latter method will leave an "aliased-providers.tf.json" file in your repo. You will either want to automate a way to clean this up or add it to your .gitignore
or both.
terraform_wrapper_module_for_each
generates module wrappers for Terraform modules (useful for Terragrunt where for_each
is not supported). When using this hook without arguments it will create wrappers for the root module and all modules available in "modules" directory.
You may want to customize some of the options:
--module-dir=...
- Specify a single directory to process. Values: "." (means just root module), "modules/iam-user" (a single module), or empty (means include all submodules found in "modules/*").--module-repo-org=...
- Module repository organization (e.g. "terraform-aws-modules").--module-repo-shortname=...
- Short name of the repository (e.g. "s3-bucket").--module-repo-provider=...
- Name of the repository provider (e.g. "aws" or "google").Sample configuration:
- id: terraform_wrapper_module_for_each
args:
- --args=--module-dir=. # Process only root module
- --args=--dry-run # No files will be created/updated
- --args=--verbose # Verbose output
If you use hook inside Docker:
The terraform_wrapper_module_for_each
hook attempts to determine the module's short name to be inserted into the generated README.md
files for the source
URLs. Since the container uses a bind mount at a static location, it can cause this short name to be incorrect.
If the generated name is incorrect, set them by providing the module-repo-shortname
option to the hook:
- id: terraform_wrapper_module_for_each
args:
- '--args=--module-repo-shortname=ec2-instance'
terrascan
supports custom arguments so you can pass supported flags like --non-recursive
and --policy-type
to disable recursive inspection and set the policy type respectively:
- id: terrascan
args:
- --args=--non-recursive # avoids scan errors on subdirectories without Terraform config files
- --args=--policy-type=azure
See the terrascan run -h
command line help for available options.
Use the --args=--verbose
parameter to see the rule ID in the scaning output. Usuful to skip validations.
Use --skip-rules="ruleID1,ruleID2"
parameter to skip one or more rules globally while scanning (e.g.: --args=--skip-rules="ruleID1,ruleID2"
).
Use the syntax #ts:skip=RuleID optional_comment
inside a resource to skip the rule for that resource.
Out of the box tfupdate
will pin the terraform version:
- id: tfupdate
name: Autoupdate Terraform versions
If you'd like to pin providers, etc., use custom arguments, i.e provider=PROVIDER_NAME
:
- id: tfupdate
name: Autoupdate AWS provider versions
args:
- --args=provider aws # Will be pined to latest version
- id: tfupdate
name: Autoupdate Helm provider versions
args:
- --args=provider helm
- --args=--version 2.5.0 # Will be pined to specified version
Check tfupdate
usage instructions for other available options and usage examples.
No need to pass --recursive .
as it is added automatically.
A mismatch between the Docker container's user and the local repository file ownership can cause permission issues in the repository where pre-commit
is run. The container runs as the root
user by default, and uses a tools/entrypoint.sh
script to assume a user ID and group ID if specified by the environment variable USERID
.
The recommended command to run the Docker container is:
TAG=latest
docker run -e "USERID=$(id -u):$(id -g)" -v $(pwd):/lint -w /lint ghcr.io/antonbabenko/pre-commit-terraform:$TAG run -a
which uses your current session's user ID and group ID to set the variable in the run command. Without this setting, you may find files and directories owned by root
in your local repository.
If the local repository is using a different user or group for permissions, you can modify the USERID
to the user ID and group ID needed. Do not use the username or groupname in the environment variable, as it has no meaning in the container. You can get the current directory's owner user ID and group ID from the 3rd (user) and 4th (group) columns in ls
output:
$ ls -aldn .
drwxr-xr-x 9 1000 1000 4096 Sep 1 16:23 .
This repository is managed by Anton Babenko with help from these awesome contributors:
MIT licensed. See LICENSE for full details.