feat: renovate, aqua, tf-docs, TF workspaces (#10)

* Adds Renovate configuration (along with documentation)
* Adds `terraform-docs` along with corresponding tools
* Adds example of using TF workspaces 

Also let's come up with the new name for this template repo, and I'll
adjust accordingly in the other dependent repos.

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added configuration files for automated dependency updates and
documentation generation tools.
* Introduced environment-specific variable files for development and
production.
* Added a new input variable and output for the template root module to
enhance customization and visibility.

* **Improvements**
* Updated documentation for improved clarity, structure, and actionable
guidance.
* Enhanced module documentation with clearer requirements, usage
instructions, and example commands.

* **Updates**
* Upgraded versions of required tools, linters, and providers for better
compatibility and security.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: oycyc

.github/renovate.json5

@@ -0,0 +1,17 @@
+{
+  "extends": [
+    "config:best-practices",
+    "github>aquaproj/aqua-renovate-config#2.7.5"
+  ],
+  "schedule": ["before 5am on Monday"],
+  "baseBranches": ["main", "master"],
+  "labels": ["auto-upgrade"],
+  "dependencyDashboardAutoclose": true,
+  "enabledManagers": ["terraform"],
+  "terraform": {
+    "ignorePaths": [
+      "**/context.tf",
+      "components/**", // We should upgrade the majority of components manually
+    ]
+  },
+}

.terraform-docs.yaml

@@ -0,0 +1,20 @@
+version: 0.20.0
+formatter: markdown table
+
+settings:
+  anchor: false
+  html: false
+  lockfile: false
+
+recursive:
+  enabled: true
+  path: root-modules
+  include-main: false
+
+output:
+  file: README.md
+  mode: inject
+  template: |-
+    <!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+    {{ .Content }}
+    <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

.trunk/trunk.yaml

@@ -20,15 +20,15 @@ lint:
     # Incompatible with some Terraform features: https://github.com/tenable/terrascan/issues/1331
     - terrascan
   enabled:
-    - tofu@1.10.1
+    - tofu@1.10.3
     - actionlint@1.7.7
-    - checkov@3.2.447
+    - checkov@3.2.451
     - git-diff-check
     - markdownlint@0.45.0
     - prettier@3.6.2
-    - tflint@0.58.0
-    - trivy@0.63.0
-    - trufflehog@3.89.2
+    - tflint@0.58.1
+    - trivy@0.64.1
+    - trufflehog@3.90.0
     - yamllint@1.37.1
   ignore:
     - linters: [tofu]

README.md

@@ -1,33 +1,18 @@
-# example-tf
+# infra-monorepo-template
 
 This repository serves as an example and template for how Masterpoint thinks about organizing a vanilla Terraform or OpenTofu (from now on referred to as "TF") monorepo with root modules, child modules, and accompanying tooling.
 
 This includes example configurations and recommendations around the following topics:
 
-<!-- TODO: Link to what Multi-instance root modules are once https://github.com/masterpointio/masterpoint.io/pull/49 ships -->
-
-1. Example organizational structure for an IaC Monorepo (Multi-instance Root Modules + Child Modules)
+1. Example organizational structure for an IaC Monorepo ([Multi-instance Root Modules](https://masterpoint.io/blog/terraform-opentofu-terminology-breakdown/#multi-instance-root-modules) + Child Modules)
    1. Root module example is provided in the [root-modules/template-root-module](./root-modules/template-root-module/) directory.
    2. Child module example is provided in the [child-modules/random-pet](./child-modules/random-pet/) directory
 2. [Recommendations for module file structure](#structure) with [file-by-file guidance](#file-by-file-guidance)
 3. [Recommendations for version pinning TF + Providers](#versioning-tf-and-providers)
-4. [Managing which TF binary is used per project](#managing-which-tf-binary-is-used-per-project)
+4. [Managing which TF binary is used per project using Aqua](#managing-which-tf-binary-is-used-per-project-using-aqua)
 5. [Guidance on linting + CI for TF](#tf-linting--ci)
-6. [Frequently Asked Questions](#frequently-asked-questions)
-
-<!-- TODO
-1. Example Native TF Tests with accompanying GitHub Action workflow for running tests
- -->
-
-## Recommendations (TODO: Discuss)
-
-We recommend to include:
-
-- Module Description: Provide a concise explanation of what the module does and its intended use cases.
-- Usage Instructions: Include code snippets demonstrating how to call the module from a [root module](https://developer.hashicorp.com/terraform/language/modules#the-root-module).
-- Inputs & Outputs Summary: List the module’s input variables (with defaults and required ones highlighted) and outputs. We recommend using [terraform-docs](https://github.com/terraform-docs/terraform-docs) to keep the summary up-to-date.
-- Prerequisites and Dependencies: Mention any dependencies, required providers, or external resources.
-- Example Configurations: If applicable, include or link to example code snippets or a separate examples/ directory.
+6. [Renovate to Automate Dependency Updates](#renovate-to-automate-dependency-updates)
+7. [Frequently Asked Questions](#frequently-asked-questions)
 
 ## Structure
 
@@ -132,11 +117,9 @@ The principles below apply to both root and child modules, unless otherwise spec
 
 We’re particular about how we version providers and Terraform/OpenTofu in child and root modules. We recommend the following:
 
-### Child Modules
+### [Child Modules](https://masterpoint.io/blog/terraform-opentofu-terminology-breakdown/#child-modules)
 
-<!-- TODO: Update to link Child Modules to Terms blog post once live -->
-
-Since child-modules are intended to be used many times throughout your or others code, it’s important to make it so that they create as little restrictions on the consuming root module as possible.
+Since [child-modules](https://masterpoint.io/blog/terraform-opentofu-terminology-breakdown/#child-modules) are intended to be used many times throughout your or others code, it’s important to make it so that they create as little restrictions on the consuming root module as possible.
 
 This means you should:
 
@@ -162,11 +145,9 @@ terraform {
 
 In this example, the child module only demands a minimum version (Terraform or OpenTofu 1.3, Random provider 3.0), letting the root module run newer versions as they become available.
 
-### Root Modules
-
-<!-- TODO: Update to link Root Modules to Terms blog post once live -->
+### [Root Modules](https://masterpoint.io/blog/terraform-opentofu-terminology-breakdown/#root-modules)
 
-Root modules are intended to be planned and applied and therefore they should be more prescriptive so that they’re called consistently in each case that you instantiate a new root module instance (i.e. create a new state file).
+[Root modules](https://masterpoint.io/blog/terraform-opentofu-terminology-breakdown/#root-modules) are intended to be planned and applied and therefore they should be more prescriptive so that they’re called consistently in each case that you instantiate a new root module instance (i.e. create a new state file).
 
 To accomplish that, you should do the following:
 
@@ -195,7 +176,7 @@ In this example two things are happening:
 
 If you're more willing to use the bleeding edge of providers, you can always use the `~>` operator on the minor version like so `version = "~> 5.81"`. This will enable any new minor version updates and is essentially a shorthand for `>= 5.81.0 && < 6.0`. Be aware that providers do break and this has the possibility to frustrating bugs from providers to affect your project.
 
-## Managing which TF binary is used per project
+## Managing which TF binary is used per project using Aqua
 
 At Masterpoint, we're big fans of [Aqua](https://aquasecurity.github.io/aqua/) for managing which TF binary is used per project. This allows us to have a single TF binary that is used across our entire project, but still enables us to use root module specific TF versions if needed.
 
@@ -229,6 +210,12 @@ As you can see, this is a LOT of checks that trunk is supporting for us and this
 
 Check out our [.trunk/trunk.yaml](.trunk/trunk.yaml) file to see how we configure this and [check the trunk Code Quality getting started documentation](https://docs.trunk.io/code-quality) on how you can use this tool for your own project.
 
+## Renovate to Automate Dependency Updates
+
+We use [Renovate](https://github.com/apps/renovate) to automatically keep our Terraform and OpenTofu dependencies up-to-date through automated pull requests. This includes providers, modules, and even the Terraform/OpenTofu binaries themselves through Aqua.
+
+This repository comes with configurations available at [.github/renovate.json5](.github/renovate.json5) that are configured to run on a weekly basis. Visit the [Renovate GitHub App page](https://github.com/apps/renovate) to install the app and configure it to run on your repository. There's also an [example tutorial that Renovate](https://github.com/renovatebot/tutorial) has to guide setting up Renovate.
+
 ## Frequently Asked Questions
 
 ### Why do you prefer DRY (Don't Repeat Yourself) Root Modules vs WET (Write Every Time) Root Modules?

aqua.yaml

@@ -11,3 +11,4 @@ registries:
     ref: v4.331.0 # renovate: depName=aquaproj/aqua-registry
 packages:
   - name: opentofu/opentofu@v1.9.0
+  - name: terraform-docs/terraform-docs@v0.20.0

root-modules/template-root-module/README.md

@@ -2,6 +2,26 @@
 
 This is a template root module that creates a random pet resource. It can be easily copied and updated for other use-cases.
 
+## Using `tfvars` with [TF Workspaces](https://masterpoint.io/blog/terraform-opentofu-terminology-breakdown/#tf-cli-workspaces)
+
+Terraform/OpenTofu workspaces are used with environment-specific tfvars files for separate TF state files to keep your configuration DRY. This allows you to maintain the same infrastructure code while using different variable values for different environments.
+
+```bash
+# Set up a new workspace for `dev` -- only needs to be done once
+tofu workspace new dev
+# Select the workspace, this is how TF knows where the state file is stored
+tofu workspace select dev
+# Apply the configuration with the corresponding tfvars file
+tofu apply --var-file tfvars/dev.tfvars
+```
+
+This approach ensures that:
+
+- Your infrastructure code remains consistent across environments
+- Environment-specific configurations are isolated in tfvars files
+- State files are automatically separated by workspace
+- You can easily switch between environments
+
 <!-- README TEMPLATE: AFTER READING THE BELOW SECTION, DELETE THE BELOW SECTION AND REPLACE WITH YOUR OWN CONTENT -->
 
 ## Documentation Recommendations (DO NOT INCLUDE THIS INTO THE REAL README)
@@ -16,33 +36,36 @@ This is a template root module that creates a random pet resource. It can be eas
 
 ## Requirements
 
-| Name                                                                     | Version |
-| ------------------------------------------------------------------------ | ------- |
-| <a name="requirement_terraform"></a> [terraform](#requirement_terraform) | ~> 1.0  |
-| <a name="requirement_random"></a> [random](#requirement_random)          | ~> 3.0  |
+| Name      | Version  |
+| --------- | -------- |
+| terraform | 1.10.3   |
+| random    | ~> 3.7.2 |
 
 ## Providers
 
 No providers.
 
 ## Modules
 
-| Name                                                              | Source                   | Version |
-| ----------------------------------------------------------------- | ------------------------ | ------- |
-| <a name="module_random_pet"></a> [random_pet](#module_random_pet) | masterpointio/random/pet | 0.1.0   |
+| Name       | Source                         | Version |
+| ---------- | ------------------------------ | ------- |
+| random_pet | ../../child-modules/random-pet | n/a     |
 
 ## Resources
 
 No resources.
 
 ## Inputs
 
-| Name                                                | Description                   | Type     | Default | Required |
-| --------------------------------------------------- | ----------------------------- | -------- | ------- | :------: |
-| <a name="input_length"></a> [length](#input_length) | The length of the random name | `number` | `2`     |    no    |
+| Name   | Description                                 | Type     | Default    | Required |
+| ------ | ------------------------------------------- | -------- | ---------- | :------: |
+| length | The length of the random name               | `number` | `2`        |    no    |
+| prefix | The prefix to prepend to the generated name | `string` | `"random"` |    no    |
 
 ## Outputs
 
-No outputs.
+| Name            | Description                   |
+| --------------- | ----------------------------- |
+| random_pet_name | The generated random pet name |
 
 <!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->

root-modules/template-root-module/main.tf

@@ -1,11 +1,15 @@
 locals {
-  # Get the current timestamp and format it as YYYYMMDD
-  prefix = formatdate("YYYYMMDD", timestamp())
+  # Get the current timestamp and format it as YYYYMMDD, then concatenate with user-provided prefix
+  prefix = "${var.prefix}-${formatdate("YYYYMMDD", timestamp())}"
 }
 
 module "random_pet" {
-  source  = "masterpointio/random/pet"
-  version = "0.1.0"
+  # If using a module from Terraform/OpenTofu Registry:
+  # source  = "masterpointio/random/pet"
+  # version = "0.1.0"
+
+  # If using a module from a local directory:
+  source = "../../child-modules/random-pet"
 
   length = var.length
   prefix = local.prefix

root-modules/template-root-module/outputs.tf

@@ -0,0 +1,4 @@
+output "random_pet_name" {
+  description = "The generated random pet name"
+  value       = module.random_pet.random_pet_name
+}

root-modules/template-root-module/tfvars/dev.tfvars

@@ -0,0 +1 @@
+prefix = "dev"

root-modules/template-root-module/tfvars/prod.tfvars

@@ -0,0 +1 @@
+prefix = "prod"