feat: updatetemplate (#35)

.github/actions/docs-check/action.yml

@@ -4,33 +4,47 @@ description: Checks that documentation has been updated on PR
 runs:
   using: composite
   steps:
-    - name: Setup go
+    - name: setup go
       uses: actions/setup-go@v4
       with:
         go-version: "1.21.x"
         # cache-dependency-path: tests/go.sum
 
-    - name: Setup Terraform
+    - name: setup Terraform
       uses: hashicorp/setup-terraform@v2
       with:
         terraform_wrapper: false
 
-    - name: Install tools
-      run: make tools
+    - name: install tools
       shell: bash
+      run: |
+        go install github.com/katbyte/terrafmt@latest
+        go install github.com/terraform-docs/terraform-docs@latest
+
+    - name: fmt check
+      shell: bash
+      run: |
+        echo "==> Fixing Terraform code with terraform fmt..."
+        terraform fmt -recursive
+        echo "==> Fixing embedded Terraform with terrafmt..."
+        find . | egrep ".md|.tf" | grep -v README.md | sort | while read f; do terrafmt fmt $$f; done
 
-    - name: Check fmt and docs
+    - name: docs check
+      shell: bash
+      run: |
+        echo "==> Generating module documentation..."
+        terraform-docs -c .terraform-docs.yml .
+        echo "==> Generating examples documentation..."
+        cd examples && for d in $(ls -d */); do terraform-docs $d; done
+
+    - name: check for changes
       shell: bash
       run: |
-        echo "==> Running make fmt & make docs"
-        make fmt
-        make docs
         echo "==> Testing for changes to tracked files"
         CHANGES=$(git status -suno)
         if [ "$CHANGES" ]; then
           echo "Repository formatting or documentation is not correct."
-          echo "$CHANGES"
-          echo "Diff:"
+          echo
           git diff
           echo
           echo "Run 'make fmt && make docs' locally and commit the changes to fix."

.github/workflows/e2e.yml

@@ -30,6 +30,7 @@ jobs:
     environment: test
     env:
       TF_IN_AUTOMATION: 1
+      TF_VAR_enable_telemetry: false
     strategy:
       matrix:
         example: ${{ fromJson(needs.getexamples.outputs.examples) }}
@@ -43,7 +44,7 @@ jobs:
           tenant-id: ${{ secrets.AZURE_TENANT_ID }}
           subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
 
-      - name: test example
+      - name: Test example
         uses: Azure/terraform-azurerm-avm-template/.github/actions/e2e-testexamples@main
         with:
           example: ${{ matrix.example }}

.github/workflows/linting.yml

@@ -11,12 +11,12 @@ permissions:
   contents: read
 
 concurrency:
-  group: docsfmttest-${{ github.event.pull_request.head.repo.full_name }}/${{ github.head_ref || github.run_id }}
+  group: linting-${{ github.event.pull_request.head.repo.full_name }}/${{ github.head_ref || github.run_id }}
   cancel-in-progress: true
 
 jobs:
-  docsfmttest:
-    name: docs-check
+  linting:
+    name: linting
     runs-on: ubuntu-latest
     steps:
       - name: checkout repository

Makefile

@@ -1,6 +1,9 @@
 .PHONY: docs
 docs:
+	@echo "==> Generating module documentation..."
 	terraform-docs -c .terraform-docs.yml .
+	@echo "==> Generating examples documentation..."
+	cd examples && for d in $$(ls -d */); do terraform-docs  $$d; done
 
 .PHONY: fmt
 fmt:

README.md

@@ -3,7 +3,17 @@
 
 This is a template repo for Terraform Azure Verified Modules.
 
-TODO: Provide instructions or links to spec to explain how to use this template.
+Things to do:
+
+1. Set up a GitHub repo environment called `test`.
+1. Configure environment protection rule to ensure that approval is required before deploying to this environment.
+1. Create a user-assigned managed identity in your test subscription.
+1. Create a role assignment for the managed identity on your test subscription, use the minimum required role.
+1. Configure federated identity credentials on the user assigned managed identity. Use the GitHub environment.
+1. Create the following environment secrets on the `test` environment:
+   1. AZURE\_CLIENT\_ID
+   1. AZURE\_TENANT\_ID
+   1. AZURE\_SUBSCRIPTION\_ID
 
 <!-- markdownlint-disable MD033 -->
 ## Requirements
@@ -49,7 +59,7 @@ The following input variables are optional (have default values):
 ### <a name="input_enable_telemetry"></a> [enable\_telemetry](#input\_enable\_telemetry)
 
 Description: This variable controls whether or not telemetry is enabled for the module.  
-For more information see https://aka.ms/avm/telemetry.  
+For more information see https://aka.ms/avm/telemetryinfo.  
 If it is set to false, then no telemetry will be collected.
 
 Type: `bool`

examples/.terraform-docs.yml

@@ -0,0 +1,69 @@
+### To generate the output file to partially incorporate in the README.md,
+### Execute this command in the Terraform module's code folder:
+# terraform-docs -c .terraform-docs.yml .
+
+formatter: "markdown document" # this is required
+
+version: "0.16.0"
+
+header-from: "_header.md"
+
+recursive:
+  enabled: false
+  path: modules
+
+sections:
+  hide: []
+  show: []
+
+content: |-
+  {{ .Header }}
+
+  ```hcl
+  {{ include "main.tf" }}
+  ```
+
+  <!-- markdownlint-disable MD033 -->
+  {{ .Requirements }}
+
+  {{ .Providers }}
+
+  {{ .Resources }}
+
+  <!-- markdownlint-disable MD013 -->
+  {{ .Inputs }}
+
+  {{ .Outputs }}
+
+  {{ .Modules }}
+
+  {{ .Footer }}
+output:
+  file: README.md
+  mode: replace
+  template: |-
+    <!-- BEGIN_TF_DOCS -->
+    {{ .Content }}
+    <!-- END_TF_DOCS -->
+output-values:
+  enabled: false
+  from: ""
+
+sort:
+  enabled: true
+  by: required
+
+settings:
+  anchor: true
+  color: true
+  default: true
+  description: false
+  escape: true
+  hide-empty: false
+  html: true
+  indent: 2
+  lockfile: false
+  read-comments: true
+  required: true
+  sensitive: true
+  type: true

examples/README.md

@@ -1,6 +1,8 @@
 # Examples
 
-Create a directory for each example.
-Create a README.md file in each directory to help consumers understand the example.
+- Create a directory for each example.
+- Create a `_header.md` file in each directory to describe the example.
+- See the `default` example provided as a skeleton - this must remain, but you can add others.
+- Run `make fmt && make docs` from the repo root to generate the required documentation.
 
-> **Note:** Examples must be deployable and idempotent. Ensure that no input variables are requried to run the example and that random values are used to ensure unique resource names. E.g. use `random_pet` to generate a unique name for a resource.
+> **Note:** Examples must be deployable and idempotent. Ensure that no input variables are required to run the example and that random values are used to ensure unique resource names. E.g. use the [naming module](https://registry.terraform.io/modules/Azure/naming/azurerm/latest) to generate a unique name for a resource.

examples/default/README.md

@@ -0,0 +1,109 @@
+<!-- BEGIN_TF_DOCS -->
+# Default example
+
+This deploys the module in its simplest form.
+
+```hcl
+terraform {
+  required_version = ">= 1.0.0"
+  required_providers {
+    azurerm = {
+      source  = "hashicorp/azurerm"
+      version = ">= 3.7.0, < 4.0.0"
+    }
+  }
+}
+
+variable "enable_telemetry" {
+  type        = bool
+  default     = true
+  description = <<DESCRIPTION
+This variable controls whether or not telemetry is enabled for the module.
+For more information see https://aka.ms/avm/telemetryinfo.
+If it is set to false, then no telemetry will be collected.
+DESCRIPTION
+}
+
+# This ensures we have unique CAF compliant names for our resources.
+module "naming" {
+  source  = "Azure/naming/azurerm"
+  version = "0.3.0"
+}
+
+# This is required for resource modules
+resource "azurerm_resource_group" "this" {
+  name     = module.naming.resource_group.name_unique
+  location = "MYLOCATION"
+}
+
+# This is the module call
+module "MYMODULE" {
+  source = "../../"
+  # source             = "Azure/avm-<res/ptn>-<name>/azurerm"
+  enable_telemetry = var.enable_telemetry
+  # ...
+}
+```
+
+<!-- markdownlint-disable MD033 -->
+## Requirements
+
+The following requirements are needed by this module:
+
+- <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) (>= 1.0.0)
+
+- <a name="requirement_azurerm"></a> [azurerm](#requirement\_azurerm) (>= 3.7.0, < 4.0.0)
+
+## Providers
+
+The following providers are used by this module:
+
+- <a name="provider_azurerm"></a> [azurerm](#provider\_azurerm) (>= 3.7.0, < 4.0.0)
+
+## Resources
+
+The following resources are used by this module:
+
+- [azurerm_resource_group.this](https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/resources/resource_group) (resource)
+
+<!-- markdownlint-disable MD013 -->
+## Required Inputs
+
+No required inputs.
+
+## Optional Inputs
+
+The following input variables are optional (have default values):
+
+### <a name="input_enable_telemetry"></a> [enable\_telemetry](#input\_enable\_telemetry)
+
+Description: This variable controls whether or not telemetry is enabled for the module.  
+For more information see https://aka.ms/avm/telemetryinfo.  
+If it is set to false, then no telemetry will be collected.
+
+Type: `bool`
+
+Default: `true`
+
+## Outputs
+
+No outputs.
+
+## Modules
+
+The following Modules are called:
+
+### <a name="module_MYMODULE"></a> [MYMODULE](#module\_MYMODULE)
+
+Source: ../../
+
+Version:
+
+### <a name="module_naming"></a> [naming](#module\_naming)
+
+Source: Azure/naming/azurerm
+
+Version: 0.3.0
+
+
+<!-- END_TF_DOCS -->

examples/default/_header.md

@@ -0,0 +1,3 @@
+# Default example
+
+This deploys the module in its simplest form.

examples/default/main.tf

@@ -0,0 +1,39 @@
+terraform {
+  required_version = ">= 1.0.0"
+  required_providers {
+    azurerm = {
+      source  = "hashicorp/azurerm"
+      version = ">= 3.7.0, < 4.0.0"
+    }
+  }
+}
+
+variable "enable_telemetry" {
+  type        = bool
+  default     = true
+  description = <<DESCRIPTION
+This variable controls whether or not telemetry is enabled for the module.
+For more information see https://aka.ms/avm/telemetryinfo.
+If it is set to false, then no telemetry will be collected.
+DESCRIPTION
+}
+
+# This ensures we have unique CAF compliant names for our resources.
+module "naming" {
+  source  = "Azure/naming/azurerm"
+  version = "0.3.0"
+}
+
+# This is required for resource modules
+resource "azurerm_resource_group" "this" {
+  name     = module.naming.resource_group.name_unique
+  location = "MYLOCATION"
+}
+
+# This is the module call
+module "MYMODULE" {
+  source = "../../"
+  # source             = "Azure/avm-<res/ptn>-<name>/azurerm"
+  enable_telemetry = var.enable_telemetry
+  # ...
+}

variables.tf

@@ -3,7 +3,7 @@ variable "enable_telemetry" {
   default     = true
   description = <<DESCRIPTION
 This variable controls whether or not telemetry is enabled for the module.
-For more information see https://aka.ms/avm/telemetry.
+For more information see https://aka.ms/avm/telemetryinfo.
 If it is set to false, then no telemetry will be collected.
 DESCRIPTION
 }