{"id":13505796,"url":"https://github.com/cloudflare/cf-terraforming","last_synced_at":"2025-05-14T08:06:45.618Z","repository":{"id":37549542,"uuid":"160878303","full_name":"cloudflare/cf-terraforming","owner":"cloudflare","description":"A command line utility to facilitate terraforming your existing Cloudflare resources.","archived":false,"fork":false,"pushed_at":"2025-04-29T21:53:30.000Z","size":8247,"stargazers_count":1135,"open_issues_count":34,"forks_count":156,"subscribers_count":24,"default_branch":"master","last_synced_at":"2025-04-29T22:34:24.374Z","etag":null,"topics":["cloudflare","terraform"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudflare.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-12-07T21:41:47.000Z","updated_at":"2025-04-29T19:03:04.000Z","dependencies_parsed_at":"2023-10-12T10:45:22.948Z","dependency_job_id":"4525e8c2-6a0f-4edc-b8b2-26ea4426a1f9","html_url":"https://github.com/cloudflare/cf-terraforming","commit_stats":{"total_commits":868,"total_committers":61,"mean_commits":"14.229508196721312","dds":0.6670506912442397,"last_synced_commit":"e62988f44b9ac92bd31d80c9622c2c565981a50a"},"previous_names":[],"tags_count":43,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fcf-terraforming","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fcf-terraforming/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fcf-terraforming/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudflare%2Fcf-terraforming/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudflare","download_url":"https://codeload.github.com/cloudflare/cf-terraforming/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101618,"owners_count":22014909,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","terraform"],"created_at":"2024-08-01T00:01:14.002Z","updated_at":"2025-05-14T08:06:40.604Z","avatar_url":"https://github.com/cloudflare.png","language":"Go","funding_links":[],"categories":["Tools","Go","Developer Tools"],"sub_categories":["Community providers","Infrastructure as Code"],"readme":"# Cloudflare Terraforming\n\n## Overview\n\n`cf-terraforming` is a command line utility to facilitate terraforming your\nexisting Cloudflare resources. It does this by using your account credentials to\nretrieve your configurations from the [Cloudflare API](https://api.cloudflare.com)\nand converting them to Terraform configurations that can be used with the\n[Terraform Cloudflare provider](https://registry.terraform.io/providers/cloudflare/cloudflare/latest).\n\nThis tool is ideal if you already have Cloudflare resources defined but want to\nstart managing them via Terraform, and don't want to spend the time to manually\nwrite the Terraform configuration to describe them.\n\nRead the [announcement blog](https://blog.cloudflare.com/cloudflares-partnership-with-hashicorp-and-bootstrapping-terraform-with-cf-terraforming/) for further details on using `cf-terraforming` in your workflow.\n\n\u003e [!NOTE]\n\u003e If you would like to export resources compatible with Terraform \u003c 0.12.x,\n\u003e you will need to download an older release as this tool no longer supports it.\n\n## Usage\n\n```\nUsage:\n cf-terraforming [command]\n\nAvailable Commands:\n completion Generate the autocompletion script for the specified shell\n generate Fetch resources from the Cloudflare API and generate the respective Terraform stanzas\n help Help about any command\n import Output `terraform import` compatible commands in order to import resources into state\n version Print the version number of cf-terraforming\n\nFlags:\n -a, --account string Target the provided account ID for the command\n -c, --config string Path to config file (default \"~/.cf-terraforming.yaml\")\n -e, --email string API Email address associated with your account\n -h, --help help for cf-terraforming\n --hostname string Hostname to use to query the API\n -k, --key string API Key generated on the 'My Profile' page. See: https://dash.cloudflare.com/profile\n --modern-import-block Whether to generate HCL import blocks for generated resources instead of terraform import compatible CLI commands. This is only compatible with Terraform 1.5+\n --resource-type string Comma delimitered string of which resource(s) you wish to generate\n --terraform-binary-path string Path to an existing Terraform binary (otherwise, one will be downloaded)\n --terraform-install-path string Path to an initialized Terraform working directory (default \".\")\n -t, --token string API Token\n -v, --verbose Specify verbose output (same as setting log level to debug)\n -z, --zone string Target the provided zone ID for the command\n\nUse \"cf-terraforming [command] --help\" for more information about a command.\n```\n\n## Authentication\n\nCloudflare supports two authentication methods to the API:\n\n- API Token - gives access only to resources and permissions specified for that token (recommended)\n- API key - gives access to everything your user profile has access to\n\nBoth can be retrieved on the [user profile page](https://dash.cloudflare.com/profile/api-tokens).\n\n\u003e [!TIP]\n\u003e We recommend that you store your Cloudflare credentials (API key, email, token) as environment\n\u003e variables as demonstrated below.\n\n```bash\n# if using API Token\nexport CLOUDFLARE_API_TOKEN='Hzsq3Vub-7Y-hSTlAaLH3Jq_YfTUOCcgf22_Fs-j'\n\n# if using API Key\nexport CLOUDFLARE_EMAIL='user@example.com'\nexport CLOUDFLARE_API_KEY='1150bed3f45247b99f7db9696fffa17cbx9'\n\n# specify zone ID\nexport CLOUDFLARE_ZONE_ID='81b06ss3228f488fh84e5e993c2dc17'\n\n# now call cf-terraforming, e.g.\ncf-terraforming generate \\\n --resource-type \"cloudflare_record\" \\\n --zone $CLOUDFLARE_ZONE_ID\n```\n\ncf-terraforming supports the following environment variables:\n\n- CLOUDFLARE_API_TOKEN - API Token based authentication\n- CLOUDFLARE_EMAIL, CLOUDFLARE_API_KEY - API Key based authentication\n\nAlternatively, if using a config file, then specify the inputs using the same\nnames the `flag` names. Example:\n\n```\ncat ~/.cf-terraforming.yaml\nemail: \"email@domain.com\"\nkey: \"\u003ckey\u003e\"\n#or\ntoken: \"\u003ctoken\u003e\"\n```\n\n## Example usage\n\n```bash\ncf-terraforming generate \\\n --zone $CLOUDFLARE_ZONE_ID \\\n --resource-type \"cloudflare_record\"\n```\n\nwill contact the Cloudflare API on your behalf and result in a valid Terraform\nconfiguration representing the **resource** you requested:\n\n```hcl\nresource \"cloudflare_record\" \"terraform_managed_resource\" {\n name = \"example.com\"\n proxied = false\n ttl = 120\n type = \"A\"\n value = \"198.51.100.4\"\n zone_id = \"0da42c8d2132a9ddaf714f9e7c920711\"\n}\n```\n\n## Prerequisites\n\n- A Cloudflare account with resources defined (e.g. a few zones, some load\n balancers, spectrum applications, etc)\n- A valid Cloudflare API key and sufficient permissions to access the resources\n you are requesting via the API\n- An initialised Terraform directory (`terraform init` has run and providers installed). See the [provider documentation](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs) if you have not yet setup the Terraform directory.\n\n## Installation\n\n### Homebrew\n\n```bash\nbrew tap cloudflare/cloudflare\nbrew install cloudflare/cloudflare/cf-terraforming\n```\n\n\u003e [!NOTE]\n\u003e If you have installed an older version of `cf-terraforming` via Homebrew,\n\u003e you may need to first uninstall `cf-terraforming` and then install it to\n\u003e pick up the updated install process and address the signing/notarisation\n\u003e issues.\n\n### Go\n\n```bash\ngo install github.com/cloudflare/cf-terraforming/cmd/cf-terraforming@latest\n```\n\nIf you use another OS, you will need to download the release directly from\n[GitHub Releases](https://github.com/cloudflare/cf-terraforming/releases) or\nbuild the Go source.\n\n## Importing with Terraform state\n\n`cf-terraforming` has the ability to generate the configuration for you to import\nexisting resources.\n\nDepending on your version of Terraform, you can generate the `import` block\n(Terraform 1.5+) using the `--modern-import-block` flag or the `terraform import`\ncompatible CLI output (all versions).\n\nThis command assumes you have already ran `cf-terraforming generate ...` to\noutput your resources.\n\n```\n# All versions of Terraform\ncf-terraforming import \\\n --resource-type \"cloudflare_record\" \\\n --email $CLOUDFLARE_EMAIL \\\n --key $CLOUDFLARE_API_KEY \\\n --zone $CLOUDFLARE_ZONE_ID\n```\n\n```\n# Terraform 1.5+ only\ncf-terraforming import \\\n --resource-type \"cloudflare_record\" \\\n --modern-import-block \\\n --email $CLOUDFLARE_EMAIL \\\n --key $CLOUDFLARE_API_KEY \\\n --zone $CLOUDFLARE_ZONE_ID\n```\n\n## Using non-standard Terraform binaries\n\nInternally, we use [`terraform-exec`](https://github.com/hashicorp/terraform-exec)\nlibrary to run Terraform operations in the same way that the CLI tooling would.\nIf a `terraform` binary is not available on your system path, we will attempt\nto download the latest to use it.\n\nShould you have the binary stored in a non-standard location, want to use an\nexisting binary, or you wish to provide a Terraform compatible binary (such as\n`tofu`), you need to provide the `--terraform-binary-path` flag or\n`CLOUDFLARE_TERRAFORM_BINARY_PATH` environment variable to instruct\n`cf-terraforming` which you expect to use.\n\n## CDKTF\n\nIf you'd like to use [cdktf](https://developer.hashicorp.com/terraform/cdktf)\nfor your project resources, you can pipe the output from `cf-terraforming` into\n`cdktf convert` in order to correctly generate CDKTF output automatically.\n\nExample:\n\n```\ncf-terraforming generate \\\n --resource-type \"cloudflare_record\" \\\n --zone \"0da42c8d2132a9ddaf714f9e7c920711\" \\\n| cdktf convert --language \"typescript\" --provider \"cloudflare/cloudflare\"\n```\n\n## Supported Resources\n\n### v5\n\nAny resource that is released within the Terraform Provider is automatically\nsupported for generation and import.\n\n### v4\n\nAny resources not listed are currently not supported.\n\n| Resource | Resource Scope | Generate Supported | Import Supported |\n| ------------------------------------------------------------------------------------------------------------------------------------------------ | --------------- | ------------------ | ---------------- |\n| [cloudflare_access_application](https://www.terraform.io/docs/providers/cloudflare/r/access_application) | Account | ✅ | ✅ |\n| [cloudflare_access_group](https://www.terraform.io/docs/providers/cloudflare/r/access_group) | Account | ✅ | ✅ |\n| [cloudflare_access_identity_provider](https://www.terraform.io/docs/providers/cloudflare/r/access_identity_provider) | Account | ✅ | ❌ |\n| [cloudflare_access_mutual_tls_certificate](https://www.terraform.io/docs/providers/cloudflare/r/access_mutual_tls_certificate) | Account | ✅ | ❌ |\n| [cloudflare_access_policy](https://www.terraform.io/docs/providers/cloudflare/r/access_policy) | Account | ❌ | ❌ |\n| [cloudflare_access_rule](https://www.terraform.io/docs/providers/cloudflare/r/access_rule) | Account | ✅ | ✅ |\n| [cloudflare_access_service_token](https://www.terraform.io/docs/providers/cloudflare/r/access_service_token) | Account | ✅ | ❌ |\n| [cloudflare_account_member](https://www.terraform.io/docs/providers/cloudflare/r/account_member) | Account | ✅ | ✅ |\n| [cloudflare_api_shield](https://www.terraform.io/docs/providers/cloudflare/r/api_shield) | Zone | ✅ | ❌ |\n| [cloudflare_api_token](https://www.terraform.io/docs/providers/cloudflare/r/api_token) | User | ❌ | ❌ |\n| [cloudflare_argo](https://www.terraform.io/docs/providers/cloudflare/r/argo) | Zone | ✅ | ✅ |\n| [cloudflare_authenticated_origin_pulls](https://www.terraform.io/docs/providers/cloudflare/r/authenticated_origin_pulls) | Zone | ❌ | ❌ |\n| [cloudflare_authenticated_origin_pulls_certificate](https://www.terraform.io/docs/providers/cloudflare/r/authenticated_origin_pulls_certificate) | Zone | ❌ | ❌ |\n| [cloudflare_bot_management](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/bot_management) | Zone | ✅ | ✅ |\n| [cloudflare_byo_ip_prefix](https://www.terraform.io/docs/providers/cloudflare/r/byo_ip_prefix) | Account | ✅ | ✅ |\n| [cloudflare_certificate_pack](https://www.terraform.io/docs/providers/cloudflare/r/certificate_pack) | Zone | ✅ | ✅ |\n| [cloudflare_custom_hostname](https://www.terraform.io/docs/providers/cloudflare/r/custom_hostname) | Zone | ✅ | ✅ |\n| [cloudflare_custom_hostname_fallback_origin](https://www.terraform.io/docs/providers/cloudflare/r/custom_hostname_fallback_origin) | Account | ✅ | ❌ |\n| [cloudflare_custom_pages](https://www.terraform.io/docs/providers/cloudflare/r/custom_pages) | Account or Zone | ✅ | ✅ |\n| [cloudflare_custom_ssl](https://www.terraform.io/docs/providers/cloudflare/r/custom_ssl) | Zone | ✅ | ✅ |\n| [cloudflare_filter](https://www.terraform.io/docs/providers/cloudflare/r/filter) | Zone | ✅ | ✅ |\n| [cloudflare_firewall_rule](https://www.terraform.io/docs/providers/cloudflare/r/firewall_rule) | Zone | ✅ | ✅ |\n| [cloudflare_healthcheck](https://www.terraform.io/docs/providers/cloudflare/r/healthcheck) | Zone | ✅ | ✅ |\n| [cloudflare_ip_list](https://www.terraform.io/docs/providers/cloudflare/r/ip_list) | Account | ❌ | ✅ |\n| [cloudflare_list](https://www.terraform.io/docs/providers/cloudflare/r/list) | Account | ✅ | ❌ |\n| [cloudflare_load_balancer](https://www.terraform.io/docs/providers/cloudflare/r/load_balancer) | Zone | ✅ | ✅ |\n| [cloudflare_load_balancer_monitor](https://www.terraform.io/docs/providers/cloudflare/r/load_balancer_monitor) | Account | ✅ | ✅ |\n| [cloudflare_load_balancer_pool](https://www.terraform.io/docs/providers/cloudflare/r/load_balancer_pool) | Account | ✅ | ✅ |\n| [cloudflare_logpull_retention](https://www.terraform.io/docs/providers/cloudflare/r/logpull_retention) | Zone | ❌ | ❌ |\n| [cloudflare_logpush_job](https://www.terraform.io/docs/providers/cloudflare/r/logpush_job) | Zone | ✅ | ❌ |\n| [cloudflare_logpush_ownership_challenge](https://www.terraform.io/docs/providers/cloudflare/r/logpush_ownership_challenge) | Zone | ❌ | ❌ |\n| [cloudflare_magic_firewall_ruleset](https://www.terraform.io/docs/providers/cloudflare/r/magic_firewall_ruleset) | Account | ❌ | ❌ |\n| [cloudflare_origin_ca_certificate](https://www.terraform.io/docs/providers/cloudflare/r/origin_ca_certificate) | Zone | ✅ | ✅ |\n| [cloudflare_page_rule](https://www.terraform.io/docs/providers/cloudflare/r/page_rule) | Zone | ✅ | ✅ |\n| [cloudflare_rate_limit](https://www.terraform.io/docs/providers/cloudflare/r/rate_limit) | Zone | ✅ | ✅ |\n| [cloudflare_record](https://www.terraform.io/docs/providers/cloudflare/r/record) | Zone | ✅ | ✅ |\n| [cloudflare_ruleset](https://www.terraform.io/docs/providers/cloudflare/r/ruleset) | Account or Zone | ✅ | ✅ |\n| [cloudflare_spectrum_application](https://www.terraform.io/docs/providers/cloudflare/r/spectrum_application) | Zone | ✅ | ✅ |\n| [cloudflare_tiered_cache](https://www.terraform.io/docs/providers/cloudflare/r/tiered_cache) | Zone | ✅ | ❌ |\n| [cloudflare_teams_list](https://www.terraform.io/docs/providers/cloudflare/r/teams_list) | Account | ✅ | ✅ |\n| [cloudflare_teams_location](https://www.terraform.io/docs/providers/cloudflare/r/teams_location) | Account | ✅ | ✅ |\n| [cloudflare_teams_proxy_endpoint](https://www.terraform.io/docs/providers/cloudflare/r/teams_proxy_endpoint) | Account | ✅ | ✅ |\n| [cloudflare_teams_rule](https://www.terraform.io/docs/providers/cloudflare/r/teams_rule) | Account | ✅ | ✅ |\n| [cloudflare_tunnel](https://www.terraform.io/docs/providers/cloudflare/r/tunnel) | Account | ✅ | ✅ |\n| [cloudflare_turnstile_widget](https://registry.terraform.io/providers/cloudflare/cloudflare/latest/docs/resources/turnstile_widget) | Account | ✅ | ✅ |\n| [cloudflare_url_normalization_settings](https://www.terraform.io/docs/providers/cloudflare/r/url_normalization_settings) | Zone | ✅ | ❌ |\n| [cloudflare_waf_group](https://www.terraform.io/docs/providers/cloudflare/r/waf_group) | Zone | ❌ | ❌ |\n| [cloudflare_waf_override](https://www.terraform.io/docs/providers/cloudflare/r/waf_override) | Zone | ✅ | ✅ |\n| [cloudflare_waf_package](https://www.terraform.io/docs/providers/cloudflare/r/waf_package) | Zone | ✅ | ❌ |\n| [cloudflare_waf_rule](https://www.terraform.io/docs/providers/cloudflare/r/waf_rule) | Zone | ❌ | ❌ |\n| [cloudflare_waiting_room](https://www.terraform.io/docs/providers/cloudflare/r/waiting_room) | Zone | ✅ | ✅ |\n| [cloudflare_worker_cron_trigger](https://www.terraform.io/docs/providers/cloudflare/r/worker_cron_trigger) | Account | ❌ | ❌ |\n| [cloudflare_worker_route](https://www.terraform.io/docs/providers/cloudflare/r/worker_route) | Zone | ✅ | ✅ |\n| [cloudflare_worker_script](https://www.terraform.io/docs/providers/cloudflare/r/worker_script) | Account | ❌ | ❌ |\n| [cloudflare_workers_kv](https://www.terraform.io/docs/providers/cloudflare/r/workers_kv) | Account | ❌ | ❌ |\n| [cloudflare_workers_kv_namespace](https://www.terraform.io/docs/providers/cloudflare/r/workers_kv_namespace) | Account | ✅ | ✅ |\n| [cloudflare_zone](https://www.terraform.io/docs/providers/cloudflare/r/zone) | Account | ✅ | ✅ |\n| [cloudflare_zone_dnssec](https://www.terraform.io/docs/providers/cloudflare/r/zone_dnssec) | Zone | ❌ | ❌ |\n| [cloudflare_zone_lockdown](https://www.terraform.io/docs/providers/cloudflare/r/zone_lockdown) | Zone | ✅ | ✅ |\n| [cloudflare_zone_settings_override](https://www.terraform.io/docs/providers/cloudflare/r/zone_settings_override) | Zone | ✅ | ❌ |\n\n## Testing\n\nTo ensure changes don't introduce regressions this tool uses an automated test\nsuite consisting of HTTP mocks via go-vcr and Terraform configuration files to\nassert against. The premise is that we mock the HTTP responses from the\nCloudflare API to ensure we don't need to create and delete real resources to\ntest. The Terraform files then allow us to build what the resource structure is\nexpected to look like and once the tool parses the API response, we can compare\nthat to the static file.\n\nSuggested local testing steps:\n\n1. Create a file with the basic provider configuration (do not commit this file)\n\n```bash\ncat \u003e main.tf \u003c\u003cEOF\nterraform {\n required_providers {\n cloudflare = {\n source = \"cloudflare/cloudflare\"\n version = \"~\u003e 4\"\n }\n }\n}\nEOF\n```\n\n2. Initialize terraform\n\n```bash\nterraform init\n```\n\n3. Run tests (Cloudflare Install path should be path to repository)\n\n```bash\nmake test\n```\n\nIf you want to run a specific test case you can do so with the TESTARGS variable and -run flag\n\n```bash\nTESTARGS=\"-run '^TestResourceGeneration/cloudflare_teams_list'\" make test\n```\n\n## Updating VCR cassettes\n\nPeriodically, it is a good idea to recreate the VCR cassettes used in our\ntesting to ensure they haven't drifted from actual responses. To do this, you\nwill need to:\n\n- Create the appropriate resource in a Cloudflare account/zone you have access\n to. This is required as overwriting cassettes makes real API requests on your\n behalf.\n- Invoke the test suite with `OVERWRITE_VCR_CASSETTES=true`,\n `CLOUDFLARE_DOMAIN=\u003creal domain here\u003e`, authentication credentials\n (`CLOUDFLARE_EMAIL`, `CLOUDFLARE_KEY`, `CLOUDFLARE_API_TOKEN`) and the test\n you want to update.\n Example of updating the DNS CAA record test with a zone I own:\n\n```bash\n OVERWRITE_VCR_CASSETTES=true \\\n CLOUDFLARE_DOMAIN=\"terraform.cfapi.net\" \\\n CLOUDFLARE_EMAIL=\"jb@example.com\" \\\n CLOUDFLARE_API_KEY=\"...\" \\\n TESTARGS=\"-run '^TestResourceGeneration/cloudflare_record_caa'\" \\\n make test\n```\n\n- Commit your changes and push them via a Pull Request.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fcf-terraforming","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudflare%2Fcf-terraforming","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudflare%2Fcf-terraforming/lists"}