abc-spec/src/profiles/tf.rst

#################
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
    }