cf-terraforming
is a command line utility to facilitate terraforming your
existing Cloudflare resources. It does this by using your account credentials to
retrieve your configurations from the Cloudflare API
and converting them to Terraform configurations that can be used with the
Terraform Cloudflare provider.
This tool is ideal if you already have Cloudflare resources defined but want to start managing them via Terraform, and don't want to spend the time to manually write the Terraform configuration to describe them.
Read the announcement blog for further details on using cf-terraforming
in your workflow.
NOTE: If you would like to export resources compatible with Terraform < 0.12.x, you will need to download an older release as this tool no longer supports it.
Usage:
cf-terraforming [command]
Available Commands:
generate Fetch resources from the Cloudflare API and generate the respective Terraform stanzas
help Help about any command
import Output `terraform import` compatible commands in order to import resources into state
version Print the version number of cf-terraforming
Flags:
-a, --account string Use specific account ID for commands
-c, --config string Path to configuration file (default is $HOME/.cf-terraforming.yaml)
-e, --email string API Email address associated with your account
-h, --help Help for cf-terraforming
-k, --key string API Key generated on the 'My Profile' page. See: https://dash.cloudflare.com/profile
--resource-type string Which resource you wish to generate
--terraform-binary-path string Path to an existing Terraform binary (otherwise, one will be downloaded)
--terraform-install-path string Path to an initialized Terraform working directory (default ".")
-t, --token string API Token
-v, --verbose Specify verbose output (same as setting log level to debug)
-z, --zone string Limit the export to a single zone ID
Use "cf-terraforming [command] --help" for more information about a command.
Cloudflare supports two authentication methods to the API:
- API Token - gives access only to resources and permissions specified for that token (recommended)
- API key - gives access to everything your user profile has access to
Both can be retrieved on the user profile page.
A note on storing your credentials securely: We recommend that you store your Cloudflare credentials (API key, email, token) as environment variables as demonstrated below.
# if using API Token
export CLOUDFLARE_API_TOKEN='Hzsq3Vub-7Y-hSTlAaLH3Jq_YfTUOCcgf22_Fs-j'
# if using API Key
export CLOUDFLARE_EMAIL='[email protected]'
export CLOUDFLARE_API_KEY='1150bed3f45247b99f7db9696fffa17cbx9'
# specify zone ID
export CLOUDFLARE_ZONE_ID='81b06ss3228f488fh84e5e993c2dc17'
# now call cf-terraforming, e.g.
cf-terraforming generate \
--resource-type "cloudflare_record" \
--zone $CLOUDFLARE_ZONE_ID
cf-terraforming supports the following environment variables:
- CLOUDFLARE_API_TOKEN - API Token based authentication
- CLOUDFLARE_EMAIL, CLOUDFLARE_API_KEY - API Key based authentication
Alternatively, if using a config file, then specify the inputs using the same
names the flag
names. Example:
$ cat ~/.cf-terraforming.yaml
email: "[email protected]"
key: "<key>"
#or
token: "<token>"
$ cf-terraforming generate \
--zone $CLOUDFLARE_ZONE_ID \
--resource-type "cloudflare_record"
will contact the Cloudflare API on your behalf and result in a valid Terraform configuration representing the resource you requested:
resource "cloudflare_record" "terraform_managed_resource" {
name = "example.com"
proxied = false
ttl = 120
type = "A"
value = "198.51.100.4"
zone_id = "0da42c8d2132a9ddaf714f9e7c920711"
}
- A Cloudflare account with resources defined (e.g. a few zones, some load balancers, spectrum applications, etc)
- A valid Cloudflare API key and sufficient permissions to access the resources you are requesting via the API
- An initialised Terraform directory (
terraform init
has run and providers installed). See the provider documentation if you have not yet setup the Terraform directory.
If you use Homebrew on MacOS, you can run the following:
$ brew tap cloudflare/cloudflare
$ brew install --cask cloudflare/cloudflare/cf-terraforming
If you use another OS, you will need to download the release directly from GitHub Releases.
cf-terraforming
will output the terraform import
compatible commands for you
when you invoke the import
command. This command assumes you have already ran
cf-terraforming generate ...
to output your resources.
In the future we aim to automate this however for now, it is a manual step to allow flexibility in directory structure.
$ cf-terraforming import \
--resource-type "cloudflare_record" \
--email $CLOUDFLARE_EMAIL \
--key $CLOUDFLARE_API_KEY \
--zone $CLOUDFLARE_ZONE_ID
Any resources not listed are currently not supported.
Last updated Apr 13, 2021
To ensure changes don't introduce regressions this tool uses an automated test suite consisting of HTTP mocks via go-vcr and Terraform configuration files to assert against. The premise is that we mock the HTTP responses from the Cloudflare API to ensure we don't need to create and delete real resources to test. The Terraform files then allow us to build what the resource structure is expected to look like and once the tool parses the API response, we can compare that to the static file.
Periodically, it is a good idea to recreate the VCR cassettes used in our testing to ensure they haven't drifted from actual responses. To do this, you will need to:
- Create the appropriate resource in a Cloudflare account/zone you have access to. This is required as overwriting cassettes makes real API requests on your behalf.
- Invoke the test suite with
OVERWRITE_VCR_CASSETTES=true
,CLOUDFLARE_DOMAIN=<real domain here>
, authentication credentials (CLOUDFLARE_EMAIL
,CLOUDFLARE_KEY
,CLOUDFLARE_API_TOKEN
) and the test you want to update. Example of updating the DNS CAA record test with a zone I own:$ OVERWRITE_VCR_CASSETTES=true \ CLOUDFLARE_DOMAIN="terraform.cfapi.net" \ CLOUDFLARE_EMAIL="[email protected]" \ CLOUDFLARE_API_KEY="..." \ TESTARGS="-run '^TestResourceGeneration/cloudflare_record_caa'" \ make test
- Commit your changes and push them via a Pull Request.