pre-commit,
terraform,
git,
BASH 3.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.
[!IMPORTANT]
To build image you need to have docker buildx enabled as default builder.
Otherwise - provide TARGETOS and TARGETARCH as additional --build-arg's to docker build.
When hooks-related --build-args are not specified, only the latest version of pre-commit and terraform will be installed.
git clone git@github.com: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:
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.
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
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
Available Hooks
There are several pre-commit hooks to keep Terraform configurations (both *.tf and *.tfvars) and Terragrunt configurations (*.hcl) in a good shape:
tfupdate Update version constraints of Terraform core, providers, and modules. Hook notes
tfupdate
Check the source file to know arguments used for each hook.
Hooks usage notes and examples
Known limitations
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 hooks: Usage of environment variables in --args
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.
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 hooks: Set env vars inside hook at runtime
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
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
All hooks: Log levels
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.
Many hooks: Parallelism
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 on terragrunt_fmt and terragrunt_validate hooks
By default, parallelism is set to number of logical CPUs - 1.
If you'd like to disable parallelism, set it to 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
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.
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 (deprecated) and terraform_checkov
checkov hook is deprecated, please use terraform_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.
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 the Git working directory (repo root) at run time. For example:
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_breakdownargs:
- --args=--path=./env/devverbose: true # Always show costs
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 by infracost breakdown command
Expressions defined as --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:
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.
terraform_docs
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:
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 in v2.0.
To migrate to terraform-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_docsargs:
- --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
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: replacetemplate: |- {{/** End of file fixer */}}
Replace terraform_docs_replace hook config in .pre-commit-config.yaml with:
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 in args:
Before terraform_providers_lock, add terraform_validate hook with --hook-config=--retry-once-with-cleanup=true
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 and always-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.
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
always-regenerate-lockfile only with terraform_validate hook - regenerate lockfile from scratch. Can be useful for upgrading providers in lockfile to latest versions
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:
Warning
DEPRECATION NOTICE: This is available only in no-mode mode, which will be removed in v2.0. Please provide this keys to terraform_validate hook, which, to take effect, should be called before terraform_providers_lock
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 the Git working directory (repo root) at run time. For example:
By default, pre-commit-terraform performs directory switching into the terraform modules for you. If you want to delgate 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:
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_tfsecfiles: ^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:
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:
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 flag
Example:
- id: terraform_trivyfiles: ^prd-infra/
The above will tell pre-commit to pass down files from the prd-infra/ folder
only such that the underlying trivy 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-0124resource"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:
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_validateargs:
- --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 the terraform validate command.
Caution
If you use Terraform workspaces, DO NOT use this option (details). Consider the first option, or wait for 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 <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 of terraform_validate hook like this:
- id: terraform_validateexclude: '^[^/]+$'
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/[^/]+$.
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
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-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_eachargs:
- --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:
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: terrascanargs:
- --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.
tfupdate
Out of the box tfupdate will pin the terraform version:
- id: tfupdatename: Autoupdate Terraform versions
If you'd like to pin providers, etc., use custom arguments, i.e provider=PROVIDER_NAME:
- id: tfupdatename: Autoupdate AWS provider versionsargs:
- --args=provider aws # Will be pined to latest version
- id: tfupdatename: Autoupdate Helm provider versionsargs:
- --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.
terragrunt_providers_lock
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.
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.
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:
Download Terraform modules from private GitHub repositories
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 fileecho -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
Authors
This repository is managed by Anton Babenko with help from these awesome contributors:
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.
