docs(readme): add terraform docs automation (#27)

* docs(readme): add terraform docs automation
Add terraform docs script along with makefile target and gihub action for same

Signed-off-by: Timothy MacDonald <tim.macdonald@lacework.net>

* docs(readme): automate update and testing of README.md by terraform-docs
Add github action to test that README.md has been update. Also add update of README.md to /scripts/release.sh prepare

Signed-off-by: Timothy MacDonald <tim.macdonald@lacework.net>

---------

Signed-off-by: Timothy MacDonald <tim.macdonald@lacework.net>

.github/workflows/terraform_docs.yml

@@ -0,0 +1,29 @@
+name: Test that terraform docs has been run
+on: push
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v3
+      with:
+        ref: ${{ github.event.pull_request.head.ref }}
+    - name: Install terraform-docs
+      run: curl -L https://github.com/terraform-docs/terraform-docs/releases/download/v0.16.0/terraform-docs-v0.16.0-linux-amd64.tar.gz | (cd /usr/local/bin; tar zxvf -; chmod +x /usr/local/bin/terraform-docs)
+    - name: store hash of orig README.md
+      id: old_hash
+      run: echo "README_HASH=$(md5sum README.md)" >> $GITHUB_OUTPUT
+    - name: Update README.md using terraform-docs make target
+      run: make terraform-docs
+    - name: store hash of new README.md
+      id: new_hash
+      run: echo "README_HASH=$(md5sum README.md)" >> $GITHUB_OUTPUT
+    - name: echo hashes
+      run: |
+        echo ${{ steps.old_hash.outputs.README_HASH }}
+        echo ${{ steps.new_hash.outputs.README_HASH }}
+    - name: test to see of hashs are the same
+      if: ${{ steps.old_hash.outputs.README_HASH != steps.new_hash.outputs.README_HASH }}
+      uses: actions/github-script@v6
+      with:
+        script: |
+          core.setFailed('Please run "make terraform-docs" and try again')

.terraform-docs.yml

@@ -0,0 +1,4 @@
+formatter: "markdown"
+version: "0.16.0"
+output:
+  file: README.md

GNUmakefile

@@ -15,3 +15,8 @@ ci: ## *CI ONLY* Runs tests on CI pipeline
 .PHONY: release
 release: ci ## *CI ONLY* Prepares a release of the Terraform module
 	scripts/release.sh prepare
+
+.PHONY: terraform-docs
+terraform-docs:
+	scripts/terraform-docs.sh
+

README.md

@@ -7,31 +7,32 @@
 
 A Terraform Module for configuring an integration with Lacework and AWS for CloudTrail analysis for organizations using AWS Control Tower.
 
+<!-- BEGIN_TF_DOCS -->
 ## Requirements
 
 | Name | Version |
 |------|---------|
-| terraform | >= 0.15.1 |
-| aws | ~> 3.0 |
-| lacework | ~> 0.2 |
-| random | >= 2.1 |
-| time | ~> 0.6 |
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 0.15.1 |
+| <a name="requirement_aws"></a> [aws](#requirement\_aws) | >= 3.0, < 5.0.0 |
+| <a name="requirement_lacework"></a> [lacework](#requirement\_lacework) | ~> 1.0 |
+| <a name="requirement_random"></a> [random](#requirement\_random) | >= 2.1 |
+| <a name="requirement_time"></a> [time](#requirement\_time) | ~> 0.6 |
 
 ## Providers
 
 | Name | Version |
 |------|---------|
-| aws.audit | ~> 3.0 |
-| aws.log\_archive | ~> 3.0 |
-| lacework | ~> 0.2 |
-| random | >= 2.1 |
-| time | ~> 0.6 |
+| <a name="provider_aws.audit"></a> [aws.audit](#provider\_aws.audit) | >= 3.0, < 5.0.0 |
+| <a name="provider_aws.log_archive"></a> [aws.log\_archive](#provider\_aws.log\_archive) | >= 3.0, < 5.0.0 |
+| <a name="provider_lacework"></a> [lacework](#provider\_lacework) | ~> 1.0 |
+| <a name="provider_random"></a> [random](#provider\_random) | >= 2.1 |
+| <a name="provider_time"></a> [time](#provider\_time) | ~> 0.6 |
 
 ## Modules
 
 | Name | Source | Version |
 |------|--------|---------|
-| lacework\_ct\_iam\_role | lacework/iam-role/aws | ~> 0.1 |
+| <a name="module_lacework_ct_iam_role"></a> [lacework\_ct\_iam\_role](#module\_lacework\_ct\_iam\_role) | lacework/iam-role/aws | ~> 0.4 |
 
 ## Resources
 
@@ -46,37 +47,41 @@ A Terraform Module for configuring an integration with Lacework and AWS for Clou
 | [random_id.uniq](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/id) | resource |
 | [time_sleep.wait_time](https://registry.terraform.io/providers/hashicorp/time/latest/docs/resources/sleep) | resource |
 | [aws_iam_policy_document.cross_account_policy](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+| [aws_iam_policy_document.kms_decrypt](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+| [aws_iam_policy_document.read_logs](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/iam_policy_document) | data source |
+| [aws_organizations_organization.main](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/data-sources/organizations_organization) | data source |
 
 ## Inputs
 
 | Name | Description | Type | Default | Required |
 |------|-------------|------|---------|:--------:|
-| s3\_bucket\_arn | The ARN for the  S3 bucket for consolidated CloudTrail logging. Usually in the form like: arn:aws:s3:::aws-controltower-logs-<log\_archive\_account\_id>-<control\_tower\_region> | `string` | n/a | yes |
-| sns\_topic\_arn | The SNS topic ARN. Usually in the form of: arn:aws:sns:<control-tower-region>:<aws\_audit\_account\_id>:aws-controltower-AllConfigNotifications | `string` | n/a | yes |
-| cross\_account\_policy\_name | n/a | `string` | `""` | no |
-| enable\_log\_file\_validation | Specifies whether cloudtrail log file integrity validation is enabled | `bool` | `false` | no |
-| iam\_role\_arn | The IAM role ARN is required when setting use\_existing\_iam\_role to true | `string` | `""` | no |
-| iam\_role\_external\_id | The external ID configured inside the IAM role is required when setting use\_existing\_iam\_role to true | `string` | `""` | no |
-| iam\_role\_name | The IAM role name. Required to match with iam\_role\_arn if use\_existing\_iam\_role is set to true | `string` | `""` | no |
-| lacework\_aws\_account\_id | The Lacework AWS account that the IAM role will grant access | `string` | `"434813966438"` | no |
-| lacework\_integration\_name | The name of the integration in Lacework. | `string` | `"TF cloudtrail"` | no |
-| org\_account\_mappings | Mapping of AWS accounts to Lacework accounts within a Lacework organization | <pre>list(object({<br>    default_lacework_account = string<br>    mapping = list(object({<br>      lacework_account = string<br>      aws_accounts     = list(string)<br>    }))<br>  }))</pre> | `[]` | no |
-| prefix | The prefix that will be use at the beginning of every generated resource | `string` | `"lacework-ct"` | no |
-| sqs\_queue\_name | The SQS queue name | `string` | `""` | no |
-| tags | A map/dictionary of Tags to be assigned to created resources | `map(string)` | `{}` | no |
-| use\_existing\_iam\_role | Set this to true to use an existing IAM role | `bool` | `false` | no |
-| wait\_time | Amount of time to wait before the next resource is provisioned. | `string` | `"10s"` | no |
-| kms\_key\_arn | Control Tower KMS key arn | `string` | `""` | no |
-
+| <a name="input_cross_account_policy_name"></a> [cross\_account\_policy\_name](#input\_cross\_account\_policy\_name) | n/a | `string` | `""` | no |
+| <a name="input_enable_log_file_validation"></a> [enable\_log\_file\_validation](#input\_enable\_log\_file\_validation) | Specifies whether cloudtrail log file integrity validation is enabled | `bool` | `false` | no |
+| <a name="input_external_id_length"></a> [external\_id\_length](#input\_external\_id\_length) | **Deprecated** - Will be removed on our next major release v1.0.0 | `number` | `16` | no |
+| <a name="input_iam_role_arn"></a> [iam\_role\_arn](#input\_iam\_role\_arn) | The IAM role ARN is required when setting use\_existing\_iam\_role to true | `string` | `""` | no |
+| <a name="input_iam_role_external_id"></a> [iam\_role\_external\_id](#input\_iam\_role\_external\_id) | The external ID configured inside the IAM role is required when setting use\_existing\_iam\_role to true | `string` | `""` | no |
+| <a name="input_iam_role_name"></a> [iam\_role\_name](#input\_iam\_role\_name) | The IAM role name. Required to match with iam\_role\_arn if use\_existing\_iam\_role is set to true | `string` | `""` | no |
+| <a name="input_kms_key_arn"></a> [kms\_key\_arn](#input\_kms\_key\_arn) | The KMS key arn, if Control Tower was deployed with custom KMS key | `string` | `""` | no |
+| <a name="input_lacework_aws_account_id"></a> [lacework\_aws\_account\_id](#input\_lacework\_aws\_account\_id) | The Lacework AWS account that the IAM role will grant access | `string` | `"434813966438"` | no |
+| <a name="input_lacework_integration_name"></a> [lacework\_integration\_name](#input\_lacework\_integration\_name) | The name of the integration in Lacework. | `string` | `"TF cloudtrail"` | no |
+| <a name="input_org_account_mappings"></a> [org\_account\_mappings](#input\_org\_account\_mappings) | Mapping of AWS accounts to Lacework accounts within a Lacework organization | <pre>list(object({<br>    default_lacework_account = string<br>    mapping = list(object({<br>      lacework_account = string<br>      aws_accounts     = list(string)<br>    }))<br>  }))</pre> | `[]` | no |
+| <a name="input_prefix"></a> [prefix](#input\_prefix) | The prefix that will be use at the beginning of every generated resource | `string` | `"lacework-ct"` | no |
+| <a name="input_s3_bucket_arn"></a> [s3\_bucket\_arn](#input\_s3\_bucket\_arn) | The ARN for the  S3 bucket for consolidated CloudTrail logging. Usually in the form like: arn:aws:s3:::aws-controltower-logs-<log\_archive\_account\_id>-<control\_tower\_region> | `string` | n/a | yes |
+| <a name="input_sns_topic_arn"></a> [sns\_topic\_arn](#input\_sns\_topic\_arn) | The SNS topic ARN. Usually in the form of: arn:aws:sns:<control-tower-region>:<aws\_audit\_account\_id>:aws-controltower-AllConfigNotifications | `string` | n/a | yes |
+| <a name="input_sqs_queue_name"></a> [sqs\_queue\_name](#input\_sqs\_queue\_name) | The SQS queue name | `string` | `""` | no |
+| <a name="input_tags"></a> [tags](#input\_tags) | A map/dictionary of Tags to be assigned to created resources | `map(string)` | `{}` | no |
+| <a name="input_use_existing_iam_role"></a> [use\_existing\_iam\_role](#input\_use\_existing\_iam\_role) | Set this to true to use an existing IAM role from the log\_archive AWS Account | `bool` | `false` | no |
+| <a name="input_wait_time"></a> [wait\_time](#input\_wait\_time) | Amount of time to wait before the next resource is provisioned. | `string` | `"10s"` | no |
 
 ## Outputs
 
 | Name | Description |
 |------|-------------|
-| external\_id | The External ID configured into the IAM role |
-| iam\_role\_arn | The IAM Role ARN |
-| iam\_role\_name | The IAM Role name |
-| sns\_arn | SNS Topic ARN |
-| sqs\_arn | SQS Queue ARN |
-| sqs\_name | SQS Queue name |
-| sqs\_url | SQS Queue URL |
+| <a name="output_external_id"></a> [external\_id](#output\_external\_id) | The External ID configured into the IAM role |
+| <a name="output_iam_role_arn"></a> [iam\_role\_arn](#output\_iam\_role\_arn) | The IAM Role ARN |
+| <a name="output_iam_role_name"></a> [iam\_role\_name](#output\_iam\_role\_name) | The IAM Role name |
+| <a name="output_sns_arn"></a> [sns\_arn](#output\_sns\_arn) | SNS Topic ARN |
+| <a name="output_sqs_arn"></a> [sqs\_arn](#output\_sqs\_arn) | SQS Queue ARN |
+| <a name="output_sqs_name"></a> [sqs\_name](#output\_sqs\_name) | SQS Queue name |
+| <a name="output_sqs_url"></a> [sqs\_url](#output\_sqs\_url) | SQS Queue URL |
+<!-- END_TF_DOCS -->

scripts/release_helpers.sh

@@ -1,6 +1,6 @@
 #
 # Name::        release_helpers.sh
-# Description:: A set of helper funtions to be used by our release.sh script
+# Description:: A set of helper functions to be used by our release.sh script
 # Author::      Salim Afiune Maya (<afiune@lacework.net>)
 #
 
@@ -137,6 +137,7 @@ prepare_release() {
   prerequisites
   remove_tag_version
   check_for_minor_version_bump
+  generate_readme
   generate_release_notes
   update_changelog
   push_release
@@ -192,6 +193,10 @@ generate_release_notes() {
   echo "$(cat CHANGES.md)" >> RELEASE_NOTES.md
 }
 
+generate_readme() {
+  make terraform-docs
+}
+
 load_list_of_changes() {
   latest_version=$(find_latest_version)
   local _list_of_changes=$(git log --no-merges --pretty="* %s (%an)([%h](https://github.com/${org_name}/${project_name}/commit/%H))" ${latest_version}..${main_branch})

scripts/terraform-docs.sh

@@ -0,0 +1,13 @@
+
+if which terraform-docs >/dev/null; then
+    terraform-docs .
+elif which docker >/dev/null; then
+    echo "## terraform-docs not found in PATH, but docker was found"
+    echo "## running terraform-docs in docker"
+    terraform_docs_version=$(cat .terraform-docs.yml | grep version | cut -d\" -f 2)
+    docker run --rm -v `pwd`:/data cytopia/terraform-docs:${terraform_docs_version} terraform-docs .
+else
+    echo "## terraform-docs not found in PATH, neither was docker"
+    echo "## please install terraform-docs or docker"
+    exit 1
+fi