tf-migrate - Cloudflare Terraform Provider Migration Tool

A powerful CLI tool for automatically migrating Terraform configurations and state files between different versions of the Cloudflare Terraform Provider.

Overview

tf-migrate helps you upgrade your Terraform infrastructure code by automatically transforming:

• Configuration files (.tf) - Updates resource types, attribute names, and block structures
• State files (terraform.tfstate) - Migrates resource state to match new provider schemas

Currently supports migrations:

• v4 → v5: Cloudflare Provider v4 to v5

Installation

Building from Source

# Clone the repository
git clone <repository-url>
cd tf-migrate

# Build the binary
make

# The binary will be available as ./tf-migrate

Requirements

• Go 1.25 or later
• Make
• Terraform (for testing migrated configurations)

Usage

Authentication

Some resource migrations require access to the Cloudflare API to complete the migration successfully. The tool supports two authentication methods:

Option 1: API Token (Recommended)

export CLOUDFLARE_API_TOKEN="your-api-token"

Option 2: API Key + Email

export CLOUDFLARE_API_KEY="your-api-key"
export CLOUDFLARE_EMAIL="[email protected]"

Resources Requiring Authentication

The following resources require API credentials for complete migration:

• cloudflare_tunnel_route → cloudflare_zero_trust_tunnel_cloudflared_route
  • Why: The v4 provider stored network CIDR as the resource ID, but v5 requires the UUID from the API. The migration queries the API to fetch the correct UUID for your tunnel routes.
  • Without credentials: The migration will still update resource types and attributes, but you'll need to run terraform refresh after migration to update the IDs.

Basic Migration

Migrate all Terraform files in the current directory:

tf-migrate migrate --source-version v4 --target-version v5

Migrate Specific Directory

tf-migrate migrate --config-dir ./terraform --source-version v4 --target-version v5

Include State File Migration

tf-migrate migrate \
  --config-dir ./terraform \
  --state-file terraform.tfstate \
  --source-version v4 \
  --target-version v5

Dry Run Mode

Preview changes without modifying files:

tf-migrate migrate --dry-run --source-version v4 --target-version v5

Migrate Specific Resources Only

tf-migrate migrate \
  --resources dns_record,zero_trust_list \
  --source-version v4 \
  --target-version v5

Output to Different Directory

tf-migrate migrate \
  --config-dir ./terraform \
  --output-dir ./terraform-v5 \
  --state-file terraform.tfstate \
  --output-state terraform-v5.tfstate \
  --source-version v4 \
  --target-version v5

Command Reference

Global Flags

Flag	Description	Default
--config-dir	Directory containing Terraform configuration files	Current directory
--state-file	Path to Terraform state file	None
--source-version	Source provider version (e.g., v4)	Required
--target-version	Target provider version (e.g., v5)	Required
--resources	Comma-separated list of resources to migrate	All resources
--dry-run	Preview changes without modifying files	false
--log-level	Set log level (debug, info, warn, error, off)	warn

Migrate Command Flags

Flag	Description	Default
--output-dir	Output directory for migrated configuration files	In-place
--output-state	Output path for migrated state file	In-place
--backup	Create backup of original files before migration	true

Running Tests

Unit Tests

Run all unit tests:

go test ./...

Run tests for a specific package:

go test ./internal/resources/dns_record -v

Run with coverage:

go test ./... -cover

Integration Tests

Integration tests verify the complete migration workflow using real configuration and state files.

# Run all v4 to v5 integration tests
cd integration/v4_to_v5
go test -v

# Run tests for a specific resource
go test -v -run TestV4ToV5Migration/DNSRecord

# Test a single resource using environment variable
TEST_RESOURCE=dns_record go test -v -run TestSingleResource

# Run with detailed diff output (set KEEP_TEMP to see test directory)
KEEP_TEMP=true TEST_RESOURCE=dns_record go test -v -run TestSingleResource

Test Organization

Integration tests are organized by version migration path:

• integration/test_runner.go - Shared test runner used by all version tests
• integration/v4_to_v5/ - Tests for v4 to v5 migrations
  • integration_test.go - Test suite specific to v4→v5
  • testdata/ - Test fixtures for each resource
• Future: integration/v5_to_v6/ - Tests for v5 to v6 migrations
  • integration_test.go - Test suite specific to v5→v6
  • testdata/ - Test fixtures for each resource

Each version migration has its own test suite with explicit migration registration, while sharing the common test runner infrastructure.

End-to-End Tests

E2E tests validate the complete migration workflow with real Cloudflare resources. These tests:

1. Apply v4 Terraform configs to create real infrastructure
2. Run the migration tool to generate v5 configs
3. Apply v5 configs and verify no changes are needed
4. Compare v4 and v5 state to ensure equivalence

Requirements:

• Cloudflare API credentials for "Terraform Test" account (set as CLOUDFLARE_API_KEY and CLOUDFLARE_EMAIL)
• Terraform installed

# Run E2E tests
cd ..
./scripts/run-e2e-tests

Output:

• Test logs saved to e2e/tmp/*.log
• State snapshots saved to e2e/tmp/*-state.json