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

Контекст шаблонов параметров

Раздел parameters: содержит значения параметров, заполненные сущностью Release и проверенные по контракту. Их доступность определяют две параллельные модели:

  • Поверхности шаблонов значений (строки values: компонентов, фич и вложенных агрегатов внутри сущности Aggregate, а также valuesMapping сущности Recipe, injectMapping и provides сущности FeatureRecipe, тела сущностей Workload) получают значения параметров как уже интерполированные литералы. Проход интерполяции на этапе разрешения вычисляет весь текст сущности Aggregate как шаблон и заменяет каждую ссылку {{ .parameters.<slot> }} разрешённым значением; последующие поверхности шаблонов значений никогда не видят .parameters напрямую в своём контексте шаблона.
  • Поверхности шаблонов путей (шаблоны directory: и subDirectory:, написанные оператором, на границах сущностей Release) читают .parameters.<slot> напрямую при вычислении шаблона пути во время рендеринга. Объединённая карта параметров остаётся доступной для чтения до конца рендеринга, чтобы шаблон пути мог читать .parameters по закрытому списку разрешённых переменных.

Асимметричное разрешение — шаблоны путей читают .parameters напрямую, шаблоны значений нет — оставляет каждому слою то, что ему нужно: values: на стороне разработчика передают шаблонам значений уже разрешённые данные, специфичные для окружения; шаблоны путей на стороне оператора ссылаются на параметры региона, окружения и идентификатора аккаунта, не проходя через схему values сущности Aggregate.

На этой странице описаны проход интерполяции, формы значений для каждого слота, шаблоны доступа внутри строк YAML сущности Aggregate, исключение для шаблонов путей и то, как долго объединённая карта остаётся доступной для чтения. Общую структуру контекста шаблонов Recipe / FeatureRecipe (.values, .infra, .uses и т. д.) см. в template-context-contract.md. Доступность в каждом месте шаблонов на протяжении конвейера компиляции см. в expansion-matrix.md. Структуру объявления контракта типизированных параметров в сущности Aggregate см. в entities/aggregate.md, раздел «Typed parameter contracts». Список разрешённых переменных шаблонов путей, включающий .parameters.<slot> при вычислении directory: / subDirectory: на границе, см. в path-template-variables.md.

Жизненный цикл параметров

Компилятор разрешает параметры в четыре последовательные фазы:

  1. Чтение контракта — блок spec.parameters: сущности Aggregate проверяется сам по себе до того, как рассматривается какое-либо значение Release, поэтому слот, который ничего не может ограничить, останавливает сборку, даже если ни один Release его не предоставляет. Отрицательное minLength или maxLength в собственном объявлении параметра отклоняется при загрузке Aggregate с указанием параметра и ключа. Каждый pattern — в самом слоте и внутри любого вложенного контракта в items, properties или valuesType — компилируется как регулярное выражение, а некомпилируемое выражение отклоняется с указанием параметра, шаблона и причины. На ограничение длины внутри вложенного контракта этот нижний предел не распространяется; см. entities/aggregate.md.
  2. Заполнение значений по умолчанию — слоты, для которых определено default: и нет значения, предоставленного Release, получают значение по умолчанию. На этом этапе карта .parameters находится в области видимости.
  3. Проверка контракта параметров — каждое значение в объединённой карте, предоставлено ли оно Release или заполнено из default:, проверяется на соответствие объявленным в spec.parameters.<slot> сущности Aggregate ограничениям type / enum / min / max / pattern / вложенной структуры; pattern сопоставляется с выражением, скомпилированным при чтении контракта. Карта .parameters существует в контексте валидатора в памяти как проверяемая структурированная полезная нагрузка.
  4. Интерполяция — компилятор вычисляет весь текст Aggregate как шаблон, прежде чем читать его как YAML, и заменяет каждую ссылку {{ .parameters.<slot> }} разрешённым значением; любая другая {{ в тексте также читается как синтаксис шаблона, поэтому в значении с собственными двойными фигурными скобками каждая {{ записывается как {{"{{"}} (см. Текст с собственными двойными фигурными скобками). Интерполяция — это путь подстановки для поверхностей шаблонов значений: после этого прохода контексты шаблонов значений больше не содержат .parameters; они используют разрешённые значения, записанные в окружающие строки values:. Объединённая карта остаётся доступной для чтения после интерполяции, на протяжении всего рендеринга, именно для поддержки вычисления шаблонов путей. Срок её доступности ограничен сроком сборки: компилятор передаёт разрешённое представление потребляющей его компиляции, а не возвращает его вызывающей стороне, поэтому ничто вне этой сборки не может обратиться к карте. Поверхность шаблонов путей (directory: / subDirectory: сущности Release) читает .parameters.<slot> во время рендеринга по закрытому списку разрешённых переменных, описанному в path-template-variables.md.

Шаблоны внутри строк YAML сущности Aggregate (values: компонента, values: функции, выражения сквозной передачи parameters: вложенного агрегата) читают карту .parameters с помощью стандартного синтаксиса шаблонов Go во время прохода интерполяции. Шаблоны внутри файлов Recipe и FeatureRecipe НЕ получают .parameters в своём контексте шаблона (контракт для каждой поверхности см. ниже в разделе «Граница с последующими контекстами шаблонов»).

Текст, содержащий собственные двойные фигурные скобки

Поскольку весь текст является шаблоном, двойные фигурные скобки, которые принадлежат значению, а не шаблону, тоже читаются как действия шаблона. Типичный случай — определение потоковой платформы, переданное в values: компонента: n8n заключает каждое выражение в параметрах узла в двойные фигурные скобки, как в ={{ $json.body.message }}, промпт Flowise обозначает переменную как {{question}}, а chatflow Flowise записывает {{chatOpenAI_0.data.instance}} для каждого соединения между двумя узлами, и экспорт Langflow содержит исходный код своих компонентов, где скобки тоже могут встречаться. Если записать их в Aggregate как есть, сборка останавливается на этом Aggregate с E0158, описанной в разделе «A {{ .parameters.* }} reference cannot be interpolated (Ссылку невозможно интерполировать)» на странице Fatal halts; причина указывает строку и первый токен, который шаблонизатор не смог прочитать, — undefined variable "$json" для выражения n8n. Комментарий YAML тоже является текстом шаблона, поэтому {{, записанная в комментарии, приводит к такой же остановке.

Записывайте каждую {{ в таком значении как {{"{{"}}. Это действие шаблона, результатом которого является строка {{, поэтому интерполяция возвращает обе скобки на место. Закрывающей }} ничего не требуется, поскольку вне действия это обычный текст. Интерполяция выполняется один раз, над текстом Aggregate, а шаблон Recipe записывает прочитанное из .values как данные, поэтому восстановленные скобки попадают в отрендеренный результат в том виде, в каком были экспортированы.

# Aggregate fragment — an n8n workflow definition carried as exported
spec:
components:
automation:
type: core/ai-agent/n8n
values:
workflow_id: support-reply
flow_definition: |
{
"name": "Support reply",
"nodes": [
{
"name": "Set reply",
"type": "n8n-nodes-base.set",
"parameters": {
"value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}"
}
}
],
"connections": {}
}

Платформа получает "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".

Храните такое определение в блочном скаляре (|), как показано выше, где кавычки экранирования — обычные символы. Текст Aggregate также читается как YAML до интерполяции, а внутри строки YAML в двойных кавычках " из экранирования закрывает строку, поэтому файл перестаёт разбираться, и сборка останавливается с ошибкой YAML.

Шаблон доступа .parameters.<slot>

Каждый объявленный слот параметра доступен как поле карты .parameters. Доступ с корректным типом соответствует объявленному type:

# Aggregate fragment — parameter declarations
spec:
parameters:
region: { type: string, enum: [us-east-1, us-west-2] }
cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 }
enable_debug: { type: boolean, default: false }
components:
web:
type: core/web-server:1.0.0
values:
region: "{{ .parameters.region }}" # string
cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer
debug: {{ .parameters.enable_debug }} # boolean

Проход интерполяции выполняет вычисление шаблона Go над картой .parameters; результат заменяет шаблонное выражение на его месте в документе. Затем схема values: сущности Component / Feature проверяет полученное значение на фазе проверки схемы после интерполяции в ходе разрешения.

Кавычки определяют поднимаемый тип

Заключайте в кавычки ссылку, нацеленную на строковый лист; для любого другого объявленного типа оставляйте её без кавычек. Это правило самого YAML, а не надстройка, добавленная Aggrega: интерполяция подставляет заполненное значение в байты документа и больше ничего не делает, поэтому последующий разбор читает результат точно так же, как любой другой скаляр. Ссылка {{ .parameters.cache_ttl_seconds }} без кавычек несёт собственный тип заполненного значения — именно это позволяет целочисленному параметру попасть в целочисленный лист, а логическому параметру — в логический лист. Ссылка в кавычках "{{ .parameters.cache_ttl_seconds }}" несёт строку, и лист, объявленный как integer или boolean, её отвергает: записанное значение не проходит схему values: своей сущности Component или Feature по типу, и диагностика называет несоответствие типа, а не какое-либо ограничение области значений, которое строка тоже не выполнила бы.

Ссылка, которая делит свой скаляр с другим текстом, является строкой независимо от способа записи, поскольку в документе после подстановки читается один скаляр: image: app:{{ .parameters.tag }} даёт app:1.4.0. Именно эту форму следует использовать, когда нестроковый параметр должен попасть в строковый лист.

Доступ к слотам объектного и массивного типа

Слоты параметров объектного типа предоставляют объявленные свойства как вложенные поля в отображении .parameters.<slot>. Слоты массивного типа поддерживают семантику срезов Go-шаблонов (range, index, len).

# Aggregate fragment — object-typed parameter
spec:
parameters:
database_config:
type: object
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full] }
components:
api:
type: core/compute/api:1.0.0
values:
db_host: "{{ .parameters.database_config.host }}"
db_port: {{ .parameters.database_config.port }}
db_ssl: "{{ .parameters.database_config.ssl_mode }}"

Слоты параметров массивного типа поддерживают перебор с помощью range:

# Aggregate fragment — array-typed parameter
spec:
parameters:
allowed_hosts:
type: array
items: { type: string, format: hostname }
min: 1
components:
ingress:
type: core/ingress:1.0.0
values:
# Compose a comma-separated list from the parameter array
hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"

Каждый элемент, который передаёт сущность Release, проверяется на соответствие контракту items до интерполяции, поэтому значение, не являющееся именем хоста, — например, * — останавливает сборку с указанием параметра, элемента и формата. Имена, которые принимает format, и то, что проверяет каждое из них, перечислены в vocabulary/compact-form-authoring.md.

Во время интерполяции доступна библиотека шаблонов Sprig, которая предоставляет вспомогательные функции, например join, для компактного преобразования массивов в строки:

hosts: "{{ join `,` .parameters.allowed_hosts }}"

Семантика заполнения значениями по умолчанию

Слот параметра с объявлением default: получает значение по умолчанию, если сущность Release не указывает этот слот. Значение по умолчанию применяется до прохода проверки контракта, поэтому проверка видит уже разрешённое значение (заданное в Release или значение по умолчанию):

# Aggregate
spec:
parameters:
timeout_seconds:
type: integer
min: 1
max: 300
default: 30
components:
api:
type: core/compute/api:1.0.0
values:
timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30
# Release supplies timeout_seconds: 60 — interpolation uses 60
# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)
# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)
# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)

Слот, помеченный required: true и не имеющий default:, вызывает ошибку во время сборки, если сущность Release его не указывает (E0165). В ошибке названы слот и его место в контракте, которое автору нужно исправить. Слот, у которого нет ни required: true, ни default:, необязателен: если он опущен, каждая ссылка на него интерполируется как пустая, а затем результат оценивает схема values: сущности Component.

Параметры с вложенными объектами

Если параметр объявляет type: object с properties:, дочерние свойства которого сами содержат значения default:, три варианта написания дают разные результаты. Понимать это различие важно, когда объявление параметра — структурированный объект (конфигурация базы данных, набор флагов функций, политика тайм-аутов и повторов), а не одно скалярное значение.

Случай 1 — Release не указывает родительский слот. Заполняются значения по умолчанию дочерних свойств из контракта. Автор Aggregate, объявивший вложенные значения по умолчанию, получает задуманное поведение: если эксплуатация не задаёт слот, конфигурация использует документированные значения по умолчанию.

# Aggregate
spec:
parameters:
database:
type: object
properties:
host: { type: string, default: "localhost" }
port: { type: integer, default: 5432 }
# Release (parent omitted)
spec:
parameters: {}
# Resolved at template-interpolation time
parameters:
database:
host: "localhost"
port: 5432

Случай 2 — Release задаёт родителя как явный пустой словарь. Явное пустое значение учитывается как намеренный отказ. Значения по умолчанию дочерних свойств НЕ заполняются; слот остаётся пустым. Используйте эту форму, когда эксплуатации нужно подавить вложенные значения по умолчанию из контракта, не задавая переопределений, — например, когда последующий потребитель ожидает, что слот присутствует, но пуст.

# Release (parent explicit empty)
spec:
parameters:
database: {}
# Resolved at template-interpolation time
parameters:
database: {}

Отличие от случая 1 намеренное: эксплуатация может выразить и «использовать значения по умолчанию» (не указывая слот), и «подавить значения по умолчанию» (задав слот как {}). Это повторяет то, как Aggrega обрабатывает явный null в аннотациях: аннотация, заданная как aggrega.ai/<key>: null, — это намеренный отказ, отличный от полного отсутствия аннотации.

Случай 3 — Release задаёт родителя частично. Дочерние свойства, заданные в Release, получают указанные значения; не заданные в Release заполняются значениями по умолчанию.

# Release (partial)
spec:
parameters:
database:
host: "db.prod.example.com"
# Resolved at template-interpolation time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

Это типичный случай для авторов Release, которые хотят переопределить отдельные поля, оставив остальные со значениями по умолчанию из контракта.

Когда использовать каждую форму

  • Не указывайте слот, если хотите, чтобы применились значения по умолчанию из контракта.
  • Задайте {}, если намеренно хотите, чтобы слот присутствовал, но был пуст, — когда значения по умолчанию из контракта не подходят для вашего окружения, а переопределений у вас нет.
  • Задайте частично, если хотите переопределить часть значений, а для остальных использовать значения по умолчанию из контракта.

Автор Release, который пишет database: {}, ожидая «дайте мне значения по умолчанию», будет удивлён: разрешённое значение пусто, а не заполнено значениями по умолчанию. Чтобы получить значения по умолчанию, не указывайте слот вовсе.

Выбор между тремя случаями выполняется для каждого соседнего элемента на любой глубине вложенности. Родитель, заданный как { connection: {}, other_field: "x" }, даёт разрешённое дерево, в котором connection пуст (случай 2 на глубине 1), а other_field содержит значение, заданное в Release (случай 3 на глубине 0): случаи выбираются независимо для каждого соседнего элемента, а не единым решением для всего поддерева.

Граница с последующими контекстами шаблонов

Асимметричное предоставление доступа — шаблоны путей читают .parameters напрямую, шаблоны значений нет — ключевое различие на этой границе. Семантика границы для каждой поверхности:

  • Шаблон component-values: сущности Aggregate, в котором написано {{ .parameters.X }}, корректно разрешается при интерполяции. Разрешённый литерал записывается в строку YAML на месте.
  • Шаблон valuesMapping: сущности Recipe, в котором написано {{ .parameters.X }}, относится к поверхности шаблонов значений; контекст шаблона не содержит .parameters. Авторы, которым нужны различия по окружениям в valuesMapping:, выражают их через путь потребления разрешённого .values.<key>: Aggregate объявляет параметр, ссылается на него из values: сущности Component, Release заполняет его, и значение после интерполяции передаётся в Recipe.
  • Шаблон injectMapping:, provides: или pipeline.with: сущности FeatureRecipe относится к поверхности шаблонов значений, так же как valuesMapping: сущности Recipe. .parameters отсутствует в контексте шаблона.
  • Шаблон тела Workload (содержимое workload: внутри Recipe) относится к поверхности шаблонов значений; то же самое.
  • Шаблон пути (directory: / subDirectory: на границе Release) — это исключение. Контекст шаблона пути включает .parameters.<slot> в соответствии с закрытым списком разрешённых значений; ссылки разрешаются, когда рендеринг размещает выходные данные каждой границы. Полную матрицу переменных шаблонов путей см. в path-template-variables.md.

Граница владения между четырьмя доменами сохраняется за счёт того, какая поверхность получает параметры, а не за счёт того, существует ли карта параметров в памяти на данном этапе конвейера. Шаблоны путей пишет и сопровождает оператор; прямой доступ к параметрам для них удерживает задачи оператора (раскладку артефактов по окружениям) внутри поверхности оператора. Шаблоны значений пишутся на стороне каталога; запрет прямого доступа к параметрам для них сохраняет слабую связанность авторской работы на стороне каталога с контрактом Aggregate как единого источника истины.

Объединённая карта параметров остаётся доступной для чтения, пока не завершатся все фазы рендеринга, и не дольше: она достижима только из той компиляции, для которой была разрешена, поэтому срок её жизни ограничен сроком сборки.

Связывание между столпами

Во время разрешения параметры интерполируются в окружающие строки значений. Интерполированные значения могут попасть в любой столп, который сущность Aggregate задаёт в своей области: строки values: компонентов, строки values: фич, сквозные объявления parameters: вложенных агрегатов (где значение параметра родительской сущности Aggregate разрешается, а затем передаётся в слот параметра дочерней сущности Aggregate), а также строки метаданных name: / labels:.

Связывание однонаправленное: значение параметра передаётся из предоставленного сущностью Release (или взятого по умолчанию) .parameters.<slot> в строку YAML в месте ссылки. В обратном направлении параметры не передаются — параметр не может прочитать поле values:, поле provides: или содержимое любого другого столпа. Эта направленность входит в гарантию контракта параметров, действующую только во время компиляции.

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

  • Форма объявления контракта типизированных параметров в сущности Aggregate: entities/aggregate.md, раздел «Typed parameter contracts».
  • Более широкий контекст шаблонов, который сущности Recipes используют при базовом рендеринге (.values, .infra, .uses, .context.* и т. д.): template-context-contract.md.
  • Доступность полей в каждом месте шаблона на протяжении конвейера компиляции (какие поля присутствуют в каком месте вычисления): expansion-matrix.md.
  • Контрольный список поднятия параметров (четыре последовательные точки авторской работы — объявление в Aggregate, ссылка в values, заполнение в Release, использование в Recipe): vocabulary/data-pillars.md, раздел «The parameter-hoisting checklist».
  • Полный набор опор данных (values:, infra:, provides:, uses:, features:, locals:, parameters:): vocabulary/data-pillars.md.