# int128/terraform-aws-nat-instance architecture

> Architecture diagram of the GitHub repository int128/terraform-aws-nat-instance, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/int128/terraform-aws-nat-instance
- Repository: https://github.com/int128/terraform-aws-nat-instance

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Orchestrator
    TerraformCI["Terraform / CI (Makefile & GitHub Actions)"]:::ci
    TerraformCI -->|"applies Terraform via AWS Provider"| AWSAPI["AWS API"]:::external

    %% AWS Cloud Boundary
    subgraph "AWS Cloud"
        direction TB

        %% VPC
        subgraph "VPC" 
            direction TB

            %% Public Subnet
            subgraph "Public Subnet A" 
                direction TB
                ENI["Elastic Network Interface (ENI)"]:::networking
                EIP["Elastic IP (EIP)"]:::networking
                ASG["Auto Scaling Group\n(mixed spot | on-demand)"]:::compute
                LT["Launch Template"]:::compute
                EC2["EC2 NAT Instance\n(Amazon Linux 2)"]:::compute
                SG["Security Group\n(NAT SG)"]:::security
                IAM["IAM Role & Instance Profile"]:::iam

                %% Scripts
                RunOnce["runonce.sh"]:::script
                SnaTSh["snat.sh"]:::script
                SnatSvc["snat.service"]:::script

                ENI -->|attached by runonce.sh| EC2
                EC2 -->|configures NAT via snat.sh| EC2
                EC2 -->|uses Security Group| SG
                EC2 -->|assigned IAM Role| IAM
                EC2 -->|"uses Launch Template"| LT
                ASG -->|launches EC2| EC2
                LT --> ASG
                EIP -->|associated with| ENI
            end

            %% Private Subnets
            subgraph "Private Subnets A, B, C"
                direction TB
                Apps["Application Instances"]:::compute
            end

            %% Routing
            Apps -->|"0.0.0.0/0 via NAT Instance"| EC2
            PrivateRoutes["Private Route Tables"]:::networking
            PrivateRoutes -.->|"optional aws_route"| ENI
            EC2 -->|"0.0.0.0/0 via EIP"| InternetGW["Internet Gateway"]:::networking
        end
    end

    %% Click Events for Component Mapping
    click main.tf "https://github.com/int128/terraform-aws-nat-instance/blob/master/main.tf"
    click variables.tf "https://github.com/int128/terraform-aws-nat-instance/blob/master/variables.tf"
    click outputs.tf "https://github.com/int128/terraform-aws-nat-instance/blob/master/outputs.tf"
    click versions.tf "https://github.com/int128/terraform-aws-nat-instance/blob/master/versions.tf"
    click runonce.sh "https://github.com/int128/terraform-aws-nat-instance/blob/master/runonce.sh"
    click snat.sh "https://github.com/int128/terraform-aws-nat-instance/blob/master/snat.sh"
    click snat.service "https://github.com/int128/terraform-aws-nat-instance/blob/master/snat.service"
    click .github/workflows/terraform.yaml "https://github.com/int128/terraform-aws-nat-instance/blob/master/.github/workflows/terraform.yaml"
    click Makefile "https://github.com/int128/terraform-aws-nat-instance/tree/master/Makefile"
    click example/example.tf "https://github.com/int128/terraform-aws-nat-instance/blob/master/example/example.tf"
    click example/instance.tf "https://github.com/int128/terraform-aws-nat-instance/blob/master/example/instance.tf"
    click example/dnat.sh "https://github.com/int128/terraform-aws-nat-instance/blob/master/example/dnat.sh"
    click example/dnat.service "https://github.com/int128/terraform-aws-nat-instance/blob/master/example/dnat.service"
    click example/Makefile "https://github.com/int128/terraform-aws-nat-instance/tree/master/example/Makefile"
    click example/README.md "https://github.com/int128/terraform-aws-nat-instance/blob/master/example/README.md"
    click README.md "https://github.com/int128/terraform-aws-nat-instance/blob/master/README.md"
    click LICENSE "https://github.com/int128/terraform-aws-nat-instance/tree/master/LICENSE"
    click .gitignore "https://github.com/int128/terraform-aws-nat-instance/blob/master/.gitignore"
    click renovate.json "https://github.com/int128/terraform-aws-nat-instance/blob/master/renovate.json"

    %% Styles
    classDef networking fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef compute fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20
    classDef security fill:#ffcdd2,stroke:#b71c1c,color:#b71c1c
    classDef iam fill:#e1bee7,stroke:#4a148c,color:#4a148c
    classDef script fill:#eeeeee,stroke:#9e9e9e,color:#424242
    classDef ci fill:#fff9c4,stroke:#f57f17,color:#f57f17
    classDef external fill:#f5f5f5,stroke:#9e9e9e,color:#424242
```
