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

自备 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.yamlhelm/envoy-ai-gateway-operator,来自标准库cert-manager构建成功
release-own-certificate.yamlhelm/envoy-ai-gateway-operator,来自标准库Secret ai-gateway-webhook-tls构建成功,每次构建的字节完全相同
release-negative-without-omits.yamlhelm/envoy-ai-gateway-operator-without-omits,来自本工作区Secret ai-gateway-webhook-tls使用 --verify-determinism 构建时以 E0058 中止
release-negative-stale-omits.yamlhelm/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-tls

chart 在自有证书模式下渲染的内容

设置该键后,项目的 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 助手替你构建。

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

Terminal window
aggrega scaffold --example ai-gateway-own-webhook-certificate

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

Terminal window
cd ai-gateway-own-webhook-certificate

构建

Terminal window
aggrega build --release release-cert-manager.yaml --auto-pull
aggrega build --release release-own-certificate.yaml --auto-pull
aggrega build --release release-negative-without-omits.yaml --auto-pull --verify-determinism # halts; exits 1
aggrega 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-controller
ai-controller-certificate-envoy-ai-gateway-system-self-signed-cert-for-mutating-webhook.yaml
ai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yaml
ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
ai-controller-issuer-envoy-ai-gateway-system-self-signed-issuer-for-mutating-webhook.yaml
ai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yaml
ai-controller-service-envoy-ai-gateway-system-ai-controller.yaml
ai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yaml

ai-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>/dist

ls dist/helm 列出:

ai-controller
ai-controller-clusterrole-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrole-envoy-ai-gateway-inference-pool-reader-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-ai-controller-envoy-ai-gateway-system.yaml
ai-controller-clusterrolebinding-envoy-ai-gateway-inference-pool-reader-binding-envoy-ai-gateway-system.yaml
ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
ai-controller-mutatingwebhookconfiguration-envoy-ai-gateway-gateway-pod-mutator-envoy-ai-gateway-system.yaml
ai-controller-service-envoy-ai-gateway-system-ai-controller.yaml
ai-controller-serviceaccount-envoy-ai-gateway-system-ai-controller.yaml

cert-manager 模式的目录树包含一个 Certificate 和一个 Issuer,没有 Secret。自有证书模式的目录树三者都没有:没有 Certificate 也没有 Issuer,因为 chart 在该模式下不渲染这两者;也没有 Secret,因为 Recipe 中的条目排除了 chart 确实渲染出的那个。控制器转而挂载的是 Release 所指定的 Secret:

dist/helm/ai-controller-deployment-envoy-ai-gateway-system-ai-controller.yaml
[… omitted: the chart's licence header, four comment lines]
apiVersion: apps/v1
kind: Deployment
metadata:
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:

dist/helm/ai-controller-secret-envoy-ai-gateway-system-ai-gateway-webhook-tls.yaml
apiVersion: v1
kind: Secret
metadata:
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 cause

provider 以运行该构建的二进制文件的版本命名,因此你自己运行时,此处显示的是你的二进制文件的版本。

构建以 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 写出的副本不包含该辅助脚本。

Terminal window
./check.sh

check.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=0
release-own-certificate.yaml 0/0 pass OK: byte-identical twice; Certificate=0 Issuer=0 Secret=0; certs volume: ai-gateway-webhook-tls
release-negative-without-omits.yaml 1 halt OK: E0058, the expected sentence
release-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 — 构建全部四个并检查每个结果。