为什么瞬时资源更安全:agent-skills详解Terraform Ephemeral Resources设计原理
为什么瞬时资源更安全:agent-skills详解Terraform Ephemeral Resources设计原理
agent-skills 是 HashiCorp 官方开源的 Agent 技能集合,覆盖 Terraform 与 Packer 两大产品。本文基于仓库中的 provider-ephemeral-resources 技能,详解 Terraform Ephemeral Resources(瞬时资源) 的设计原理:为什么"绝不落盘"的瞬时资源,是把 Token、密码等敏感数据交给配置所需组件时最安全的答案。
一、什么是 Terraform 瞬时资源?
从 Terraform 1.10 开始,ephemeral 块产生一个永远不会持久化到 state 或 plan 的值。它只为一件事而存在:
把密钥——Token、生成的密码、短时效证书、解密后的值——交给配置中真正需要它的地方,同时不把它们写到磁盘上。
用一句话理解传统方案的痛点:普通 data 块或普通 resource 读出的敏感值会进入 state 文件,而 state 文件恰恰是最容易泄露的地方。瞬时资源的设计原则只有一条——值不持久化。仓库中的安全风格指南也明确建议:优先使用 ephemeral 资源与 write-only 属性处理敏感数据,详见 SECURITY.md。
二、瞬时资源的 Open / Renew / Close 生命周期
Terraform 在一次操作中最多调用 provider 的三个方法,这是理解其设计的关键:
| 方法 | 是否必需 | 作用 |
|---|---|---|
Open |
✅ 必需 | 在 plan 或 apply 需要时获取/创建值;没有 state 需要 refresh,也没有 import |
Renew |
可选 | 当墙上时钟越过 RenewAt 时调用,用于刷新 STS 风格等"运行中会过期"的凭证 |
Close |
可选 | Terraform 用完值时调用,在这里撤销租约或删除临时凭证 |
设计上有几个值得注意的细节:
Renew不能返回新值。它只能延展Open产生的那个值(例如重新租约同一凭证);如果续期后值本身会变,就应该在Open时直接返回更长效的值。- 用
resp.Private传递租约句柄(如lease_id),让Renew和Close都能拿到它——注意是放在私有数据里,而不是结果中。 RenewAt要留安全余量。Terraform 是惰性续期而不是精确定时器,实践中会在真实过期时间前 2 分钟设置续期点。
完整可编译的 Token 瞬时资源示例见 provider-ephemeral-resources/SKILL.md,展示了从 Metadata、Schema 到 Open/Renew/Close 的完整实现。
三、如何选择:数据源 vs 瞬时资源
不是所有读操作都该用瞬时资源。仓库给出了一张清晰的决策表 🎯:
| 场景 | 应该用什么 |
|---|---|
| 只读、非敏感数据查询 | 普通 data source |
| 值敏感,且只在 apply 时用到(如 provider 块里的数据库密码、write-only 属性里的 Token) | 瞬时资源 |
| 敏感值需要被下游受管资源存储为属性 | 普通资源/data source,尽量配合 write-only 属性 |
| 凭证在操作中途会过期(STS 风格 Token、短 TTL 租约) | 瞬时资源 + Renew |
判断标准可以浓缩为一句话:值真的不该持久化,才用瞬时资源;否则数据源更简单。
瞬时结果可用的位置也有明确边界:provider 配置、write-only 属性、provisioner 配置和其他瞬时上下文;不能用在普通属性里——因为普通属性会持久化到 state,会破坏整个安全设计。
四、最佳实践:瞬时资源 + Write-Only 属性
terraform-style-guide/SECURITY.md 给出处理敏感属性的三级优先级:
- 首选:原生 secrets manager 集成。如果资源本身支持把敏感值托管给 AWS Secrets Manager、Azure Key Vault 等(如 RDS 的
manage_master_user_password = true),直接用。 - 次选:瞬时资源 + write-only 属性。敏感值只进内存不落盘。以生成数据库密码写入 Vault 为例:
# 好的做法:密码不经过 state
ephemeral "random_password" "password" {
length = 16
special = true
}
resource "vault_kv_secret_v2" "example" {
mount = vault_mount.kvv2.path
name = "secret"
data_json_wo = jsonencode({
password = ephemeral.random_password.password.result
})
data_json_wo_version = 1
}
对比"坏做法":用普通 random_password 资源生成密码再写入,密码会完整落进 state 文件。
3. 最后手段:普通资源。仅在前两者都不可用、或 Terraform 版本低于 1.11.0 时才接受敏感数据写入 state。
五、设计规则:provider 开发者的安全红线
针对实现瞬时资源的 provider 开发者,技能文档列出了一组必须遵守的规则:
- 🚫 绝不记录值,绝不把值放进诊断信息——错误消息里出现 Token 就彻底破坏了非持久化的意义;
- 敏感属性仍要标记
Sensitive: true,保护瞬时值自身生命周期输出中的渲染; - 没有 plan modifier、没有 import、没有
id约定——没有 state,它们就都无从谈起; - 如果上游值无法撤销,就跳过
Close,而不是实现一个看起来会撤销的空操作。
测试方面也有专门的模式:由于瞬时值永远不进 state,标准 plan/state 断言无法直接检查它,官方推荐通过 echoprovider 把瞬时值"回显"到一个普通资源上再断言,并用 tfversion.SkipBelow(tfversion.Version1_10_0) 做版本门控。完整的直接集成测试与多步测试模式见 ephemeral.md。
六、如何安装 agent-skills 使用这些技能
agent-skills 仓库将 20 个技能组织在 plugins/terraform/skills/ 与 plugins/packer/skills/ 下,完整目录见 SKILLS.md。
按路径安装单个技能(支持 GitHub Copilot、Claude Code、Cursor 等):
npx skills add hashicorp/agent-skills/plugins/terraform/skills/provider-ephemeral-resources
安装整个 Terraform 产品插件包(Claude Code):
claude plugin marketplace add hashicorp/agent-skills
claude plugin install terraform@hashicorp
安装后,当你让 AI 助手为 provider 添加 Token、证书等瞬时资源时,provider-ephemeral-resources 技能会自动提供生命周期设计、注册方式、测试与文档的完整指导;terraform-style-guide 则会在生成 HCL 时优先选择瞬时资源与 write-only 属性的安全写法。
七、小结:检查清单
开发或使用瞬时资源前,对照这份清单快速自检:
- [ ] 值确实不应持久化(否则用数据源更简单)
- [ ]
Open已实现;Renew/Close仅在 API 支持时实现 - [ ] 敏感属性
Sensitive: true;值绝不进入日志或诊断信息 - [ ] 租约句柄通过
Private传递 - [ ]
RenewAt为过期凭证预留了安全余量 - [ ] 文档中说明了值的生命周期、续期与撤销行为
核心结论:瞬时资源的安全性不来自更复杂的加密,而来自更简单的一条设计——值在内存中短暂存在、用后即弃,state 与 plan 中永远看不到它。这正是 agent-skills 把 provider-ephemeral-resources 作为独立技能沉淀下来的原因:把"正确且安全"的做法固化为 AI 助手可直接执行的标准。