Collection of git hooks for Terraform to be used with pre-commit framework
Want to contribute? Check open issues and contributing notes.
![Terramate: Automate, Orchestrate and Observe Terraform](https://raw.githubusercontent.com/antonbabenko/pre-commit-terraform/master/assets/terramate.png)
Terramate is an IaC collaboration, visibility and observability platform that empowers your team to manage Terraform and OpenTofu faster and more confidently than ever before.
If you want to support the development of pre-commit-terraform
and many other open-source projects, please become a GitHub Sponsor!
- Sponsors
- Table of content
- How to install
- Available Hooks
- Hooks usage notes and examples
- Known limitations
- All hooks: Usage of environment variables in
--args
- All hooks: Set env vars inside hook at runtime
- All hooks: Disable color output
- All hooks: Log levels
- Many hooks: Parallelism
- checkov (deprecated) and terraform_checkov
- infracost_breakdown
- terraform_docs
- terraform_docs_replace (deprecated)
- terraform_fmt
- terraform_providers_lock
- terraform_tflint
- terraform_tfsec (deprecated)
- terraform_trivy
- terraform_validate
- terraform_wrapper_module_for_each
- terrascan
- tfupdate
- terragrunt_providers_lock
- terragrunt_validate_inputs
- Docker Usage
- Github Actions
- Authors
- License
pre-commit
,terraform
oropentofu
,git
, BASH3.2.57
or newer, Internet connection (on first run), x86_64 or arm64 compatible operation system, Some hardware where this OS will run, Electricity for hardware and internet connection, Some basic physical laws, Hope that it all will work.checkov
required forterraform_checkov
hookterraform-docs
required forterraform_docs
hookterragrunt
required forterragrunt_validate
andterragrunt_valid_inputs
hooksterrascan
required forterrascan
hookTFLint
required forterraform_tflint
hookTFSec
required forterraform_tfsec
hookTrivy
required forterraform_trivy
hookinfracost
required forinfracost_breakdown
hookjq
required forterraform_validate
with--retry-once-with-cleanup
flag, and forinfracost_breakdown
hooktfupdate
required fortfupdate
hookhcledit
required forterraform_wrapper_module_for_each
hook
It is possible to set custom path to terraform
binary.
This makes it possible to use OpenTofu binary tofu
instead of terraform
.
How binary discovery works and how you can redefine it (first matched takes precedence):
- Check if per hook configuration
--hook-config=--tf-path=<path_to_binary_or_binary_name>
is set - Check if
PCT_TFPATH=<path_to_binary_or_binary_name>
environment variable is set - Check if
TERRAGRUNT_TFPATH=<path_to_binary_or_binary_name>
environment variable is set - Check if
terraform
binary can be found in the user's $PATH - Check if
tofu
binary can be found in the user's $PATH
Docker
Pull docker image with all hooks:
TAG=latest
docker pull ghcr.io/antonbabenko/pre-commit-terraform:$TAG
All available tags here.
Build from scratch:
[!IMPORTANT] To build image you need to have
docker buildx
enabled as default builder.
Otherwise - provideTARGETOS
andTARGETARCH
as additional--build-arg
's todocker build
.
When hooks-related --build-arg
s are not specified, only the latest version of pre-commit
and terraform
will be installed.
git clone [email protected]:antonbabenko/pre-commit-terraform.git
cd pre-commit-terraform
# Install the latest versions of all the tools
docker build -t pre-commit-terraform --build-arg INSTALL_ALL=true .
To install a specific version of individual tools, define it using --build-arg
arguments or set it to latest
:
docker build -t pre-commit-terraform \
--build-arg PRE_COMMIT_VERSION=latest \
--build-arg OPENTOFU_VERSION=latest \
--build-arg TERRAFORM_VERSION=1.5.7 \
--build-arg CHECKOV_VERSION=2.0.405 \
--build-arg HCLEDIT_VERSION=latest \
--build-arg INFRACOST_VERSION=latest \
--build-arg TERRAFORM_DOCS_VERSION=0.15.0 \
--build-arg TERRAGRUNT_VERSION=latest \
--build-arg TERRASCAN_VERSION=1.10.0 \
--build-arg TFLINT_VERSION=0.31.0 \
--build-arg TFSEC_VERSION=latest \
--build-arg TFUPDATE_VERSION=latest \
--build-arg TRIVY_VERSION=latest \
.
Set -e PRE_COMMIT_COLOR=never
to disable the color output in pre-commit
.
MacOS
brew install pre-commit terraform-docs tflint tfsec trivy checkov terrascan infracost tfupdate minamijoyo/hcledit/hcledit jq
Ubuntu 18.04
sudo apt update
sudo apt install -y unzip software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install -y python3.7 python3-pip
python3 -m pip install --upgrade pip
pip3 install --no-cache-dir pre-commit
python3.7 -m pip install -U checkov
curl -L "$(curl -s https://api.github.com/repos/terraform-docs/terraform-docs/releases/latest | grep -o -E -m 1 "https://.+?-linux-amd64.tar.gz")" > terraform-docs.tgz && tar -xzf terraform-docs.tgz && rm terraform-docs.tgz && 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 -m 1 "https://.+?_linux_amd64.zip")" > tflint.zip && unzip tflint.zip && rm tflint.zip && sudo mv tflint /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/aquasecurity/tfsec/releases/latest | grep -o -E -m 1 "https://.+?tfsec-linux-amd64")" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/aquasecurity/trivy/releases/latest | grep -o -E -i -m 1 "https://.+?/trivy_.+?_Linux-64bit.tar.gz")" > trivy.tar.gz && tar -xzf trivy.tar.gz trivy && rm trivy.tar.gz && sudo mv trivy /usr/bin
curl -L "$(curl -s https://api.github.com/repos/tenable/terrascan/releases/latest | grep -o -E -m 1 "https://.+?_Linux_x86_64.tar.gz")" > terrascan.tar.gz && tar -xzf terrascan.tar.gz terrascan && rm terrascan.tar.gz && sudo mv terrascan /usr/bin/ && terrascan init
sudo apt install -y jq && \
curl -L "$(curl -s https://api.github.com/repos/infracost/infracost/releases/latest | grep -o -E -m 1 "https://.+?-linux-amd64.tar.gz")" > infracost.tgz && tar -xzf infracost.tgz && rm infracost.tgz && sudo mv infracost-linux-amd64 /usr/bin/infracost && infracost auth login
curl -L "$(curl -s https://api.github.com/repos/minamijoyo/tfupdate/releases/latest | grep -o -E -m 1 "https://.+?_linux_amd64.tar.gz")" > tfupdate.tar.gz && tar -xzf tfupdate.tar.gz tfupdate && rm tfupdate.tar.gz && sudo mv tfupdate /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/minamijoyo/hcledit/releases/latest | grep -o -E -m 1 "https://.+?_linux_amd64.tar.gz")" > hcledit.tar.gz && tar -xzf hcledit.tar.gz hcledit && rm hcledit.tar.gz && sudo mv hcledit /usr/bin/
Ubuntu 20.04+
sudo apt update
sudo apt install -y unzip software-properties-common python3 python3-pip python-is-python3
python3 -m pip install --upgrade pip
pip3 install --no-cache-dir pre-commit
pip3 install --no-cache-dir checkov
curl -L "$(curl -s https://api.github.com/repos/terraform-docs/terraform-docs/releases/latest | grep -o -E -m 1 "https://.+?-linux-amd64.tar.gz")" > terraform-docs.tgz && tar -xzf terraform-docs.tgz terraform-docs && rm terraform-docs.tgz && chmod +x terraform-docs && sudo mv terraform-docs /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/tenable/terrascan/releases/latest | grep -o -E -m 1 "https://.+?_Linux_x86_64.tar.gz")" > terrascan.tar.gz && tar -xzf terrascan.tar.gz terrascan && rm terrascan.tar.gz && sudo mv terrascan /usr/bin/ && terrascan init
curl -L "$(curl -s https://api.github.com/repos/terraform-linters/tflint/releases/latest | grep -o -E -m 1 "https://.+?_linux_amd64.zip")" > tflint.zip && unzip tflint.zip && rm tflint.zip && sudo mv tflint /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/aquasecurity/tfsec/releases/latest | grep -o -E -m 1 "https://.+?tfsec-linux-amd64")" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/aquasecurity/trivy/releases/latest | grep -o -E -i -m 1 "https://.+?/trivy_.+?_Linux-64bit.tar.gz")" > trivy.tar.gz && tar -xzf trivy.tar.gz trivy && rm trivy.tar.gz && sudo mv trivy /usr/bin
sudo apt install -y jq && \
curl -L "$(curl -s https://api.github.com/repos/infracost/infracost/releases/latest | grep -o -E -m 1 "https://.+?-linux-amd64.tar.gz")" > infracost.tgz && tar -xzf infracost.tgz && rm infracost.tgz && sudo mv infracost-linux-amd64 /usr/bin/infracost && infracost auth login
curl -L "$(curl -s https://api.github.com/repos/minamijoyo/tfupdate/releases/latest | grep -o -E -m 1 "https://.+?_linux_amd64.tar.gz")" > tfupdate.tar.gz && tar -xzf tfupdate.tar.gz tfupdate && rm tfupdate.tar.gz && sudo mv tfupdate /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/minamijoyo/hcledit/releases/latest | grep -o -E -m 1 "https://.+?_linux_amd64.tar.gz")" > hcledit.tar.gz && tar -xzf hcledit.tar.gz hcledit && rm hcledit.tar.gz && sudo mv hcledit /usr/bin/
Windows 10/11
We highly recommend using WSL/WSL2 with Ubuntu and following the Ubuntu installation guide. Or use Docker.
[!IMPORTANT] We won't be able to help with issues that can't be reproduced in Linux/Mac. So, try to find a working solution and send PR before open an issue.
Otherwise, you can follow this gist:
Ensure your PATH environment variable looks for bash.exe
in C:\Program Files\Git\bin
(the one present in C:\Windows\System32\bash.exe
does not work with pre-commit.exe
)
For checkov
, you may need to also set your PYTHONPATH
environment variable with the path to your Python modules.
E.g. C:\Users\USERNAME\AppData\Local\Programs\Python\Python39\Lib\site-packages
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):
Tip
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. DEPRECATED, use terraform_trivy . Hook notes |
tfsec |
terraform_trivy |
Trivy static analysis of terraform templates to spot potential security issues. Hook notes | trivy |
terraform_validate |
Validates all Terraform configuration files. Hook notes | jq , only for --retry-once-with-cleanup flag |
terragrunt_fmt |
Reformat all Terragrunt configuration files (*.hcl ) to a canonical format. |
terragrunt |
terragrunt_validate |
Validates all Terragrunt configuration files (*.hcl ) |
terragrunt |
terragrunt_validate_inputs |
Validates Terragrunt unused and undefined inputs (*.hcl ) |
|
terragrunt_providers_lock |
Generates .terraform.lock.hcl files using Terragrunt. |
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.
Terraform operates on a per-dir basis, while pre-commit
framework only supports files and files that exist. This means if you only remove the TF-related file without any other changes in the same dir, checks will be skipped. Example and details here.
All, except deprecated hooks:
checkov
,terraform_docs_replace
You can use environment variables for the --args
section.
Important
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.
Important
Variable values are exported verbatim:
- No interpolation or expansion are applied
- The enclosing double quotes are removed if they are provided
Config example:
- id: terraform_validate
args:
- --env-vars=AWS_DEFAULT_REGION="us-west-2"
- --env-vars=AWS_PROFILE="my-aws-cli-profile"
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
In case you need to debug hooks, you can set PCT_LOG=trace
.
For example:
PCT_LOG=trace pre-commit run -a
Less verbose log levels will be implemented in #562.
All, except deprecated hooks:
checkov
,terraform_docs_replace
and hooks which can't be paralleled this way:infracost_breakdown
,terraform_wrapper_module_for_each
.
Also, there's a chance that parallelism have no effect onterragrunt_fmt
andterragrunt_validate
hooks
By default, parallelism is set to number of logical CPUs - 1
.
If you'd like to disable parallelism, set it to 1
- id: terragrunt_validate
args:
- --hook-config=--parallelism-limit=1
In the same way you can set it to any positive integer.
If you'd like to set parallelism value relative to number of CPU logical cores - provide valid Bash arithmetic expression and use CPU
as a reference to the number of CPU logical cores
- id: terraform_providers_lock
args:
- --hook-config=--parallelism-limit=CPU*4
Tip
Info useful for parallelism fine-tunning
Tests below were run on repo with 45 Terraform dirs on laptop with 16 CPUs, SSD and 1Gbit/s network. Laptop was slightly used in the process.
Observed results may vary greatly depending on your repo structure, machine characteristics and their usage.
If during fine-tuning you'll find that your results are very different from provided below and you think that this data could help someone else - feel free to send PR.
Hook | Most used resource | Comparison of optimization results / Notes |
---|---|---|
terraform_checkov | CPU heavy | - |
terraform_fmt | CPU heavy | - |
terraform_providers_lock (3 platforms,--mode=always-regenerate-lockfile ) |
Network & Disk heavy | defaults (CPU-1) - 3m 39s; CPU*2 - 3m 19s; CPU*4 - 2m 56s |
terraform_tflint | CPU heavy | - |
terraform_tfsec | CPU heavy | - |
terraform_trivy | CPU moderate | defaults (CPU-1) - 32s; CPU*2 - 30s; CPU*4 - 31s |
terraform_validate (t validate only) | CPU heavy | - |
terraform_validate (t init + t validate) | Network & Disk heavy, CPU moderate | defaults (CPU-1) - 1m 30s; CPU*2 - 1m 25s; CPU*4 - 1m 41s |
terragrunt_fmt | CPU heavy | N/A? need more info from TG users |
terragrunt_validate | CPU heavy | N/A? need more info from TG users |
terrascan | CPU moderate-heavy | defaults (CPU-1) - 8s; CPU*2 - 6s |
tfupdate | Disk/Network? | too quick in any settings. More info needed |
args:
- --hook-config=--parallelism-ci-cpu-cores=N
If you don't see code above in your pre-commit-config.yaml
or logs - you don't need it.
--parallelism-ci-cpu-cores
used only in edge cases and is ignored in other situations. Check out its usage in hooks/_common.sh
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 the 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 byterraform_checkov
hooks with the 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 allinfracost breakdown
arguments (runinfracost breakdown --help
to see them). The following example only shows costs:- id: infracost_breakdown args: - --args=--path=./env/dev verbose: true # Always show costs
Output
Running in "env/dev" Summary: { "unsupportedResourceCounts": { "aws_sns_topic_subscription": 1 } } Total Monthly Cost: 86.83 USD Total Monthly Cost (diff): 86.83 USD
-
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 constraints
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"'
Output
Running in "env/dev" Passed: .totalHourlyCost|tonumber > 0.1 0.11894520547945205 > 0.1 Failed: .totalHourlyCost|tonumber > 1 0.11894520547945205 > 1 Passed: .projects[].diff.totalMonthlyCost|tonumber !=10000 86.83 != 10000 Passed: .currency == "USD" "USD" == "USD" Summary: { "unsupportedResourceCounts": { "aws_sns_topic_subscription": 1 } } Total Monthly Cost: 86.83 USD Total Monthly Cost (diff): 86.83 USD
- Only one path per one hook (
- id: infracost_breakdown
) is allowed. - Set
verbose: true
to see cost even when the checks are passed. - Hook uses
jq
to process the cost estimation report returned byinfracost breakdown
command - Expressions defined as
--hook-config
argument should be in a jq-compatible format (e.g..totalHourlyCost
,.totalMonthlyCost
) To study json output produced byinfracost
, run the commandinfracost breakdown -p PATH_TO_TF_DIR --format json
, and explore it on jqplay.org. - Supported comparison operators:
<
,<=
,==
,!=
,>=
,>
. - Most useful paths and checks:
.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)
- Only one path per one hook (
-
Docker usage. In
docker build
ordocker run
command:- You need to provide Infracost API key via
-e INFRACOST_API_KEY=<your token>
. By default, it is saved in~/.config/infracost/credentials.yml
- Set
-e INFRACOST_SKIP_UPDATE_CHECK=true
to skip the Infracost update check if you use this hook as part of your CI/CD pipeline.
- You need to provide Infracost API key via
-
terraform_docs
andterraform_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
andterraform_docs_without_aggregate_type_defaults
. -
It is possible to automatically:
-
create a documentation file
-
extend existing documentation file by appending markers to the end of the file (see item 1 above)
-
use different filename for the documentation (default is
README.md
) -
use the same insertion markers as
terraform-docs
by default. It will be default inv2.0
.
To migrate toterraform-docs
insertion markers, run in repo root:grep -rl 'BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/BEGIN_TF_DOCS/g' grep -rl 'END OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs sed -i 's/END OF PRE-COMMIT-TERRAFORM DOCS HOOK/END_TF_DOCS/g'
- 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 - --hook-config=--use-standard-markers=true # Boolean. Defaults in v1.x to false. Set to true for compatibility with terraform-docs
-
-
You can provide any configuration available in
terraform-docs
as an argument toterraform_doc
hook, for example:- id: terraform_docs args: - --args=--config=.terraform-docs.yml
Warning
Avoid userecursive.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
.
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.
To replicate functionality in terraform_docs
hook:
-
Create
.terraform-docs.yml
in the repo root with the following content:formatter: "markdown" output: file: "README.md" mode: replace template: |- {{/** End of file fixer */}}
-
Replace
terraform_docs_replace
hook config in.pre-commit-config.yaml
with:- id: terraform_docs args: - --args=--config=.terraform-docs.yml
-
terraform_fmt
supports custom arguments so you can pass supported flags. Eg:- id: terraform_fmt args: - --args=-no-color - --args=-diff - --args=-write=false
Note
The hook requires Terraform 0.14 or later.
Note
The hook can invoke terraform providers lock
that can be really slow and requires fetching metadata from remote Terraform registries - not all of that metadata is currently being cached by Terraform.
Note
Read this if you used this hook before v1.80.0 | Planned breaking changes in v2.0
We introduced `--mode` flag for this hook. If you'd like to continue using this hook as before, please:
- Specify
--hook-config=--mode=always-regenerate-lockfile
inargs:
- Before
terraform_providers_lock
, addterraform_validate
hook with--hook-config=--retry-once-with-cleanup=true
- Move
--tf-init-args=
toterraform_validate
hook
In the end, you should get config like this:
- id: terraform_validate
args:
- --hook-config=--retry-once-with-cleanup=true
# - --tf-init-args=-upgrade
- id: terraform_providers_lock
args:
- --hook-config=--mode=always-regenerate-lockfile
Why? When v2.x will be introduced - the default mode will be changed, probably, to only-check-is-current-lockfile-cross-platform
.
You can check available modes for hook below.
-
The hook can work in a few different modes:
only-check-is-current-lockfile-cross-platform
with and without terraform_validate hook andalways-regenerate-lockfile
- only with terraform_validate hook.-
only-check-is-current-lockfile-cross-platform
without terraform_validate - only checks that lockfile has all required SHAs for all providers already added to lockfile.- id: terraform_providers_lock args: - --hook-config=--mode=only-check-is-current-lockfile-cross-platform
-
only-check-is-current-lockfile-cross-platform
with terraform_validate hook - make up-to-date lockfile by adding/removing providers and only then check that lockfile has all required SHAs.Important Next
terraform_validate
flag requires additional dependency to be installed:jq
. Also, it could run another slow and time consuming command -terraform init
- id: terraform_validate args: - --hook-config=--retry-once-with-cleanup=true - id: terraform_providers_lock args: - --hook-config=--mode=only-check-is-current-lockfile-cross-platform
-
always-regenerate-lockfile
only with terraform_validate hook - regenerate lockfile from scratch. Can be useful for upgrading providers in lockfile to latest versions- id: terraform_validate args: - --hook-config=--retry-once-with-cleanup=true - --tf-init-args=-upgrade - id: terraform_providers_lock args: - --hook-config=--mode=always-regenerate-lockfile
-
-
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 theterraform providers lock
command. -
terraform_providers_lock
support passing custom arguments to itsterraform init
:Warning
DEPRECATION NOTICE: This is available only inno-mode
mode, which will be removed in v2.0. Please provide this keys toterraform_validate
hook, which, to take effect, should be called beforeterraform_providers_lock
- 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 byterraform_tflint
hooks with the Git working directory (repo root) at run time. For example:- id: terraform_tflint args: - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl
-
By default, pre-commit-terraform performs directory switching into the terraform modules for you. If you want to delegate the directory changing to the binary - this will allow tflint to determine the full paths for error/warning messages, rather than just module relative paths. Note: this requires
tflint>=0.44.0
. For example:- id: terraform_tflint args: - --hook-config=--delegate-chdir
DEPRECATED. tfsec was replaced by trivy, so please use terraform_trivy
.
-
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 flagExample:
- 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 underlyingtfsec
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 byterraform_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_trivy
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 flagExample:
- id: terraform_trivy files: ^prd-infra/
The above will tell pre-commit to pass down files from the
prd-infra/
folder only such that the underlyingtrivy
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:
#trivy:ignore:AVD-AWS-0107 #trivy:ignore:AVD-AWS-0124 resource "aws_security_group_rule" "my-rule" { type = "ingress" cidr_blocks = ["0.0.0.0/0"] }
-
terraform_trivy
supports custom arguments, so you can pass supported--format
(output),--skip-dirs
(exclude directories) and other flags:- id: terraform_trivy args: - --args=--format=json - --args=--skip-dirs="**/.terraform"
-
When you have multiple directories and want to run
trivy
in all of them and share a single config file - use the__GIT_WORKING_DIR__
placeholder. It will be replaced byterraform_trivy
hooks with Git working directory (repo root) at run time. For example:- id: terraform_trivy args: - --args=--ignorefile=__GIT_WORKING_DIR__/.trivyignore
Important
If you use TF_PLUGIN_CACHE_DIR
, we recommend enabling --hook-config=--retry-once-with-cleanup=true
or disabling parallelism (--hook-config=--parallelism-limit=1
) to avoid race conditions when terraform init
writes to it.
-
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 itsterraform init
:- id: terraform_validate args: - --tf-init-args=-upgrade - --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 delete broken.terraform
directories in your repository:Option 1
- id: terraform_validate args: - --hook-config=--retry-once-with-cleanup=true # Boolean. true or false
Important
The flag requires additional dependency to be installed:jq
.Note
Reinit can be very slow and require downloading data from remote Terraform registries, and not all of that downloaded data or meta-data is currently being cached by Terraform.When
--retry-once-with-cleanup=true
, in each failed directory the cached modules and providers from the.terraform
directory will be deleted, before retrying once more. To avoid unnecessary deletion of this directory, the cleanup and retry will only happen if Terraform produces any of the following error messages:- "Missing or corrupted provider plugins"
- "Module source has changed"
- "Module version requirements have changed"
- "Module not installed"
- "Could not load plugin"
Warning
When using--retry-once-with-cleanup=true
, problematic.terraform/modules/
and.terraform/providers/
directories will be recursively deleted without prompting for consent. Other files and directories will not be affected, such as the.terraform/environment
file.Option 2
An alternative solution is to 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 theterraform validate
command.Caution
If you use Terraform workspaces, DO NOT use this option (details). Consider the first option, or wait forforce-init
option implementation. -
terraform_validate
in a repo with Terraform module, written using Terraform 0.15+ and which uses providerconfiguration_aliases
(Provider Aliases Within Modules), errors out.When running the hook against Terraform code where you have provider
configuration_aliases
defined in arequired_providers
configuration block, terraform will throw an error like:Error: Provider configuration not present To work with
<resource>
its original provider configuration at provider["registry.terraform.io/hashicorp/aws"].<provider_alias>
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<resource>
, 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 ofterraform_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 apre-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 [...]
Tip
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 scanning output. Useful 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.
Tip
Use this hook only in infrastructure repos managed solely by terragrunt
and do not mix with terraform_providers_lock
to avoid conflicts.
Warning
Hook may be very slow, because terragrunt invokes t init
under the hood.
Hook produces same results as terraform_providers_lock
, but for terragrunt root modules.
It invokes terragrunt providers lock
under the hood and terragrunt does its' own magic for handling lock files.
- id: terragrunt_providers_lock
name: Terragrunt providers lock
args:
- --args=-platform=darwin_arm64
- --args=-platform=darwin_amd64
- --args=-platform=linux_amd64
Validates Terragrunt unused and undefined inputs. This is useful for keeping configs clean when module versions change or if configs are copied.
See the Terragrunt docs for more details.
Example:
- id: terragrunt_validate_inputs
name: Terragrunt validate inputs
args:
# Optionally check for unused inputs
- --args=--terragrunt-strict-validate
Note
This hook requires authentication to a given account if defined by config to work properly. For example, if you use a third-party tool to store AWS credentials like aws-vault
you must be authenticated first.
See docs for the iam_role attribute and --terragrunt-iam-role flag for more.
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 .
If you use a private Git repository as your Terraform module source, you are required to authenticate to GitHub using a Personal Access Token.
When running pre-commit on Docker, both locally or on CI, you need to configure the ~/.netrc file, which contains login and initialization information used by the auto-login process.
This can be achieved by firstly creating the ~/.netrc
file including your GITHUB_PAT
and GITHUB_SERVER_HOSTNAME
# set GH values (replace with your own values)
GITHUB_PAT=ghp_bl481aBlabl481aBla
GITHUB_SERVER_HOSTNAME=github.com
# create .netrc file
echo -e "machine $GITHUB_SERVER_HOSTNAME\n\tlogin $GITHUB_PAT" >> ~/.netrc
The ~/.netrc
file will look similar to the following:
machine github.com
login ghp_bl481aBlabl481aBla
Tip
The value of GITHUB_SERVER_HOSTNAME
can also refer to a GitHub Enterprise server (i.e. github.my-enterprise.com
).
Finally, you can execute docker run
with an additional volume mount so that the ~/.netrc
is accessible within the container
# run pre-commit-terraform with docker
# adding volume for .netrc file
# .netrc needs to be in /root/ dir
docker run --rm -e "USERID=$(id -u):$(id -g)" -v ~/.netrc:/root/.netrc -v $(pwd):/lint -w /lint ghcr.io/antonbabenko/pre-commit-terraform:latest run -a
You can use this hook in your GitHub Actions workflow togehther with pre-commit. To easy up dependency management, you can use the managed docker image within your workflow. Make sure to set the image tag to the version you want to use.
In this repository's pre-commit workflow file we run pre-commit without the container image.
Here is an example that use the container image, includes caching of pre-commit dependencies and uses the pre-commit
command to run the checks (but fixes will be not automatically push back to your branch, when it possible):
name: pre-commit-terraform
on:
pull_request:
jobs:
pre-commit:
runs-on: ubuntu-latest
container:
image: ghcr.io/antonbabenko/pre-commit-terraform:latest # latest used here for simplicity, not recommended
defaults:
run:
shell: bash
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
ref: ${{ github.event.pull_request.head.sha }}
- run: |
git config --global --add safe.directory $GITHUB_WORKSPACE
git fetch --no-tags --prune --depth=1 origin +refs/heads/*:refs/remotes/origin/*
- name: Get changed files
id: file_changes
run: |
export DIFF=$(git diff --name-only origin/${{ github.base_ref }} ${{ github.sha }})
echo "Diff between ${{ github.base_ref }} and ${{ github.sha }}"
echo "files=$( echo "$DIFF" | xargs echo )" >> $GITHUB_OUTPUT
- name: fix tar dependency in alpine container image
run: |
apk --no-cache add tar
# check python modules installed versions
python -m pip freeze --local
- name: Cache pre-commit since we use pre-commit from container
uses: actions/cache@v4
with:
path: ~/.cache/pre-commit
key: pre-commit-3|${{ hashFiles('.pre-commit-config.yaml') }}
- name: Execute pre-commit
run: |
pre-commit run --color=always --show-diff-on-failure --files ${{ steps.file_changes.outputs.files }}
This repository is managed by Anton Babenko with help from these awesome contributors:
MIT licensed. See LICENSE for full details.
- Russia has illegally annexed Crimea in 2014 and brought the war in Donbas followed by full-scale invasion of Ukraine in 2022.
- Russia has brought sorrow and devastations to millions of Ukrainians, killed hundreds of innocent people, damaged thousands of buildings, and forced several million people to flee.
- Putin khuylo!