Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Функції та допоміжні функції 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.replicashasKey .values "replicas"optional .values "replicas" 1.values.replicas | default 1if .values.replicas
відсутнєfalse11false
0true01false
3true33true

Значення, яке може законно бути 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 (Recipe valuesMapping:, FeatureRecipe injectMapping:, 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; шаблонам, яким потрібно перейти до запасного значення без зупинки, слід покладатися на стандартні гілки Go if/else.

Перелік допоміжних функцій різних рушіїв (суттєвий для авторів MappingLibrary)

Фрагменти MappingLibrary можуть бути призначені для одного з двох місць використання:

  • Використання на боці Aggrega (Recipe valuesMapping:, FeatureRecipe injectMapping: тощо, обчислюються рендерером 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 — канонічний довідник за кожною функцією.