Функции и помощники Sprig
Шаблонизатор Aggrega подключает библиотеку функций Sprig v3, а также собственные помощники Aggrega (optional и capitalizedWords) к каждому шаблону Go, который вычисляет рендерер, и заменяет index из Go версией, которая останавливает работу на ключе, отсутствующем в карте. Авторам, которые пишут valuesMapping: для Recipe, injectMapping: для FeatureRecipe или любую другую шаблонную поверхность, вычисляемую рендерером, доступен полный набор помощников Sprig наряду со встроенными функциями Go text/template и полями контекста времени выполнения, описанными в template-context-contract.md.
🔴 Понимайте «вычисляемую рендерером» буквально, как границу области: одна поверхность для авторов лежит за её пределами. Структурированная координата source: разрешается, чтобы зафиксировать артефакт, на который она указывает, и это разрешение не является проходом рендеринга: оно регистрирует собственные помощники Aggrega и ничего больше, поэтому вызов Sprig в поле source: или в записи locals:, которую это поле читает, останавливает загрузку. Запись, которую не читает ни одно поле source:, вычисляется только при рендеринге, с полным набором. Разрешение координаты определяет, что будет зафиксировано, а не создаёт артефакт, поэтому набор функций для него намеренно уже — см. errors/fatal-halts.md, раздел «Resolving a source: coordinate registers a narrower function set (Разрешение координаты регистрирует более узкий набор функций)», где описаны остановка и переносимая форма, которую следует использовать вместо этого.
Набор Sprig регистрируется отдельно для интерполяции параметров, а на поверхностях шаблонов значений рендерера — вместе с собственными вспомогательными функциями Aggrega.
Что подключено
Sprig v3 открывает доступ ко всему своему набору вспомогательных функций — примерно 200 функций в перечисленных ниже категориях. На этой странице категории описаны кратко, с наиболее распространёнными функциями каждой; основной справочник по отдельным функциям — исходная документация Sprig.
- Строки —
upper,lower,title,trim,trimAll,trimPrefix,trimSuffix,replace,contains,hasPrefix,hasSuffix,substr,quote,squote,cat,indent,nindent,repeat, функции преобразования регистра (snakecase,camelcase,kebabcase), функции сокращения (abbrev,abbrevboth,trunc), функции контрольных сумм (sha1sum,sha256sum,sha512sum,adler32sum),toString. - Списки —
list,tuple,first,last,rest,initial,append/push,prepend,concat,reverse,uniq,without,has,slice,chunk,join,splitList,split,splitn,sortAlpha,compact. - Словари —
dict,get,set,unset,hasKey,keys,values,pick,omit,pluck,merge,mergeOverwrite,dig,deepCopy. - Математика —
add,sub,mul,div,mod,add1,min,max,ceil,floor,round, а также десятичные варианты с суффиксомf(addf,subf,mulf,divf,minf,maxf). - Преобразование —
int,int64,float64,atoi,toString,toDecimal,seq,until,untilStep. - Кодирование —
b64enc,b64dec,b32enc,b32dec,toJson,toPrettyJson,toRawJson,fromJson, а также JSON-варианты с префиксомmust, которые сообщают об ошибках декодирования, а не молча возвращают нулевое значение. - Проверки типов —
typeOf,typeIs,typeIsLike,kindOf,kindIs,deepEqual,empty. - Значения по умолчанию и управление потоком —
default,coalesce,all,any,ternary,fail(вызывает ошибку шаблона с произвольным сообщением — стандартный способ прервать рендеринг с защитным сообщением). - Регулярные выражения —
regexMatch,regexFind,regexFindAll,regexReplaceAll,regexReplaceAllLiteral,regexSplit,regexQuoteMeta, а также строгие варианты с префиксомmust. - Пути —
base,dir,clean,ext,isAbs(в стиле Unix);osBase,osClean,osDir,osExt,osIsAbs(с учётом ОС). - SemVer —
semver,semverCompare. - URL —
urlParse,urlJoin. - Даты —
ago,date,dateInZone,dateModify,duration,durationRound,htmlDate,htmlDateInZone,now,toDate,unixEpoch.
Оговорка о детерминированности
Aggrega гарантирует побайтно идентичный вывод для побайтно идентичного ввода. Часть функций Sprig читает внешнее состояние и нарушает эту гарантию при вызове из шаблона. Авторам следует избегать следующих функций в шаблонах, которые участвуют в формировании отрисовываемых артефактов:
- Чтение системных часов —
now,date,dateInZone,dateModify,htmlDate,htmlDateInZone,agoпри вызове без зафиксированного опорного времени. - Генераторы случайных значений —
randAlpha,randAlphaNum,randAscii,randNumeric,randBytes,randInt,uuidv4. - Чтение окружения —
env,expandenv(читают переменные окружения процесса, которые различаются на рабочих станциях операторов и в CI-раннерах). - Сетевое разрешение имён —
getHostByName.
Движок не блокирует эти функции: они входят в набор Sprig v3. Дисциплину отказа от них в шаблонах, участвующих в отрисовке, поддерживают рецензенты и гарантия детерминированного вывода, на которую опираются авторы и каталог стандартной библиотеки.
Числа в шаблоне значений
Число, записанное автором, доходит до шаблона значений как число. Целое число является integer и выводится целым: 1000000 выводится как 1000000. Любое другое число выводится в кратчайшей точной десятичной форме, никогда в экспоненциальной: записанное 0.0000001 выводится как 0.0000001, а записанное 1e21 — как 1000000000000000000000, независимо от того, пишет ли шаблон значение напрямую или превращает его в текст с помощью toString, quote, printf "%v" или toJson. Число, которое возвращает математическая функция, — mulf, float64, round и подобные им, — является собственным значением этой функции и выводится в её собственной форме, которая для очень малого или очень большого значения экспоненциальная: для записанного 0.0000001 выражение {{ mulf .values.ratio 1 }} выводит 1e-07.
Сравнения — eq, ne, lt, le, gt и ge — читают два числа по значению, каким бы видом ни было представлено каждое, поэтому записанное автором целое сравнивается с десятичным числом, записанным в шаблоне, и 3 равно 3.0:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → trueЧисло никогда не сравнивается с текстом: любое из шести сравнений, получив число и текст в кавычках, останавливает сборку и называет оба вида. Сравнивайте число с числом, записанным без кавычек, или сначала превратите его в текст:
{{ eq .values.port "8080" }} # halts: cannot compare a number with text{{ eq .values.port 8080 }} # .values.port = 8080 → true{{ eq (toString .values.port) "8080" }} # .values.port = 8080 → trueЭта остановка — A value template failed while it ran (Шаблон значений завершился сбоем во время выполнения). Утверждение читает записанное автором число так же; см. Числа на этой поверхности.
Наличие и пустота — два разных вопроса
Шаблон задаёт о значении один из двух вопросов, и у каждого вопроса свои вспомогательные функции.
- Записал ли это автор?
hasKeyиoptionalотвечают по наличию. Ключ, записанный автором, присутствует, что бы он ни содержал, — включая0,""иfalse, — и отсутствует только ключ, который автор опустил. - Пусто ли это?
default,with,ifиemptyотвечают по пустоте.0,"",false, пустой список, пустая карта и отсутствующее значение там считаются пустыми, как и в Helm.
.values.replicas | hasKey .values "replicas" | optional .values "replicas" 1 | .values.replicas | default 1 | if .values.replicas |
|---|---|---|---|---|
| отсутствует | false | 1 | 1 | false |
0 | true | 0 | 1 | false |
3 | true | 3 | 3 | true |
Значение, которое может законно быть 0, "" или false, — нулевое число реплик, нулевой тайм-аут, выключенный флаг, — проверяется через hasKey или optional, чтобы 0 автора дошёл до вывода как 0. default, with и if подходят для значения, пустая форма которого сама по себе ничего не означает и где «пусто» и «не записано» можно считать одним и тем же. Читайте каждый ключ в шаблоне одним способом: ключ, который шаблон также читает как путь через точку, считается присутствующим, как описано в разделе об ограничении optional.
Вспомогательные функции Aggrega
optional — значение по умолчанию с учётом наличия ключа
optional <map> <key> <fallback> возвращает значение по ключу <key> в <map>, если ключ присутствует, иначе возвращает <fallback>. В отличие от default из Sprig, optional различает «ключ отсутствует» и «ключ присутствует с нулевым, пустым или ложным значением».
Сигнатура принимает карту и ключ отдельными аргументами, потому что значение, переданное через оператор | шаблонов Go, теряет доступ к родительской карте. Без родительской карты в области видимости проверить наличие ключа невозможно.
У проверки наличия есть одно ограничение, и исходит оно от шаблона, а не от вспомогательной функции: шаблон значений читает отсутствующий ключ как пустоту, подставляя пустое значение для каждого отсутствующего ключа, который шаблон называет точечным путём и читает как значение. Поэтому шаблон, который читает один ключ и через optional, и как такой путь, находит этот ключ присутствующим и пустым и получает пустое значение, а не значение по умолчанию. Читайте ключ в шаблоне одним способом — и оба ответа совпадут.
# Present and non-zero: returns 3{{ optional .infra `replicas` 1 }} # .infra.replicas = 3 → 3
# Absent: returns the fallback{{ optional .infra `replicas` 1 }} # .infra.replicas unset → 1
# Present but authored zero: returns 0 (the discriminator){{ optional .infra `replicas` 1 }} # .infra.replicas = 0 → 0Последний случай — это различие, которое default из Sprig провести не может. {{ .infra.replicas | default 1 }} возвращает 1 независимо от того, задан ли replicas как 0 или опущен, — смешение, которое мешает законным сценариям масштабирования до нуля, отказа от повторов, отсутствия тайм-аута и ложных флагов.
Соглашение о кавычках для ключа: предпочитайте обратные кавычки. Шаблоны Go принимают для аргумента-ключа строковые литералы как в двойных кавычках ("replicas"), так и в обратных (`replicas`); при вычислении шаблона оба дают одну и ту же строку. В примерах каталога и документации единообразно используется форма с обратными кавычками, поскольку она безопасна для YAML в любом контексте кавычек. Ключ в двойных кавычках внутри YAML-скаляра в двойных кавычках обрывает строку YAML посреди шаблона:
# BROKEN — the inner " closes the outer YAML string:service_port: "{{ optional .infra "port" 8080 }}"
# WORKS — backticks are not a YAML escape character:service_port: "{{ optional .infra `port` 8080 }}"Когда шаблон находится внутри блочного скаляра YAML (форма |) или является скаляром без кавычек, обе формы отображаются правильно. Когда шаблон встроен в YAML-скаляр в двойных кавычках (шаблон field: "{{ ... }}", где значение поля является шаблоном), обратные кавычки обязательны. Единое соглашение (всегда обратные кавычки) полностью исключает ловушку с кавычками YAML.
Когда предпочесть optional, а не default. Используйте optional, когда поле может законно быть нулевым, пустым или ложным и автору каталога нужно отличать «автор это не задал» от «автор задал ложное значение». Используйте default, когда смешение допустимо (например, строковые поля, где пустое значение недопустимо; числовые поля, где ноль недопустим).
Доступность по поверхностям. optional зарегистрирована на каждой поверхности, которую вычисляет рендерер: поверхностях шаблонов значений (valuesMapping в Recipe, injectMapping в FeatureRecipe, provides, pipeline.with, тело Workload), в вычислителе утверждений и в шаблонах путей (directory: / subDirectory: на границах Release). На поверхности шаблонов путей отличается не набор функций, а политика отсутствующих ключей: шаблон пути считает отсутствующий ключ ошибкой, а не пустым значением, потому что незаметно пустой сегмент пути даёт сломанную структуру файловой системы, которая обнаруживается только после сборки. optional читает ключ до срабатывания этой строгой политики, что и делает её пригодной там.
capitalizedWords — свёртка имени в буквы и цифры
capitalizedWords <string> читает аргумент как слова, разделённые последовательностями любых символов, кроме букв и цифр ASCII, делает первую букву каждого слова заглавной и соединяет их. Каждый символ результата — буква или цифра.
Функция существует потому, что некоторые целевые платформы допускают только буквы и цифры в именах, по которым они обращаются к ресурсам, тогда как идентификатор компонента может законно содержать точку, дефис или подчёркивание. Ручная запись такого преобразования в каждом Recipe, где оно нужно, порождает несколько написаний одной идеи; единая функция даёт всем авторам один ответ.
# separators become word boundaries{{ capitalizedWords `payments-db` }} # → PaymentsDb{{ capitalizedWords `payments_db` }} # → PaymentsDb{{ capitalizedWords `payments.db` }} # → PaymentsDb
# a run of separators is one boundary, and leading or trailing ones add nothing{{ capitalizedWords `-payments--db-` }} # → PaymentsDb
# characters already inside a word keep the case they were authored with{{ capitalizedWords `MY-app` }} # → MYApp
# a word beginning with a digit is carried as authored{{ capitalizedWords `1st-app` }} # → 1stApp
# anything outside the alphabet is a boundary, including a non-ASCII letter{{ capitalizedWords `café-app` }} # → CafApp🔴 Результат не идентифицирует имя, из которого он получен. Все разделители отбрасываются, поэтому два идентификатора, различающиеся только расположением разделителей, дают один результат: payments-db и payments_db оба дают PaymentsDb. Функция не может это обнаружить, потому что видит одно имя за раз; выявлять это — задача того, что обращается к ресурсам по результату. Целевая платформа, которая так делает, отвергает коллизию, а не выпускает развёртывание без одного из двух: при сборке для CloudFormation два компонента, идентификаторы которых сворачиваются в одно имя, останавливают сборку, и сообщение называет каждый такой идентификатор. Выбирайте идентификаторы, различающиеся не только пунктуацией, и вопрос не возникнет.
Доступность по поверхностям. capitalizedWords зарегистрирована везде, где и optional: на каждой поверхности, которую вычисляет рендерер, и при разрешении структурированной координаты source:. Она недоступна в интерполяции параметров Aggregate, где предоставляется только набор Sprig.
index — ключ, который карта обязана содержать
index <collection> <key>... читает коллекцию по позиции или по ключу, как собственная index в Go, — с одним отличием. Когда коллекция — карта и карта не содержит ключа, index останавливает сборку и называет ключ, тогда как функция Go отвечает пустым значением, которое выводится как буквальный текст <no value>.
# Present: returns the value{{ index .values `replicas` }} # .values.replicas = 3 → 3
# A position in a list, or in a string, reads as Go's does{{ index .values.zones 0 }} # .values.zones = [a, b] → a
# Absent: halts, naming the key{{ index .values `replicas` }} # .values.replicas unset → halts: (key "replicas")Это способ чтения для случаев, когда ключ обязан быть, — учётные данные, читаемые под именем переменной, вычисленным Recipe, ключ, публикуемый другим шаблоном, — чтобы отсутствующий ключ останавливал сборку, а не попадал в артефакт как <no value>. Если ключ может законно отсутствовать, сначала проверьте его: {{ optional .values `replicas` 1 }} подставляет значение по умолчанию, get из Sprig возвращает пустую строку, а hasKey проверяет без чтения. Чтение через index с последующим default не даёт значения по умолчанию, потому что остановка происходит до выполнения default. Ключ, который присутствует и содержит null, не отсутствует: index возвращает его, и он выводится как <no value>.
Остановка — свойство только index, и она одинакова на каждой поверхности: в шаблонах значений, вычислителе утверждений, шаблонах путей, структурированной координате source:, интерполяции параметров Aggregate, предикате validate: параметра и предикатах x-aggrega-when: / x-aggrega-validate: схемы. Чтение незаданного ключа через точку следует собственной политике отсутствующих ключей своей поверхности и не затрагивается. Остановка описана в errors/fatal-halts.md «A template indexes a map with a key the map does not hold (Шаблон индексирует карту ключом, которого карта не содержит)».
Распространённые хелперы, которые НЕ доступны
Helm расширяет text/template из Go хелперами шаблонов чартов, которые часто ошибочно принимают за общие хелперы Sprig. Ни один из них не зарегистрирован в рендерере Aggrega. Шаблоны, которые вычисляет рендерер Aggrega (valuesMapping: в Recipe, injectMapping: в FeatureRecipe, provides, тело Workload, вычислитель утверждений), не могут их вызывать:
include— предпочтительная в Helm форма вызова определённого фрагмента шаблона со строковым выводом, который можно передать по конвейеру. Рендерер Aggrega его не регистрирует. Вместо него используйте стандартный для шаблонов Go{{ template "name" . }}(форма только с побочным эффектом); для вывода, передаваемого по конвейеру, составляйте композицию из фрагментов MappingLibrary и директив$import:.tpl— повторно вычисляет строку как вложенный шаблон в текущем контексте. Aggrega его не регистрирует; вложенное повторное вычисление не входит в поверхность шаблонов. Авторам, которым нужны вычисляемые значения, следует составлять их с помощью строковых хелперов Sprig и выводить итоговое значение напрямую.required— прерывает рендеринг чарта с пользовательским сообщением, если указанное значение отсутствует. Aggrega его не регистрирует. Проверка обязательных полей в Aggrega выполняется на уровне типизированного контракта параметров (слотparameters:в Aggregate сrequired: true, который Release оставляет незаполненным, останавливает сборку сE0165, называя слот и место, где Aggregate его объявляет); проверки обязательных маркеров в отдельных шаблонах используютfailиз Sprig, чтобы вызвать фатальную ошибку шаблона с переданной строкой.warn— выводит нефатальное примечание в терминал оператора. Aggrega его не регистрирует. Шаблонам, которым нужно остановить рендеринг с поясняющим сообщением, следует использоватьfailиз Sprig; шаблонам, которым нужно перейти к запасному варианту без остановки, следует опираться на стандартные ветвиif/elseв Go.
Перечень хелперов в разных движках (важно для авторов MappingLibrary)
Фрагменты MappingLibrary могут быть предназначены для одного из двух мест потребления:
- Потребление на стороне Aggrega (
valuesMapping:в Recipe,injectMapping:в FeatureRecipe и т. д., вычисляемые рендерером Aggrega). Доступные хелперы: полный Sprig v3 (default,coalesce,quote,nindent,indent,b64encи т. д.) плюс собственные хелперы Aggrega (optional,capitalizedWords), аindexостанавливает сборку на ключе, которого нет в карте. Хелперы шаблонов чартов (include,tpl,required,warn) НЕ доступны. - Потребление внутри чарта Helm (содержимое
values.yamlчарта илиtemplates/*.yamlчарта, которые затем рендерит собственный движок шаблонов Helm). Доступные хелперы: полный Sprig v3 плюс хелперы шаблонов чартов Helm (include,tpl,required,warn). Собственные хелперы Aggrega НЕ доступны, аindexтам — собственный из Go, который на отсутствующий ключ отвечает пустым значением, а не остановкой.
Два набора хелперов разделяют поверхность Sprig, но расходятся в расширениях, специфичных для движка. Записи MappingLibrary, предназначенные для потребления внутри чарта Helm, следуют соглашениям Helm (корень .Values.<key> с заглавной V, | default, композиция на основе include); записи, предназначенные для потребления на стороне Aggrega, следуют соглашениям Aggrega (.values.<key> в нижнем регистре, optional для запасного значения с учётом наличия ключа). Сущность библиотеки хранит фрагменты дословно; форма при написании определяется тем, где фрагмент должен рендериться.
Собственные вспомогательные функции Aggrega поверх Sprig — это optional и capitalizedWords, обе описаны выше, а её index заменяет одноимённую функцию Go, как описано выше. Остальная часть набора вспомогательных функций — это в точности набор Sprig v3.
Перекрёстные ссылки
template-context-contract.md— поля времени выполнения, которые шаблоны читают наряду с хелперами Sprig.expansion-matrix.md— порядок вычисления для каждого места шаблона.05-templates.md— обзор шаблонизации и соглашения о написании шаблонов.- Документация Sprig v3 — канонический справочник по каждой функции.