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

一份契约,三种实现

一个 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 助手替你构建。

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

Terminal window
aggrega scaffold --example postgres-three-realizations

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

Terminal window
cd postgres-three-realizations

构建

Terminal window
aggrega build --release release-selfhosted.yaml --auto-pull
aggrega build --release release-managed.yaml --auto-pull
aggrega build --release release-managed-dns.yaml --auto-pull
aggrega build --release release-external.yaml --auto-pull

--auto-pull 会在每个 Release 首次构建时写入其锁文件;之后的构建无需该标志。每次构建都写入 dist/,且构建会添加其文件,而不会清除先前构建留下的内容。若要单独查看某一种实现的输出,请在两次运行之间删除 dist/:

Terminal window
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 访问它。

dist/stack/helm/app-deployment.yaml
- 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:此部署的两侧在数据库发布的契约处相接,而不是在共享的目标处。

dist/stack/helm/app-deployment.yaml
- 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.net

Recipe 以 host 发布该名称来代替 Terraform 引用, 应用接收到的是:

dist/stack/helm/app-deployment.yaml
- name: DB_HOST
value: db.internal.example.net
变量release-managed.yamlrelease-managed-dns.yaml
DB_HOST${module.db.address}db.internal.example.net
DB_PORT54325432

输出中只有这一行发生变化。Recipe 不为该名称输出 DNS 记录或别名,构建也不查找它:编译器传递它的方式与传递引用完全相同。在实例存在后把 db.internal.example.net 指向该实例——在运维人员自己的 DNS 区域中创建一条指向实例地址的记录——是运维人员的事,在 Release 之外。该键与下文引用式实现读取同一地址所用的键相同;此 Recipe 将其作为裸名称或 IP 字面量接受,带有协议、路径、用户或端口的值会使构建停止,因为端口是 Release 的 infra.port,消费者用这两者组合出连接。

渲染到与数据库相同 Terraform 配置中的消费者也会接收到该名称,同时失去 引用带来的顺序:Terraform 会在某个模块所引用的模块之后处理该模块,而名称 不引用任何东西。把该消费者放入一个独立边界,与数据库共享 directory:, 并携带更晚的 syncWave:,即可恢复顺序。

外部——此部署中无人运行服务器

helm/postgres-external 不创建任何资源。它的全部输出是一个 Service,把集群内名称映射到 Release 提供的地址:

dist/stack/helm/db-service.yaml
[… 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
dist/stack/helm/app-deployment.yaml
- 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 of
PostgreSQL, which addresses a server it does not provision, but no address was
supplied: set infra.overrides.host on this component in the Release to the DNS
name or IP literal the existing server answers on

关键在于这一对比

应用渲染出的环境变量,三者并列对比:

变量自托管托管外部
POOL_SIZE101010
DB_HOSTdb-default${module.db.address}postgres.data.example.net
DB_NAMEappdbappdbappdb
DB_PORT543254325432
DB_PROTOCOLpostgrespostgrespostgres
DB_USERappuserappuserappuser

变量相同,顺序相同,每次都一样。只有其中一个变量背后的字符串会变化。 应用的 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 不会改变。