docs: add docs

README.md

@@ -0,0 +1,110 @@
+# Terragrunt Reference Architecture 🌐
+
+Welcome to the Terragrunt Reference Architecture repository! This project serves as a blueprint for creating and managing highly scalable, modular, and maintainable infrastructure as code (IaC) using Terragrunt and Terraform.
+
+## Overview 📖
+
+This repository embodies a structured approach to organizing Terraform code with Terragrunt, focusing on reusability, ease of management, and scalability across multiple environments and cloud providers. It's crafted to guide teams in building robust cloud infrastructure that adheres to best practices and principles.
+
+## Structure 🏗️
+
+```txt
+├── infra
+│   └── terraform
+│       ├── live
+│       │   ├── _globals
+│       │   │   ├── backend.hcl
+│       │   │   ├── git.hcl
+│       │   │   ├── ownership.hcl
+│       │   │   ├── tags.hcl
+│       │   │   └── tf_version.hcl
+│       │   ├── _modules
+│       │   │   ├── cloudflare_common.hcl
+│       │   │   ├── cloudflare_dns_zone.hcl
+│       │   │   └── random_string.hcl
+│       │   ├── _providers
+│       │   │   └── config.hcl
+│       │   ├── common.hcl
+│       │   ├── common.tfvars
+│       │   ├── stack-example
+│       │   │   ├── prod
+│       │   │   │   ├── env.hcl
+│       │   │   │   ├── env.tfvars
+│       │   │   │   └── global
+│       │   │   │       ├── cloudflare-dns-zone
+│       │   │   │       │   ├── .terraform.lock.hcl
+│       │   │   │       │   ├── module.hcl
+│       │   │   │       │   ├── terraform.tfvars
+│       │   │   │       │   └── terragrunt.hcl
+│       │   │   │       ├── random-string
+│       │   │   │       │   ├── .terraform-version
+│       │   │   │       │   ├── .terraform.lock.hcl
+│       │   │   │       │   ├── .terragrunt-version
+│       │   │   │       │   ├── module.hcl
+│       │   │   │       │   ├── terraform.tfvars
+│       │   │   │       │   └── terragrunt.hcl
+│       │   │   │       ├── region.hcl
+│       │   │   │       └── region.tfvars
+│       │   │   ├── stack.hcl
+│       │   │   └── stack.tfvars
+│       │   └── terragrunt.hcl
+│       ├── modules
+│       │   └── random-string
+│       │       ├── data.tf
+│       │       ├── locals.tf
+│       │       ├── main.tf
+│       │       ├── outputs.tf
+│       │       ├── variables.tf
+│       │       └── versions.tf
+│       ├── providers.aws.tpl
+│       └── providers.cloudflare.tpl
+```
+
+The architecture is segmented into distinct sections, each serving a specific purpose within the Terragrunt framework:
+
+- `_globals`: Centralized configurations for backend, ownership, versioning, and common tags.
+- `_modules`: Modular configurations for provider-specific settings, promoting DRY principles.
+- `_providers`: Provider configurations ensuring consistent behavior across modules.
+- `stack-example`: An example stack demonstrating the application of this architecture across different environments and regions.
+
+Each component is meticulously designed to fit into a hierarchical configuration strategy, facilitating fine-grained control and reuse across your infrastructure projects.
+
+## Key Features 🔑
+
+- **Modularity**: Break down your infrastructure into manageable, reusable components.
+- **Scalability**: Easily adapt and scale your infrastructure to meet evolving requirements.
+- **Best Practices**: Incorporates Terragrunt and Terraform best practices for security, state management, and infrastructure as code.
+
+## Getting Started 🚀
+
+To get started with this reference architecture:
+
+1. Clone the repository to your local machine.
+2. Navigate through the directories to understand the structure and purpose of each section.
+3. Customize the configurations (_globals, _modules, _providers) according to your project's needs.
+4. Use the `stack-example` as a template to create your own stacks.
+
+This repository includes a [Taskfile](https://taskfile.dev) to simplify common tasks. Run `task` to see the available commands, or run a CI/Plan/Apply/Destroy on a given stack and module. E.g.:
+
+```bash
+task infra-ci tgmod=random-string env=prod stack=stack-example
+```
+
+## Documentation 📚
+
+For more details on how to use Terragrunt and Terraform effectively within this architecture:
+
+- [Terragrunt Documentation](https://terragrunt.gruntwork.io/docs/)
+- [Terraform Documentation](https://www.terraform.io/docs/)
+
+## Contributing 🤝
+
+Contributions are welcome! If you have improvements or fixes, please open a pull request. For major changes or new features, please open an issue first to discuss what you would like to change.
+
+## License 📄
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+---
+
+Embrace the power of Infrastructure as Code with this Terragrunt Reference Architecture and elevate your cloud infrastructure to new heights!

infra/terraform/live/README.md

@@ -0,0 +1,75 @@
+# Parent `terragrunt.hcl` Configuration Overview 📘
+
+This document serves as a guide to understanding the central `terragrunt.hcl` configuration file at the root of your Terragrunt project. This configuration plays a pivotal role in orchestrating the deployment and management of your infrastructure across multiple environments, regions, and modules.
+
+## Understanding the Configuration 🧩
+
+The parent `terragrunt.hcl` file is designed to streamline and centralize the management of your cloud infrastructure. Here’s a breakdown of its key components:
+
+### Stack Configuration 🏗️
+
+- **Purpose**: Defines essential variables for stack management, using the stack's relative path for organization and naming consistency.
+- **Components**:
+    - `stack_name_path`: Derives the path relative to the include path for modular reuse.
+    - `stack_name`: Extracts the stack name from the path, aiding in identification and management.
+
+### Global Configuration 🌐
+
+- **Purpose**: Consolidates configurations that apply universally across Terragrunt modules, like backend settings, ownership details, and versioning for Terraform and Terragrunt.
+- **Components**:
+    - Inclusion of global settings from the `_globals` directory ensures consistency and central management.
+
+### Hierarchical Configuration 📚
+
+- **Purpose**: Facilitates a layered configuration strategy, allowing precise control over the behavior of Terragrunt and Terraform at different levels (e.g., common, environment, stack, region).
+- **Components**:
+    - Modular configurations for reuse and simplified management across the project.
+
+### Provider Configuration 🔌
+
+- **Purpose**: Ensures consistent provider behavior across all modules by centralizing provider-specific settings and credentials.
+- **Components**:
+    - Centralized setup for providers enhances security and reusability.
+
+### Environment and Region Configuration 🌍
+
+- **Purpose**: Specifies settings critical for deploying resources to the appropriate environment and region, aligning with organizational and cloud provider standards.
+- **Components**:
+    - Dynamic selection of environment and region-specific settings facilitates targeted deployments.
+
+### Ownership Configuration 👤
+
+- **Purpose**: Centralizes tagging for resource ownership, supporting resource management, cost allocation, and compliance.
+- **Components**:
+    - Ownership tags are defined globally and customized to fit organizational needs.
+
+### Remote State Configuration 🗄️
+
+- **Purpose**: Manages configuration and settings for state files, promoting secure and consistent state management practices.
+- **Components**:
+    - Supports centralization, encryption, and custom naming for state files, enhancing collaboration and efficiency.
+
+### Exposed Configuration 📢
+
+- **Purpose**: Makes certain configurations visible for debugging and transparency, aiding in operational understanding.
+- **Components**:
+    - Uses `run_cmd` to expose critical parameters during runtime, simplifying troubleshooting.
+
+### Dynamic `providers.tf` Generation 🛠️
+
+- **Purpose**: Dynamically generates the `providers.tf` file based on enabled providers, streamlining provider management.
+- **Components**:
+    - Utilizes `generate` blocks to create or update `providers.tf`, ensuring only necessary configurations are included.
+
+## How It Ties Together with Child Configurations 🧬
+
+The parent `terragrunt.hcl` not only defines the scaffold for your infrastructure but also intricately links with child configurations through includes and merges. This structure allows for:
+
+- **Modular Inheritance**: Child configurations inherit settings from the parent, ensuring consistency while allowing for overrides and customizations at lower levels.
+- **Flexibility and Control**: By defining core configurations at the parent level, you maintain centralized control with the ability to adapt each module or environment as needed.
+
+## Summary 📌
+
+The parent `terragrunt.hcl` file is the cornerstone of your Terragrunt architecture, providing a robust framework for managing a complex cloud infrastructure landscape. It exemplifies best practices in infrastructure as code, offering a scalable, maintainable, and secure approach to cloud infrastructure management.
+
+For a deeper understanding of Terragrunt and its capabilities, refer to the [Terragrunt Documentation](https://terragrunt.gruntwork.io/docs/).

infra/terraform/live/_globals/README.md

@@ -0,0 +1,56 @@
+# `_globals` Directory Overview
+
+The `_globals` directory is a key part of our Terragrunt reference architecture, designed to encapsulate configurations that are common across multiple modules and environments. This approach promotes the DRY (Don't Repeat Yourself) principle, ensuring consistency and facilitating easier management and updates across our infrastructure codebase.
+
+## Structure
+
+The directory consists of the following files, each serving a specific purpose within our global configuration strategy:
+
+
+```txt
+_globals/
+├── backend.hcl
+├── git.hcl
+├── ownership.hcl
+├── tags.hcl
+└── tf_version.hcl
+```
+
+
+## Configuration Files
+
+### `backend.hcl`
+
+- **Purpose**: Configures Terraform's state management backend, typically AWS S3, including encryption and bucket update prevention.
+- **Key Features**: Backend type specification, state file generation behavior, security features.
+- **Usage**: Included in the root `terragrunt.hcl` to ensure a consistent state management strategy.
+
+### `git.hcl`
+
+- **Purpose**: Provides centralized Git configuration for module sourcing, specifying the base URL for Git repositories.
+- **Key Features**: Base URL configuration, preference for SSH authentication.
+- **Usage**: Facilitates module sourcing and version management across the project.
+
+### `ownership.hcl`
+
+- **Purpose**: Defines resource ownership and organizational structuring, aiding in resource tagging and management.
+- **Key Features**: Dynamic environment variable support, ownership tagging.
+- **Usage**: Helps associate resources with specific owners and infrastructure layers.
+
+### `tags.hcl`
+
+- **Purpose**: Establishes a set of global tags applicable to all resources, supporting identification, organization, and governance.
+- **Key Features**: ManagedBy, OrchestratedBy, Author, and Owner tags.
+- **Usage**: Applied to resources in Terraform `resource` blocks for unified tagging.
+
+### `tf_version.hcl`
+
+- **Purpose**: Specifies required Terraform and Terragrunt versions, ensuring consistent tooling across environments.
+- **Key Features**: Version specification and overrides via environment variables.
+- **Usage**: Ensures that the infrastructure is provisioned using approved tooling versions.
+
+## Importance of `_globals`
+
+The `_globals` directory underpins our commitment to efficient, maintainable infrastructure code by reducing redundancy, simplifying updates, and ensuring consistency across all modules and environments. It represents the foundational settings of our infrastructure, embodying key principles such as IaC (Infrastructure as Code) and the DRY principle.
+
+For a deeper dive into best practices and detailed documentation, visit the [Terragrunt Documentation](https://terragrunt.gruntwork.io/docs/).

infra/terraform/live/_modules/README.md

@@ -0,0 +1,52 @@
+# `_modules` Directory Overview 📚
+
+The _modules directory within the Terragrunt architecture is designed to house common configurations for various providers (like Cloudflare, AWS, etc.), ensuring a DRY approach to managing provider-specific settings across all modules. This strategy not only streamlines the configuration management process but also enhances maintainability and scalability.
+
+# Directory structure
+
+
+```txt
+_modules/
+├── cloudflare_common.hcl # it depends on the provider
+├── cloudflare_dns_zone.hcl
+└── random_string.hcl
+```
+
+## Configuration Files 📄
+
+### `cloudflare_common.hcl`
+
+- **Purpose**: Centralizes common Cloudflare provider configurations, such as account IDs, to be shared across all Cloudflare-related modules.
+- **Key Features**: Cloudflare account ID specification.
+- **Usage**: Encapsulates common settings to avoid repetition and ensure consistency across Cloudflare modules.
+
+### `cloudflare_dns_zone.hcl`
+
+- **Purpose**: Defines configurations specific to the Cloudflare DNS Zone module, including stack and git module configurations, Cloudflare settings, and tags.
+- **Key Features**: Module versioning, Cloudflare configuration, and tagging strategy.
+- **Usage**: Utilized in child configurations to merge global and ownership tags with Cloudflare-specific settings for DNS zone management.
+
+### `random_string.hcl`
+
+- **Purpose**: Similar to `cloudflare_dns_zone.hcl`, but intended for modules generating random strings, demonstrating the template's versatility across different types of resources and providers.
+- **Key Features**: Flexible module versioning and tagging strategy.
+- **Usage**: Showcases how common and specific configurations merge to manage resource uniqueness and identity within the infrastructure.
+
+## Goals and Importance of `_modules` 🎯
+
+The `_modules` directory is instrumental in achieving a DRY and maintainable codebase. It allows for:
+
+- **Centralizing Provider Configurations**: Grouping common configurations for each provider, enhancing code reusability and consistency.
+- **Modularity and Reusability**: Encouraging modular infrastructure development where common configurations are defined once and referenced across multiple deployments.
+- **Simplification**: Reducing complexity by abstracting common configurations, making the overall infrastructure setup more understandable and easier to manage.
+
+## Utilization in Terragrunt 🛠️
+
+Modules within the `_modules` directory are referenced by Terragrunt configurations (`.hcl` files) in various environments or stacks. These references allow for:
+
+- **Configurable Deployments**: Tailoring infrastructure components per environment while maintaining a base configuration.
+- **Scalable Architecture**: Efficiently scaling the infrastructure setup by adding or modifying modules as needed without duplicating common configurations.
+
+By strategically leveraging the `_modules` directory, teams can manage complex cloud environments with greater ease, clarity, and control.
+
+For more insights into effective Terragrunt usage and module management, refer to the [Terragrunt Documentation](https://terragrunt.gruntwork.io/docs/).

infra/terraform/live/_providers/README.md

@@ -0,0 +1,71 @@
+# `_providers` Directory Overview 🌍
+
+The `_providers` directory is integral to managing Terraform provider configurations in a Terragrunt-driven infrastructure. It centralizes the setup for various providers like Cloudflare, AWS, etc., leveraging the dynamic capabilities of Terragrunt and Terraform for environment-specific configurations.
+
+The config.hcl file within the _providers directory serves as a central point for configuring Terraform providers such as Cloudflare, AWS, and others. It utilizes Terraform's heredoc syntax for inline definitions, allowing for dynamic and environment-specific configurations.
+
+## Key Features 🔑
+
+* Dynamic Configuration: Provider configurations are defined inline, enabling dynamic adjustments based on environment variables. This method supports conditional provider setup, making it possible to enable or disable specific providers as needed.
+* Enhanced Security: Sensitive details, like API keys and email addresses, are securely injected using environment variables, avoiding hard-coded credentials within the configuration files.
+* Modularity: This approach promotes a modular configuration strategy, where provider settings can be easily adjusted without modifying the core codebase.
+Usage 🛠️
+
+# Usage 🛠️
+
+1. Conditional Inclusion: Providers are conditionally included based on their enabled status, which is determined by environment variables. This allows for precise control over which providers are activated in different environments or deployment contexts.
+2. Streamlined Management: The direct use of heredoc syntax for provider configurations streamlines the Terraform codebase by eliminating the need for separate template files for each provider, simplifying management and updates.
+
+## Best Practices 📝
+
+
+* Environment Variables: Utilize environment variables for all sensitive information and to toggle the inclusion of different providers. This practice not only secures sensitive details but also provides flexibility across different deployment environments.
+* Provider Management: Regularly review and update the config.hcl file to reflect changes in provider requirements or to introduce new providers as your infrastructure evolves.
+* Documentation: Keep detailed documentation of each provider's configuration, including required environment variables and any specific setup instructions, to ensure clarity and ease of use for team members.
+
+## Configuration File: `config.hcl`
+
+The sole configuration file within this directory, `config.hcl`, orchestrates the definition and conditional inclusion of Terraform providers.
+
+### Key Aspects of `config.hcl` 🗝️
+
+*
+* **Dynamic Provider Configuration**: Using Terraform's heredoc syntax, `config.hcl` allows for inline provider definitions that can be dynamically adjusted with environment variables.
+*
+* **Security and Flexibility**: Sensitive information (e.g., API keys) is passed via environment variables, enhancing security and providing the flexibility to alter configurations per deployment environment.
+*
+* **Modularity**: This setup promotes a modular approach, enabling the selective use of providers without altering the core codebase.
+
+### How It Works 🔧
+
+```hcl
+locals {
+  providers = {
+    cloudflare = {
+      enabled = get_env("TG_PROVIDER_CLOUDFLARE_ENABLED", false)
+      content = <<EOF
+provider "cloudflare" {
+  email   = "${get_env("CLOUDFLARE_EMAIL", "")}"
+  api_key = "${get_env("CLOUDFLARE_API_KEY", "")}"
+}
+EOF
+    },
+    // Additional providers follow the same pattern.
+  }
+
+  providers_content = [
+    for provider, details in local.providers : details.content
+    if details.enabled
+  ]
+}
+```
+
+And then, it's used in the `terragrunt.hcl` file like this:
+
+```hcl
+generate "providers" {
+  path      = "providers.tf"
+  if_exists = "overwrite_terragrunt"
+  contents  = join("\n", local.providers_cfg.locals.providers_content)
+}
+```