diff --git a/README.md b/README.md index 14c3bcf..81e1fe8 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,11 @@ # tf_authoritative_scanner + ## Overview -`tfas` performs static analysis on Terraform files to detect the presence of authoritative resources (currently only GCP Terraform resources, but pull requests welcome). It scans a specified directory (and optionally hidden directories to inspect modules) for Terraform configuration files (.tf) and identifies lines containing these authoritative resources. +`tfas` performs static analysis on Terraform files to detect the presence of Terraformauthoritative resources (ARs). It scans a specified directory (and optionally hidden directories to inspect modules) for Terraform configuration files (.tf) and identifies lines containing these ARs. + +`tfast` is a Terraform porcelain (e.g. `tfast plan`). It will only run the specified Terraform command if `tfas` doesn't find any ARs. ### Background and Comments @@ -15,9 +18,9 @@ Authoritative Terraform resources should be used when setting up new infrastruct If you're working with existing infrastructure they should only be used once all infrastructure is being managed by Terraform. - ## Usage + ### Authoritative Resource Exceptions If you want to allow a specific usage of an authorized resource, add a comment with `terraform_authoritative_scanner_ok` and `tfas` won't alert on it. The comment can be on the line before the authoritative resource or inline. @@ -33,7 +36,18 @@ If you want to allow a specific usage of an authorized resource, add a comment w } ``` -### Running via Pre-Commit +### Installation + +```bash +$ poetry build +$ pipx install dist/tf_authoritative_scanner-1.0.X-py3-none-any.whl +``` + + +### `tfas` + + +#### Running via Pre-Commit Add the following to your `.pre-commit-config.yaml` file. @@ -46,17 +60,13 @@ Add the following to your `.pre-commit-config.yaml` file. Stage the file then run `pre-commit autoupdate` to grab the latest release. -### Running Interactively -#### Normal Usage +#### Running Interactively ```bash -$ poetry build -$ pip install dist/tf_authoritative_scanner-1.0.X-py3-none-any.whl - $ tfas -h -# help output ... + $ tfas ~/git/terraform_repo/ AUTHORITATIVE: ~/git/terraform_repo/project_red/iam.tf:10: resource "google_project_iam_binding" "compute_admin" { AUTHORITATIVE: ~/git/terraform_repo/project_blue/iam.tf:10: resource "google_project_iam_binding" "compute_admin" { @@ -66,15 +76,31 @@ $ echo $? $ ``` -#### Development + +### `tfast` + +```bash +cd ~/git/your_terraform_repo +tfast plan +tfast apply +``` + + + + + +## Development + +### Development ```bash $ poetry shell $ poetry install +# make changes to the code $ tfas +$ tfast ``` -## Development ### Version Bumping @@ -90,14 +116,14 @@ poetry version -h poetry version patch ``` + ### TODO - publish to pypi - surface confidence in verbose mode - add an option to show the list of authoritative resources checked for - provide links to documentation when an authoritative resource is detected -- terraform wrapper to ensure tfas protection earlier - - pre-commit not always run before applying + ## Relevant Links