these are the pre-commit hooks used for this repo:

Table of Contents

• Down At The Bottom Of The Mole HoleTerraform module template
  • Table of Contents
  • About The Project
  • Built With
• Terraform
  • Requirements
  • Consuming Module_Name
  • Example 1
    • Resources
    • Inputs
    • Outputs
    • Modules
      • Automatically generated Terraform variables
        • Terraform versions
        • Installing Tfupdate
        • Terraform version
        • Azure Naming module version
        • AWS version
        • AzureAD version
        • AzureDevOps version
        • AzureRm version
        • Random version
        • Time version
  • terraform_module_template Usage
    • Creating your own terraform module using terraform_module_template
    • Backfitting terraform_module_template to an existing module
  • Roadmap
  • Contributing
    • Contributing Prerequisites
  • License
  • Contact

About The Project

This is a repository template to be used for all of Down At The Bottom Of The Mole Hole's Terraform modules.

(Back to the Table of Contents)

Built With

• cspell
• GitVersion
• Infracost
• Markdown
• Mermaid
• Pre-Commit
• pre-commit-terraform
• prettier
• Terraform
• Terraform-docs
• Terrascan
• tflint
• tfsec
• tfupdate

(Back to the Table of Contents)

Terraform

The below documentation was generated via Terraform docs using pre-commit

(Back to the Table of Contents)

Requirements

(Back to the Table of Contents)

Consuming Module_Name

To consume this module add the following to your module.tf:

module "Module_Name" {
	 source  = "github.com/DownAtTheBottomOfTheMoleHole/Module_Name.git"

	 # Required variables
	 application_name  = 
	 application_shortname  = 
	 azdo_pat  = 
	 azdo_project_name  = 
	 azdo_repo_name  = 
	 cag_division  = 
	 environment_tag  = 
	 resource_group_name  = 

	 # Optional variables
	 aws_access_key  = ""
	 aws_profile  = ""
	 aws_resource_location  = "eu-west-1"
	 aws_secret_key  = ""
	 azdo_orgurl  = null
	 azrm_client_id  = null
	 azrm_client_secret  = null
	 azrm_keyvault_whitelist  = []
	 azrm_resource_location  = "northeurope"
	 azrm_storage_whitelist  = []
	 azrm_subscription_id  = null
	 azrm_tenant_id  = null
	 default_tags  = {}
	 time_secret_expiry  = 100
	 time_spn_expiry  = 100
}

Example 1

##### Put your example Terraform code in this file and it will be displayed in the read me. ######

(Back to the Table of Contents)

Resources

(Back to the Table of Contents)

Inputs

(Back to the Table of Contents)

Outputs

{
  "ADO-Project": "project_name",
  "Application": "application_name",
  "Environment": "dev",
  "Managed-By": "Terraform",
  "Owner": "project_name Contributors",
  "Repository": "repo_name"
}

(Back to the Table of Contents)

Modules

(Back to the Table of Contents)

Automatically generated Terraform variables

This project uses terraform-docs to automatically generate tfvar files per environment that will allow you to have per environment values as well as common values.

the common values will reside in:

for the terraform directory (the terraform directory the pipelines refer to): .\environment\default.tfvars

Environment specific variables then reside in an environment specific folder under the terraform directory e.g. .\environment\dev\variables.tfvars

to generate these files do the following

1. Navigate to your terraform directory using command prompt or powershell
2. To generate environment specific variables run terraform-docs tfvars hcl . --output-file .\environment\poc\variables.tfvars --output-mode inject --read-comments --description --header-from ./terraform-docs/tf_header.txt --footer-from ./terraform-docs/tf_footer.txt replacing the environment foldername as appropriate
3. To generate the common variables file run terraform-docs tfvars hcl . --output-file .\environment\default.tfvars --output-mode inject --read-comments --description --header-from ./terraform-docs/tf_header.txt --footer-from ./terraform-docs/tf_footer.txt

Terraform versions

Terraform version and terraform provider versions have been set using tfupdate. In order to update the installed providers to the latest versions please first install tfupdate using the below instructions and then run the following commands from the root of the repo in a powershell session. Please only run the commands for the providers/modules you are using.

Installing Tfupdate

the tfupdate repo can be found here

either download the tarball and add tfupdate.exe to your PATH or do the following:

1. Ensure you have Go installed
2. Clone the repository locally git clone https://github.com/minamijoyo/tfupdate.git
3. build the source code with go build
4. Add the complied binaries to your PATH

Terraform version

tfupdate terraform . --version ">=$(tfupdate release latest hashicorp/terraform)" --recursive

please also add the terraform version to the terraform_installer_version variable in build/pipelines/iac_templates/variables.yml

Azure Naming module version

tfupdate module Azure/naming/azurerm . --version ">=$(tfupdate release latest Azure/naming/azurerm --source-type tfregistryModule)" --recursive

AWS version

tfupdate provider aws . --version ">=$(tfupdate release latest hashicorp/aws --source-type tfregistryProvider)" --recursive

AzureAD version

tfupdate provider azuread . --version ">=$(tfupdate release latest hashicorp/azuread --source-type tfregistryProvider)" --recursive

AzureDevOps version

tfupdate provider azuredevops . --version ">=$(tfupdate release latest microsoft/azuredevops --source-type tfregistryProvider)" --recursive

AzureRm version

tfupdate provider azurerm . --version ">=$(tfupdate release latest hashicorp/azurerm --source-type tfregistryProvider)" --recursive

Random version

tfupdate provider random . --version ">=$(tfupdate release latest hashicorp/random --source-type tfregistryProvider)" --recursive

Time version

tfupdate provider time . --version ">=$(tfupdate release latest hashicorp/time --source-type tfregistryProvider)" --recursive

(Back to the Table of Contents)

terraform_module_template Usage

Below are instructions on how to using the terraform module template to create a new module or to apply to a pre-existing module.

Creating your own terraform module using terraform_module_template

1. browse to RolfMoleman organisation on github and create a new repository

2. Choose the Repository template as RolfMoleman/terraform_module_template

3. Leave the owner as RolfMoleman

4. Give the repository a name following the naming convention of terraform-<provider name>-<resource name replacing spaces with -> Note: this will be the name of the module

5. Give the repository a meaningful concise description

6. Leave the repository visibility as private

7. clone your newly created repository using git clone https://github.com/DownAtTheBottomOfTheMoleHole/Module_Name.git

8. Create your readme:

9. In your vscode terminal do the following:

   1. Rename-Item -Path ".\README.md" -NewName "README.OLD"

   2. Rename-Item -Path ".\BLANK_README.md" -NewName "README.md"

10. In the new README.md do the following:

    1. Find & replace (CTRL+SHIFT+H in vs code) Module_Name with your module name. Note: Please use snake_case e.g. azurerm_awesome_module

    2. Find and replace (CTRL+SHIFT+H in vs code) Your_Email_Address with your email address e.g. carl.dawson@bca.com

    3. Find and replace (CTRL+SHIFT+H in vs code) Your_Team with the name of your team

    4. Find and replace (CTRL+SHIFT+H in vs code) Team_Email_List with a comma separated list of your team member's email addresses

    5. Find and replace (CTRL+SHIFT+H in vs code) Team_Email_Address with your team's email address if you have one, else remove it.

    6. Find and replace (CTRL+SHIFT+H in vs code) Module_Title with a sensible name e.g. Down At The Bottom Of The Mole Hole Terraform module template

    7. Find and replace (CTRL+SHIFT+H in vs code) Module_Description with some details about what the module is and what it is for

    8. Find and replace (CTRL+SHIFT+H in vs code) Your_Name with your name e.g. Carl Dawson

11. Update the roadmap so other staff can see your progress

12. Start creating/editing your terraform files - Note: use tflint to help you remove unneeded variables, outputs, resources & locals. This will also help ensure you have good descriptions, sensitive flags set etc. use validation on input variables where possible.

13. Generate your default_values.json this is a json file that populates your values in your documentation with actual values. You can either do this manually or by running terraform output --json > default_values.json once you have done a successful plan and apply.

14. Use terraform-docs to generate your documentation.

    1. README.md

       either run:

       terraform-docs markdown table . --config '.config\.readme-terraform-docs.yml'
       

       or:

       pre-commit run terraform-docs-go
       

    2. TERRAFORM.md

       either run:

       terraform-docs markdown table . --config '.config\.terraform-terraform-docs.yml'
       

       or:

       pre-commit run terraform-docs-go
       

15. Create a really useful module!

16. Tag your finished code using [GitVersion] - powershell one liner to do so: $gitversion = (gitversion |ConvertFrom-Json);git tag $GitVersion.SemVer -m 'My awesome release';git push --tags

17. Push your finished code up to github Note: dont forget to push your tags as well with git push --tags

18. The rest of CAG can consume your module :clap:

(Back to the Table of Contents)

Backfitting terraform_module_template to an existing module

1. Clone the terraform module template using git clone https://github.com/DownAtTheBottomOfTheMoleHole/terraform_module_template.git

2. rename your existing README.md using Rename-Item -Path ".\README.md" -NewName "README.OLD"

3. copy the following basic directories from the template to the root of your repo

   1. .assets
   2. .config
   3. .github
   4. .infracost
   5. .pre-commit_logs - you may need to create this
   6. scripts
   7. terraform-docs

4. copy the following files from the template to the root of your repo

   1. LICENSE
   2. .gitignore - replace your own or merge them.
   3. .tflint.hcl
   4. BLANK_README.md - we will rename this later to become your new readme
   5. CODE_OF_CONDUCT.md
   6. TERRAFORM.md
   7. .prettierignore
   8. .pre-commit-config.yml

5. merge the .tf files from the template with your own to achieve the following structure

   1. main.tf - contains the core resources and locals use tflint to help you remove unneeded resources and locals.
   2. data.tf - contains any data sources your module requires use tflint to help you remove unneeded data sources.
   3. modules.tf - contains any external modules you may be calling. use tflint to help you remove unneeded modules.
   4. outputs.tf - contains all your module outputs. use tflint to help you remove unneeded outputs.
   5. variables.tf - contains your input variables. Please ensure you use our standard inputs to ensure consistency. use tflint to help you remove unneeded variables.
   6. versions.tf - contains the required versions for terraform and required providers. you must use the latest possible versions. You must be No more than 3 minor versions out of date.

6. update the ./terraform-docs/default_values.json this must match the your terraform outputs in json format. this is a json file that populates your values in your documentation with actual values. You can either do this manually or by running terraform output --json > default_values.json once you have done a successful plan and apply.

7. create your readme from BLANK_README.md

   1. Find & replace (CTRL+SHIFT+H in vs code) Module_Name with your module name. Note: Please use snake_case e.g. azurerm_awesome_module

   2. Find and replace (CTRL+SHIFT+H in vs code) Your_Email_Address with your email address e.g. carl.dawson@bca.com

   3. Find and replace (CTRL+SHIFT+H in vs code) Your_Team with the name of your team

   4. Find and replace (CTRL+SHIFT+H in vs code) Team_Email_List with a comma separated list of your team member's email addresses

   5. Find and replace (CTRL+SHIFT+H in vs code) Team_Email_Address with your team's email address if you have one, else remove it.

   6. Find and replace (CTRL+SHIFT+H in vs code) Module_Title with a sensible name e.g. Down At The Bottom Of The Mole Hole Terraform module template

   7. Find and replace (CTRL+SHIFT+H in vs code) Module_Description with some details about what the module is and what it is for

   8. Find and replace (CTRL+SHIFT+H in vs code) Your_Name with your name e.g. Carl Dawson

   9. Update the roadmap so other staff can see your progress

   10. rename BLANK_README.md to README.md using:

       1. Rename-Item -Path ".\BLANK_README.md" -NewName "README.md"

8. Use terraform-docs to generate your documentation.

   1. README.md

      either run:

      terraform-docs markdown table . --config '.config\.readme-terraform-docs.yml'
      

      or:

      pre-commit run terraform-docs-go
      

   2. TERRAFORM.md

      either run:

      terraform-docs markdown table . --config '.config\.terraform-terraform-docs.yml'
      

      or:

      pre-commit run terraform-docs-go
      

9. Create a really useful module!

10. Tag your finished code using [GitVersion] - powershell one liner to do so: $gitversion = (gitversion |ConvertFrom-Json);git tag $GitVersion.SemVer -m 'My awesome release';git push --tags

11. Push your finished code back to your source control Note: dont forget to push your tags as well with git push --tags

12. Anyone can consume your module :clap:

(Back to the Table of Contents)

Roadmap

• Basic template
• Finish readme guide
• Refine BLANK_README.md
• Terraform-docs config per output markdown file :toolbox:
• Basic GitHub actions
• GitHub Issue Templates :toolbox:
• GitHub Pull Request Template :toolbox:
• Automated releases on push/merge/rebase to main :champagne: :toolbox: :dog::cut_of_meat:
• Consolidate workflows
• Auto add issues to Platform & Automation backlog :champagne: :toolbox: :dog::cut_of_meat:
• Megalinter automatic fixes via pull request :toolbox: :dog::cut_of_meat:
• Dependabot automated dependency management :toolbox: :dog::cut_of_meat:
• Renovate automated dependency management :toolbox: :dog::cut_of_meat:
• Automated issue assignment to the Platform and Automation team :toolbox: :dog::cut_of_meat:
• Add instructions on how to backfit the template :toolbox: :dog::cut_of_meat:

See the issues for a full list of proposed features (and known issues).

(Back to the Table of Contents)

Contributing

Everyone is encouraged to contribute Contributions are what make the open source community such a great way to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please create a branch and create a pull request. You can also simply open an issue with the tag "enhancement".

Don't forget to give the project a star! Thanks again!

1. Clone the Repo (git clone https://github.com/DownAtTheBottomOfTheMoleHole/terraform_module_template)
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

NOTE: This repo has tagged releases where the version is generated by gitversion. You can increment the release version by adding to your commit message as follows:

Adding +semver: breaking or +semver: major will cause the major version to be increased, +semver: feature or +semver: minor will bump minor and +semver: patch or +semver: fix will bump the patch. source

(Back to the Table of Contents)

To work with this repo we recommend you install the tools that are included in the prerequisites. However, you may work on the repo in the browser if you prefer.

Contributing Prerequisites

To replicate the setup used to initially create this repository you will need

1. Clone the Repo

   git clone https://github.com/DownAtTheBottomOfTheMoleHole/terraform_module_template.git
   

2. Install Chocolatey

   Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
   

3. Install Node

   choco install nodejs
   

4. Install Terraform

   choco install terraform
   

5. Install TFlint

   choco install tflint
   

   Also download the tflint plugins from github such as tflint-ruleset-azurerm and tflint-ruleset-aws put these in your .tflint.d/plugins directory at the root of your user directory

6. Install terraform-docs

   choco install terraform-docs
   

7. Install Python

   choco install python
   

8. Install pip

   curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
   python get-pip.py
   

9. Install pre-commit

   pip install pre-commit
   

10. Install vscode

    choco install vscode
    

11. Install tfupdate

Download the latest compiled binaries from here then put it in your executable path.

(Back to the Table of Contents)

License

for more information about the license please see LICENSE.md

(Back to the Table of Contents)

Contact

RolfMoleman - @RolfMoleman

Module Link: https://github.com/DownAtTheBottomOfTheMoleHole/terraform_module_template

(Back to the Table of Contents)