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

Terraform Provider

terraform provider 将 Aggrega Recipes 渲染为 Terraform 配置。它只输出配置,从不运行 Terraform:Aggrega 构建是一次预先(ahead-of-time)编译,因此无法解析那些只有在 terraform apply 之后才存在的资源 ID、IP 地址和输出。Terraform 的 ${ ... } 插值会原样透传,作为确定性的指针字符串,由 Terraform 运行时稍后解析。该 provider 离线且封闭:它从不访问网络,也从不调用 terraform 或 tofu。

边界的布局方式

terraform provider 组合一个边界,而不是将其中的 component 并排输出。它渲染的每个边界都会得到一个根配置 aggrega.modules.tf,其中将在此渲染的每个 component 声明为一个 module 块,其 source 是该 component 自己在 modules/ 下的子目录:

module "cache" {
source = "./modules/cache"
}
module "db" {
source = "./modules/db"
allocated_storage = 100
db_name = "appdb"
engine_version = "11.4"
}

每个 component 自己的文件(vendored 模块或编写的配置主体,以及来源标记)位于其块所指向的子目录中。这是 Terraform 标准的“根组合子模块”结构,其约定是嵌套模块位于 modules/ 子目录下;无论 terraform 边界包含一个还是多个 component,都采用这种布局。附加到 component 或边界上的 Feature 会在同一根配置中声明为独立的 module 块,参见附加的 Feature 的输出落在何处。

这种结构起承重作用,而非装饰,原因有二。

**Terraform 依赖图以配置为单位。**输出到不同目录的 Components 是彼此无关的独立依赖图:引用和 depends_on 都无法从一个跨到另一个,也没有任何一次 terraform plan 能同时看到两者。由一个根配置将每个组件组合为子模块,可以把整个边界放进一个依赖图和一次计划中。

component 的文件按其自己的目录寻址。 同一边界中的两个 component 可能 vendor 写入同名文件(main.tf、variables.tf)的模块,每组文件都位于各自 component 的目录下,而不会争用同一路径。

provider 在何处配置

provider 的配置(即 provider 块)写在根中,绝不写在 component 的模块内。Terraform 文档指出,供其他模块调用的模块不得包含 provider 块,被调用的模块会继承根中它所使用的每个 provider 的默认配置。自带 provider 块的模块无法通过 depends_on、count 或 for_each 调用;而当同一根中另一个 component 具有更早的 syncWave 时,此 provider 会在该 component 的 module 块上写入 depends_on,如下文“部署顺序”所述。此时 Terraform 会在加载阶段、执行任何计划之前拒绝整个配置。

因此,若 Recipe 的 provider 需要配置,应将该配置写为 spec.boundary.artifacts 下的文件。每个这样的文件只在 aggrega.modules.tf 旁写入一次,Terraform 会将其与根配置一起读取,而 component 的模块只保留声明该 provider 来源和版本的 required_providers:

infra/terraform/
aggrega.modules.tf
provider-azurerm.tf
modules/
gateway/main.tf

同一根配置中以相同字节声明同一文件的 Components 共享这一份副本;同名但字节不同则会终止构建。这些模块的资源记录在这一份配置之下,因此 Terraform 销毁它们时用的也是这份配置。如果某个 Release 移除了最后一个声明该文件的组件,该文件也随之被移除,此后 Terraform 会拒绝为销毁这些模块所创建的资源制定计划,并要求提供一个配置该 provider 的 provider 块。请在移除最后一个此类组件之前先销毁这些资源。

component 的输入在何处提供

component 的输入是根配置中其 module 块的参数,这也是写入输入的唯一位置。当由编译器提供模块输入时(即通过 source: vendor 模块的 Recipe),块带有参数。当 Recipe 自行编写配置主体并将其值解析到该主体中时,块不带参数,因为已没有需要编译器传递的内容。

模块参数是 Terraform 会求值的位置,因此值放在这里。Recipe 提供的 ${ ... } 指针在此处解析,而不是作为字面字符串到达模块。它依据根配置解析:引用指向该配置所声明的内容,即其某个 module 块,形式为 module.<name>.<output>;引用任何未声明的内容都会在计划时明确报错,并指出缺失的引用对象。

因此,component 自己的目录不是一个可以按部署状态进行计划的配置。 其输入在上一级的根中声明,所以进入 modules/<component> 并在其中运行引擎时,计划的是别的东西,具体是以下两种情况中的哪一种,取决于模块自身的 variable 块:

  • 若至少有一个输入未声明 default,计划会明确失败:报出 No value for required variable,指出每个未设置的变量及其所在行,并给出 Terraform 自身的 -var / -var-file 解决办法。
  • 若每个输入都带有 default,计划会成功,但依据的是模块的默认值,而不是根配置提供的值。此时不会有任何警告,所以这是需要了解的情况:一个看似正确的计划,描述的却是没人要求的配置。

应改为对边界自己的输出目录进行计划,即包含 aggrega.modules.tf、紧位于 modules/ 之上的目录。部署的值就在那里,也只有在那里,单次计划才能看到整个边界。

使用另一个 component 发布的值

通过 uses 边连接到另一个 component 的 component,会经由自己的 .context.inject 管道(或经由 .context.uses.<alias>.provides.<name>)读取该 component 发布的值。它读取到的是编译器不加解释地传递的字符串,而该字符串的落点是Terraform 在 Recipe 写入它的作用域中求值的文本。terraform 边界有两个这样的作用域,其中只有一个声明了跨 component 引用所需的模块调用:

  • 根配置将每个贡献者声明为 module 块,因此 module.<name>.<output> 可在此解析;
  • component 自己的目录完全不声明模块调用,因此 module.<name>.<output> 在那里不指向任何东西,无论 <name> 是什么。换成正确的名称也无济于事,因为缺少的是声明,而不是拼写。

因此,决定所使用的引用能否解析的,是使用方 Recipe 的输入类型,而不是被使用的值。

将使用方 Recipe 编写为 source: Recipe。 其 valuesMapping: 会成为根配置中它自己的 module 块的参数,这是唯一既会被求值、又处于其相邻模块已声明的作用域中的位置。

一对完整示例

生产方发布一个指向其自身模块调用的地址,这正是其使用方作用域所声明的形式。.context.instance_id 位于 provides 求值的可用范围内,对于部署的 Aggregate 所声明的 component,它就是该 component 的 module 块所带的名称:

# Recipe — the producer. Its vendored module declares `output "endpoint"`.
spec:
capability: terraform
implements: example/storage/object-store:1.0.0
source: ./module
valuesMapping: |
bucket: "{{ .values.bucket }}"
provides:
endpoint: "${module.{{ .context.instance_id }}.endpoint}"

使用方 vendor 一个声明了输入的模块,并将注入的值映射到该输入:

# Recipe — the consumer. Its vendored module declares `variable "store_endpoint"`.
spec:
capability: terraform
implements: example/compute/reporting-api:1.0.0
source: ./module
valuesMapping: |
store_endpoint: "{{ .context.inject.env.STORE_ENDPOINT }}"

Aggregate 将它们连接起来,并指明该边所携带的已发布键:

spec:
components:
store:
type: example/storage/object-store
values:
bucket: app-artifacts
api:
type: example/compute/reporting-api
uses:
store:
store:
target: store
inject:
env:
- in: STORE_ENDPOINT
from: endpoint

构建输出一个根配置,其中引用及其引用对象在一起声明:

module "api" {
source = "./modules/api"
store_endpoint = "${module.store.endpoint}"
}
module "store" {
source = "./modules/store"
bucket = "app-artifacts"
}

Terraform 能解析 module.store.endpoint,因为同一配置声明了 module "store",该值作为普通输入到达使用方的模块。

aws-rds-and-ecs-service 示例使用标准库 Recipes 构建了这样一对组件:一个由已发布的 RDS 模块预配的 PostgreSQL 数据库,以及一个在 Amazon ECS 上运行的服务器,后者的 environment 参数在声明了 module "db" 的根配置中携带 ${module.db.db_instance_address}。

三种出错方式及各自的表现

自行编写主体的 Recipe 无法消费跨组件引用。 artifacts: Recipe 会将其值解析进它所编写的主体,而该主体输出到组件自己的目录中。于是引用位于一个不声明任何模块调用的作用域中:

Error: Reference to undeclared module
on modules/api/main.tf line 11, in output "seen":
11: value = "${module.store.endpoint}"
No module call named "store" is declared in module.api.

没有任何拼写能修复这一点,因为嵌套模块的表达式根本无法引用同级模块——嵌套模块只能以输入的形式接收相邻模块的值,而这正是 source 方式已经提供的 module 块参数。消费其他组件所发布值的组件应编写为 source: Recipe。

指向生产者自身模块内部某项内容的地址是针对根配置解析的,而不是针对该模块。 拼写为 aws_db_instance.this.endpoint 的 provides 条目引用的是生产者模块声明的资源;写成插值后,它在消费者参数所在的位置求值,也就是根配置:

Error: Reference to undeclared resource
on aggrega.modules.tf line 19, in module "api":
19: store_endpoint = "${aws_db_instance.this.endpoint}"
There is no managed resource "aws_db_instance" "this" definition in the root module.

应发布 ${module.<...>.<output>},并为该值给模块添加一个 output 块,而不是直接访问其资源。

不带插值的 provides 条目会作为文本传递。 这是唯一不会失败的情况:编译器传递字符串,无法区分指针和字面量,因此不带 ${ ... } 的 aws_db_instance.this.endpoint 会渲染为带引号的字符串,构建成功,引擎校验通过,而消费者收到的是字符 aws_db_instance.this.endpoint。只要该值意在作为引用,就应写上 ${ ... } 包裹——正是它将字符串标记为需要 Terraform 求值的内容。

依赖它之前值得了解的一个限制

.context.instance_id 表示组件的标识,而 module 块的名称派生自组件文件所在的目录。对于部署自身的 Aggregate 所声明的组件,两者是同一个名称。 对于从另一个 Aggregate 组合进来的组件则不然:组合后的标识和模块名称以不同方式写入各自的字母表,此时引用会在根配置处明确报错,而不是静默失败:

Error: Reference to undeclared module
on aggrega.modules.tf line 25, in module "api":
25: store_endpoint = "${module.nested-zdinner.endpoint}"
No module call named "nested-zdinner" is declared in the root module.

若某个生产者的地址需要由另一个组件解析,应将该生产者声明在部署自身的 Aggregate 中,与消费它的组件放在一起。

附加的 Feature 的输出落在何处

渲染自身配置的 Feature 附加项会获得一个独立的模块,与其旁边的组件声明在同一个根配置中。正是这一点使其配置成为部署的一部分:Terraform 只加载直接位于某目录中的文件,并将嵌套目录视为一个必须显式调用的完全独立的模块,因此附加项的文件之所以被读取,是因为根配置声明了一个指向其所在目录的块。

附加项的模块目录位于组件目录的旁边,处于 modules/ 下一级,并以标识它的两项内容命名——承载它的组件以及附加时所用的名称,以 -- 连接。因此,对于带有名为 aux 的附加项的组件 api,根配置声明两个模块:

module "api--aux" {
source = "./modules/api--aux"
}
module "api" {
source = "./modules/api"
}

附加在边界而非组件上的 Feature 没有可命名的宿主组件,因此其目录仅以自身名称命名:在包含组件 api 的边界上名为 aux 的附加项,会在 ./modules/api 旁边生成 ./modules/aux。

为什么放在旁边而不是内部。 Terraform 会将模块目录中的所有顶层文件合并到一个命名空间中——output、variable、resource 和 locals 都是如此——因此共享同一目录的两个贡献者,无论文件名是什么,都会在双方都声明的任何名称上冲突。每个贡献者各用一个目录,才能将它们隔开。放在旁边而非内部,也正是 Terraform 自身对嵌套模块的指导所要求的:嵌套模块应由调用方组合,而不是彼此直接调用,形成层层嵌套的模块树。

连接按坐标分别转义。 两个坐标在连接之前各自写入目录字母表,因此本身包含 -- 的坐标不会与连接符混淆:宿主名为 a--b、附加项为 c,与宿主为 a、附加项为 b--c 是可以区分的。大小写 ASCII 字母、数字、句点和下划线按原样保留;你写下的连字符只要其后的字符属于上述字符之一就会保留;其他字符都会被转义。chart 目标的子目录也由同一规则和同一字母表生成,因此无论由这两种目标中的哪一种渲染,同一附加项的目录拼写都相同。

块的名称派生自其 source 指向的目录,其中不符合 Terraform 模块名称语法的每个字符都会替换为下划线。这种映射不是一一对应的,因此当两个贡献者会得到同一个模块名称时,构建会中止并指出两者,而不是输出一份 Terraform 会拒绝的配置。

附加项作为独立模块,带来三点结果。

其输入来自它自己的映射。 若附加项的 FeatureRecipe 引用一个模块并声明了 valuesMapping,该映射产生的值会写为其自身 module 块的参数,与组件的 source 模块接收值的方式相同。未声明 valuesMapping 的 FeatureRecipe 不向其模块传递任何参数:模块中声明了 default 的变量取该默认值,而未声明默认值的变量保持未设置,因此 Terraform 会拒绝该计划。

其资源位于边界唯一的依赖图中。 引用或 depends_on 可以在附加项与其所附加的组件之间生效,并且一次 terraform plan 能同时看到两者——这与根组合子模块的结构给组件带来的特性相同,原因也相同。

其顶层名称属于它自己。 由于上文所述的命名空间合并是按目录进行的,位于独立目录中的贡献者声明其 output、variable、resource 和 locals 名称时不会与相邻贡献者冲突——因此附加项可以复用其宿主已声明的名称,双方都无需知道对方如何命名。

请注意此目标不要求什么,因为 chart 目标的约束不同,而共享的布局可能被理解为暗示了更多内容:嵌套在另一个贡献者目录中的模块在这里仍然可以访问,因为根配置从构建所组合的位置读取每个贡献者的 source,而不是根据标识符重新构造它。此目标拒绝的是两个贡献者共享同一目录。chart 目标则直接拒绝嵌套位置,因为它只在下一级发现子 chart,不会更深。

支持的输入类型

terraform provider 接受三种 Recipe 输入类型中的两种:

  • Artifacts 模式。 Recipe 以模板化主体编写 Terraform 配置;provider 对 Aggrega 模板求值,并输出结果而不改写它。HCL(main.tf)是便捷的默认格式,Terraform JSON(.tf.json)同样被接受。构建来源信息以一块 Terraform 注释的形式写在 HCL 主体的顶部;对于 JSON 主体(它没有注释语法),来源信息写入一个配套文件 aggrega.provenance.tf,而不是内联。
  • Sourced 模式。 Recipe 通过 source: 引用一个 Terraform 模块。模块的文件被原样 vendor 到该 component 的目录中,而 Recipe 的 valuesMapping: 成为边界根配置中该 component 的 module 块的参数。模块主体完全按编写时的样子保留,不会向其中写入任何内容;值只在根配置中声明一次,由 Terraform 在那里求值。当节点声明的 values 叶子直接成为模块的输入时(即没有 valuesMapping: 的 source: Recipe),携带作者声明为敏感的内容的输入还会获得一个生成的覆盖文件,其中带有 Terraform 自身的敏感性属性;valuesMapping: 模板会自行决定输出名称,因此这种情况不带标记,构建会以一条提示信息报告它。两者均在声明为敏感的模块输入中说明。

valuesMapping: 中的 null 就是一个 null 参数。 映射设为 null 的键在模块块中写作 <name> = null,引擎会将模块变量的值设为 null,覆盖其 default;除非该变量声明了 nullable = false,此时使用其 default。若要让输入取模块的默认值,请在映射中省略该键。

不提供 synthesized 输入类型。从平台 Workload 类型到任意 Terraform 资源之间不存在忠实且与能力无关的映射,因此针对 terraform provider 声明 workload: 的 Recipe 会直接报错,而不是生成一个臆造的转换。

声明了 omits: 的 Recipe 会被拒绝。 omits: 键用于将某个源渲染出的文档排除在构建之外,而此 provider 在构建时不会从 sourced 模块渲染任何内容:它原样 vendor 模块的文件,由 Terraform 在 plan 和 apply 配置时对其求值。既然没有渲染任何内容,也就没有可排除的内容,因此此 provider 不声明支持该键,声明了它的 Recipe 或 FeatureRecipe 会在 vendor 任何内容之前被拒绝——参见 The provider does not support omits(该 provider 不支持 omits)。对于放在 Recipe 旁边的模块,可以改为在那里的 .aggregaignore 中添加一行来排除模块的某个文件,从下一次固定该 Recipe 时起生效。

引用 registry 发布的模块

模块 registry 将模块的每个版本发布为该模块自身 git 仓库的一个标签,当被请求下载某个版本时,它返回的是一个固定到该标签所指提交的 git 源。因此,Recipe 使用 git-repository 源类型,从该仓库的该标签引用已发布的模块:

spec:
capability: terraform
implements: example/storage/database:1.0.0
source:
kind: git-repository
url: https://github.com/terraform-aws-modules/terraform-aws-rds.git
ref: v7.2.2
valuesMapping: |
identifier: "{{ .values.identifier }}"
provides:
host: "${module.{{ .context.instance_id }}.db_instance_address}"
port: "${module.{{ .context.instance_id }}.db_instance_port}"

ref: 是与仓库命名完全一致的发布标签。valuesMapping: 按模块 variable 块声明的名称提供模块的输入(Terraform 要求每个未声明 default 的输入都必须有值),这些输入会成为根配置中此 component 的 module 块的参数,与任何 sourced 模块相同。

固定的是什么。 aggrega pin 和 pull 会将标签解析为它所指的提交,并在该提交处对仓库归档。随后 Release 的锁文件记录该提交作为源的固定版本、标签作为你编写的引用,以及归档的摘要。之后的每次构建都从缓存读取归档,并在 vendor 任何内容之前根据该摘要进行校验,因此无需网络;缓存的归档字节不再匹配时,构建会中止。标签是仓库可以移到另一个提交的名称;之后的 pull 若发现你的标签解析到别处,会中止而不是采用新提交,aggrega pull --upgrade 则会有意采用它。这比 Terraform 自身的依赖锁文件更严格:后者只记录配置选择的 provider,完全不记录模块,因此以 git 源加标签方式写入配置的模块,其固定程度仅取决于该标签。而在这里,模块的提交及其字节的摘要固定在锁文件中,字节被 vendor 到输出中,根配置通过本地路径调用它们,因此引擎加载模块本身时无需获取任何内容——被 vendor 的模块通过 registry 或远程源调用的模块仍会被获取,构建会报告每个这样的调用,如引擎初始化时获取的模块调用所述。

vendor 的是什么。 固定提交处的整个仓库(除其 .git/ 目录外)被逐字节放入 modules/ 下该 component 自己的目录——包括模块自身的配置文件和子模块,以及仓库携带的其他任何内容:其 examples/ 和 wrappers/ 目录、文档、CI 配置,以及所有测试夹具(包括二进制文件)。引擎只读取模块调用的内容:当根配置调用该 component 的目录时,引擎加载直接位于其中的配置文件,以及从那里经由本地 source 到达的每个目录中的配置文件。因此,调用其他 registry 模块的示例目录会被 vendor 但永远不会被加载,它调用的任何内容也不会被获取。

缩小 vendor 的范围。 获取的源就是它被获取时的归档,因此缩小范围的唯一方法是 module_subdir:,它使仓库中的一个目录成为制品。这只在你需要的模块位于子目录时才有用:位于仓库根目录且调用自身 ./modules/* 的模块需要整棵目录树。仓库携带的 .terraformignore 和 Recipe 旁边的 .aggregaignore 都不会改变获取的源所 vendor 的内容——两者只作用于放在 Recipe 旁边的模块,对于从仓库获取的模块都不会被读取。

读取模块发布的内容。 模块发布的值是它的某个 output 块,使用方以 ${module.<name>.<output>} 读取它,其中 <name> 是生产方的模块块——这就是上面的生产方发布 ${module.{{ .context.instance_id }}.<output>} 的原因。引擎在校验根配置时根据模块自身的 output 块解析该引用,因此模块未声明的输出名称会在那里被拒绝,并指出该名称:

Error: Unsupported attribute
on aggrega.modules.tf line 9, in module "api":
9: db_host = "${module.db.db_instance_addresz}"
This object does not have an attribute named "db_instance_addresz".

构建不读取模块的任何 variable 或 output 块,不向模块写入任何内容,也不向其添加任何 provider 配置,因此拼错的输出名称由引擎而非构建捕获。使用方的情况参见使用另一个 component 发布的值。

原样输出与 vendoring

terraform provider 不会转译、重新格式化或改写 Terraform 主体。编写的 HCL 或 .tf.json 主体完全按其模板求值的结果输出,HCL 主体以来源注释开头,sourced 模块则逐文件 vendor。正是这一点使 terraform 输出具有确定性和可复现性:给定相同的输入,渲染出的配置在多次运行之间逐字节相同,vendor 的模块往返后保持不变。由于 provider 从不解析运行时状态,所有依赖运行时的内容都保留为插值字符串,由 Terraform 在 apply 时绑定。

平台注解

terraform provider 不读取任何 aggrega.ai/ 注解。vendored 模块、Recipe 的制品文件以及 provider 写入的根配置都没有可放置命名空间、镜像仓库前缀、拉取密钥或服务账号的位置,因此为其中任何一项设置的值都不会改变渲染出的配置;需要此类值的模块会通过组件的 values,将其作为自身的一个输入来接收。

该 provider 在其 Plugin 实体中通过 readsNoWellKnownAnnotations: true 声明这一点(参见 Plugin 实体),因此构建会针对每个经由它到达某次渲染的 aggrega.ai/ 注解发出警告——每个键、每次渲染各一次,并列出该渲染声明的输入类型:

warning: node "db" (provider "terraform"): target "terraform" does not support annotation aggrega.ai/namespace on sourced input and ignored it

该值仍会原封不动地通过构建,构建也不会中止:边界注解会级联到其下的每个组件,而组件通过不同目标渲染的边界是正常情况,并非错误。该警告属于 unsupported-field 类别,可用该类别的标志静默。

声明为敏感的模块输入

Terraform 是标准库中唯一一个具有原生逐值敏感性原语的目标,因此作者声明为敏感的数据可以用 Terraform 自身的方式渲染,而不只是记录在 Aggrega 的方式中。

当一个已 vendor 的模块的输入携带作者声明为敏感的内容时,provider 会在该模块旁再追加一个文件 aggrega_override.tf.json,为该输入声明 sensitive = true:

{
"variable": {
"db_password": {
"sensitive": true
}
}
}

Terraform 会把文件名恰为 override 或以 _override 结尾的配置文件合并到同一目录的配置中,因此模块自身的 variable 块获得该属性,而每一个已 vendor 的字节都保持与编写时完全一致。该输入声明的类型、默认值和描述均不受影响——override 只携带敏感性属性,别无其他。未标记的节点不会生成此类文件。

**这一限制是有意为之,而非文件格式所强加:**override 中没有任何机制会拒绝第二个属性,而如果你想在不修改已 vendor 模块字节的情况下向其传入一个值,variable 块的 default 是最容易想到的位置——但这个值不会送达。在该文件所用的 JSON 配置语法中,default 不是 Terraform 会求值的位置,因此写在那里、携带 ${ ... } 指针的值会以指针的字面字符到达模块,而 plan 会成功且不给出任何提示。同样的指针写入原生 HCL 的 default 中会被直接拒绝,这说明这种静默源于该语法,而非 override 文件本身。因此 override 只携带 sensitive:它的含义不依赖于是否被求值。

哪个输入被标记取决于声明,而绝不取决于名称。 provider 读取编译计算出的标记,自身不检查任何内容:它不识别 password、secret 或 token,也不读取模块的文本来猜测。一个名为 db_password 但其值不携带声明的模块输入会以未标记状态输出,而一个名为 region 的已声明输入会被标记。

标记只在能够从声明中还原输入身份的地方传递。 一个用 source: vendor 模块、并让节点声明的 values 叶子直接成为模块输入的 Recipe,会让每个输入使用与作者声明相同的名称,因此关联是精确的——附加到以同样方式 vendor 模块的 component 上的 Feature,其 FeatureRecipe 在该 Feature 声明的叶子上也是如此。通过 valuesMapping: 模板重塑这些值的 Recipe 或此类 FeatureRecipe 会自行生成输出名称,而没有任何声明命名它们——因此标记会缺失而非近似处理,构建会为每个已声明叶子给出一条提示,指明该叶子及该映射所属的实体(附加到 boundary 的 Feature 不针对任何 values 渲染,因此没有可标记的内容,也不会产生提示);参见 A declared-sensitive value reaches the target through a values mapping(声明为敏感的值通过 values 映射到达目标)。缺失是有意为之:猜测哪个重塑后的输入携带了声明的数据,可能会把公开输入标记为机密,而 Terraform 随后会在 plan 输出中隐藏一个从未敏感的值。

示例 terraform-declared-sensitivity 端到端地构建了这一过程,篇幅小到可以完整阅读:一个 component 声明了 3 个 values 叶子,其中 2 个携带公开标识符,1 个携带凭据。其渲染输出显示 module 块的参数携带全部 3 个模块输入,而 override 只指明已声明的那一个,因此规则的两个方面在同一次构建中都清晰可见——包括位于机密旁边的凭据标识符保持未标记。删除这一个声明并重新构建,将完全不会输出 override 文件。

Terraform 的 sensitive 保证什么、不保证什么

Aggrega 承诺的正是 Terraform 自身属性所提供的,不多也不少。

它限制显示。 敏感值在 plan 输出中显示为 (sensitive value),在 apply 输出中显示为 <sensitive>。标记会在表达式中传播,因此由敏感输入派生的值同样是敏感的,并且 Terraform 拒绝从自身未标记为敏感的根 output 中导出这样的值——这是一个显式的错误,而非静默的泄露。

它不改变存储,也不是加密。 Terraform 在 state 中以明文记录敏感值。把 sensitive = true 理解为 state 可以安全提交或共享的承诺,是唯一需要避免的误读:保护 state 仍取决于 state 后端的配置方式,与完全不携带标记的模块完全相同。该属性也不限制谁可以读取该值,不影响 provider 传输的内容,也不会以任何其他方式改变渲染出的配置。

因此,标记让声明为敏感的输入在有人阅读 plan 时更不容易被意外泄露。它并不能让可部署产物变得可以安全发布。关键字以及声明在所有目标上的作用,参见将叶子声明为敏感。

结构性输入校验

terraform provider 在渲染之前校验所引用模块的结构。它解析模块的 HCL 和 .tf.json 文件并报告解析错误,以明确的消息中止构建,消息中会指出出错的节点和 provider。解析只检查形状,不检查语义:它不解析 provider、不求值表达式,也不联系任何 registry。校验是封闭的:它使用编译进 provider 的自包含 HCL 解析器,不需要 terraform 二进制文件,也不访问网络。格式错误的模块会在编写边界处被发现,而不会在之后运行 terraform 时以令人困惑的错误出现。

引擎在初始化时获取的模块调用

同一次读取还会以一条不拒绝任何内容的警告,报告每个其来源会在配置初始化时由 Terraform 下载的 module 块。vendored 模块的提交和归档摘要在锁文件中是固定的,但如果其中某个 module 块的 source 是 registry 地址、git、Mercurial 或 HTTP 归档 URL、S3 或 GCS 存储桶,或者绝对路径,那么它指向的是引擎在初始化时获取的模块,版本取决于引擎届时选择的版本;而 Terraform 自身的依赖锁文件只记录 provider,因此没有任何东西固定该模块。跳出 vendored 模块之外的本地 source 也会被报告,因为它指向构建未 vendor 的文件。每条发现都会给出节点和 provider,然后是该块、其所在的文件和行,以及原样写出的来源:

warning: node "app" (provider "terraform"): module "vpc" (main.tf, line 2) has the source "terraform-aws-modules/vpc/aws", which Terraform downloads when the configuration is initialised, at whatever version it then selects, so no commit or digest this build records covers that module

读取哪些内容。 即模块被调用时引擎加载的文件:直接位于模块自身目录中的配置文件,然后是从该目录出发、经由本地 source(以 ./ 或 ../ 开头,或其反斜杠写法)到达的每个目录中的配置文件,逐个目录追踪,每个只读取一次。没有被任何调用指向的目录不会被读取,因此模块的 examples/ 或 tests/ 目录中的调用不会被报告:模块被调用时引擎从不加载它们,它们调用的内容也不会被获取。上文的解析检查仍会解析每个 vendored 配置文件。Recipe 的编写主体在渲染时也以同样方式读取,从主体写入的目录开始,因此编写主体中以 registry 来源写出的 module 块同样会被报告。spec.boundary.artifacts 下的文件由编译器自身求值并写出,不交给任何 provider,因此其中写出的 module 块不会被读取,也不会产生警告。

不读取哪些内容。 只读取 source 所写的内容。构建不会读取调用所指向的模块,不判断该模块做什么,也不决定该调用是否可接受。对于引擎会求值而非按原样读取的 source(即携带插值或引用的来源),按其开头文本判断:以地址开头的会按原样报告,而以本地前缀或插值本身开头的既不报告也不追踪,因为它指向何处并不在文本中。位于 required_providers 中的 source 指向的是 provider 而非模块,不属于模块调用。

为何报告而非拒绝。 调用其他模块的模块是合法输入:Terraform 会获取被调用的模块,配置可以正常工作。作者放弃的是构建对被调用模块的版本固定,这是值得知道的事实,而非需要修复的错误;该获取是否可接受由作者判断。必须保持完全固定的配置只 vendor 不进行此类调用的模块。该警告、其类别代码及其还会出现在哪些地方,见 Warnings and Linter Output(警告与 Linter 输出)。

FeatureRecipe 补丁边界

渲染后的 FeatureRecipe pipeline 步骤只修补 provider 渲染为结构化树的输出。对 terraform 而言,这意味着:

  • 以 JSON 编写的 Terraform 可以修补。 .tf.json 模块是结构化文档,因此 pipeline 步骤的 JSONPatch 会就地编辑所寻址的值,其余每个字节(顺序、格式、周围的键)均保持不变。
  • 原生 HCL 是不透明的。 原生 HCL 主体(main.tf)不是结构化的补丁目标。针对不透明主体的补丁会以诊断信息中止构建,而不会去修改它无法按结构寻址的文本;针对 HCL 主体编写 pipeline 步骤属于设计错误,会以明确的中止暴露出来,而不是静默地不执行任何操作。
  • 来源模块的输入根本不是补丁目标。 它们是该组件 module 块的参数,而该块位于根配置中:它是原生 HCL,因此是不透明的,并且是整个边界的产物,而不属于任何单个节点。pipeline 步骤修补的是节点自身的渲染输出,因此不存在可以寻址这些输入的位置。

因此,需要让 Terraform 主体可被 pipeline 修补的作者应将其编写为 .tf.json。关于各 provider 通用的补丁目标边界,请参阅 FeatureRecipe。

部署顺序

Release 边界的 syncWave: 值决定该边界所汇入的根配置中各 module 块的顺序。边界中的每个组件都继承该边界的 wave;当多个边界解析到同一个输出目录,从而其组件被组合进同一个根配置时,该根配置包含不止一个 wave,provider 会以 module 块上的 depends_on 表达它们之间的顺序。

每个 module 都列出紧邻的前一个包含任何 components 的 wave 中的每个 module,且不列出比它更早的 wave。 其余部分由 Terraform 串联:wave 2 中的 module 依赖 wave 1,而后者又依赖 wave 0,因此整个序列是有序的,同时每个 module 自身的列表只保持一个 wave 的规模,而不是整个 boundary 的规模。wave 不必连续,负值也很常见——对于其余配置会读取的存储桶或角色,-1 是常用的选择。最低的 wave 不列出任何 module,因为它之前没有任何内容。

这种顺序是什么:Terraform 执行其操作的顺序。 Terraform 构建一个依赖图,并在该图允许的范围内并行处理。depends_on 向该图添加一条边,因此 Terraform 会先完成对所列模块的操作,再开始对声明该依赖的模块进行操作。因此,wave 将运行分阶段进行:先对较早 wave 的组件执行操作,再开始较晚 wave 的组件。

它不是就绪顺序。 Terraform 配置中没有资源“可用”的概念,因此这里不会等待资源就绪,只会等待 Terraform 完成对它的操作。这与 compose 上的同一 wave 有实际区别:在 compose 上,声明了 healthcheck 的服务会被等待,直到报告为健康。compose 有可供门控的就绪原语,而 Terraform 配置没有。此目标提供的是操作顺序,直接说明这一点,比给一个无法兑现的承诺附加注意事项更有用。

不承诺销毁顺序。 depends_on 表明的是 Terraform 先完成依赖项的操作,再开始依赖方的操作;destroy 移除它们的顺序不在此表述之内,因此这里对销毁顺序不做任何声明。这比同一 wave 在 cloudformation 上的承诺更窄,后者的属性同时约束两个方向。如果你依赖 wave 来安排销毁顺序,这一点值得了解,因为在此目标上它做不到。

所有组件都带有同一 wave 的边界不会因此获得任何效果。 完全未声明 syncWave 的 Release 也是如此:每个贡献者都带有该字段的默认值 0,根配置只包含一个 wave,生成的字节与 provider 不表达任何 wave 顺序时完全相同。

跨两个根配置的顺序无法表达,也不会被近似处理。 Terraform 依赖图按配置划分,depends_on 指向声明它的配置内部的模块,因此 wave 只对组合进该根配置的组件排序,不涉及其外的任何内容。为两个配置安排顺序是运维人员的事,正如远程状态引用是在部署时而非构建时解析一样。

wave 不仅会被执行,也会被记录:它与节点的其余构建溯源信息一起保存,在加盖的注释块中记为 aggrega.ai/sync-wave,若主体为 JSON 或 vendor 的模块,则记录在配套的溯源文件中。因此,渲染出的配置既按其边界声明的 wave 排序,也记录了该 wave。

wave 未表达的顺序仍由 Terraform 自行处理,而资源之间的引用已经承载了其中大部分:对另一资源属性的引用会让 Terraform 先对该资源执行操作。若模块需要的约束既无法由引用推出,也无法由 wave 推出,则应在模块内部自行编写 depends_on,provider 会像处理主体的其他部分一样原样输出它。

  • Provider 架构 — provider 如何融入编译流水线以及按 provider 分派。
  • Provider 参考索引 — 每个标准库 provider 生成什么,以及哪个页面回答哪个问题。
  • Recipe 实体 — Recipe 的编写接口以及三种输入类型。
  • FeatureRecipe — 渲染后的 pipeline 补丁模型及其结构化/不透明边界。
  • Recipe 输入组合 — 权威的 Provider 能力矩阵。