Down At The Bottom Of The Mole HoleTerraform module template

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

Name	Version
terraform	1.7.5
aws	5.42.0
azuread	2.47.0
azuredevops	1.0.1
azurerm	3.97.1
mongodbatlas	1.15.2
random	3.6.0
time	0.11.1

---

(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

Name	Type
random_password.aws_pass	resource
random_password.azure_pass	resource
time_offset.secret_expiry	resource
time_offset.spn_password_expiry	resource
azuread_client_config.bootstrap	data source
azuread_group.bootstrap	data source
azuredevops_project.bcaapp	data source
azuredevops_project.bootstrap	data source
azurerm_client_config.bootstrap	data source
azurerm_subscription.bcaapp	data source
azurerm_subscription.bootstrap	data source

---

(Back to the Table of Contents)

---

Inputs

Name	Description	Type	Default	Required
application_name	Project/application name	string	n/a	yes
application_shortname	short version of project/application name	string	n/a	yes
azdo_pat	Azure Devops Personal Access token (can be set to system.accesstoken)	string	n/a	yes
azdo_project_name	azure devops project name	string	n/a	yes
azdo_repo_name	The name of the Azure Devops Git Repository your code resides in	string	n/a	yes
cag_division	Division of CAG 3 character abbreviation e.hg. BCA, MMG	string	n/a	yes
environment_tag	Environment tag e.g. dev, test, systest, UAT, Prod	string	n/a	yes
resource_group_name	Specifies the name of the existing resource group to be used for the service plan	string	n/a	yes
aws_access_key	AWS access key	string	""	no
aws_profile	AWS profile	string	""	no
aws_resource_location	Resource location. Must be a valid AWS region	string	"eu-west-1"	no
aws_secret_key	AWS secret key	string	""	no
azdo_orgurl	short version of project/application name	string	null	no
azrm_client_id	Service principal id - cannot be null if working with azure	string	null	no
azrm_client_secret	Service principal password - cannot be null if working with azure	string	null	no
azrm_keyvault_whitelist	List of IP addresses and CIDR blocks for Key Vault whitelist to be combined with the defaults in main.tf	list(string)	[]	no
azrm_resource_location	Resource group location. Must be a valid azure region	string	"northeurope"	no
azrm_storage_whitelist	List of IP addresses and CIDR blocks for storage account whitelist to be combined with the defaults in main.tf	list(string)	[]	no
azrm_subscription_id	Azure subscription id - cannot be null if working with azure	string	null	no
azrm_tenant_id	Azure tenant id. cannot be null if working with Azure	string	null	no
default_tags	Default map of tags to be applied to all resources generated by this module.	map(string)	{}	no
time_secret_expiry	Number of years from now when keyvault secrets should expire	number	100	no
time_spn_expiry	Number of years from now when service principal password should expire	number	100	no

---

(Back to the Table of Contents)

---

Outputs

Name	Description	Value	Sensitive
application_name	The project/application name for this repository	"application_name"	no
application_shortname	The shortened project/application name for this repository	"application_shortname"	no
aws_access_key	The AWS Access Key	<sensitive>	yes
aws_profile	The AWS profile used	"aws_profile"	no
aws_resource_location	The AWS region used for the resources	"eu-west-1"	no
azdo_orgurl	The Azure DevOps URL used for this run	"https://dev.azure.com/bcagroup"	no
azdo_pat	The Azure DevOps Personal Access Token (PAT) used for this run	<sensitive>	yes
azrm_client_id	The ID of the service principal used for this run	"azrm_client_id"	no
azrm_resource_location	The location of resources being worked on with this run	"northeurope"	no
azure_subscription_display_name	The current subscription name	"subscription_display_name"	no
azure_subscription_id	The current subscription id	"subscription_id"	no
azuredevops_project_name	The current Azure DevOps name	"project_name"	no
environment	The environment being worked on with this run	"dev"	no
tags	The tags applied to resources as part of this run	{ "ADO-Project": "project_name", "Application": "application_name", "Environment": "dev", "Managed-By": "Terraform", "Owner": "project_name Contributors", "Repository": "repo_name" }	no
tenant_id	The azure tenant id of resources being worked on with this run	"tenant_id"	no

---

(Back to the Table of Contents)

---

Modules

Name	Source	Version
azrm_naming	Azure/naming/azurerm	0.4.1

---

(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 👏

---

(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 👏

---

(Back to the Table of Contents)

---

Roadmap

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

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)

---