Cloudflare Terraform Provider 资源配置完全指南Zone、Workers、存储、Rulesets 与 Zero Trust 的 HCL 实战【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills本指南基于 Skills 仓库 cloudflare-deploy 技能包中的 Terraform 配置参考文档系统讲解使用官方cloudflare/cloudflareTerraform Provider 对 Cloudflare 全栈基础设施进行声明式管理的方法。你将掌握 Zone 与 DNS、Workers含渐进式发布与各类 Binding、KV/R2/D1/Queue 存储、Pages、RulesetsWAF/重定向/缓存、负载均衡与 Zero Trust Access 的完整 HCL 写法并了解 v5 版本的关键变化与避坑要点可直接用于生产环境的 IaC 落地。阅读前准备Provider 版本与认证在动手写资源之前先确认你使用的 Provider 版本。Cloudflare 官方 Terraform Provider 目前分两代版本状态说明5.x当前版本基于 OpenAPI 自动生成与 v4 相比存在破坏性变更4.x旧版手动维护已弃用关键提醒v5 对大量资源做了重命名例如cloudflare_record→cloudflare_dns_record、cloudflare_worker_*→cloudflare_workers_*注意是复数形式。详细迁移对照见 gotchas.md 的 v5 破坏性变更章节。基础 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 环境变量 }认证方式按推荐优先级排列API Token推荐api_token或CLOUDFLARE_API_TOKEN环境变量。在 Dashboard → My Profile → API Tokens 创建建议将权限范围限定到具体 Account/Zone 以降低泄露风险。Global API Key旧版api_keyapi_email或CLOUDFLARE_API_KEYCLOUDFLARE_EMAIL安全性较低优先使用 Token。User Service Keyuser_service_key用于 Origin CA 证书场景。常用命令速查terraform init # 初始化 Provider terraform plan # 预览变更 terraform apply # 应用变更 terraform destroy # 销毁资源 terraform import cloudflare_zone.example zone-id # 导入已有资源 terraform state list # 列出状态中的资源 terraform output # 查看输出 terraform fmt -recursive # 格式化代码 terraform validate # 校验配置Zone 与 DNS 配置Zone 是 Cloudflare 管理的域名实体配置时通过account对象语法指定所属账号type full表示完整托管即使用 Cloudflare 的 Name Server。# Zone 站点级设置 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 # 严格 SSL要求源站具备有效证书 always_use_https on # 强制 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表示开启橙色云代理流量经过 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 批量创建 MX 记录priority 对应 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批量创建是处理多 MX、多 TXT如 SPF/DKIM等重复型记录的常用手法可大幅减少样板代码。若需查询已有 Zone 而非新建可参考 api.md 中的cloudflare_zoneData Source 用法。Workers两种部署模式简单模式旧式仍可用使用cloudflare_workers_script一次性声明脚本内容、兼容日期与全部 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应来自变量严禁硬编码到源码。渐进式发布生产环境推荐生产环境推荐将「脚本定义」与「版本发布」分离通过cloudflare_worker_version指定脚本内容与 SHA256 摘要确保内容可校验再用cloudflare_workers_deployment控制版本流量比例# 定义 Worker不含内容 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 } } } # 将版本发布到 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」三段式结构支持金丝雀发布先发布percentage 10观察指标再逐步提升到 100是生产环境的推荐做法。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 侧的类型定义与完整示例可参见 bindings/configuration.md其中也提到所有类型 Binding 合计上限为 64 个。路由与定时触发器Worker 需要路由才能对外提供服务也支持 Cron 定时触发# 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 触发器每 5 分钟执行一次 resource cloudflare_worker_cron_trigger task { account_id var.account_id script_name cloudflare_workers_script.api.name schedules [*/5 * * * *] }Cron 调度表达式使用标准 Unix Cron 语法完整能力可参考 cron-triggers。存储资源KV、R2、D1 与 Queue# KV命名空间 预置一个键值对值为 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对象存储桶location 必须大写详见下方避坑 resource cloudflare_r2_bucket assets { account_id var.account_id name assets location WNAM } # D1关系型数据库schema 迁移需通过 wrangler 执行见下文 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 }注意细节KV 键名v5 中属性名为key_namev4 为key同时需要namespace_id关联命名空间。R2 location 大小写location必须使用大写字母如WNAM、ENAM、WEUR、EEUR、APAC小写会导致创建后再次 apply 失败见 gotchas.md。D1 只建库不建表Terraform 仅创建 D1 数据库资源本身表结构与数据迁移必须用 wrangler 完成wrangler d1 migrations apply db-name。上述资源创建后即可在上文 Worker Binding 中引用id/name/bucket_name/database_id形成完整的资源依赖链。Pages 项目Pages 适合前端静态站点与全栈应用Terraform 中通过cloudflare_pages_project管理项目、环境变量、构建配置与 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中可按环境注入 KV/D1 Binding 与环境变量build_config控制构建命令与产物目录source声明 GitHub 源码仓库实现推送即部署。已知问题cloudflare_pages_project的deployment_configs.*存在状态漂移Cloudflare API 会回填默认值建议在lifecycle中加入ignore_changes [deployment_configs]详见 gotchas.md 的状态漂移章节。RulesetsWAF、重定向与缓存规则Ruleset 是 Cloudflare 统一的规则引擎通过phase指定作用阶段# WAF 自定义规则拦截机器人流量但放行 Cloudflare 验证过的机器人 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) } } # 动态重定向/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 } } } } } # 缓存规则对静态资源开启边缘缓存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 } } } }关键点phase 决定规则类型http_request_firewall_customWAF 自定义规则、http_request_dynamic_redirect动态重定向、http_request_cache_settings缓存设置。expression使用 Cloudflare 规则表达式语言支持eq、matches等操作符与cf.*、http.request.*字段。WAF 规则表达式中cf.client.bot判断客户端是否为机器人cf.verified_bot识别通过验证的合法爬虫两者组合可实现精准拦截。WAF 更多玩法见 waf。负载均衡Load Balancers由「健康检查 Monitor 源站池 Pool 负载均衡器 LB」三层组成# 健康检查每 60 秒对 /health 发起 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 } } # 负载均衡器绑定默认池启用基于地理位置的流量调度 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表示按访问者地理位置就近分配。多区域场景如美东/西欧双池 region_pools的完整写法可参考 patterns.md 的「Multi-Region Load Balancing」用例。AccessZero Trust通过 Access 为内部系统增加身份认证层应用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 } } # 受保护的应用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限定该应用可用的身份源session_duration控制会话有效期。precedence决定多条策略的匹配优先级数值越小优先级越高。decision支持allow/deny/non_identity等可组合出「先拒绝、后放行」的分层策略。cloudflare_access_*系列在 v5 中已更名为cloudflare_zero_trust_*迁移时需注意。实战避坑与最佳实践状态漂移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注意复数cloudflare_worker_*cloudflare_workers_*cloudflare_access_*cloudflare_zero_trust_*属性变更v4v5适用资源zonenameZoneaccount_idaccount.id对象语法Zonekeykey_nameKVlocation_hintlocationR2状态迁移命令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重新导入或terraform state rm cloudflare_zone.example从状态移除。409 Conflict on worker deploymentTerraform 与 wrangler 同时部署同一 Worker须二选一。DNS record already exists已有记录未导入状态。在 Dashboard 找到 record ID 后用terraform import cloudflare_dns_record.example zone-id/record-id导入。Invalid provider configurationAPI Token 缺失、无效或权限不足检查CLOUDFLARE_API_TOKEN环境变量与 Dashboard 中的 Token 权限。State locking errors并发运行或残留锁谨慎使用terraform force-unlock lock-id。Worker 脚本超过 10 MB脚本与依赖总大小受限使用代码拆分、外部依赖或压缩。工具链协作约定Terraform 负责Zone、DNS、安全规则、Access、负载均衡、Worker 部署CI/CD、KV/R2/D1 资源创建。Wrangler 负责本地开发wrangler dev、手动部署、D1 迁移、KV 批量操作、日志流wrangler tail。核心铁律同一资源严禁同时被 Terraform 与 wrangler 管理否则会出现状态冲突如 409。团队环境务必使用远程状态后端S3、Terraform Cloud 等R2 作为 S3 兼容后端的完整 backend 配置见 patterns.md。更多参考Provider 配置与认证Provider 版本、三种认证方式、常用命令与 cf-terraforming 导入工具Data Sources 参考查询已有 Zone、Worker、KV、IP 段等资源以及跨模块引用与 output 用法架构模式与多环境目录结构、多环境、R2 状态后端、CI/CD 集成、完整用例故障排查与最佳实践状态漂移、v5 迁移、资源专属坑点、限额明细【免费下载链接】skillsSkills Catalog for Codex项目地址: https://gitcode.com/GitHub_Trending/skills4/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考