# Oshun Application Load Balancer Terraform Module

This Terraform module creates an Application Load Balancer (ALB) with HTTPS
support for routing traffic to ECS services.

## Features

- **HTTPS/TLS termination**: ACM certificate integration
- **HTTP to HTTPS redirect**: Automatic secure redirect
- **Access logging**: S3 bucket for ALB logs
- **Path-based routing**: Route to different services by URL path
- **Host-based routing**: Route by domain/subdomain
- **WAF integration**: Optional AWS WAF protection
- **Cross-zone load balancing**: Distribute traffic across AZs

## Architecture

```
                                  ┌───────────────────────────────────┐
                                  │        Route 53 (DNS)             │
                                  │     app.oshun.example.com         │
                                  └───────────────┬───────────────────┘
                                                  │
                                                  ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                    Application Load Balancer                                 │
│                                                                              │
│  ┌───────────────┐  ┌───────────────┐  ┌───────────────────────────────┐   │
│  │ HTTP Listener │  │HTTPS Listener │  │      WAF (Optional)           │   │
│  │    :80        │─▶│    :443       │  └───────────────────────────────┘   │
│  │  (redirect)   │  │ (TLS termn.)  │                                       │
│  └───────────────┘  └───────┬───────┘                                       │
│                             │                                                │
│           ┌─────────────────┼─────────────────┐                             │
│           │                 │                 │                             │
│           ▼                 ▼                 ▼                             │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐               │
│  │  /api/isis/*    │ │ /api/sophia/*   │ │    /studio/*    │               │
│  │ (Target Group)  │ │ (Target Group)  │ │ (Target Group)  │               │
│  └────────┬────────┘ └────────┬────────┘ └────────┬────────┘               │
└───────────┼───────────────────┼───────────────────┼─────────────────────────┘
            │                   │                   │
            ▼                   ▼                   ▼
     ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
     │ Isis Service │   │Sophia Service│   │Yemaya Studio │
     │   (Fargate)  │   │   (Fargate)  │   │   (Fargate)  │
     └──────────────┘   └──────────────┘   └──────────────┘
```

## Usage

### Basic Usage

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

  environment       = "production"
  region            = "us-east-1"
  vpc_id            = module.vpc.vpc_id
  public_subnet_ids = module.vpc.public_subnet_ids

  certificate_arn = "arn:aws:acm:us-east-1:123456789:certificate/xxx"

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

### With Custom Service Routes

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

  environment       = "production"
  region            = "us-east-1"
  vpc_id            = module.vpc.vpc_id
  public_subnet_ids = module.vpc.public_subnet_ids

  certificate_arn = "arn:aws:acm:us-east-1:123456789:certificate/xxx"

  service_routes = [
    {
      name             = "isis-api"
      priority         = 100
      target_group_arn = aws_lb_target_group.isis.arn
      path_patterns    = ["/api/generation/*", "/api/workflows/*"]
    },
    {
      name             = "sophia-api"
      priority         = 110
      target_group_arn = aws_lb_target_group.sophia.arn
      path_patterns    = ["/api/search/*", "/api/knowledge/*"]
    },
    {
      name             = "yemaya-studio"
      priority         = 200
      target_group_arn = aws_lb_target_group.yemaya.arn
      host_headers     = ["studio.oshun.example.com"]
    }
  ]
}
```

### With WAF Protection

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

  environment       = "production"
  vpc_id            = module.vpc.vpc_id
  public_subnet_ids = module.vpc.public_subnet_ids

  certificate_arn = "arn:aws:acm:us-east-1:123456789:certificate/xxx"

  enable_waf      = true
  waf_web_acl_arn = aws_wafv2_web_acl.main.arn
}
```

### Internal ALB (Private)

```hcl
module "alb_internal" {
  source = "./infra/terraform/alb"

  environment       = "production"
  name_prefix       = "oshun-internal"
  vpc_id            = module.vpc.vpc_id
  public_subnet_ids = module.vpc.private_subnet_ids # Use private subnets

  internal                      = true
  create_https_listener         = false  # No TLS for internal
  enable_http_to_https_redirect = false
}
```

## Initialization

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

# Plan
terraform plan

# Apply
terraform apply
```

## Inputs

| Name               | Description            | Type           | Default |
| ------------------ | ---------------------- | -------------- | ------- |
| environment        | Deployment environment | `string`       | -       |
| vpc_id             | VPC ID                 | `string`       | -       |
| public_subnet_ids  | Subnet IDs for ALB     | `list(string)` | -       |
| certificate_arn    | ACM certificate ARN    | `string`       | `""`    |
| internal           | Internal ALB           | `bool`         | `false` |
| enable_access_logs | Enable S3 access logs  | `bool`         | `true`  |
| enable_waf         | Enable WAF             | `bool`         | `false` |
| service_routes     | Service routing rules  | `list(object)` | `[]`    |

See `variables.tf` for all available inputs.

## Outputs

| Name               | Description                    |
| ------------------ | ------------------------------ |
| alb_arn            | ALB ARN                        |
| alb_dns_name       | ALB DNS name                   |
| alb_zone_id        | Route 53 zone ID               |
| https_listener_arn | HTTPS listener ARN             |
| security_group_id  | ALB security group ID          |
| summary            | Complete configuration summary |

## Creating Target Groups for Services

Each ECS service should create its own target group:

```hcl
resource "aws_lb_target_group" "my_service" {
  name        = "my-service-tg"
  port        = 8080
  protocol    = "HTTP"
  vpc_id      = var.vpc_id
  target_type = "ip"  # Required for Fargate

  health_check {
    enabled             = true
    path                = "/health"
    port                = "traffic-port"
    protocol            = "HTTP"
    interval            = 30
    timeout             = 5
    healthy_threshold   = 2
    unhealthy_threshold = 3
    matcher             = "200"
  }

  deregistration_delay = 30
}
```

## Route 53 Configuration

Create an alias record pointing to the ALB:

```hcl
resource "aws_route53_record" "app" {
  zone_id = aws_route53_zone.main.zone_id
  name    = "app.example.com"
  type    = "A"

  alias {
    name                   = module.alb.alb_dns_name
    zone_id                = module.alb.alb_zone_id
    evaluate_target_health = true
  }
}
```

## Cost Considerations

| Component                         | Cost (approx)             |
| --------------------------------- | ------------------------- |
| ALB                               | $0.0225/hour (~$16/month) |
| LCU (Load Balancer Capacity Unit) | $0.008/LCU-hour           |
| Access Logs (S3)                  | Standard S3 pricing       |

## Security Best Practices

1. **Use HTTPS**: Always enable TLS with a valid certificate
2. **Drop invalid headers**: Prevent header injection attacks
3. **Enable WAF**: For production, enable AWS WAF with managed rules
4. **Restrict access**: Use security groups to limit source IPs
5. **Enable access logs**: For security audit and troubleshooting
