Столпы данных
Концептуальное описание пяти структурных ключевых слов DSL — parameters, values, uses, infra, inject — находится в architecture/06-data-taxonomy-and-composition.md. На этой странице описаны канонический список столпов данных, семантика написания каждого столпа, механика взаимодействия между столпами и словарь значений по умолчанию, с которым авторы сталкиваются в разных столпах. Дополняющая их топологическая триада (provides, inject, uses — ключевые слова, задающие рёбра графа) описана в topology-triad.md; словарь метаданных, отличный от столпов данных (метки, аннотации, поля поверхности публикации), описан в labels-and-annotations.md и publishing-surface.md.
Канонический список столпов
Сущности Aggrega несут семь именованных столпов данных. Пять участвуют в потоке данных IR как живое состояние на протяжении рендеринга; два являются временными или приватными и существуют только на определённых этапах компиляции.
| Столп | Где находится | Жизненный цикл | Роль |
|---|---|---|---|
values | Экземпляры компонентов и вложений сущности Aggregate | Живёт на протяжении рендеринга | Когнитивная нагрузка, задаваемая разработчиком |
infra | Записи компонентов, вложений и соединений сущности Release | Живёт на протяжении рендеринга | Физическое масштабирование, задаваемое оператором |
provides | Блок provides: сущности Recipe | Живёт на протяжении рендеринга (производный столп — см. ниже) | Вычисляемые сущностью Recipe публичные выходные строки, которые потребляет топологический канал |
uses | Экземпляры компонентов и возможностей сущности Aggregate | Живёт на протяжении рендеринга | Топологические рёбра к другим компонентам и возможностям |
features | Экземпляры компонентов Aggregate + Release; слоты, объявленные в featuresSchema сущности каталога, — см. «Features pillar» (столп Features) ниже | Живёт на протяжении рендеринга | Столп вложений — одна форма для каждого семейства вложений |
parameters | Корни сущностей Aggregate и Release | Доступен для чтения до конца конвейера, пока не завершатся все фазы рендеринга; доступен шаблонам путей во время рендеринга через асимметричное разрешение; контексты шаблонов значений потребляют литералы после интерполяции, а не .parameters напрямую | Слоты для каждого окружения, заполняемые сущностью Release |
locals | Блок locals: сущности Recipe | Приватен для Recipe — виден только внутри собственных шаблонов сущности Recipe | Вычисляемое строковое состояние, которое Recipes выводят в преамбуле locals |
values / infra / provides / uses / features — это пять живых столпов, которые контекст шаблонов среды выполнения предоставляет через .values, .infra, .provides, .context.uses и .features соответственно. parameters и locals не входят в список живых столпов: parameters — потому что не переживает разрешение; locals — потому что он приватен для Recipe и никогда не пересекает границы сущностей.
Столпы — это указатели, а не стены: шаблонизатор разрешает чтение между столпами в каждом месте, если это явно не запрещено правилами самодостаточности (чтение .context.inject / .context.uses в блоках provides: и source: сущности Recipe; описано в templates/expansion-matrix.md). Границы столпов — это дисциплина написания, а не ограничение языка.
Границы опор и дисциплина написания
Чтение из других опор в шаблоне Recipe не ограничено ни в одном месте, где доступен полный контекст шаблона. Дисциплина написания предполагает, что авторы:
- Читают
.valuesдля когнитивной нагрузки (намерения, заданного разработчиком). - Читают
.infraдля физического масштабирования (размеров, заданных оператором). - Читают
.context.uses[].provides.<key>для строк-указателей между компонентами (поток данных топологической триады). - Читают
.context.injectдля канала доставки после гидратации (собирается из источников inject вcomponent.inject,uses[].injectи перехватахinjectMappingв FeatureRecipe).
Эта дисциплина — указатели, а не стены. Шаблон Recipe, который читает .infra.replicas, чтобы задать поле values:, работает: движок шаблонов не блокирует это чтение. Архитектура исходит из того, что границы опор описывают намерение автора — кому принадлежат данные, — а не ограничение во время выполнения. Соглашения соответствуют разделению на четыре домена: значения, заданные разработчиком, берутся из .values; размеры, заданные оператором, — из .infra; координаты между компонентами — из топологического канала.
Когда нужен намеренный мост между опорами — например, schema: сущности Component предоставляет настройку для разработчика, которую шаблон valuesMapping: сущности Recipe передаёт в вывод на стороне эксплуатации в форме infra: согласно vocabulary/inheritance-and-interface.md, — архитектура рассматривает такой мост как обозначенное исключение. См. раздел «Механика между опорами» ниже.
Values
Опора values: несёт когнитивную нагрузку, задаваемую разработчиком, — параметры формы приложения, которые разработчик определяет для каждого экземпляра компонента. schema: сущности Component объявляет форму значений; Aggregate разработчика заполняет конкретные значения для каждого экземпляра. Это зона ответственности разработчика.
Где задаётся:
- Aggregate
components.<id>.values:— когнитивная нагрузка для каждого экземпляра компонента. - Aggregate
subsystems.<name>.components.<id>.values:— то же самое внутри компонентов, сгруппированных по подсистемам. - Aggregate
components.<id>.features.<name>.values:иfeatures.<name>.values:подсистемы — нагрузка значений присоединения, к какому бы семейству ни относилась присоединённая сущность Feature (параметры запроса к хранилищу секретов для присоединения учётных данных задаются здесь так же, как и любые другие).
Запрещено в:
- Сущности Release (схема Release запрещает блок
values:на любом уровне вложенности — поддерживаемый путь для вариаций по окружениям — Parameter Hoisting; см. Parameters ниже).
Чем проверяется: блоком values: в schema сущности Component (и блоком values: в schema сущности Feature для присоединений Feature), который преобразуется в JSON Schema 2020-12 при загрузке Component / Feature согласно vocabulary/validation-surface.md, уровень 2.
Кем потребляется: шаблонами valuesMapping: сущности Recipe через .values. Полный контекст шаблона предоставляет разрешённый словарь значений в каждой точке шаблона базового рендеринга.
Infra
Опора infra: несёт физические параметры размеров, задаваемые оператором: число реплик, запросы ресурсов, лимиты IOPS, привязку к региону, класс машины. Она выражает где и какого размера, дополняя что и как себя ведёт из values. Это область оператора.
Четыре точки авторинга
Авторы встречают infra: в четырёх отдельных точках, у каждой из которых своя область действия и своё каскадное поведение:
| # | Точка вывода | Область действия | Приоритет слияния |
|---|---|---|---|
| 1 | components.<id>.infra: границы Release (spec.components.<id>.infra: в сущности Release без границ) | Один экземпляр компонента | Собственные размеры компонента; никакая другая точка их не задаёт |
| 2 | features.<name>.infra: границы Release | Вложение на всю границу — на каждом компоненте границы | Самый низкий для этого вложения — точка 3 переопределяет его поле за полем |
| 3 | components.<id>.features.<name>.infra: границы Release | Одно вложение на одном компоненте | Переопределяет точку 2 для этого вложения поле за полем |
| 4 | components.<id>.uses.<socket>.<alias>.infra: сущности Release | Одно соединение | Проверяется по infraSchema сокета; доходит только до рендеринга потребляющего компонента |
Точка 1 используется чаще всего: оператор задаёт размеры каждого компонента, который размещает сущность Release. Граница не имеет собственного infra: — схема Release его отклоняет, — поэтому размеры, общие для нескольких компонентов, записываются в каждом из них или наследуются от родительской сущности Release через extends: (см. ниже). Точки 2 и 3 охватывают размеры подключений Feature: сущности Features несут собственную полезную нагрузку infra, которую FeatureRecipe использует при синтезе sidecar-контейнеров или ресурсов для каждой Feature; вложение на всю границу получает размеры один раз, а отдельный компонент корректирует одно его поле.
«Infra преимущественно локализована» — правило с исключениями
Архитектурная цель для infra: — локальность на уровне компонента: размеры компонента применяются к этому экземпляру компонента и не перетекают на другие компоненты. Именно этот механизм позволяет эксплуатации увеличить IOPS базы данных, не затрагивая запрос CPU API-сервера.
Правило: infra: преимущественно локализована в той точке, где она задана. Каскадные исключения существуют намеренно:
- Каскад аннотаций границы. Аннотации
annotations:границы каскадно передаются через вложенные границы во внутренние компоненты (точка 5 матрицы аннотаций в labels-and-annotations.md). Аннотации, которые сущности Recipes используют как входные данные маршрутизации, становятся косвенным охватомinfra: аннотация уровня границы проходит через.context.annotations.releaseв отрисованный вывод Recipe каждого узла. - Наследование Release через
extends:. Сущность Release, которая черезextends:расширяет родительскую Release, наследует объявленияinfraродителя во всех точках, где они есть, если только дочерняя сущность не переопределяет их по ключам. Значение дочерней сущности побеждает ключ за ключом вплоть до первого неделимого значения — скаляра, списка, шаблона, — которое заменяется целиком, а ключ, который дочерняя сущность записывает какnull, удаляется, а не получает пустое значение. Наследование намеренно пересекает границу отдельной Release; полное правило свёртки и то, что передаётся вместе с ним, см. вentities/release.md. - Межопорная передача через мост схемы.
schema:сущности Component может предоставить обращённый к разработчику параметрvalues:, который шаблонvaluesMapping:сущности Recipe передаёт в вывод провайдера в формеinfra:(см. ниже «Межопорные механизмы — межопорная передача через мост схемы»). Строго говоря, значение возникает вvalues:и попадает в отрисованный вывод; каскад происходит внутри экземпляра, но между опорами.
Локализация — это замысел проекта, а не стена, которую обеспечивает движок: описанные выше каскады — намеренные исключения, каждое из которых задокументировано в точке, где оно возникает.
Разделение сторон и опор для раскрытия Feature по аннотациям. Инвариант «Aggregate как точка авторинга» распространяется и на путь раскрытия Feature по аннотациям: аннотации на стороне Aggregate (область подсистемы и экземпляра компонента) могут активировать только подключи maps.values; аннотации на стороне Release (область границы и экземпляра компонента) могут активировать только подключи maps.infra. Привязка Manifest может объявлять пути в обеих опорах; каждая сторона активирует только совместимое с ней подмножество, а межсторонняя композиция объединяет вклады по полям во время построения IR. Это разделение сохраняет разграничение авторинга «values — разработчик / infra — оператор» в точке аннотаций — то же разграничение, которое values: и infra: обеспечивают в точках явного подключения. Описание для каждого подключа и шаблон межсторонней композиции см. в providers/well-known-annotations.md, §«Side-vs-pillar partition per subkey».
Provides
Столп provides: является производным: его объявляет Recipe, но, в отличие от values / infra, разработчик не пишет его напрямую. Recipes вычисляют публичные выходные строки, которые будет потреблять топологический конвейер.
Блок provides: сущности Recipe — это отображение пар <key>: <template>. Каждый шаблон во время вычисления provides вычисляется относительно собственной самодостаточной поверхности Recipe (.values, .infra, .context.instance_id, .context.rendered_name, если provider узла его сообщает, и разрешённые .locals узла). Полученные строки доступны через .provides и потребляются блоками uses[].inject вызывающих сторон через ссылки from: "<key>". .locals доступен, потому что locals узла разрешаются в преамбуле этого этапа, до его provides (см. Locals ниже); указание ключа, который блок locals не объявляет, приводит к остановке.
Инвариант самодостаточности. Шаблоны provides: сущности Recipe не должны ссылаться на .context.inject или .context.uses. Вычисление provides выполняет эти шаблоны в произвольном порядке: они замыкаются только на собственных данных узла, поэтому порядок не важен. Ссылки между узлами привязали бы это вычисление к порядку топологического обхода, чего архитектура намеренно избегает. Правило и его обоснование см. в templates/expansion-matrix.md, строка 6.
Почему provides: — это столп. Выходные строки являются канонической публичной поверхностью каждой Recipe; нижестоящие потребители (uses[].inject вызывающей стороны, блоки injectMapping сущности FeatureRecipe, читающие разрешённые provides цели через .context.uses) рассматривают этот словарь как типизированный контракт. Называя provides: столпом, мы признаём его полноправный статус наряду с values / infra / uses / features. Рассматривать его как «всего лишь внутреннюю деталь Recipe» значит недооценивать его роль основного источника данных топологического конвейера.
Uses
Столп uses: — это объявление рёбер топологии. Блок uses: экземпляра компонента перечисляет рёбра, в которых участвует компонент, — сокеты, через которые он потребляет цели. Полная грамматика описана в topology-triad.md; в этом разделе uses: назван столпом для полноты.
uses: находится в экземплярах компонентов Aggregate и в подключениях фич; контекст шаблонов во время выполнения предоставляет по одной записи на каждое исходящее соединение, с его псевдонимом в качестве ключа, как .context.uses. Проекция содержит разрешённые метаданные цели каждого ребра (provides цели, метки, аннотации), чтобы Recipes вызывающих сторон могли читать строки-указатели на другие компоненты при вычислении шаблонов базового рендеринга, а также подключения, записанные на этом соединении, — по пути .context.uses.<alias>.features.<slot>.
Столп Features
features: — опора подключений: одно ключевое слово, одна форма, все подключения. Операционная Feature, Feature учётных данных и Feature идентичности объявляются здесь под именем экземпляра, которое выбирает автор. Контекст шаблона во время выполнения предоставляет подключения узла как .features.<name>, и каждое из них несёт type, values, infra и разрешённые provides подключения. Подключение, записанное на одном из соединений компонента, вместо этого предоставляется в той же форме под соединением, по пути .context.uses.<alias>.features.<slot>, и никогда не под .features, поэтому Recipe, перебирающий .features, встречает только собственные подключения компонента (см. контракт контекста шаблона).
Подключение, имя экземпляра которого совпадает со слотом, объявленным сущностью в featuresSchema, заполняет этот слот; любое другое имя экземпляра — свободное подключение. Именно заполнение слота связывает четыре точки, через которые проходят учётные данные на основе слота:
| Точка вывода | Где задаётся | Роль |
|---|---|---|
Component / Feature featuresSchema: | сущность каталога | Объявляет слоты, которые ожидает сущность; для каждого слота ограничивает список допустимых способов доставки (env / file / blackbox) и, при необходимости, селектор меток, которому должно удовлетворять заполнение |
Aggregate components.<id>.features.<slot>: | экземпляр компонента в Aggregate | Заполняет слот подключением; задаёт собственные values: подключения и, для прозрачного слота, его отображение inject: |
Workload containers.<name>.attachments.<KEY>.from/as: | тело Workload в Recipe | Ссылается на объявленный слот — или, рядом с connection: <alias>, на слот, объявленный сокетом этого соединения, — и определяет доставку заполнившего его содержимого для каждого контейнера |
FeatureRecipe (source / workload / artifacts / valuesMapping, injectMapping, pipeline:) | привязанный FeatureRecipe | Создаёт результат подключения — выпускаемый ресурс, переписывание доставки или и то и другое |
Имя слота — ключевой идентификатор во всех четырёх точках: точка 1 его объявляет, точки 2–4 ссылаются на него, а поток данных однонаправленный (объявление → заполнение → ссылка → создание).
Контрольный список для авторов см. в examples/04-secrets.md, раздел «The secret-delivery checklist».
Locals
Столп locals: — это приватное состояние Recipe. Весь блок разрешается в преамбуле locals, до provides: этого узла; полученные строки видны всем последующим шаблонам самого Recipe — provides:, source:, valuesMapping:, workload:, artifacts:, assertions:, pipeline[].with. Шаблон provides:, ссылающийся на ключ, который блок не объявляет, вызывает останов.
Где задаётся: блок spec.locals: сущности Recipe — словарь пар <key>: <template>, вычисляемых на замкнутой локальной для узла поверхности: .context.instance_id, .values, .infra и уже разрешённые записи того же блока. Больше на ней ничего нет: .provides, .metadata и остальная часть .context.* недоступны, и ссылка на любой из них вызывает останов.
Порядок имеет значение. Записи разрешаются в порядке написания, и запись может читать соседнюю запись, определённую выше неё, получая её разрешённое значение. Цепочки идут только вниз: если одна запись читает другую, перенос определения ниже читающей записи отклоняется, и компилятор никогда не переупорядочивает блок, чтобы ссылка разрешилась. Ссылка на более позднюю запись вызывает останов с указанием ошибки порядка; ссылка на необъявленный ключ вызывает останов с указанием ключа. Для Recipe, у которого source: — структурированный блок, обе ошибки отклоняются ещё при закреплении указанного в нём артефакта, поэтому aggrega pull сообщает о них до того, как какая-либо сборка выведет результат. Проверка читает путь, к которому ссылка разрешается, а не набранный текст, поэтому она одинаково охватывает прямую форму, блок with .locals, переменную, привязанную к .locals, и блок в скобках, (.locals).<key> или ($.locals).<key>. Один вариант записи она не охватывает: ключ, полученный через функцию, например index .locals или (default dict .locals).<key>. Отсутствующий ключ, полученный этим способом, не вызывает останова и выводится как буквальный текст <no value>, а не как пустое значение, — за исключением самой index, которая вызывает останов с указанием ключа на любой шаблонной поверхности, если читаемый ею словарь не содержит этого ключа.
Видимость: приватна для Recipe. Поля .context.uses[].locals не существует — вызывающая сторона не может прочитать locals своей цели через ребро. Вызывающая сторона может прочитать только provides: цели.
Сценарии использования:
- Вычисление внутренних для Recipe строк-указателей (например,
secret_target_admin_password: "redis-auth", суффикс имени Secret), которые потребляют иvaluesMapping:, иprovides:этого Recipe и которые credential FeatureRecipe, подключённый к тому же компоненту, читает как.locals.secret_target_admin_password: шаблоны подключения видят разрешённые locals основного Recipe, объединённые с собственными locals подключения. Для целиhelmкаждый из них записывает полное имя как{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}: отрисованное имя — это имя компонента, записанное символами, допустимыми в имени Kubernetes, и local не может его прочитать, поэтому local содержит суффикс, а каждый читатель соединяет обе части. - Устранение повторов вычисляемых значений внутри одного Recipe (имя хоста вычисляется один раз и используется в нескольких полях
valuesMapping:). - Промежуточные значения для сложной шаблонной логики, которая была бы нечитаемой при записи в одну строку.
provides: и locals: — публичная и приватная стороны
Два столпа на стороне Recipe намеренно разделены по видимости, и авторам следует об этом помнить:
provides:— публичная сторона. Каждый ключ — каноническая поверхность передачи по топологии: блокиuses[].injectнижестоящих вызывающих сторон потребляют их через ссылкиfrom: "<key>". Словарьprovides:— типизированный контракт, от которого зависят вызывающие стороны; переименование или удаление ключа — несовместимое изменение для каждого Recipe, чьи объявленияuses[].injectна него ссылаются.locals:— приватная сторона. Каждый ключ — внутреннее состояние Recipe, видимое только в последующих шаблонах самого Recipe. Никакая вызывающая сторона не может прочитать locals сущности Recipe; имена вlocals:не входят ни в один опубликованный интерфейс, и их переименование — внутренний рефакторинг Recipe без последствий для нижестоящих сторон.
Кроме того, они упорядочены: locals: разрешается первым, поэтому provides: может читать .locals, но locals: не может читать .provides. Поэтому опубликовать значение local через provides: означает добавить запись provides, которая читает этот local, — выражение остаётся в одном месте.
Разделение намеренно следует архитектурному отделению внутреннего устройства Recipe (приватного) от интерфейса Recipe (публичного). Авторы, рассматривающие provides: и locals: как одно пространство имён, теряют различие в видимости и рискуют раскрыть внутреннее состояние через передачу по топологии: каждый ключ, объявленный в provides:, становится частью контракта Recipe, независимо от намерений автора. Цель дисциплины: сначала объявлять ключ в locals:; переносить его в provides: только тогда, когда он действительно нужен нижестоящей вызывающей стороне.
Видимость определяется опорой, в которой объявлен ключ: маркера видимости для отдельного ключа нет, поэтому значение, которое одновременно приватно и опубликовано, — это запись locals: и запись provides:, которая её читает.
Параметры
Схемы Aggregate и Release содержат в корне словарь parameters. Разработчики объявляют ключи, которые ожидает Aggregate; эксплуатация заполняет значения из файлов Release для конкретных окружений. Это разделение — механизм GitOps-продвижения: один неизменяемый Aggregate.yaml проходит через окружения Dev, Staging и Production, а Release каждого окружения поставляет собственные значения параметров.
spec: parameters: corp_db_name: type: string required: true env_workers: type: integer required: true region: type: string required: true enable_debug: type: boolean required: true components: my-backend: type: core/python-worker:1.0.0 values: workers: {{ .parameters.env_workers }} region: "{{ .parameters.region }}"# release-prod.yaml — inline parameter valuesspec: aggregate: my-app manifest: prod-manifest parameters: corp_db_name: "enterprise_data" env_workers: 10 region: "eu-west-1" enable_debug: falseДля процессов CI/CD, в которых значения параметров хранятся в отдельном файле (например, в .yaml для каждого окружения, хранящемся рядом с Release), Release использует форму $import:: parameters: { $import: ./prod-values.yaml }. Содержимое файла заменяет встроенную карту на уровне Release. Путь разрешается от каталога, содержащего Release, откуда бы ни запускалась команда, и должен вести к файлу внутри рабочего пространства — или, для Release, указанного вне рабочего пространства, внутри содержащего его каталога. Многофайловое наслоение (объединение базового файла с наложением для конкретного окружения) выражается цепочками extends: сущностей Release: родительский Release поставляет базовые параметры, дочерний Release расширяет и переопределяет их по ключам.
Жизненный цикл параметров. Компилятор разрешает параметры в три фазы. (1) Заполнение значений по умолчанию — слоты, для которых определено default: и нет значения из Release, получают значение по умолчанию. (2) Проверка контракта параметров — типизированный контракт parameters: проверяет каждое значение на соответствие объявленным ограничениям type / enum / min / max / pattern, включая подставленное значение по умолчанию, поэтому значение по умолчанию, нарушающее собственный контракт, останавливает сборку. (3) Интерполяция — компилятор вычисляет весь текст Aggregate как шаблон и заменяет каждую ссылку {{ .parameters.<slot> }} разрешённым значением. Затем объединённая карта остаётся доступной для чтения на протяжении рендеринга, чтобы шаблоны путей (границы Release directory: / subDirectory:) могли читать .parameters.<slot> напрямую по закрытому списку разрешённого, описанному в ../path-template-variables.md. Поверхности шаблонов значений (Recipe valuesMapping, FeatureRecipe injectMapping / provides / pipeline.with, тела Workload) НЕ получают .parameters в своём контексте шаблона — они используют разрешённые значения, записанные в окружающие строки values: интерполяцией фазы 3.
Контрольный список подъёма параметров
Каждое значение, различающееся между окружениями, последовательно проходит через четыре точки авторинга. Мысленная модель для авторов: для любого значения, которое различается между Dev / Staging / Production, следует ожидать правок в Aggregate (объявление), в шаблоне значений (ссылка), в Release (заполнение) и в шаблоне Recipe (использование).
| Шаг | Точка вывода | Действие |
|---|---|---|
| 1 | Aggregate spec.parameters.<name> | Объявите параметр как часть типизированного контракта авторинга Aggregate. Каждый слот параметра содержит объявленный type (string, integer, number, boolean, array, object), необязательное description, необязательное default, необязательные ограничения пространства значений (enum, min, max, pattern, minLength, maxLength) и необязательную вложенную структуру для слотов объектного типа. Контракт проверяет каждое значение, переданное из Release, до интерполяции. |
| 2 | Шаблон values: сущности Component внутри того же Aggregate | Сошлитесь на параметр через {{ .parameters.<name> }} внутри блока values: любого компонента (или фичи, или вложенного агрегата), который его использует. Ссылка — это выражение шаблона Go: компилятор вычисляет его на фазе интерполяции при разрешении. |
| 3 | Release spec.parameters.<name> (встроенно или parameters: { $import: ./path.yaml }) | Заполните параметр значением для конкретного окружения на уровне Release. Файлы Release для разных окружений поставляют разные значения для одного и того же ключа параметра, не изменяя Aggregate. |
| 4 | Шаблон Recipe valuesMapping: | Используйте разрешённое значение через {{ .values.<key> }} — Recipe является поверхностью шаблонов значений; её контекст шаблона не содержит .parameters напрямую. Различия между окружениями доходят до Recipe через словарь values: после интерполяции, который записывает описанная выше фаза интерполяции. (Исключение составляют шаблоны путей на границах Release: они читают .parameters.<slot> напрямую во время рендеринга согласно асимметричному разрешению.) |
Четыре точки последовательны и несут нагрузку: если пропустить объявление в Aggregate, у Release не будет слота для заполнения; если пропустить ссылку в values, у Recipe не будет значения для использования; если пропустить заполнение в Release, параметр останется пустым. Компилятор проверяет цепочку при разрешении (проверка контракта параметров по типизированному объявлению parameters:, затем интерполяция в окружающие строки values:, затем проверка JSON Schema полученного словаря values: по schema: сущности Component или Feature); несоответствия проявляются либо как нарушение контракта параметров (выявляется по типизированному объявлению parameters:), либо как ошибка незаполненного шаблона (выявляется при интерполяции), либо как нарушение ограничения JSON Schema по схеме values: (выявляется при проверке схемы).
Этот шаблон — канонический механизм GitOps-продвижения: один неизменяемый Aggregate проходит через окружения, а Release каждого окружения поставляет собственные значения параметров. Каждое значение, которое автор хочет менять между окружениями, должно проходить через цепочку параметров, а не встраиваться непосредственно в Aggregate.
Семантика слияния extends: по столпам
Когда сущность каталога объявляет extends: и компилятор обходит цепочку наследования, содержимое каждого столпа сливается по правилам, специфичным для этого столпа. Семантика различается между столпами; таблица ниже — канонический справочник по столпам.
| Столп | Поведение слияния в цепочке extends: |
|---|---|
values (JSON Schema 2020-12) | В цепочке Feature схемы объединяются средствами композиции JSON Schema 2020-12. Расширяющая сущность Component не задаёт содержимого столпов и получает блок своей базы ровно в том виде, в каком его написала база, на любой глубине цепочки. |
infra (фрагмент JSON Schema 2020-12) | Так же, как values: объединяется в цепочке Feature, целиком наследуется расширяющей сущностью Component. |
provides (карта шаблонов Recipe) | Поверхностная замена на верхнем уровне: ключ потомка полностью заменяет ключ родителя с тем же именем; соседние ключи сохраняются от родителя. Шаблоны не объединяются; шаблон потомка полностью владеет своим слотом. |
uses (usesSchema) | Наложение целых записей по имени сокета. Потомок добавляет сокеты, которые его база не объявляет, а сокет, переобъявленный под существующим именем, полностью заменяет эту запись — вместе со схемами значений и инфраструктуры и его selector. Записи сокетов не объединяются, и переобъявленный selector ни с чем из базы не сравнивается. |
features (схема по слотам featuresSchema) | Наложение целых записей по имени слота, на тех же условиях, что и usesSchema. Потомок свободно добавляет слоты; переобъявленный слот полностью заменяет запись базы, а не объединяется с ней. |
locals (карта шаблонов Recipe) | Поверхностная замена на верхнем уровне — так же, как provides. |
parameters (корневая карта Aggregate) | У сущности Aggregate нет поля extends:, поэтому никакая цепочка Aggregate не сливает параметры. В цепочке extends: сущности Release параметр-карта сливается глубоко с приоритетом ключа потомка, скалярный параметр заменяется потомком, а ключ, который потомок записывает как null, удаляется. |
Общая закономерность зависит от вида сущности и от поверхности. Валидируемые схемой столпы Feature объединяются по JSON Schema 2020-12. Столпы расширяющей сущности Component наследуются целиком — она не задаёт ни одного, поэтому её контракт в точности совпадает с контрактом базы, и ограничение базы, следовательно, ослабить нельзя по построению. Поверхности фиксированной формы — usesSchema и featuresSchema — накладываются по имени для обоих видов: потомок добавляет записи, а переобъявленная запись полностью заменяет запись базы. Столпы, задаваемые шаблонами, используют поверхностную замену по ключам, давая потомку полное владение любым объявленным им слотом шаблона.
Расширяющая сущность Component ужесточает ограничение через assertions:, а не через столп, — добавляемым предикатом, который вычисляется вместе с унаследованными. Этот механизм описан в inheritance-and-interface.md.
Сам механизм наследования описан в inheritance-and-interface.md, раздел «Наследование через extends», который охватывает виды сущностей каталога. Сущность Release не является сущностью каталога и сворачивается по собственному правилу; это правило приведено в entities/release.md, раздел «Составной Release и наследование extends:».
Межстолповые механизмы
Подход с указателями допускает межстолповое чтение везде, кроме документированных поверхностей самодостаточности. Шаблоны ниже формализуют распространённые межстолповые механизмы; описан и один настораживающий признак в написании, чтобы авторы понимали компромисс.
Межстолповая передача через мост схем — указатели, а не стены
Границы столпов — это дисциплина авторинга: архитектура указывает, что куда относится (values: для когнитивного намерения разработчика, infra: для физического масштабирования со стороны Ops, provides: для строк, выдаваемых Recipe, и так далее), а рецензент каталога следит за соблюдением соглашения. Сам движок шаблонов допускает межстолповое чтение, если его не запрещают документированные правила самодостаточности (provides: сущности Recipe не видит .context.inject; provides: области границы FeatureRecipe не видит полей отдельных потребителей). Стены столпов — это указатели, а не принуждение.
Каноническое обозначенное исключение: schema: сущности Component может объявить обращённый к разработчику параметр values:, который шаблон valuesMapping: сущности Recipe передаёт в отрисованный вывод формы infra:. Разработчик задаёт намерение через типизированное поле values:; шаблон Recipe передаёт полученное значение в инфраструктурный слой провайдера, и разработчику не приходится писать инфраструктурный код. Рабочий пример:
# Component schema declares a developer-facing dial in valuesspec: schema: values: required_iops: { type: integer, min: 100 }# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knobvaluesMapping: iops_limit: "{{ .values.required_iops }}"Мост описан в inheritance-and-interface.md с рабочими примерами. Архитектурное намерение (объявленный межстолповый параметр, который Recipe передаёт дальше) действует в одном направлении — values: со стороны разработчика поступает в отрисованный вывод со стороны Ops — и реализуется в шаблонах отображения Recipe, а не в самой схеме Component. Граница столпа остаётся обозначенной: разработчик видит values:, Recipe видит и values:, и infra:, отрисованный вывод объединяет их.
Межстолповый накопитель inject
Канал .context.inject — точка слияния трёх источников, охватывающих несколько столпов:
- Self-inject на уровне Component (
component.inject) — берёт строки из собственныхvaluesи собственныхprovidesкомпонента. - Внедрение через uses (
uses[].inject) — берёт строки изprovidesцели. - Перехваты
injectMapping:сущности FeatureRecipe — берут строки из любого из перечисленных источников, а также из собственной полезной нагрузкиinfra:сущности FeatureRecipe.
К моменту запуска базовой отрисовки .context.inject.<mechanism>.<key> уже содержит записи из всех трёх источников. Накопитель межстолповый по построению — записи, происходящие из values, provides и infra, попадают в одну и ту же карту .context.inject. Сущности Recipes, потребляющие .context.inject, видят состояние после слияния, и им не нужно знать, какой столп внёс какую запись.
Грамматику inject и правила коллизий см. в topology-triad.md.
Дублирование ограничений между столпами
Поле, находящееся в двух столпах с разными слоями валидации, может нести дублирующиеся ограничения. Канонический пример: номер порта, объявленный в usesSchema сущности Component (валидируется JSON Schema, диапазон min: 1, max: 65535), и тот же номер порта, потребляемый в поле services.<name>.ports.<port> сущности Workload, для которого spec.provider.workloadSchema плагина отрисовки провайдера может добавить правило min: 1024 для непривилегированных портов. spec.provider.workloadSchema сущности Plugin для отрисовки провайдера описывает, как провайдер преобразует Workload, и отмечает провайдер как способный её синтезировать; она ничего не валидирует. Каждое тело Workload валидируется по схеме Workload платформы, каким бы ни был провайдер, поэтому ограничение, записанное только в workloadSchema, — скажем, правило min: 1024 для порта — не применяется; чтобы отклонять такое значение, поместите ограничение в схему сущности Component или в утверждение (assertion).
Изоляция столпов присоединения Feature и Component
Присоединение Feature не записывает в столпы родительской сущности Component. Каждая присоединённая Feature несёт собственную полезную нагрузку столпов (собственный блок values: и собственный блок infra:). FeatureRecipe, синтезирующий ресурсы Feature, читает собственную полезную нагрузку столпов независимо от Component. Изолируются входные данные: то, что читает присоединение, принадлежит ему самому, что бы ни стало с тем, что оно записывает. Если провайдер цели записывает отдельные документы, отрисованный вывод присоединения располагается рядом с выводом Component в собственном каталоге; если провайдер сводит участников границы в один документ, присоединение вносит вклад в этот документ так же, как Component, и каждый ресурс по-прежнему несёт собственную идентичность присоединения, чтобы происхождение оставалось понятным.
Два следствия для авторов:
- Настройка
values:в присоединении Feature не появляется в.valuesшаблонаvaluesMapping:сущности Component. Component видит только собственные значения. - Полезная нагрузка
infra:сущности Feature не попадает вinfra:сущности Component. Каждая присоединённая Feature имеет собственное физическое масштабирование, ограниченное ресурсами Feature.
Изоляция явно следует из разделения ответственности в архитектуре: Features — независимые участники, накладываемые на Components через пятиуровневую луковичную модель. Поверхности присоединения и порядок см. в labels-and-annotations.md, раздел «Feature attachment — five surfaces».
Одинаковое имя свойства в обоих столпах
Component или Feature, в которых spec.schema.values: и spec.schema.infra: объявляют одно и то же имя свойства — в корне, на любой глубине вложенности или и там, и там, — частый «запах» авторинга. Два столпа по замыслу являются отдельными пространствами имён (компилятор допускает пересечение), поэтому схема проходит валидацию, а отрисованный вывод корректен. «Запах» когнитивный: читатели и авторы шаблонов каждый раз, просматривая схему или пиша по ней шаблон, спотыкаются о вопрос «в каком столпе находится foo, который я читаю?».
# Smell — both pillars declare `mode`. A reader of the schema or a# template against the Feature has to disambiguate every reference.spec: schema: values: mode: { type: string } infra: mode: { type: string }У авторов с намеренным пересечением есть реальная причина сохранить оба — например, mode, означающий «операционный режим приложения» в values ("debug" / "production") и «режим топологии развёртывания» в infra ("standalone" / "clustered"), несёт разную семантику, а имена просто совпадают. Авторы со случайным пересечением (более частый случай) переименовывают одну из записей.
Второй намеренный вариант — одно значение, которое может предоставить любой из авторов. Сущности Features стандартной библиотеки для учётных данных, несущие локатор вызывающей стороны, — core/referenced-secret, core/referenced-secret-set, core/secret-value и core/secret-provided — объявляют его в обоих столпах под одним именем и в одной форме, так что разработчик пишет его в values или оператор в infra, а собственная проверка каждой Feature отклоняет присоединение, которое записывает его в обоих столпах или ни в одном. Описанное ниже предупреждение называет эти четыре при каждой загрузке, которая до них доходит; для них оно сообщает о контракте, а не об ошибке.
Загрузка каталога выдаёт предупреждение notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) для каждого одноимённого свойства, пересечение которого хотя бы с одной стороны разрешается в конечный лист. Одноимённые свойства, существующие как общие организующие пространства имён (оба столпа содержат объект ingress с непересекающимися подсвойствами), не вызывают предупреждения; сообщается только о пересечении листьев. Предупреждение носит рекомендательный характер — сборка продолжается.
Уровни валидации столпов
Валидация столпов выполняется на трёх уровнях. Каждый уровень отвечает за свою задачу; одно и то же поле может проверяться более чем на одном уровне (см. «Дублирование ограничений между столпами» выше).
| Уровень | Что проверяется | Где выполняется |
|---|---|---|
| 1 — оболочка JSON Schema | Структура (какие ключи присутствуют, соответствуют ли типы объявлениям полей) | Разрешение, при загрузке каждого файла |
2 — схема столпа (schema / featuresSchema / usesSchema) | Типизированное содержимое каждого столпа, проверяемое как JSON Schema 2020-12 | Разрешение, после успешной проверки оболочки |
| 3 — проверка возможностей провайдера | Содержимое Workload, допускаемое в зависимости от возможности синтезированного режима привязанного провайдера, документированной в spec.provider.workloadSchema плагина рендеринга провайдера | Базовый рендеринг, после разрешения valuesMapping |
Таблицу форм ошибок для четырёх слоёв и префиксы ошибок каждого слоя см. в validation-surface.md.
Механизмы значений по умолчанию
Значения по умолчанию появляются в корпусе через несколько разных механизмов. Авторы встречают слово «default» более чем в пяти контекстах; таблица ниже — каноническая справка о том, какой механизм выдаёт значение, когда автор оставляет поле пустым.
| # | Механизм | Где задаётся | Срабатывание |
|---|---|---|---|
| 1 | JSON Schema default: (компактная форма { default: <value> }) | Component / Feature schema:, Aggregate parameters: | Поле проходит валидацию со значением по умолчанию, когда разработчик опускает ключ. Для параметров Aggregate слияние параметров подставляет объявленное значение по умолчанию до запуска валидации контракта (см. templates/parameters-context.md). |
| 2 | Шаблон Go optional .X `Y` <fallback> | Recipe valuesMapping:, тело Workload, шаблоны FeatureRecipe, вычислитель утверждений | Запасное значение с учётом наличия — возвращает <fallback> только тогда, когда ключ отсутствует в map; заданные автором ноль / пустое значение / false по этому ключу возвращают это заданное значение. Каноническая для Aggrega форма запасного значения для отсутствующего поля. См. templates/sprig-functions.md. |
| 3 | Шаблон Go | default <expr> | Recipe valuesMapping:, тело Workload, шаблоны FeatureRecipe | Встроенный конвейер, срабатывающий на «пустое» значение (проверка пустоты Sprig — ноль, пустая строка, false, nil). Не различает отсутствие в map и наличие нулевого / пустого / false значения. Подходит для семантики переопределения в конкретном месте вызова (запасное значение привязки отличается от значения по умолчанию на уровне схемы поля), где такое смешение допустимо. Не подходит для запасного значения отсутствующего поля, где заданные автором ноль / пустое значение / false — законное намерение: для этого случая используйте optional (механизм 2). |
| 4 | Функция Sprig default ({{ default <expr> .field }}) | То же, что 3 | Функциональная форма механизма 3 с тем же смешением пустых значений. |
| 5 | Запасное значение в Recipe locals: | Шаблон Recipe locals: | Запись locals вычисляет строку со значением по умолчанию, которую использует остальная часть Recipe |
Рекомендации по размещению. Когда значение по умолчанию действительно является частью контракта типа (например, «этот порт по умолчанию 5432, если разработчик его не переопределит»), канонической формой является JSON Schema default: (механизм 1): автодополнение в IDE показывает значение по умолчанию, инструменты валидации его учитывают, а контракт переносится вместе с каталожной сущностью Component / Feature ИЛИ с объявлением параметра Aggregate. Когда шаблону Recipe нужно запасное значение для необязательного ключа map, канонической формой запасного значения для отсутствующего поля является помощник optional (механизм 2): он отличает заданные автором ноль / пустое значение / false от отсутствия. Шаблон Go | default (механизм 3) предназначен для случая переопределения в конкретном месте вызова, где смешение отсутствующих и ложных значений допустимо; прибегайте к нему только тогда, когда семантика переопределения — явное намерение.
Перекрёстные ссылки
inheritance-and-interface.md— механизмextends:, привязка интерфейсаimplements:(Interface Binding), межстолповая передача данных через мост схем.topology-triad.md— топологическая механикаprovides,inject,uses.labels-and-annotations.md— словарь метаданных на стороне содержимого, отдельный от столпов данных (приведённый выше канонический список столпов не включает метки, аннотации и поля публикации — это словарь метаданных).publishing-surface.md— словарь метаданных на стороне публикации, отдельный от столпов данных.validation-surface.md— четыре уровня валидации по схеме, включая три описанных выше уровня валидации столпов.templates/expansion-matrix.md— доступность межстолповых чтений в каждом месте шаблона и правила самодостаточности вprovides:иsource:сущности Recipe.examples/04-secrets.md— контрольный список доставки секретов из шести точек.architecture/06-data-taxonomy-and-composition.md— каноническое концептуальное описание пяти структурных ключевых слов DSL.