Перейти до вмісту
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/ цього робочого простору — навчальні варіанти тієї, що зі стандартної бібліотеки. Кожна бере той самий чарт того самого випуску і вибирає режим сертифіката за тим самим зіставленням: одна не має запису 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 контролера, належить оператору й створюється окремо. Поле вилучає документ; воно не перевіряє, чи існує деінде те, на що спирається решта виводу.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

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 заповнює 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-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 виключив той, який чарт таки відрендерив. Натомість контролер монтує секрет, названий у сутності 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, яким є секрет 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, який згенерував чарт:

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 (Провайдер двічі відрендерив ті самі вхідні дані й отримав різний результат), виправлення в якому називає два виходи, коли різниця — це значення, яке генерує чарт, що ви використовуєте як джерело: передати значення через налаштування, яке пропонує чарт, або, якщо згенерований документ сутність 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, цього скрипту не містить.

Terminal window
./check.sh

check.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=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, що контролер із ним робить і навіщо чарту його генерувати. Він обчислює шаблони запису так само, як обчислює будь-який шаблон сутності 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 — збирає всі чотири й перевіряє кожен результат.