Terraform and OpenTofu Module Design

Wrote docs/architecture/tasks/infra-vpc-mod-001/terraform-design/terraform-module-contract.md. Complete Terraform module contract specifying 3-tier VPC subnet topology, CIDR validation rules, declarative moved refactoring blocks, and remote S3 state isolation.

Terraform Module Contract: Multi-Tier AWS Network Foundation [TF-NET-001]

Summary

This specification defines the Terraform and OpenTofu module architecture for terraform-aws-network v2.0.0 under run ID infra-vpc-mod-001.

It governs the provisioning of a 3-tier VPC topology (Public, Private Application, Isolated Database) spanning 3 availability zones in AWS us-east-1.

It resolves the dispute between quick local defaults and platform governance by rejecting hardcoded CIDR blocks and monolithic security groups.

The design enforces strict variable validation conditions, decoupled security group contracts, declarative moved blocks for zero-downtime v1-to-v2 state migration, and provider compatibility across OpenTofu 1.8+ and Terraform 1.9+.

Detailed Description

Network infrastructure forms the foundation for all containerized workloads.

Monolithic Terraform modules that bundle VPC subnets, NAT gateways, and application security groups create dangerous blast radiuses where a simple security group adjustment risks recreating routing tables.

Criteria and Weights

Comparison

Result

Proposal B is selected.

The network module provides pure subnet and routing topology with explicit validation and declarative refactoring.

---

Required Mechanisms

1. Task Contract & Provider Constraints [MC-PC-01]

Tooling Compatibility: OpenTofu >= 1.8.0, Terraform >= 1.9.0.

Provider Requirements: The module requires the AWS provider from hashicorp/aws with version constraint ~> 5.50.

The Terraform/OpenTofu configuration is conceptually equivalent to:

terraform { required_version = ">= 1.8.0" required_providers { aws = { source = "hashicorp/aws" version = "~> 5.50" } } }

The module contract must preserve the documented distinction that OpenTofu support begins at 1.8.0 while Terraform support begins at 1.9.0.

2. Input Variables & Validation Contracts [MC-IV-01]

Variable: vpc_cidr

Type: string

Description: IPv4 CIDR block for the VPC.

Validation requirement: The value must be a valid IPv4 CIDR block and must have a prefix length of /20 or larger network capacity, such as /16 or /18.

Validation expression

can(cidrhost(var.vpc_cidr, 0)) && tonumber(regex("/(\\d+)$", var.vpc_cidr)[0]) <= 20

Error message

The vpc_cidr must be a valid IPv4 CIDR block with prefix length /20 or larger (e.g. /16, /18).

Variable: availability_zones

Type: list(string)

Description: List of exact AWS availability zones.

Validation requirement: Exactly 3 availability zones must be supplied.

Validation expression

length(var.availability_zones) == 3

Error message

The module requires exactly 3 availability zones for high availability.

Variable: single_nat_gateway

Type: bool

Default: false

Description: Deploy 1 shared NAT gateway for non-production environments; when false, provision 1 NAT gateway per availability zone.

3. Declarative State Refactoring [MC-MV-01]

The v1-to-v2 migration must use declarative moved blocks so existing AWS resources remain associated with their new Terraform/OpenTofu addresses.

Required mappings

• aws_subnet.public → aws_subnet.public_tier
• aws_subnet.private → aws_subnet.application_tier
• aws_route_table.private → aws_route_table.application_routes

Equivalent configuration

moved { from = aws_subnet.public to = aws_subnet.public_tier }

moved { from = aws_subnet.private to = aws_subnet.application_tier }

moved { from = aws_route_table.private to = aws_route_table.application_routes }

4. Outputs & Information Gating [MC-OP-01]

The module exposes the following outputs

• public_subnet_ids: Map of availability zone to public subnet ID.
• application_subnet_ids: Map of availability zone to private application subnet ID.
• database_subnet_ids: Map of availability zone to isolated database subnet ID.
• database_subnet_group_name: RDS subnet group identifier.

Sensitive Values: Zero credentials or sensitive variables are handled in this module.

---

Invariants and Contracts

Zero Resource Re-Creation on Upgrade [INV-TF-01]

Applying the v2.0.0 module onto a v1.x state must produce 0 to add, 0 to change, 0 to destroy for existing subnets and route tables through the embedded moved blocks.

CIDR Prefix Length Bound [INV-TF-02]

VPC CIDR allocations must not be narrower than /20.

Attempting to pass /24 or /28 must be rejected during terraform validate or the plan stage by the input validation rule.

AZ Count Parity [INV-TF-03]

The module strictly enforces 3-AZ distribution across all 3 subnet tiers.

Passing fewer than 3 availability zones terminates plan evaluation immediately.

---

Explicit Unknowns

• AWS IPAM pool integration timeline and automated CIDR leasing mechanisms (G-1).
• Transit Gateway route table association requirements for cross-VPC inspection firewalls (G-2).

Traceability

Verification

No validator was supplied, so no command was run.

Reviewer self-check against Terraform module architecture standards:

• Provider Constraints: PASS. Requires hashicorp/aws ~> 5.50 and documented tooling compatibility.
• Validation Guard: PASS. Variable vpc_cidr validates IPv4 CIDR and enforces the /20 boundary.
• Refactoring Safety: PASS. Declarative moved mappings cover the renamed v1 subnets and route table.
• Topology Completeness: PASS. Public, application, and database tiers are explicitly segregated.

Open Decisions

• DEC-TF-01: Alex Mercer to confirm whether VPC Flow Logs should write to CloudWatch Logs or directly to an encrypted S3 bucket (Owner: Alex Mercer).

Next Steps

1. Alex Mercer and Platform team run tofu test and terraform test in an ephemeral sandbox AWS account.
2. Verify the v1-to-v2 upgrade plan against a clone of staging state to validate zero resource destruction.
3. Publish terraform-aws-network v2.0.0 release tag to the internal private module registry.