带附件的 CloudFormation 栈
一个托管数据库和读取它的应用,作为开发者意图编写一次,并组装成 AWS CloudFormation 栈模板。两个附件各自带来自己的资源——数据库上的一个告警和边界上的一个共享设置参数——因此本示例展示附件的资源在组装后的栈中落在何处,以及它们如何与组件的资源一同命名。
同一份开发者意图以三种方式构建:作为一个栈;作为两个栈, 二者之间有一个跨越的引用;以及——有意地——作为一个会中止的构建。
本页的输出块复制自一次真实运行,参见 阅读这些页面上的输出。
文件
aggregate.yaml— 开发者意图:一个类型为core/datastore/mariadb的payments-db数据库,以及一个类型为example/compute/db-reader并声明使用该数据库的reporting-app。这里不包含任何 与 AWS 相关的内容。该数据库的features:块带有storage-headroom, 用于挂载example/storage-alarm。release-one-stack.yaml— 两个组件位于同一个边界内,因此两者会组装 成单个堆栈。在整个边界上挂载core/shared-config。release-two-stacks.yaml— 将同一意图拆分到两个边界中,因此 应用对数据库的引用会跨越堆栈边缘。release-negative-name-collision.yaml搭配aggregate-name-collision.yaml— 预期会失败。 将该告警两次挂载到同一个组件上。manifest.yaml— 将每个组件类型和每个挂载的 Feature 绑定到 在此目标上实现它的 Recipe。.aggrega-config.yaml— 指定目录实体从中解析的 hub 注册表。
每个 release 都在其 payments-db 条目上,用 core/generated-secret 绑定数据库的 root_password 槽位。在此目标上,RDS 掌管管理员密码,Manifest 选中的数据库 Recipe 带有说明这一点的指令;因此该绑定是运维人员的决定,写在 Release 中,Aggregate 对此不作任何说明。
每个 release 还将 core/backup 附加到 payments-db,并设置 infra.retention_days: 14,Manifest 将其绑定到 cloudformation/backup-native。在没有其他设置时,RDS 将实例的自动备份保留 7 天;此附件将每个备份保留 14 天。该 FeatureRecipe 不渲染任何内容:备份是实例的一项设置,因此数据库 Recipe 读取该附件,并将 "BackupRetentionPeriod": 14 写入实例自身的 Properties。
本示例使用的实体全部位于已发布的 catalog 中。没有任何内容 被复制到 release 文件旁边,因此本示例针对 catalog 的当前状态进行解析, 而不是针对其私有快照。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example cloudformation-rds-stack然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd cloudformation-rds-stack构建
本示例包含三个 release,因此需要指定你要构建的那一个。每次运行只构建一个 release。每个 release 的首次构建都需要其锁文件,该文件由拉取写入:
aggrega pull --release release-one-stack.yamlaggrega build --release release-one-stack.yaml构建会输出如下内容,其中 <workspace> 代表本示例的文件夹:
Total build time: 4.1sBuild completed: 1 file written to <workspace>/dist组装好的 stack 位于
dist/one-stack/cloudformation/cloudformation-stack.json。渲染到该目录的每个 component 和每个 attachment 都会为这一个模板贡献内容——provider 输出单个纯 JSON 的 stack,而不是为每个贡献者各生成一个文件。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `cloudformation-rds-stack` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `cloudformation-rds-stack`,且不设置 `dir`:它会将示例写入新的 `cloudformation-rds-stack` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `cloudformation-rds-stack`,`release` 设为 `release-one-stack.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `cloudformation-rds-stack/dist/` 下。产出了什么,由谁贡献
单栈构建从 四个 不同的贡献者组装出 四个 资源:
| 资源 | 贡献者 |
|---|---|
PaymentsDb | 数据库组件自身的 Recipe |
PaymentsDbStorageHeadroom | 该组件上的 storage-headroom 附件 |
AppSharedConfig | 边界上的 shared-settings 附件 |
ReportingApp | 应用组件自身的 Recipe |
payments-db 上的 backup 附件不在表中,因为它不贡献自己的资源:它所设置的内容落在 PaymentsDb 内部。
每个资源都带有一个来源块,指明它来自哪个贡献者,因此在双方共同贡献的栈中, 两部分仍可区分:
"PaymentsDbStorageHeadroom": { "Metadata": { "aggrega.ai/provenance": { "aggrega.ai/aggregate-name": "aggregate", "aggrega.ai/boundary-path": "app", [… omitted: a compiler-version entry, which moves with the build] "aggrega.ai/component-id": "cfr--payments-db--storage-headroom", "aggrega.ai/environment": "production", "aggrega.ai/provider": "cloudformation", [… omitted: a provider-version entry, which moves with the build] "aggrega.ai/recipe-uri": "storage-alarm:1.0.0" } }, [… omitted: the alarm's Properties, printed in full just below] "Type": "AWS::CloudWatch::Alarm" },两个版本条目是该块中仅有的会在不同构建之间变化的行,因此将其省略;第三处省略只是告警的
Properties,单独在下方列出。其余所示内容正是你自己的构建所写出的内容。
告警是附件的资源,而不是数据库的资源。从 Aggregate 上拆下
storage-headroom,恰好会移除该资源及其发布的那一个输出,而 PaymentsDb 逐字节保持原样。
附件的资源名称带有承载该附件的作用域
一个 Feature 只编写一次,却会被多次附加,因此 FeatureRecipe
派生的名称必须对每个附件都不同。这里组合了宿主组件和附件名称:宿主 payments-db,以 storage-headroom 承载,
得到 PaymentsDbStorageHeadroom。
仅组合宿主足以让告警与其监视的资源不冲突,但 不 足以避免同一个 Feature 两次附加到同一组件时与自身冲突——这正是下文失败的 release 所要说明的。
告警自身的属性通过宿主的派生名称引用宿主:
"Properties": { "AlarmDescription": "Free storage below 21474836480 bytes on payments-db", "ComparisonOperator": "LessThanThreshold", "Dimensions": [ { "Name": "DBInstanceIdentifier", "Value": { "Ref": "PaymentsDb" } } ], "EvaluationPeriods": 2, "MetricName": "FreeStorageSpace", "Namespace": "AWS/RDS", "Period": 300, "Statistic": "Minimum", "Threshold": 21474836480, "TreatMissingData": "breaching" },在栈部署时,数据库资源上的 Ref 解析为该实例的标识符。两部分都从同一个组件名称派生出 PaymentsDb,
这正是二者一致的原因——这里没有任何查找。
在一个附件上,谁决定什么
附件划分输入的方式与组件相同。应用需要多少余量属于开发者意图,在
aggregate.yaml 中的附件上编写——它是应用的属性。告警通知到哪里,以及下降需持续多久才触发,属于运维规格,
由 Release 提供:
payments-db: features: storage-headroom: infra: evaluation_periods: 3 notify_target: "arn:aws:sns:eu-west-1:123456789012:payments-oncall"Release 为 Aggregate 声明的附件提供 infra,从不提供
values。双栈 release 两者都设置;单栈 release 两者都不设置,差异可从输出中看出。设置时:
"Properties": { "AlarmActions": [ "arn:aws:sns:eu-west-1:123456789012:payments-oncall" ],未设置时,该字段是 不存在,而非为空——告警生成时完全没有通知动作,EvaluationPeriods 取 Recipe 携带的 2,而不是 Feature 声明的任何值。两者都不提供的 Release 仍能得到一个可用的告警,提供其中一个则恰好增加一个字段。
附件的输出由其宿主命名,而不是由附件自身命名
栈的两部分按不同规则命名,而这一部分最容易让人意外。
资源逻辑 ID 来自附件自身的 Recipe——即上文的名称。
输出按发布组件与条目共同命名,而对于附件,发布组件就是宿主。 告警发布一个条目 alarm-id,它呈现为:
"paymentsXzhdbXXalarmXzhid": { "Value": { "Ref": "PaymentsDbStorageHeadroom" } },了解规则后,两部分便可读懂:逻辑 ID 只允许字母和数字,因此 provider 会把该字母表拒绝的字符拼写出来,而不是丢弃——Xzh 是你写的连字符,XX 是组件名称结束、条目名称开始的位置。只有 payments-db 发布 alarm-id 才会得到这个名称。组装后栈中的名称完整说明了该方案。
如果是数据库本身发布 alarm-id,得到的也会是同一个输出名称。因此,宿主也发布的条目名称会与附件的条目在同一个输出名称上相撞——这就是为什么读起来属于附件自身的条目名称能与宿主的保持区分。
边界范围的附件对该边界只渲染一次
core/shared-config 在 Release 中附加在边界上而不是某个组件上,它对该边界只渲染 一次——而不是对其中每个组件各渲染一次。单栈构建包含两个组件,且恰好一个 AppSharedConfig:
"AppSharedConfig": { [… omitted: the provenance Metadata, whose shape is shown above] "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production" }, "Type": "AWS::SSM::Parameter" },构建双栈 release 时这一点更明显:每个边界都有自己的一份,携带该边界自身解析后的设置。该构建写出的两个模板中各自那一份的 Properties:
"Properties": { "Description": "Settings shared by every component in the data boundary", "Name": "/data/shared-config", "Type": "String", "Value": "tier=production-data" }, "Properties": { "Description": "Settings shared by every component in the app boundary", "Name": "/app/shared-config", "Type": "String", "Value": "tier=production-app" },它在 Release 中附加,是因为它携带的是运维者自己的安排,而不是 Aggregate 声明的内容。边界附件设置 infra:,从不设置 values:——Aggregate 仍是编写开发者值的地方。
将同一意图拆分到两个栈中
aggrega pull --release release-two-stacks.yamlaggrega build --release release-two-stacks.yamlaggregate.yaml 中没有任何改动。应用仍然声明它使用该数据库;由运维人员在 Release 中决定二者分开预置,因此它们之间的引用会跨越一条栈边界。
在单栈构建中,应用在同一个模板内以引用的形式接收该端点:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] } },在双栈构建中,生产者栈将该值发布为一个导出:
"paymentsXzhdbXXhost": { "Value": { "Fn::GetAtt": [ "PaymentsDb", "Endpoint.Address" ] }, "Export": { "Name": "aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host" } },消费者栈则按同一名称将其读回:
"Properties": { "Name": "/reporting/db-host", "Tier": "Standard", "Type": "String", "Value": {"Fn::ImportValue":"aggrega--cloudformation-two-stacks--two-stacks-data-zscloudformation--payments-db--host"} },只有 host 带有 Export,因为它是一条边实际消费的条目;数据库发布的其他条目以普通输出的形式出现。组件作用域的告警随其宿主进入生产者栈,而每个边界保留各自的边界级附加项。
这两个内部函数都不会在构建时求值。端点要到栈部署时才存在,因此编译器将该引用原样传递,由 CloudFormation 解析——这就是应用从不指定地址的原因。
关于导出名称如何构建,以及消费者何时通过 Fn::ImportValue 而不是直接跨账户读取,请参阅跨栈连接。
会中止的构建
aggrega pull --release release-negative-name-collision.yamlaggrega build --release release-negative-name-collision.yamlaggregate-name-collision.yaml 将告警两次附加到同一个组件上,
使用两个不同的附加名称。每个附加的资源名称都由其自身的
附加名称组合而成,因此这两个告警是两个不同的资源,在资源名称上不会冲突。
冲突发生在它们的输出上:每个附加都发布 alarm-id,而输出是按
宿主组件和条目命名的,两者的宿主又是同一个组件。
[… omitted: the pull's lines, which report the same collision while writing the lockfile][TRANSLATION_ERROR E0038] dispatch groups whose contributors derive one name more than once in one key space caused by (2): [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom", provider "cloudformation", dispatch path "name-collision/cloudformation") --- [TRANSLATION_ERROR] release-negative-name-collision.yaml derived name collision: one name is derived more than once in one key space ("paymentsXzhdbXXalarmXzhid", key space "output-logical-ids", derived by component "payments-db", carrying attachment "storage-headroom-strict", provider "cloudformation", dispatch path "name-collision/cloudformation")从中可以读出四点,每一点都是有意为之。
- 两端都被指明。 每个条目都给出组件以及它所承载的附加 名称,因此两者都可以在你编写的文件中搜索到。冲突本身 并不能说明哪一个贡献者的名称才是预期的,因此两者都会 被报告,而不只是第一个。
- 键空间被指明。
output-logical-ids告诉你到达的是该栈 两个名称空间中的哪一个,并且——由于此次中止中没有出现资源名称空间—— 说明资源名称没有问题。 - 不输出任何内容。 构建会停止,而不是写出一个其中 有一个告警悄无声息地没有输出的栈。
- 给资源取不同的名称并不能解决这个问题。 输出名称由 宿主组件和条目构建而成,因此必须不同的是条目—— 要么只用一个附加而不是两个,要么使用一个 Feature,其发布的条目名称 读起来就属于该附加自身。
相同的输入,相同的输出
在输入未变的情况下构建两次,会生成逐字节相同的模板。 编译器不解析任何实时数据——它从不调用 AWS,从不查询账户标识符,也从不运行 CloudFormation——因此重新构建时 不会发现任何可能改变字节的内容。这正是基于差异的审查所依赖的特性。
dist/ 和 *.lock 文件是生成的,不会提交;它们
可以从已提交的文件重新生成。