How int128/terraform-aws-nat-instance works
Project type and purpose
• This is a Terraform module (infrastructure-as-code) that provisions a low-cost NAT instance in AWS.
• Purpose: provide NAT for private subnets using an EC2 instance (with autoscaling, spot instances, fixed EIP on ENI, SSM support).
File structure
• Top-level Terraform files: main.tf, variables.tf, outputs.tf, versions.tf – define and configure AWS resources.
• helper scripts: runonce.sh, snat.sh – executed via cloud-init on the EC2 instance for configuring IP forwarding and masquerading.
• example/ directory: sample configuration, demonstration of module usage.
• CI config: .github/workflows/terraform.yaml.
• Makefile + runonce.sh wrapper: build/test pipeline.
README for insights
• Lists AWS resources created: Auto Scaling Group (mixed instances), Launch Template, ENI, Security Group, IAM Role & Policy, optional Route.
• Describes runonce.sh and snat.sh on the instance: ENI attach → kernel params → default route.
a. Main components
• Terraform orchestrator (your workstation/CI)
• AWS Cloud block
– VPC (with public and private subnets)
– Public Subnet A (where NAT instance lives)
– Private Subnets (A, B, C)
– Elastic Network Interface (ENI) in Public Subnet
– Elastic IP attached to ENI
– Auto Scaling Group (ASG) + Launch Template (spot/on-demand selection)
– EC2 NAT instance(s) (Amazon Linux 2 with cloud-init)
– Security Group for NAT (ingress from private CIDRs, egress to Internet)
– IAM Role & Instance Profile (policies: SSM + ENI attachment)
– Optional Route Table entries: private route tables → ENI’s private IP
b. Relationships & interactions
– Terraform applies via AWS Provider → provisions VPC components, ASG, Launch Template, IAM, ENI, SG, Route.
– ASG/Launch Template spins up EC2 instance; user-data invokes runonce.sh & snat.sh.
– runonce.sh attaches ENI to eth1; snat.sh enables IP forwarding & NAT masquerade; default route points to eth1.
– Private subnet instances route 0.0.0.0/0 through this NAT instance.
– EIP ensures a fixed public IP for outbound traffic.
– SSM Agent connects to AWS Systems Manager (for remote shell).
c. Architectural patterns & principles
– Immutable infrastructure via Terraform.
– Auto-healing via ASG.
– Cost optimization: spot instances + minimal instance types.
– Separation of concerns: network components (VPC, subnets, route tables), compute (ASG/Launch Template/EC2), security (SG, IAM), IP management (ENI, EIP).
d. Technologies/frameworks
– Terraform 0.12+
– AWS Provider (autoscaling_group, launch_template, network_interface, route, security_group, iam_role, iam_instance_profile)
– AWS SSM Session Manager
– Cloud-init (runonce.sh, snat.sh)