1# Terraform Patterns & Use Cases
2 
3Architecture patterns, multi-environment setups, and real-world use cases.
4 
5## Recommended Directory Structure
6 
7```
8terraform/
9├── environments/
10│   ├── production/
11│   │   ├── main.tf
12│   │   └── terraform.tfvars
13│   └── staging/
14│       ├── main.tf
15│       └── terraform.tfvars
16├── modules/
17│   ├── zone/
18│   ├── worker/
19│   └── dns/
20└── shared/          # Shared resources across envs
21    └── main.tf
22```
23 
24**Note:** Cloudflare recommends avoiding modules for provider resources due to v5 auto-generation complexity. Prefer environment directories + shared state instead.
25 
26## Multi-Environment Setup
27 
28```hcl
29# Directory: environments/{production,staging}/main.tf + modules/{zone,worker,pages}
30module "zone" {
31  source = "../../modules/zone"; account_id = var.account_id; zone_name = "example.com"; environment = "production"
32}
33module "api_worker" {
34  source = "../../modules/worker"; account_id = var.account_id; zone_id = module.zone.zone_id
35  name = "api-worker-prod"; script = file("../../workers/api.js"); environment = "production"
36}
37```
38 
39## R2 State Backend
40 
41```hcl
42terraform {
43  backend "s3" {
44    bucket = "terraform-state"
45    key = "cloudflare.tfstate"
46    region = "auto"
47    endpoints = { s3 = "https://<account_id>.r2.cloudflarestorage.com" }
48    skip_credentials_validation = true
49    skip_region_validation = true
50    skip_requesting_account_id = true
51    skip_metadata_api_check = true
52    skip_s3_checksum = true
53  }
54}
55```
56 
57## Worker with All Bindings
58 
59```hcl
60locals { worker_name = "full-stack-worker" }
61resource "cloudflare_workers_kv_namespace" "app" { account_id = var.account_id; title = "${local.worker_name}-kv" }
62resource "cloudflare_r2_bucket" "app" { account_id = var.account_id; name = "${local.worker_name}-bucket" }
63resource "cloudflare_d1_database" "app" { account_id = var.account_id; name = "${local.worker_name}-db" }
64 
65resource "cloudflare_worker_script" "app" {
66  account_id = var.account_id; name = local.worker_name; content = file("worker.js"); module = true
67  compatibility_date = "2025-01-01"
68  kv_namespace_binding { name = "KV"; namespace_id = cloudflare_workers_kv_namespace.app.id }
69  r2_bucket_binding { name = "BUCKET"; bucket_name = cloudflare_r2_bucket.app.name }
70  d1_database_binding { name = "DB"; database_id = cloudflare_d1_database.app.id }
71  secret_text_binding { name = "API_KEY"; text = var.api_key }
72}
73```
74 
75## Wrangler Integration
76 
77**CRITICAL**: Wrangler and Terraform must NOT manage same resources.
78 
79**Terraform**: Zones, DNS, security rules, Access, load balancers, worker deployments (CI/CD), KV/R2/D1 resource creation  
80**Wrangler**: Local dev (`wrangler dev`), manual deploys, D1 migrations, KV bulk ops, log streaming (`wrangler tail`)
81 
82### CI/CD Pattern
83 
84```hcl
85# Terraform creates infrastructure
86resource "cloudflare_workers_kv_namespace" "app" { account_id = var.account_id; title = "app-kv" }
87resource "cloudflare_d1_database" "app" { account_id = var.account_id; name = "app-db" }
88output "kv_namespace_id" { value = cloudflare_workers_kv_namespace.app.id }
89output "d1_database_id" { value = cloudflare_d1_database.app.id }
90```
91 
92```yaml
93# GitHub Actions: terraform apply → envsubst wrangler.jsonc.template → wrangler deploy
94- run: terraform apply -auto-approve
95- run: |
96    export KV_NAMESPACE_ID=$(terraform output -raw kv_namespace_id)
97    envsubst < wrangler.jsonc.template > wrangler.jsonc
98- run: wrangler deploy
99```
100 
101## Use Cases
102 
103### Static Site + API Worker
104 
105```hcl
106resource "cloudflare_pages_project" "frontend" {
107  account_id = var.account_id; name = "frontend"; production_branch = "main"
108  build_config { build_command = "npm run build"; destination_dir = "dist" }
109}
110resource "cloudflare_worker_script" "api" {
111  account_id = var.account_id; name = "api"; content = file("api-worker.js")
112  d1_database_binding { name = "DB"; database_id = cloudflare_d1_database.api_db.id }
113}
114resource "cloudflare_dns_record" "frontend" {
115  zone_id = cloudflare_zone.main.id; name = "app"; content = cloudflare_pages_project.frontend.subdomain; type = "CNAME"; proxied = true
116}
117resource "cloudflare_worker_route" "api" {
118  zone_id = cloudflare_zone.main.id; pattern = "api.example.com/*"; script_name = cloudflare_worker_script.api.name
119}
120```
121 
122### Multi-Region Load Balancing
123 
124```hcl
125resource "cloudflare_load_balancer_pool" "us" {
126  account_id = var.account_id; name = "us-pool"; monitor = cloudflare_load_balancer_monitor.http.id
127  origins { name = "us-east"; address = var.us_east_ip }
128}
129resource "cloudflare_load_balancer_pool" "eu" {
130  account_id = var.account_id; name = "eu-pool"; monitor = cloudflare_load_balancer_monitor.http.id
131  origins { name = "eu-west"; address = var.eu_west_ip }
132}
133resource "cloudflare_load_balancer" "global" {
134  zone_id = cloudflare_zone.main.id; name = "api.example.com"; steering_policy = "geo"
135  default_pool_ids = [cloudflare_load_balancer_pool.us.id]
136  region_pools { region = "WNAM"; pool_ids = [cloudflare_load_balancer_pool.us.id] }
137  region_pools { region = "WEU"; pool_ids = [cloudflare_load_balancer_pool.eu.id] }
138}
139```
140 
141### Secure Admin with Access
142 
143```hcl
144resource "cloudflare_pages_project" "admin" { account_id = var.account_id; name = "admin"; production_branch = "main" }
145resource "cloudflare_access_application" "admin" {
146  account_id = var.account_id; name = "Admin"; domain = "admin.example.com"; type = "self_hosted"; session_duration = "24h"
147  allowed_idps = [cloudflare_access_identity_provider.google.id]
148}
149resource "cloudflare_access_policy" "allow" {
150  account_id = var.account_id; application_id = cloudflare_access_application.admin.id
151  name = "Allow admins"; decision = "allow"; precedence = 1; include { email = var.admin_emails }
152}
153```
154 
155### Reusable Module
156 
157```hcl
158# modules/cloudflare-zone/main.tf
159variable "account_id" { type = string }; variable "domain" { type = string }; variable "ssl_mode" { default = "strict" }
160resource "cloudflare_zone" "main" { account = { id = var.account_id }; name = var.domain }
161resource "cloudflare_zone_settings_override" "main" {
162  zone_id = cloudflare_zone.main.id; settings { ssl = var.ssl_mode; always_use_https = "on" }
163}
164output "zone_id" { value = cloudflare_zone.main.id }
165 
166# Usage: module "prod" { source = "./modules/cloudflare-zone"; account_id = var.account_id; domain = "example.com" }
167```
168 
169## See Also
170 
171- [README](./README.md) - Provider setup
172- [Configuration Reference](./configuration.md) - All resource types
173- [API Reference](./api.md) - Data sources
174- [Troubleshooting](./gotchas.md) - Best practices, common issues
175