diff --git a/.trunk/configs/.markdownlint.yaml b/.trunk/configs/.markdownlint.yaml
index c97ae62..e66984e 100644
--- a/.trunk/configs/.markdownlint.yaml
+++ b/.trunk/configs/.markdownlint.yaml
@@ -12,3 +12,7 @@ whitespace: false
# Ignore MD041/first-line-heading/first-line-h1
# Error: First line in a file should be a top-level heading
MD041: false
+
+# Ignore markdownlint/MD029
+# Error: Ordered list item prefix
+MD029: false
diff --git a/README.md b/README.md
index 51eb4b5..d4f3b16 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,12 @@
-# terraform-child-module-template
+# client-tf-templates
-This repository serves as a template for creating Terraform [child modules](https://developer.hashicorp.com/terraform/language/modules#child-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 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 README.md serves as the module’s primary documentation and entry point.
+Child module example is provided in [terraform-random-pet](./terraform-random-pet/) directory.
+
+Root module example is provided in [root-module](./root-module/) directory.
+
+This README.md serves as the module's primary documentation and entry point.
## Recommenations
@@ -14,60 +18,164 @@ We recommend to include:
- 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.
-## Repository Structure
+## Structure
+
+This template includes a recommended layout for both root modules and child TF modules. Each file has a specific purpose and set of best practices. While many principles apply to both root and child modules, any differences are noted below.
-Below is the recommended structure for a Terraform child module. You'll fine the best practices for what to include inside each file. This layout helps maintain clarity, and consistency across your infrastructure code:
+For root modules:
```sh
.
├── README.md
├── main.tf
├── data.tf (optional)
-├── outputs.tf
+├── outputs.tf (optional)
+├── providers.tf
├── variables.tf
└── versions.tf
```
-## Additional Tips
+For child modules:
-- 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.
+```sh
+.
+├── README.md
+├── main.tf
+├── data.tf (optional)
+├── outputs.tf (optional)
+├── variables.tf
+└── versions.tf
+```
+
+### File-by-File Guidance
+
+The principles below apply to both root and child modules, unless otherwise specified.
+
+1. `main.tf`
+
+- Purpose: Defines core resources and the module’s primary logic. In root modules, this may also include calls to child modules.
+- Best Practices:
+ - Resource definitions: Declare here all the primary resources that this module is responsible for managing.
+ - Locals and expressions: Use locals blocks to simplify expressions and keep the code DRY (Don’t Repeat Yourself).
+ - Comments and structure: Organize resources logically and use comments to explain complex or non-obvious configurations.
+ - Minimal hard-coding: Use variables extensively to avoid embedding environment-specific values directly in the code.
+ - Child module calls:
+ - Use Terraform Registry Modules with Version Pinning:
+ ```hcl
+ module "vpc" {
+ source = "terraform-aws-modules/vpc/aws"
+ version = "1.0.0"
+ }
+ ```
+ - Use Git Sources with a Specific Tag or Commit
+ ```hcl
+ module "vpc" {
+ source = "git::https://github.com/org/terraform-aws-vpc.git?ref=v1.0.0"
+ }
+ ```
+
+2. `data.tf` (Optional)
+
+- Purpose: Contains data sources that retrieve external information.
+- Best Practices:
+ - Data source declarations: Place all data blocks here, for example, `data "aws_ami" "linux" { ... }`.
+ - Clear naming and purpose: Use descriptive names for data sources to indicate their role (e.g., `data "aws_ami" "ubuntu_latest"`).
+ - Commenting and filtering: Document why each data source is used and ensure filters or queries are well explained.
+ - Minimize external dependencies: Only query the minimum necessary information. Overly complicated data sources can slow down Terraform runs and confuse future maintainers.
-
+3. `outputs.tf` (Optional)
-## Requirements
+- Purpose: Defines values exported from the module for use by its caller.
+- Best Practices:
+ - Descriptive output names: Use meaningful names (e.g., `instance_id`, `db_connection_string`).
+ - Descriptions: Include description attributes to clarify the purpose of each output.
+ - Minimal outputs: Only output what consumers need. For sensitive outputs, mark as `sensitive = true`.
-| Name | Version |
-| ------------------------------------------------------------------------ | ------- |
-| [terraform](#requirement_terraform) | ~> 1.0 |
-| [random](#requirement_random) | ~> 3.0 |
+4. `providers.tf` (Root Module Only)
-## Providers
+- Purpose: Configures providers for the root module, such as authentication or default regions.
+- Best Practices:
+ - Provider configuration: Define providers (e.g., `aws {}`, `google {}`) and set their region, credentials, or other parameters.
+ - Multiple provider configurations: If you need multiple configurations for the same provider (e.g., two AWS regions), define them here with explicit aliases.
+ - Avoid hard-coded and static credentials: Instead of embedding static credentials directly in your code, consider:
+ - AWS Assume Role: For the AWS provider, configure an assume role to obtain temporary credentials dynamically.
+ - Encrypted Configuration Files: For providers requiring API tokens, use a tool like [SOPS](https://getsops.io/) to encrypt sensitive variables.
-| Name | Version |
-| --------------------------------------------------------- | ------- |
-| [random](#provider_random) | 3.6.3 |
+5. `variables.tf`
-## Modules
+- Purpose: Defines input variables controlling the module’s configuration.
+- Best Practices:
+ - Descriptive variables: Use meaningful names and description attributes.
+ - Default values: Provide reasonable defaults when possible. For mandatory inputs, omit defaults to enforce explicit user input.
+ - Type constraints and validation: Use type constraints and validation blocks to catch incorrect inputs early.
+ - Group related variables: Organize variables logically, adding comments to separate sections if many variables exist.
-No modules.
+6. `versions.tf`
-## Resources
+- Purpose: Sets Terraform and provider version requirements for consistency and compatibility.
+- Best Practices:
+ - See the detailed version constraints explanation in [Versioning TF and Providers](#versioning-tf-and-providers).
+ - Regular Review: Update constraints as Terraform and providers evolve.
-| Name | Type |
-| --------------------------------------------------------------------------------------------------------- | -------- |
-| [random_pet.template](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/pet) | resource |
+## Versioning TF and Providers
-## Inputs
+We’re particular about how we version providers and Terraform/OpenTofu in child and root modules. We recommend the following:
-| Name | Description | Type | Default | Required |
-| --------------------------------------------------- | ----------------------------- | -------- | ------- | :------: |
-| [length](#input_length) | The length of the random name | `number` | `2` | no |
+### Child Modules
-## Outputs
+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.
-| Name | Description |
-| -------------------------------------------------------------------------------- | ----------------------------- |
-| [random_pet_name](#output_random_pet_name) | The generated random pet name |
+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.
+
+Example:
+
+```hcl
+terraform {
+ required_version = ">= 1.3"
+
+ required_providers {
+ random = {
+ source = "hashicorp/random"
+ version = ">= 3.0"
+ }
+ }
+}
+```
+
+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.
+
+### 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).
+
+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.
+- 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:
+
+```hcl
+terraform {
+ required_version = "1.3.7"
+
+ required_providers {
+ aws = {
+ source = "hashicorp/aws"
+ version = "~> 5.81.0"
+ }
+ }
+}
+```
+
+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.
+
+## 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.
diff --git a/data.tf b/data.tf
deleted file mode 100644
index 1fc7d85..0000000
--- a/data.tf
+++ /dev/null
@@ -1,8 +0,0 @@
-# Purpose:
-# The data.tf file contains Terraform data sources—these do not create resources but query existing infrastructure or configuration for reference.
-
-# Best Practices:
-# - Data Source Declarations: Place all data blocks here, for example, data "aws_ami" "linux" { ... }.
-# - Clear Naming and Purpose: Use descriptive names for data sources to indicate their role (e.g., data "aws_ami" "ubuntu_latest").
-# - Commenting and Filtering: Document why each data source is used and ensure filters or queries are well explained.
-# - Minimize External Dependencies: Only query the minimum necessary information. Overly complicated data sources can slow down Terraform runs and confuse future maintainers.
diff --git a/main.tf b/main.tf
deleted file mode 100644
index 4f6affe..0000000
--- a/main.tf
+++ /dev/null
@@ -1,12 +0,0 @@
-# Purpose:
-# The main.tf file contains the core resource definitions and logic that compose the module’s functionality.
-
-# Best Practices:
-# - Resource Definitions: Declare here all the primary resources that this module is responsible for managing.
-# - Locals and Expressions: Use locals blocks to simplify expressions and keep the code DRY (Don’t Repeat Yourself).
-# - Comments and Structure: Organize resources logically and use comments to explain complex or non-obvious configurations.
-# - Minimal Hard-Coding: Use variables extensively to avoid embedding environment-specific values directly in the code.
-
-resource "random_pet" "template" {
- length = var.length
-}
diff --git a/outputs.tf b/outputs.tf
deleted file mode 100644
index 21abdaa..0000000
--- a/outputs.tf
+++ /dev/null
@@ -1,12 +0,0 @@
-# Purpose:
-# The outputs.tf file defines values that the module exports for use by the caller.
-
-# Best Practices:
-# - Descriptive Output Names: Use meaningful names (e.g., instance_id, db_connection_string).
-# - Descriptions: Include description attributes to clarify the purpose of each output.
-# - Minimal Outputs: Only output what consumers need. For sensitive outputs, mark as sensitive = true.
-
-output "random_pet_name" {
- description = "The generated random pet name"
- value = random_pet.template.id
-}
diff --git a/root-module/README.md b/root-module/README.md
new file mode 100644
index 0000000..ae4c381
--- /dev/null
+++ b/root-module/README.md
@@ -0,0 +1,48 @@
+# root-module
+
+This is a template root module.
+
+
+
+## Documentation Recommendations (DO NOT INCLUDE THIS INTO THE REAL README)
+
+- Module description: Briefly explain what the root module sets up (e.g., infrastructure for RDS Postgres instances).
+- Use [terraform-docs](https://github.com/terraform-docs/terraform-docs) to ensure that variables, outputs, child module, and resource documentation is included.
+- Maintain current information: Keep the README updated as the infrastructure evolves.
+
+
+
+
+
+## Requirements
+
+| Name | Version |
+| ------------------------------------------------------------------------ | ------- |
+| [terraform](#requirement_terraform) | ~> 1.0 |
+| [random](#requirement_random) | ~> 3.0 |
+
+## Providers
+
+No providers.
+
+## Modules
+
+| Name | Source | Version |
+| ----------------------------------------------------------------- | ------------------------ | ------- |
+| [random_pet](#module_random_pet) | masterpointio/random/pet | 0.1.0 |
+
+## Resources
+
+No resources.
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+| --------------------------------------------------- | ----------------------------- | -------- | ------- | :------: |
+| [length](#input_length) | The length of the random name | `number` | `2` | no |
+
+## Outputs
+
+No outputs.
+
+
diff --git a/root-module/example.auto.tfvars b/root-module/example.auto.tfvars
new file mode 100644
index 0000000..be955f5
--- /dev/null
+++ b/root-module/example.auto.tfvars
@@ -0,0 +1,5 @@
+# This example.auto.tfvars file provides a sample set of input variable values for the root module.
+# Terraform automatically loads any `.auto.tfvars` files, applying these values without requiring additional command-line flags.
+# Rename or remove this file to fit your needs.
+
+length = 1
diff --git a/root-module/main.tf b/root-module/main.tf
new file mode 100644
index 0000000..180c194
--- /dev/null
+++ b/root-module/main.tf
@@ -0,0 +1,12 @@
+locals {
+ # Get the current timestamp and format it as YYYYMMDD
+ prefix = formatdate("YYYYMMDD", timestamp())
+}
+
+module "random_pet" {
+ source = "masterpointio/random/pet"
+ version = "0.1.0"
+
+ length = var.length
+ prefix = local.prefix
+}
diff --git a/root-module/providers.tf b/root-module/providers.tf
new file mode 100644
index 0000000..17955e4
--- /dev/null
+++ b/root-module/providers.tf
@@ -0,0 +1,3 @@
+provider "random" {
+ # Configuration options
+}
diff --git a/root-module/variables.tf b/root-module/variables.tf
new file mode 100644
index 0000000..f684e07
--- /dev/null
+++ b/root-module/variables.tf
@@ -0,0 +1,9 @@
+variable "length" {
+ description = "The length of the random name"
+ type = number
+ default = 2
+ validation {
+ condition = var.length > 0
+ error_message = "The length must be a positive number."
+ }
+}
diff --git a/root-module/versions.tf b/root-module/versions.tf
new file mode 100644
index 0000000..9c733fb
--- /dev/null
+++ b/root-module/versions.tf
@@ -0,0 +1,10 @@
+terraform {
+ required_version = "1.8.7"
+
+ required_providers {
+ random = {
+ source = "hashicorp/random"
+ version = "~> 3.0.0"
+ }
+ }
+}
diff --git a/terraform-random-pet/README.md b/terraform-random-pet/README.md
new file mode 100644
index 0000000..1f27ddb
--- /dev/null
+++ b/terraform-random-pet/README.md
@@ -0,0 +1,96 @@
+# terraform-random-pet
+
+This is a template child module.
+
+
+
+## Documentation Recommendations (DO NOT INCLUDE THIS INTO THE REAL README)
+
+### Naming
+
+The repository/directory name should follow this pattern:
+
+```sh
+[terraform-]-
+```
+
+Here’s what this means:
+
+1. [If it's a separate repository] The repository should start with `terraform-` if your module should be [published to and discovered on the Registry](https://opentofu.org/docs/language/modules/develop/publish/). Even if you don’t intend to publish the module, following this pattern is a good practice that helps differentiate your Terraform child modules from other code in your projects.
+2. Include the provider name: Specify the primary provider your module is for, such as aws, google, datadog, etc.
+3. Use descriptive name: Follow the provider name with a clear and concise identifier that describes the module’s purpose.
+4. Use hyphens to separate words.
+
+Also:
+
+1. Keep name short and focused: While it should be descriptive, avoid overly long names. The goal is to convey the module’s purpose concisely:
+ - Good: `terraform-aws-internal-lb`.
+ - Not so good: `terraform-aws-internal-misc-module`.
+ - Too long: `terraform-aws-internal-application-load-balancer-with-extra-rules`.
+2. Module names should reflect their purpose rather than environment-specific details.
+
+### Usage
+
+To use this module, reference it from your main configuration and provide the necessary input variables. For example:
+
+```hcl
+module "sandbox_pet" {
+ source = "masterpointio/random/pet"
+ # We recommend to pin the specific version
+ # version = "X.X.X"
+
+ # Input variables
+ length = 2
+ prefix = "sandbox"
+}
+```
+
+Once applied, the random resource will produce a random name such as `sandbox-lively-parrot` (the exact name will vary). This name can be referenced via:
+
+```hcl
+output "pet_name" {
+ value = module.sandbox_pet.random_pet_name
+}
+```
+
+
+
+
+
+## Requirements
+
+| Name | Version |
+| ------------------------------------------------------------------------ | ------- |
+| [terraform](#requirement_terraform) | >= 1.0 |
+| [random](#requirement_random) | >= 3.0 |
+
+## Providers
+
+| Name | Version |
+| --------------------------------------------------------- | ------- |
+| [random](#provider_random) | >= 3.0 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+| --------------------------------------------------------------------------------------------------------- | -------- |
+| [random_pet.template](https://registry.terraform.io/providers/hashicorp/random/latest/docs/resources/pet) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+| --------------------------------------------------- | --------------------------------- | -------- | ------- | :------: |
+| [length](#input_length) | The length of the random name. | `number` | `2` | no |
+| [prefix](#input_prefix) | A string to prefix the name with. | `string` | `null` | no |
+
+## Outputs
+
+| Name | Description |
+| -------------------------------------------------------------------------------- | ----------------------------- |
+| [random_pet_name](#output_random_pet_name) | The generated random pet name |
+
+
diff --git a/terraform-random-pet/main.tf b/terraform-random-pet/main.tf
new file mode 100644
index 0000000..c7103e1
--- /dev/null
+++ b/terraform-random-pet/main.tf
@@ -0,0 +1,4 @@
+resource "random_pet" "template" {
+ length = var.length
+ prefix = var.prefix
+}
diff --git a/terraform-random-pet/outputs.tf b/terraform-random-pet/outputs.tf
new file mode 100644
index 0000000..c44df14
--- /dev/null
+++ b/terraform-random-pet/outputs.tf
@@ -0,0 +1,4 @@
+output "random_pet_name" {
+ description = "The generated random pet name"
+ value = random_pet.template.id
+}
diff --git a/terraform-random-pet/variables.tf b/terraform-random-pet/variables.tf
new file mode 100644
index 0000000..d1f182b
--- /dev/null
+++ b/terraform-random-pet/variables.tf
@@ -0,0 +1,15 @@
+variable "length" {
+ description = "The length of the random name."
+ type = number
+ default = 2
+ validation {
+ condition = var.length > 0
+ error_message = "The length must be a positive number."
+ }
+}
+
+variable "prefix" {
+ description = "A string to prefix the name with."
+ type = string
+ default = null
+}
diff --git a/terraform-random-pet/versions.tf b/terraform-random-pet/versions.tf
new file mode 100644
index 0000000..0cf661c
--- /dev/null
+++ b/terraform-random-pet/versions.tf
@@ -0,0 +1,10 @@
+terraform {
+ required_version = ">= 1.0"
+
+ required_providers {
+ random = {
+ source = "hashicorp/random"
+ version = ">= 3.0"
+ }
+ }
+}
diff --git a/variables.tf b/variables.tf
deleted file mode 100644
index 2d081cf..0000000
--- a/variables.tf
+++ /dev/null
@@ -1,18 +0,0 @@
-# Purpose:
-# The variables.tf file defines input variables that control the module’s configuration.
-
-# Best Practices:
-# - Descriptive Variables: Use meaningful names and description attributes.
-# - Default Values: Provide reasonable defaults when possible. For mandatory inputs, omit defaults to enforce explicit user input.
-# - Type Constraints and Validation: Use type constraints and validation blocks to catch incorrect inputs early.
-# - Group Related Variables: Organize variables logically, adding comments to separate sections if many variables exist.
-
-variable "length" {
- description = "The length of the random name"
- type = number
- default = 2
- validation {
- condition = var.length > 0
- error_message = "The length must be a positive number."
- }
-}
diff --git a/versions.tf b/versions.tf
deleted file mode 100644
index 8d67298..0000000
--- a/versions.tf
+++ /dev/null
@@ -1,18 +0,0 @@
-# Purpose:
-# The versions.tf file specifies the required Terraform and provider versions, ensuring consistency and compatibility.
-
-# Best Practices:
-# - Terraform Version Constraints: Use required_version to pin known-compatible Terraform versions (e.g., required_version = "~> 1.3").
-# - Provider Requirements: Lock provider versions with required_providers to avoid unexpected upgrades (e.g., aws = { source = "hashicorp/aws" version = "~> 5.0" }).
-# - Stability Over Time: Regularly review and update version constraints as Terraform and providers evolve.
-
-terraform {
- required_version = "~> 1.0"
-
- required_providers {
- random = {
- source = "hashicorp/random"
- version = "~> 3.0"
- }
- }
-}