1# Cloudflare Terraform Provider
2 
3**Expert guidance for Cloudflare Terraform Provider - infrastructure as code for Cloudflare resources.**
4 
5## Core Principles
6 
7- **Provider-first**: Use Terraform provider for ALL infrastructure - never mix with wrangler.jsonc for the same resources
8- **State management**: Always use remote state (S3, Terraform Cloud, etc.) for team environments
9- **Modular architecture**: Create reusable modules for common patterns (zones, workers, pages)
10- **Version pinning**: Always pin provider version with `~>` for predictable upgrades
11- **Secret management**: Use variables + environment vars for sensitive data - never hardcode API tokens
12 
13## Provider Version
14 
15| Version | Status | Notes |
16|---------|--------|-------|
17| 5.x | Current | Auto-generated from OpenAPI, breaking changes from v4 |
18| 4.x | Legacy | Manual maintenance, deprecated |
19 
20**Critical:** v5 renamed many resources (`cloudflare_record` → `cloudflare_dns_record`, `cloudflare_worker_*` → `cloudflare_workers_*`). See [gotchas.md](./gotchas.md#v5-breaking-changes) for migration details.
21 
22## Provider Setup
23 
24### Basic Configuration
25 
26```hcl
27terraform {
28  required_version = ">= 1.0"
29  
30  required_providers {
31    cloudflare = {
32      source  = "cloudflare/cloudflare"
33      version = "~> 5.15.0"
34    }
35  }
36}
37 
38provider "cloudflare" {
39  api_token = var.cloudflare_api_token  # or CLOUDFLARE_API_TOKEN env var
40}
41```
42 
43### Authentication Methods (priority order)
44 
451. **API Token** (RECOMMENDED): `api_token` or `CLOUDFLARE_API_TOKEN`
46   - Create: Dashboard → My Profile → API Tokens
47   - Scope to specific accounts/zones for security
48   
492. **Global API Key** (LEGACY): `api_key` + `api_email` or `CLOUDFLARE_API_KEY` + `CLOUDFLARE_EMAIL`
50   - Less secure, use tokens instead
51   
523. **User Service Key**: `user_service_key` for Origin CA certificates
53 
54 
55 
56## Quick Reference: Common Commands
57 
58```bash
59terraform init          # Initialize provider
60terraform plan          # Plan changes
61terraform apply         # Apply changes
62terraform destroy       # Destroy resources
63terraform import cloudflare_zone.example <zone-id>  # Import existing
64terraform state list    # List resources in state
65terraform output        # Show outputs
66terraform fmt -recursive  # Format code
67terraform validate      # Validate configuration
68```
69 
70## Import Existing Resources
71 
72Use cf-terraforming to generate configs from existing Cloudflare resources:
73 
74```bash
75# Install
76brew install cloudflare/cloudflare/cf-terraforming
77 
78# Generate HCL from existing resources
79cf-terraforming generate --resource-type cloudflare_dns_record --zone <zone-id>
80 
81# Import into Terraform state
82cf-terraforming import --resource-type cloudflare_dns_record --zone <zone-id>
83```
84 
85## Reading Order
86 
871. Start with [README.md](./README.md) for provider setup and authentication
882. Review [configuration.md](./configuration.md) for resource configurations
893. Check [api.md](./api.md) for data sources and existing resource queries
904. See [patterns.md](./patterns.md) for multi-environment and CI/CD patterns
915. Read [gotchas.md](./gotchas.md) for state drift, v5 breaking changes, and troubleshooting
92 
93## In This Reference
94- [configuration.md](./configuration.md) - Resources for zones, DNS, workers, KV, R2, D1, Pages, rulesets
95- [api.md](./api.md) - Data sources for existing resources
96- [patterns.md](./patterns.md) - Architecture patterns, multi-env setup, CI/CD integration
97- [gotchas.md](./gotchas.md) - Common issues, security, best practices
98 
99## See Also
100- [pulumi](../pulumi/) - Alternative IaC tool for Cloudflare
101- [wrangler](../wrangler/) - CLI deployment alternative
102- [workers](../workers/) - Worker runtime documentation
103