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

跨边界网络——一个意图,两种部署

一个由两个组件组成的栈——Adminer 数据库 UI 和 PostgreSQL 数据库 ——分布在两个边界上,Adminer 必须跨越边界接缝访问数据库。同一份开发者意图以两种方式部署,而这种 对比正是要点:

  • 本地(Docker Compose):每个边界是各自独立的 compose 网络,一个网络中的服务无法通过名称访问另一个网络中的服务。标准库 core/compose-bridge Feature 的 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 助手替你构建。

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

Terminal window
aggrega scaffold --example cross-boundary-networking

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

Terminal window
cd cross-boundary-networking

构建

每个变体都是一个 Release,基于其自己的目录文件夹构建,每次运行一个 Release:

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega 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):桥接

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega 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 写出网关的 nginx stream 配置,作为挂载的 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 流动,经由网关跨越 网络边界。

运行

Terminal window
cd dist/bridge/compose
docker compose up

打开 http://localhost:8080(服务器已预填 aggrega-gw:5432)并登录:

字段值
系统PostgreSQL
服务器aggrega-gw:5432(已预填)
用户名appuser
密码apppass
数据库appdb

这些凭据仅用于演示(直接内联设置在 db recipe 上,使该栈 开箱即可运行);实际部署使用凭据子系统。

变体 B — Kubernetes(Helm):命名空间 + 跨命名空间 DNS

Terminal window
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

同一个 Aggregate,部署到 Kubernetes。两个同级边界,各自带有不同的 aggrega.ai/namespace 注解,该注解以 metadata.namespace 的形式级联到每个资源:

dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontend
dist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontend
dist/backend/helm/db-statefulset.yaml # metadata.namespace: backend
dist/backend/helm/db-default-service.yaml # metadata.namespace: backend
dist/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。该主机名是推导出来的,而不是 手写在生产方中:

dist/frontend/helm/adminer-deployment.yaml
- 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。