github/pre-commit-opentofu
1
0
Fork 1
mirror of https://github.com/tofuutils/pre-commit-opentofu.git synced 2025-10-15 17:38:54 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

docs: Pre-release 1.53 (#267)

Browse source
This commit is contained in:
Anton Babenko 2021-10-26 14:39:23 +02:00 • committed by GitHub
commit 9656159025
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 47 additions and 68 deletions
Download patch file Download diff file Expand all files Collapse all files

115
README.md
View file

@ -2,7 +2,7 @@
[![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/2021.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) [![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/2021.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)
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). 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).
* [How to install](#how-to-install) * [How to install](#how-to-install)
* [1. Install dependencies](#1-install-dependencies) * [1. Install dependencies](#1-install-dependencies)
@ -29,19 +29,9 @@ Want to Contribute? Check [open issues](https://github.com/antonbabenko/pre-comm
<!-- markdownlint-disable no-inline-html --> <!-- markdownlint-disable no-inline-html -->
* [`pre-commit`](https://pre-commit.com/#install), * [`pre-commit`](https://pre-commit.com/#install)
<sub><sup>[`terraform`](https://www.terraform.io/downloads.html),
<sub><sup>[`git`](https://git-scm.com/downloads),
<sub><sup>POSIX compatible shell,
<sub><sup>Internet connection (on first run),
<sub><sup>x86_64 compatible operation system,
<sub><sup>Some hardware where this OS will run,
<sub><sup>Electricity for hardware and internet connection,
<sub><sup>Some basic physical laws,
<sub><sup>Hope that it all will works.
</sup></sub></sup></sub></sup></sub></sup></sub></sup></sub></sup></sub></sup></sub></sup></sub></sup></sub><br><br>
* [`checkov`](https://github.com/bridgecrewio/checkov) required for `checkov` hook. * [`checkov`](https://github.com/bridgecrewio/checkov) required for `checkov` hook.
* [`terraform-docs`](https://github.com/terraform-docs/terraform-docs) required for `terraform_docs` hooks. * [`terraform-docs`](https://github.com/terraform-docs/terraform-docs) required for `terraform_docs` hook.
* [`terragrunt`](https://terragrunt.gruntwork.io/docs/getting-started/install/) required for `terragrunt_validate` hook. * [`terragrunt`](https://terragrunt.gruntwork.io/docs/getting-started/install/) required for `terragrunt_validate` hook.
* [`terrascan`](https://github.com/accurics/terrascan) required for `terrascan` hook. * [`terrascan`](https://github.com/accurics/terrascan) required for `terrascan` hook.
* [`TFLint`](https://github.com/terraform-linters/tflint) required for `terraform_tflint` hook. * [`TFLint`](https://github.com/terraform-linters/tflint) required for `terraform_tflint` hook.
@ -51,17 +41,16 @@ Want to Contribute? Check [open issues](https://github.com/antonbabenko/pre-comm
<details><summary><b>Docker</b></summary><br> <details><summary><b>Docker</b></summary><br>
If no `--build-arg` is specified, then the latest versions of `pre-commit` and `terraform` will be installed. When `--build-arg` is not specified, the latest version of `pre-commit` and `terraform` will be installed.
```bash ```bash
git clone git@github.com:antonbabenko/pre-commit-terraform.git git clone git@github.com:antonbabenko/pre-commit-terraform.git
cd pre-commit-terraform cd pre-commit-terraform
# Install all tools with latest versions: # Install the latest versions of all the tools
docker build -t pre-commit --build-arg INSTALL_ALL=true . docker build -t pre-commit --build-arg INSTALL_ALL=true .
``` ```
You can specify needed tool versions by providing `--build-arg`'s. To install a specific version of individual tools, define it using `--build-arg` arguments or set it to `latest`:
If you'd like you can use the `latest` versions:
```bash ```bash
docker build -t pre-commit \ docker build -t pre-commit \
@ -77,19 +66,17 @@ docker build -t pre-commit \
. .
``` ```
To disable the pre-commit color output, set `-e PRE_COMMIT_COLOR=never`. Set `-e PRE_COMMIT_COLOR=never` to disable the color output in `pre-commit`.
</details> </details>
<details><summary><b>MacOS</b></summary><br> <details><summary><b>MacOS</b></summary><br>
[`coreutils`](https://formulae.brew.sh/formula/coreutils) required for `terraform_validate` hook on macOS (due to use of `realpath`). [`coreutils`](https://formulae.brew.sh/formula/coreutils) is required for `terraform_validate` hook on MacOS (due to use of `realpath`).
```bash ```bash
brew install pre-commit terraform-docs tflint tfsec coreutils checkov terrascan infracost jq brew install pre-commit terraform-docs tflint tfsec coreutils checkov terrascan infracost jq
terrascan init
infracost register
``` ```
</details> </details>
@ -163,25 +150,22 @@ EOF
### 4. Run ### 4. Run
After the pre-commit hook has been installing you can run it manually on all files in the repository. Execute this command to run `pre-commit` on all files in the repository (not only changed files):
Local installation:
```bash ```bash
pre-commit run -a pre-commit run -a
``` ```
Docker: Or, using Docker:
```bash ```bash
docker run -v $(pwd):/lint -w /lint pre-commit run -a docker run -v $(pwd):/lint -w /lint pre-commit run -a
``` ```
> You be able to list tools versions when needed Execute this command to list the versions of the tools in Docker:
> ```bash
> ```bash docker run --entrypoint cat pre-commit:latest /usr/bin/tools_versions_info
> TAG=latest && docker run --entrypoint cat pre-commit:$TAG /usr/bin/tools_versions_info ```
> ```
## Available Hooks ## Available Hooks
@ -191,16 +175,16 @@ There are several [pre-commit](https://pre-commit.com/) hooks to keep Terraform
| Hook name | Description | Dependencies<br><sup>[Install instructions here](#1-install-dependencies)</sup> | | Hook name | Description | Dependencies<br><sup>[Install instructions here](#1-install-dependencies)</sup> |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `checkov` | [checkov](https://github.com/bridgecrewio/checkov) static analysis of terraform templates to spot potential security issues. [Hook notes](#checkov) | `checkov`<br>Ubuntu deps: `python3`, `python3-pip` | | `checkov` | [checkov](https://github.com/bridgecrewio/checkov) static analysis of terraform templates to spot potential security issues. [Hook notes](#checkov) | `checkov`<br>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), Internet connection | `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_replace` | Runs `terraform-docs` and pipes the output directly to README.md | `python3`, `terraform-docs` | | `terraform_docs_replace` | Runs `terraform-docs` and pipes the output directly to README.md | `python3`, `terraform-docs` |
| `terraform_docs_without_`<br>`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_docs_without_`<br>`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_docs` | Inserts input and output documentation into `README.md`. Recommended. [Hook notes](#terraform_docs) | `terraform-docs` | | `terraform_docs` | Inserts input and output documentation into `README.md`. Recommended. [Hook notes](#terraform_docs) | `terraform-docs` |
| `terraform_fmt` | Rewrites all Terraform configuration files to a canonical format. [Hook notes](#terraform_fmt) | - | | `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_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/tree/master/docs/rules#rules). [Hook notes](#terraform_tflint). | `tflint` | | `terraform_tflint` | Validates all Terraform configuration files with [TFLint](https://github.com/terraform-linters/tflint). [Available TFLint rules](https://github.com/terraform-linters/tflint/tree/master/docs/rules#rules). [Hook notes](#terraform_tflint). | `tflint` |
| `terraform_tfsec` | [TFSec](https://github.com/liamg/tfsec) static analysis of terraform templates to spot potential security issues. [Hook notes](#terraform_tfsec) | `tfsec` | | `terraform_tfsec` | [TFSec](https://github.com/aquasecurity/tfsec) static analysis of terraform templates to spot potential security issues. [Hook notes](#terraform_tfsec) | `tfsec` |
| `terraform_validate` | Validates all Terraform configuration files. [Hook notes](#terraform_validate) | - | | `terraform_validate` | Validates all Terraform configuration files. [Hook notes](#terraform_validate) | - |
| `terragrunt_fmt` | Rewrites all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) to a canonical format. | `terragrunt` | | `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` | Validates all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) | `terragrunt` |
| `terrascan` | [terrascan](https://github.com/accurics/terrascan) Detect compliance and security violations. | `terrascan` | | `terrascan` | [terrascan](https://github.com/accurics/terrascan) Detect compliance and security violations. | `terrascan` |
<!-- markdownlint-enable no-inline-html --> <!-- markdownlint-enable no-inline-html -->
@ -223,15 +207,11 @@ For [checkov](https://github.com/bridgecrewio/checkov) you need to specify each
### infracost_breakdown ### infracost_breakdown
`infracost_breakdown` build on top of the `infracost breakdown` command. It, if needed, runs `terraform init`, `terraform plan` and calls `infracost` API - so this hook can run up to several minutes. `infracost_breakdown` executes `infracost breakdown` command and compare the estimated costs with those specified in the hook-config. `infracost breakdown` normally runs `terraform init`, `terraform plan`, and calls Infracost Cloud Pricing API (remote version or [self-hosted version](https://www.infracost.io/docs/cloud_pricing_api/self_hosted)).
Unlike most other hooks, this one triggers all changes to the files but checks predefined paths each time. Unlike most other hooks, this hook triggers once if there are any changed files in the repository.
For example, the hook tracks `--path=./env/dev` and `./env/dev` depend on `./main.tf`. So when you will make changes to `./main.tf` - the hook will run and show the cost changes for `./env/dev`. 1. `infracost_breakdown` supports [all `infracost breakdown` arguments](https://www.infracost.io/docs/#useful-options). The following example only shows costs:
1. `infracost_breakdown` supports custom arguments so you can pass [supported flags](https://www.infracost.io/docs/#useful-options).
The following example only shows costs:
```yaml ```yaml
- id: infracost_breakdown - id: infracost_breakdown
@ -257,7 +237,7 @@ For example, the hook tracks `--path=./env/dev` and `./env/dev` depend on `./mai
<!-- markdownlint-disable-next-line no-inline-html --> <!-- markdownlint-disable-next-line no-inline-html -->
</details> </details>
2. You can provide limitations when the hook should fail: 2. (Optionally) Define `cost constrains` the hook should evaluate successfully in order to pass:
```yaml ```yaml
- id: infracost_breakdown - id: infracost_breakdown
@ -280,7 +260,7 @@ For example, the hook tracks `--path=./env/dev` and `./env/dev` depend on `./mai
Summary: { Summary: {
"unsupportedResourceCounts": { "unsupportedResourceCounts": {
"aws_sns_topic_subscription": 1 "aws_sns_topic_subscription": 1
} }
} }
@ -290,24 +270,23 @@ For example, the hook tracks `--path=./env/dev` and `./env/dev` depend on `./mai
<!-- markdownlint-disable-next-line no-inline-html --> <!-- markdownlint-disable-next-line no-inline-html -->
</details> </details>
* Hook uses `jq` to parse `infracost` output, so paths to values like `.totalHourlyCost` and `.totalMonthlyCost` should be in jq-compatible format. * Only one path per one hook (`- id: infracost_breakdown`) is allowed.
To check available structure use `infracost breakdown -p PATH_TO_TF_DIR --format json | jq -r . > infracost.json`. And play with it on [jqplay.org](https://jqplay.org/) * 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](https://jqplay.org/).
* Supported comparison operators: `<`, `<=`, `==`, `!=`, `>=`, `>`. * Supported comparison operators: `<`, `<=`, `==`, `!=`, `>=`, `>`.
* Most useful paths and checks: * Most useful paths and checks:
* `.totalHourlyCost` (same to `.projects[].breakdown.totalHourlyCost`) - show total hourly infra cost * `.totalHourlyCost` (same as `.projects[].breakdown.totalHourlyCost`) - show total hourly infra cost
* `.totalMonthlyCost` (same to `.projects[].breakdown.totalMonthlyCost`) - show total monthly infra cost * `.totalMonthlyCost` (same as `.projects[].breakdown.totalMonthlyCost`) - show total monthly infra cost
* `.projects[].diff.totalHourlyCost` - show hourly cost diff between existing infra and tf plan * `.projects[].diff.totalHourlyCost` - show the difference in hourly cost for the existing infra and tf plan
* `.projects[].diff.totalMonthlyCost` - show monthly cost diff between 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 > 1000` (for Infracost older than 0.9.12): * `.diffTotalHourlyCost` (for Infracost version 0.9.12 or newer) or `[.projects[].diff.totalMonthlyCost | select (.!=null) | tonumber] | add` (for Infracost older than 0.9.12)
* fail if changes push the total monthly cost estimate above $1K * To disable hook color output, set `PRE_COMMIT_COLOR=never` env var.
* fail if changes increase the cost by $1K.
* You can set up only one path per one hook (`- id: infracost_breakdown`) - this is an `infracost` limitation.
* Set `verbose: true` to see cost even when the checks are passed.
* To disable hook color output, set `PRE_COMMIT_COLOR=never` env var
3. **Docker usage**. In `docker build` or `docker run` command: 3. **Docker usage**. In `docker build` or `docker run` command:
* You need to provide [Infracost API key](https://www.infracost.io/docs/integrations/environment_variables/#infracost_api_key) via `-e INFRACOST_API_KEY=<your token>`. By default it is saved in `~/.config/infracost/credentials.yml` * You need to provide [Infracost API key](https://www.infracost.io/docs/integrations/environment_variables/#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; can be useful in CI/CD systems. [Doc](https://www.infracost.io/docs/integrations/environment_variables/#infracost_skip_update_check) * Set `-e INFRACOST_SKIP_UPDATE_CHECK=true` to [skip the Infracost update check](https://www.infracost.io/docs/integrations/environment_variables/#infracost_skip_update_check) if you use this hook as part of your CI/CD pipeline.
### terraform_docs ### terraform_docs
@ -321,12 +300,12 @@ For example, the hook tracks `--path=./env/dev` and `./env/dev` depend on `./mai
if they are present in `README.md`. 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`. Send pull-request with the new hook if something is missing. 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: 3. It is possible to automatically:
* create docfile (and PATH to it) * create documentation file
* extend existing doc files by appending markers to the end of the file (see item 1) * extend existing documentation file by appending markers to the end of the file (see item 1 above)
* use different than `README.md` docfile name. * use different filename for the documentation (default is `README.md`)
```yaml ```yaml
- id: terraform_docs - id: terraform_docs
@ -336,7 +315,7 @@ For example, the hook tracks `--path=./env/dev` and `./env/dev` depend on `./mai
- --hook-config=--create-file-if-not-exist=true # Boolean. true or false - --hook-config=--create-file-if-not-exist=true # Boolean. true or false
``` ```
4. You can provide arguments to terraform_doc. Eg. for [configuration](https://github.com/terraform-docs/terraform-docs/blob/master/docs/user-guide/configuration.md#usage): 4. You can provide [any configuration available in `terraform-docs`](https://terraform-docs.io/user-guide/configuration/) as argument to `terraform_doc` hook, for example:
```yaml ```yaml
- id: terraform_docs - id: terraform_docs
@ -347,7 +326,7 @@ For example, the hook tracks `--path=./env/dev` and `./env/dev` depend on `./mai
```yaml ```yaml
- id: terraform_docs - id: terraform_docs
args: args:
- tfvars hcl --output-file terraform.tfvars.model . - tfvars hcl --output-file terraform.tfvars.model .
``` ```
@ -381,7 +360,7 @@ Example:
1. The hook requires Terraform 0.14 or later. 1. The hook requires Terraform 0.14 or later.
2. The hook invokes two operations that can be really slow: 2. The hook invokes two operations that can be really slow:
* `terraform init` (in case `.terraform` directory is not initialised) * `terraform init` (in case `.terraform` directory is not initialised)
* `terraform providers lock`. * `terraform providers lock`
Both operations require downloading data from remote Terraform registries, and not all of that downloaded data or meta-data is currently being cached by Terraform. Both operations require downloading data from remote Terraform registries, and not all of that downloaded data or meta-data is currently being cached by Terraform.
@ -406,7 +385,7 @@ Example:
# Reload shell and use `rm_terraform` command in the repo root # Reload shell and use `rm_terraform` command in the repo root
``` ```
`terraform_providers_lock` hook will try to reinitialize them before running the `terraform providers lock` command. `terraform_providers_lock` hook will try to reinitialize directories before running the `terraform providers lock` command.
### terraform_tflint ### terraform_tflint
@ -449,7 +428,7 @@ Example:
directory, ignoring any other folders at the root level directory, ignoring any other folders at the root level
2. To ignore specific warnings, follow the convention from the 2. To ignore specific warnings, follow the convention from the
[documentation](https://github.com/liamg/tfsec#ignoring-warnings). [documentation](https://github.com/aquasecurity/tfsec#ignoring-warnings).
Example: Example:
@ -460,7 +439,7 @@ Example:
} }
``` ```
3. `terraform_tfsec` supports custom arguments so you can pass supported `--no-color` or `--format` (output), `-e` (exclude checks) flags: 3. `terraform_tfsec` supports custom arguments, so you can pass supported `--no-color` or `--format` (output), `-e` (exclude checks) flags:
```yaml ```yaml
- id: terraform_tfsec - id: terraform_tfsec
@ -522,7 +501,7 @@ Example:
`terraform_validate` hook will try to reinitialize them before running the `terraform validate` command. `terraform_validate` hook will try to reinitialize them before running the `terraform validate` command.
**Warning:** If you use Terraform workspaces, DO NOT use this workaround ([details](https://github.com/antonbabenko/pre-commit-terraform/issues/203#issuecomment-918791847)). Wait to [`force-init`](https://github.com/antonbabenko/pre-commit-terraform/issues/224) option implementation **Warning:** If you use Terraform workspaces, DO NOT use this workaround ([details](https://github.com/antonbabenko/pre-commit-terraform/issues/203#issuecomment-918791847)). Wait to [`force-init`](https://github.com/antonbabenko/pre-commit-terraform/issues/224) option implementation.
## Authors ## Authors