只允许其网关调用的模型服务器
在集群中运行的模型服务器会响应任何访问其地址的调用方。在没有网络策略的 Pod 网络上(这是 Kubernetes 的默认情况),这意味着集群中的每个 workload:部署在模型前面的网关是流量预期的到达途径,而不是唯一可能的途径。
Aggregate 已经说明了哪些组件调用哪些组件:网关的
upstream 连接指向模型服务器。运维人员在 Release 中将 core/caller-allowlist
附加到模型服务器上,它会把这条声明的连接转换为集群网络的规则。本工作区将这一
编排编译为 Kubernetes manifest:位于命名空间 edge 中的 NGINX 网关、
位于命名空间 models 中的 Ollama 模型服务器,以及该附加项在模型服务器旁写入的网络策略。
本工作区不编写任何自有的目录实体。这里的三个实体文件 ——一个 Aggregate、一个 Manifest 和一个 Release——就是任何人需要 编写的全部内容。
谁编写什么
| 文件 | 作者 | 它在此处声明的内容 |
|---|---|---|
aggregate.yaml | 开发者 | 网关、模型服务器,以及网关指向模型服务器的 upstream 连接 |
release.yaml | 运维人员 | 两个命名空间,以及模型服务器条目上的 allowlist 挂载及其 infra |
manifest.yaml | 运维人员 | 在 Kubernetes 上由哪个 Recipe 实现每个组件和该 Feature |
Aggregate 不包含任何关于网络策略的内容。开发者声明网关建立的
连接;集群是否拒绝其他所有连接,
是运维人员针对此环境做出的决定,在 Release 的
components.model.features 下作出。该 Feature 接受的每个输入都是 infra,即
运维人员的支柱。开发者应当了解的是其后果:只要
Release 将此 Feature 挂载到某个组件上,任何 Aggregate 未声明为指向该组件的 uses 边的调用,都会被集群拒绝——前提是集群的
网络插件会执行网络策略。
它构建了什么
| 实例 | 目录中的 Component | 命名空间 | 它在此处的角色 |
|---|---|---|---|
gateway | core/gateway/nginx | edge | 客户端调用的网关;它将请求转发给模型服务器 |
model | core/ai-model/ollama | models | 模型服务器,提供 llama3.1 服务 |
一条 uses 边:网关指向模型服务器的 upstream 套接字。一个
Feature 挂载,位于 Release 中:allowlist,即 core/caller-allowlist,挂载在
模型服务器上。该 Release 确认集群会强制执行网络策略,并
指定了 Aggregate 之外的一个来源:一个监控代理。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example model-server-caller-allowlist然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd model-server-caller-allowlist构建
aggrega build --release release.yaml --auto-pullrelease 在构建之前需要一个 lockfile,而 lockfile 是生成的而非随附发布的,因此全新克隆的仓库中没有 lockfile。请先解析出一个,或者让构建来填充它:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the build此工作区从 .aggrega-config.yaml 指定的默认注册表解析目录实体;不会从 chart 仓库获取任何内容。
构建会输出如下内容,其中 <workspace> 代表本示例的文件夹:
warning: node "model" (provider "helm"): target "helm" does not support annotation aggrega.ai/namespace on artifacts-only input and ignored it[… omitted: the resolution's summary and a total build time, which differ per run]Build completed: 6 files written to <workspace>/dist该警告与策略有关。目标不会将 Feature 自身的
manifest 放入某个命名空间,因此附加项的模板会将模型服务器的 StatefulSet 所输出到的命名空间写入策略——
即下文中的 namespace: "models"。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `model-server-caller-allowlist` 文件夹,调用一次 `scaffold` 工具,将 `example` 设为 `model-server-caller-allowlist`,不设 `dir`:它会把示例写入一个新的 `model-server-caller-allowlist` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `model-server-caller-allowlist`、`release` 设为 `release.yaml`、`auto_pull` 设为 true、`write` 设为 true。告诉我构建写入了哪些文件;它们位于 `model-server-caller-allowlist/dist/` 下。渲染出的目录树
dist/├── edge/helm/│ ├── gateway-default-service.yaml│ └── gateway-deployment.yaml└── models/helm/ ├── model--allowlist--networkpolicy.yaml ├── model-default-service.yaml ├── model-headless-service.yaml └── model-statefulset.yaml该附加项只添加了一个文件,即该策略。其余每个文件都与同一 Release 在没有它时渲染出的内容逐字节相同。
哪些可以访问模型服务器
dist/models/helm/model--allowlist--networkpolicy.yaml,从其 spec 开始:
spec: podSelector: matchLabels: "app": "model" policyTypes: - Ingress ingress: - from: - namespaceSelector: matchLabels: "kubernetes.io/metadata.name": "models" podSelector: matchLabels: "app": "model" - namespaceSelector: matchLabels: "kubernetes.io/metadata.name": "edge" podSelector: matchLabels: "app": "gateway" - namespaceSelector: matchLabels: "kubernetes.io/metadata.name": "monitoring" podSelector: matchLabels: "app.kubernetes.io/name": "prometheus" ports: - port: 11434 protocol: "TCP"该策略位于 models,即模型服务器的 StatefulSet
被输出到的命名空间;它选中模型服务器的 pod,并在模型服务器容器声明的唯一端口上,
允许来自三个来源的连接:
- 模型服务器自身的 pod,位于
models中,使同一服务器的副本 可以互相访问。 - 网关的 pod,位于命名空间
edge中。 命名空间选择器和 pod 选择器位于同一条目中,因此 pod 必须同时匹配两者。另一个命名空间中 带有相同标签的 workload——例如在别处再次发布的同一个 Aggregate—— 不是该网关,不会被允许。 - 该 Release 指定的监控代理:命名空间
monitoring中 带有标签app.kubernetes.io/name: prometheus的 pod。
每个组件的 pod 由其自身控制器写出的选择器选中——
模型服务器的 StatefulSet 为 app: model,网关的 Deployment 为
app: gateway——每个命名空间都是其 workload 被输出到的命名空间,
两者都读取自渲染输出的内容,而不是手工重新声明。
两个选择器都不带版本,因此新构建上线时,上一个构建的 pod
在被替换之前仍会被选中,仍会被允许。
无法访问它的内容
- 任何其他工作负载,无论位于
models、edge还是其他任何命名空间—— 包括monitoring中的其他代理。 - ingress 控制器,或集群外的任何客户端。 除非 Release 指明,否则 Aggregate 之外的任何对象都不被允许,而此 Release 只指明了监控代理。客户端通过网关访问模型服务器, 这正是该 Aggregate 声明的连接。
- 11434 以外的任何端口。
该策略限制的是谁可以连接,而不是连接所承载的内容:网关转发的请求 会按网关发送时的原样到达模型。
构建无法知道什么
该规则是否被执行。 网络策略由集群的网络插件执行,并且只在该插件实现了网络策略时才会执行;如果集群的插件没有实现,集群会接受该策略,但不执行任何限制。构建负责写出策略,却看不到集群,因此该 Release 在挂载上带有
control_plane_present: true:这是运维人员声明目标集群会执行该策略,在做出这一声明之前,构建会中止。
另有三项限制源于网络策略的工作方式,而不是源于这个 Feature:
- 策略会叠加。 如果集群中另有策略选中了相同的 pod,那么其中任一策略允许的连接都会被允许。
- 网关不受此挂载的限制。 它保护的是模型 服务器;若要限制谁能访问网关,还需在 Release 中网关的条目上也挂载该 Feature,并在那里列出网关所服务的客户端。
- 出站流量不受影响。 模型服务器仍能访问 它拉取权重的镜像仓库,并像以前一样解析名称。
什么会中止构建
以下每一项都是构建打印的一句话,指明需要修改什么:
-
前提条件未被确认。 从 Release 中删除
control_plane_present: true:[… omitted: what resolving the lockfile prints, the same halt among it, and the halt's heading, the template position and the assertion's own source]error calling fail: assertion failed: core/caller-allowlist attachment "allowlist" on "model" writes a network policy, which restricts connections only where the cluster's network plugin enforces network policy; once the target cluster's plugin does, affirm it by setting infra.control_plane_present to true on this attachment in the Release -
某个调用方的 workload 未被输出到任何命名空间。 从
edge边界上删除aggrega.ai/namespace注解,网关的 Deployment 便会在没有命名空间的情况下输出:[… omitted: what resolving the lockfile prints, the same halt among it, and the halt's heading, the artifact being rendered, the template position and the template's own source]error calling fail: core/caller-allowlist attachment "allowlist" on "model": "gateway" connects to "model" through its "upstream" socket, but the Deployment "gateway" it renders is emitted into no namespace, so the policy cannot name where its pods run; set aggrega.ai/namespace on the boundary holding "gateway", or on its own entry, in the Release, or have the manifest that carries it write one -
模型服务器的 workload 未被输出到任何命名空间,原因相同: 策略只选择其自身命名空间中的 pod。
-
两者中任一方的某个 workload 未写控制器选择器,也不带构建在其 pod 上标记的任何身份标签 ——例如某个 chart 的 Job 依赖集群生成的选择器。若按它所带的全部标签来选择它, 一旦某个版本标签发生变化,就不再匹配其 pod,因此构建会改为停止。
-
某个调用方或模型服务器的渲染不输出任何 pod——例如由自定义资源实现、 其控制器稍后才创建 pod 的组件,或通过集群外部地址访问的组件。这样的组件无法在 策略中被指定,因此构建会停止,而不是写出一个会拒绝它或什么都不选择的策略。
-
admitted_sources中的某个来源同时指定了地址范围和 pod, 或两者都未指定。
编译器不做解释的地方
编译器把每次渲染报告的选择器、标签和命名空间作为字符串传入策略。它不连接集群,不知道集群中运行的是哪个网络插件,也不知道某个命名空间中已经运行着哪些工作负载。上文的每一种中止都由目录自身的实体在该 Feature 的实现中声明,没有一种依赖于对集群的任何了解。
改编示例
- 允许一个 ingress 控制器。 在
admitted_sources中添加一个条目,写明它的 命名空间和它的 pod 的标签——两者放在同一个条目中,这样只有该命名空间中的 这些 pod 会被允许。 - 允许一个地址范围。 添加一个带
cidr的条目,例如10.20.0.0/16。 - 第二个调用方。 在 Aggregate 中添加一条从它指向模型服务器的
uses边, 并把它放在该 Release 声明的某个命名空间中;下一次构建即会允许它, 无需修改挂载。 - Compose。 该 Feature 在 Compose 上没有实现:Compose 栈会把一个组中的每个 服务放在同一个网络上,而一个服务的配置无法把另一个服务移出该网络, 因此在 Compose 上绑定此 Feature 的 Release 会因缺少实现而中止。