Sprig の関数とヘルパー
Aggrega のテンプレートエンジンは、レンダラーが評価するすべての Go テンプレートに Sprig v3 関数ライブラリと Aggrega 独自のヘルパー(optional と capitalizedWords)を組み込み、Go の index を、マップが保持していないマップキーで停止するものに置き換えます。Recipe の valuesMapping:、FeatureRecipe の injectMapping:、またはレンダラーが評価するその他のテンプレート記述箇所を書く作成者は、Go の text/template 組み込み関数と template-context-contract.md に記載されたランタイムコンテキストフィールドに加えて、Sprig ヘルパー一式を利用できます。
🔴 「the renderer evaluates」は文字どおりの範囲として読んでください。オーサリング面の一つがその範囲の外にあるためです。 構造化された source: 座標は、それが指すアーティファクトを固定できるように解決されますが、この解決はレンダリングパスではありません。この解決で登録されるのは Aggrega 独自のヘルパーのみ であり、source: フィールド内、またはそのフィールドが読み取る locals: エントリ内で Sprig を呼び出すと、プルが停止します。どの source: フィールドからも読み取られないエントリはレンダリングでのみ評価され、完全な関数セットを使用できます。座標の解決はアーティファクトを生成するのではなく、何を固定するかを決めるものであり、そのため関数セットは意図的に狭くなっています。停止の内容と代わりに使用できる移植可能な形式については、errors/fatal-halts.md の「Resolving a source: coordinate registers a narrower function set(source 座標の解決では、より狭い関数セットが登録されます)」を参照してください。
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、および先頭にmustが付く JSON 版(デコードエラーを暗黙にゼロ値にせず、エラーとして表面化させます)。 - 型チェック —
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(OS 依存)。 - 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 と出力されます。それ以外の数値は最短の正確な 10 進表記で出力され、指数表記にはなりません。記述された 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)は、それぞれをどの種類が保持しているかにかかわらず 2 つの数値を値で読みます。そのため、記述された整数はテンプレート内に書かれた小数と比較でき、3 は 3.0 と等しくなります:
{{ lt .values.replicas 1.5 }} # .values.replicas = 1 → true{{ eq .values.replicas 3.0 }} # .values.replicas = 3 → true数値がテキストと比較されることはありません。6 つの比較のいずれかに数値と引用符付きのテキストを渡すと、両方の種類を示してビルドが停止します。数値は引用符なしで書いた数値と比較するか、先にテキストに変換してください:
{{ 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(値テンプレートの実行中に失敗した) です。アサーションも記述された数値を同じように読みます。このサーフェスでの数値を参照してください。
存在と空であること — 2 つの異なる問い
テンプレートは値について 2 つの問いのいずれかを問い、それぞれの問いには専用のヘルパーがあります。
- 作成者はそれを書いたか?
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 は、空の形がそれ自体の意味を持たず、「空」と「書かれていない」を同じに扱ってよい値に適しています。1 つのテンプレートでは、あるキーを 1 つの方法で読んでください。テンプレートがドット区切りのパスとしても読むキーは存在するものとみなされます。これは optional の制限で説明しています。
Aggrega 固有のヘルパー
optional — 存在を考慮したフォールバック
optional <map> <key> <fallback> は、<map> にキーが存在する場合は <key> の値を返し、存在しない場合は <fallback> を返します。Sprig の default と異なり、optional は「キーが存在しない」ことと「キーが存在し、値がゼロ、空、または false である」ことを区別します。
シグネチャがマップとキーを別々の引数として受け取るのは、Go テンプレートの | 演算子でパイプされた値は親マップへのアクセスを失っているためです。親マップがスコープにない状態では、存在を確認できません。
存在チェックには制約が 1 つあり、それはヘルパーではなくテンプレートに由来します。値テンプレートは存在しないキーを「何もない」として読みます。これは、テンプレートがドット区切りのパスとして指定し値として読む、存在しない各キーに空の値を補うことで行われます。そのため、1 つのキーを optional 経由と、そのようなパスとしての両方で読むテンプレートは、そのキーが存在し空であると判断し、フォールバックではなく空の値を得ます。1 つのテンプレート内ではキーを 1 つの方法で読めば、2 つの答えは一致します。
# 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最後のケースが、Sprig の default では判別できないものです。{{ .infra.replicas | default 1 }} は、replicas が 0 と記述された場合も省略された場合も 1 を返します。この混同により、正当なゼロへのスケール、リトライなし、タイムアウトなし、false フラグといったパターンが妨げられます。
キーのクォートの慣例: バッククォートを推奨します。 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 のクォートの落とし穴を完全に回避できます。
default より optional を優先すべき場合。 フィールドが正当にゼロ、空、または false になり得て、カタログの作成者が「作成者がこれを設定していない」ことと「作成者がこれを偽となる値に設定した」ことを区別する必要がある場合は optional を使用します。混同が許容される場合(例: 空が無効な文字列フィールド、ゼロが無効な数値フィールド)は default を使用します。
サーフェスごとの利用可否。 optional は、レンダラーが評価するすべてのサーフェスに登録されています。値テンプレートのサーフェス(Recipe の valuesMapping、FeatureRecipe の injectMapping、provides、pipeline.with、Workload の本体)、アサーション評価器、およびパステンプレート(Release 境界の directory: / subDirectory:)です。パステンプレートのサーフェスで異なるのはヘルパーのセットではなく、欠落キーのポリシーです。パステンプレートは存在しないキーを空ではなくエラーとして扱います。黙って空になったパスセグメントは壊れたファイルシステムレイアウトを生み、それはビルド後にしか発見されないためです。optional はその厳格なポリシーが先に発動することなくキーを読むため、そこで使用できます。
capitalizedWords — 名前を英字と数字に畳み込む
capitalizedWords <string> は、引数を ASCII の英字と数字以外の文字の連続で区切られた単語として読み、各単語の最初の文字を大文字にして連結します。結果のすべての文字は英字または数字です。
このヘルパーが存在するのは、一部のターゲットはリソースを指定する名前に英字と数字しか受け付けない一方で、component の id にはドット、ハイフン、アンダースコアが正当に含まれ得るためです。必要な Recipe ごとにその変換を手作業で書くと、1 つの考えに複数の綴りが生まれます。単一のヘルパーにより、すべての作成者が同じ答えを得られます。
# 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🔴 結果は元の名前を識別しません。 すべての区切り文字が取り除かれるため、区切り文字の位置だけが異なる 2 つの id は同じ結果になります。payments-db と payments_db はどちらも PaymentsDb になります。ヘルパーは一度に 1 つの名前しか見ないため、これを検出できません。それを検出するのは、結果によってリソースを指定する側の役割です。そうしたターゲットは、2 つのうち一方が欠けたデプロイメントを出力するのではなく、衝突を拒否します。CloudFormation 向けのビルドでは、id が 1 つの名前に畳み込まれる 2 つの component はビルドを停止させ、メッセージにはその名前に至ったすべての id が示されます。句読点以外でも異なる id を選べば、この問題は生じません。
サーフェスごとの利用可否。 capitalizedWords は optional と同じ場所に登録されています。レンダラーが評価するすべてのサーフェスと、構造化された source: 座標の解決です。Sprig のセットのみを提供する Aggregate のパラメーター補間では利用できません。
index — マップが保持していなければならないキー
index <collection> <key>... は、Go 本来の index と同様に、位置またはキーでコレクションを読みます。ただし 1 つの違いがあります。コレクションがマップで、そのマップがキーを保持していない場合、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 }} はフォールバックを補い、Sprig の get は空文字列を返し、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 は Go の text/template をチャートテンプレート用のヘルパーで拡張しており、これらは一般的な Sprig ヘルパーとよく誤解されます。これらはいずれも Aggrega のレンダラーには登録されていません。 Aggrega のレンダラーが評価するテンプレート(Recipe の valuesMapping:、FeatureRecipe の injectMapping:、provides、Workload 本体、アサーション評価器)からは呼び出せません。
include— 定義済みのテンプレート断片を、パイプ可能な文字列出力として呼び出すための Helm で推奨される形式です。Aggrega のレンダラーはこれを登録していません。代わりに標準の Go テンプレートの{{ template "name" . }}(副作用のみの形式)を使用してください。パイプ可能な出力が必要な場合は、MappingLibrary の断片と$import:ディレクティブを使って組み立ててください。tpl— 文字列を現在のコンテキストに対してネストしたテンプレートとして再評価します。Aggrega はこれを登録していません。ネストした再評価はテンプレートの仕組みに含まれていません。計算した値が必要な場合は、Sprig の文字列ヘルパーで組み立て、最終的な値を直接出力してください。required— 指定した値が欠けている場合に、独自のメッセージでチャートのレンダリングを失敗させます。Aggrega はこれを登録していません。Aggrega における必須フィールドの強制は、型付きパラメーター契約の層で行われます(required: trueを持つ Aggregate のparameters:スロットを Release が埋めずに残すと、ビルドはE0165で停止し、そのスロットと Aggregate がそれを宣言している場所を示します)。テンプレート単位の必須チェックには、Sprig のfailを使用して、指定した文字列を含む致命的なテンプレートエラーを発生させます。warn— オペレーターの端末に致命的でない注記を出力します。Aggrega はこれを登録していません。説明メッセージ付きでレンダリングを停止する必要があるテンプレートは Sprig のfailを使用し、停止せずにフォールバックする必要があるテンプレートは標準の Go のif/else分岐を使用してください。
エンジン間のヘルパー一覧(MappingLibrary の作成者にとって重要)
MappingLibrary の断片は、次の 2 つの利用先のいずれかを対象にできます。
- 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 本来のもので、存在しないキーに対しては停止せず空の値を返します。
2 つのヘルパー群は Sprig の部分を共有していますが、エンジン固有の拡張では異なります。Helm チャート内部での利用を対象とする MappingLibrary のエントリーは Helm の慣例(大文字 V のルート .Values.<key>、| default、include ベースの組み立て)に従い、Aggrega 側での利用を対象とするエントリーは Aggrega の慣例(小文字の .values.<key>、存在を考慮したフォールバックには optional)に従います。ライブラリエンティティは断片をそのまま保存します。記述の形は、その断片がどこでレンダリングされるかに従います。
Sprig に加えて Aggrega が独自に提供するヘルパーは optional と capitalizedWords で、いずれも上で説明したとおりです。また、上で説明したとおり、Aggrega の index は Go のものを置き換えます。それ以外のヘルパーは、Sprig v3 のセットとまったく同じです。
相互参照
template-context-contract.md— テンプレートが Sprig ヘルパーと併せて読み取るランタイムフィールド。expansion-matrix.md— テンプレートサイトごとの評価順序。05-templates.md— テンプレートの概要とオーサリングの慣例。- Sprig v3 ドキュメント — 関数ごとの正規リファレンス。