Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Собственный сертификат вебхука: исключение сгенерированного чартом 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.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останавливается с E0058 при сборке с --verify-determinism
release-negative-stale-omits.yamlhelm/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, который монтирует под контроллера, принадлежит оператору и создаётся отдельно. Это поле исключает документ; оно не проверяет, существует ли где-то ещё то, на что опирается остальной вывод.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

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 — реестра по умолчанию, который он указывает. При наличии рабочей копии каталога стандартной библиотеки (где её взять) укажите её директорию 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-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 содержит шесть определений ресурсов 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-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, потому что в этом режиме чарт не рендерит ни того, ни другого, и ни Secret, потому что запись в Recipe исключила тот, который чарт всё же отрендерил. Вместо этого контроллер монтирует Secret, указанный в сущности Release:

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 — имя, которое сборка передаёт как написано, а кластер разрешает при запуске пода.

Одни и те же байты от сборки к сборке

При повторной сборке с --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:

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]

Соберите его дважды, и два дерева будут различаться ровно этими тремя значениями. Обычная сборка рендерит каждый компонент один раз, поэтому записывает тот ключ, который сгенерировала, и ничего не замечает; именно проверка делает различие видимым. Будучи применён, этот файл заменил бы 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, этого скрипта не содержит.

Terminal window
./check.sh

check.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=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.

Ему нужно то же, что и отдельной сборке: каталог стандартной библиотеки и сеть для чарта. Он использует бинарный файл, который находит ./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 — собирает все четыре и проверяет результат каждой сборки.