feat: first pass at reworking to more holistic example (#5)

## what

- Reworking the `client-tf-templates` repo into `example-tf`

## why

- I want to have something more holistic that shows + describes how we
do things. The way things are now is great, but I want to setup this
project so that we can use it for more. This is a first attempt at doing
so. cc @gberenice I want to collab on this, so we'll discuss soon 👍

## references

- N/A

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

## Summary by CodeRabbit

- **Documentation**
- Revised repository overview and module guides for clearer usage
instructions.
- **New Features**
- Introduced a new configuration for streamlined CLI tool version
management.
- **Chores**
	- Removed obsolete pre-commit settings.
- Updated tool versions and added a new linting action to enhance
overall quality.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Veronika Gnilitska <[email protected]>

Author: Gowiem

.pre-commit-config.yaml

@@ -2,7 +2,7 @@
 # To learn more about the format of this file, see https://docs.trunk.io/reference/trunk-yaml
 version: 0.1
 cli:
-  version: 1.22.10
+  version: 1.22.11
 # Trunk provides extensibility via plugins. (https://docs.trunk.io/plugins)
 plugins:
   sources:
@@ -22,20 +22,21 @@ lint:
   enabled:
     - [email protected]
     - [email protected]
-    - [email protected].378
+    - [email protected].386
     - git-diff-check
     - [email protected]
-    - [email protected].2
+    - [email protected].3
     - [email protected]
-    - trivy@0.59.1
-    - [email protected].14
-    - yamllint@1.35.1
+    - trivy@0.60.0
+    - [email protected].17
+    - yamllint@1.36.2
   ignore:
     - linters: [tofu]
       paths:
         - "**/backend.tf.json"
 actions:
   enabled:
+    - terraform-docs
     - trunk-announce
     - trunk-check-pre-push
     - trunk-fmt-pre-commit

.trunk/trunk.yaml

@@ -1,14 +1,25 @@
-# client-tf-templates
+# example-tf
 
-This repository serves as a template for creating Terraform [child](https://opentofu.org/docs/language/modules/#child-modules) and [root](https://opentofu.org/docs/language/modules/#the-root-module) modules, providing a standardized structure and essential files for efficient module development. It's designed to ensure consistency and best practices across Terraform projects.
+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.
 
-Child module example is provided in [terraform-random-pet](./terraform-random-pet/) directory.
+This includes example configurations and recommendations around the following topics:
 
-Root module example is provided in [root-module](./root-module/) directory.
+<!-- TODO: Link to what Multi-instance root modules are once https://github.com/masterpointio/masterpoint.io/pull/49 ships -->
 
-This README.md serves as the module's primary documentation and entry point.
+1. Example organizational structure for an IaC Monorepo (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)
+5. [Guidance on linting + CI for TF](#tf-linting--ci)
+6. [Frequently Asked Questions](#frequently-asked-questions)
 
-## Recommenations
+<!-- TODO
+1. Example Native TF Tests with accompanying GitHub Action workflow for running tests
+ -->
+
+## Recommendations (TODO: Discuss)
 
 We recommend to include:
 
@@ -123,14 +134,16 @@ We’re particular about how we version providers and Terraform/OpenTofu in chil
 
 ### Child Modules
 
-Since child-modules are intended to be used many times throughout your code, it’s important to make it so that they create as little restrictions on the consuming consuming root module as possible.
+<!-- 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.
 
 This means you should:
 
 - Identify the earliest Terraform/OpenTofu and provider versions your child module supports.
 - Use the `>=` operator to ensure that consumers run at least these versions.
 
-By setting a lower bound (e.g., `>= 1.3`) rather than pinning exact versions, you allow root modules to choose their own Terraform and provider versions. This means a root module can upgrade Terraform or providers without requiring updates to all child modules.
+By setting a lower bound (e.g., `>= 1.3`) rather than pinning exact versions, you allow root modules to choose their own Terraform/OpenTofu and provider versions. This means a root module can upgrade their TF or providers versions without requiring updates to the child modules that they consume.
 
 Example:
 
@@ -147,15 +160,17 @@ terraform {
 }
 ```
 
-In this example, the child module only demands a minimum version (Terraform 1.3, Random provider 3.0), letting the root module run newer versions as they become available.
+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
 
-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. a state file).
+<!-- TODO: Update to link Root Modules to Terms blog post once live -->
+
+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:
 
-- Explicitly pin the latest version of Terraform/OpenTofu that your root module supports. You’ll need to upgrade this version each time you want to use a new TF version across your code base.
+- Explicitly pin the latest version of TF that your root module supports. You’ll need to upgrade this version each time you want to use a new TF version across your code base.
 - Identify the highest stable provider versions your root module supports, then use the [pessimistic operator](https://developer.hashicorp.com/terraform/language/expressions/version-constraints#operators) `~>` to allow only patch-level updates. This gives you automatic bug fixes and minor improvements without risking major breaking changes.
 
 Example:
@@ -173,9 +188,55 @@ terraform {
 }
 ```
 
-In this example Terraform is pinned exactly at 1.3.7, the AWS provider is pinned with `~> 5.81.0`, which means it can update to 5.81.1, 5.81.2, etc., but not jump to 5.82.0.
+In this example two things are happening:
+
+1. TF is pinned exactly at `1.3.7`, which ensures your entire team will use the correct version with this root module.
+2. The AWS provider is pinned with `~> 5.81.0`, which means it can update to `5.81.1`, `5.81.2`, etc., but not jump to `5.82.0`.
+
+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
+
+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.
+
+Check out the [aqua.yaml](.aqua/aqua.yaml) file to see how simple it is to use aqua for this project and check out [the Aqua docs](https://aquasecurity.github.io/aqua/getting-started/installation/) on how you can use this tool for your own project.
+
+<!--
+TODO: Work these into other sections.
 ## Additional Tips
 
 - Testing and Examples: Consider adding an examples/ directory with sample configurations and a test/ directory (if using tools like terratest or native Terraform testing) to ensure the module works as intended
-- Continuous Improvement: Update documentation and constraints (versions.tf) as Terraform and providers evolve, and as you refine the module’s functionality.
+- Continuous Improvement: Update documentation and constraints (versions.tf) as Terraform and providers evolve, and as you refine the module’s functionality. -->
+
+## TF Linting + CI
+
+There are many tools to format, lint, and ensure consistency of TF code. The tool that we recommend is [trunk Code Quality](https://docs.trunk.io/code-quality). This single tool allows us to do the following:
+
+1. Format our TF code with `terraform fmt` or `tofu fmt` within our IDE and ensure this is run on each commit.
+   1. [This is handled by the trunk `terraform` or `tofu` linter](https://docs.trunk.io/code-quality/linters/supported/tofu).
+2. Validate our TF code with `terraform validate` or `tofu validate` within our IDE and ensure this is run on each commit.
+   1. [This is handled by the trunk `terraform` or `tofu` linter](https://docs.trunk.io/code-quality/linters/supported/tofu).
+3. Generate documentation for our TF code with `terraform-docs` and ensure it is kept up-to-date on each commit.
+   1. [This is handled by the trunk `terraform-docs` action](https://github.com/trunk-io/plugins/tree/main/actions/terraform-docs), which [Masterpoint originally developed](https://github.com/trunk-io/plugins/pull/966).
+4. Run TFLint against our code to ensure it is written against the best practices.
+   1. [This is handled by the trunk `tflint` linter](https://docs.trunk.io/code-quality/linters/supported/tflint).
+5. Run a TF security scan against our code to ensure we're not introducing any security vulnerabilities.
+   1. [This is handled by the trunk `trivy` linter](https://docs.trunk.io/code-quality/linters/supported/trivy).
+6. Run these checks in a CI pipeline to ensure they're enforced on each PR.
+   1. [This is handled by the trunk-action workflow](https://docs.trunk.io/code-quality/setup-and-installation/github-integration) in the [.github/workflows/lint.yaml](.github/workflows/lint.yaml) file.
+
+As you can see, this is a LOT of checks that trunk is supporting for us and this consolidation on one tool to support this (and much more) is a huge win.
+
+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.
+
+## Frequently Asked Questions
+
+### Why do you prefer DRY (Don't Repeat Yourself) Root Modules vs WET (Write Every Time) Root Modules?
+
+We advocate IaC should be treated like code and traditional software. You encode some level of business logic into it, and consistently copying+pasting that logic as part of your day-to-day processes creates a maintenance burden that we believe should be avoided. This particularly shows up when IaC is managed at scale and we have seen these types of setups lead to a lot of toil and a lot of technical debt.
+
+We will write up more on this soon and link to it here.
+
+### Why don't you use a TF Framework like [Terragrunt](https://terragrunt.gruntwork.io/), [Terramate](https://terramate.io/), or [Atmos](https://atmos.tools/)?
+
+We're big fans of the frameworks (particularly Atmos + Terramate, which we have a good deal of experience with), and we believe they're fantastic options for sophisticated teams that are starting from scratch. But for projects that aren't starting from scratch or have a desire to keep things simple, we believe Vanilla TF combined with a strong automation platform is a great option.

README.md

@@ -0,0 +1,13 @@
+---
+# aqua - Declarative CLI Version Manager
+# https://aquaproj.github.io/
+# checksum:
+#   enabled: true
+#   require_checksum: true
+#   supported_envs:
+#   - all
+registries:
+  - type: standard
+    ref: v4.331.0 # renovate: depName=aquaproj/aqua-registry
+packages:
+  - name: opentofu/[email protected]

aqua.yaml

@@ -1,6 +1,6 @@
 # terraform-random-pet
 
-This is a template child module.
+This is a template child module to create a random pet resource. It can be easily copied and updated for other use-cases.
 
 <!-- README TEMPLATE: AFTER READING THE BELOW SECTION, DELETE THE BELOW SECTION AND REPLACE WITH YOUR OWN CONTENT -->
 

terraform-random-pet/README.md renamed to child-modules/random-pet/README.md

@@ -1,6 +1,6 @@
-# root-module
+# template-root-module
 
-This is a template root module.
+This is a template root module that creates a random pet resource. It can be easily copied and updated for other use-cases.
 
 <!-- README TEMPLATE: AFTER READING THE BELOW SECTION, DELETE THE BELOW SECTION AND REPLACE WITH YOUR OWN CONTENT -->