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

带附件的 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 助手替你构建。

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

Terminal window
aggrega scaffold --example cloudformation-rds-stack

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

Terminal window
cd cloudformation-rds-stack

构建

本示例包含三个 release,因此需要指定你要构建的那一个。每次运行只构建一个 release。每个 release 的首次构建都需要其锁文件,该文件由拉取写入:

Terminal window
aggrega pull --release release-one-stack.yaml
aggrega build --release release-one-stack.yaml

构建会输出如下内容,其中 <workspace> 代表本示例的文件夹:

Total build time: 4.1s
Build 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 仍是编写开发者值的地方。

将同一意图拆分到两个栈中

Terminal window
aggrega pull --release release-two-stacks.yaml
aggrega build --release release-two-stacks.yaml

aggregate.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 而不是直接跨账户读取,请参阅跨栈连接。

会中止的构建

Terminal window
aggrega pull --release release-negative-name-collision.yaml
aggrega build --release release-negative-name-collision.yaml

aggregate-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 文件是生成的,不会提交;它们 可以从已提交的文件重新生成。