콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

Sprig 함수와 헬퍼

Aggrega 템플릿 엔진은 렌더러가 평가하는 모든 Go 템플릿에 Sprig v3 함수 라이브러리와 Aggrega 자체 헬퍼(optional 및 capitalizedWords)를 연결하고, Go의 index를 맵에 없는 맵 키에서 중단하는 함수로 대체합니다. Recipe valuesMapping:, FeatureRecipe injectMapping: 또는 렌더러가 평가하는 그 밖의 템플릿 표면을 작성하는 작성자는 Go text/template 내장 함수 및 template-context-contract.md에 설명된 런타임 컨텍스트 필드와 함께 Sprig 헬퍼 전체를 사용할 수 있습니다.

🔴 “렌더러가 평가하는”이라는 표현은 말 그대로의 범위로 읽어야 합니다. 작성 영역 하나가 그 범위 밖에 있기 때문입니다. 구조화된 source: 좌표는 그것이 가리키는 아티팩트를 고정할 수 있도록 해석되며, 이 해석은 렌더링 패스가 아닙니다. 이 해석은 Aggrega 자체 헬퍼만 등록하고 그 밖의 것은 등록하지 않으므로, source: 필드나 그 필드가 읽는 locals: 항목에서 Sprig를 호출하면 pull이 중단됩니다. 어떤 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, 그리고 조용히 0 값으로 처리하는 대신 디코딩 오류를 드러내는 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으로 출력됩니다. 그 밖의 숫자는 가장 짧은 정확한 십진 형식으로 출력되며 지수 형식으로는 결코 출력되지 않습니다. 작성된 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일 수 있는 값 — 0개의 레플리카 수, 0의 타임아웃, 꺼진 플래그 — 은 hasKey 또는 optional로 검사하므로, 작성자의 0은 0으로 출력에 도달합니다. default, with, if는 빈 형태가 그 자체로 의미를 갖지 않아 “비어 있음”과 “작성되지 않음”을 같게 취급해도 되는 값에 적합합니다. 한 템플릿에서는 주어진 키를 한 가지 방식으로만 읽으십시오. 템플릿이 점으로 구분된 경로로도 읽는 키는 존재하는 것으로 간주되며, 이는 optional의 한계에서 설명합니다.

Aggrega 전용 헬퍼

optional — 존재 여부를 인식하는 대체값

optional <map> <key> <fallback>는 <map>에 <key>가 있으면 그 키의 값을 반환하고, 없으면 <fallback>을 반환합니다. Sprig의 default와 달리 optional은 “키가 없음”과 “키가 있지만 값이 0, 빈 값 또는 false임”을 구별합니다.

시그니처가 맵과 키를 별도의 인수로 받는 이유는 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

마지막 경우가 Sprig의 default가 구별하지 못하는 부분입니다. {{ .infra.replicas | default 1 }}는 replicas가 0으로 작성되었든 생략되었든 1을 반환합니다. 이러한 혼동 때문에 정당한 scale-to-zero, 재시도 없음, 타임아웃 없음, 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을 우선할 때. 필드가 정당하게 0, 빈 값 또는 false일 수 있고 카탈로그 작성자가 “작성자가 설정하지 않음”과 “작성자가 falsy 값으로 설정함”을 구별해야 할 때 optional을 사용합니다. 혼동이 허용되는 경우(예: 빈 값이 유효하지 않은 문자열 필드, 0이 유효하지 않은 숫자 필드)에는 default를 사용합니다.

표면별 사용 가능 여부. optional은 렌더러가 평가하는 모든 표면에 등록되어 있습니다. 값 템플릿 표면(Recipe valuesMapping, FeatureRecipe injectMapping, provides, pipeline.with, Workload 본문), 어서션 평가기, 경로 템플릿(Release 경계의 directory: / subDirectory:)이 이에 해당합니다. 경로 템플릿 표면에서 다른 점은 헬퍼 집합이 아니라 누락 키 정책입니다. 경로 템플릿은 없는 키를 빈 값이 아닌 오류로 취급합니다. 조용히 비어 버린 경로 세그먼트는 빌드 후에야 발견되는 깨진 파일 시스템 레이아웃을 만들기 때문입니다. optional은 이 엄격한 정책이 먼저 작동하지 않은 채 키를 읽으므로 그곳에서도 사용할 수 있습니다.

capitalizedWords — 이름을 문자와 숫자로 접기

capitalizedWords <string>는 인수를 ASCII 문자와 숫자 이외의 문자 연속으로 구분된 단어들로 읽고, 각 단어의 첫 글자를 대문자로 바꾼 뒤 이어 붙입니다. 결과의 모든 문자는 문자 또는 숫자입니다.

이 헬퍼가 존재하는 이유는 일부 대상이 리소스를 가리키는 이름에 문자와 숫자만 허용하는 반면, component id에는 점, 하이픈, 밑줄이 정당하게 포함될 수 있기 때문입니다. 필요한 각 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

🔴 결과는 원래 이름을 식별하지 않습니다. 모든 구분자가 제거되므로 구분자 위치만 다른 두 id는 같은 결과가 됩니다. payments-db와 payments_db는 모두 PaymentsDb가 됩니다. 헬퍼는 한 번에 하나의 이름만 보므로 이를 감지할 수 없으며, 이를 잡아내는 일은 결과로 리소스를 가리키는 쪽의 몫입니다. 그렇게 하는 대상은 둘 중 하나가 빠진 배포를 내보내는 대신 충돌을 거부합니다. CloudFormation용으로 빌드할 때 id가 하나의 이름으로 접히는 두 component는 빌드를 중단시키며, 메시지에는 그 이름에 이른 모든 id가 표시됩니다. 구두점 이상으로 다른 id를 선택하면 이 문제는 생기지 않습니다.

표면별 사용 가능 여부. capitalizedWords는 optional이 등록된 모든 곳, 즉 렌더러가 평가하는 모든 표면과 구조화된 source: 좌표의 해석에 등록되어 있습니다. Sprig 집합만 제공하는 Aggregate 매개변수 보간에서는 사용할 수 없습니다.

index — 맵에 반드시 있어야 하는 키

index <collection> <key>...는 Go 자체의 index처럼 컬렉션을 위치나 키로 읽지만, 한 가지 차이가 있습니다. 컬렉션이 맵이고 맵에 키가 없으면 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 조각은 두 가지 소비 위치 중 하나를 대상으로 할 수 있습니다.

  • 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 내용 또는 Helm 자체 템플릿 엔진이 다운스트림에서 렌더링하는 차트 templates/*.yaml). 사용 가능한 헬퍼는 전체 Sprig v3 및 Helm의 차트 템플릿 헬퍼(include, tpl, required, warn)입니다. Aggrega 자체 헬퍼는 사용할 수 없으며, 그곳의 index는 Go 자체의 것으로, 없는 키에 대해 중단하지 않고 빈 값으로 응답합니다.

두 헬퍼 집합은 Sprig 표면을 공유하지만 엔진별 확장에서는 서로 다릅니다. Helm 차트 내부 소비를 대상으로 하는 MappingLibrary 항목은 Helm 관례(.Values.<key> 대문자 V 루트, | default, include 기반 구성)를 사용하고, Aggrega 측 소비를 대상으로 하는 항목은 Aggrega 관례(소문자 .values.<key>, 존재를 인식하는 대체 값을 위한 optional)를 사용합니다. 라이브러리 엔터티는 조각을 그대로 저장하며, 작성 형태는 조각이 렌더링될 위치를 따릅니다.

Sprig 위에 추가된 Aggrega의 사용자 지정 헬퍼는 위에서 설명한 optional과 capitalizedWords이며, 위에서 설명한 대로 Aggrega의 index가 Go의 것을 대체합니다. 나머지 헬퍼 표면은 정확히 Sprig v3 집합입니다.

상호 참조