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: Initial docs improvement (#218)

Browse source
This commit is contained in:
Maksym Vlasov 2021-09-09 12:38:43 +03:00 • committed by GitHub
commit 5daffe8727
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
6 changed files with 153 additions and 53 deletions
Download patch file Download diff file Expand all files Collapse all files

14
.editorconfig Normal file
View file

@ -0,0 +1,14 @@
root = true
[*]
indent_style = space
indent_size = 2
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true
[{*.{sh,py,md},Dockerfile}]
indent_size = 4
[*.md]
trim_trailing_whitespace = false

24
.pre-commit-config.yaml
View file

@ -1,13 +1,31 @@
repos:
- repo: git://github.com/pre-commit/pre-commit-hooks
rev: v3.4.0
rev: v4.0.1
hooks:
- id: check-yaml
# Git style
- id: check-added-large-files
- id: check-merge-conflict
- id: check-vcs-permalinks
- id: forbid-new-submodules
- id: no-commit-to-branch
# Common errors
- id: end-of-file-fixer
- id: trailing-whitespace
- id: check-case-conflict
args: [--markdown-linebreak-ext=md]
- id: check-yaml
- id: check-merge-conflict
- id: check-executables-have-shebangs
# Cross platform
- id: check-case-conflict
# Security
- id: detect-aws-credentials
args: ['--allow-missing-credentials']
- id: detect-private-key
- repo: git://github.com/jumanjihouse/pre-commit-hooks
rev: 2.1.5
hooks:

160
README.md
View file

@ -1,6 +1,25 @@
# 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) ![](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)
* [How to install](#how-to-install)
* [1. Install dependencies](#1-install-dependencies)
* [MacOS](#macos)
* [Ubuntu 18.04](#ubuntu-1804)
* [Ubuntu 20.04](#ubuntu-2004)
* [2. Install the pre-commit hook globally](#2-install-the-pre-commit-hook-globally)
* [3. Add configs and hooks](#3-add-configs-and-hooks)
* [4. Run](#4-run)
* [Available Hooks](#available-hooks)
* [Hooks notes](#hooks-notes)
* [terraform_docs](#terraform_docs)
* [terraform_tflint](#terraform_tflint)
* [terraform_tfsec](#terraform_tfsec)
* [terraform_validate](#terraform_validate)
* [Notes for contributors](#notes-for-contributors)
* [Run and debug hooks locally](#run-and-debug-hooks-locally)
* [Authors](#authors)
* [License](#license)
## How to install
@ -16,28 +35,46 @@
or build and use the Docker image locally as mentioned below in the `Run` section.
##### MacOS
#### MacOS
```bash
brew install pre-commit gawk terraform-docs tflint tfsec coreutils checkov terrascan
```
##### Ubuntu 18.04
#### Ubuntu 18.04
```bash
sudo apt update
sudo apt install -y gawk 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 pre-commit
curl -L "$(curl -s https://api.github.com/repos/terraform-docs/terraform-docs/releases/latest | grep -o -E "https://.+?-linux-amd64.tar.gz")" > terraform-docs.tgz && tar xzf 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 "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/tfsec/tfsec/releases/latest | grep -o -E "https://.+?tfsec-linux-amd64")" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/aquasecurity/tfsec/releases/latest | grep -o -E "https://.+?tfsec-linux-amd64" | head -n 1)" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/accurics/terrascan/releases/latest | grep -o -E "https://.+?_Linux_x86_64.tar.gz")" > terrascan.tar.gz && tar -xf terrascan.tar.gz terrascan && rm terrascan.tar.gz && sudo mv terrascan /usr/bin/
python3.7 -m pip install -U checkov
```
##### Ubuntu 20.04
```bash
sudo apt update
sudo apt install -y gawk unzip software-properties-common
sudo apt install -y python3 python3-pip
python3 -m pip install --upgrade pip
pip3 install pre-commit
curl -L "$(curl -s https://api.github.com/repos/terraform-docs/terraform-docs/releases/latest | grep -o -E "https://.+?-linux-amd64.tar.gz")" > terraform-docs.tgz && tar -xzf terraform-docs.tgz terraform-docs && 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 "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 "https://.+?tfsec-linux-amd64" | head -n 1)" > tfsec && chmod +x tfsec && sudo mv tfsec /usr/bin/
curl -L "$(curl -s https://api.github.com/repos/accurics/terrascan/releases/latest | grep -o -E "https://.+?_Linux_x86_64.tar.gz")" > terrascan.tar.gz && tar -xf terrascan.tar.gz terrascan && rm terrascan.tar.gz && sudo mv terrascan /usr/bin/
pip3 install -U checkov
```
### 2. Install the pre-commit hook globally
Note: not needed if you use the Docker image
```bash
@ -71,6 +108,7 @@ pre-commit run -a
```
or you can also build and use the provided Docker container, which wraps all dependencies by
```bash
# first building it
docker build -t pre-commit .
@ -83,48 +121,54 @@ docker run -v $(pwd):/lint -w /lint pre-commit run -a
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 |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| `terraform_fmt` | Rewrites all Terraform configuration files to a canonical format. |
| `terraform_validate` | Validates all Terraform configuration files. |
| `terraform_docs` | Inserts input and output documentation into `README.md`. Recommended. |
| `terraform_docs_without_aggregate_type_defaults` | Inserts input and output documentation into `README.md` without aggregate type defaults. |
| `terraform_docs_replace` | Runs `terraform-docs` and pipes the output directly to README.md (requires terraform-docs v0.10.0 or later) |
| `terraform_tflint` | Validates all Terraform configuration files with [TFLint](https://github.com/terraform-linters/tflint). |
| `terragrunt_fmt` | Rewrites all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) to a canonical format. |
| `terragrunt_validate` | Validates all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) |
| `terraform_tfsec` | [TFSec](https://github.com/liamg/tfsec) static analysis of terraform templates to spot potential security issues. |
| `checkov` | [checkov](https://github.com/bridgecrewio/checkov) static analysis of terraform templates to spot potential security issues. |
| `terrascan` | [terrascan](https://github.com/accurics/terrascan) Detect compliance and security violations. |
| Hook name | Description |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `terraform_fmt` | Rewrites all Terraform configuration files to a canonical format. [Hook notes](#terraform_docs) |
| `terraform_validate` | Validates all Terraform configuration files. [Hook notes](#terraform_validate) |
| `terraform_docs` | Inserts input and output documentation into `README.md`. Recommended. |
| `terraform_docs_without_aggregate_type_defaults` | Inserts input and output documentation into `README.md` without aggregate type defaults. |
| `terraform_docs_replace` | Runs `terraform-docs` and pipes the output directly to README.md |
| `terraform_tflint` | Validates all Terraform configuration files with [TFLint](https://github.com/terraform-linters/tflint). [Hook notes](#terraform_tflint). |
| `terragrunt_fmt` | Rewrites all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) to a canonical format. |
| `terragrunt_validate` | Validates all [Terragrunt](https://github.com/gruntwork-io/terragrunt) configuration files (`*.hcl`) |
| `terraform_tfsec` | [TFSec](https://github.com/liamg/tfsec) static analysis of terraform templates to spot potential security issues. [Hook notes](#terraform_tfsec) |
| `checkov` | [checkov](https://github.com/bridgecrewio/checkov) static analysis of terraform templates to spot potential security issues. |
| `terrascan` | [terrascan](https://github.com/accurics/terrascan) Detect compliance and security violations. |
Check the [source file](https://github.com/antonbabenko/pre-commit-terraform/blob/master/.pre-commit-hooks.yaml) to know arguments used for each hook.
## Notes about terraform_docs hooks
## Hooks notes
### 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:
```txt
<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
```
if they are present in `README.md`.
```txt
<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
1. `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. The optional `--dest` argument lets you change the name of the file that gets created/modified. This hook requires terraform-docs v0.10.0 or later.
<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
```
if they are present in `README.md`.
2. `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. The optional `--dest` argument lets you change the name of the file that gets created/modified.
Example:
1. Example:
```yaml
hooks:
- id: terraform_docs_replace
args: ['--sort-by-required', '--dest=TEST.md']
```
1. 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 there is something missing.
3. 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 there is something missing.
## Notes about terraform_tflint hooks
### terraform_tflint
1. `terraform_tflint` supports custom arguments so you can enable module inspection, deep check mode etc.
1. Example:
Example:
```yaml
hooks:
- id: terraform_tflint
@ -132,6 +176,7 @@ if they are present in `README.md`.
```
In order to pass multiple args, try the following:
```yaml
- id: terraform_tflint
args:
@ -139,24 +184,25 @@ if they are present in `README.md`.
- '--args=--enable-rule=terraform_documented_variables'
```
1. When you have multiple directories and want to run `tflint` in all of them and share single config file it is impractical to hard-code the path to `.tflint.hcl` file. The solution is to use `__GIT_WORKING_DIR__` placeholder which will be replaced by `terraform_tflint` hooks with Git working directory (repo root) at run time. For example:
3. When you have multiple directories and want to run `tflint` in all of them and share single config file it is impractical to hard-code the path to `.tflint.hcl` file. The solution is to use `__GIT_WORKING_DIR__` placeholder which will be replaced by `terraform_tflint` hooks with Git working directory (repo root) at run time. For example:
```yaml
hooks:
- id: terraform_tflint
args:
- '--args=--config=__GIT_WORKING_DIR__/.tflint.hcl'
```
```yaml
hooks:
- id: terraform_tflint
args:
- '--args=--config=__GIT_WORKING_DIR__/.tflint.hcl'
```
## Notes about terraform_tfsec hooks
### terraform_tfsec
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](https://pre-commit.com/#config-files)
pre-commit flag
1. Example:
Example:
```yaml
hooks:
- id: terraform_tfsec
@ -167,9 +213,11 @@ if they are present in `README.md`.
only such that the underlying `tfsec` tool can run against changed files in this
directory, ignoring any other folders at the root level
1. 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).
1. Example:
Example:
```hcl
resource "aws_security_group_rule" "my-rule" {
type = "ingress"
@ -177,11 +225,12 @@ if they are present in `README.md`.
}
```
## Notes about terraform_validate hooks
### terraform_validate
1. `terraform_validate` supports custom arguments so you can pass supported no-color or json flags.
1. Example:
Example:
```yaml
hooks:
- id: terraform_validate
@ -189,15 +238,18 @@ if they are present in `README.md`.
```
In order to pass multiple args, try the following:
```yaml
- id: terraform_validate
args:
- '--args=-json'
- '--args=-no-color'
```
1. `terraform_validate` also supports custom environment variables passed to the pre-commit runtime
1. Example:
2. `terraform_validate` also supports custom environment variables passed to the pre-commit runtime
Example:
```yaml
hooks:
- id: terraform_validate
@ -205,6 +257,7 @@ if they are present in `README.md`.
```
In order to pass multiple args, try the following:
```yaml
- id: terraform_validate
args:
@ -213,7 +266,7 @@ if they are present in `README.md`.
- '--envs=AWS_SECRET_ACCESS_KEY="asecretkey"'
```
1. 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 using this command:
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 using this command:
```shell
find . -type d -name ".terraform" -print0 | xargs -0 rm -r
@ -221,14 +274,29 @@ if they are present in `README.md`.
`terraform_validate` hook will try to reinitialize them before running `terraform validate` command.
## Notes for developers
## Notes for contributors
1. Python hooks are supported now too. All you have to do is:
1. add a line to the `console_scripts` array in `entry_points` in `setup.py`
1. Put your python script in the `pre_commit_hooks` folder
2. Put your python script in the `pre_commit_hooks` folder
Enjoy the clean, valid, and documented code!
### Run and debug hooks locally
```bash
pre-commit try-repo {-a} /path/to/local/pre-commit-terraform/repo {hook_name}
```
I.e.
```bash
pre-commit try-repo /mnt/c/Users/tf/pre-commit-terraform terraform_fmt # Run only `terraform_fmt` check
pre-commit try-repo -a ~/pre-commit-terraform # run all existing checks from repo
```
Running `pre-commit` with `try-repo` ignores all arguments specified in `.pre-commit-config.yaml`.
## Authors
This repository is managed by [Anton Babenko](https://github.com/antonbabenko) with help from [these awesome contributors](https://github.com/antonbabenko/pre-commit-terraform/graphs/contributors).