cf-iac-and-deployment

Cloudflare IaC and Deployment

When to use

• Setting up a new Worker, Pages, or D1 project with production-grade defaults.
• Writing or reviewing wrangler.toml / wrangler.jsonc for multi-environment deploys.
• Authoring or migrating Terraform for Cloudflare resources (especially v4 → v5 provider migration).
• Designing a CI/CD pipeline with GitHub Actions that deploys to Cloudflare using scoped API tokens.
• Managing Workers secrets safely across environments.
• Reviewing an existing IaC repo for drift, secret hygiene, or missing resources.

Wrangler (the Cloudflare CLI)

Wrangler is the canonical tool for developing, testing, and deploying Workers and Pages projects. Wrangler ≥ 4.x (npm install -D wrangler@latest) is required for current features.

wrangler.toml vs wrangler.jsonc

• Use wrangler.toml (TOML format) unless your project has an existing wrangler.jsonc (JSON5 with comments) convention.
• wrangler.jsonc supports comments and is friendlier for complex configs with inline documentation.
• Do not mix formats in the same project.

Configuration structure

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2025-01-01"   # Pin; advance deliberately.
compatibility_flags = []

# Shared bindings (available in all environments)
[[kv_namespaces]]
binding = "SESSIONS"
id = "abc123..."

[env.production]
name = "my-worker-production"
[[env.production.kv_namespaces]]
binding = "SESSIONS"
id = "xyz789..."          # Different namespace ID per environment.

[[env.production.d1_databases]]
binding = "DB"
database_name = "my-db-prod"
database_id = "..."

[env.production.placement]
mode = "smart"            # Smart Placement for production if origin-latency matters.

Key rules:

• compatibility_date: pin to a specific date; check Cloudflare's compatibility changelog before advancing.
• Separate resource IDs per environment — never share a KV namespace or D1 database between production and development.
• main: always explicit; never rely on convention defaults in production configs.
• Secrets are NOT declared in wrangler.toml — they are pushed via wrangler secret put.