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

Provider для Helm-Chart

Провайдер helm-chart создаёт упакованный зонтичный Helm-чарт для каждого пути сборки. Если провайдер helm выдаёт плоский Kubernetes YAML для непосредственного использования в 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:» ниже), поэтому любая шаблонизация 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:» ниже) он внедряется в каталог templates/ подчарта с объединёнными сведениями о происхождении, поэтому Helm рендерит его как манифест наряду с собственными шаблонами чарта.
  • Запись со встроенным содержимым — это отдельный файл данных: после вычисления он попадает в корень чарта без изменений относительно результата вычисления и без объединённых сведений о происхождении, для использования через .Files.

Правило внедрения artifacts:

Когда Recipe для helm-chart объявляет записи artifacts: через $import: в каждой записи, каждое значение $import: — это путь к файлу шаблона, который разрешается относительно собственного каталога Recipe (каталога, содержащего YAML-файл Recipe на диске). Провайдер:

  1. Читает содержимое каждого файла.
  2. Предварительно обрабатывает содержимое как шаблон с разделителями Aggrega [[ ]] в контексте шаблонов сущности Recipe (том же контексте, в котором вычисляется valuesMapping: сущности Recipe). {{ }} внутри содержимого файла остаются нетронутыми — они становятся директивами шаблонов Helm во время helm install.
  3. Записывает каждый файл в charts/<instance-id>/templates/<authored-key> под путём сборки зонтичного чарта; файлы пакета вкладываются под этот ключ. Ключ, под которым записана запись, задаёт имя файла; путь $import: выбирает его содержимое и никак не влияет на имя, поэтому структура каталогов внутри этого пути никогда не попадает в выходные данные.

Ключевая деталь — дисциплина двух пар разделителей [[ ]] / {{ }}. Типичный файл артефакта, загружаемый через $import:, может сочетать интерполяцию на этапе Aggrega (например, [[ .values.image ]]) с интерполяцией на этапе Helm (например, {{ .Release.Namespace }}). Каждая пара разделителей срабатывает на своём этапе: Aggrega разрешает [[ ]] во время компиляции, до того как файл будет размещён; Helm разрешает {{ }} во время установки, после поставки зонтичного чарта.

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

Композиция по путям — форма зонтичного чарта

Провайдер работает в две фазы для каждого пути сборки:

  1. Копирование для каждого участника. Для каждого узла, привязанного к сущности Recipe helm-chart, провайдер копирует полное дерево каталогов исходного чарта в слот подчарта. Файлы попадают плоско в карту вывода участника; сборщик называет charts подкаталогом, в котором размещаются его участники, а оркестратор при сборке зонтичного чарта выделяет там каждому участнику собственный каталог — charts/<instance_id>/ для компонента. Привязка сущности Feature тоже является участником — поставляет ли она чарт или отрисовывает манифесты через провайдер helm — и получает каталог рядом с каталогом компонента, а не внутри него; см. «Куда попадает чарт привязки».
  2. Сборка зонтичного чарта для каждой пары (path, provider). Когда все копирования по узлам для пути завершены, сборщик создаёт зонтичные Chart.yaml + values.yaml в корне пути сборки. Зонтичный чарт объявляет по одной зависимости на каждый участвующий узел и направляет значения каждого узла в подблоки с ключами по идентификатору экземпляра. Когда путь сборки получает участников более чем от одной границы (границы с общим directory:), каждый участник становится зависимостью в одном и том же зонтичном чарте.

Зонтичный Chart.yaml имеет следующую форму:

apiVersion: v2
name: <effective-chart-name> # see "Chart-name resolution" below
version: 0.1.0
description: 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 зонтичного чарта разрешается через каскад аннотаций границ. Эффективная аннотация aggrega.ai/chart-name каждой участвующей границы (значение, разрешённое каскадом при подъёме по дереву границ) определяет имя зонтичного чарта; разрешённое значение кодируется для позиции имени чарта точно так же, как любая другая идентичность, поэтому значение, содержащее только буквы, цифры, подчёркивания и дефисы, которые сохраняет описанное ниже правило, попадает в чарт без изменений. Когда путь сборки получает участников более чем от одной границы, эффективная aggrega.ai/chart-name каждого участника ДОЛЖНА разрешаться в одно и то же значение; при несовпадении сборка останавливается с диагностикой, называющей конфликтующие значения и участвующие границы.

Каскад естественно снимает противоречие с принципом DRY: объявите aggrega.ai/chart-name один раз на родительской границе, и дочерние границы унаследуют его через каскад; соседние границы без общего родителя должны явно объявить совпадающие значения. Границы, у которых aggrega.ai/chart-name не объявлена нигде в каскаде, используют имя агрегата и путь сборки — выходной каталог зонтичного чарта в dist/, например boundaries/data/helm-chart, — каждое из которых кодируется и соединяется, как описано ниже.

Поле name каждой записи зависимости — это имя, которое несёт размещённый подчарт: собственная закодированная идентичность экземпляра компонента, то же значение, что и alias, — по причинам, изложенным в «Имя чарта, которым владеет зонтичный чарт». Его version по-прежнему берётся из собственного Chart.yaml исходного чарта. Alias ограничивает область значений подчарта ключом values.yaml.<alias>.* в соответствии с соглашением Helm о значениях зонтичного чарта, чтобы значения каждого экземпляра правильно передавались при установке зонтичного чарта.

Каталог подчарта компонента сохраняет instance_id точно в том виде, в каком он написан, поэтому charts/<instance_id>/ — это место, куда попадают его файлы и на которое указывает repository зависимости. Поэтому два экземпляра одного исходного чарта сосуществуют без коллизии в файловой системе, и у каждого остаётся собственный блок значений под собственным alias.

name и repository зависимости — разные строки, и так задумано. name — это то, что ОБЪЯВЛЯЕТ чарт в этом месте, потому что Helm привязывает зависимость к дочернему чарту по собственному объявленному имени дочернего чарта; repository — это место, где находится чарт. Для компонента они совпадают, поскольку оба выводятся из одного идентификатора экземпляра. Для привязки сущности 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 component

У сущности Feature, привязанной к границе, а не к компоненту, нет компонента-хоста, который можно назвать, поэтому её каталог — только её имя экземпляра: charts/aux/.

Почему рядом, а не внутри. Helm находит дочерний чарт в charts/* — на один уровень, без рекурсивного обхода. Чарт, размещённый глубже, ничьим дочерним чартом не является; это данные внутри каталога другого дочернего чарта, доступные только через .Files. Поэтому чарт, размещённый внутри собственного каталога чарта компонента, был бы скопирован в вывод, сборка прошла бы успешно, но ни один из его ресурсов не попал бы в развёртывание — и ничто бы об этом не сообщило. Именно размещение каждого участника в собственном каталоге верхнего уровня обеспечивает рендеринг ресурсов привязки.

Зонтичный чарт также объявляет привязку одной из своих зависимостей. Нужны обе половины: чарт, присутствующий в charts/, но отсутствующий в dependencies:, — ошибка lint, а чарт, объявленный в dependencies: без соответствующего дочернего чарта, приводит к тому, что зонтичный чарт не загружается.

Две координаты соединяются, а не склеиваются. Имя каталога составляется из хоста и экземпляра по тому же правилу экранирования, описанному ниже, которое применяется к каждой координате перед их соединением через --. Прямая склейка через -- была бы неоднозначной: хост с именем 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 зонтичного чарта составляется за вас, и блок уже находится по адресу, по которому адресуется размещённый чарт. Для сущности Feature, привязанной к компоненту, это values:, которые вы объявляете в привязке и которые читает собственный valuesMapping: сущности FeatureRecipe; для сущности Feature, привязанной к границе, это infra:, которое вы объявляете там, поскольку у привязанной к границе сущности Feature нет опоры значений компонента. В любом случае карта, в которую разрешается valuesMapping:, становится собственным блоком привязки в зонтичном чарте:

# the umbrella's values.yaml, composed for you
api: # the component's own chart
replicaCount: 3
cfr-zh-api-zh-guardrail: # the chart the Feature attached under `guardrail` brought
auditEndpoint: "https://audit.internal"

Это единственный путь этих значений. Чарт, который приносит сущность Feature, поступает с файлами в том виде, в каком их написал автор, — за исключением единственного поля манифеста, описанного в «Имя чарта, которым владеет зонтичный чарт», — поэтому ничто не записывает ваши значения в этот чарт, и их поставляет блок зонтичного чарта. Чарт, чей блок так и не пришёл, не является сломанным: он рендерит значения по умолчанию из собственного 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" }}

Объявленное имя — то же, которое объявил бы чарт, поставленный той же привязкой, поэтому запись зависимости зонтичного чарта и его блок значений адресуются точно так, как описано выше. .Files.Get возвращает байты файла как есть, не вычисляя их повторно, поэтому манифест с литеральными фигурными скобками шаблонов — {{ $labels.instance }} в правиле оповещения, запрос дашборда — устанавливается с ними нетронутыми. Его значения были разрешены в эти манифесты, когда их отрисовывал провайдер helm, поэтому блок, который values.yaml зонтичного чарта несёт под этим именем, ничем не читается.

Имя чарта, которым владеет 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 допускают более узкий набор символов, чем может содержать имя агрегата, путь границы или instance_id. Вместо того чтобы подменять символ, который цель не принимает, выведение выписывает его, поэтому две идентичности, различающиеся только пунктуацией, всегда дают два имени — а значение, записанное под одним псевдонимом, может попасть только в подчарт, который этот псевдоним называет.

  • Буква, цифра и подчёркивание переносятся точно так, как написаны.
  • Дефис сохраняется как написан везде, где следующий за ним символ переносится напрямую и не является строчной z. Дефис, за которым следует строчная z, открывает экранирование, поэтому написанный в такой позиции дефис сам выписывается — api-zone превращается в api-zhzone, что и позволяет прочитать любое имя обратно без догадок.
  • Любой другой символ записывается как -z и буква, обозначающая его: d для точки, s для разделителя пути, h для дефиса, который правило выше не сохраняет. Всё остальное записывается как x и шестизначная шестнадцатеричная кодовая точка символа, а байт, который не начинает ни одного символа, — как b и его собственное двузначное значение, так что имя, не являющееся допустимым текстом, всё равно выписывается различимо, а не схлопывается.
  • Пустое значение записывается как -ze, чего не может дать ни одно непустое значение.
  • Там, где две идентичности составляют одно имя чарта — имя агрегата, уточняющее путь сборки, — они соединяются через --. Одна закодированная идентичность никогда не содержит эту пару, поэтому соединённое имя однозначно показывает, какая идентичность где.

Так, instance_id data.main-db даёт псевдоним data-zdmain-db, а агрегат fullstack-app с путём сборки boundaries/data/helm-chart даёт имя чарта fullstack-app--boundaries-zsdata-zshelm-chart. Одинаковый ввод всегда даёт одинаковое имя.

values.yaml umbrella индексируется по псевдониму:

api-server: # sub-chart alias = encoded instance_id
image: "registry/api-server:v2"
replicaCount: 3
billing-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. Провайдер не вызывает конвейер отрисовки Helm SDK; он копирует и компонует. Авторам, которым нужны заранее отрисованные плоские манифесты, следует вместо этого использовать режим sourced провайдера helm.

Рабочий пример

Граница из двух узлов, каждый из которых привязан к сущности Recipe типа helm-chart, указывающей на один и тот же исходный чарт:

# Recipe — used by both `api-east` and `api-west` instances
apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: api-server-helmchart
version: 1.0.0
spec:
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 имя своего экземпляра — именно это позволяет включить один чарт дважды в один зонтичный чарт. Всё остальное в обеих копиях идентично исходнику.

Команда helm install <release-name> dist/<boundary-directory>/helm-chart для этой структуры устанавливает оба экземпляра как один релиз Helm, причём значения зонтичного чарта, ключами которых служат псевдонимы, управляют шаблонами каждого подчарта.

Перекрёстные ссылки

  • 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 — текущая классификация готовности.