# Oshun VPC Terraform Module

This Terraform module creates a production-ready AWS VPC with public, private,
and database subnets across multiple availability zones.

## Features

- **Multi-AZ deployment**: Configurable availability zones (default: 3)
- **Subnet tiers**: Public, private, and database subnets
- **NAT Gateway**: Single or per-AZ for high availability
- **VPC Endpoints**: Gateway (S3, DynamoDB) and interface endpoints
- **Flow Logs**: CloudWatch or S3 destination
- **IPv6 support**: Optional dual-stack networking
- **Subnet groups**: RDS and ElastiCache subnet groups included

## Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                                   VPC (10.0.0.0/16)                          │
│                                                                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐              │
│  │   AZ-1 (a)      │  │   AZ-2 (b)      │  │   AZ-3 (c)      │              │
│  │                 │  │                 │  │                 │              │
│  │ ┌─────────────┐ │  │ ┌─────────────┐ │  │ ┌─────────────┐ │              │
│  │ │   Public    │ │  │ │   Public    │ │  │ │   Public    │ │  ← ALB, NAT │
│  │ │ 10.0.0.0/20 │ │  │ │10.0.16.0/20 │ │  │ │10.0.32.0/20 │ │              │
│  │ └─────────────┘ │  │ └─────────────┘ │  │ └─────────────┘ │              │
│  │                 │  │                 │  │                 │              │
│  │ ┌─────────────┐ │  │ ┌─────────────┐ │  │ ┌─────────────┐ │              │
│  │ │   Private   │ │  │ │   Private   │ │  │ │   Private   │ │  ← ECS, EKS │
│  │ │10.0.64.0/18 │ │  │ │10.0.128.0/18│ │  │ │10.0.192.0/18│ │              │
│  │ └─────────────┘ │  │ └─────────────┘ │  │ └─────────────┘ │              │
│  │                 │  │                 │  │                 │              │
│  │ ┌─────────────┐ │  │ ┌─────────────┐ │  │ ┌─────────────┐ │              │
│  │ │  Database   │ │  │ │  Database   │ │  │ │  Database   │ │  ← RDS,Redis│
│  │ │10.0.48.0/22 │ │  │ │10.0.49.0/22 │ │  │ │10.0.50.0/22 │ │              │
│  │ └─────────────┘ │  │ └─────────────┘ │  │ └─────────────┘ │              │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘              │
│                                                                              │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                         VPC Endpoints                                 │   │
│  │  S3 (Gateway) │ ECR.api │ ECR.dkr │ Logs │ SSM │ Secrets Manager    │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────────┘
         │                                    │
         ▼                                    ▼
    ┌─────────┐                        ┌──────────┐
    │   IGW   │                        │   NAT    │
    └─────────┘                        └──────────┘
         │                                    │
         ▼                                    ▼
    ┌──────────────────────────────────────────────┐
    │                  Internet                     │
    └──────────────────────────────────────────────┘
```

## Usage

### Basic Usage (Development)

```hcl
module "vpc" {
  source = "./infra/terraform/vpc"

  environment = "development"
  region      = "us-east-1"
  name_prefix = "oshun"

  vpc_cidr = "10.0.0.0/16"
  az_count = 2

  # Single NAT for cost savings
  single_nat_gateway = true

  tags = {
    Project = "oshun"
  }
}
```

### Production Usage (High Availability)

```hcl
module "vpc" {
  source = "./infra/terraform/vpc"

  environment = "production"
  region      = "us-east-1"
  name_prefix = "oshun"

  vpc_cidr = "10.0.0.0/16"
  az_count = 3

  # NAT Gateway per AZ for high availability
  single_nat_gateway     = false
  one_nat_gateway_per_az = true

  # Enable all features
  enable_vpc_endpoints = true
  enable_flow_logs     = true
  create_database_subnets = true

  vpc_endpoint_services = [
    "s3",
    "dynamodb",
    "ecr.api",
    "ecr.dkr",
    "logs",
    "secretsmanager",
    "ssm",
    "ssmmessages",
    "ec2messages"
  ]

  tags = {
    Project     = "oshun"
    Environment = "production"
  }
}
```

### Custom CIDR Configuration

```hcl
module "vpc" {
  source = "./infra/terraform/vpc"

  environment = "staging"
  region      = "us-east-1"
  name_prefix = "oshun"

  vpc_cidr = "172.16.0.0/16"

  # Custom subnet CIDRs
  public_subnet_cidrs   = ["172.16.0.0/24", "172.16.1.0/24", "172.16.2.0/24"]
  private_subnet_cidrs  = ["172.16.10.0/24", "172.16.11.0/24", "172.16.12.0/24"]
  database_subnet_cidrs = ["172.16.20.0/24", "172.16.21.0/24", "172.16.22.0/24"]
}
```

## Initialization

```bash
# Initialize with remote state backend
terraform init \
  -backend-config="bucket=oshun-terraform-state" \
  -backend-config="key=vpc/terraform.tfstate" \
  -backend-config="region=us-east-1" \
  -backend-config="dynamodb_table=oshun-terraform-locks" \
  -backend-config="encrypt=true"

# Plan
terraform plan -var="environment=production"

# Apply
terraform apply -var="environment=production"
```

## Inputs

| Name                    | Description            | Type     | Default         |
| ----------------------- | ---------------------- | -------- | --------------- |
| environment             | Deployment environment | `string` | -               |
| region                  | AWS region             | `string` | `"us-east-1"`   |
| vpc_cidr                | VPC CIDR block         | `string` | `"10.0.0.0/16"` |
| az_count                | Number of AZs to use   | `number` | `3`             |
| single_nat_gateway      | Use single NAT Gateway | `bool`   | `true`          |
| one_nat_gateway_per_az  | NAT per AZ (HA)        | `bool`   | `false`         |
| enable_vpc_endpoints    | Create VPC endpoints   | `bool`   | `true`          |
| enable_flow_logs        | Enable VPC Flow Logs   | `bool`   | `true`          |
| create_database_subnets | Create database tier   | `bool`   | `true`          |

See `variables.tf` for all available inputs.

## Outputs

| Name                       | Description                        |
| -------------------------- | ---------------------------------- |
| vpc_id                     | VPC ID                             |
| public_subnet_ids          | Public subnet IDs                  |
| private_subnet_ids         | Private subnet IDs                 |
| database_subnet_ids        | Database subnet IDs                |
| database_subnet_group_name | RDS subnet group name              |
| nat_gateway_public_ips     | NAT Gateway public IPs             |
| summary                    | Complete VPC configuration summary |

See `outputs.tf` for all available outputs.

## Cost Considerations

### NAT Gateway Costs

NAT Gateway charges ~$0.045/hour + $0.045/GB processed.

| Configuration  | Monthly Cost (approx) |
| -------------- | --------------------- |
| Single NAT     | $32 + data transfer   |
| NAT per AZ (3) | $97 + data transfer   |

### VPC Endpoint Costs

- **Gateway endpoints** (S3, DynamoDB): Free
- **Interface endpoints**: ~$7.30/month each + $0.01/GB

Enabling all 8 interface endpoints: ~$58/month

### Recommendations

- **Development**: Single NAT, minimal endpoints
- **Production**: NAT per AZ, all endpoints enabled

## Security Best Practices

1. **Default security group** is locked down (no traffic allowed)
2. **Database subnets** have no internet access
3. **Flow logs** capture all traffic for audit
4. **VPC endpoints** keep traffic within AWS network

## Troubleshooting

### Instances can't reach internet

1. Check NAT Gateway status
2. Verify private subnet route table has NAT route
3. Check security group egress rules

### Can't pull ECR images

Enable ECR VPC endpoints or ensure NAT Gateway is working:

```hcl
vpc_endpoint_services = ["ecr.api", "ecr.dkr", "s3"]
```

### High NAT costs

Consider:

1. Enable S3 VPC endpoint (free)
2. Review which services are making external calls
3. Use VPC endpoints for AWS services
