From eee8fa1d55d404d87688bf44ef81bd0b2a8bac2d Mon Sep 17 00:00:00 2001 From: Maksym Vlasov Date: Sat, 10 Feb 2024 00:38:26 +0200 Subject: [PATCH] docs: Revisit docs constructions to Github markdown extension (#619) And partially revert syntax as GH Markdown is buggy: https://github.com/orgs/community/discussions/16925#discussioncomment-7574895 --- .../bug_report_local_install.md | 2 + Dockerfile | 1 + README.md | 79 ++++++++++--------- 3 files changed, 46 insertions(+), 36 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report_local_install.md b/.github/ISSUE_TEMPLATE/bug_report_local_install.md index 63a1ce915..544dc03ed 100644 --- a/.github/ISSUE_TEMPLATE/bug_report_local_install.md +++ b/.github/ISSUE_TEMPLATE/bug_report_local_install.md @@ -82,11 +82,13 @@ terraform --version | head -n 1 2>/dev/null || echo "terraform SKIPPED python --version 2>/dev/null || echo "python SKIPPED" python3 --version 2>/dev/null || echo "python3 SKIPPED" echo -n "checkov " && checkov --version 2>/dev/null || echo "checkov SKIPPED" +infracost --version 2>/dev/null || echo "infracost SKIPPED" terraform-docs --version 2>/dev/null || echo "terraform-docs SKIPPED" terragrunt --version 2>/dev/null || echo "terragrunt SKIPPED" echo -n "terrascan " && terrascan version 2>/dev/null || echo "terrascan SKIPPED" tflint --version 2>/dev/null || echo "tflint SKIPPED" echo -n "tfsec " && tfsec --version 2>/dev/null || echo "tfsec SKIPPED" +echo -n "trivy " && trivy --version 2>/dev/null || echo "tfsec SKIPPED" echo -n "tfupdate " && tfupdate --version 2>/dev/null || echo "tfupdate SKIPPED" echo -n "hcledit " && hcledit version 2>/dev/null || echo "hcledit SKIPPED" EOF diff --git a/Dockerfile b/Dockerfile index fcf33f2a9..83d0bc05b 100644 --- a/Dockerfile +++ b/Dockerfile @@ -181,6 +181,7 @@ RUN . /.env && \ (if [ "$TERRASCAN_VERSION" != "false" ]; then echo "terrascan $(./terrascan version)" >> $F; else echo "terrascan SKIPPED" >> $F ; fi) && \ (if [ "$TFLINT_VERSION" != "false" ]; then ./tflint --version >> $F; else echo "tflint SKIPPED" >> $F ; fi) && \ (if [ "$TFSEC_VERSION" != "false" ]; then echo "tfsec $(./tfsec --version)" >> $F; else echo "tfsec SKIPPED" >> $F ; fi) && \ + (if [ "$TRIVY_VERSION" != "false" ]; then echo "trivy $(./trivy --version)" >> $F; else echo "trivy SKIPPED" >> $F ; fi) && \ (if [ "$TFUPDATE_VERSION" != "false" ]; then echo "tfupdate $(./tfupdate --version)" >> $F; else echo "tfupdate SKIPPED" >> $F ; fi) && \ (if [ "$HCLEDIT_VERSION" != "false" ]; then echo "hcledit $(./hcledit version)" >> $F; else echo "hcledit SKIPPED" >> $F ; fi) && \ echo -e "\n\n" && cat $F && echo -e "\n\n" diff --git a/README.md b/README.md index 7d7be2dea..dcafd39e1 100644 --- a/README.md +++ b/README.md @@ -18,8 +18,6 @@ Automated provisioning of Terraform workflows and Infrastructure as Code.
infracost - - Cloud cost estimates for Terraform. If you are using `pre-commit-terraform` already or want to support its development and [many other open-source projects](https://github.com/antonbabenko/terraform-aws-devops), please become a [GitHub Sponsor](https://github.com/sponsors/antonbabenko)! @@ -64,8 +62,6 @@ If you are using `pre-commit-terraform` already or want to support its developme ### 1. Install dependencies - - * [`pre-commit`](https://pre-commit.com/#install), [`terraform`](https://www.terraform.io/downloads.html), [`git`](https://git-scm.com/downloads), @@ -102,7 +98,8 @@ All available tags [here](https://github.com/antonbabenko/pre-commit-terraform/p **Build from scratch**: -> **Note**: To build image you need to have [`docker buildx`](https://docs.docker.com/build/install-buildx/) enabled as default builder. +> [!IMPORTANT] +> To build image you need to have [`docker buildx`](https://docs.docker.com/build/install-buildx/) enabled as default builder. > Otherwise - provide `TARGETOS` and `TARGETARCH` as additional `--build-arg`'s to `docker build`. When hooks-related `--build-arg`s are not specified, only the latest version of `pre-commit` and `terraform` will be installed. @@ -195,7 +192,8 @@ curl -L "$(curl -s https://api.github.com/repos/minamijoyo/hcledit/releases/late We highly recommend using [WSL/WSL2](https://docs.microsoft.com/en-us/windows/wsl/install) with Ubuntu and following the Ubuntu installation guide. Or use Docker. -> **Note**: We won't be able to help with issues that can't be reproduced in Linux/Mac. +> [!IMPORTANT] +> We won't be able to help with issues that can't be reproduced in Linux/Mac. > So, try to find a working solution and send PR before open an issue. Otherwise, you can follow [this gist](https://gist.github.com/etiennejeanneaurevolve/1ed387dc73c5d4cb53ab313049587d09): @@ -211,11 +209,10 @@ E.g. `C:\Users\USERNAME\AppData\Local\Programs\Python\Python39\Lib\site-packages - - ### 2. Install the pre-commit hook globally -> **Note**: not needed if you use the Docker image +> [!NOTE] +> Not needed if you use the Docker image ```bash DIR=~/.git-template @@ -249,7 +246,8 @@ pre-commit run -a Or, using Docker ([available tags](https://github.com/antonbabenko/pre-commit-terraform/pkgs/container/pre-commit-terraform/versions)): -> **Note**: This command uses your user id and group id for the docker container to use to access the local files. If the files are owned by another user, update the `USERID` environment variable. See [File Permissions section](#file-permissions) for more information. +> [!TIP] +> This command uses your user id and group id for the docker container to use to access the local files. If the files are owned by another user, update the `USERID` environment variable. See [File Permissions section](#file-permissions) for more information. ```bash TAG=latest @@ -267,7 +265,6 @@ 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` | @@ -278,7 +275,7 @@ There are several [pre-commit](https://pre-commit.com/) hooks to keep Terraform | `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/tree/master/docs/rules#rules). [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_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` | @@ -286,7 +283,6 @@ There are several [pre-commit](https://pre-commit.com/) hooks to keep Terraform | `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` | - Check the [source file](https://github.com/antonbabenko/pre-commit-terraform/blob/master/.pre-commit-hooks.yaml) to know arguments used for each hook. @@ -302,7 +298,8 @@ Terraform operates on a per-dir basis, while `pre-commit` framework only support You can use environment variables for the `--args` section. -> **Warning**: You _must_ use the `${ENV_VAR}` definition, `$ENV_VAR` will not expand. +> [!IMPORTANT] +> You _must_ use the `${ENV_VAR}` definition, `$ENV_VAR` will not expand. Config example: @@ -390,7 +387,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files - --args=--path=./env/dev verbose: true # Always show costs ``` - +
Output ```bash @@ -405,7 +402,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files 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: @@ -429,7 +426,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files - --hook-config='.projects[].diff.totalMonthlyCost|tonumber != 10000' - --hook-config='.currency == "USD"' ``` - +
Output ```bash @@ -448,7 +445,7 @@ Unlike most other hooks, this hook triggers once if there are any changed files Total Monthly Cost: 86.83 USD Total Monthly Cost (diff): 86.83 USD ``` - +
* Only one path per one hook (`- id: infracost_breakdown`) is allowed. @@ -511,7 +508,8 @@ Unlike most other hooks, this hook triggers once if there are any changed files - --args=--config=.terraform-docs.yml ``` - > **Warning**: Avoid use `recursive.enabled: true` in config file, that can cause unexpected behavior. + > **Warning** + > Avoid use `recursive.enabled: true` in config file, that can cause unexpected behavior. 5. If you need some exotic settings, it can be done too. I.e. this one generates HCL files: @@ -563,12 +561,16 @@ To replicate functionality in `terraform_docs` hook: ### terraform_providers_lock -> **Note**: The hook requires Terraform 0.14 or later. +> [!NOTE] +> The hook requires Terraform 0.14 or later. -> **Note**: The hook can invoke `terraform providers lock` that can be really slow and requires fetching metadata from remote Terraform registries - not all of that metadata is currently being cached by Terraform. +> [!NOTE] +> The hook can invoke `terraform providers lock` that can be really slow and requires fetching metadata from remote Terraform registries - not all of that metadata is currently being cached by Terraform. ->
Note: Read this if you used this hook before v1.80.0 | Planned breaking changes in v2.0 -> We introduced '--mode' flag for this hook. If you'd like to continue using this hook as before, please: +> [!NOTE] +>
Read this if you used this hook before v1.80.0 | Planned breaking changes in v2.0 +>
+> We introduced `--mode` flag for this hook. If you'd like to continue using this hook as before, please: > > * Specify `--hook-config=--mode=always-regenerate-lockfile` in `args:` > * Before `terraform_providers_lock`, add `terraform_validate` hook with `--hook-config=--retry-once-with-cleanup=true` @@ -605,7 +607,8 @@ To replicate functionality in `terraform_docs` hook: * `only-check-is-current-lockfile-cross-platform` with [terraform_validate hook](#terraform_validate) - make up-to-date lockfile by adding/removing providers and only then check that lockfile has all required SHAs. - > **Note**: Next `terraform_validate` flag requires additional dependency to be installed: `jq`. Also, it could run another slow and time consuming command - `terraform init` + > **Important** + > Next `terraform_validate` flag requires additional dependency to be installed: `jq`. Also, it could run another slow and time consuming command - `terraform init` ```yaml - id: terraform_validate @@ -654,9 +657,10 @@ To replicate functionality in `terraform_docs` hook: `terraform_providers_lock` hook will try to reinitialize directories before running the `terraform providers lock` command. -5. `terraform_providers_lock` support passing custom arguments to its `terraform init`: +3. `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` + > **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` ```yaml - id: terraform_providers_lock @@ -826,9 +830,11 @@ To replicate functionality in `terraform_docs` hook: - --hook-config=--retry-once-with-cleanup=true # Boolean. true or false ``` - > **Note**: The flag requires additional dependency to be installed: `jq`. + > **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. + > **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: @@ -838,7 +844,8 @@ To replicate functionality in `terraform_docs` hook: * "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. + > **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** @@ -856,9 +863,10 @@ To replicate functionality in `terraform_docs` hook: `terraform_validate` hook will try to reinitialize them before running the `terraform validate` command. - **Warning**: 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. + > **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. -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. +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. 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: @@ -907,7 +915,8 @@ To replicate functionality in `terraform_docs` hook: [...] ``` - > Note: 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. + > **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 @@ -1030,7 +1039,8 @@ machine github.com login ghp_bl481aBlabl481aBla ``` -> **Note**: The value of `GITHUB_SERVER_HOSTNAME` can also refer to a GitHub Enterprise server (i.e. `github.my-enterprise.com`). +> [!TIP] +> The value of `GITHUB_SERVER_HOSTNAME` can also refer to a GitHub Enterprise server (i.e. `github.my-enterprise.com`). Finally, you can execute `docker run` with an additional volume mount so that the `~/.netrc` is accessible within the container @@ -1045,7 +1055,6 @@ docker run --rm -e "USERID=$(id -u):$(id -g)" -v ~/.netrc:/root/.netrc -v $(pwd) This repository is managed by [Anton Babenko](https://github.com/antonbabenko) with help from these awesome contributors: - @@ -1059,8 +1068,6 @@ This repository is managed by [Anton Babenko](https://github.com/antonbabenko) w - - ## License MIT licensed. See [LICENSE](LICENSE) for full details.