Сущности по ролям
У каждого вида сущностей есть роль, которая обычно его создаёт. Эта страница — полная карта: обращайтесь к ней, когда вы знаете свою задачу, но ещё не знаете, к какому файлу она относится. Распределение ролей — это рекомендация, а не ограничение, которое проверяет компилятор (см. Персоны); оно указывает, кто обычно владеет видом сущностей в хорошо структурированной конфигурации.
Карта вкратце
| Роль | Виды сущностей | Задача |
|---|---|---|
| Разработчик | Aggregate | Намерение приложения: что представляет собой приложение и что ему нужно |
| Архитектор платформы | Component, Feature | Переиспользуемый версионируемый контракт каталога |
| Эксплуатация платформы | Recipe, FeatureRecipe, Plugin для рендеринга провайдера | Перевод с учётом специфики Provider в отрисованную инфраструктуру |
| Оператор платформы | Manifest, Release | Маршрутизация и связывание развёртывания |
| Сквозная поддержка | SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary, Plugin, Workload | Общие структуры, код расширений и принадлежащий платформе вид компилятора |
Разработчик
Aggregate — единственная поверхность, на которой работает разработчик, и единственный источник истины о топологии приложения. В нём объявляются компоненты, из которых состоит приложение, значения values, которые принимает каждый из них, сущности Features, поведение которых является намерением приложения (вместе с их values), параметры parameters, открытые для вариаций между окружениями, и рёбра uses, связывающие компоненты между собой. Он намеренно остаётся агностичным по отношению к физической инфраструктуре: ничто в сущности Aggregate не называет облако, кластер или провайдер. Именно эта агностичность по отношению к возможностям позволяет развернуть одну сущность Aggregate где угодно.
Архитектор платформы
Component — переиспользуемый версионируемый контракт для одного вида строительных блоков. С помощью JSON Schema он объявляет значения values, которые может передать разработчик; выходы provides, которые он передаёт потребителям; и сокеты usesSchema, которые он открывает для связывания. Сущности Components несут семантические метки, управляющие политиками и рендерингом. Архитектор поддерживает контракт сущности Component стабильным, чтобы разработчики могли на него опираться.
Feature — подключаемая возможность, которую разработчик или оператор может добавить к компоненту: экспортёр метрик, маскирование чувствительного текста на AI-шлюзе, привязка учётных данных. Сущность Feature объявляет, что ей нужно и с чем она несовместима; то, как она реализуется — ресурсы, которые она генерирует, или настройки, которые она записывает в то, что её компонент уже рендерит, — находится в её сущности FeatureRecipe.
Эксплуатация платформы
Recipe — реализация сущности Component для конкретного провайдера. С помощью шаблонов она отображает объявленные в сущности Component значения на выход конкретного провайдера — релиз Helm, сервис Compose, модуль Terraform — и передаёт значения provides потребителям. Сущность Recipe никогда не меняет значения, которые сущность Component объявляет для разработчика; она решает лишь, как они рендерятся.
FeatureRecipe — реализация сущности Feature для конкретного провайдера, применяемая во время привязки. Она генерирует ресурсы, которые подразумевает подключение сущности Feature для данного провайдера, или записывает подразумеваемые настройки в то, что подключённый компонент уже рендерит.
Provider-rendering Plugin — провайдер — это гостевой модуль Wasm, который превращает входные данные сущности Recipe в нативные для провайдера манифесты. Он поставляется как сущность Plugin с pluginType: provider, которая объявляет имя (или имена) провайдера, для которого она выполняет отрисовку, и свой контракт сокета провайдера. Эксплуатация (или автор плагина) предоставляет провайдеры, чтобы у сущностей Recipes был провайдер для отрисовки. Поставляемые провайдеры и их контракты описаны в разделе Providers Overview.
Безопасное чтение учётных данных в сущности Recipe
Учётные данные поступают в сущность Recipe по каналу inject, .context.inject.env, в виде любого текста, который выбрал их автор, поэтому они могут содержать символы, которые шаблон не может записать в YAML как есть. Внутри скаляра в двойных кавычках двойная кавычка преждевременно завершает значение, а обратная косая черта начинает escape-последовательность: сборка останавливается либо обратная косая черта молча теряется. Экранируйте оба символа там, где записывается значение:
variables: {{- $env := optional (default dict .context.inject) "env" dict }} DB_PASSWORD: "{{ optional $env "DB_PASSWORD" "" | replace "\\" "\\\\" | replace "\"" "\\\"" }}"optional читает ключ из отображения канала с пустым значением по умолчанию, поэтому пароль, который ничто не доставило, при рендеринге даёт пустой текст. Два вызова replace экранируют сначала обратную косую черту, а затем кавычку — именно в таком порядке, чтобы экранирование самой кавычки не экранировалось повторно, — и оставляют все остальные символы как есть. К значению, прочитанному через index, который останавливает сборку при отсутствии ключа, применяются те же два вызова replace без изменений.
Один символ эта форма не передаёт — разрыв строки. YAML сворачивает разрыв строки внутри скаляра в двойных кавычках в пробел, поэтому учётные данные, содержащие его, доставляются с пробелом на месте разрыва. Сущность FeatureRecipe, записывающая учётные данные в свой injectMapping, вместо этого записывает их через toJson, который одинаково передаёт кавычку, обратную косую черту и разрыв строки, как показывает справочник по FeatureRecipe.
Эта сущность FeatureRecipe записывает учётные данные под тем механизмом, из которого их читает сущность Recipe, — env: для .context.inject.env, file:, arg: или собственным механизмом компонента под его собственным именем. .context.inject.all строится из этих механизмов и никогда — из вывода сопоставления, поэтому сопоставление, записывающее под all:, не доставило бы ничего; вместо этого сборка на нём останавливается, называя подключение, ключ и FeatureRecipe.
Оператор платформы
Manifest — слой маршрутизации. Он указывает компилятору, какая сущность Recipe реализует каждую сущность Component для данной цели, поэтому одну и ту же сущность Aggregate можно направлять на разные реализации в разных окружениях — облачную сущность Recipe для продакшена, сущность Recipe для Compose для локального тестирования — без изменений в файле разработчика.
Release — единственный вход компиляции, фиксирующий, что собирает одно окружение. Она указывает на сущности Aggregate и Manifest, заполняет параметры parameters, открытые разработчиком, подключает сущности Features, входные данные которых являются эксплуатационными, задаёт с помощью infra размеры тех, что подключил разработчик, и связывает собственные рёбра в пределах сокетов, объявленных архитектором. Сущность Release заполняет открытые точки вариаций; она не может вводить новые значения приложения values или новые вычислительные ресурсы — они приходят только из сущности Aggregate.
Виды сквозной поддержки
Эти виды служат авторам во всех ролях, а не принадлежат одной из них.
SchemaLibrary — общая библиотека структур схем, повторяющихся во многих сущностях Components и Features. Когда одна и та же структура (например, блок ресурсов пода) встречается во многих сущностях, архитектор выносит её в запись SchemaLibrary, чтобы она определялась и обновлялась в одном месте.
MappingLibrary — общая библиотека переиспользуемой логики отображения, к которой обращаются сущности Recipes и FeatureRecipes, чтобы общие шаблоны преобразования имели единый источник, а не копировались.
WorkloadLibrary — общая библиотека переиспользуемого содержимого Workload, чтобы структура развёртывания, повторяющаяся во многих сущностях Recipes, объявлялась один раз и импортировалась в каждый блок workload:.
ArtifactLibrary — общая библиотека переиспользуемых наборов артефактов: именованных наборов вспомогательных выходных файлов, которые связаны между собой, например CRD вместе с её RBAC. Сущность Recipe или FeatureRecipe импортирует набор в одной записи artifacts: и выводит каждый файл из него.
Plugin — вид расширения. Помимо рендеринга провайдеров, сущности Plugins упаковывают код WebAssembly, обеспечивающий предметную логику: проверку политик, мутацию, линтинг и другие сокеты. Создание сущностей Plugin — задача команды платформы, которая поддерживает все остальные роли.
Workload — принадлежащий платформе вид компилятора, а не файл, который разработчик или оператор пишет вручную как сущность верхнего уровня. Он используется внутри блока workload: сущности Recipe, где провайдер, с помощью которого сущность Recipe выполняет рендеринг, преобразует нормализованную структуру рабочей нагрузки в свою нативную форму. Авторы сущностей Recipe работают с ним через этот блок; структура описана в справочнике по Workload.
Далее
- Написание файлов Aggrega — цикл создания от начала до конца.
- Персоны — роли, стоящие за этой картой.