Skip to main content

DevOps

Why We Still Use Cloudflare Terraform Provider v4 (And You Should Too)

Cloudflare's Terraform provider v5 launched with promises of better API coverage, but stability issues affect ~15% of resources. Here's why we're sticking with v4 for production deployments.

Cloud Associates

Cloud Associates

Cloudflare released their Terraform provider v5 in February 2025 with impressive promises: 100% API property coverage, 25% more resources, and over 200 additional data sources. On paper, it looked like a significant upgrade.

In practice? It’s been a bumpy ride.

We’ve been testing v5 on internal projects and we’ve made a deliberate decision: we’re sticking with v4 for production Cloudflare deployments until v5 stabilises further.

Here’s why, and what you should consider for your own infrastructure.

What Changed in v5

The v5 provider represents a fundamental architectural shift. Unlike v4, which was hand-crafted, v5 is automatically generated from Cloudflare’s OpenAPI schemas.

This approach has clear benefits:

  • Faster feature parity with new API capabilities
  • Consistent behaviour across all resources
  • Reduced maintenance burden for Cloudflare’s team

But auto-generation comes with trade-offs, and those trade-offs have caused real problems.

The Stability Issues

Cloudflare has been transparent about the problems. From their own changelog:

“We are aware of the high number of issues reported by the Cloudflare community related to the v5 release. These issues currently impact about 15% of resources.”

15% might not sound like much, but when you’re managing production infrastructure, hitting one of those broken resources can derail an entire deployment.

Common Issues We’ve Seen

1. Unexpected plan changes after migration

Resources that were stable in v4 suddenly show changes in terraform plan after upgrading to v5, even when nothing has actually changed. This is particularly problematic for cloudflare_zone and cloudflare_record resources.

2. State drift on apply

Some resources don’t properly reconcile state after terraform apply, leading to perpetual drift that requires manual intervention.

3. Breaking changes in resource schemas

Attribute names and structures changed between v4 and v5, requiring significant refactoring of existing Terraform code.

4. Missing migration tooling

While Cloudflare promised migration scripts, comprehensive tooling is still in development. The current migration path requires careful manual work.

Cloudflare’s Response

Credit where it’s due: Cloudflare has acknowledged the issues and committed to fixing them. They’ve:

  • Shifted to a 2-week release cadence for stability improvements
  • Pivoted to a resource-by-resource stabilisation approach
  • Invested in more comprehensive test-driven development
  • Promised migration scripts (still in progress)

From their August 2025 changelog:

“We have pivoted from an issue-to-issue approach to a resource-per-resource approach - we will be focusing on specific resources for every release, stabilizing the release and closing all associated bugs with that resource before moving onto resolving migration issues.”

This is the right approach, but it takes time.

Our Recommendation: Stay on v4 for Now

For production infrastructure, we recommend staying on v4 until:

  1. The affected resource percentage drops below 5%
  2. Migration tooling is mature and well-documented
  3. You have time to thoroughly test the migration in a non-production environment

How to Pin to v4

In your versions.tf or provider block:

terraform {
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 4.0"
    }
  }
}

This ensures you stay on the latest v4.x release without accidentally upgrading to v5.

For OpenTofu Users

The same constraint works in OpenTofu:

terraform {
  required_providers {
    cloudflare = {
      source  = "cloudflare/cloudflare"
      version = "~> 4.0"
    }
  }
}

When to Consider v5

v5 isn’t all bad. Consider it if:

  • You’re starting a greenfield project with no existing Cloudflare Terraform state
  • You need features only available in v5 (check the changelog)
  • You have dedicated time for testing and can tolerate some instability
  • The specific resources you need are confirmed stable in v5

Check the Cloudflare Terraform provider issues to see if your specific resources are affected.

Migration Strategy (When You’re Ready)

When v5 stabilises and you’re ready to migrate:

1. Audit your current resources

List all Cloudflare resources in your state:

terraform state list | grep cloudflare_

2. Check each resource against known issues

Review the GitHub issues for each resource type you use.

3. Test in isolation

Create a separate workspace or state file to test the migration without affecting production.

4. Plan for state surgery

Some migrations require terraform state rm and terraform import cycles. Document your rollback plan.

5. Migrate during low-traffic periods

Even with careful planning, have a maintenance window ready.

What We Do for Clients

When we deliver Cloudflare infrastructure as code for clients, we:

  1. Pin to v4 for all production deployments
  2. Document the upgrade path so clients can migrate when ready
  3. Monitor v5 stability and advise when it’s safe to upgrade
  4. Test v5 compatibility in staging environments

This approach gives clients stable, production-ready infrastructure today while keeping the door open for future upgrades.

The Bigger Picture

This situation highlights an important principle: new isn’t always better for production infrastructure.

Auto-generated providers are the future—they scale better and stay current with API changes. But that future isn’t quite here yet for Cloudflare’s Terraform provider.

The good news? Cloudflare is actively fixing issues, and v5 will eventually be the right choice. Just not today.

Need help with Cloudflare infrastructure as code? Our Cloudflare CDN/WAF service includes Terraform/OpenTofu implementation with proper version pinning and upgrade documentation.

References