Cloudflare Terraform Provider 資源配置完全指南Zone、Workers、存儲、Rulesets 與 Zero Trust 的 HCL 實戰(zhàn)【免費下載鏈接】skillsSkills Catalog for Codex項目地址: https://gitcode.com/GitHub_Trending/skills4/skills本指南基于 Skills 倉庫 cloudflare-deploy 技能包中的 Terraform 配置參考文檔系統(tǒng)講解使用官方cloudflare/cloudflareTerraform Provider 對 Cloudflare 全?；A(chǔ)設(shè)施進(jìn)行聲明式管理的方法。你將掌握 Zone 與 DNS、Workers含漸進(jìn)式發(fā)布與各類 Binding、KV/R2/D1/Queue 存儲、Pages、RulesetsWAF/重定向/緩存、負(fù)載均衡與 Zero Trust Access 的完整 HCL 寫法并了解 v5 版本的關(guān)鍵變化與避坑要點可直接用于生產(chǎn)環(huán)境的 IaC 落地。閱讀前準(zhǔn)備Provider 版本與認(rèn)證在動手寫資源之前先確認(rèn)你使用的 Provider 版本。Cloudflare 官方 Terraform Provider 目前分兩代版本狀態(tài)說明5.x當(dāng)前版本基于 OpenAPI 自動生成與 v4 相比存在破壞性變更4.x舊版手動維護(hù)已棄用關(guān)鍵提醒v5 對大量資源做了重命名例如cloudflare_record→cloudflare_dns_record、cloudflare_worker_*→cloudflare_workers_*注意是復(fù)數(shù)形式。詳細(xì)遷移對照見 gotchas.md 的 v5 破壞性變更章節(jié)?；A(chǔ) Provider 配置來自 terraform/README.mdterraform { required_version 1.0 required_providers { cloudflare { source cloudflare/cloudflare version ~ 5.15.0 } } } provider cloudflare { api_token var.cloudflare_api_token # 或使用 CLOUDFLARE_API_TOKEN 環(huán)境變量 }認(rèn)證方式按推薦優(yōu)先級排列API Token推薦api_token或CLOUDFLARE_API_TOKEN環(huán)境變量。在 Dashboard → My Profile → API Tokens 創(chuàng)建建議將權(quán)限范圍限定到具體 Account/Zone 以降低泄露風(fēng)險。Global API Key舊版api_keyapi_email或CLOUDFLARE_API_KEYCLOUDFLARE_EMAIL安全性較低優(yōu)先使用 Token。User Service Keyuser_service_key用于 Origin CA 證書場景。常用命令速查terraform init # 初始化 Provider terraform plan # 預(yù)覽變更 terraform apply # 應(yīng)用變更 terraform destroy # 銷毀資源 terraform import cloudflare_zone.example zone-id # 導(dǎo)入已有資源 terraform state list # 列出狀態(tài)中的資源 terraform output # 查看輸出 terraform fmt -recursive # 格式化代碼 terraform validate # 校驗配置Zone 與 DNS 配置Zone 是 Cloudflare 管理的域名實體配置時通過account對象語法指定所屬賬號type full表示完整托管即使用 Cloudflare 的 Name Server。# Zone 站點級設(shè)置 resource cloudflare_zone example { account { id var.account_id } name example.com type full } resource cloudflare_zone_settings_override example { zone_id cloudflare_zone.example.id settings { ssl strict # 嚴(yán)格 SSL要求源站具備有效證書 always_use_https on # 強(qiáng)制 HTTPS min_tls_version 1.2 # 最低 TLS 版本 tls_1_3 on # 啟用 TLS 1.3 http3 on # 啟用 HTTP/3 (QUIC) } }DNS 記錄支持 A、CNAME、MX、TXT 等類型。proxied true表示開啟橙色云代理流量經(jīng)過 Cloudflare 邊緣false則為僅 DNS 解析# A 記錄 resource cloudflare_dns_record www { zone_id cloudflare_zone.example.id name www content 192.0.2.1 type A proxied true } # 使用 for_each 批量創(chuàng)建 MX 記錄priority 對應(yīng) each.key resource cloudflare_dns_record mx { for_each { 10 mail1.example.com, 20 mail2.example.com } zone_id cloudflare_zone.example.id name content each.value type MX priority each.key }提示for_each批量創(chuàng)建是處理多 MX、多 TXT如 SPF/DKIM等重復(fù)型記錄的常用手法可大幅減少樣板代碼。若需查詢已有 Zone 而非新建可參考 api.md 中的cloudflare_zoneData Source 用法。Workers兩種部署模式簡單模式舊式仍可用使用cloudflare_workers_script一次性聲明腳本內(nèi)容、兼容日期與全部 Bindingresource cloudflare_workers_script api { account_id var.account_id name api-worker content file(worker.js) module true compatibility_date 2025-01-01 # 各類 Binding詳見下方 v5 Binding 類型表 kv_namespace_binding { name KV; namespace_id cloudflare_workers_kv_namespace.cache.id } r2_bucket_binding { name BUCKET; bucket_name cloudflare_r2_bucket.assets.name } d1_database_binding { name DB; database_id cloudflare_d1_database.app.id } secret_text_binding { name SECRET; text var.secret } }module true表示使用 ES Module 格式的 Workercompatibility_date決定運行時兼容行為版本。注意secret_text_binding的text應(yīng)來自變量嚴(yán)禁硬編碼到源碼。漸進(jìn)式發(fā)布生產(chǎn)環(huán)境推薦生產(chǎn)環(huán)境推薦將「腳本定義」與「版本發(fā)布」分離通過cloudflare_worker_version指定腳本內(nèi)容與 SHA256 摘要確保內(nèi)容可校驗再用cloudflare_workers_deployment控制版本流量比例# 定義 Worker不含內(nèi)容 resource cloudflare_worker api { account_id var.account_id name api-worker } # 定義一個不可變版本 resource cloudflare_worker_version api_v1 { account_id var.account_id worker_name cloudflare_worker.api.name content file(worker.js) content_sha256 filesha256(worker.js) compatibility_date 2025-01-01 bindings { kv_namespace { name KV; namespace_id cloudflare_workers_kv_namespace.cache.id } r2_bucket { name BUCKET; bucket_name cloudflare_r2_bucket.assets.name } } } # 將版本發(fā)布到 100% 流量 resource cloudflare_workers_deployment api { account_id var.account_id worker_name cloudflare_worker.api.name versions { version_id cloudflare_worker_version.api_v1.id percentage 100 } }這種「Worker Version Deployment」三段式結(jié)構(gòu)支持金絲雀發(fā)布先發(fā)布percentage 10觀察指標(biāo)再逐步提升到 100是生產(chǎn)環(huán)境的推薦做法。Worker Binding 類型一覽Provider v5Binding屬性示例KVkv_namespace_binding{ name KV, namespace_id ... }R2r2_bucket_binding{ name BUCKET, bucket_name ... }D1d1_database_binding{ name DB, database_id ... }Serviceservice_binding{ name AUTH, service auth-worker }Secretsecret_text_binding{ name API_KEY, text ... }Queuequeue_binding{ name QUEUE, queue_name ... }Vectorizevectorize_binding{ name INDEX, index_name ... }Hyperdrivehyperdrive_binding{ name DB, id ... }AIai_binding{ name AI }Browserbrowser_binding{ name BROWSER }Analyticsanalytics_engine_binding{ name ANALYTICS, dataset ... }mTLSmtls_certificate_binding{ name CERT, certificate_id ... }Binding 名稱即 Worker 運行時env對象中的字段名Worker 側(cè)的類型定義與完整示例可參見 bindings/configuration.md其中也提到所有類型 Binding 合計上限為 64 個。路由與定時觸發(fā)器Worker 需要路由才能對外提供服務(wù)也支持 Cron 定時觸發(fā)# HTTP 路由api.example.com 下所有路徑 resource cloudflare_worker_route api { zone_id cloudflare_zone.example.id pattern api.example.com/* script_name cloudflare_workers_script.api.name } # Cron 觸發(fā)器每 5 分鐘執(zhí)行一次 resource cloudflare_worker_cron_trigger task { account_id var.account_id script_name cloudflare_workers_script.api.name schedules [*/5 * * * *] }Cron 調(diào)度表達(dá)式使用標(biāo)準(zhǔn) Unix Cron 語法完整能力可參考 cron-triggers。存儲資源KV、R2、D1 與 Queue# KV命名空間 預(yù)置一個鍵值對值為 JSON resource cloudflare_workers_kv_namespace cache { account_id var.account_id title cache } resource cloudflare_workers_kv config { account_id var.account_id namespace_id cloudflare_workers_kv_namespace.cache.id key_name config value jsonencode({ version 1.0 }) } # R2對象存儲桶l(fā)ocation 必須大寫詳見下方避坑 resource cloudflare_r2_bucket assets { account_id var.account_id name assets location WNAM } # D1關(guān)系型數(shù)據(jù)庫schema 遷移需通過 wrangler 執(zhí)行見下文 resource cloudflare_d1_database app { account_id var.account_id name app-db } # Queue消息隊列 resource cloudflare_queue events { account_id var.account_id name events-queue }注意細(xì)節(jié)KV 鍵名v5 中屬性名為key_namev4 為key同時需要namespace_id關(guān)聯(lián)命名空間。R2 location 大小寫location必須使用大寫字母如WNAM、ENAM、WEUR、EEUR、APAC小寫會導(dǎo)致創(chuàng)建后再次 apply 失敗見 gotchas.md。D1 只建庫不建表Terraform 僅創(chuàng)建 D1 數(shù)據(jù)庫資源本身表結(jié)構(gòu)與數(shù)據(jù)遷移必須用 wrangler 完成wrangler d1 migrations apply db-name。上述資源創(chuàng)建后即可在上文 Worker Binding 中引用id/name/bucket_name/database_id形成完整的資源依賴鏈。Pages 項目Pages 適合前端靜態(tài)站點與全棧應(yīng)用Terraform 中通過cloudflare_pages_project管理項目、環(huán)境變量、構(gòu)建配置與 Git 源resource cloudflare_pages_project site { account_id var.account_id name site production_branch main deployment_configs { production { compatibility_date 2025-01-01 environment_variables { NODE_ENV production } kv_namespaces { KV cloudflare_workers_kv_namespace.cache.id } d1_databases { DB cloudflare_d1_database.app.id } } } build_config { build_command npm run build destination_dir dist } source { type github config { owner org repo_name site production_branch main } } } # 綁定自定義域名 resource cloudflare_pages_domain custom { account_id var.account_id project_name cloudflare_pages_project.site.name domain site.example.com }deployment_configs.production中可按環(huán)境注入 KV/D1 Binding 與環(huán)境變量build_config控制構(gòu)建命令與產(chǎn)物目錄source聲明 GitHub 源碼倉庫實現(xiàn)推送即部署。已知問題cloudflare_pages_project的deployment_configs.*存在狀態(tài)漂移Cloudflare API 會回填默認(rèn)值建議在lifecycle中加入ignore_changes [deployment_configs]詳見 gotchas.md 的狀態(tài)漂移章節(jié)。RulesetsWAF、重定向與緩存規(guī)則Ruleset 是 Cloudflare 統(tǒng)一的規(guī)則引擎通過phase指定作用階段# WAF 自定義規(guī)則攔截機(jī)器人流量但放行 Cloudflare 驗證過的機(jī)器人 resource cloudflare_ruleset waf { zone_id cloudflare_zone.example.id name WAF kind zone phase http_request_firewall_custom rules { action block enabled true expression (cf.client.bot) and not (cf.verified_bot) } } # 動態(tài)重定向/old → https://example.com/new301 resource cloudflare_ruleset redirects { zone_id cloudflare_zone.example.id name Redirects kind zone phase http_request_dynamic_redirect rules { action redirect enabled true expression (http.request.uri.path eq \/old\) action_parameters { from_value { status_code 301 target_url { value https://example.com/new } } } } } # 緩存規(guī)則對靜態(tài)資源開啟邊緣緩存TTL 覆蓋源站為 86400 秒 resource cloudflare_ruleset cache { zone_id cloudflare_zone.example.id name Cache kind zone phase http_request_cache_settings rules { action set_cache_settings enabled true expression (http.request.uri.path matches \\\.(jpg|png|css|js)$\) action_parameters { cache true edge_ttl { mode override_origin # 覆蓋源站 Cache-Control default 86400 } } } }關(guān)鍵點phase 決定規(guī)則類型http_request_firewall_customWAF 自定義規(guī)則、http_request_dynamic_redirect動態(tài)重定向、http_request_cache_settings緩存設(shè)置。expression使用 Cloudflare 規(guī)則表達(dá)式語言支持eq、matches等操作符與cf.*、http.request.*字段。WAF 規(guī)則表達(dá)式中cf.client.bot判斷客戶端是否為機(jī)器人cf.verified_bot識別通過驗證的合法爬蟲兩者組合可實現(xiàn)精準(zhǔn)攔截。WAF 更多玩法見 waf。負(fù)載均衡Load Balancers由「健康檢查 Monitor 源站池 Pool 負(fù)載均衡器 LB」三層組成# 健康檢查每 60 秒對 /health 發(fā)起 HTTP 探測超時 5 秒 resource cloudflare_load_balancer_monitor http { account_id var.account_id type http path /health interval 60 timeout 5 } # 源站池掛載 Monitor聲明多個源站 resource cloudflare_load_balancer_pool api { account_id var.account_id name api-pool monitor cloudflare_load_balancer_monitor.http.id origins { name api-1 address 192.0.2.1 } origins { name api-2 address 192.0.2.2 } } # 負(fù)載均衡器綁定默認(rèn)池啟用基于地理位置的流量調(diào)度 resource cloudflare_load_balancer api { zone_id cloudflare_zone.example.id name api.example.com default_pool_ids [cloudflare_load_balancer_pool.api.id] steering_policy geo }steering_policy geo表示按訪問者地理位置就近分配。多區(qū)域場景如美東/西歐雙池 region_pools的完整寫法可參考 patterns.md 的「Multi-Region Load Balancing」用例。AccessZero Trust通過 Access 為內(nèi)部系統(tǒng)增加身份認(rèn)證層應(yīng)用Application 策略Policy 身份源Identity Provider三者配合# 身份源接入 GitHub OAuth resource cloudflare_access_identity_provider github { account_id var.account_id name GitHub type github config { client_id var.github_id client_secret var.github_secret } } # 受保護(hù)的應(yīng)用admin.example.com自托管 resource cloudflare_access_application admin { account_id var.account_id name Admin domain admin.example.com type self_hosted session_duration 24h allowed_idps [cloudflare_access_identity_provider.github.id] } # 訪問策略僅允許指定郵箱登錄 resource cloudflare_access_policy allow { account_id var.account_id application_id cloudflare_access_application.admin.id name Allow decision allow precedence 1 include { email [adminexample.com] } }要點說明allowed_idps限定該應(yīng)用可用的身份源session_duration控制會話有效期。precedence決定多條策略的匹配優(yōu)先級數(shù)值越小優(yōu)先級越高。decision支持allow/deny/non_identity等可組合出「先拒絕、后放行」的分層策略。cloudflare_access_*系列在 v5 中已更名為cloudflare_zero_trust_*遷移時需注意。實戰(zhàn)避坑與最佳實踐狀態(tài)漂移State Drift部分資源存在已知漂移問題可通過lifecycle.ignore_changes消除永久 diff資源漂移屬性處理方式cloudflare_pages_projectdeployment_configs.*ignore_changes [deployment_configs]cloudflare_workers_scriptsecrets 返回為 REDACTEDignore_changes [secret_text_binding]cloudflare_load_balanceradaptive_routing、random_steeringignore_changes [adaptive_routing, random_steering]cloudflare_workers_kv鍵含特殊字符 5.16.0升級到 5.16.0示例忽略 Secret 漂移resource cloudflare_workers_script api { account_id var.account_id name api-worker content file(worker.js) secret_text_binding { name API_KEY; text var.api_key } lifecycle { ignore_changes [secret_text_binding] } }v5 破壞性變更速查資源重命名v4v5cloudflare_recordcloudflare_dns_recordcloudflare_worker_scriptcloudflare_workers_script注意復(fù)數(shù)cloudflare_worker_*cloudflare_workers_*cloudflare_access_*cloudflare_zero_trust_*屬性變更v4v5適用資源zonenameZoneaccount_idaccount.id對象語法Zonekeykey_nameKVlocation_hintlocationR2狀態(tài)遷移命令terraform state mv cloudflare_record.example cloudflare_dns_record.example terraform state mv cloudflare_worker_script.api cloudflare_workers_script.api常見錯誤排查Error: couldnt find resource資源被 Terraform 之外刪除。用terraform import cloudflare_zone.example zone-id重新導(dǎo)入或terraform state rm cloudflare_zone.example從狀態(tài)移除。409 Conflict on worker deploymentTerraform 與 wrangler 同時部署同一 Worker須二選一。DNS record already exists已有記錄未導(dǎo)入狀態(tài)。在 Dashboard 找到 record ID 后用terraform import cloudflare_dns_record.example zone-id/record-id導(dǎo)入。Invalid provider configurationAPI Token 缺失、無效或權(quán)限不足檢查CLOUDFLARE_API_TOKEN環(huán)境變量與 Dashboard 中的 Token 權(quán)限。State locking errors并發(fā)運行或殘留鎖謹(jǐn)慎使用terraform force-unlock lock-id。Worker 腳本超過 10 MB腳本與依賴總大小受限使用代碼拆分、外部依賴或壓縮。工具鏈協(xié)作約定Terraform 負(fù)責(zé)Zone、DNS、安全規(guī)則、Access、負(fù)載均衡、Worker 部署CI/CD、KV/R2/D1 資源創(chuàng)建。Wrangler 負(fù)責(zé)本地開發(fā)wrangler dev、手動部署、D1 遷移、KV 批量操作、日志流wrangler tail。核心鐵律同一資源嚴(yán)禁同時被 Terraform 與 wrangler 管理否則會出現(xiàn)狀態(tài)沖突如 409。團(tuán)隊環(huán)境務(wù)必使用遠(yuǎn)程狀態(tài)后端S3、Terraform Cloud 等R2 作為 S3 兼容后端的完整 backend 配置見 patterns.md。更多參考Provider 配置與認(rèn)證Provider 版本、三種認(rèn)證方式、常用命令與 cf-terraforming 導(dǎo)入工具Data Sources 參考查詢已有 Zone、Worker、KV、IP 段等資源以及跨模塊引用與 output 用法架構(gòu)模式與多環(huán)境目錄結(jié)構(gòu)、多環(huán)境、R2 狀態(tài)后端、CI/CD 集成、完整用例故障排查與最佳實踐狀態(tài)漂移、v5 遷移、資源專屬坑點、限額明細(xì)【免費下載鏈接】skillsSkills Catalog for Codex項目地址: https://gitcode.com/GitHub_Trending/skills4/skills創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考