一份契约,三种实现
一个 PostgreSQL 数据库和读取它的应用程序,由同一个未经改动的 Aggregate 以三种不同方式部署:在集群中运行的 PostgreSQL、作为托管云实例的 PostgreSQL,以及一个在本 Release 部署之前就已存在的 PostgreSQL 服务器。
**要点在于不变的部分。**应用程序只需一次性地指明它想从数据库获取哪些键,以及 如何称呼它们。它永远不会知道三者中是哪一个作出了响应。编译器也不会知道:它读取所选 Recipe 发布的键,并路由这些字符串。
唯一变化的部分
.-- helm/postgres ---------- a StatefulSet in the cluster /core/datastore/postgres --- terraform/postgres-rds -- an RDS instance in Terraform one Component \ one contract '- helm/postgres-external -- a server that already exists三个 Recipes 实现同一个 Component。每个都发布相同的 provides
键——host、port、user、database、protocol,以及说明
抓取器在何处找到数据库指标的键,这些键在三者中均为空。运行哪一个,只是
Manifest 中的一行。
文件
aggregate.yaml— 开发者意图,且三种部署使用同一份文档:一个类型为core/datastore/postgres的db组件,一个uses它的app,以及应用所需的五个键。这里没有指定任何目标、云或 Recipe。manifest-selfhosted.yaml、manifest-managed.yaml、manifest-external.yaml— 运维映射。每个都用一行选择其实现方式:PostgreSQL 组件类型绑定哪个 Recipe。托管的那个还会绑定其 Releases 所附加的备份 Feature。release-selfhosted.yaml、release-managed.yaml、release-external.yaml— 运维人员在每个 Release 中设定的规格:集群内部署的存储和引擎版本,托管部署的存储、高可用以及一个core/backup附加项,引用部署的现有服务器地址。release-managed-dns.yaml— 再次给出托管的 Release,附带运维人员为实例指定的 DNS 名称,从而应用获得一个可以解析的名称。catalog/— 应用自己的 Component 以及渲染它的那一个 Recipe。数据库一侧的所有内容都直接来自标准库,未作修改。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example postgres-three-realizations然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd postgres-three-realizations构建
aggrega build --release release-selfhosted.yaml --auto-pullaggrega build --release release-managed.yaml --auto-pullaggrega build --release release-managed-dns.yaml --auto-pullaggrega build --release release-external.yaml --auto-pull--auto-pull 会在每个 Release 首次构建时写入其锁文件;之后的构建无需该标志。每次构建都写入 dist/,且构建会添加其文件,而不会清除先前构建留下的内容。若要单独查看某一种实现的输出,请在两次运行之间删除 dist/:
rm -rf dist && aggrega build --release release-managed.yaml借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `postgres-three-realizations` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `postgres-three-realizations`,不设 `dir`:它会把示例写入新的 `postgres-three-realizations` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-selfhosted.yaml`、`release-managed.yaml`、`release-managed-dns.yaml` 和 `release-external.yaml`——每次都将 `workspace_root` 设为 `postgres-three-realizations`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `postgres-three-realizations/dist/` 下。每种实现渲染出什么
自托管——由部署运行服务器
helm/postgres 在集群中合成数据库:一个 StatefulSet、一个
ClusterIP Service 和一个 headless Service。provides.host 是该 Service 的裸名称,
因此应用通过集群内 DNS 访问它。
- name: DB_HOST value: db-default托管——由云服务商运行服务器
terraform/postgres-rds 以 Terraform HCL 形式输出一个 aws_db_instance,运维人员的 ha 规格和 core/backup 附加项映射到该实例的原生设置上:附加项的 retention_days: 14 变为实例的 backup_retention_period = 14。应用仍渲染到 Kubernetes:此部署的两侧在数据库发布的契约处相接,而不是在共享的目标处。
- name: DB_HOST value: ${module.db.address}该值不是主机名,本次构建中也没有任何环节把它变成主机名。 RDS 实例的地址在实例创建之前并不存在,因此提前运行的编译器无从查找。 Recipe 发布的是对数据库自身模块某个输出的 Terraform 引用;编译器原封不动地 把它沿边传递,应用的 Recipe 逐字接收,并在 Kubernetes manifest 中渲染为 上文所示的字面字符。容器拿到的就是这段文本。
DB_PORT 则不同:它渲染为 "5432",因为 Recipe 根据 Release 设置实例端口,
并发布同一个值,该值在任何资源存在之前就已确定。
两个组件之间的原生连接是目标在其自身输出内部完成的事,因此这里无需进行。
这条边的两端通过不同目标渲染——数据库渲染为 Terraform HCL,应用渲染为
Kubernetes manifest——而 Terraform 引用只在 Terraform 配置内部才有意义。
跨越这条接缝时,发布的值和其他字符串一样以文本形式交付。若消费者以 source:
Recipe 渲染到 Terraform 上,并与数据库处于同一根配置中,它会以其模块参数之一的
形式接收同一个引用,Terraform 会在那里解析它。
这是通用规则,而不是针对 RDS 的特例:凡是依赖运行中系统状态的内容, 都表示为由运行时解析的确定性指针,而不是由编译器获取的值。编译器的职责是 原样交付该指针。让它在落地处能被解析,是 Recipe 作者的事:发布一个消费方 可用的地址,或为两个组件提供渲染到同一目标的 Recipes。
为实例提供一个应用可解析的名称
terraform/postgres-rds 把其中第一种做法作为运维人员设置的选项。release-managed-dns.yaml 是托管的 Release,只多了一项:运维人员为实例指定的 DNS 名称:
db: infra: overrides: host: db.internal.example.netRecipe 以 host 发布该名称来代替 Terraform 引用,
应用接收到的是:
- name: DB_HOST value: db.internal.example.net| 变量 | release-managed.yaml | release-managed-dns.yaml |
|---|---|---|
DB_HOST | ${module.db.address} | db.internal.example.net |
DB_PORT | 5432 | 5432 |
输出中只有这一行发生变化。Recipe 不为该名称输出 DNS 记录或别名,构建也不查找它:编译器传递它的方式与传递引用完全相同。在实例存在后把 db.internal.example.net 指向该实例——在运维人员自己的 DNS 区域中创建一条指向实例地址的记录——是运维人员的事,在 Release 之外。该键与下文引用式实现读取同一地址所用的键相同;此 Recipe 将其作为裸名称或 IP 字面量接受,带有协议、路径、用户或端口的值会使构建停止,因为端口是 Release 的 infra.port,消费者用这两者组合出连接。
渲染到与数据库相同 Terraform 配置中的消费者也会接收到该名称,同时失去
引用带来的顺序:Terraform 会在某个模块所引用的模块之后处理该模块,而名称
不引用任何东西。把该消费者放入一个独立边界,与数据库共享 directory:,
并携带更晚的 syncWave:,即可恢复顺序。
外部——此部署中无人运行服务器
helm/postgres-external 不创建任何资源。它的全部输出是一个
Service,把集群内名称映射到 Release 提供的地址:
[… omitted: the Service's apiVersion, kind and metadata — its name, db, and the labels and annotations every rendered document carries]spec: type: ExternalName externalName: postgres.data.example.net ports: - port: 5432没有 StatefulSet、没有卷、没有容器——服务器的生命周期完全 在此部署之外。地址来自 Release:
db: infra: overrides: host: postgres.data.example.net- name: DB_HOST value: postgres.data.example.net引用一个服务器并不等于接管它。此 Recipe 访问的服务器 仍归外部所有;这里没有任何内容把它纳入部署的管理,也没有任何内容会更改它。
**省略地址,构建就会停止并说明原因。**被引用的服务器 要么有地址,要么什么都没有,因此 Recipe 会拒绝,而不是输出一个 为空名称设置别名的 Service:
[… omitted: what resolving the lockfile prints, the same halt among it, then [CATALOG_ERROR E0033], the Recipe's assertion external_host_supplied, its template position and source, and "error calling fail:"]assertion failed: the Manifest selects the referenced realization ofPostgreSQL, which addresses a server it does not provision, but no address wassupplied: set infra.overrides.host on this component in the Release to the DNSname or IP literal the existing server answers on关键在于这一对比
应用渲染出的环境变量,三者并列对比:
| 变量 | 自托管 | 托管 | 外部 |
|---|---|---|---|
POOL_SIZE | 10 | 10 | 10 |
DB_HOST | db-default | ${module.db.address} | postgres.data.example.net |
DB_NAME | appdb | appdb | appdb |
DB_PORT | 5432 | 5432 | 5432 |
DB_PROTOCOL | postgres | postgres | postgres |
DB_USER | appuser | appuser | appuser |
变量相同,顺序相同,每次都一样。只有其中一个变量背后的字符串会变化。 应用的 Recipe 没有点名任何 DB_ 变量:它输出 uses 边解析得到的任何内容,这正是同一个 Recipe 能针对这三种数据库不加修改地渲染的原因。
而且编译器并不知道这些字符串是什么。db-default 是一个 Kubernetes Service 名称,${module.db.address} 是一个 Terraform 引用,postgres.data.example.net 是一个 DNS 名称——对编译器而言,它们只是三个字符串:某个 Recipe 以键 host 发布了它们,某条边要求以 DB_HOST 交付它们。编译器不检查其中任何一个是否可路由,不检查端口是否为数字,也不检查名为 db 的组件是否是数据库。它只是根据 Component 携带的标签匹配边,读取契约声明的键,然后搬运文本。
分界线在哪里
这三种部署各由一个 Ops 映射选定,而开发者文档不受这一选择的影响。这正是整个示例要具体呈现的分工:
- 开发者说明应用需要数据库提供什么;
- Ops 说明数据库由什么构成——每种实现一个 Recipe;
- 运维人员说明本次部署使用哪一种,并确定其规格。
明天再添加第四种实现——换一个云、换一个运营方,或用于本地开发的 Compose 服务——也只是多一个发布相同键的 Recipe,外加一行 Manifest。此目录中的 aggregate.yaml 不会改变。