diff --git a/README.md b/README.md index 78740b8be..789d8da92 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,36 @@ # Collection of git hooks for Terraform to be used with [pre-commit framework](http://pre-commit.com/) -[![Github tag](https://img.shields.io/github/tag/antonbabenko/pre-commit-terraform.svg)](https://github.com/antonbabenko/pre-commit-terraform/releases) ![maintenance status](https://img.shields.io/maintenance/yes/2025.svg) [![Help Contribute to Open Source](https://www.codetriage.com/antonbabenko/pre-commit-terraform/badges/users.svg)](https://www.codetriage.com/antonbabenko/pre-commit-terraform) -[![CI/CD Badge]][CI/CD] -[![Codecov Badge]][Codecov] -[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/antonbabenko/pre-commit-terraform/badge)](https://scorecard.dev/viewer/?uri=github.com/antonbabenko/pre-commit-terraform) - -[CI/CD Badge]: -https://github.com/antonbabenko/pre-commit-terraform/actions/workflows/ci-cd.yml/badge.svg?branch=master -[CI/CD]: -https://github.com/antonbabenko/pre-commit-terraform/actions/workflows/ci-cd.yml - -[Codecov Badge]: -https://codecov.io/gh/antonbabenko/pre-commit-terraform/branch/master/graph/badge.svg?flag=pytest -[Codecov]: https://app.codecov.io/gh/antonbabenko/pre-commit-terraform?flags[]=pytest - -[![SWUbanner](https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct.svg)](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md) - -Want to contribute? Check [open issues](https://github.com/antonbabenko/pre-commit-terraform/issues?q=label%3A%22good+first+issue%22+is%3Aopen+sort%3Aupdated-desc) and [contributing notes](/.github/CONTRIBUTING.md). +[![Latest Github tag]](https://github.com/antonbabenko/pre-commit-terraform/releases) +![Maintenance status](https://img.shields.io/maintenance/yes/2025.svg) +[![Codetriage - Help Contribute to Open Source Badge]](https://www.codetriage.com/antonbabenko/pre-commit-terraform) +[![GHA Tests CI/CD Badge]](https://github.com/antonbabenko/pre-commit-terraform/actions/workflows/ci-cd.yml) +[![Codecov pytest Badge]](https://app.codecov.io/gh/antonbabenko/pre-commit-terraform?flags[]=pytest) +[![OpenSSF Scorecard Badge]](https://scorecard.dev/viewer/?uri=github.com/antonbabenko/pre-commit-terraform) + +[![StandWithUkraine Banner]](https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md) + +Want to contribute? +Check [open issues](https://github.com/antonbabenko/pre-commit-terraform/issues?q=label%3A%22good+first+issue%22+is%3Aopen+sort%3Aupdated-desc) +and [contributing notes](/.github/CONTRIBUTING.md). + +[Latest Github tag]: https://img.shields.io/github/tag/antonbabenko/pre-commit-terraform.svg +[Codetriage - Help Contribute to Open Source Badge]: https://www.codetriage.com/antonbabenko/pre-commit-terraform/badges/users.svg +[GHA Tests CI/CD Badge]: https://github.com/antonbabenko/pre-commit-terraform/actions/workflows/ci-cd.yml/badge.svg?branch=master +[Codecov Pytest Badge]: https://codecov.io/gh/antonbabenko/pre-commit-terraform/branch/master/graph/badge.svg?flag=pytest +[OpenSSF Scorecard Badge]: https://api.scorecard.dev/projects/github.com/antonbabenko/pre-commit-terraform/badge +[StandWithUkraine Banner]: https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct.svg ## Sponsors
-Terramate: Automate, Orchestrate and Observe Terraform + + Terramate: Automate, Orchestrate and Observe Terraform + -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. +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](https://github.com/antonbabenko/terraform-aws-devops), please become a [GitHub Sponsor](https://github.com/sponsors/antonbabenko)! @@ -66,7 +71,7 @@ If you want to support the development of `pre-commit-terraform` and [many other * [Docker Usage](#docker-usage) * [File Permissions](#file-permissions) * [Download Terraform modules from private GitHub repositories](#download-terraform-modules-from-private-github-repositories) -* [Github Actions](#github-actions) +* [GitHub Actions](#github-actions) * [Authors](#authors) * [License](#license) * [Additional information for users from Russia and Belarus](#additional-information-for-users-from-russia-and-belarus) @@ -74,29 +79,29 @@ If you want to support the development of `pre-commit-terraform` and [many other ## How to install ### 1. Install dependencies - + * [`pre-commit`](https://pre-commit.com/#install), [`terraform`](https://www.terraform.io/downloads.html) or [`opentofu`](https://opentofu.org/docs/intro/install/), [`git`](https://git-scm.com/downloads), [BASH `3.2.57` or newer](https://www.gnu.org/software/bash/#download), Internet connection (on first run), - x86_64 or arm64 compatible operation system, + x86_64 or arm64 compatible operating 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`](https://github.com/bridgecrewio/checkov) required for `terraform_checkov` hook -* [`terraform-docs`](https://github.com/terraform-docs/terraform-docs) 0.12.0+ required for `terraform_docs` hook -* [`terragrunt`](https://terragrunt.gruntwork.io/docs/getting-started/install/) required for `terragrunt_validate` and `terragrunt_valid_inputs` hooks -* [`terrascan`](https://github.com/tenable/terrascan) required for `terrascan` hook -* [`TFLint`](https://github.com/terraform-linters/tflint) required for `terraform_tflint` hook -* [`TFSec`](https://github.com/liamg/tfsec) required for `terraform_tfsec` hook -* [`Trivy`](https://github.com/aquasecurity/trivy) required for `terraform_trivy` hook -* [`infracost`](https://github.com/infracost/infracost) required for `infracost_breakdown` hook -* [`jq`](https://github.com/stedolan/jq) required for `terraform_validate` with `--retry-once-with-cleanup` flag, and for `infracost_breakdown` hook -* [`tfupdate`](https://github.com/minamijoyo/tfupdate) required for `tfupdate` hook -* [`hcledit`](https://github.com/minamijoyo/hcledit) required for `terraform_wrapper_module_for_each` hook +* [`checkov`][checkov repo] required for `terraform_checkov` hook +* [`terraform-docs`][terraform-docs repo] 0.12.0+ required for `terraform_docs` hook +* [`terragrunt`][terragrunt repo] required for `terragrunt_validate` and `terragrunt_valid_inputs` hooks +* [`terrascan`][terrascan repo] required for `terrascan` hook +* [`TFLint`][tflint repo] required for `terraform_tflint` hook +* [`TFSec`][tfsec repo] required for `terraform_tfsec` hook +* [`Trivy`][trivy repo] required for `terraform_trivy` hook +* [`infracost`][infracost repo] required for `infracost_breakdown` hook +* [`jq`][jq repo] required for `terraform_validate` with `--retry-once-with-cleanup` flag, and for `infracost_breakdown` hook +* [`tfupdate`][tfupdate repo] required for `tfupdate` hook +* [`hcledit`][hcledit repo] required for `terraform_wrapper_module_for_each` hook #### 1.1 Custom Terraform binaries and OpenTofu support @@ -293,26 +298,26 @@ docker run --rm --entrypoint cat ghcr.io/antonbabenko/pre-commit-terraform:$TAG There are several [pre-commit](https://pre-commit.com/) hooks to keep Terraform configurations (both `*.tf` and `*.tfvars`) and Terragrunt configurations (`*.hcl`) in a good shape: -| Hook name | Description | Dependencies
[Install instructions here](#1-install-dependencies) | -| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| `checkov` and `terraform_checkov` | [checkov](https://github.com/bridgecrewio/checkov) static analysis of terraform templates to spot potential security issues. [Hook notes](#checkov-deprecated-and-terraform_checkov) | `checkov`
Ubuntu deps: `python3`, `python3-pip` | -| `infracost_breakdown` | Check how much your infra costs with [infracost](https://github.com/infracost/infracost). [Hook notes](#infracost_breakdown) | `infracost`, `jq`, [Infracost API key](https://www.infracost.io/docs/#2-get-api-key) | -| `terraform_docs` | Inserts input and output documentation into `README.md`. Recommended. [Hook notes](#terraform_docs) | `terraform-docs` | -| `terraform_docs_replace` | Runs `terraform-docs` and pipes the output directly to README.md. **DEPRECATED**, see [#248](https://github.com/antonbabenko/pre-commit-terraform/issues/248). [Hook notes](#terraform_docs_replace-deprecated) | `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-docs` | -| `terraform_fmt` | Reformat all Terraform configuration files to a canonical format. [Hook notes](#terraform_fmt) | - | -| `terraform_providers_lock` | Updates provider signatures in [dependency lock files](https://www.terraform.io/docs/cli/commands/providers/lock.html). [Hook notes](#terraform_providers_lock) | - | -| `terraform_tflint` | Validates all Terraform configuration files with [TFLint](https://github.com/terraform-linters/tflint). [Available TFLint rules](https://github.com/terraform-linters/tflint-ruleset-terraform/blob/main/docs/rules/README.md). [Hook notes](#terraform_tflint). | `tflint` | -| `terraform_tfsec` | [TFSec](https://github.com/aquasecurity/tfsec) static analysis of terraform templates to spot potential security issues. **DEPRECATED**, use `terraform_trivy`. [Hook notes](#terraform_tfsec-deprecated) | `tfsec` | -| `terraform_trivy` | [Trivy](https://github.com/aquasecurity/trivy) static analysis of terraform templates to spot potential security issues. [Hook notes](#terraform_trivy) | `trivy` | -| `terraform_validate` | Validates all Terraform configuration files. [Hook notes](#terraform_validate) | `jq`, only for `--retry-once-with-cleanup` flag | -| `terragrunt_fmt` | Reformat all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) to a canonical format. | `terragrunt` | -| `terragrunt_validate` | Validates all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) | `terragrunt` | -| `terragrunt_validate_inputs` | Validates [Terragrunt](https://github.com/gruntwork-io/terragrunt) unused and undefined inputs (`*.hcl`) -| `terragrunt_providers_lock` | Generates `.terraform.lock.hcl` files using [Terragrunt](https://github.com/gruntwork-io/terragrunt). | `terragrunt` | -| `terraform_wrapper_module_for_each` | Generates Terraform wrappers with `for_each` in module. [Hook notes](#terraform_wrapper_module_for_each) | `hcledit` | -| `terrascan` | [terrascan](https://github.com/tenable/terrascan) Detect compliance and security violations. [Hook notes](#terrascan) | `terrascan` | -| `tfupdate` | [tfupdate](https://github.com/minamijoyo/tfupdate) Update version constraints of Terraform core, providers, and modules. [Hook notes](#tfupdate) | `tfupdate` | +| Hook name | Description | Dependencies
[Install instructions here](#1-install-dependencies) | +| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | +| `checkov` and `terraform_checkov` | [checkov][checkov repo] static analysis of terraform templates to spot potential security issues. [Hook notes](#checkov-deprecated-and-terraform_checkov) | `checkov`
Ubuntu deps: `python3`, `python3-pip` | +| `infracost_breakdown` | Check how much your infra costs with [infracost][infracost repo]. [Hook notes](#infracost_breakdown) | `infracost`, `jq`, [Infracost API key](https://www.infracost.io/docs/#2-get-api-key) | +| `terraform_docs` | Inserts input and output documentation into `README.md`. [Hook notes](#terraform_docs) | `terraform-docs` | +| `terraform_docs_replace` | Runs `terraform-docs` and pipes the output directly to README.md. **DEPRECATED**, see [#248](https://github.com/antonbabenko/pre-commit-terraform/issues/248). [Hook notes](#terraform_docs_replace-deprecated) | `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-docs` | +| `terraform_fmt` | Reformat all Terraform configuration files to a canonical format. [Hook notes](#terraform_fmt) | - | +| `terraform_providers_lock` | Updates provider signatures in [dependency lock files](https://www.terraform.io/docs/cli/commands/providers/lock.html). [Hook notes](#terraform_providers_lock) | - | +| `terraform_tflint` | Validates all Terraform configuration files with [TFLint][tflint repo]. [Available TFLint rules](https://github.com/terraform-linters/tflint-ruleset-terraform/blob/main/docs/rules/README.md). [Hook notes](#terraform_tflint). | `tflint` | +| `terraform_tfsec` | [TFSec][tfsec repo] static analysis of terraform templates to spot potential security issues. **DEPRECATED**, use `terraform_trivy`. [Hook notes](#terraform_tfsec-deprecated) | `tfsec` | +| `terraform_trivy` | [Trivy][trivy repo] static analysis of terraform templates to spot potential security issues. [Hook notes](#terraform_trivy) | `trivy` | +| `terraform_validate` | Validates all Terraform configuration files. [Hook notes](#terraform_validate) | `jq`, only for `--retry-once-with-cleanup` flag | +| `terragrunt_fmt` | Reformat all [Terragrunt][terragrunt repo] configuration files (`*.hcl`) to a canonical format. | `terragrunt` | +| `terragrunt_validate` | Validates all [Terragrunt][terragrunt repo] configuration files (`*.hcl`) | `terragrunt` | +| `terragrunt_validate_inputs` | Validates [Terragrunt][terragrunt repo] unused and undefined inputs (`*.hcl`) | | +| `terragrunt_providers_lock` | Generates `.terraform.lock.hcl` files using [Terragrunt][terragrunt repo]. | `terragrunt` | +| `terraform_wrapper_module_for_each` | Generates Terraform wrappers with `for_each` in module. [Hook notes](#terraform_wrapper_module_for_each) | `hcledit` | +| `terrascan` | [terrascan][terrascan repo] Detect compliance and security violations. [Hook notes](#terrascan) | `terrascan` | +| `tfupdate` | [tfupdate][tfupdate repo] Update version constraints of Terraform core, providers, and modules. [Hook notes](#tfupdate) | `tfupdate` | Check the [source file](https://github.com/antonbabenko/pre-commit-terraform/blob/master/.pre-commit-hooks.yaml) to know arguments used for each hook. @@ -465,15 +470,15 @@ Note that `terraform_checkov` runs recursively during `-d .` usage. That means, Check all available arguments [here](https://www.checkov.io/2.Basics/CLI%20Command%20Reference.html). -For deprecated hook you need to specify each argument separately: + For deprecated hook you need to specify each argument separately: -```yaml -- id: checkov - args: [ - "-d", ".", - "--skip-check", "CKV2_AWS_8", - ] -``` + ```yaml + - id: checkov + args: [ + "-d", ".", + "--skip-check", "CKV2_AWS_8", + ] + ``` 2. 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: @@ -577,7 +582,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files ### terraform_docs -1. `terraform_docs` and `terraform_docs_without_aggregate_type_defaults` will insert/update documentation generated by [terraform-docs](https://github.com/terraform-docs/terraform-docs) framed by markers: +1. `terraform_docs` and `terraform_docs_without_aggregate_type_defaults` will insert/update documentation generated by [terraform-docs][terraform-docs repo] framed by markers: ```txt @@ -672,7 +677,7 @@ To replicate functionality in `terraform_docs` hook: ```yaml - id: terraform_docs - args: + args: - --args=--config=.terraform-docs.yml ``` @@ -762,8 +767,7 @@ To replicate functionality in `terraform_docs` hook: - --hook-config=--mode=always-regenerate-lockfile ``` - -3. `terraform_providers_lock` supports custom arguments: +2. `terraform_providers_lock` supports custom arguments: ```yaml - id: terraform_providers_lock @@ -772,7 +776,7 @@ To replicate functionality in `terraform_docs` hook: - --args=-platform=darwin_amd64 ``` -4. 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: +3. 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: ```bash echo " @@ -786,7 +790,7 @@ To replicate functionality in `terraform_docs` hook: `terraform_providers_lock` hook will try to reinitialize directories before running the `terraform providers lock` command. -3. `terraform_providers_lock` support passing custom arguments to its `terraform init`: +4. `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`](#terraform_validate) hook, which, to take effect, should be called before `terraform_providers_lock` @@ -823,8 +827,8 @@ To replicate functionality in `terraform_docs` hook: ```yaml - id: terraform_tflint - args: - - --hook-config=--delegate-chdir + args: + - --hook-config=--delegate-chdir ``` @@ -923,9 +927,9 @@ To replicate functionality in `terraform_docs` hook: ```yaml - id: terraform_trivy - args: - - --args=--format=json - - --args=--skip-dirs="**/.terraform" + args: + - --args=--format=json + - --args=--skip-dirs="**/.terraform" ``` 4. 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 by `terraform_trivy` hooks with Git working directory (repo root) at run time. For example: @@ -1005,7 +1009,7 @@ To replicate functionality in `terraform_docs` hook: > **Caution** > If you use Terraform workspaces, DO NOT use this option ([details](https://github.com/antonbabenko/pre-commit-terraform/issues/203#issuecomment-918791847)). Consider the first option, or wait for [`force-init`](https://github.com/antonbabenko/pre-commit-terraform/issues/224) option implementation. -1. `terraform_validate` in a repo with Terraform module, written using Terraform 0.15+ and which uses provider `configuration_aliases` ([Provider Aliases Within Modules](https://www.terraform.io/language/modules/develop/providers#provider-aliases-within-modules)), errors out. +4. `terraform_validate` in a repo with Terraform module, written using Terraform 0.15+ and which uses provider `configuration_aliases` ([Provider Aliases Within Modules](https://www.terraform.io/language/modules/develop/providers#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: @@ -1043,15 +1047,14 @@ To replicate functionality in `terraform_docs` hook: - 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 + 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** @@ -1234,13 +1237,16 @@ Finally, you can execute `docker run` with an additional volume mount so that th 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 ``` -## Github Actions +## GitHub Actions -You can use this hook in your GitHub Actions workflow togehther with [pre-commit](https://pre-commit.com). To easy up dependency management, you can use the managed [docker image](#docker-usage) within your workflow. Make sure to set the image tag to the version you want to use. +You can use this hook in your GitHub Actions workflow together with [pre-commit](https://pre-commit.com). To easy up +dependency management, you can use the managed [docker image](#docker-usage) 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](.github/workflows/pre-commit.yaml) 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): +Here's an example using the container image. It includes caching of pre-commit dependencies and utilizes the pre-commit +command to run checks (Note: Fixes will not be automatically pushed back to your branch, even when possible.): ```yaml name: pre-commit-terraform @@ -1295,7 +1301,7 @@ jobs: This repository is managed by [Anton Babenko](https://github.com/antonbabenko) with help from these awesome contributors: - + Contributors @@ -1316,3 +1322,17 @@ MIT licensed. See [LICENSE](LICENSE) for full details. * Russia has [illegally annexed Crimea in 2014](https://en.wikipedia.org/wiki/Annexation_of_Crimea_by_the_Russian_Federation) and [brought the war in Donbas](https://en.wikipedia.org/wiki/War_in_Donbas) followed by [full-scale invasion of Ukraine in 2022](https://en.wikipedia.org/wiki/2022_Russian_invasion_of_Ukraine). * 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!](https://en.wikipedia.org/wiki/Putin_khuylo!) + + + +[checkov repo]: https://github.com/bridgecrewio/checkov +[terraform-docs repo]: https://github.com/terraform-docs/terraform-docs +[terragrunt repo]: https://github.com/gruntwork-io/terragrunt +[terrascan repo]: https://github.com/tenable/terrascan +[tflint repo]: https://github.com/terraform-linters/tflint +[tfsec repo]: https://github.com/aquasecurity/tfsec +[trivy repo]: https://github.com/aquasecurity/trivy +[infracost repo]: https://github.com/infracost/infracost +[jq repo]: https://github.com/stedolan/jq +[tfupdate repo]: https://github.com/minamijoyo/tfupdate +[hcledit repo]: https://github.com/minamijoyo/hcledit