Cloudflare Terraform Provider

Expert guidance for Cloudflare Terraform Provider - infrastructure as code for Cloudflare resources.

Core Principles

Provider-first: Use Terraform provider for ALL infrastructure - never mix with wrangler.jsonc for the same resources
State management: Always use remote state (S3, Terraform Cloud, etc.) for team environments
Modular architecture: Create reusable modules for common patterns (zones, workers, pages)
Version pinning: Always pin provider version with ~> for predictable upgrades
Secret management: Use variables + environment vars for sensitive data - never hardcode API tokens

Provider Version

Version	Status	Notes
5.x	Current	Auto-generated from OpenAPI, breaking changes from v4
4.x	Legacy	Manual maintenance, deprecated

Critical: v5 renamed many resources (cloudflare_record → cloudflare_dns_record, cloudflare_worker_* → cloudflare_workers_*). See gotchas.md for migration details.

Provider Setup

Basic Configuration

terraform {
  required_version = ">= 1.0"
  
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 5.15.0"
    }
  }
}

provider "cloudflare" {
  api_token = var.cloudflare_api_token  # or CLOUDFLARE_API_TOKEN env var
}

Authentication Methods (priority order)

API Token (RECOMMENDED): api_token or CLOUDFLARE_API_TOKEN
- Create: Dashboard → My Profile → API Tokens
- Scope to specific accounts/zones for security
Global API Key (LEGACY): api_key + api_email or CLOUDFLARE_API_KEY + CLOUDFLARE_EMAIL
- Less secure, use tokens instead
User Service Key: user_service_key for Origin CA certificates

Quick Reference: Common Commands

terraform init          # Initialize provider
terraform plan          # Plan changes
terraform apply         # Apply changes
terraform destroy       # Destroy resources
terraform import cloudflare_zone.example <zone-id>  # Import existing
terraform state list    # List resources in state
terraform output        # Show outputs
terraform fmt -recursive  # Format code
terraform validate      # Validate configuration

Import Existing Resources

Use cf-terraforming to generate configs from existing Cloudflare resources:

# Install
brew install cloudflare/cloudflare/cf-terraforming

# Generate HCL from existing resources
cf-terraforming generate --resource-type cloudflare_dns_record --zone <zone-id>

# Import into Terraform state
cf-terraforming import --resource-type cloudflare_dns_record --zone <zone-id>

Reading Order

Start with README.md for provider setup and authentication
Review configuration.md for resource configurations
Check api.md for data sources and existing resource queries
See patterns.md for multi-environment and CI/CD patterns
Read gotchas.md for state drift, v5 breaking changes, and troubleshooting

In This Reference

configuration.md - Resources for zones, DNS, workers, KV, R2, D1, Pages, rulesets
api.md - Data sources for existing resources
patterns.md - Architecture patterns, multi-env setup, CI/CD integration
gotchas.md - Common issues, security, best practices

README.md