update to current terraform-module-template structure (#10)

Signed-off-by: Andre Licht <[email protected]>

.github/CODEOWNERS

@@ -1 +1 @@
-*   @rswrz @lixhunter @Phil-Thoennissen
+*   @rswrz @lixhunter @Phil-Thoennissen @neonwhiskers

.github/ISSUE_TEMPLATE/bug-template.yml

@@ -0,0 +1,58 @@
+name: "Bug Report"
+description: "File a bug report."
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to fill out this bug report!
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: Bug Description
+      description: "Also tell us, what did you expect to happen?"
+      placeholder: "Tell us what you see!"
+    validations:
+      required: true
+  - type: textarea
+    id: version
+    attributes:
+      label: Terraform-Version
+      description: "What version of Terraform are you running?"
+      placeholder: "Output of 'terraform version'"
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: "Please copy and paste any relevant log output. This will be automatically formatted."
+      render: shell
+  - type: textarea
+    id: error-message
+    attributes:
+      label: Relevant Error Messages
+      description: "Please copy and paste any relevant error Messages. This will be automatically formatted."
+      render: shell
+  - type: textarea
+    id: additional-info
+    attributes:
+      label: Additional Information
+      description: "Please add any information that might be relevant in solving this bug."
+  - type: checkboxes
+    id: terms2
+    attributes:
+      label: Privacy Statement
+      description: "I acknowledge that this is a public repository and confirm that I have not included any sensitive customer data, internal information, or proprietary details in this report."
+      options:
+        - label: I agree
+          required: true
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: "By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/cloudeteer/terraform-governance?tab=coc-ov-file#code-of-conduct)."
+      options:
+        - label: I agree to follow this repository's Code of Conduct
+          required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

.github/ISSUE_TEMPLATE/feature-template.yml

@@ -0,0 +1,50 @@
+name: "Feature Request"
+description: "Suggest a new feature or improvement."
+title: "[Feature Request]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thank you for taking the time to suggest a feature or improvement!
+  - type: textarea
+    id: feature-description
+    attributes:
+      label: Feature Description
+      description: "Please describe the feature or improvement you would like to see."
+      placeholder: "Provide a detailed explanation of the feature."
+    validations:
+      required: true
+
+  - type: textarea
+    id: use-case
+    attributes:
+      label: Use Case
+      description: "What is the problem this feature will solve or the benefit it will provide? How would you use it?"
+      placeholder: "Explain the context and use case."
+    validations:
+      required: true
+
+  - type: textarea
+    id: additional-info
+    attributes:
+      label: Additional Information
+      description: "Any additional context or information that may help with this feature request."
+
+  - type: checkboxes
+    id: terms2
+    attributes:
+      label: Privacy Statement
+      description: "I acknowledge that this is a public repository and confirm that I have not included any sensitive customer data, internal information, or proprietary details in this request."
+      options:
+        - label: I agree
+          required: true
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Code of Conduct
+      description: "By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/cloudeteer/terraform-governance?tab=coc-ov-file#code-of-conduct)."
+      options:
+        - label: I agree to follow this repository's Code of Conduct
+          required: true

.pre-commit-config.yaml

@@ -6,16 +6,24 @@ repos:
       - id: end-of-file-fixer
       - id: trailing-whitespace
   - repo: https://github.com/terraform-docs/terraform-docs
-    rev: v0.18.0
+    rev: v0.19.0
     hooks:
       - id: terraform-docs-system
         args: ["."]
+  - repo: local
+    hooks:
+      - id: tfsort
+        name: Sort Terraform variables
+        language: system
+        types: [terraform]
+        entry: bash -c 'for f in $@; do tfsort "$f"; done' --
+        files: ^variables|outputs\.tf$
   - repo: https://github.com/antonbabenko/pre-commit-terraform
-    rev: "v1.92.0"
+    rev: "v1.96.1"
     hooks:
       - id: terraform_fmt
       - id: terraform_tflint
-        exclude: ^examples/
+        exclude: ^(examples|tests)/
         args:
           - --args=--config=__GIT_WORKING_DIR__/.tflint.hcl
           - --hook-config=--delegate-chdir
@@ -26,6 +34,15 @@ repos:
         args:
           - --args=--config=__GIT_WORKING_DIR__/.tflint.examples.hcl
           - --hook-config=--delegate-chdir
+
+      - id: terraform_tflint
+        alias: terraform_tflint_tests
+        name: Terraform validate tests with tflint
+        files: ^tests/
+        args:
+          - --args=--config=__GIT_WORKING_DIR__/.tflint.tests.hcl
+          - --hook-config=--delegate-chdir
+
       - id: terraform_trivy
         exclude: ^(examples|tests)/
         args:

.terraform-docs.yaml

@@ -4,6 +4,10 @@ settings:
   hide-empty: true
   lockfile: false
 
+recursive:
+  enabled: true
+  path: modules
+
 output:
   file: README.md
 

.tflint.tests.hcl

@@ -0,0 +1,21 @@
+tflint {
+  required_version = "~> 0.50"
+}
+
+plugin "azurerm" {
+  enabled = true
+  version = "0.27.0"
+  source  = "github.com/terraform-linters/tflint-ruleset-azurerm"
+}
+
+rule "terraform_required_version" {
+  enabled = false
+}
+
+rule "terraform_required_providers" {
+  enabled = false
+}
+
+rule "terraform_module_version" {
+  enabled = false
+}

Makefile

@@ -0,0 +1,53 @@
+SHELL := /usr/bin/env bash
+
+##
+# Console Colors
+##
+GREEN  := $(shell tput -Txterm setaf 2)
+YELLOW := $(shell tput -Txterm setaf 3)
+WHITE  := $(shell tput -Txterm setaf 7)
+CYAN   := $(shell tput -Txterm setaf 6)
+RESET  := $(shell tput -Txterm sgr0)
+
+.PHONY: help
+help: ## show this help.
+	@echo 'Usage:'
+	@echo '  ${GREEN}make${RESET} ${YELLOW}<target>${RESET}'
+	@echo ''
+	@echo 'Targets:'
+	@awk 'BEGIN {FS = ":.*?## "} { \
+		if (/^[a-zA-Z_-]+:.*?##.*$$/) {printf "  ${GREEN}%-21s${YELLOW}%s${RESET}\n", $$1, $$2} \
+		else if (/^## .*$$/) {printf "  ${CYAN}%s${RESET}\n", substr($$1,4)} \
+		}' $(MAKEFILE_LIST)
+
+.PHONY: test-examples
+test-examples: ## Run tests on examples
+	@echo "Running tests on examples"
+	terraform init -test-directory=tests/examples
+	terraform test -test-directory=tests/examples
+
+.PHONY: test-local
+test-local: ## Run tests on local
+	@echo "Running tests on local"
+	terraform init -test-directory=tests/local
+	terraform test -test-directory=tests/local
+
+.PHONY: test-remote
+test-remote: ## Run tests on remote
+	@echo "Running tests on remote"
+	terraform init -test-directory=tests/remote
+	terraform test -test-directory=tests/remote
+
+.PHONY: test
+test: test-examples test-local test-remote ## Run all tests
+
+.PHONY: docs
+docs: README.md ## Generate Terraform docs and update README.md
+
+ROOT_TF_FILES := $(wildcard *.tf)
+EXAMPLES_TF_FILES := $(shell find ./examples -name '*.tf')
+TF_FILES := $(ROOT_TF_FILES) $(EXAMPLES_TF_FILES)
+
+README.md: $(TF_FILES) .terraform-docs.yaml
+	@echo "Generating Terraform docs for README.md"
+	@terraform-docs  . --config .terraform-docs.yaml

README.md

@@ -7,8 +7,7 @@
 
 # terraform-azurerm-helloworld
 
-[![SemVer](https://img.shields.io/badge/SemVer-2.0.0-blue.svg)](CHANGELOG.md)
-[![Keep a Changelog](https://img.shields.io/badge/changelog-Keep%20a%20Changelog%20v1.0.0-%23E05735)](CHANGELOG.md)
+[![SemVer](https://img.shields.io/badge/SemVer-2.0.0-blue.svg)](https://github.com/cloudeteer/terraform-module-template/releases)
 
 Terraform "Hello World!" Module
 
@@ -27,7 +26,7 @@ module "example" {
 
 The following providers are used by this module:
 
-- <a name="provider_azurerm"></a> [azurerm](#provider\_azurerm) (~> 4.0)
+- <a name="provider_azurerm"></a> [azurerm](#provider\_azurerm) (>= 4.1)
 
 
 

examples/usage/README.md

@@ -0,0 +1,31 @@
+# Example: Usage
+
+This primary usage example is also included in the [README.md](../../README.md) of this module.
+
+## Prerequisites
+
+Before you begin, ensure you have the following:
+
+- [Terraform](https://www.terraform.io/downloads.html) installed on your local machine.
+
+## Steps to Deploy
+
+1. **Initialize the Terraform Configuration**
+
+   Initialize the Terraform configuration to download the necessary providers and modules.
+
+   ```shell
+   terraform init
+   ```
+
+2. **Apply the Terraform Configuration**
+
+   Apply the configuration to create the resources defined in your Terraform files.
+
+   ```shell
+   terraform apply
+   ```
+
+## Additional Resources
+
+- [Terraform Configuration Language](https://www.terraform.io/docs/language/index.html)

examples/usage/tests_override.tf

@@ -1,7 +1,7 @@
 # This override file is mandatory for Terraform tests.
 # Not needed to use this example.
-
 terraform {
+  # add all providers used in the module to run tests
   required_providers {
     azurerm = { source = "hashicorp/azurerm" }
   }

main.tf

@@ -1 +1,2 @@
+# added to verify azurerm provider is required
 data "azurerm_client_config" "current" {}

modules/README.md

@@ -0,0 +1,18 @@
+# Sub-modules
+
+Create directories for each sub-module as needed. The `README.md` files for each sub-module will be automatically generated using [terraform-docs](https://terraform-docs.io/user-guide/configuration/recursive/), just like the `README.md` of the primary module. Documentation generation requires a usage example in `./<module>/examples/usage/`, with a `main.tf` file defining the example and a `main.md` file briefly describing it.
+
+Thus, the minimal file structure of a module is:
+
+```tree
+.
+├── README.md
+├── examples
+│   └── usage
+│       ├── main.md
+│       └── main.tf
+├── inputs.tf
+├── main.tf
+├── outputs.tf
+└── terraform.tf
+```

outputs.tf

@@ -1,7 +1,7 @@
-output "hello_world" {
-  value = "Hello World!"
-}
-
 output "client_id" {
   value = data.azurerm_client_config.current.client_id
 }
+
+output "hello_world" {
+  value = "Hello World!"
+}

versions.tf → terraform.tf

@@ -1,10 +1,10 @@
 terraform {
-  required_version = "~> 1.0"
+  required_version = "~> 1.9"
 
   required_providers {
     azurerm = {
       source  = "hashicorp/azurerm"
-      version = "~> 4.0"
+      version = ">= 4.1"
     }
   }
 }

tests/README.md

@@ -4,27 +4,31 @@ This directory contains a set of Terraform tests categorized into `local`, `remo
 
 ## `./examples`
 
-This directory contains tests for all Terraform examples in `../examples`. Use the following commands to initialize and run the tests:
+This directory contains tests for all Terraform examples in `../examples`. The
+following command modifies the `source` path in each example, initializes the test
+directory, runs the tests.
 
 ```shell
-terraform init -test-directory=tests/examples
-terraform test -test-directory=tests/examples
+# Run from the root of the repository
+make test-examples
 ```
 
 ## `./local`
 
-This directory is for tests intended to run locally during development. Use the following commands to initialize and run the tests:
+This directory is for tests intended to run locally during development. Use the
+following commands to initialize and run the tests:
 
 ```shell
-terraform init -test-directory=tests/local
-terraform test -test-directory=tests/local
+# Run from the root of the repository
+make test-local
 ```
 
 ## `./remote`
 
-This directory contains tests designed to be executed by CI/CD pipelines. Use the following commands to initialize and run the tests:
+This directory contains tests designed to be executed by CI/CD pipelines. Use the
+following commands to initialize and run the tests:
 
 ```shell
-terraform init -test-directory=tests/remote
-terraform test -test-directory=tests/remote
+# Run from the root of the repository
+make test-remote
 ```