自备 webhook 证书:排除 chart 生成的 Secret
这是一个进阶示例。它讲解 Recipe 字段 omits:,大多数
Recipes 都用不到它:它适用于你原样采用的来源(这里是从 registry 获取的 chart),
而该来源渲染出了你的 Release 不得交付的文档。遇到这种情况时,
再使用它。
该工作区通过标准库 Recipe
helm/envoy-ai-gateway-operator 构建 Envoy AI Gateway 控制平面(即 Envoy
Gateway 作为其扩展服务器调用的控制器),并覆盖其 webhook 证书可采用的两种模式。
在其中一种模式下,该项目的 chart 会渲染一个 Secret,其中包含每次渲染时重新生成的密钥和
证书,而 Recipe 的 omits:
条目将该 Secret 排除在构建之外。另外两个 Releases 展示了围绕该字段可能遇到的两种停止:
一种是该条目旨在防止的停止,另一种是
不再匹配任何内容的条目所导致的停止。
它构建了什么
一个组件 ai-controller,属于 core/gateway/envoy-ai-gateway-operator,
编译为 Kubernetes 清单。每个 Release 使用相同的 Aggregate。
每个 Release 将控制器放在 envoy-ai-gateway-system 中并选择
证书模式;每个 Manifest 选择 Recipe:
| Release | 其 Manifest 绑定的内容 | 证书模式 | 结果 |
|---|---|---|---|
release-cert-manager.yaml | helm/envoy-ai-gateway-operator,来自标准库 | cert-manager | 构建成功 |
release-own-certificate.yaml | helm/envoy-ai-gateway-operator,来自标准库 | Secret ai-gateway-webhook-tls | 构建成功,每次构建的字节完全相同 |
release-negative-without-omits.yaml | helm/envoy-ai-gateway-operator-without-omits,来自本工作区 | Secret ai-gateway-webhook-tls | 使用 --verify-determinism 构建时以 E0058 中止 |
release-negative-stale-omits.yaml | helm/envoy-ai-gateway-operator-stale-omits,来自本工作区 | Secret ai-gateway-webhook-tls | 以 E0334 中止 |
本工作区 catalog/ 中的两个 Recipes 是标准库中那个 Recipe 的教学变体。
它们都以同一版本获取同一个 chart,并通过相同的映射选择证书模式:
一个没有 omits: 条目,另一个的条目指定了 chart 并不渲染的 Secret。
它们有各自的名称,因此与标准库 Recipe 并存而不会遮蔽它,
由 Release 指定的 Manifest 决定使用哪一个进行构建。
为 webhook 提供证书的两种方式
该控制器运行一个变更型 webhook,集群的 API server 通过
TLS 调用它,因此该 webhook 需要提供证书。该 Component 提供两种
方式来提供证书,由一个 infra 键 webhook_tls_secret 选择:
- 未设置,即默认值。 chart 会为控制器的 Service 名称渲染一个 cert-manager
Certificate, 以及为其签名的自签名Issuer,因此 cert-manager 必须已在集群中运行。 - 已设置。 webhook 提供该键所指定 Secret 中的证书,该 Secret
由部署者事先在控制器的命名空间中创建,包含
tls.crt、tls.key和ca.crt。不会渲染Certificate和Issuer, 也不需要 cert-manager:控制器启动时,会将 该 Secret 的ca.crt写入 webhook 配置,作为 API server 校验 webhook 所用的 CA bundle。
release-own-certificate.yaml 设置了该键:
components: ai-controller: annotations: aggrega.ai/namespace: envoy-ai-gateway-system infra: webhook_tls_secret: ai-gateway-webhook-tlschart 在自有证书模式下渲染的内容
设置该键后,项目的 chart 会将该名称的 Secret 挂载到
控制器 pod 的 /certs 中——同时它还会以相同名称渲染一个自己的 Secret,
其中包含它在渲染时生成的 CA 证书、证书和私钥。两次构建会生成两个不同的密钥,因此
输出在两次构建之间不再逐字节相同;而应用该输出
会用 chart 生成的 Secret 替换运维人员创建的 Secret。
该 chart 从项目的 registry 获取,并按原样使用;Recipe 不会编辑获取到的 chart。标准库 Recipe 改为将该 Secret 排除在外:
# helm/envoy-ai-gateway-operator:1.0.0, its omits: field omits: - kind: Secret name: "{{ .infra.webhook_tls_secret }}" when: '{{ ne (optional .infra "webhook_tls_secret" "") "" }}'kind和name按 chart 渲染的样子指定该文档:一个Secret, 其metadata.name是 Release 设置的名称。name模板读取 chart 所接收的同一个infra键,因此无论 Release 如何命名,该条目都能指定所生成的 Secret。when使该条目仅在此模式下生效。 在 cert-manager 模式下, chart 不会渲染这样的 Secret;此时条件为假,而when:为假的条目 会在任何检查之前被丢弃。一个 Recipe 可同时服务于两种模式。
chart 的其余部分仍会完整渲染,只有匹配的文档会 从构建写出的内容中丢弃。此处排除它是正确的,因为 控制器 pod 挂载的 Secret 是运维人员自己单独创建的。 该字段只是排除一个文档;它不会检查输出的其余部分所依赖的内容 是否存在于别处。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example ai-gateway-own-webhook-certificate然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd ai-gateway-own-webhook-certificate构建
aggrega build --release release-cert-manager.yaml --auto-pullaggrega build --release release-own-certificate.yaml --auto-pullaggrega build --release release-negative-without-omits.yaml --auto-pull --verify-determinism # halts; exits 1aggrega build --release release-negative-stale-omits.yaml --auto-pull # halts; exits 1.aggrega-config.yaml 列出工作区自己的 catalog/,其中包含两个教学用的 Recipes;该 Component 和标准库 Recipe 从它指定的默认注册表 hub.aggrega.ai 解析。若有标准库目录的检出(获取途径),用 --catalog 指定其 aggrega-catalog 目录,每个实体便都从这两个目录解析。
--auto-pull 在构建期间填充每个 Release 的锁文件;锁文件和渲染输出都是生成的,不随项目分发。解析锁文件时会从 Docker Hub 拉取控制器的 chart,因此每个 Release 的首次构建需要联网。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 的工具,不要自己创建任何文件夹。如果工作区文件夹中还没有 `ai-gateway-own-webhook-certificate` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `ai-gateway-own-webhook-certificate`,且不提供 `dir`:它会把示例写入一个新的 `ai-gateway-own-webhook-certificate` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-cert-manager.yaml`、`release-own-certificate.yaml`——每次都将 `workspace_root` 设为 `ai-gateway-own-webhook-certificate`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。接着调用 `cli-build` 工具(它运行 `aggrega build` 并接受其 `--verify-determinism` 标志),将 `workspace_root` 设为 `ai-gateway-own-webhook-certificate`,`release` 设为 `release-negative-without-omits.yaml`,`auto_pull` 设为 true,`verify_determinism` 设为 true:这次构建预期会被拒绝,所以把拒绝信息读给我听。然后按前两次构建的方式调用 `build` 工具,将 `release` 设为 `release-negative-stale-omits.yaml`:这次也预期会被拒绝,所以也把这条拒绝信息读给我听。告诉我每次构建写入了哪些文件;它们位于 `ai-gateway-own-webhook-certificate/dist/` 下。两种证书模式的渲染结果
使用 --auto-pull 构建 release-cert-manager.yaml 时,输出如下(其中 <workspace> 代表本示例的文件夹):
Pull complete: release-cert-manager.lock (entities=5, source_artifacts=1, external_inputs=0)[… omitted: the total build time, which differs per run]Build completed: 16 files written to <workspace>/dist随后 ls dist/helm 列出:
ai-controllerai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yamlai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yamlai-controller-deployment-envoy-ai-gateway-system-ai-controller.yamlai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yamlai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yamlai-controller-service-envoy-ai-gateway-system-ai-controller.yamlai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yamlai-controller 目录存放 Recipe 在 chart 旁边输出的六个 AI Gateway 资源定义。以同样方式构建 release-own-certificate.yaml,输出如下:
Pull complete: release-own-certificate.lock (entities=5, source_artifacts=1, external_inputs=0)[… omitted: the total build time, which differs per run]Build completed: 14 files written to <workspace>/distls dist/helm 列出:
ai-controllerai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yamlai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yamlai-controller-deployment-envoy-ai-gateway-system-ai-controller.yamlai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yamlai-controller-service-envoy-ai-gateway-system-ai-controller.yamlai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yamlcert-manager 模式的目录树包含一个 Certificate 和一个 Issuer,没有 Secret。自有证书模式的目录树三者都没有:没有 Certificate 也没有 Issuer,因为 chart 在该模式下不渲染这两者;也没有 Secret,因为 Recipe 中的条目排除了 chart 确实渲染出的那个。控制器转而挂载的是 Release 所指定的 Secret:
[… omitted: the chart's licence header, four comment lines]apiVersion: apps/v1kind: Deploymentmetadata: name: ai-controller namespace: envoy-ai-gateway-system [… omitted: the labels and annotations every rendered document carries]spec: [… omitted: the replica count, the selector, and the pod template's labels, service account, host-network setting and security settings] containers: - name: ai-gateway-helm [… omitted: the container's security settings, its image and pull policy, and its ports] args: [… omitted: the controller's logging, external-processor, gateway-namespace and endpoint arguments] - --tlsCertDir=/certs - --tlsCertName=tls.crt - --tlsKeyName=tls.key [… omitted: the controller's webhook-port, leader-election, prefix, cache, namespace, quota and session-encryption arguments] [… omitted: the probes, the environment and the resources] volumeMounts: - mountPath: /certs name: certs readOnly: true volumes: - name: certs secret: secretName: ai-gateway-webhook-tls控制器从 /certs 读取证书,即 certs 卷,它对应 Secret ai-gateway-webhook-tls——这个名称由构建按原样传递,并在 pod 启动时由集群解析。
每次构建产生相同的字节
使用 --verify-determinism 再次构建 release-own-certificate.yaml,
输出:
[… omitted: the total build time, which differs per run]Build completed: 14 files written to <workspace>/dist--verify-determinism 会从同一输入将每个 component 渲染两次,
如果两次渲染结果不同则中止。此处检查通过,且它写出的目录树与第一次构建写出的目录树逐字节相同。两者都成立,是因为该
chart 每次重新生成的那一个文档从未进入输出。
没有该条目:检查确定性的构建会中止
release-negative-without-omits.yaml 是通过 manifest-without-omits.yaml 部署的自有证书 Release,该 Manifest 绑定的教学用 Recipe 没有
omits: 条目。使用 --verify-determinism 构建:
[… omitted: the pull's lines][TRANSLATION_ERROR E0058] instance ai-controller rendering node "ai-controller" caused by: wasmengine: node "ai-controller" (provider "helm"): two renders of identical input produced different output: provider render is not deterministic构建以 1 退出。控制器的两次渲染结果不同,因为 chart
每次都生成了不同的密钥和证书。拉取过程也会渲染该
Release,以找出需要固定的外部输入,并在那里遇到同样的中止;这就是被省略的拉取输出行中第二次出现这句话的原因。lockfile 仍会被写入。
不带该标志构建时,同一个 Release 会成功完成。它的输出树包含自有证书 Release 的输出树所含的 chart 文档(减去资源定义,教学用 Recipe 不会输出它们),外加一个文档,即 chart 生成的 Secret:
apiVersion: v1kind: Secretmetadata: name: ai-gateway-webhook-tls namespace: envoy-ai-gateway-system [… omitted: the labels and annotations every rendered document carries]data: [… omitted: the three base64-encoded entries ca.crt, tls.crt and tls.key]构建两次,两棵输出树恰好在这三个值上不同。普通构建只渲染每个 component 一次,因此会写出它碰巧生成的密钥而不会察觉;正是这项检查让差异变得可见。 如果应用该文件,它会替换运维人员创建的 Secret。
该中止在
A provider rendered the same input twice and produced different output(某个 provider 对同一输入渲染两次却产生了不同输出)
下有说明,其修复方法给出了当差异来自你引用的 chart 所生成的值时的两种解决途径:通过 chart 提供的设置来提供该值;或者,当生成的文档是 Release 不得发布的文档时,用
omits: 条目将其排除——这正是标准库 Recipe 采用的做法。
不匹配任何内容的条目
release-negative-stale-omits.yaml 是通过 manifest-stale-omits.yaml 部署的自有证书 Release,该文件绑定的教学 Recipe 中的条目按控制器的渲染名称而不是按键来命名该 Secret:
# catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/recipe.yaml, its omits: field omits: - kind: Secret name: "{{ .context.rendered_name }}-webhook-tls" when: '{{ ne (optional .infra "webhook_tls_secret" "") "" }}'构建结果:
[… omitted: the pull's lines][TRANSLATION_ERROR E0334] instance ai-controller rendering node "ai-controller" caused by: [CATALOG_ERROR] instance ai-controller an omits entry left out nothing the source rendered (node "ai-controller", provider "provider/helm:0.8.8-75-g9e6ef4e0", "envoy-ai-gateway-operator-stale-omits" omits[0], kind "Secret", name "ai-controller-webhook-tls"). correct the entry so it names something the source renders, or remove it; a source upgrade that renamed or removed it is the usual causeprovider 以运行该构建的二进制文件的版本命名,因此你自己运行时,此处显示的是你的二进制文件的版本。
构建以 1 退出,pull 的输出行出于与上文相同的原因带有同一句话。该消息从左到右依次说明要查看的位置:组件、渲染它的 provider、声明该条目的 Recipe 以及该条目在其 omits: 列表中的位置(从 0 开始计数),然后是该条目解析得到的 kind 和名称。when: 条件在此模式下为真,因此该条目适用;其名称渲染为 ai-controller-webhook-tls,而 chart 将其 Secret 命名为 ai-gateway-webhook-tls,于是该条目没有排除任何内容。
每个适用的条目都必须排除某些内容,构建会在不满足这一点的条目上停止,因为一个不匹配任何内容的条目是对源的一个不再成立的陈述。常见原因是源升级后重命名了该文档。此时被重命名的文档会以新名称出现在输出中——正是该条目原本要排除的那个文档——而此次中止正是为了防止它在无人察觉的情况下被发布。在本次构建中,chart 生成的 Secret 就是这样的文档:条目原本是为排除它而写的,却命名了别的东西。要更正条目,请将其与源当前渲染的内容进行比较:移除该条目后进行构建(就像 release-negative-without-omits.yaml 在不做检查时那样),然后从 chart 写出的文件中读取名称。
E0334 在诊断参考中列为 omit-matched-nothing,并在 An omits entry left out nothing the source rendered(omits 条目未排除源渲染的任何内容)下进行了说明。该字段本身——每个条目字段、模板上下文、Release 可以就条目决定什么,以及哪些 provider 支持它——见 Recipe → omits: 字段。
检查每一次构建
此自检在文档仓库的检出中运行,该检出包含它所使用的共享构建辅助脚本;由 aggrega scaffold --example 写出的副本不包含该辅助脚本。
./check.shcheck.sh 通过 ./build-release.sh 构建这四个 Releases,并将每个结果与本页描述的结果进行核对。它将每个能通过的 Release 构建两次,第二次带上 --verify-determinism:两次构建都必须以 0 退出并逐字节写出相同的文件;按每个渲染出的文档的 kind 计数,输出树在 cert-manager 模式下必须包含一个 Certificate 和一个 Issuer 且不含 Secret,在自有证书模式下三者都不含,并且控制器 Deployment 的 certs 卷指向 ai-gateway-webhook-tls。防护性的 Release 必须以非零状态退出,且恰好产生一个中止,该中止带有本页为其给出的简短代码和语句;过时条目的中止必须指出该条目。它为每个 Release 打印一行,若有任何结果不符则以 1 退出,并打印该次构建的输出:
RELEASE EXIT EXPECTED VERDICT------------------------------------------------------------------------------------------------release-cert-manager.yaml 0/0 pass OK: byte-identical twice; Certificate=1 Issuer=1 Secret=0release-own-certificate.yaml 0/0 pass OK: byte-identical twice; Certificate=0 Issuer=0 Secret=0; certs volume: ai-gateway-webhook-tlsrelease-negative-without-omits.yaml 1 halt OK: E0058, the expected sentencerelease-negative-stale-omits.yaml 1 halt OK: E0334, the expected sentence, naming "envoy-ai-gateway-operator-stale-omits" omits[0]
check: every build ended as expected.它所需的与单次构建相同:标准库目录,以及获取 chart 所需的网络。它使用 ./build-release.sh 解析出的二进制文件,因此由 AGGREGA_BIN 选择;-- 之后的参数会传给每一次构建。只要本目录下存在 dist/,它就拒绝启动,因为它要比较各次构建写出的输出树,并且不会留下任何输出树。它的退出状态就是全部结论,因此流水线可以运行它来代替逐个构建每个 Release。
编译器不做解释的地方
编译器不知道 Secret 是什么、控制器拿它做什么,也不知道 chart 为什么会生成它。编译器像求值任何 Recipe 模板一样求值该条目的模板,把它们解析出的 kind 和 name 连同该组件的输入交给 helm provider,由 provider 丢弃匹配的渲染文档,并报告每个条目丢弃了多少个。编译器从不在集群中查找
ai-gateway-webhook-tls,从不创建它,也从不检查它是否包含控制器读取的三个条目:这个名称只是 Release 提供的一个字符串,被传入 chart 的 values 和该条目中。确保该 Secret 在控制器启动之前存在,是部署一方需要安排的事。
文件
aggregate.yaml— AI 网关控制器,即唯一的组件;对每个 Release 都相同。manifest.yaml— 将控制器绑定到标准库 Recipe;由两个 通过的 Releases 共用。manifest-without-omits.yaml、manifest-stale-omits.yaml— 将控制器绑定到 两个教学用 Recipes 之一。release-cert-manager.yaml、release-own-certificate.yaml— 两种 证书模式。release-negative-without-omits.yaml、release-negative-stale-omits.yaml— 通过各个教学用 Recipe 使用自有证书模式;两者都会中止。catalog/recipe/helm/envoy-ai-gateway-operator-without-omits/1.0.0/— 没有omits:条目的教学用 Recipe,以及固定其 chart 的entity.lock。catalog/recipe/helm/envoy-ai-gateway-operator-stale-omits/1.0.0/— 条目 不匹配任何内容的教学用 Recipe,及其entity.lock。.aggrega-config.yaml— 目录搜索栈和注册表。build-release.sh— 构建一个 Release,并输出等效的aggrega build命令。check.sh— 构建全部四个并检查每个结果。