跨边界网络——一个意图,两种部署
一个由两个组件组成的栈——Adminer 数据库 UI 和 PostgreSQL 数据库 ——分布在两个边界上,Adminer 必须跨越边界接缝访问数据库。同一份开发者意图以两种方式部署,而这种 对比正是要点:
- 本地(Docker Compose):每个边界是各自独立的 compose 网络,一个网络中的服务无法通过名称访问另一个网络中的服务。标准库
core/compose-bridgeFeature 的 compose FeatureRecipe 会生成一个aggrega-gw网关来跨越这一接缝。 - Kubernetes(Helm):每个边界是各自独立的命名空间,一个命名空间中的 pod
通过原生跨命名空间 DNS访问另一个命名空间中的 Service
(
db-default.backend)——无需桥接。数据库发布一个不带限定的服务 名称;消费方的core/k8s-dns-resolver路由 feature 会用目标命名空间 对其加以限定。
**compose-bridge 所提供的,正是 Kubernetes 命名空间 + 跨命名空间 DNS
原生提供的能力。**跨越接缝是 Ops/Operator 关注的问题,因目标而异;
开发者意图不变。同一个 aggrega.ai/namespace
边界注解,在一个变体中决定 compose 网络的放置,在另一个变体中决定
Kubernetes 命名空间的放置。
共享的开发者意图
aggregate.yaml 在两种变体中完全相同:
components: adminer: type: core/devtool/adminer uses: databases: primary: target: db inject: env: - in: ADMINER_DEFAULT_SERVER # rewritten/resolved per variant from: host # ← the target db's provides.host db: type: core/datastore/postgres唯一的 uses 边将数据库的 host 注入 ADMINER_DEFAULT_SERVER。
该主机解析为什么,是在 Aggregate 之下决定的 Ops 关注点——因此
同一条边在 compose 下得到 aggrega-gw:5432,在 helm 下得到 db-default.backend,
而开发者意图无需任何改动。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example cross-boundary-networking然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd cross-boundary-networking构建
每个变体都是一个 Release,基于其自己的目录文件夹构建,每次运行一个 Release:
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeaggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helm借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自行创建任何文件夹。如果工作区文件夹中还没有 `cross-boundary-networking` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `cross-boundary-networking`,且不设置 `dir`:它会把示例写入新的 `cross-boundary-networking` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `cross-boundary-networking`,`release` 设为 `release-compose.yaml`,`catalog_dirs` 设为包含 `catalog-compose` 的列表,`auto_pull` 设为 true,`write` 设为 true。然后以同样的方式调用 `build` 工具,将 `release` 设为 `release-helm.yaml`,`catalog_dirs` 设为包含 `catalog-helm` 的列表。告诉我每次构建写入了哪些文件;它们位于 `cross-boundary-networking/dist/` 下。变体 A — 本地(Docker Compose):桥接
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-compose父级 bridge 边界包含两个子边界:frontend(adminer)和 backend(db),二者共享同一目录,因此合并为单个 dist/bridge/compose/docker-compose.yaml。每个子边界的 aggrega.ai/namespace 注解成为一个 compose 网络。挂载在父级(边界作用域)的 core/compose-bridge 根据跨网络的 uses 边派生出一个 aggrega-gw 网关。它的标准库 FeatureRecipe 为该边界计算一次需要桥接的边的表——两端都在这一个 compose 文件中,但位于不同的网络——下文的一切都由它自己的模板从该表中读取:
- 它的
valuesMapping写出网关的 nginxstream配置,作为挂载的 compose config 交付(顶层configs:,挂载在/etc/nginx/nginx.conf);它带有一个resolver和按边设置的变量proxy_pass,使上游在连接时解析($被转义为$$,以便 Compose 的插值为 nginx 保留它); - 同一个
valuesMapping在网关的x-aggrega-networks-of下指明两端,由 compose provider 解析,因此网关会加入两个被桥接的网络; - 它的
injectMapping针对 adminer 运行,将消费方的ADMINER_DEFAULT_SERVER改写为aggrega-gw:5432。该改写替换的是 adminer 自身的databases连接所交付的值;如果挂载到 adminer 的另一个 Feature 交付了该变量,构建会停止并指出两者,而不是替换它。
因此流量按 adminer → aggrega-gw:5432 → proxy_pass db:5432 流动,经由网关跨越
网络边界。
运行
cd dist/bridge/composedocker compose up打开 http://localhost:8080(服务器已预填 aggrega-gw:5432)并登录:
| 字段 | 值 |
|---|---|
| 系统 | PostgreSQL |
| 服务器 | aggrega-gw:5432(已预填) |
| 用户名 | appuser |
| 密码 | apppass |
| 数据库 | appdb |
这些凭据仅用于演示(直接内联设置在 db recipe 上,使该栈 开箱即可运行);实际部署使用凭据子系统。
变体 B — Kubernetes(Helm):命名空间 + 跨命名空间 DNS
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helm同一个 Aggregate,部署到 Kubernetes。两个同级边界,各自带有不同的 aggrega.ai/namespace 注解,该注解以
metadata.namespace 的形式级联到每个资源:
dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontenddist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontenddist/backend/helm/db-statefulset.yaml # metadata.namespace: backenddist/backend/helm/db-default-service.yaml # metadata.namespace: backenddist/backend/helm/db-headless-service.yaml # metadata.namespace: backend这里没有 aggrega-gw。helm 的 db recipe 在 provides.host 中发布一个裸服务
名称——helm provider 将合成的 Service 命名为
<rendered_name>-<service-key>(db-default),不带命名空间。消费方
挂载 core/k8s-dns-resolver 路由 feature(由 Release 将其指向
ADMINER_DEFAULT_SERVER),该 feature 在消费方自己这一侧用目标的命名空间限定这个裸主机名——在 Adminer 渲染之前生成跨命名空间 DNS
名称 db-default.backend。该主机名是推导出来的,而不是
手写在生产方中:
- name: ADMINER_DEFAULT_SERVER value: db-default.backend # == the rendered db Service <name>.<namespace>该值与渲染出的 db Service 的 metadata.name +
metadata.namespace 逐字节匹配,这就是全部的证明:Kubernetes 跨命名空间 DNS 是
确定性的契约,因此只要渲染出的主机名等于渲染出的 Service
标识,它就能在运行时解析——无需网关,也无需运行中的集群来验证
连接关系。
二者的对偶
| compose(变体 A) | helm(变体 B) | |
|---|---|---|
| 边界接缝 | 各自独立的 compose 网络 | 各自独立的命名空间 |
| 跨越机制 | core/compose-bridge 网关(aggrega-gw) | 原生跨命名空间 DNS |
ADMINER_DEFAULT_SERVER 解析为 | aggrega-gw:5432(经过重写) | db-default.backend(在调用方一侧限定) |
| 额外资源 | aggrega-gw 服务及其配置 | 无 |
同一个 aggrega.ai/namespace 决定 | compose 网络归属 | k8s 命名空间归属 |
开发者意图只有一个;跨越接缝是特定于 provider 的 Ops/Operator 机制。compose 桥接之所以存在,是因为扁平的 compose 网络没有 按命名空间划分的 DNS;而 Kubernetes 原生就提供了这一能力。
当两端由不同的 provider 渲染时
上面的两个变体都保持同一个开发者意图,并让跨越过程依托于一个
确定性指针字符串:数据库的 provides.host 作为稳定指针跨越
边界接缝,每个目标以自己的方式解析该指针
——compose 网关地址,或跨命名空间 DNS 名称。该指针
总能跨越,因为编译器在生产者与
消费者之间传递字符串,而不解释它们。
provider 还可以更进一步,在接缝两侧其自身组装的两个工件之间连接一个原生交叉引用——一个以该
provider 自身词汇表达、由目标平台在部署时解析的引用。
CloudFormation provider 对跨越栈的 uses 边就是这样做的:
生产者栈发布一个 Export,消费者栈通过
Fn::ImportValue 读取它(参见 providers/cloudformation.md)。
原生交叉引用是一种同一 provider 内的升级——它之所以可行,是因为两
端使用相同的工件词汇,所以一方可以发布另一方知道如何解析的引用。
当一条 uses 边跨越两个不同 provider 之间的边界时——生产者在一个 provider 下组装,消费者在另一个 provider 下组装——就无法建立原生交叉引用。以一个 provider 的词汇生成的引用对另一个毫无意义,而编译器不在它们之间做转换:它传递字符串,不推断含义,也不把一个 provider 的引用改写成另一个的形式。因此,生产者的确定性指针原样跨越接缝;若两个 provider 中任一个自身会连接原生交叉引用(如 CloudFormation),编译器会发出一条警告,指明两个端点、两个 provider 名称以及该 socket;构建则基于该指针完成。编译器信任作者,不会中止:作者提供的确定性指针很可能可以跨接缝解析——稳定的 DNS 名称或基础设施插值字符串——而只有作者了解目标拓扑。
这让跨越接缝的工作留在它应在的位置。跨 provider 的指针是否 可用,是由作者负责的部署问题;把一个 provider 的原生 引用转换为另一个 provider 的消费者形式,是带有立场、特定于 provider 的工作,位于中立核心之外。
目录结构
cross-boundary-networking/├── .aggrega-config.yaml # marks this folder as the workspace root; names the hub registry├── aggregate.yaml # SHARED developer intent (both variants)├── release-compose.yaml # Variant A: parent bridge boundary + two networks├── manifest-compose.yaml├── catalog-compose/ # local adminer compose recipe (the component + the rest from standard)├── release-helm.yaml # Variant B: two namespace boundaries, no bridge├── manifest-helm.yaml└── catalog-helm/ # local adminer helm recipe (the components + the rest from standard)本示例使用标准库。每个变体都使用 --catalog catalog-<variant>(即它自己的本地目录)构建,并从 .aggrega-config.yaml 指定的默认注册表 hub.aggrega.ai 解析该目录未声明的内容,因此本地实体先于共享实体解析。core/datastore/postgres、共享的 core/devtool/adminer UI 组件、core/compose-bridge 和 core/k8s-dns-resolver 这两个 Features 及其 compose 和 helm FeatureRecipes,以及 compose/helm provider,均来自标准目录。保留在本地的是本示例特有的教学内容:各目标的 Adminer recipe。helm 的 db recipe 是标准库的 helm/postgres,其 provides.host 是一个独立、自包含的服务名。消费者通过标准库的 core/k8s-dns-resolver 路由 feature,在调用方用目标命名空间限定该服务名,因此该 recipe 不硬编码任何边界命名空间。
构建后的变体中有两类文件:编写的输入(上述所有内容),以及 dist/ 下由编译器生成的输出(合并后的 docker-compose.yaml,或按命名空间划分的 helm 清单)——后者无需你编写。dist/ 由 aggrega build 重新生成,并已加入 gitignore。