Власний сертифікат вебхука: вилучення згенерованого чартом 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/ цього робочого простору — навчальні варіанти
тієї, що зі стандартної бібліотеки. Кожна бере той самий чарт того самого випуску і
вибирає режим сертифіката за тим самим зіставленням: одна не має запису omits:, а
інша має запис, що називає Secret, якого чарт не рендерить. Вони мають
власні імена, тож стоять поруч із сутністю Recipe зі стандартної бібліотеки, а не
затіняють її, і сутність Manifest, яку називає Release, визначає, з якою з них відбувається збирання.
Два способи надати вебхуку сертифікат
Контролер запускає змінювальний вебхук, який API-сервер кластера викликає через
TLS, тож вебхук надає сертифікат. Сутність Component пропонує два способи
його надати, вибір між якими визначає один ключ infra, webhook_tls_secret:
- Не задано, типово. Чарт рендерить cert-manager
Certificateдля імені Service контролера та самопідписанийIssuer, що його підписує, тож cert-manager уже має працювати в кластері. - Задано. Вебхук надає сертифікат із Secret, названого ключем, який
заздалегідь створює в просторі імен контролера той, хто розгортає, і який містить
tls.crt,tls.keyтаca.crt. ЖоденCertificateі жоденIssuerне рендеряться, і cert-manager не потрібен: під час запуску контролер записуєca.crtіз Secret у конфігурацію вебхука як пакет CA, за яким API-сервер перевіряє вебхук.
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, сертифікат і приватний ключ, які він генерує під час рендерингу. Дві збірки генерують два різні ключі, тож вивід перестає бути побайтово ідентичним від однієї збірки до наступної; а його застосування замінило б Secret, створений оператором, тим, що згенерував chart.
Chart завантажується з реєстру проєкту й використовується як є; сутність 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читає той самий ключinfra, що й передається chart, тож запис називає згенерований Secret, хоч як його назве сутність Release.whenробить запис чинним лише в цьому режимі. У режимі cert-manager chart не рендерить такого Secret; там умова хибна, а запис, чияwhen:хибна, відкидається ще до будь-якої перевірки. Одна сутність Recipe обслуговує обидва режими.
Решта chart і далі рендериться повністю, і лише відповідний документ вилучається з того, що записує збірка. Вилучати його тут правильно, бо Secret, який монтує pod контролера, належить оператору й створюється окремо. Поле вилучає документ; воно не перевіряє, чи існує деінде те, на що спирається решта виводу.
Створення прикладу
Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.
Запишіть приклад у нову теку, названу за ним:
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 заповнює lockfile кожної сутності Release під час збирання; lockfile-и та
відрендерений результат генеруються, а не постачаються. Розв’язання lockfile завантажує
чарт контролера з 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 виключив той, який чарт таки відрендерив. Натомість контролер монтує секрет, названий у сутності 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, яким є секрет 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. Два рендери контролера відрізняються, бо чарт
щоразу генерував інший ключ і сертифікат. Отримання (pull) також рендерить
сутність Release, щоб знайти зовнішні вхідні дані, які потрібно закріпити, і там стикається з тією самою зупинкою;
саме тому пропущені рядки отримання містять це речення вдруге. Файл
блокування все одно записується.
Зібрана без прапорця, та сама сутність Release завершується успішно. Її дерево містить ті документи чарта, які містить дерево сутності Release із власним сертифікатом, — за винятком визначень ресурсів, яких навчальний Recipe не виводить, — і ще один, 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]Зберіть її двічі, і два дерева відрізнятимуться саме цими трьома значеннями. Звичайна збірка рендерить кожен компонент один раз, тож записує той ключ, який згенерувала, і нічого не помічає; саме перевірка робить різницю видимою. Застосований, цей файл замінив би Secret, який створив оператор.
Зупинку описано в розділі
A provider rendered the same input twice and produced different output (Провайдер двічі відрендерив ті самі вхідні дані й отримав різний результат),
виправлення в якому називає два виходи, коли різниця — це значення, яке генерує чарт, що ви
використовуєте як джерело: передати значення через налаштування, яке пропонує чарт, або, якщо
згенерований документ сутність 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, чарт
назвав свій Secret ai-gateway-webhook-tls, і запис нічого не вилучив.
Кожен запис, що застосовується, мусить щось вилучити, і збірка зупиняється на записі,
який цього не робить, бо запис, що нічому не відповідає, — це твердження про джерело,
яке вже не є правдивим. Звичайна причина — оновлення джерела, яке перейменувало
документ. Перейменований документ тоді потрапляє у вихідні дані під новим ім’ям — саме
той документ, який запис мав не допустити, — і зупинка не дає йому
непомітно потрапити в постачання. У цій збірці Secret, згенерований чартом, і є таким
документом: запис було написано, щоб його вилучити, а називає він щось інше. Щоб
виправити запис, порівняйте його з тим, що джерело рендерить зараз: зберіть
без цього запису, як це робить release-negative-without-omits.yaml без
перевірки, і прочитайте ім’я з файлу, який записав чарт.
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 і
записати однакові файли, байт у байт, а дерево, якщо рахувати за типом
кожного відрендереного документа, має містити 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.Йому потрібне те саме, що й окремій збірці: каталог стандартної бібліотеки і мережа для chart. Він використовує бінарний файл, який визначає ./build-release.sh, тож його вибирає AGGREGA_BIN; аргументи після -- передаються кожній збірці. Він відмовляється запускатися, поки в цьому каталозі є dist/, бо порівнює дерева, які записують збірки, і сам не залишає жодного. Його код завершення — це весь вердикт, тож конвеєр може запускати його замість окремої збірки кожної сутності Release.
Де компілятор не інтерпретує
Компілятор не знає, що таке Secret, що контролер із ним робить і навіщо чарту його генерувати. Він обчислює шаблони запису так само, як обчислює будь-який шаблон сутності Recipe, передає тип і ім’я, до яких вони зводяться, провайдеру 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— збирає всі чотири й перевіряє кожен результат.