pre-commit-terraform

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

pre-commit-terraform provides a collection of Git Hooks for Terraform and related tools and is driven by the pre-commit framework. It helps ensure that Terraform, OpenTofu, and Terragrunt configurations are kept in good shape by automatically running various checks and formatting code before committing changes to version control system. This helps maintain code quality and consistency across the project.

It can be run:

• Locally and in CI
• As standalone Git hooks or as a Docker image
• For the entire repository or just for change-related files (e.g., local git stash, last commit, or all changes in a Pull Request)

Want to contribute? Check open issues and contributing notes.

Sponsors

If you want to support the development of pre-commit-terraform and many other open-source projects, please become a GitHub Sponsor!

Table of content

• Sponsors
• Table of content
• How to install
  • 1. Install dependencies
    • 1.1 Custom Terraform binaries and OpenTofu support
  • 2. Install the pre-commit hook globally
  • 3. Add configs and hooks
  • 4. Run
• Available Hooks
• Hooks usage notes and examples
  • Known limitations
  • All hooks: Usage of environment variables in --args
  • All hooks: Usage of __GIT_WORKING_DIR__ placeholder in --args
  • All hooks: Set env vars inside hook at runtime
  • All hooks: Disable color output
  • All hooks: Log levels
  • Most hooks: Pin a specific tool version
    • Keeping pinned versions up-to-date using Renovate
  • 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
  • terragrunt_validate_inputs
• Docker Usage
  • About Docker image security
  • File Permissions
  • Download Terraform modules from private GitHub repositories
  • Mount tools cache directory
• GitHub Actions
• Authors
• License
  • Additional information for users from Russia and Belarus

How to install

1. Install dependencies

TAG=latest
docker pull ghcr.io/antonbabenko/pre-commit-terraform:$TAG

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 .

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 \
    .

brew install pre-commit terraform-docs tflint tfsec trivy checkov terrascan infracost tfupdate minamijoyo/hcledit/hcledit jq

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/

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/

Full list of dependencies and where they are used:

• pre-commit, _{^{terraform or opentofu, git, BASH 3.2.57 or newer, Internet connection (on first run), 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][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

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):

1. Check if per hook configuration --hook-config=--tf-path=<path_to_binary_or_binary_name> is set
2. Check if PCT_TFPATH=<path_to_binary_or_binary_name> environment variable is set
3. Check if TERRAGRUNT_TFPATH=<path_to_binary_or_binary_name> environment variable is set
4. Check if terraform binary can be found in the user’s $PATH
5. Check if tofu binary can be found in the user’s $PATH

2. Install the pre-commit hook globally

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

3. Add configs and hooks

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

git init
cat <<EOF > .pre-commit-config.yaml
repos:
- repo: 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

If this repository was initialized locally via git init or git clone before you installed the pre-commit hook globally (step 2), you will need to run:

pre-commit install

4. Run

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):

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:

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.

Config example:

- id: terraform_tflint
  args:
  - --args=--config=${CONFIG_NAME}.${CONFIG_EXT}
  - --args=--call-module-type="all"

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 --call-module-type="all".

All hooks: Usage of __GIT_WORKING_DIR__ placeholder in --args

All, except deprecated hooks: checkov, terraform_docs_replace

You can use __GIT_WORKING_DIR__ placeholder in --args. It will be replaced by the Git working directory (repo root) at run time.

For instance, if you have multiple directories and want to run terraform_tflint in all of them while sharing a single config file — use the __GIT_WORKING_DIR__ placeholder in the file path. For example:

- id: terraform_tflint
  args:
    - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl

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.

Config example:

- id: terraform_validate
  args:
    - --env-vars=AWS_DEFAULT_REGION="us-west-2"
    - --env-vars=AWS_PROFILE="my-aws-cli-profile"

All hooks: Disable color output

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.

Most hooks: Pin a specific tool version

All hooks, which wrap a tool distributed as a downloadable release asset. Not supported for checkov/terraform_checkov (distributed via PyPi) and for deprecated terraform_docs_replace hook.

1. You can pin a specific version of the wrapped tool per hook, independent of whatever is on your $PATH or baked into the Docker image. If that version isn’t already cached locally, it’s downloaded from the tool’s GitHub releases on first use, then reused (without re-downloading) on every subsequent run.

   Config example:

   - id: terraform_tflint
     args:
       - --hook-config=--tool-version=0.50.0
   

2. The same --tool-version key also works for terraform_validate, terraform_fmt and terraform_providers_lock, which resolve their Terraform/OpenTofu binary through --tf-path - by default it downloads/uses whichever of terraform/opentofu binary the rest of that precedence chain would otherwise have picked (terraform, unless it’s missing from $PATH while tofu is present, in which case opentofu). To pick explicitly instead of relying on the auto-detection mechanism, set --tf-path to the literal value of terraform, opentofu or tofu:

   - id: terraform_validate
     args:
       - --hook-config=--tf-path=opentofu
       - --hook-config=--tool-version=1.12.0
   

   --tf-path and --tool-version either can be set on its own, or combined:

   --tf-path	--tool-version	Behavior
   set to a literal path/binary name	unset	Use that local binary as-is (normal --tf-path behavior); --tool-version is ignored
   unset	set	Auto-detect terraform/opentofu as described above, then download/use that tool at the pinned version
   set to terraform, opentofu, or tofu	set	Download/use the pinned version of whichever of the two was selected
   set to anything else (e.g. an actual path)	set	Error - combined with --tool-version, --tf-path only accepts terraform, opentofu, or tofu
   unset	unset	Falls back to the normal --tf-path precedence chain (env vars, then $PATH)

- id: terraform_tflint
  args:
    - --hook-config=--tool-version=0.50.0
- id: terraform_tflint
  args:
    - --hook-config=--tool-version=0.55.0

4. By default, if a different version of the tool is already on $PATH, the pinned version still wins (with a warning message logged) based on --hook-config=--tool-version-mode=strict. Set it to prefer-local (as opposite to strict) to invert that: if the tool already resolves via $PATH, this local binary is used as-is and no download is attempted; the pinned version is only downloaded/used as a fallback when nothing is found locally.

   - id: terraform_tflint
     args:
       - --hook-config=--tool-version=0.50.0
       - --hook-config=--tool-version-mode=prefer-local
   

5. By default, downloaded binaries are cached under $XDG_CACHE_HOME/pre-commit-terraform/ (or $HOME/.cache/pre-commit-terraform/ if XDG_CACHE_HOME is unset). Override this location with the PCT_TOOL_CACHE_DIR environment variable - see Mount tools cache directory for the Docker case.

6. If a GITHUB_TOKEN environment variable is set, it’s inherited automatically to authenticate GitHub API requests made during version resolution, the same way it already is utilized for building your own Docker image.

Keeping pinned versions up-to-date using Renovate

[!TIP] TL;DR: Real-life usage example. Or you can just use SpotOnInc/renovate-config.

Neither Renovate’s built-in pre-commit manager (which only understands repo:/rev: and additional_dependencies for Go/Node/Python) nor its dockerfileVersions preset can “look” inside hook’s args:, so the --tool-version pin needs its own customManagers entry in your own renovate.json5 config file, using the same # renovate: datasource=... depName=... annotation convention commonly used for Dockerfile ARG *_VERSION pins:

- id: terraform_tflint
  args:
    # renovate: datasource=github-releases depName=terraform-linters/tflint
    - --hook-config=--tool-version=0.50.0

{
  customManagers: [
    { // Enable https://github.com/antonbabenko/pre-commit-terraform tool updates
      customType: "regex",
      managerFilePatterns: ["/(\\.pre-commit-config\\.ya?ml|prek\\.toml)/"],
      matchStrings: [
        "# renovate: datasource=(?<datasource>\\S+) depName=(?<depName>\\S+)[\\s\\S]*?--hook-config=--tool-version=(?<currentValue>[^\\s\"']+)",
      ],
    },
  ],
}

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

- 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

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 (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.

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",
  ]

infracost_breakdown

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.

1. infracost_breakdown supports all infracost breakdown arguments (run infracost breakdown --help to see them). The following example only shows costs:

   - id: infracost_breakdown
     args:
       - --args=--path=./env/dev
     verbose: true # Always show costs
   

   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
   

2. 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"
   

3. (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 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.
   • 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)

4. 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

1. terraform_docs and terraform_docs_without_aggregate_type_defaults will insert/update documentation generated by [terraform-docs][terraform-docs repo] framed by markers:

   <!-- BEGIN_TF_DOCS -->
   
   <!-- END_TF_DOCS -->
   

   if they are present in README.md.

2. It is possible to pass additional arguments to shell scripts when using terraform_docs and terraform_docs_without_aggregate_type_defaults.

3. 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. It’s default starting from v1.93.
     To migrate everything to terraform-docs insertion markers, run in repo root:

     sed --version &> /dev/null && SED_CMD=(sed -i) || SED_CMD=(sed -i '')
     grep -rl --null 'BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs -0 "${SED_CMD[@]}" -e 's/BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK/BEGIN_TF_DOCS/'
     grep -rl --null 'END OF PRE-COMMIT-TERRAFORM DOCS HOOK' . | xargs -0 "${SED_CMD[@]}" -e 's/END OF PRE-COMMIT-TERRAFORM DOCS HOOK/END_TF_DOCS/'
     

   - 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 to true (v1.93+), false (<v1.93). Set to true for compatibility with terraform-docs
         # The following two options "--custom-marker-begin" and "--custom-marker-end" are ignored if "--use-standard-markers" is set to false
       - --hook-config=--custom-marker-begin=<!-- BEGIN_TF_DOCS -->  # String.
                                                       # Set to use custom marker which helps you with using other formats like asciidoc.
                                                       # For Asciidoc this could be "--hook-config=--custom-marker-begin=// BEGIN_TF_DOCS"
       - --hook-config=--custom-marker-end=<!-- END_TF_DOCS -->  # String.
                                                       # Set to use custom marker which helps you with using other formats like asciidoc.
                                                       # For Asciidoc this could be "--hook-config=--custom-marker-end=// END_TF_DOCS"
       - --hook-config=--custom-doc-header="# "        # String. Defaults to "# "
                                                       # Set to use custom marker which helps you with using other formats like asciidoc.
                                                       # For Asciidoc this could be "--hook-config=--custom-marker-end=\= "
   

4. If you want to use a terraform-docs config file, you must supply the path to the file, relative to the git repo root path:

   - id: terraform_docs
     args:
       - --args=--config=.terraform-docs.yml
   

   Warning
   Avoid use recursive.enabled: true in config file, that can cause unexpected behavior.

5. You can provide any configuration available in terraform-docs as an argument to terraform_docs hook:

   - id: terraform_docs
     args:
       - --args=--output-mode=replace
   

6. 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 .
   

terraform_docs_replace (deprecated)

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:

1. 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 */}}
   

2. Replace terraform_docs_replace hook config in .pre-commit-config.yaml with:

   - id: terraform_docs
     args:
       - --args=--config=.terraform-docs.yml
   

terraform_fmt

terraform_fmt supports custom arguments so you can pass supported flags. Eg:

 - id: terraform_fmt
   args:
     - --args=-no-color
     - --args=-diff
     - --args=-write=false

terraform_providers_lock

- 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

1. The hook can work in a few different modes:

   1. --mode=check-lockfile-is-cross-platform (standalone)

      Checks that lockfile has the same number of platform checksums (`h1:`) as requested by the hook configuration. It **does not** check whether these checksums are valid or that they match target platforms.

      - id: terraform_providers_lock
        args:
        - --hook-config=--mode=check-lockfile-is-cross-platform
      

   2. --mode=regenerate-lockfile-if-some-platform-missed (standalone)

      Checks that lockfile has checksums (h1:) for all requested platforms for all providers tracked by the lockfile, and if any are missed - tries to add them (but could fail if terraform init wasn’t run previously).

      - id: terraform_providers_lock
        args:
        - --hook-config=--mode=regenerate-lockfile-if-some-platform-missed
      

   3. --mode=regenerate-lockfile-if-some-platform-missed with terraform_validate hook

      Regenerates lockfile for all required providers and checks that the lockfile tracks all required platform checksums (h1:) afterwards. If any are missed - adds them; superfluous providers are removed.

      Important The following terraform_validate hook’s 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=regenerate-lockfile-if-some-platform-missed
      

   4. always-regenerate-lockfile - meant to be used only along with terraform_validate hook

      Regenerates lockfile from the scratch. May be useful for upgrading providers in the lockfile to the 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
      

2. terraform_providers_lock supports custom arguments:

    - id: terraform_providers_lock
      args:
         - --args=-platform=windows_amd64
         - --args=-platform=darwin_amd64
   

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:

   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.

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 hook, which, to take effect, should be called before terraform_providers_lock

   - id: terraform_providers_lock
     args:
       - --tf-init-args=-upgrade
   

terraform_tflint

1. 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
   

2. 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
   

terraform_tfsec (deprecated)

DEPRECATED. tfsec was replaced by trivy, so please use terraform_trivy.

1. terraform_tfsec will consume modified files that pre-commit passes to it, so you can perform whitelisting of directories or files to run against via files pre-commit flag

   Example:

   - id: terraform_tfsec
     files: ^prd-infra/
   

   The above will tell pre-commit to pass down files from the prd-infra/ folder only such that the underlying tfsec tool can run against changed files in this directory, ignoring any other folders at the root level

2. 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
   }
   

3. 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
   

terraform_trivy

1. 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_trivy
     files: ^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

2. 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"]
   }
   

3. 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"
   

terraform_validate

[!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.
This issue was fixed in OpenTofu v1.10+, so it’s safe to use parallelism with it.

1. terraform_validate supports custom arguments so you can pass supported -no-color or -json flags:

    - id: terraform_validate
      args:
        - --args=-json
        - --args=-no-color
   

2. terraform_validate also supports passing custom arguments to its terraform init:

   - id: terraform_validate
     args:
       - --tf-init-args=-upgrade
       - --tf-init-args=-lockfile=readonly
   

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 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 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.

4. 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_validate
     exclude: '^[^/]+$'
   

   This will exclude the root directory from being processed by this hook. Then add a subdirectory like “examples” or “tests” and put an example implementation in place that defines the providers with the proper aliases, and this will give you validation of your module through the example. If instead you are using this with multiple modules in one repository you’ll want to set the path prefix in the regular expression, such as exclude: modules/offendingmodule/[^/]+$.

   Alternately, you can use terraform-config-inspect and use a variant of this script to generate a providers file at runtime:

   terraform-config-inspect --json . | jq -r '
     [.required_providers[].aliases]
     | flatten
     | del(.[] | select(. == null))
     | reduce .[] as $entry (
       {};
       .provider[$entry.name] //= [] | .provider[$entry.name] += [{"alias": $entry.alias}]
     )
   ' | tee aliased-providers.tf.json
   

   Save it as .generate-providers.sh in the root of your repository and add a pre-commit hook to run it before all other hooks, like so:

   - repos:
     - repo: local
       hooks:
         - id: generate-terraform-providers
           name: generate-terraform-providers
           require_serial: true
           entry: .generate-providers.sh
           language: script
           files: \.tf(vars)?$
           pass_filenames: false
   
     - repo: https://github.com/pre-commit/pre-commit-hooks
   

   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:

1. --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/*”).
2. --module-repo-org=... - Module repository organization (e.g. “terraform-aws-modules”).
3. --module-repo-shortname=... - Short name of the repository (e.g. “s3-bucket”).
4. --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

1. terrascan supports custom arguments so you can pass supported flags like `–non-recursi</provider_alias></path_to_binary_or_binary_name></path_to_binary_or_binary_name></path_to_binary_or_binary_name>

README 内容过长，已截取前 64 KB。完整内容请前往 GitHub 仓库查看。