1# AWS Application Load Balancer (ALB) Setup
2
3This guide covers deploying Gordon behind AWS Application Load Balancer for TLS termination.
4
5## Overview
6
7AWS ALB is a Layer 7 load balancer that:
8- Terminates TLS connections
9- Forwards requests to your EC2 instances or ECS containers
10- Automatically scales with traffic
11- Sets `X-Forwarded-For` header with the client's real IP
12
13## Architecture
14
15```
16Client → ALB (HTTPS/443) → Gordon (HTTP/80) → Containers
17              ↓
18         TLS terminated
19         X-Forwarded-For set
20```
21
22## Understanding VPC CIDR
23
24A **VPC** (Virtual Private Cloud) is your isolated network in AWS. Every VPC has a **CIDR** (Classless Inter-Domain Routing) block—the private IP range used by resources in that VPC.
25
26ALB connects to Gordon from within your VPC, so Gordon sees the ALB's private IP, not the client's public IP. The client IP is passed via `X-Forwarded-For`.
27
28**To find your VPC CIDR:**
29
301. Go to AWS Console → VPC → Your VPCs
312. Find the **IPv4 CIDR** column
323. Common values: `10.0.0.0/16`, `172.31.0.0/16`
33
34## Gordon Configuration
35
36```toml
37[api.rate_limit]
38enabled = true
39# Trust your VPC CIDR so Gordon reads X-Forwarded-For from ALB
40trusted_proxies = ["10.0.0.0/16"]  # Replace with your VPC CIDR
41```
42
43### Multiple VPCs or Subnets
44
45If Gordon receives traffic from multiple VPCs (e.g., via VPC peering):
46
47```toml
48[api.rate_limit]
49trusted_proxies = [
50    "10.0.0.0/16",   # Production VPC
51    "10.1.0.0/16",   # Staging VPC
52]
53```
54
55## ALB Configuration
56
57### Target Group Settings
58
59When creating your ALB target group:
60
61| Setting | Value |
62|---------|-------|
63| Target type | `instance` or `ip` |
64| Protocol | HTTP |
65| Port | 80 (or your Gordon port) |
66| Health check path | `/health` or `/v2/` |
67
68### Client IP Preservation
69
70ALB automatically sets `X-Forwarded-For`. No special configuration needed for HTTP targets.
71
72For **NLB** (Network Load Balancer) with TCP, you may need to enable Proxy Protocol v2:
73
74```yaml
75# Kubernetes annotation for AWS Load Balancer Controller
76service.beta.kubernetes.io/aws-load-balancer-proxy-protocol: "*"
77```
78
79## Verifying the Setup
80
811. Make a request through the ALB
822. Check Gordon logs for the client IP:
83
84```bash
85# Should show real client IP, not ALB IP
86journalctl -u gordon | grep "client_ip"
87```
88
89If you see the ALB's private IP (e.g., `10.0.x.x`) instead of the client's public IP, check that:
90- `trusted_proxies` includes your VPC CIDR
91- ALB is forwarding `X-Forwarded-For` (default behavior)
92
93## Security Groups
94
95Ensure your security groups allow:
96
97| Source | Destination | Port | Purpose |
98|--------|-------------|------|---------|
99| `0.0.0.0/0` | ALB | 443 | HTTPS from internet |
100| ALB SG | Gordon SG | 80 | ALB to Gordon |
101
102## Terraform Example
103
104```hcl
105resource "aws_lb" "gordon" {
106  name               = "gordon-alb"
107  internal           = false
108  load_balancer_type = "application"
109  security_groups    = [aws_security_group.alb.id]
110  subnets            = var.public_subnets
111}
112
113resource "aws_lb_listener" "https" {
114  load_balancer_arn = aws_lb.gordon.arn
115  port              = "443"
116  protocol          = "HTTPS"
117  ssl_policy        = "ELBSecurityPolicy-TLS13-1-2-2021-06"
118  certificate_arn   = var.certificate_arn
119
120  default_action {
121    type             = "forward"
122    target_group_arn = aws_lb_target_group.gordon.arn
123  }
124}
125
126resource "aws_lb_target_group" "gordon" {
127  name     = "gordon-tg"
128  port     = 80
129  protocol = "HTTP"
130  vpc_id   = var.vpc_id
131
132  health_check {
133    path                = "/v2/"
134    healthy_threshold   = 2
135    unhealthy_threshold = 10
136  }
137}
138```
139
140## Troubleshooting
141
142### All requests show the same IP
143
144**Symptom:** Rate limiting doesn't work, logs show ALB IP for all requests.
145
146**Cause:** `trusted_proxies` doesn't include ALB's IP range.
147
148**Fix:** Add your VPC CIDR to `trusted_proxies`.
149
150### 502 Bad Gateway
151
152**Symptom:** ALB returns 502 errors.
153
154**Cause:** Gordon health check failing or not listening.
155
156**Fix:** Verify Gordon is running and health check path is correct.
157
158## Related
159
160- [Rate Limiting Configuration](../../docs/config/rate-limiting.md)
161- [Running Gordon in a Container](./running-in-container.md)