Helm-Chart Provider
Провайдер helm-chart створює запакований парасольковий чарт Helm для кожного шляху збирання. Тоді як провайдер helm видає пласкі YAML-файли Kubernetes для безпосереднього використання в GitOps, helm-chart видає каркас чарта — парасольковий Chart.yaml + values.yaml і по одному підчарту на кожен вузол, що робить внесок, — який подальші інструменти можуть установити через helm install або включити до себе для подальшого налаштування під кожне середовище. Провайдер збирає результат окремо для кожної пари (path, provider): кожен вузол, прив’язаний до сутності Recipe для helm-chart, робить внесок у парасольковий чарт за обчисленим directory: межі, з’єднаним із subDirectory: окремого компонента. Дві межі, що обчислюються в той самий шлях, зливаються в один об’єднаний парасольковий чарт, який перелічує кожного учасника як залежність-підчарт.
Шаблони підчарта, скопійовані з вихідного чарта, несуть те, що написав їхній автор: значення syncWave: <integer> межі, helm.sh/hook-weight на хуку та мітки походження Aggrega потрапляють до них лише там, де їх записує сам чарт. Саме провайдер helm проставляє argocd.argoproj.io/sync-wave: "<N>", helm.sh/hook-weight: "<N>" і мітки походження на кожен ресурс, який рендерить. Артефакт, завантажений через $import:, який цей провайдер додає до підчарта, несе мітки походження й анотацію argocd.argoproj.io/sync-wave, але не helm.sh/hook-weight (див. «Правило вставлення artifacts:» нижче). ArgoCD читає анотацію sync-wave, а Helm читає вагу хука.
Ця сторінка — довідник з авторингу для провайдера helm-chart. Про розподіл між helm і helm-chart див. розділ Providers сторінки статусу; про міжпровайдерну модель композиції вхідних даних див. architecture/16-recipe-input-composition.md.
Підтримувані типи вхідних даних
Провайдер helm-chart приймає два види вхідних даних:
- Режим із джерелом. Recipe з
source: <chart-path>вказує на каталог Helm-чарту на диску. Чарт копіюється в структуру umbrella як підчарт дослівно, за винятком власногоnameчарту — див. «Ім’я чарту, яким володіє umbrella»; на рівні окремого вузла не виконується ні рендеринг, ні шаблонізація. Роль Aggrega — композиція (збирання umbrella з вузлів межі), а не обчислення шаблонів. - Режим
artifacts:із завантаженням через$import:. Recipe із записамиartifacts:, кожен з яких записано як$import:, оголошує додаткові файли шаблонів, які провайдер helm-chart вставляє в каталогtemplates/підчарту після копіювання вихідного чарту. Кожен файл попередньо обробляється як шаблон із контекстом шаблонів Aggrega з розділювачами[[ ]](див. «artifacts:injection rule» нижче), тож будь-які шаблонні конструкції Helm{{ }}у тому самому файлі зберігаються до подальшого рендерингу черезhelm install.
Recipe, націлений на helm-chart, який оголошує workload:, відхиляється ще до рендерингу з тією самою відмовою, яку будь-який провайдер дає для неоголошеного ним виду вхідних даних: вона називає вид, який підтримує цей провайдер, і спрямовує автора до провайдера, що виконує синтез:
provider does not support the node’s input kind (node “api”). provider “helm-chart” does not support synthesized recipes (this provider supports: sourced); declare one of the supported input kinds, or target a provider that supports synthesized (провайдер не підтримує вид вхідних даних вузла (вузол «api»). Провайдер «helm-chart» не підтримує синтезовані recipes (цей провайдер підтримує: sourced); оголосіть один із підтримуваних видів вхідних даних або оберіть ціллю провайдер, що підтримує синтез)
Такий поділ навмисний: синтез робочих навантажень (перетворення абстрактного Workload на ресурси Kubernetes) — виключна відповідальність провайдера helm. Роль helm-chart — композиція umbrella та підчартів для чартів, які автор уже створив.
Recipe, націлений на helm-chart, може також оголошувати записи artifacts: із вбудованим вмістом (записи, значенням яких є блоковий скаляр, що містить тіло файлу безпосередньо в Recipe, а не посилання, завантажене через $import:). Запис із вбудованим вмістом розміщується в корені підчарту під заданим ключем — без префікса templates/ і без вставлення походження. Власні шаблони чарту читають такий окремий файл через .Files.Get / .Files.Glob Helm (канонічний шаблон ConfigMap-з-файлів), тож файл у корені чарту — це легітимна, повноцінна форма, а не помилка.
Обидві форми обчислюються з роздільниками Aggrega [[ ]] перед розміщенням, тож тіло будь-якої форми може читати контекст стовпів Recipe; {{ }} у будь-якому тілі залишається незмінним і стає директивою Helm під час подальшого helm install. Форми відрізняються тим, куди потрапляє файл і чи вливається в нього походження:
- Запис, завантажений через
$import:, — це файл шаблону: після обробки (див. «artifacts:injection rule» нижче) його вставляють у каталогtemplates/підчарту з об’єднаними даними про походження, тож Helm рендерить його як маніфест разом із власними шаблонами чарту. - Запис із вбудованим вмістом — це окремий файл даних: після обчислення він потрапляє в корінь чарту без змін відносно результату обчислення і без влитого походження, для використання через
.Files.
Правило впровадження artifacts:
Коли Recipe для helm-chart оголошує записи artifacts: через $import: для кожного запису, кожне значення $import: — це шлях до файлу шаблону, що розв’язується відносно власного каталогу Recipe (каталогу, який містить YAML сутності Recipe на диску). Провайдер:
- Зчитує вміст кожного файлу.
- Попередньо обробляє вміст як шаблон із роздільниками Aggrega
[[ ]]щодо контексту шаблонів сутності Recipe (того самого контексту, щодо якого обчислюєтьсяvaluesMapping:сутності Recipe).{{ }}усередині вмісту файлу залишаються без змін — вони стають директивами шаблонів Helm під часhelm install. - Записує кожен файл до
charts/<instance-id>/templates/<authored-key>під шляхом збирання umbrella-чарта, а файли пакета — вкладеними під цей ключ. Ключ, під яким записано запис, задає ім’я файлу; шлях$import:вибирає його вміст і нічого не додає до імені, тож структура каталогів у цьому шляху ніколи не потрапляє у вихідні дані.
Ключова деталь — дисципліна подвійних роздільників [[ ]] / {{ }}. Типовий файл артефакту, завантажений через $import:, може поєднувати інтерполяцію часу Aggrega (наприклад, [[ .values.image ]]) з інтерполяцією часу Helm (наприклад, {{ .Release.Namespace }}). Кожна пара роздільників спрацьовує на своїй фазі: Aggrega розв’язує [[ ]] під час компіляції, до того як файл буде розміщено; Helm розв’язує {{ }} під час встановлення, після постачання umbrella-чарта.
Збіги імен файлів між шаблонами вихідного чарта та артефактами, впровадженими через $import:, спричиняють CATALOG_ERROR — діагностика називає конфліктний вихідний шлях, наприклад templates/cm.yaml, і два види вхідних даних, що його створили. Автори усувають збіг, перейменувавши ключ артефакту або власний шаблон чарта.
Набір ключів source:
Поле source: провайдера helm-chart називає чарт і приймає обидві форми, яких набуває поле source:, і читає їх саме так, як описує набір ключів source: провайдера helm: простий рядок шляху у файловій системі та структурований об’єкт, чий url: містить розташування. Якщо url: називає шлях у файловій системі, нічого не завантажується, і чарт читається з диска; якщо він містить схему транспорту — наприклад, oci://… разом із kind: helm-oci-chart — aggrega pull завантажує й закріплює чарт, а збірка копіює його з кешу в umbrella як підчарт на тих самих умовах, що й чарт, прочитаний з диска.
spec: capability: helm-chart source: ./charts/api-server # filesystem path to a chart directory valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}Чарт за шляхом джерела повинен містити коректний Chart.yaml у своєму корені; за його відсутності ще до копіювання виникає зрозуміла помилка. Структура каталогів чарту під час копіювання зберігається — templates/, values.yaml, Chart.yaml та будь-які інші файли присутні в каталозі підчарту після композиції. Кожен файл надходить із тими байтами, які ви написали, аж до коментарів, порядку ключів і лапок; єдиний виняток — поле name власного Chart.yaml чарту, яке встановлює umbrella, — див. «Назва чарту, якою володіє umbrella».
Обидва способи не назвати чарт відхиляються, і ці дві відмови походять
з різних місць — це варто знати, бо лише одна з них змінюється, якщо ви змінюєте
capability. source:, який присутній, але нічого не оголошує, відхиляє
компілятор ще до запуску будь-якого провайдера, тож результат однаковий, хоч би яку
capability називала сутність Recipe; діагностика радить пропустити поле для
режиму без джерела або вказати непорожній шлях. Повний пропуск source: —
допустиме авторство: саме так Recipe запитує режим без джерела, — а відхиляється
він тут тому, що helm-chart оголошує лише вид вхідних даних із джерелом, тож компілятор
відхиляє цю комбінацію з тим самим повідомленням, яке він дає для будь-якої capability, від якої
запитано вид вхідних даних, якого вона не оголошує. Власним для helm-chart є оголошення, а не
власна відмова: для ресурсів Kubernetes, згенерованих із блоку workload:,
використовуйте натомість capability helm.
Recipe, що оголошує omits:, відхиляється. Ключ omits:
вилучає зі збірки документи, які рендерить джерело, а цей провайдер не рендерить жодного
документа під час збірки: він копіює чарт в umbrella, а шаблони чарту
рендеряться під час встановлення umbrella. Коли нічого не відрендерено, немає
чого вилучати, тож цей провайдер не оголошує, що підтримує цей ключ, і
сутність Recipe чи FeatureRecipe, що його оголошує, відхиляється ще до будь-якого копіювання — див.
The provider does not support omits (Провайдер не підтримує omits).
Для чарту, який ви зберігаєте поруч із Recipe, рядок у .aggregaignore там натомість вилучає
файл чарту, починаючи з наступного закріплення Recipe; для завантаженого
чарту, з виводу якого має зникнути документ, рендерте його через провайдер helm, який
підтримує цей ключ.
Композиція за шляхом — форма umbrella-чарта
Для кожного шляху збирання провайдер працює у дві фази:
- Копіювання для кожного учасника. Для кожного вузла, прив’язаного до helm-chart Recipe, провайдер копіює повне дерево каталогів вихідного чарта у слот під-чарта. Файли потрапляють пласко в мапу виводу кожного учасника; збирач називає
chartsпідкаталогом, у якому розміщуються його учасники, а оркестратор під час збирання umbrella-чарта дає кожному учаснику там окремий каталог —charts/<instance_id>/для компонента. Прикріплення Feature теж є учасником — чи постачає воно чарт, чи рендерить маніфести через провайдер helm — і отримує каталог поруч із каталогом компонента, а не всередині нього; див. «Куди потрапляє чарт прикріплення». - Збирання umbrella-чарта для кожної пари
(path, provider). Щойно всі копіювання вузлів для шляху завершено, збирач створює umbrella-файлиChart.yaml+values.yamlу корені шляху збирання. Umbrella-чарт оголошує по одній залежності на кожен вузол-учасник і спрямовує значення кожного вузла в підблоки з ключами за instance id. Коли шлях збирання отримує учасників із кількох меж (меж зі спільнимdirectory:), кожен учасник потрапляє як залежність в один і той самий umbrella-чарт.
Umbrella-файл Chart.yaml має таку форму:
apiVersion: v2name: <effective-chart-name> # see "Chart-name resolution" belowversion: 0.1.0description: Aggrega umbrella chart for boundary "<assembly-path>"dependencies: - name: <encoded-instance-id> # the name the placed sub-chart carries version: <user-chart-version> # from the source chart's Chart.yaml alias: <encoded-instance-id> # see "How a name is derived" below repository: file://charts/<instance_id> # the sub-chart's own directoryВизначення назви чарта
Назва name umbrella-чарта визначається через каскад анотацій меж. Ефективна анотація aggrega.ai/chart-name кожної межі-учасника (значення, визначене каскадом під час підйому деревом меж) задає назву umbrella-чарта; визначене значення кодується для позиції назви чарта так само, як будь-яка інша ідентичність, тож значення, що містить лише літери, цифри, підкреслення та дефіси, які зберігає наведене нижче правило, потрапляє в чарт дослівно. Коли шлях збирання отримує учасників із кількох меж, ефективна aggrega.ai/chart-name кожного учасника ПОВИННА визначатися в одне й те саме значення; розбіжності зупиняють збирання з діагностикою, що називає конфліктні значення та межі-учасники.
Каскад природно розв’язує напругу з принципом DRY: оголосіть aggrega.ai/chart-name один раз на батьківській межі, і дочірні межі успадкують її через каскад; сусідні межі без спільного батька мають явно оголосити однакові значення. Межі, у каскаді яких aggrega.ai/chart-name не оголошено ніде, повертаються до назви aggregate та шляху збирання — вихідного каталогу umbrella-чарта в dist/, наприклад boundaries/data/helm-chart, — кожен з яких закодовано й об’єднано, як описано нижче.
name кожного запису залежності — це назва, яку має розміщений під-чарт, — власна закодована ідентичність екземпляра компонента, те саме значення, що й alias, — з причин, описаних у «Назва чарта, якою володіє umbrella-чарт». Його version і далі є версією з власного Chart.yaml вихідного чарта. Псевдонім обмежує значення під-чарта областю values.yaml.<alias>.*, що відповідає домовленості Helm щодо значень umbrella-чарта, тож значення кожного екземпляра правильно поширюються під час встановлення umbrella-чарта.
Каталог під-чарта компонента зберігає instance_id точно так, як його написано, тож charts/<instance_id>/ — це місце, куди потрапляють його файли, і те, на що вказує repository залежності. Тому два екземпляри одного вихідного чарта співіснують без колізії у файловій системі, і кожен зберігає власний блок значень під власним псевдонімом.
name залежності та її repository — різні рядки, і так задумано. name — це те, що ОГОЛОШУЄ чарт у цьому розташуванні, бо Helm прив’язує залежність до дочірнього чарта за власною оголошеною назвою дочірнього чарта; repository — це місце, де лежить цей чарт. Для компонента вони випадково збігаються, оскільки обидва походять від того самого instance id. Для прикріплення Feature вони відрізняються — оголошена назва містить складену ідентичність прикріплення, а каталог містить дві його координати, об’єднані разом, — тож якщо читати одне як інше, буде названо те, чого не існує.
Куди потрапляє чарт прикріплення
Прикріплення Feature, що постачає чарт, отримує власний каталог поруч із компонентом, до якого його прикріплено, на один рівень під charts/:
charts/├── api/ # the component's own chart├── api--guardrail/ # a Feature attached to `api` under `guardrail`└── api--audit/ # a second Feature attached to the same componentFeature, прикріплена до межі, а не до компонента, не має компонента-хоста, який можна назвати, тому її каталогом є лише назва її екземпляра: charts/aux/.
Чому поруч, а не всередині. Helm знаходить дочірній чарт у charts/* — на одному рівні, без рекурсивного обходу. Чарт, розміщений глибше, не є дочірнім для жодного чарта; це дані всередині каталогу іншого дочірнього чарта, доступні лише через .Files. Тож чарт, розміщений у власному каталозі чарта компонента, було б скопійовано у вивід, збирання завершилося б успішно, але жоден його ресурс не потрапив би в те, що ви розгортаєте, — і ніщо про це не повідомило б. Саме розміщення кожного учасника в окремому каталозі верхнього рівня забезпечує рендеринг ресурсів прикріплення.
Umbrella-чарт також оголошує прикріплення однією зі своїх залежностей. Потрібні обидві половини: чарт, присутній у charts/ і відсутній у dependencies:, є помилкою lint, а чарт, оголошений у dependencies: без відповідного дочірнього чарта, призводить до того, що umbrella-чарт відмовляється завантажуватися.
Дві координати об’єднуються, а не конкатенуються. Назва каталогу складається з хоста та екземпляра за тим самим правилом екранування, описаним нижче, яке застосовується до кожної координати перед їх об’єднанням через --. Пряме з’єднання через -- було б неоднозначним: хост із назвою a--b з екземпляром c і хост a з екземпляром b--c потрапили б в один каталог. Попереднє кодування кожної координати розділяє їх, тож написане -- всередині координати відображається як -zh-.
Що допускає назва каталогу. Літери ASCII обох регістрів, цифри, крапка та підкреслення проходять так, як ви їх написали, тож API--aux і web.api--aux читаються очікувано. Написаний вами дефіс зберігається скрізь, де наступний символ — один із цих, тож web-api--aux не змінюється; подвійний дефіс екранується, бо ця пара є з’єднанням. Усе інше екранується за тим самим правилом, що й назва чарта. Межу набору проведено саме так, бо ці назви каталогів є водночас шляхами на диску та розташуванням, на яке вказує покажчик file:// залежності, а символ, прийнятний у назві файлу, може обрізати URL або змінити його декодування.
Значення слідують за оголошеною назвою, а не за каталогом. Значення дочірнього чарта обмежено назвою, яку оголошує цей чарт, тож значення для наведеного вище чарта адресуються за оголошеною назвою api--guardrail — cfr-zh-api-zh-guardrail, — а не за його каталогом.
Цей ключ ви ніколи не пишете самі. Ви пишете значення на прикріпленні, а values.yaml umbrella-чарта складається за вас, і блок уже стоїть за адресою, за якою адресується розміщений чарт. Для Feature, прикріпленої до компонента, це values:, які ви оголошуєте на прикріпленні й які читає власний valuesMapping: сутності FeatureRecipe; для Feature, прикріпленої до межі, це infra:, який ви там оголошуєте, оскільки Feature, прикріплена до межі, не має опори значень компонента. У будь-якому разі мапа, у яку перетворюється valuesMapping:, стає власним блоком прикріплення в umbrella-чарті:
# the umbrella's values.yaml, composed for youapi: # the component's own chart replicaCount: 3cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought auditEndpoint: "https://audit.internal"Це єдиний шлях цих значень. Чарт, який приносить Feature, надходить із файлами в тому вигляді, у якому їх написав автор, — за винятком єдиного поля маніфесту, описаного в «Назва чарта, якою володіє umbrella-чарт», — тож ніщо не записує ваші значення в цей чарт, і саме блок umbrella-чарта їх постачає. Чарт, блок якого так і не надійшов, не є зламаним: він рендерить стандартні значення, які постачає його власний values.yaml, і повідомляє про успіх, тож задайте стандартному значенню помітне значення, якщо хочете бачити різницю під час написання.
Прикріплення, чий FeatureRecipe рендериться через провайдер helm
FeatureRecipe з capability helm, прикріплений до компонента на цій цілі, приносить готові маніфести Kubernetes, а не чарт. Вони потрапляють до власного каталогу прикріплення точно такими, якими їх відрендерив провайдер helm, і провайдер дає цьому каталогу дві речі, що роблять його чартом, який встановлює Helm: мінімальний Chart.yaml, що оголошує власне ім’я прикріплення з версією 0.1.0, і один шаблон, templates/rendered.yaml, який виводить кожен відрендерений файл YAML через .Files.Get Helm за його іменем:
charts/api--guardrail/├── Chart.yaml # apiVersion: v2, name: cfr-zh-api-zh-guardrail, version: 0.1.0├── guardrail-config.yaml # the manifest the helm provider rendered└── templates/ └── rendered.yaml # {{ .Files.Get "guardrail-config.yaml" }}Оголошене ім’я — те саме, яке оголосив би чарт, постачений тим самим прикріпленням, тож запис залежності umbrella-чарта та його блок значень адресуються точно так, як описано вище. .Files.Get повертає байти файлу як є, не обчислюючи їх удруге, тож маніфест із літеральними фігурними дужками шаблонів — {{ $labels.instance }} правила сповіщення, запит дашборда — встановлюється з ними незмінними. Його значення було розв’язано в ці маніфести, коли їх рендерив провайдер helm, тож блок, який values.yaml umbrella-чарта несе під цим ім’ям, ніщо не читає.
Назва чарта, якою володіє umbrella-чарт
Єдине, що Aggrega змінює всередині постаченого вами чарта, — це власне поле name цього чарта. У Chart.yaml розміщеного чарта для name встановлюється закодована ідентичність того, що надало цей чарт.
Для компонента це власна ідентичність екземпляра компонента — те саме значення, що й alias залежності, — і запис залежності umbrella-чарта також називає це значення, тож обидві сторони завжди збігаються.
Чарт, який приносить прикріплення Feature, є повноцінним учасником і оголошує власну ідентичність, а не повторює ідентичність компонента, до якого його прикріплено. Ця ідентичність складається з двох написаних вами речей — компонента, що містить прикріплення, і назви, під якою прикріплено Feature, — після короткого префікса, який позначає її як ідентичність прикріплення, а не компонента; складене значення потім записується для позиції назви чарта через наведене нижче виведення так само, як будь-яка інша ідентичність.
Тож прикріплення Feature, що постачає чарт, до компонента з назвою api під назвою guardrail розміщує чарт, який оголошує cfr-zh-api-zh-guardrail, тоді як власний чарт цього компонента й далі оголошує api. Це два окремі учасники, і кожен оголошує власну назву, а не обидва — назву хоста.
Більше нічого в чарті не змінюється. Кожен інший файл надходить байт у байт таким, яким ви його написали, а всередині Chart.yaml кожне інше поле, кожен коментар, порядок ключів і лапки залишаються точно такими, як написано. Ключ, вкладений деінде в маніфесті, який теж випадково називається name, — наприклад, ім’я супровідника, — залишається без змін.
Навіщо umbrella-чарту це поле. name чарта — це те, до чого Helm прив’язує залежність umbrella-чарта. Його пише автор чарта, а для чарта, отриманого з upstream, це не та людина, яка його розгортає, — тож два компоненти в одному шляху збирання цілком можуть постачати чарти, маніфести яких оголошують однакову назву. Якби обидва під-чарти зберегли цю спільну назву, обидві залежності umbrella-чарта визначалися б у той із двох, який Helm завантажив першим: чарт одного компонента рендерився б двічі, а іншого — жодного разу, хоча значення кожного компонента все одно надходили б, тож вивід виглядав би повним, але був би хибним. Виведення назви розміщеного чарта з екземпляра компонента повністю усуває спільну назву, тому нічого не доводиться відхиляти — зокрема у двох випадках, які не мають іншого рішення: постачання того самого чарта для двох компонентів, де назва спільна за побудовою, і постачання чарта, який ви не писали, назву якого ви не можете змінити.
Єдине, що ви можете помітити. Шаблон, який читає назву власного чарта, — {{ .Chart.Name }} і все, що з неї виведено, як-от поширена ідіома іменування ресурсів {{ .Chart.Name }}-{{ .Release.Name }}, — читає закодовану ідентичність екземпляра, а не назву, написану в Chart.yaml вихідного чарта. Саме це такий шаблон читав і до встановлення поля, бо Helm повідомляє під-чарт під псевдонімом, за яким його прив’язує батьківський чарт; встановлення поля лише узгоджує файл на диску з тим, що рендеринг уже давав. Тож у наведеному нижче прикладі шаблон у під-чарті api-east читає api-east.
Якщо назва ресурсу має містити написану автором назву чарта, помістіть цю назву в values.yaml чарта й читайте її звідти — значення належить вам, і Aggrega його не змінює.
Як виводиться назва
Назва чарта Helm і псевдонім залежності Helm приймають вужчий набір символів, ніж може містити назва aggregate, шлях межі чи instance_id. Замість того щоб замінювати символ, який ціль не приймає, виведення записує його явно, тож дві ідентичності, що відрізняються лише пунктуацією, завжди дають дві назви — і значення, записане під одним псевдонімом, може потрапити лише в той під-чарт, який цей псевдонім називає.
- Літера, цифра та підкреслення передаються точно так, як написано.
- Дефіс зберігається як написано скрізь, де наступний символ передається напряму й не є малою
z. Дефіс, за яким іде малаz, відкриває екранування, тож написаний дефіс у цій позиції сам записується явно —api-zoneстаєapi-zhzone, і саме це дозволяє прочитати будь-яку назву назад без здогадок. - Кожен інший символ записується як
-z, за яким іде літера, що його називає:dдля крапки,sдля роздільника шляху,hдля дефіса, який наведене вище правило не зберігає. Усе інше записується якxі шестизначна шістнадцяткова кодова точка символу, а байт, який не починає жодного символу, — якbі його власне двоцифрове значення, тож назва, яка не є коректним текстом, однаково записується розрізнювано, а не зливається. - Порожнє значення записується як
-ze, чого не може дати жодне непорожнє значення. - Там, де дві ідентичності складають одну назву чарта — назва aggregate, що уточнює шлях збирання, — вони об’єднуються через
--. Одна закодована ідентичність ніколи не містить цієї пари, тож об’єднана назва однозначно показує, яка ідентичність яка.
Тож instance_id data.main-db дає псевдонім data-zdmain-db, а aggregate fullstack-app зі шляхом збирання boundaries/data/helm-chart дає назву чарта fullstack-app--boundaries-zsdata-zshelm-chart. Ідентичні вхідні дані завжди дають ідентичну назву.
Umbrella-файл values.yaml має ключі за псевдонімами:
api-server: # sub-chart alias = encoded instance_id image: "registry/api-server:v2" replicaCount: 3billing-svc: image: "registry/billing:v1" replicaCount: 2Коли valuesMapping: під-чарта обчислюється відносно його контексту шаблонів, отримана мапа значень автоматично заповнює цей підблок із ключем за псевдонімом. Це стосується кожного учасника umbrella-чарта, а не лише компонентів: прикріплення Feature, що постачає чарт, є повноцінним учасником, тож valuesMapping: його FeatureRecipe заповнює власний блок із ключем за назвою, яку оголошує його розміщений чарт. Див. «Куди потрапляє чарт прикріплення».
Ключ, який valuesMapping: встановлює в null, записується в його блок як null. Під час встановлення з Helm 4 null у власному values.yaml umbrella-чарта видаляє стандартне значення під-чарта для цього ключа лише тоді, коли встановлення також постачає значення для цього під-чарта; встановлення, яке не постачає для нього жодних значень, відкидає null, і стандартне значення під-чарта залишається. null у значеннях, переданих helm install, видаляє стандартне значення в будь-якому разі.
Особливості цього Provider
Chart.yamlпідчарту є обов’язковим. Операція копіювання вимагає наявностіChart.yamlу корені вихідного шляху. Його відсутність зупиняє збірку ще до запуску кроку umbrella.nameрозміщеного чарту належить umbrella. Йому присвоюється закодована ідентичність того, хто додав чарт, — власна ідентичність екземпляра компонента або, для чарту, який приносить прикріплення сутності Feature, власна ідентичність цього прикріплення, — і це єдине, що Aggrega змінює всередині вендореного чарту. Див. «Назва чарту, якою володіє umbrella».- Вихідний чарт має оголошувати версію та назву. Версія в записі залежності — це та, яку оголошує власний
Chart.yamlвихідного чарту, тож чарт без оголошеної версії зупиняє збірку, а не отримує версію автоматично: залежність, закріплена за версією, якої підчарт не має, залишила б значення umbrella для окремих екземплярів неспроможними до нього дістатися. Чарт, чийChart.yamlне оголошує назви, містить більше одного документа YAML або не розбирається, зупиняє збірку з тієї самої причини: umbrella не може скомпонувати підчарт, який не може прочитати. - Закодовані псевдоніми та назви чартів. instance_id, назва агрегату чи шлях межі, що містить символ, якого не приймає назва чарту Helm або псевдонім залежності, з’являється в згенерованому umbrella в закодованому вигляді, згідно з розділом «Як виводиться назва» вище. Ідентичність, складена лише з літер, цифр, підкреслень і дефісів, які зберігає виведення, з’являється точно так, як її написано.
- Вказівник репозиторію
file://. Записи залежностей umbrella використовують вказівник репозиторіюfile://, що називає власний каталог дочірнього чарту:file://charts/<instance_id>для компонента та власний каталог прикріплення для чарту, який приносить сутність Feature. Це домовленість локальної файлової системи для дочірніх чартів у дереві, яка дає змогуhelm dependency buildрозв’язати umbrella без звернень до зовнішнього реєстру. Вказівник називає розташування, а не оголошену назву чарту; для прикріплення вони відрізняються, і самеhelm dependency buildє кроком, що відхиляє вказівник на каталог, якого не існує. - Жодного рендерингу шаблонів на рівні helm-chart. Provider не викликає конвеєр рендерингу Helm SDK; він копіює та компонує. Авторам, яким потрібні попередньо згенеровані пласкі маніфести, слід натомість використовувати режим sourced провайдера helm.
Робочий приклад
Межа з двома вузлами, кожен з яких прив’язаний до helm-chart Recipe, що вказує на той самий вихідний чарт:
# Recipe — used by both `api-east` and `api-west` instancesapiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api-server-helmchart version: 1.0.0spec: capability: helm-chart implements: core/api-server source: ./charts/api-server valuesMapping: | image: "{{ .values.image }}" replicaCount: {{ optional .infra `replicas` 2 }}Після компонування обчислений шлях збирання межі (типово dist/<boundary-directory>/<capability>/, оскільки subDirectory: типово має значення {{ .capability }}) містить:
dist/<boundary-directory>/helm-chart/├── Chart.yaml # umbrella; lists api-east and api-west as dependencies├── values.yaml # alias-keyed: api-east + api-west values blocks└── charts/ ├── api-east/ # ./charts/api-server, name: api-east │ ├── Chart.yaml │ ├── values.yaml │ └── templates/ │ └── deployment.yaml └── api-west/ # ./charts/api-server, name: api-west ├── Chart.yaml ├── values.yaml └── templates/ └── deployment.yamlОбидва субчарти є копіями одного вихідного чарту, і кожен містить у своєму Chart.yaml ім’я власного екземпляра — саме це дає змогу вендорити один чарт двічі в одному umbrella-чарті. Усе інше в обох копіях ідентичне вихідному чарту.
Команда helm install <release-name> dist/<boundary-directory>/helm-chart для цієї структури встановлює обидва екземпляри як один реліз Helm, а значення umbrella-чарту, ключами яких є псевдоніми, керують шаблонами кожного субчарту.
Перехресні посилання
providers/helm.md— споріднений провайдер, який видає плаский відрендерений Kubernetes YAML замість каркаса чарту; виконує синтез робочих навантажень.entities/recipe.md— засоби створення сутності Recipe і три типи вхідних даних.entities/release.md— семантика меж сутності Release і вихідні каталоги для кожної межі.architecture/16-recipe-input-composition.md— матриця можливостей Provider для всіх провайдерів (Provider Capability Matrix).10-status.md#providers— поточна класифікація готовності.