init

src/profiles/tf.rst

@@ -0,0 +1,249 @@
+#################
+Terraform Profile
+#################
+
+Concept → Terraform Mapping
+===========================
+
+.. list-table:: 
+  :header-rows: 1
+
+  * - ABC Concept
+    - Meaning
+    - Terraform Mapping
+  * - ABC‑C0
+    - Construct
+    - Terraform module
+  * - ABC‑C1
+    - Application Stack
+    - Root Terraform module
+  * - ABC‑C2
+    - Logical Unit
+    - Child module representing a domain
+  * - ABC‑C3
+    - Resource Group
+    - Submodule representing a cohesive resource cluster
+  * - ABC‑C4
+    - Input Contract
+    - variables.tf in a module
+  * - ABC‑C5
+    - Output Contract
+    - outputs.tf in a module
+  * - ABC‑C6
+    - Instantiation Interface
+    - ``module "" { ... }`` block
+  * - ABC‑C7
+    - Capturing Down
+    - Passing variables from parent to child module
+  * - ABC‑C8
+    - Bubbling Up
+    - Exposing outputs from child modules to parent
+
+Proile Rules
+============
+
+Terraform profile rules follow the canonical identifier format:
+
+.. code-block::
+
+    ABC-PROFILE-TF-R#
+
+These rules are profile‑specific, not core ABC rules.
+
+ABC-PROFILE-TF-R1 (SHOULD)
+--------------------------
+
+Each ABC construct SHOULD be implemented as a Terraform module.
+
+ABC-PROFILE-TF-R2 (SHOULD)
+--------------------------
+
+The directory structure SHOULD reflect the ABC hierarchy:
+
+.. code-block::
+
+    root/
+      main.tf
+      data/
+        main.tf
+        storage/
+          main.tf
+        database/
+          main.tf
+      logic/
+        main.tf
+      presentation/
+        main.tf
+
+ABC-PROFILE-TF-R3 (SHOULD)
+--------------------------
+
+Each module SHOULD contain:
+
+* main.tf
+* variables.tf (InputContract)
+* outputs.tf (OutputContract)
+
+ABC-PROFILE-TF-R4 (MUST)
+------------------------
+
+Module inputs MUST be declared exclusively in variables.tf.
+
+ABC-PROFILE-TF-R5 (MUST)
+------------------------
+
+Module outputs MUST be declared exclusively in outputs.tf.
+
+ABC-PROFILE-TF-R6 (MUST)
+------------------------
+
+Modules MUST NOT reference parent or sibling modules directly; all data MUST
+flow through variables and outputs.
+
+(This enforces ABC‑R22, ABC‑R40, ABC‑R42.)
+
+ABC-PROFILE-TF-R7 (MUST)
+------------------------
+
+Modules MUST be instantiated using a module "<name>" { ... } block with explicit
+variable assignments.
+
+ABC-PROFILE-TF-R8 (MUST)
+------------------------
+
+Modules MUST NOT read Terraform state from other modules except via outputs.
+
+ABC-PROFILE-TF-R9 (MUST)
+------------------------
+
+Capturing Down MUST be implemented by passing parent variables or outputs into
+child module inputs.
+
+ABC-PROFILE-TF-R10 (MUST)
+-------------------------
+
+Bubbling Up MUST be implemented by exposing child module outputs and re‑exposing
+them in the parent module if needed.
+
+ABC-PROFILE-TF-R11 (MUST)
+-------------------------
+
+Resource definitions MUST reside only in Resource Group modules (ABC‑C3).
+
+ABC-PROFILE-TF-R12 (MUST)
+-------------------------
+
+Logical Units MUST NOT contain Terraform resources directly.
+
+ABC-PROFILE-TF-R13 (SHOULD)
+---------------------------
+
+Logical Units SHOULD only orchestrate child modules and expose aggregated
+outputs.
+
+Canonical Example
+=================
+
+A minimal 3‑tier ABC architecture in Terraform.
+
+Application Stack
+-----------------
+
+.. code-block:: hcl
+    :caption: main.tf
+
+    module "data" {
+      source = "./data"
+      environment = var.environment
+      region      = var.region
+    }
+    
+    module "logic" {
+      source = "./logic"
+      environment      = var.environment
+      region           = var.region
+      database_endpoint = module.data.database_endpoint
+    }
+    
+    module "presentation" {
+      source = "./presentation"
+      environment           = var.environment
+      region                = var.region
+      frontend_assets_bucket = module.data.storage_bucket_name
+      api_endpoint           = module.logic.api_endpoint
+    }
+    
+    output "frontend_url" {
+      value = module.presentation.frontend_url
+    }
+    
+    output "api_endpoint" {
+      value = module.logic.api_endpoint
+    }
+
+.. code-block:: hcl
+    :caption: variables.tf
+
+    variable "environment" { type = string }
+    variable "region"      { type = string }
+
+Data Logical Unit
+-----------------
+
+.. code-block::
+    :caption: data/main.tf
+
+    module "storage" {
+      source = "./storage"
+      environment  = var.environment
+      region       = var.region
+      storage_class = var.storage_class
+    }
+    
+    module "database" {
+      source = "./database"
+      environment      = var.environment
+      db_engine        = var.db_engine
+      db_instance_size = var.db_instance_size
+    }
+    
+    output "storage_bucket_name" {
+      value = module.storage.bucket_name
+    }
+    
+    output "database_endpoint" {
+      value = module.database.endpoint
+    }
+
+.. code-block::
+    :caption: data/variables.tf
+
+    variable "environment"   { type = string }
+    variable "region"        { type = string }
+    variable "storage_class" { type = string }
+    variable "db_engine"     { type = string }
+    variable "db_instance_size" { type = string }
+
+Storage Resource Group
+^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: hcl
+    :caption: data/storage/main.tf
+
+    resource "aws_s3_bucket" "bucket" {
+      bucket = "${var.environment}-storage"
+    }
+
+.. code-block:: hcl
+    :caption: data/storage/variables.tf
+
+    variable "environment"   { type = string }
+    variable "region"        { type = string }
+    variable "storage_class" { type = string }
+
+.. code-block:: hcl
+    :caption: data/storage/outputs.tf
+
+    output "bucket_name" {
+      value = aws_s3_bucket.bucket.bucket
+    }