Собственный сертификат вебхука: исключение сгенерированного чартом Secret
Это продвинутый пример. Он знакомит с полем omits: сущности Recipe, которое большинству сущностей Recipes никогда не требуется: оно предназначено для источника, который используется как есть, — здесь это чарт, загруженный
из реестра, — и который рендерит документ, который ваша сущность Release не должна поставлять. Обращайтесь
к нему, когда встретите такой случай.
Рабочее пространство собирает плоскость управления Envoy AI Gateway — контроллер, который Envoy
Gateway вызывает как свой сервер расширений, — через Recipe из стандартной библиотеки
helm/envoy-ai-gateway-operator, в обоих режимах, которые может принимать его сертификат вебхука. В одном из них чарт проекта рендерит Secret, содержащий ключ и
сертификат, которые он заново генерирует при каждом рендеринге, и запись omits: в Recipe
исключает этот Secret из сборки. Ещё две сущности Releases показывают две остановки,
с которыми можно столкнуться вокруг этого поля: ту, для предотвращения которой запись существует, и ту, которую
вызывает запись, больше ничему не соответствующая.
Что собирается
Один компонент, ai-controller, из core/gateway/envoy-ai-gateway-operator,
скомпилированный в манифесты Kubernetes. Сущность Aggregate одна и та же для каждой сущности Release.
Каждая сущность 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 | останавливается с E0058 при сборке с --verify-determinism |
release-negative-stale-omits.yaml | helm/envoy-ai-gateway-operator-stale-omits, из этого рабочего пространства | Secret ai-gateway-webhook-tls | останавливается с E0334 |
Две сущности Recipes в catalog/ этого рабочего пространства — учебные варианты
Recipe из стандартной библиотеки. Каждая берёт тот же чарт той же версии и
выбирает режим сертификата по тому же сопоставлению: в одной нет записи omits:, а
в другой есть запись, называющая Secret, который чарт не генерирует. У них
собственные имена, поэтому они располагаются рядом с Recipe из стандартной библиотеки, а не
затеняют её, и то, с какой из них собирается сущность Release, решает названная ею сущность Manifest.
Два способа предоставить webhook сертификат
Контроллер запускает изменяющий webhook, который API-сервер кластера вызывает по
TLS, поэтому webhook предъявляет сертификат. Сущность Component предлагает два способа
его предоставить, выбираемые одним ключом infra — webhook_tls_secret:
- Не задан — по умолчанию. Чарт создаёт cert-manager
Certificateдля имени Service контроллера и самоподписанныйIssuer, который его подписывает, поэтому cert-manager уже должен работать в кластере. - Задан. Webhook предъявляет сертификат из Secret, названного ключом; его
заранее создаёт в пространстве имён контроллера тот, кто выполняет развёртывание, и он содержит
tls.crt,tls.keyиca.crt. НиCertificate, ниIssuerне создаются, и cert-manager не нужен: при запуске контроллер записываетca.crtиз Secret в конфигурацию webhook как пакет CA, по которому API-сервер проверяет webhook.
release-own-certificate.yaml задаёт его:
components: ai-controller: annotations: aggrega.ai/namespace: envoy-ai-gateway-system infra: webhook_tls_secret: ai-gateway-webhook-tlsЧто рендерит чарт в режиме собственного сертификата
Когда ключ задан, чарт проекта монтирует Secret с этим именем в под контроллера
по пути /certs — и при этом рендерит собственный Secret под тем же
именем, содержащий сертификат CA, сертификат и закрытый ключ, которые он
генерирует во время рендеринга. Две сборки генерируют два разных ключа, поэтому
вывод перестаёт быть побайтово идентичным от сборки к сборке, а его применение
заменило бы Secret, созданный оператором, на Secret, сгенерированный чартом.
Чарт загружается из реестра проекта и используется как есть: сущность Recipe не редактирует загруженный чарт. Вместо этого 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указывают документ таким, каким его рендерит чарт:Secret, у которогоmetadata.name— имя, заданное сущностью Release. Шаблонnameчитает тот же ключinfra, который передаётся чарту, поэтому запись указывает на сгенерированный Secret, как бы его ни назвала сущность Release.whenделает так, что запись применяется только в этом режиме. В режиме cert-manager чарт не рендерит такой Secret; там условие ложно, а запись, у которойwhen:ложно, отбрасывается до каких-либо проверок. Одна сущность Recipe обслуживает оба режима.
Остальная часть чарта по-прежнему рендерится полностью, и из того, что записывает сборка, исключается только совпавший документ. Исключить его здесь правильно, потому что Secret, который монтирует под контроллера, принадлежит оператору и создаётся отдельно. Это поле исключает документ; оно не проверяет, существует ли где-то ещё то, на что опирается остальной вывод.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
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 — реестра по умолчанию, который он указывает. При наличии рабочей копии каталога стандартной библиотеки (где её взять) укажите её директорию aggrega-catalog через --catalog, и каждая сущность будет разрешаться из этих двух каталогов.
--auto-pull заполняет lock-файл каждой сущности Release во время сборки; lock-файлы и
отрисованный вывод генерируются, а не поставляются. При разрешении lock-файла чарт
контроллера загружается из Docker Hub, поэтому для первой сборки каждой сущности Release нужна
сеть.
С ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки сами. Если в папке рабочего пространства ещё нет папки `ai-gateway-own-webhook-certificate`, вызовите один раз инструмент `scaffold`, задав для `example` значение `ai-gateway-own-webhook-certificate` и не задавая `dir`: он запишет пример в новую папку `ai-gateway-own-webhook-certificate`. Затем вызовите инструмент `build` по одному разу для каждой сущности Release в таком порядке — `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/`.Два режима сертификата в отрендеренном виде
При сборке release-cert-manager.yaml с --auto-pull выводится следующее (<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.yamlКаталог ai-controller содержит шесть определений ресурсов AI Gateway, которые Recipe выпускает рядом с чартом. Сборка 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-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.yamlДерево режима cert-manager содержит Certificate и Issuer и не содержит Secret. Дерево режима собственного сертификата не содержит ни одного из трёх: ни Certificate, ни Issuer, потому что в этом режиме чарт не рендерит ни того, ни другого, и ни Secret, потому что запись в Recipe исключила тот, который чарт всё же отрендерил. Вместо этого контроллер монтирует Secret, указанный в сущности Release:
[… 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 — имя, которое сборка передаёт как написано, а кластер разрешает при запуске пода.
Одни и те же байты от сборки к сборке
При повторной сборке с --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 рендерит каждый компонент дважды из одних и тех же входных данных и
останавливает сборку, если два результата различаются. Здесь проверка проходит, и дерево, которое она записывает, байт
в байт совпадает с деревом, записанным первой сборкой. И то и другое выполняется потому, что единственный документ, который
чарт каждый раз генерирует заново, никогда не попадает в вывод.
Без записи: сборка с проверкой детерминированности останавливается
release-negative-without-omits.yaml — это Release с собственным сертификатом, развёрнутый
через manifest-without-omits.yaml, который привязывает учебный 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
каждый раз генерировал другой ключ и сертификат. Pull также рендерит
Release, чтобы найти внешние входные данные, которые нужно закрепить, и встречает там ту же остановку;
поэтому опущенные строки pull повторяют это предложение. Lock-файл
всё равно записывается.
Без этого флага тот же Release собирается успешно. Его дерево содержит те же документы chart, что и дерево Release с собственным сертификатом, — за вычетом определений ресурсов, которые учебный Recipe не выдаёт, — и ещё один: Secret, сгенерированный chart:
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]Соберите его дважды, и два дерева будут различаться ровно этими тремя значениями. Обычная сборка рендерит каждый компонент один раз, поэтому записывает тот ключ, который сгенерировала, и ничего не замечает; именно проверка делает различие видимым. Будучи применён, этот файл заменил бы Secret, созданный оператором.
Эта остановка описана в разделе
A provider rendered the same input twice and produced different output (Провайдер дважды отрендерил одни и те же входные данные и получил разный результат),
где исправление называет два выхода, когда различие — значение, которое генерирует используемый
вами chart: передать значение через настройку, которую предлагает chart, или, если
сгенерированный документ не должен поставляться в составе Release, исключить его записью
omits: — так поступает Recipe из стандартной библиотеки.
Запись, которая ничему не соответствует
release-negative-stale-omits.yaml — это Release с собственным сертификатом, развёртываемый
через manifest-stale-omits.yaml, который привязывает учебный 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Провайдер указывается с версией бинарного файла, выполнившего сборку, поэтому при вашем собственном запуске там будет версия вашего бинарного файла.
Сборка завершается с кодом 1, а строки получения содержат то же предложение по той же
причине, что и выше. Сообщение читается слева направо как указание, куда смотреть:
компонент, провайдер, который его отрендерил, Recipe, объявляющий запись, и
позиция записи в его списке omits:, считая от 0, а затем вид и
имя, в которые разрешилась запись. Условие when: в этом режиме истинно, поэтому
запись применяется; её имя рендерится в ai-controller-webhook-tls, chart
назвал свой Secret ai-gateway-webhook-tls, и запись ничего не исключила.
Каждая применяемая запись должна что-то исключать, и сборка останавливается на записи,
которая этого не делает, потому что запись, ничему не соответствующая, — это утверждение об источнике,
которое больше не верно. Обычная причина — обновление источника, переименовавшее
документ. Переименованный документ тогда попадает в вывод под новым именем — тот
самый документ, ради исключения которого была написана запись, — и остановка не даёт ему
незаметно попасть в поставку. В этой сборке таким документом является Secret, сгенерированный chart:
запись была написана, чтобы исключить его, но называет нечто другое. Чтобы
исправить запись, сравните её с тем, что источник рендерит сейчас: выполните сборку
без этой записи, как это делает release-negative-without-omits.yaml без
проверки, и прочитайте имя в файле, который записал chart.
E0334 указан в справочнике диагностик как
omit-matched-nothing и описан в разделе
An omits entry left out nothing the source rendered (Запись omits не исключила ничего из отрендеренного источником).
Само поле — все поля записи, контекст шаблона, что Release может
решать о записи и какие провайдеры её учитывают, — описано в разделе
Recipe → Поле omits:.
Проверка каждой сборки
Эта самопроверка выполняется в рабочей копии репозитория документации, которая содержит используемый ею общий вспомогательный скрипт сборки; копия, записанная aggrega scaffold --example, этого скрипта не содержит.
./check.shcheck.sh собирает четыре сущности Releases через ./build-release.sh и сверяет каждый
результат с тем, который описывает эта страница. Каждую успешную сущность Release он собирает
дважды, второй раз с --verify-determinism: обе сборки должны завершиться с кодом 0 и
записать одни и те же файлы, байт в байт, а дерево, если считать по kind
каждого отрендеренного документа, должно содержать Certificate и Issuer и ни одного Secret в
режиме cert-manager и ни одного из трёх в режиме собственного сертификата, причём
том certs в Deployment контроллера должен указывать 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.Ему нужно то же, что и отдельной сборке: каталог стандартной библиотеки и сеть для чарта. Он использует бинарный файл, который находит ./build-release.sh, поэтому его выбирает AGGREGA_BIN; аргументы после -- передаются каждой сборке. Он отказывается запускаться, пока в этом каталоге есть dist/, потому что сравнивает деревья, которые записывают сборки, и не оставляет ни одного после себя. Его код завершения — это весь вердикт, поэтому конвейер может запускать его вместо того, чтобы собирать каждую сущность Release по отдельности.
Где компилятор не интерпретирует
Компилятор не знает, что такое Secret, что контроллер с ним делает и зачем чарту его генерировать. Он вычисляет шаблоны записи так же, как любой шаблон сущности Recipe, передаёт kind и имя, в которые они разрешаются, helm-провайдеру вместе с входными данными компонента, а провайдер отбрасывает отрендеренные документы, которые им соответствуют, и сообщает, сколько документов отбросила каждая запись. Компилятор никогда не ищет ai-gateway-webhook-tls в кластере, никогда его не создаёт и никогда не проверяет, что он содержит три записи, которые читает контроллер: имя — это строка, которую передаёт сущность Release и которая подставляется в значения чарта и в запись. Обеспечить, чтобы 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/— учебный Recipe без записиomits:и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— собирает все четыре и проверяет результат каждой сборки.