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

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.

cloudflare/tf-migrate