声明的敏感性,渲染为 Terraform 自身的 `sensitive`
关于某个值携带机密材料的声明只需编写一次,写在
Component 的 schema 上。当渲染目标自身提供相应的原语时,
该声明就渲染为这一原语。本示例是 Terraform 的情形:
构建会追加一个 override 文件,为声明的值所流入的模块输入添加 sensitive = true,
随后引擎会在原本会显示该值的任何地方将其遮蔽。
本示例有意保持精简,每个部分都可以检查:一个 component、三个模块输入,以及一个只标记其中 一个输入的渲染结果。
构建产出什么
在 dist/infra/terraform/ 下,是该边界的根配置:
aggrega.modules.tf—— 将store声明为一个module块,其source为./modules/store,其参数为该模块已解析的输入 变量,按确定的键顺序排列。每个 terraform 边界都会生成一个。
在 dist/infra/terraform/modules/store/ 下,是 store component 自己的文件:
- 逐字节复制的模块文件 ——
variables.tf和main.tf, 与模块作者编写的完全一致; aggrega_override.tf.json—— 敏感性标记,详见下文。它位于 模块自身文件旁边,因为 Terraform 会将 override 合并到 其所在目录的配置中;aggrega.provenance.tf—— 一个用#注释标识本次构建的文件(JSON 文件无法携带注释,因此来源信息放在单独的文件中)。
标记,以及它未标记的两个输入
example/storage/external-object-store 声明了三个 values 叶子。其中两个携带
公开标识符;一个携带凭据并声明了 sensitive: true:
values: bucket: { type: string, required: true } access_key_id: { type: string, required: true } secret_access_key: { type: string, required: true, sensitive: true }module 块绑定了全部三个模块输入:
module "store" { source = "./modules/store"
access_key_id = "AKIAEXAMPLE0001" bucket = "app-artifacts" secret_access_key = "example-placeholder-not-a-real-credential"}而追加的 override 只标记了其中一个:
{ "variable": { "secret_access_key": { "sensitive": true } }}Terraform 会将名为 override 或以 _override 结尾的文件合并到
同一目录的配置中,因此该文件为模块已有的
secret_access_key 声明添加该属性,并保留其类型、
描述和默认值不变,与模块编写的一致。所有 vendored 的字节都保持
原样。
override 未标记的那两个输入正是本示例的重点。
标记只跟随声明,别无其他 —— 不看变量的名称,
也不看其值的形态。access_key_id 是凭据标识符,而不是
凭据材料,因此它没有被声明为敏感,也不会被标记,
尽管它紧挨着机密,名称看起来也像机密。从那个叶子中删除
sensitive: true 并重新构建:override 文件将完全不会
生成。
实际观察效果
main.tf 将公开坐标和凭据放在同一资源的不同属性中,
因此一次 plan 就能同时显示两种情况。对边界的
根配置执行 plan —— 即包含 aggrega.modules.tf 的目录,
本部署的值就在这里:
cd dist/infra/terraformtofu init && tofu plan # or: terraform init && terraform plan # module.store.terraform_data.reference will be created + resource "terraform_data" "reference" { [… omitted: an id attribute, reported as known only after apply] + input = (sensitive value) [… omitted: an output attribute, reported as known only after apply] + triggers_replace = [ + "app-artifacts", + "AKIAEXAMPLE0001", ] }你自己的 plan 会在所示各行之间包含这两个属性。它们被 标记为省略而非缺失,因此你 无法解释的行就是真实的差异,而不是本页遗漏的内容。
凭据被遮蔽了;它旁边的两个公开值则没有。删除
aggrega_override.tf.json 并重新运行 plan,即可看到凭据被完整
打印出来 —— 这一差异就是标记所做的全部。标记位于
模块自身的 variable 块上,因此它随模块一起传递,并在
该模块被使用的任何地方生效。
**请在根目录运行,而不要在 modules/store/ 内运行。**component 的输入是
其 module 块的参数,而该块位于上一级,因此 component
自己的目录并不是一个可以按部署方式执行 plan 的配置。引擎
在那里的行为取决于模块自身的 variable 块,而两种
结果中只有一种会明显报错:
- 本模块声明的三个输入都没有
default,因此在modules/store/中执行 plan 会失败 —— 每个输入报一次No value for required variable, 每条都指明所在行,并给出-var/-var-file的解决办法。 - 而如果模块的输入全部带有默认值,在那里执行 plan 就会成功, 使用的是这些默认值,而不是根配置提供的值。 不会有任何警告。这正是需要了解的情形,因为一个看起来正确的 plan 描述的却是一个没人要求的配置。
标记不做什么
sensitive 控制的是显示。它阻止值在 plan 和 apply
输出中被打印,并阻止 Terraform 将该值放入本身未被
标记为敏感的 output 中。它不会加密该值,也不会改变
值的存储方式:apply 之后,该值以明文形式存在于 state 中。
无论标记如何,都应将 state 视为携带了凭据。
此外,只有当输入的标识来自声明时,标记才会作用于渲染后的输入。
本 Recipe 声明了 source: 而没有声明 valuesMapping:,因此
参数名就是 Component 所声明的值叶子路径,二者的对应
是精确的。声明了 valuesMapping: 的 Recipe 会在模板中自行创造输出名称,
而这些名称没有任何声明涉及,因此这样的 Recipe 会渲染相同的
值,但不带标记 —— override 文件会缺失,而不是做近似处理。
标记一个没有声明涉及的名称,会对一个公开输入作出不实的断言,
引擎自身的工具随后会隐藏一个从来不是机密的值。
为什么这里的凭据是模块输入
托管云数据库通常属于另一种情形:provider 会自行生成并 轮换主密码,因此模块不需要凭据输入,也就 没有需要标记的内容。本 bucket 在部署之外运维,因此 没有这样的 provider 可以委托 —— 部署持有访问密钥, 必须将其传入。这就是为什么本模块声明了凭据变量,而标准库中的 托管数据库模块没有。
模块声明该变量时没有使用 Terraform 的 sensitive 属性,
这正是本示例清晰易懂的原因:读者看到在渲染时应用的属性
来自 Component 的声明,而不是来自模块。
文件
aggregate.yaml—— 开发者意图:一个类型为example/storage/external-object-store的storecomponent,直接指定 bucket 名称, 并将访问密钥的两部分都暴露为带类型的parameters。release.yaml—— 为本环境提供这些参数,并设置 运维方的endpoint。此处的值只是占位符,不是任何真实服务的 凭据。manifest.yaml—— 将该 component 类型绑定到 Terraform Recipeterraform/external-object-store,后者从本地获取其模块。.aggrega-config.yaml— 指定目录实体从中解析的 hub 注册表。
凭据的两部分都是 parameters 而不是编写的值,因为它们
是由运维方提供、且随环境而不同的值。Release 不能
声明 values:,因此带类型的参数正是为此而设的接口:
开发者声明变化点,Release 来提供它。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example terraform-declared-sensitivity然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd terraform-declared-sensitivity构建
aggrega build --release release.yaml --auto-pull--auto-pull 会在构建期间写入全新克隆所缺少的 lockfile。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
仅使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `terraform-declared-sensitivity` 文件夹,请调用一次 `scaffold` 工具,将 `example` 设为 `terraform-declared-sensitivity`,且不设 `dir`:它会把示例写入新的 `terraform-declared-sensitivity` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `terraform-declared-sensitivity`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `terraform-declared-sensitivity/dist/` 下。