跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

声明的敏感性,渲染为 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 的目录, 本部署的值就在这里:

Terminal window
cd dist/infra/terraform
tofu 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 的 store component,直接指定 bucket 名称, 并将访问密钥的两部分都暴露为带类型的 parameters。
  • release.yaml —— 为本环境提供这些参数,并设置 运维方的 endpoint。此处的值只是占位符,不是任何真实服务的 凭据。
  • manifest.yaml —— 将该 component 类型绑定到 Terraform Recipe terraform/external-object-store,后者从本地获取其模块。
  • .aggrega-config.yaml — 指定目录实体从中解析的 hub 注册表。

凭据的两部分都是 parameters 而不是编写的值,因为它们 是由运维方提供、且随环境而不同的值。Release 不能 声明 values:,因此带类型的参数正是为此而设的接口: 开发者声明变化点,Release 来提供它。

生成示例

你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example terraform-declared-sensitivity

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd terraform-declared-sensitivity

构建

Terminal window
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/` 下。