cf-terraforming

The cf-terraforming CLI tool supports any resource released within version 5 of the Cloudflare Terraform Provider. This means the tool can automatically generate HCL configuration for these resources.

Note on validation: Some generated HCL configurations may fail the terraform validate command due to schema inconsistencies. These are known issues that are addressed in subsequent releases. If a resource is not explicitly listed as supported, the tool may still generate HCL, but manual modifications might be required to ensure correctness.

To make the cf-terraforming command globally accessible from any terminal session, move the compiled binary to a directory included in your $PATH, such as /usr/local/bin/.

sudo mv cf-terraforming /usr/local/bin/
cf-terraforming --help

cf-terraforming supports two authentication methods. It is recommended to store credentials as environment variables.

Option 1: API Token (Recommended)

Use the CLOUDFLARE_API_TOKEN environment variable.

export CLOUDFLARE_API_TOKEN='your-api-token'

Option 2: API Key

Use the CLOUDFLARE_EMAIL and CLOUDFLARE_API_KEY environment variables.

export CLOUDFLARE_EMAIL='user@example.com'
export CLOUDFLARE_API_KEY='your-api-key'

Using a Config File

You can also use a YAML config file (default path: /Users/vaishak/.cf-terraforming.yaml). Use the same names as the CLI flags:

email: "email@domain.com"
key: "<key>"
# or
token: "<token>"

export CLOUDFLARE_API_TOKEN='Hzsq3Vub-7Y-hSTlAaLH3Jq_YfTUOCcgf22_Fs-j'

cf-terraforming can generate the necessary commands or blocks to import existing resources into your Terraform state.

For Terraform 1.5+ (Modern Import Blocks)

Use the --modern-import-block flag to generate HCL import blocks.

cf-terraforming import \
  --resource-type "cloudflare_record" \
  --modern-import-block \
  --email $CLOUDFLARE_EMAIL \
  --key $CLOUDFLARE_API_KEY \
  --zone $CLOUDFLARE_ZONE_ID

For all Terraform versions (CLI Commands)

Generates standard terraform import compatible CLI commands.

cf-terraforming import \
  --resource-type "cloudflare_record" \
  --email $CLOUDFLARE_EMAIL \
  --key $CLOUDFLARE_API_KEY \
  --zone $CLOUDFLARE_ZONE_ID

To build the cf-terraforming binary manually, clone the repository and use the Go compiler. This creates an executable in your current directory.

git clone https://github.com/cloudflare/cf-terraforming.git
cd cf-terraforming
go build -o cf-terraforming ./cmd/cf-terraforming
./cf-terraforming --help

Use the generate command to retrieve existing Cloudflare resources and convert them into Terraform HCL blocks.

Prerequisites:

• An initialized Terraform directory (terraform init must have been run).
• A valid Cloudflare API credential.

Basic Usage

cf-terraforming generate \
  --zone $CLOUDFLARE_ZONE_ID \
  --resource-type "cloudflare_record"

Resources requiring specific IDs

Some resources require a specific ID mapping using the --resource-id flag in the format resource_type=id_value.

Example for cloudflare_hostname_tls_setting:

cf-terraforming generate \
  --zone $CLOUDFLARE_ZONE_ID \
  --resource-type "cloudflare_hostname_tls_setting" \
  --resource-id "cloudflare_hostname_tls_setting=ciphers"

To quickly install cf-terraforming into your current working directory without a manual build process, use the go install command with GOBIN set to your current path.

GOBIN=$(pwd) go install -v github.com/cloudflare/cf-terraforming/cmd/cf-terraforming@master

The project uses an automated test suite with HTTP mocks (via go-vcr) and Terraform configuration files. To run the full test suite, ensure you have initialized Terraform in your environment first.

1. Create a main.tf with the required provider configuration:

cat > main.tf <<EOF
terraform {
  required_providers {
    cloudflare = {
      source = "cloudflare/cloudflare"
      version = "(~> 4 or ~> 5)"
    }
  }
}
EOF

2. Initialize Terraform:

terraform init

3. Run the tests using make:

make test

To run a specific test case, use the TESTARGS environment variable with the -run flag:

TESTARGS="-run '^TestResourceGeneration/cloudflare_teams_list'" make test

To prevent test drift, you can recreate the VCR cassettes by making real API requests. This requires having a real resource in a Cloudflare account/zone you control.

Set OVERWRITE_VCR_CASSETTES=true and provide necessary authentication credentials (CLOUDFLARE_EMAIL, CLOUDFLARE_API_KEY or CLOUDFLARE_API_TOKEN) and the target domain (CLOUDFLARE_DOMAIN).

Example of updating the DNS CAA record test:

OVERWRITE_VCR_CASSETTES=true \
  CLOUDFLARE_DOMAIN="terraform.cfapi.net" \
  CLOUDFLARE_EMAIL="jb@example.com" \
  CLOUDFLARE_API_KEY="..." \
  TESTARGS="-run '^TestResourceGeneration/cloudflare_record_caa'" \
  make test

You can install cf-terraforming using Homebrew or Go.

Homebrew

brew tap cloudflare/cloudflare
brew install cloudflare/cloudflare/cf-terraforming

Go

go install github.com/cloudflare/cf-terraforming/cmd/cf-terraforming@latest

If you are on another OS, download the release directly from GitHub Releases or build from the Go source.

cf-terraforming uses the terraform-exec library. If your Terraform binary is not in your system path, or if you want to use a specific version or a compatible binary like tofu, you must specify the path.

You can do this via the --terraform-binary-path flag or the CLOUDFLARE_TERRAFORM_BINARY_PATH environment variable.

The cf-terraforming tool performs automatic post-processing on generated HCL (HashiCorp Configuration Language) for certain resource types to ensure compatibility with Terraform functions. This is handled internally during the generation process.

Supported transformations include:

• jsonencode wrapping: For cloudflare_stream_live_input and cloudflare_stream resources, the meta attribute is automatically wrapped with the jsonencode() function if the attribute value is a JSON object (starts with {).
• urlencode wrapping: For cloudflare_observatory_scheduled_test resources, the url attribute is automatically wrapped with the urlencode() function.